@linimin/pi-letscook 0.1.71 → 0.1.73

package/.agent/README.md

@@ -22,6 +22,8 @@ This repository uses the `completion` workflow for long-running coding tasks.
 - `.agent/*.log`
 - `.agent/tmp/`
 
+`.agent/profile.json` carries the stop-wave defaults for this repo, including `required_stop_judges` and `stop_aggregation_policy`. The packaged default is `required_stop_judges: 2` plus `stop_aggregation_policy: "unanimous-current-head-v1"`.
+
 `.agent/startup-brief.json` preserves the confirmed `/cook` startup intent as canonical intake for re-grounding. It does not replace `.agent/plan.json` or `.agent/active-slice.json`, which remain under regrounder authority.
 
 `.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.

package/.agent/mission.md

@@ -3,6 +3,6 @@
 Project: pi-letscook
 
 Mission anchor:
-Refactor the /cook startup boundary into the agreed mixed model: ordinary chat stays advisory-first by default with no default pre-/cook handoff capsule formation, while explicit /cook performs structured startup synthesis from recent discussion and preserves the approval-only Start/Cancel gate.
+Change pi-letscook stop-wave behavior from 3 generic stop judges to 2 stop judges plus an explicit current-HEAD aggregation policy (`unanimous-current-head-v1`), then update control-plane defaults, protocol docs, and regression tests so final stop requires two valid current-HEAD `can_stop=yes` judgments and a passing stop verifier before reconciliation to done.
 
 This file is a tracked human-readable statement of the repo's completion mission. Re-grounders may refine this file when repo truth becomes clearer, but it must stay truthful to shipped behavior and the active completion objective.

package/.agent/profile.json

@@ -2,7 +2,8 @@
   "schema_version": 1,
   "protocol_id": "completion",
   "project_name": "pi-letscook",
-  "required_stop_judges": 3,
+  "required_stop_judges": 2,
+  "stop_aggregation_policy": "unanimous-current-head-v1",
   "priority_policy_id": "completion-default",
   "task_type": "completion-workflow",
   "evaluation_profile": "completion-rubric-v1",

package/.agent/verify_completion_control_plane.sh

@@ -101,12 +101,23 @@ for (const [file, record] of [
 
 const taskType = asString(profile.task_type);
 const evaluationProfile = asString(profile.evaluation_profile);
+const requiredStopJudges = asNumber(profile.required_stop_judges);
+const stopAggregationPolicy = asString(profile.stop_aggregation_policy);
+if (!Number.isInteger(requiredStopJudges) || requiredStopJudges < 1) {
+  fail('.agent/profile.json required_stop_judges must be a positive integer');
+}
+if (stopAggregationPolicy !== 'unanimous-current-head-v1') {
+  fail('.agent/profile.json stop_aggregation_policy must be unanimous-current-head-v1');
+}
 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');
+const remainingStopJudges = asNumber(state.remaining_stop_judges);
+if (remainingStopJudges === undefined) fail('.agent/state.json remaining_stop_judges must be numeric');
+if (remainingStopJudges < 0) fail('.agent/state.json remaining_stop_judges must not be negative');
 
 if (asString(evidence.artifact_type) !== 'completion-verification-evidence') {
   fail('.agent/verification-evidence.json artifact_type must be completion-verification-evidence');

package/.agent/verify_completion_stop.sh

@@ -1,20 +1,108 @@
 #!/usr/bin/env bash
 set -euo pipefail
 
-ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
-cd "$ROOT"
-
-echo "[completion-stop] verifying control plane and .agent/verification-evidence.json parity"
+# .agent/verification-evidence.json parity is enforced by .agent/verify_completion_control_plane.sh before stop-wave policy checks.
 bash .agent/verify_completion_control_plane.sh
 
-if [[ "${PI_COMPLETION_RUNNING_RELEASE_CHECK:-0}" == "1" ]]; then
-  echo "[completion-stop] release-check is already in progress; skipping nested npm run release-check >/dev/null recursion"
-  npm run evaluator-calibration-test >/dev/null
-  echo "completion stop verification passed"
-  exit 0
-fi
+CURRENT_HEAD="$(git rev-parse HEAD 2>/dev/null || true)"
+export COMPLETION_STOP_HEAD="$CURRENT_HEAD"
+
+node <<'NODE'
+const fs = require('node:fs');
+const { spawnSync } = require('node:child_process');
+
+function fail(message) {
+  console.error(message);
+  process.exit(1);
+}
+
+function readJson(file) {
+  try {
+    return JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch (error) {
+    fail('Failed to read ' + file + ': ' + error.message);
+  }
+}
+
+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 gitHeadSha() {
+  const result = spawnSync('git', ['rev-parse', 'HEAD'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] });
+  if (result.status !== 0) {
+    fail('git rev-parse HEAD failed: ' + (asString(result.stderr) ?? 'unknown git error'));
+  }
+  return asString(result.stdout);
+}
+
+const profile = readJson('.agent/profile.json');
+const state = readJson('.agent/state.json');
+const requiredStopJudges = asNumber(profile.required_stop_judges);
+if (!Number.isInteger(requiredStopJudges) || requiredStopJudges < 1) {
+  fail('.agent/profile.json required_stop_judges must be a positive integer before stop verification can run.');
+}
+const stopAggregationPolicy = asString(profile.stop_aggregation_policy);
+if (stopAggregationPolicy !== 'unanimous-current-head-v1') {
+  fail('.agent/profile.json stop_aggregation_policy must be unanimous-current-head-v1 before stop verification can run.');
+}
+
+const currentPhase = asString(state.current_phase) ?? 'unknown';
+const stopWaveActive = currentPhase === 'stop_wave' || currentPhase === 'done';
+const rawHistory = fs.existsSync('.agent/stop-check-history.jsonl') ? fs.readFileSync('.agent/stop-check-history.jsonl', 'utf8') : '';
+const seededHeadSha = asString(process.env.COMPLETION_STOP_HEAD);
+if (!seededHeadSha && !stopWaveActive && rawHistory.trim().length === 0) {
+  console.log('[completion] current phase ' + currentPhase + ' is not stop_wave/done; current-HEAD stop judgments are not required yet');
+  process.exit(0);
+}
+const headSha = seededHeadSha ?? gitHeadSha();
+const currentHeadJudgments = [];
+for (const [index, rawLine] of rawHistory.split(/\r?\n/).entries()) {
+  const line = rawLine.trim();
+  if (!line) continue;
+  let parsed;
+  try {
+    parsed = JSON.parse(line);
+  } catch (error) {
+    fail('.agent/stop-check-history.jsonl contains invalid JSON at line ' + (index + 1) + ': ' + error.message);
+  }
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    fail('.agent/stop-check-history.jsonl line ' + (index + 1) + ' must be a JSON object judgment record.');
+  }
+  if (parsed.type !== 'judgment') continue;
+  if (asString(parsed.head_sha) !== headSha) continue;
+  if (typeof parsed.can_stop !== 'boolean') {
+    fail('Current-HEAD judgment at line ' + (index + 1) + ' must carry boolean can_stop.');
+  }
+  const blockerCount = asNumber(parsed.blocker_count);
+  const highValueGapCount = asNumber(parsed.high_value_gap_count);
+  if (blockerCount === undefined || highValueGapCount === undefined) {
+    fail('Current-HEAD judgment at line ' + (index + 1) + ' must carry numeric blocker_count and high_value_gap_count.');
+  }
+  if (parsed.can_stop === false) {
+    fail('Current HEAD has a can_stop=no judgment at line ' + (index + 1) + '.');
+  }
+  if (blockerCount > 0 || highValueGapCount > 0) {
+    fail('Current-HEAD judgment at line ' + (index + 1) + ' cannot pass stop verification while blocker_count or high_value_gap_count is non-zero.');
+  }
+  currentHeadJudgments.push(parsed);
+}
+
+if (!stopWaveActive && currentHeadJudgments.length === 0) {
+  console.log('[completion] current phase ' + currentPhase + ' is not stop_wave/done; current-HEAD stop judgments are not required yet');
+  process.exit(0);
+}
+
+if (currentHeadJudgments.length < requiredStopJudges) {
+  fail('Need ' + requiredStopJudges + ' valid current-HEAD judgments for HEAD ' + headSha + '; found ' + currentHeadJudgments.length + '.');
+}
 
-echo "[completion-stop] delegating to npm run release-check >/dev/null for broad packaged verification, evaluator calibration, and contract coverage"
-PI_COMPLETION_RUNNING_RELEASE_CHECK=1 npm run release-check >/dev/null
+console.log('[completion] stop-wave policy unanimous-current-head-v1 satisfied for HEAD ' + headSha + ' with ' + currentHeadJudgments.length + ' valid current-HEAD judgments');
+NODE
 
-echo "completion stop verification passed"
+echo "[completion] running repo-level verification: npm run release-check >/dev/null"
+npm run release-check >/dev/null

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## 0.1.73
+
+### Fixed
+
+- fixed `/cook` await-user-input resumptions so a user's exact reply in the active workflow can dispatch the mandatory follow-up completion role without forcing an extra `/cook` rerun
+- kept active-workflow completion-role gating strict for ordinary main-chat turns while adding regression coverage that fails if await-user-input replies lose their workflow dispatch rights
+
+## 0.1.72
+
+### Fixed
+
+- relaxed reviewer no-follow-up routing parsing so `Acceptable as-is: yes` now also accepts `none, proceed to completion-auditor` and `none - proceed to auditor` in addition to the original exact allowance, reducing avoidable completion transcription warnings without weakening the follow-up-slice guard
+- fixed completion-role continuation gating so an already-active `/cook` workflow with `continuation_policy: continue` can keep dispatching mandatory follow-up roles even when the harness no longer recognizes the current turn text as an explicit `/cook` or workflow-driver prompt, while still blocking ordinary main-chat turns from calling `completion_role`
+- fixed `/cook` await-user-input resumptions so a user's exact reply in the active workflow can dispatch the mandatory follow-up completion role without forcing an extra `/cook` rerun
+- added a dedicated `completion-role-gating-test` regression so release-check now fails if active-workflow continuation falls back to the old prompt-only dispatch gate, await-user-input replies lose workflow dispatch rights, or ordinary main-chat turns stop being rejected
+
 ## 0.1.71
 
 ### Changed

package/README.md

@@ -184,7 +184,7 @@ Deterministic verification now also persists a durable canonical artifact in `.a
 
 Canonical reviewer/auditor/stop-judge transcription now fails closed on malformed rubric-bearing reports: the shared rubric heading plus all four rubric dimensions must be present, required role fields must remain intact, and reviewer/stop-judge yes/no verdicts cannot contradict rubric `fail` lines.
 
-Evaluator calibration now also fails closed on semantically lenient but well-formed reports. `npm run evaluator-calibration-test` drives the packaged transcription path through reviewer yes-with-follow-up, auditor open-contracts-with-`Next mandatory slice: none`, and stop-judge yes-with-open-contracts fixtures while still accepting truthful passing reports. It also rejects the reproducible `none; ...` bypass family for reviewer follow-up, auditor worktree blockers, and stop-judge open-contract reporting, while still accepting only the exact reviewer routing text `Smallest follow-up slice: none; proceed to completion-auditor.` with terminal punctuation or whitespace only. Both `npm run release-check` and `bash .agent/verify_completion_stop.sh` include this calibration gate.
+Evaluator calibration now also fails closed on semantically lenient but well-formed reports. `npm run evaluator-calibration-test` drives the packaged transcription path through reviewer yes-with-follow-up, auditor open-contracts-with-`Next mandatory slice: none`, and stop-judge yes-with-open-contracts fixtures while still accepting truthful passing reports. It also rejects the reproducible `none; ...` bypass family for reviewer follow-up, auditor worktree blockers, and stop-judge open-contract reporting, while still accepting the reviewer routing forms `Smallest follow-up slice: none; proceed to completion-auditor.`, `Smallest follow-up slice: none, proceed to completion-auditor.`, and `Smallest follow-up slice: none - proceed to auditor.` with terminal punctuation or whitespace only. Both `npm run release-check` and `bash .agent/verify_completion_stop.sh` include this calibration gate.
 
 Deterministic active-slice contract regression now lives in `bash scripts/active-slice-contract-test.sh`, and `npm run release-check` pulls it into the packaged release gate before `npm pack --dry-run`.
 

package/extensions/completion/driver.ts

@@ -468,13 +468,15 @@ async function refocusCompletionMission(
 	deps: CompletionDriverDeps,
 	advisoryStartupBrief?: Record<string, unknown>,
 ): Promise<void> {
-	const requiredStopJudges = asNumber(snapshot.profile?.required_stop_judges) ?? 3;
+	const requiredStopJudges = asNumber(snapshot.profile?.required_stop_judges) ?? 2;
+	const stopAggregationPolicy = asString(snapshot.profile?.stop_aggregation_policy) ?? "unanimous-current-head-v1";
 	const root = snapshot.files.root;
 	const routing = deps.finalizeContextProposalAnalysis(analysis, [rawGoal, missionAnchor]);
 	const docsSurfaces = asStringArray(snapshot.profile?.docs_surfaces);
 	const nextProfile = buildProfileRecord({
 		projectName: asString(snapshot.profile?.project_name) ?? path.basename(root),
 		requiredStopJudges,
+		stopAggregationPolicy,
 		priorityPolicyId: asString(snapshot.profile?.priority_policy_id) ?? "completion-default",
 		docsSurfaces: docsSurfaces.length > 0 ? docsSurfaces : await detectDocsSurfaces(root),
 		taskType: routing.taskType,
@@ -485,7 +487,7 @@ async function refocusCompletionMission(
 			taskType: routing.taskType,
 			evaluationProfile: routing.evaluationProfile,
 			continuationReason: deps.buildContextProposalContinuationReason("User refocused workflow via /cook:", rawGoal, routing),
-		}, advisoryStartupBrief),
+		}, advisoryStartupBrief, { requiredStopJudges }),
 		remaining_stop_judges: requiredStopJudges,
 		next_mandatory_action: "Reconcile canonical state from current repo truth for the refocused mission",
 	};

package/extensions/completion/index.ts

@@ -262,6 +262,39 @@ function isCompletionWorkflowSessionTurn(snapshot: CompletionStateSnapshot | und
 	return isCompletionDriverPromptTurn(snapshot, ctx) || isCookCommandTurn(ctx);
 }
 
+function isOrdinaryMainChatTurnDuringActiveWorkflow(
+	snapshot: CompletionStateSnapshot | undefined,
+	ctx: { sessionManager?: any },
+): boolean {
+	if (!hasActiveWorkflowEntry(snapshot)) return false;
+	const latest = latestUserOrCustomTurnText(ctx);
+	if (!latest) return false;
+	if (isCookCommandTurn(ctx)) return false;
+	if (isCompletionDriverPromptTurn(snapshot, ctx)) return false;
+	return true;
+}
+
+function isAwaitingUserInputWorkflowReplyTurn(
+	snapshot: CompletionStateSnapshot | undefined,
+	ctx: { sessionManager?: any },
+): boolean {
+	if (!hasActiveWorkflowEntry(snapshot)) return false;
+	if (!isOrdinaryMainChatTurnDuringActiveWorkflow(snapshot, ctx)) return false;
+	return asString(snapshot?.state?.continuation_policy) === "await_user_input";
+}
+
+function isCompletionRoleDispatchAllowedTurn(
+	snapshot: CompletionStateSnapshot | undefined,
+	ctx: { sessionManager?: any },
+): boolean {
+	if (hasCompletionRoutingActivation(snapshot)) return true;
+	if (!hasActiveWorkflowEntry(snapshot)) return false;
+	if (isCompletionWorkflowSessionTurn(snapshot, ctx)) return true;
+	if (isAwaitingUserInputWorkflowReplyTurn(snapshot, ctx)) return true;
+	if (isOrdinaryMainChatTurnDuringActiveWorkflow(snapshot, ctx)) return false;
+	return asString(snapshot?.state?.continuation_policy) === "continue";
+}
+
 function shouldInjectCompletionWorkflowContext(snapshot: CompletionStateSnapshot | undefined, ctx: { sessionManager?: any }): boolean {
 	return isCompletionWorkflowSessionTurn(snapshot, ctx);
 }
@@ -1081,7 +1114,7 @@ export default function completionExtension(pi: ExtensionAPI) {
 		const snapshot = await loadCompletionSnapshot(cwd);
 		const completionActive = Boolean(snapshot) && asString(snapshot?.state?.continuation_policy) !== "done";
 		const root = snapshot?.files.root ?? findRepoRoot(cwd) ?? cwd;
-		const completionRoleDispatchAllowed = Boolean(role) || isCompletionWorkflowSessionTurn(snapshot, ctx);
+		const completionRoleDispatchAllowed = Boolean(role) || isCompletionRoleDispatchAllowedTurn(snapshot, ctx);
 		const reason = toolCallBlockReason({
 			toolName: event.toolName,
 			input: isRecord(event.input) ? event.input : undefined,

package/extensions/completion/prompt-surfaces.ts

@@ -402,6 +402,8 @@ export function buildEvaluationRoleContextLines(
 		`Canonical evaluation handoff for ${role}:`,
 		`- task_type: ${deps.currentTaskType(snapshot) ?? "(missing)"}`,
 		`- evaluation_profile: ${deps.currentEvaluationProfile(snapshot) ?? "(missing)"}`,
+		`- required_stop_judges: ${snapshot.profile?.required_stop_judges ?? "(missing)"}`,
+		`- stop_aggregation_policy: ${deps.asString(snapshot.profile?.stop_aggregation_policy) ?? "(missing)"}`,
 		`- latest_completed_slice: ${deps.asString(snapshot.state?.latest_completed_slice) ?? "(none)"}`,
 		`- active_slice_id: ${context.sliceId ?? "(none)"}`,
 		`- active_slice_status: ${context.status ?? "(unknown)"}`,

package/extensions/completion/role-reporting.js

@@ -115,7 +115,7 @@ function isPureNoneLike(value) {
 function isReviewerProceedToAuditorRoutingValue(value) {
   const raw = asString(value);
   if (!raw) return false;
-  return /^none\s*;\s*proceed to completion-auditor(?:[\p{P}\s]*)$/iu.test(raw);
+  return /^none(?:\s*[,;:/-]\s*|\s+)proceed to (?:completion-)?auditor(?:[\p{P}\s]*)$/iu.test(raw);
 }
 
 function isReviewerNoFollowUpValue(value) {

package/extensions/completion/state-store.ts

@@ -8,6 +8,8 @@ import type { CompletionStateSnapshot, JsonRecord } from "./types";
 const PROTOCOL_ID = "completion";
 const DEFAULT_TASK_TYPE = "completion-workflow";
 const DEFAULT_EVALUATION_PROFILE = "completion-rubric-v1";
+const DEFAULT_REQUIRED_STOP_JUDGES = 2;
+const DEFAULT_STOP_AGGREGATION_POLICY = "unanimous-current-head-v1";
 const TRACKED_CONTRACT_FILES = [
 	".agent/README.md",
 	".agent/mission.md",
@@ -197,6 +199,7 @@ async function detectVerifierCommand(root: string): Promise<string | undefined>
 		const scripts = isRecord(packageJson.scripts) ? packageJson.scripts : undefined;
 		const packageManager = asString((packageJson as JsonRecord).packageManager) ?? "";
 		const runner = packageManager.startsWith("pnpm") ? "pnpm" : packageManager.startsWith("yarn") ? "yarn" : packageManager.startsWith("bun") ? "bun" : "npm";
+		if (scripts && asString(scripts["release-check"])) return runner === "npm" ? "npm run release-check >/dev/null" : `${runner} run release-check >/dev/null`;
 		if (scripts && asString(scripts.test)) return runner === "npm" ? "npm test" : `${runner} test`;
 		if (scripts && asString(scripts.check)) return runner === "npm" ? "npm run check" : `${runner} check`;
 		if (scripts && asString(scripts.lint)) return runner === "npm" ? "npm run lint" : `${runner} lint`;
@@ -214,6 +217,7 @@ async function detectVerifierCommand(root: string): Promise<string | undefined>
 export function buildProfileRecord(args: {
 	projectName: string;
 	requiredStopJudges: number;
+	stopAggregationPolicy?: string;
 	priorityPolicyId?: string;
 	docsSurfaces: string[];
 	taskType?: string;
@@ -224,6 +228,7 @@ export function buildProfileRecord(args: {
 		protocol_id: PROTOCOL_ID,
 		project_name: args.projectName,
 		required_stop_judges: args.requiredStopJudges,
+		stop_aggregation_policy: args.stopAggregationPolicy ?? DEFAULT_STOP_AGGREGATION_POLICY,
 		priority_policy_id: args.priorityPolicyId ?? "completion-default",
 		task_type: args.taskType ?? DEFAULT_TASK_TYPE,
 		evaluation_profile: args.evaluationProfile ?? DEFAULT_EVALUATION_PROFILE,
@@ -239,8 +244,10 @@ export function defaultState(
 	missionAnchor: string,
 	routing?: { taskType?: string; evaluationProfile?: string; continuationReason?: string },
 	advisoryStartupBrief?: JsonRecord,
+	stopPolicy?: { requiredStopJudges?: number },
 ): JsonRecord {
 	const confirmedAt = asString(advisoryStartupBrief?.captured_at) ?? new Date().toISOString();
+	const requiredStopJudges = stopPolicy?.requiredStopJudges ?? DEFAULT_REQUIRED_STOP_JUDGES;
 	return {
 		schema_version: 1,
 		mission_anchor: missionAnchor,
@@ -264,7 +271,7 @@ export function defaultState(
 		release_blocker_ids: [],
 		next_mandatory_action: "Reconcile canonical state from current repo truth",
 		next_mandatory_role: "completion-regrounder",
-		remaining_stop_judges: 3,
+		remaining_stop_judges: requiredStopJudges,
 		last_reground_at: null,
 		last_auditor_verdict: null,
 		contract_status: "unknown",
@@ -360,7 +367,7 @@ export function defaultVerificationEvidence(): JsonRecord {
 }
 
 export function buildAgentReadme(projectName: string): string {
-	return `# Completion Control Plane\n\nThis repository uses the \`completion\` workflow for long-running coding tasks.\n\n## Canonical tracked contract files\n\n- \`.agent/README.md\`\n- \`.agent/mission.md\`\n- \`.agent/profile.json\`\n- \`.agent/verify_completion_stop.sh\`\n- \`.agent/verify_completion_control_plane.sh\`\n\n## Ignored canonical execution state\n\n- \`.agent/state.json\`\n- \`.agent/startup-brief.json\`\n- \`.agent/plan.json\`\n- \`.agent/active-slice.json\`\n- \`.agent/slice-history.jsonl\`\n- \`.agent/stop-check-history.jsonl\`\n- \`.agent/verification-evidence.json\`\n- \`.agent/*.log\`\n- \`.agent/tmp/\`\n\n\`.agent/startup-brief.json\` preserves the confirmed \`/cook\` startup intent as canonical intake for re-grounding. It does not replace \`.agent/plan.json\` or \`.agent/active-slice.json\`, which remain under regrounder authority.\n\n\`.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.\n\nThe source of truth for long-running completion work is canonical \`.agent/**\` state plus current repo truth.\n\nProject: ${projectName}\n`;
+	return `# Completion Control Plane\n\nThis repository uses the \`completion\` workflow for long-running coding tasks.\n\n## Canonical tracked contract files\n\n- \`.agent/README.md\`\n- \`.agent/mission.md\`\n- \`.agent/profile.json\`\n- \`.agent/verify_completion_stop.sh\`\n- \`.agent/verify_completion_control_plane.sh\`\n\n## Ignored canonical execution state\n\n- \`.agent/state.json\`\n- \`.agent/startup-brief.json\`\n- \`.agent/plan.json\`\n- \`.agent/active-slice.json\`\n- \`.agent/slice-history.jsonl\`\n- \`.agent/stop-check-history.jsonl\`\n- \`.agent/verification-evidence.json\`\n- \`.agent/*.log\`\n- \`.agent/tmp/\`\n\n\`.agent/profile.json\` carries the stop-wave defaults for this repo, including \`required_stop_judges\` and \`stop_aggregation_policy\`. The packaged default is \`required_stop_judges: 2\` plus \`stop_aggregation_policy: "${DEFAULT_STOP_AGGREGATION_POLICY}"\`.\n\n\`.agent/startup-brief.json\` preserves the confirmed \`/cook\` startup intent as canonical intake for re-grounding. It does not replace \`.agent/plan.json\` or \`.agent/active-slice.json\`, which remain under regrounder authority.\n\n\`.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.\n\nThe source of truth for long-running completion work is canonical \`.agent/**\` state plus current repo truth.\n\nProject: ${projectName}\n`;
 }
 
 export function buildMission(projectName: string, missionAnchor: string): string {
@@ -371,7 +378,114 @@ export function buildVerifyStopScript(verifierCommand?: string): string {
 	const repoCheck = verifierCommand
 		? `echo "[completion] running repo-level verification: ${verifierCommand}"\n${verifierCommand}`
 		: `echo "[completion] no repo-specific verifier auto-detected; control-plane verification only"`;
-	return `#!/usr/bin/env bash\nset -euo pipefail\n\nbash .agent/verify_completion_control_plane.sh\n${repoCheck}\n`;
+	return `#!/usr/bin/env bash
+set -euo pipefail
+
+# .agent/verification-evidence.json parity is enforced by .agent/verify_completion_control_plane.sh before stop-wave policy checks.
+bash .agent/verify_completion_control_plane.sh
+
+CURRENT_HEAD="$(git rev-parse HEAD 2>/dev/null || true)"
+export COMPLETION_STOP_HEAD="$CURRENT_HEAD"
+
+node <<'NODE'
+const fs = require('node:fs');
+const { spawnSync } = require('node:child_process');
+
+function fail(message) {
+  console.error(message);
+  process.exit(1);
+}
+
+function readJson(file) {
+  try {
+    return JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch (error) {
+    fail('Failed to read ' + file + ': ' + error.message);
+  }
+}
+
+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 gitHeadSha() {
+  const result = spawnSync('git', ['rev-parse', 'HEAD'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] });
+  if (result.status !== 0) {
+    fail('git rev-parse HEAD failed: ' + (asString(result.stderr) ?? 'unknown git error'));
+  }
+  return asString(result.stdout);
+}
+
+const profile = readJson('.agent/profile.json');
+const state = readJson('.agent/state.json');
+const requiredStopJudges = asNumber(profile.required_stop_judges);
+if (!Number.isInteger(requiredStopJudges) || requiredStopJudges < 1) {
+  fail('.agent/profile.json required_stop_judges must be a positive integer before stop verification can run.');
+}
+const stopAggregationPolicy = asString(profile.stop_aggregation_policy);
+if (stopAggregationPolicy !== '${DEFAULT_STOP_AGGREGATION_POLICY}') {
+  fail('.agent/profile.json stop_aggregation_policy must be ${DEFAULT_STOP_AGGREGATION_POLICY} before stop verification can run.');
+}
+
+const currentPhase = asString(state.current_phase) ?? 'unknown';
+const stopWaveActive = currentPhase === 'stop_wave' || currentPhase === 'done';
+const rawHistory = fs.existsSync('.agent/stop-check-history.jsonl') ? fs.readFileSync('.agent/stop-check-history.jsonl', 'utf8') : '';
+const seededHeadSha = asString(process.env.COMPLETION_STOP_HEAD);
+if (!seededHeadSha && !stopWaveActive && rawHistory.trim().length === 0) {
+  console.log('[completion] current phase ' + currentPhase + ' is not stop_wave/done; current-HEAD stop judgments are not required yet');
+  process.exit(0);
+}
+const headSha = seededHeadSha ?? gitHeadSha();
+const currentHeadJudgments = [];
+for (const [index, rawLine] of rawHistory.split(/\\r?\\n/).entries()) {
+  const line = rawLine.trim();
+  if (!line) continue;
+  let parsed;
+  try {
+    parsed = JSON.parse(line);
+  } catch (error) {
+    fail('.agent/stop-check-history.jsonl contains invalid JSON at line ' + (index + 1) + ': ' + error.message);
+  }
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    fail('.agent/stop-check-history.jsonl line ' + (index + 1) + ' must be a JSON object judgment record.');
+  }
+  if (parsed.type !== 'judgment') continue;
+  if (asString(parsed.head_sha) !== headSha) continue;
+  if (typeof parsed.can_stop !== 'boolean') {
+    fail('Current-HEAD judgment at line ' + (index + 1) + ' must carry boolean can_stop.');
+  }
+  const blockerCount = asNumber(parsed.blocker_count);
+  const highValueGapCount = asNumber(parsed.high_value_gap_count);
+  if (blockerCount === undefined || highValueGapCount === undefined) {
+    fail('Current-HEAD judgment at line ' + (index + 1) + ' must carry numeric blocker_count and high_value_gap_count.');
+  }
+  if (parsed.can_stop === false) {
+    fail('Current HEAD has a can_stop=no judgment at line ' + (index + 1) + '.');
+  }
+  if (blockerCount > 0 || highValueGapCount > 0) {
+    fail('Current-HEAD judgment at line ' + (index + 1) + ' cannot pass stop verification while blocker_count or high_value_gap_count is non-zero.');
+  }
+  currentHeadJudgments.push(parsed);
+}
+
+if (!stopWaveActive && currentHeadJudgments.length === 0) {
+  console.log('[completion] current phase ' + currentPhase + ' is not stop_wave/done; current-HEAD stop judgments are not required yet');
+  process.exit(0);
+}
+
+if (currentHeadJudgments.length < requiredStopJudges) {
+  fail('Need ' + requiredStopJudges + ' valid current-HEAD judgments for HEAD ' + headSha + '; found ' + currentHeadJudgments.length + '.');
+}
+
+console.log('[completion] stop-wave policy ${DEFAULT_STOP_AGGREGATION_POLICY} satisfied for HEAD ' + headSha + ' with ' + currentHeadJudgments.length + ' valid current-HEAD judgments');
+NODE
+
+${repoCheck}
+`;
 }
 
 export function buildVerifyControlPlaneScript(): string {
@@ -644,18 +758,20 @@ export async function scaffoldCompletionFiles(
 	const projectName = path.basename(root);
 	const docsSurfaces = await detectDocsSurfaces(root);
 	const verifierCommand = await detectVerifierCommand(root);
+	const requiredStopJudges = DEFAULT_REQUIRED_STOP_JUDGES;
+	const stopAggregationPolicy = DEFAULT_STOP_AGGREGATION_POLICY;
 	const trackedFiles: Array<{ path: string; content: string; executable?: boolean }> = [
 		{ path: path.join(files.agentDir, "README.md"), content: buildAgentReadme(projectName) },
 		{ path: path.join(files.agentDir, "mission.md"), content: buildMission(projectName, missionAnchor) },
 		{
 			path: files.profilePath,
-			content: `${JSON.stringify(buildProfileRecord({ projectName, requiredStopJudges: 3, docsSurfaces, taskType: options?.analysis?.taskType, evaluationProfile: options?.analysis?.evaluationProfile }), null, 2)}\n`,
+			content: `${JSON.stringify(buildProfileRecord({ projectName, requiredStopJudges, stopAggregationPolicy, docsSurfaces, taskType: options?.analysis?.taskType, evaluationProfile: options?.analysis?.evaluationProfile }), null, 2)}\n`,
 		},
 		{ path: path.join(files.agentDir, "verify_completion_stop.sh"), content: buildVerifyStopScript(verifierCommand), executable: true },
 		{ 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 }, options?.advisoryStartupBrief), null, 2)}\n`,
+			content: `${JSON.stringify(defaultState(missionAnchor, { taskType: options?.analysis?.taskType, evaluationProfile: options?.analysis?.evaluationProfile, continuationReason: options?.continuationReason }, options?.advisoryStartupBrief, { requiredStopJudges }), null, 2)}\n`,
 		},
 		{
 			path: files.startupBriefPath,

package/extensions/completion/status-surface.ts

@@ -423,6 +423,8 @@ export function buildCompletionStatusSurface(
 	const releaseBlockerCount = asNumber(snapshot.state?.remaining_release_blockers) ?? 0;
 	const highValueGapCount = asNumber(snapshot.state?.remaining_high_value_gaps) ?? 0;
 	const remainingStopJudgeCount = asNumber(snapshot.state?.remaining_stop_judges) ?? 0;
+	const requiredStopJudges = asNumber(snapshot.profile?.required_stop_judges) ?? 0;
+	const stopAggregationPolicy = asString(snapshot.profile?.stop_aggregation_policy);
 	const activeRole = liveActivity?.status === "running" ? liveActivity.role : undefined;
 	const liveSignal = liveActivitySignal(liveActivity);
 	const livePreview = livePreviewForStatus(liveActivity);
@@ -469,6 +471,8 @@ export function buildCompletionStatusSurface(
 		releaseBlockerCount,
 		highValueGapCount,
 		remainingStopJudgeCount,
+		requiredStopJudges,
+		stopAggregationPolicy,
 		activeRole,
 		livePreview,
 		liveState: liveSignal?.state,

package/extensions/completion/types.ts

@@ -74,6 +74,8 @@ export type CompletionStatusSurface = {
 	releaseBlockerCount?: number;
 	highValueGapCount?: number;
 	remainingStopJudgeCount?: number;
+	requiredStopJudges?: number;
+	stopAggregationPolicy?: string;
 	activeRole?: string;
 	livePreview?: string;
 	liveState?: "active" | "waiting" | "stalled";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@linimin/pi-letscook",
-  "version": "0.1.71",
+  "version": "0.1.73",
   "description": "Pi package for long-running completion workflows with canonical .agent state, role-based subagents, continuity, and verification helpers.",
   "license": "MIT",
   "private": false,
@@ -41,6 +41,7 @@
     "refocus-test": "bash ./scripts/refocus-test.sh",
     "context-proposal-test": "bash ./scripts/context-proposal-test.sh",
     "observability-status-test": "bash ./scripts/observability-status-test.sh",
+    "completion-role-gating-test": "bash ./scripts/completion-role-gating-test.sh",
     "evaluator-calibration-test": "bash ./scripts/evaluator-calibration-test.sh",
     "rubric-contract-test": "bash ./scripts/rubric-contract-test.sh",
     "release-check": "bash ./scripts/release-check.sh"

package/scripts/active-slice-contract-test.sh

@@ -261,7 +261,7 @@ state = {
     'release_blocker_ids': [],
     'next_mandatory_action': 'Implement selected slice active-slice-fixture.',
     'next_mandatory_role': 'completion-implementer',
-    'remaining_stop_judges': 3,
+    'remaining_stop_judges': 2,
     'last_reground_at': '2026-05-03T00:00:00Z',
     'last_auditor_verdict': None,
     'contract_status': 'selected_slice_pending_implementation',

package/scripts/canonical-evidence-artifact-test.sh

@@ -319,7 +319,7 @@ state = {
     'release_blocker_ids': [],
     'next_mandatory_action': 'Implement selected slice evidence-fixture.',
     'next_mandatory_role': 'completion-implementer',
-    'remaining_stop_judges': 3,
+    'remaining_stop_judges': 2,
     'last_reground_at': '2026-05-03T00:00:00Z',
     'last_auditor_verdict': None,
     'contract_status': 'selected_slice_pending_implementation',

package/scripts/completion-role-gating-test.sh

@@ -0,0 +1,55 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+cd "$ROOT"
+
+node <<'NODE'
+const fs = require('node:fs');
+
+const read = (file) => fs.readFileSync(file, 'utf8');
+const assertIncludes = (file, snippet) => {
+  const text = read(file);
+  if (!text.includes(snippet)) {
+    throw new Error(`${file} is missing required completion-role gating text: ${snippet}`);
+  }
+};
+const assertNotIncludes = (file, snippet) => {
+  const text = read(file);
+  if (text.includes(snippet)) {
+    throw new Error(`${file} still contains stale completion-role gating text: ${snippet}`);
+  }
+};
+
+assertIncludes('extensions/completion/index.ts', 'function isOrdinaryMainChatTurnDuringActiveWorkflow(');
+assertIncludes('extensions/completion/index.ts', 'function isCompletionRoleDispatchAllowedTurn(');
+assertIncludes('extensions/completion/index.ts', 'function isAwaitingUserInputWorkflowReplyTurn(');
+assertIncludes('extensions/completion/index.ts', 'if (isAwaitingUserInputWorkflowReplyTurn(snapshot, ctx)) return true;');
+assertIncludes('extensions/completion/index.ts', 'if (isOrdinaryMainChatTurnDuringActiveWorkflow(snapshot, ctx)) return false;');
+assertIncludes('extensions/completion/index.ts', 'return asString(snapshot?.state?.continuation_policy) === "await_user_input";');
+assertIncludes('extensions/completion/index.ts', 'return asString(snapshot?.state?.continuation_policy) === "continue";');
+assertIncludes('extensions/completion/index.ts', 'const completionRoleDispatchAllowed = Boolean(role) || isCompletionRoleDispatchAllowedTurn(snapshot, ctx);');
+assertIncludes('extensions/completion/index.ts', 'if (isCookCommandTurn(ctx)) return false;');
+assertIncludes('extensions/completion/index.ts', 'if (isCompletionDriverPromptTurn(snapshot, ctx)) return false;');
+assertIncludes('extensions/completion/policy-guards.ts', 'return "completion_role may only be used from an active /cook workflow session.";');
+assertIncludes('CHANGELOG.md', 'fixed completion-role continuation gating so an already-active `/cook` workflow with `continuation_policy: continue` can keep dispatching mandatory follow-up roles');
+assertIncludes('CHANGELOG.md', 'fixed `/cook` await-user-input resumptions so a user\'s exact reply in the active workflow can dispatch the mandatory follow-up completion role without forcing an extra `/cook` rerun');
+
+assertNotIncludes(
+  'extensions/completion/index.ts',
+  'const completionRoleDispatchAllowed = Boolean(role) || isCompletionWorkflowSessionTurn(snapshot, ctx);',
+);
+
+const indexText = read('extensions/completion/index.ts');
+const ordinaryGuardIndex = indexText.indexOf('if (isOrdinaryMainChatTurnDuringActiveWorkflow(snapshot, ctx)) return false;');
+const awaitReplyAllowIndex = indexText.indexOf('if (isAwaitingUserInputWorkflowReplyTurn(snapshot, ctx)) return true;');
+const continueFallbackIndex = indexText.indexOf('return asString(snapshot?.state?.continuation_policy) === "continue";');
+if (awaitReplyAllowIndex === -1 || ordinaryGuardIndex === -1 || awaitReplyAllowIndex > ordinaryGuardIndex) {
+  throw new Error('extensions/completion/index.ts must allow active await_user_input reply turns before the ordinary main-chat rejection guard.');
+}
+if (ordinaryGuardIndex === -1 || continueFallbackIndex === -1 || ordinaryGuardIndex > continueFallbackIndex) {
+  throw new Error('extensions/completion/index.ts must reject ordinary main-chat turns before allowing the continuation_policy=continue fallback.');
+}
+NODE
+
+echo "completion-role gating test passed"

package/scripts/context-proposal-test.sh

@@ -360,6 +360,8 @@ proposal = json.loads(Path(sys.argv[1]).read_text())
 assert mission in mission_text, '.agent/mission.md did not record the explicit-handoff mission anchor'
 assert profile['task_type'] == expected_task_type, 'profile.json task_type mismatch after explicit-handoff bootstrap'
 assert profile['evaluation_profile'] == expected_eval_profile, 'profile.json evaluation_profile mismatch after explicit-handoff bootstrap'
+assert profile['required_stop_judges'] == 2, 'profile.json required_stop_judges mismatch after explicit-handoff bootstrap'
+assert profile['stop_aggregation_policy'] == 'unanimous-current-head-v1', 'profile.json stop_aggregation_policy mismatch after explicit-handoff bootstrap'
 assert state['mission_anchor'] == mission, 'state.json mission_anchor mismatch after explicit-handoff bootstrap'
 assert state['task_type'] == expected_task_type, 'state.json task_type mismatch after explicit-handoff bootstrap'
 assert state['evaluation_profile'] == expected_eval_profile, 'state.json evaluation_profile mismatch after explicit-handoff bootstrap'
@@ -386,6 +388,7 @@ assert proposal['source'] == 'handoff_capsule', 'explicit startup proposal snaps
 assert proposal['analysis']['taskType'] == expected_task_type, 'explicit startup proposal snapshot should expose task_type hints separately'
 assert proposal['analysis']['evaluationProfile'] == expected_eval_profile, 'explicit startup proposal snapshot should expose evaluation_profile hints separately'
 assert state['current_phase'] == 'reground', 'state.json current_phase should start at reground after explicit-handoff bootstrap'
+assert state['remaining_stop_judges'] == 2, 'state.json remaining_stop_judges should seed from the profile stop policy after explicit-handoff bootstrap'
 assert state['next_mandatory_role'] == 'completion-regrounder', 'next_mandatory_role should start at completion-regrounder after explicit-handoff bootstrap'
 assert state['continuation_reason'].startswith('User started workflow via /cook:'), 'initial startup should record the accepted startup routing in continuation_reason'
 assert 'task_type=completion-workflow' in state['continuation_reason'], 'initial startup should persist the selected task_type in continuation_reason'
@@ -888,6 +891,8 @@ proposal = json.loads(Path(sys.argv[1]).read_text())
 assert mission in mission_text, '.agent/mission.md did not update to the next-round explicit-handoff mission anchor'
 assert profile['task_type'] == expected_task_type, 'profile.json task_type mismatch after next-round explicit handoff startup'
 assert profile['evaluation_profile'] == expected_eval_profile, 'profile.json evaluation_profile mismatch after next-round explicit handoff startup'
+assert profile['required_stop_judges'] == 2, 'profile.json required_stop_judges mismatch after next-round explicit handoff startup'
+assert profile['stop_aggregation_policy'] == 'unanimous-current-head-v1', 'profile.json stop_aggregation_policy mismatch after next-round explicit handoff startup'
 assert state['mission_anchor'] == mission, 'state.json mission_anchor mismatch after starting the next workflow round from explicit handoff'
 assert state['task_type'] == expected_task_type, 'state.json task_type mismatch after starting the next workflow round from explicit handoff'
 assert state['evaluation_profile'] == expected_eval_profile, 'state.json evaluation_profile mismatch after starting the next workflow round from explicit handoff'
@@ -902,6 +907,7 @@ assert active['evaluation_profile'] == expected_eval_profile, 'active-slice.json
 assert proposal['mission'] == mission, 'next-round explicit handoff proposal snapshot should preserve the handoff mission anchor'
 assert proposal['source'] == 'handoff_capsule', 'next-round explicit handoff proposal snapshot should record the handoff capsule source'
 assert state['current_phase'] == 'reground', 'state.json current_phase should reset to reground for the next workflow round'
+assert state['remaining_stop_judges'] == 2, 'state.json remaining_stop_judges should reset from the profile stop policy for the next workflow round'
 assert state['continuation_policy'] == 'continue', 'continuation_policy should reset to continue for the next workflow round'
 assert state['requires_reground'] is True, 'requires_reground should reset to true for the next workflow round'
 assert state['project_done'] is False, 'project_done should reset to false for the next workflow round'

package/scripts/evaluator-calibration-test.sh

@@ -22,13 +22,16 @@ const assertIncludes = (file, snippet) => {
 
 assertIncludes('package.json', '"evaluator-calibration-test": "bash ./scripts/evaluator-calibration-test.sh"');
 assertIncludes('scripts/release-check.sh', 'npm run evaluator-calibration-test');
-assertIncludes('.agent/verify_completion_stop.sh', 'npm run evaluator-calibration-test >/dev/null');
+assertIncludes('.agent/verify_completion_stop.sh', 'stop_aggregation_policy must be unanimous-current-head-v1');
+assertIncludes('.agent/verify_completion_stop.sh', 'Current HEAD has a can_stop=no judgment');
+assertIncludes('.agent/verify_completion_stop.sh', 'valid current-HEAD judgments');
+assertIncludes('.agent/verify_completion_stop.sh', 'npm run release-check >/dev/null');
 assertIncludes('README.md', 'Evaluator calibration now also fails closed on semantically lenient but well-formed reports.');
 assertIncludes('README.md', '`npm run evaluator-calibration-test` drives the packaged transcription path through reviewer yes-with-follow-up, auditor open-contracts-with-`Next mandatory slice: none`, and stop-judge yes-with-open-contracts fixtures while still accepting truthful passing reports.');
-assertIncludes('README.md', 'It also rejects the reproducible `none; ...` bypass family for reviewer follow-up, auditor worktree blockers, and stop-judge open-contract reporting, while still accepting only the exact reviewer routing text `Smallest follow-up slice: none; proceed to completion-auditor.` with terminal punctuation or whitespace only.');
+assertIncludes('README.md', 'It also rejects the reproducible `none; ...` bypass family for reviewer follow-up, auditor worktree blockers, and stop-judge open-contract reporting, while still accepting the reviewer routing forms `Smallest follow-up slice: none; proceed to completion-auditor.`, `Smallest follow-up slice: none, proceed to completion-auditor.`, and `Smallest follow-up slice: none - proceed to auditor.` with terminal punctuation or whitespace only.');
 assertIncludes('README.md', 'includes deterministic active-slice contract coverage plus observability coverage, evaluator calibration, and the rubric-contract regression');
 assertIncludes('CHANGELOG.md', 'added evaluator calibration fixtures for semantically lenient but well-formed reviewer/auditor/stop-judge reports');
-assertIncludes('CHANGELOG.md', 'tightened the reproducible `none; ...` reviewer/auditor/stop-judge bypass checks while still accepting only the exact reviewer `none; proceed to completion-auditor` routing allowance with terminal punctuation or whitespace only');
+assertIncludes('CHANGELOG.md', 'relaxed reviewer no-follow-up routing parsing so `Acceptable as-is: yes` now also accepts `none, proceed to completion-auditor` and `none - proceed to auditor` in addition to the original exact allowance');
 assertIncludes('CHANGELOG.md', 'wired `npm run evaluator-calibration-test` into `npm run release-check` and `.agent/verify_completion_stop.sh`');
 assertIncludes('CHANGELOG.md', 'fixed the smoke auto-resume prompt regression');
 assertIncludes('extensions/completion/role-reporting.js', 'Reviewer output cannot mark \'Acceptable as-is: yes\' while naming a follow-up slice other than none.');
@@ -68,6 +71,28 @@ Findings: none.
 Acceptable as-is: yes
 Smallest follow-up slice: none; proceed to completion-auditor.`;
 
+const reviewerCommaRoutingPass = `MISSION ANCHOR: test mission
+Remaining contract IDs: TEST-CONTRACT
+Rubric:
+- Contract coverage: pass - Locked acceptance criteria match the committed slice.
+- Correctness risk: pass - No blocking regression is evident.
+- Verification evidence: pass - Deterministic proof was rerun successfully.
+- Docs/state parity: pass - Docs and canonical state are aligned.
+Findings: none.
+Acceptable as-is: yes
+Smallest follow-up slice: none, proceed to completion-auditor.`;
+
+const reviewerShortAuditorRoutingPass = `MISSION ANCHOR: test mission
+Remaining contract IDs: TEST-CONTRACT
+Rubric:
+- Contract coverage: pass - Locked acceptance criteria match the committed slice.
+- Correctness risk: pass - No blocking regression is evident.
+- Verification evidence: pass - Deterministic proof was rerun successfully.
+- Docs/state parity: pass - Docs and canonical state are aligned.
+Findings: none.
+Acceptable as-is: yes
+Smallest follow-up slice: none - proceed to auditor.`;
+
 const reviewerLenient = `MISSION ANCHOR: test mission
 Remaining contract IDs: TEST-CONTRACT
 Rubric:
@@ -214,6 +239,44 @@ Brief justification: This should be rejected because remaining contracts still e
   assert(reviewed.appended.includes('reviewed:slice-review'), 'reviewer passing fixture should append a reviewed record');
   assert(readJsonl(snapshotFiles.sliceHistoryPath).length === 1, 'reviewer passing fixture should create one slice-history record');
 
+  const reviewerCommaRoutingReviewed = await transcribeCanonicalRoleReport({
+    role: 'completion-reviewer',
+    output: reviewerCommaRoutingPass,
+    reportFields: parseReportFields(reviewerCommaRoutingPass),
+    snapshotFiles,
+    headSha: '1212121212121212121212121212121212121212',
+    sliceId: 'slice-review-comma',
+    recordedAt: 12,
+  });
+  assert(
+    reviewerCommaRoutingReviewed.errors.length === 0,
+    `reviewer comma-routing fixture should transcribe cleanly: ${reviewerCommaRoutingReviewed.errors.join(' | ')}`,
+  );
+  assert(
+    reviewerCommaRoutingReviewed.appended.includes('reviewed:slice-review-comma'),
+    'reviewer comma-routing fixture should append a reviewed record',
+  );
+  assert(readJsonl(snapshotFiles.sliceHistoryPath).length === 2, 'reviewer comma-routing fixture should append a second slice-history record');
+
+  const reviewerShortAuditorRoutingReviewed = await transcribeCanonicalRoleReport({
+    role: 'completion-reviewer',
+    output: reviewerShortAuditorRoutingPass,
+    reportFields: parseReportFields(reviewerShortAuditorRoutingPass),
+    snapshotFiles,
+    headSha: '1313131313131313131313131313131313131313',
+    sliceId: 'slice-review-short-auditor',
+    recordedAt: 13,
+  });
+  assert(
+    reviewerShortAuditorRoutingReviewed.errors.length === 0,
+    `reviewer short-auditor-routing fixture should transcribe cleanly: ${reviewerShortAuditorRoutingReviewed.errors.join(' | ')}`,
+  );
+  assert(
+    reviewerShortAuditorRoutingReviewed.appended.includes('reviewed:slice-review-short-auditor'),
+    'reviewer short-auditor-routing fixture should append a reviewed record',
+  );
+  assert(readJsonl(snapshotFiles.sliceHistoryPath).length === 3, 'reviewer short-auditor-routing fixture should append a third slice-history record');
+
   const reviewerRejected = await transcribeCanonicalRoleReport({
     role: 'completion-reviewer',
     output: reviewerLenient,
@@ -227,7 +290,7 @@ Brief justification: This should be rejected because remaining contracts still e
     reviewerRejected.errors.some((error) => error.includes('follow-up slice other than none')),
     `reviewer lenient fixture should be rejected for a yes verdict with a follow-up slice: ${reviewerRejected.errors.join(' | ')}`,
   );
-  assert(readJsonl(snapshotFiles.sliceHistoryPath).length === 1, 'rejected reviewer fixture must not append history');
+  assert(readJsonl(snapshotFiles.sliceHistoryPath).length === 3, 'rejected reviewer fixture must not append history');
 
   const reviewerNonePrefixedRejected = await transcribeCanonicalRoleReport({
     role: 'completion-reviewer',
@@ -242,7 +305,7 @@ Brief justification: This should be rejected because remaining contracts still e
     reviewerNonePrefixedRejected.errors.some((error) => error.includes('follow-up slice other than none')),
     `reviewer none-prefixed lenient fixture should be rejected for a yes verdict with contradictory routing text: ${reviewerNonePrefixedRejected.errors.join(' | ')}`,
   );
-  assert(readJsonl(snapshotFiles.sliceHistoryPath).length === 1, 'rejected none-prefixed reviewer fixture must not append history');
+  assert(readJsonl(snapshotFiles.sliceHistoryPath).length === 3, 'rejected none-prefixed reviewer fixture must not append history');
 
   const reviewerTrailingTextAfterRoutingRejected = await transcribeCanonicalRoleReport({
     role: 'completion-reviewer',
@@ -255,9 +318,9 @@ Brief justification: This should be rejected because remaining contracts still e
   });
   assert(
     reviewerTrailingTextAfterRoutingRejected.errors.some((error) => error.includes('follow-up slice other than none')),
-    `reviewer routing-trailing-text fixture should be rejected for extra text after the exact completion-auditor allowance: ${reviewerTrailingTextAfterRoutingRejected.errors.join(' | ')}`,
+    `reviewer routing-trailing-text fixture should be rejected for extra text after the allowed completion-auditor routing forms: ${reviewerTrailingTextAfterRoutingRejected.errors.join(' | ')}`,
   );
-  assert(readJsonl(snapshotFiles.sliceHistoryPath).length === 1, 'rejected reviewer routing-trailing-text fixture must not append history');
+  assert(readJsonl(snapshotFiles.sliceHistoryPath).length === 3, 'rejected reviewer routing-trailing-text fixture must not append history');
 
   const audited = await transcribeCanonicalRoleReport({
     role: 'completion-auditor',
@@ -270,7 +333,7 @@ Brief justification: This should be rejected because remaining contracts still e
   });
   assert(audited.errors.length === 0, `auditor passing fixture should transcribe cleanly: ${audited.errors.join(' | ')}`);
   assert(audited.appended.includes('audited:slice-audit'), 'auditor passing fixture should append an audited record');
-  assert(readJsonl(snapshotFiles.sliceHistoryPath).length === 2, 'auditor passing fixture should append a second slice-history record');
+  assert(readJsonl(snapshotFiles.sliceHistoryPath).length === 4, 'auditor passing fixture should append the next slice-history record');
 
   const auditorRejected = await transcribeCanonicalRoleReport({
     role: 'completion-auditor',
@@ -289,7 +352,7 @@ Brief justification: This should be rejected because remaining contracts still e
     auditorRejected.errors.some((error) => error.includes("Next mandatory slice") && error.includes('none')),
     `auditor lenient fixture should reject open-work reports with no next mandatory slice: ${auditorRejected.errors.join(' | ')}`,
   );
-  assert(readJsonl(snapshotFiles.sliceHistoryPath).length === 2, 'rejected auditor fixture must not append history');
+  assert(readJsonl(snapshotFiles.sliceHistoryPath).length === 4, 'rejected auditor fixture must not append history');
 
   const auditorNonePrefixedRejected = await transcribeCanonicalRoleReport({
     role: 'completion-auditor',
@@ -304,7 +367,7 @@ Brief justification: This should be rejected because remaining contracts still e
     auditorNonePrefixedRejected.errors.some((error) => error.includes('listing worktree blockers')),
     `auditor none-prefixed lenient fixture should reject clean-yes reports that smuggle blockers behind none: ${auditorNonePrefixedRejected.errors.join(' | ')}`,
   );
-  assert(readJsonl(snapshotFiles.sliceHistoryPath).length === 2, 'rejected none-prefixed auditor fixture must not append history');
+  assert(readJsonl(snapshotFiles.sliceHistoryPath).length === 4, 'rejected none-prefixed auditor fixture must not append history');
 
   const judged = await transcribeCanonicalRoleReport({
     role: 'completion-stop-judge',

package/scripts/observability-status-test.sh

@@ -34,6 +34,8 @@ elif mode == 'static':
     assert data['releaseBlockerCount'] == 1, data
     assert data['highValueGapCount'] == 4, data
     assert data['remainingStopJudgeCount'] == 2, data
+    assert data['requiredStopJudges'] == 2, data
+    assert data['stopAggregationPolicy'] == 'unanimous-current-head-v1', data
     assert not data.get('statusText'), data
     widget = data['widgetLines']
     assert 'phase: implement' in widget, widget
@@ -55,6 +57,8 @@ elif mode == 'live':
         'tool activity separated from role judgment',
         'waiting threshold uses updatedAt timestamps',
     ], data
+    assert data['requiredStopJudges'] == 2, data
+    assert data['stopAggregationPolicy'] == 'unanimous-current-head-v1', data
     assert not data.get('statusText'), data
     widget = data['widgetLines']
     assert widget == [], widget
@@ -98,7 +102,8 @@ cat > .agent/profile.json <<'JSON'
   "schema_version": 1,
   "protocol_id": "completion",
   "project_name": "status-surface-fixture",
-  "required_stop_judges": 3,
+  "required_stop_judges": 2,
+  "stop_aggregation_policy": "unanimous-current-head-v1",
   "priority_policy_id": "completion-default",
   "docs_surfaces": ["README.md"]
 }

package/scripts/release-check.sh

@@ -5,7 +5,7 @@ ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
 cd "$ROOT"
 export PI_COMPLETION_RUNNING_RELEASE_CHECK=1
 
-echo "[release-check] running control-plane validation, tracked .agent contract coverage, slice-surface parity, explicit-/cook parity, startup/refocus/context regressions, canonical evidence artifact, active-slice contract, observability, legacy cleanup, evaluator calibration, and rubric contract coverage"
+echo "[release-check] running control-plane validation, tracked .agent contract coverage, slice-surface parity, explicit-/cook parity, startup/refocus/context regressions, canonical evidence artifact, active-slice contract, observability, completion-role gating, legacy cleanup, evaluator calibration, and rubric contract coverage"
 bash .agent/verify_completion_control_plane.sh
 git ls-files --error-unmatch .agent/README.md .agent/mission.md .agent/profile.json .agent/verify_completion_stop.sh .agent/verify_completion_control_plane.sh >/dev/null
 
@@ -34,6 +34,8 @@ checks = {
         'description: "/cook workflow: start or replace workflow only from an explicit primary-agent handoff, or resume the current workflow from canonical state"',
         '"Do not call completion_role from ordinary chat; it is reserved for active /cook workflow sessions."',
         '`COMPLETION WORKFLOW DRIVER\\nStart or continue the completion workflow for this repo.',
+        'function isCompletionRoleDispatchAllowedTurn(',
+        'return asString(snapshot?.state?.continuation_policy) === "continue";',
     ],
     "extensions/completion/policy-guards.ts": [
         'return "completion_role may only be used from an active /cook workflow session.";',
@@ -81,6 +83,7 @@ bash ./scripts/role-runner-contract-test.sh
 bash ./scripts/canonical-evidence-artifact-test.sh
 bash ./scripts/active-slice-contract-test.sh
 npm run observability-status-test
+npm run completion-role-gating-test
 bash ./scripts/legacy-cleanup-test.sh
 npm run evaluator-calibration-test
 npm run rubric-contract-test

package/scripts/rubric-contract-test.sh

@@ -81,6 +81,8 @@ assertIncludes('extensions/completion/prompt-surfaces.ts', '`Task type: ${args.t
 assertIncludes('extensions/completion/prompt-surfaces.ts', '`Evaluation profile: ${args.evaluationProfile ?? "(missing)"}`');
 assertIncludes('extensions/completion/prompt-surfaces.ts', '`- task_type: ${deps.currentTaskType(snapshot) ?? "(missing)"}`');
 assertIncludes('extensions/completion/prompt-surfaces.ts', '`- evaluation_profile: ${deps.currentEvaluationProfile(snapshot) ?? "(missing)"}`');
+assertIncludes('extensions/completion/prompt-surfaces.ts', '`- required_stop_judges: ${snapshot.profile?.required_stop_judges ?? "(missing)"}`');
+assertIncludes('extensions/completion/prompt-surfaces.ts', '`- stop_aggregation_policy: ${deps.asString(snapshot.profile?.stop_aggregation_policy) ?? "(missing)"}`');
 assertIncludes('extensions/completion/prompt-surfaces.ts', 'Canonical evaluation handoff for ${role}:');
 assertIncludes('extensions/completion/index.ts', 'buildEvaluationRoleReminderText(snapshot, nextRole)');
 assertIncludes('extensions/completion/role-runner.ts', 'import { parseReportFields, transcribeRoleOutput, type TranscriptionResult } from "./transcription";');
@@ -97,6 +99,9 @@ assertIncludes('extensions/completion/role-reporting.js', 'Stop-judge output mus
 assertIncludes('extensions/completion/role-reporting.js', 'Stop-judge output must answer \'Tracked and unignored worktree is clean\' with yes or no.');
 assertIncludes('package.json', '"rubric-contract-test": "bash ./scripts/rubric-contract-test.sh"');
 assertIncludes('scripts/release-check.sh', 'npm run rubric-contract-test');
+assertIncludes('.agent/verify_completion_stop.sh', 'stop_aggregation_policy must be unanimous-current-head-v1');
+assertIncludes('.agent/verify_completion_stop.sh', 'Current HEAD has a can_stop=no judgment');
+assertIncludes('.agent/verify_completion_stop.sh', 'valid current-HEAD judgments');
 assertIncludes('.agent/verify_completion_stop.sh', 'npm run release-check >/dev/null');
 NODE
 

package/skills/completion-protocol/SKILL.md

@@ -34,6 +34,8 @@ This skill defines shared protocol facts only. Role-specific behavior belongs in
 - Before selecting or advancing to the next slice after a committed slice, the tracked and unignored worktree must be clean. If it is not clean, treat that dirty state as a blocker to next-slice progression and reopen or continue the latest slice for reconciliation.
 - Docs, config, and runbooks must stay truthful to shipped behavior.
 - `.agent/verify_completion_stop.sh` is a generated repo-level baseline verifier. Onboarding should create a working version from current repo truth rather than an unconditional failing placeholder.
+- The packaged default stop policy is `required_stop_judges: 2` plus `stop_aggregation_policy: "unanimous-current-head-v1"` in `.agent/profile.json`.
+- Under `unanimous-current-head-v1`, only current-HEAD `judgment` records count, any current-HEAD `can_stop = no` fails closed, and repo-level stop verification must wait until the required current-HEAD judgments are recorded.
 - Keep slice-specific proof in repo tests or deterministic checks. Refresh `.agent/verify_completion_stop.sh` only when the repo's top-level verification surfaces change or the verifier becomes stale.
 - The workflow topology is flat and primary-driven: the main pi session remains the workflow root and invokes at most one completion role at a time.
 - No completion role may invoke another completion role during the normal workflow.
@@ -83,7 +85,7 @@ If the workflow driver detects that the next mandatory action belongs to a compl
 6. If the latest committed slice lacks an audit result, invoke `completion-auditor`.
 7. If review or audit have returned and canonical reconciliation is needed, invoke `completion-regrounder`. `completion-regrounder` must not select or hand off a next slice while the latest committed slice leaves the tracked and unignored worktree dirty; instead it must reopen or continue that latest slice for reconciliation.
 8. If all planned slices are done and final closure is being evaluated, invoke the required `completion-stop-judge` sessions directly.
-9. After each required `completion-stop-judge` result is faithfully recorded, rerun `bash .agent/verify_completion_stop.sh` and invoke `completion-regrounder` for final stop reconciliation.
+9. After each required current-HEAD `completion-stop-judge` result is faithfully recorded, rerun `bash .agent/verify_completion_stop.sh` and invoke `completion-regrounder` for final stop reconciliation.
 
 The workflow driver must not substitute itself for any mandatory dispatch target above.
 

package/skills/completion-protocol/references/completion.md

@@ -55,7 +55,8 @@ Optional context only:
   "schema_version": 1,
   "protocol_id": "completion",
   "project_name": "<repo-name>",
-  "required_stop_judges": 3,
+  "required_stop_judges": 2,
+  "stop_aggregation_policy": "unanimous-current-head-v1",
   "priority_policy_id": "completion-default",
   "task_type": "completion-workflow",
   "evaluation_profile": "completion-rubric-v1",
@@ -254,6 +255,21 @@ Minimum record shape:
 
 Empty history files are legal.
 
+## Final Stop Aggregation Policy
+
+The packaged default stop policy is:
+
+- `required_stop_judges: 2`
+- `stop_aggregation_policy: "unanimous-current-head-v1"`
+
+Policy meaning:
+
+- count only `judgment` records whose `head_sha` matches the current `HEAD`
+- require at least two valid current-HEAD judgments before repo-level stop verification may run
+- fail closed if any current-HEAD judgment has `can_stop = false`
+- fail closed if a current-HEAD judgment is malformed or carries non-zero blocker/high-value-gap counts
+- rerun `bash .agent/verify_completion_stop.sh` only after the required current-HEAD judgments are faithfully recorded, then hand final reconciliation back to `completion-regrounder`
+
 ## Structured Evaluation Rubric Foundation
 
 `completion-reviewer`, `completion-auditor`, and `completion-stop-judge` must emit rubric-backed evaluations using the same shared dimension names and verdict semantics.
@@ -344,7 +360,7 @@ It must not, while a slice is selected or in progress:
 6. If the latest committed slice lacks audit, invoke `completion-auditor`.
 7. If canonical reconciliation is needed after review or audit, invoke `completion-regrounder`.
 8. If all slices are done and final closure is under evaluation, invoke the required `completion-stop-judge` sessions directly.
-9. After the required judgments are recorded, rerun `bash .agent/verify_completion_stop.sh` and invoke `completion-regrounder` for final stop reconciliation.
+9. After the required current-HEAD judgments are recorded, rerun `bash .agent/verify_completion_stop.sh` and invoke `completion-regrounder` for final stop reconciliation.
 
 ## Compaction And Recovery