@linimin/pi-letscook 0.1.76 → 0.1.77

package/.agent/README.md

@@ -22,7 +22,7 @@ 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/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"`. Canonical `.agent/state.json current_stop_wave_id` carries the current stop-wave epoch so the same HEAD may restart stop evaluation without requiring a synthetic tracked commit.
 
 `.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.
 

package/.agent/verify_completion_control_plane.sh

@@ -118,6 +118,12 @@ if (asString(active.evaluation_profile) !== evaluationProfile) fail('.agent/acti
 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');
+const currentStopWaveId = asNumber(state.current_stop_wave_id);
+if (currentStopWaveId !== undefined) {
+  if (!Number.isInteger(currentStopWaveId) || currentStopWaveId < 0) {
+    fail('.agent/state.json current_stop_wave_id must be a non-negative integer');
+  }
+}
 
 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

@@ -53,6 +53,11 @@ if (stopAggregationPolicy !== 'unanimous-current-head-v1') {
 
 const currentPhase = asString(state.current_phase) ?? 'unknown';
 const stopWaveActive = currentPhase === 'stop_wave' || currentPhase === 'done';
+const currentStopWaveId = asNumber(state.current_stop_wave_id) ?? 0;
+if (!Number.isInteger(currentStopWaveId) || currentStopWaveId < 0) {
+  fail('.agent/state.json current_stop_wave_id must be a non-negative integer before stop verification can run.');
+}
+const activeStopWaveId = stopWaveActive ? currentStopWaveId || 1 : currentStopWaveId;
 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) {
@@ -75,6 +80,11 @@ for (const [index, rawLine] of rawHistory.split(/\r?\n/).entries()) {
   }
   if (parsed.type !== 'judgment') continue;
   if (asString(parsed.head_sha) !== headSha) continue;
+  const recordStopWaveId = asNumber(parsed.stop_wave_id) ?? 0;
+  if (!Number.isInteger(recordStopWaveId) || recordStopWaveId < 0) {
+    fail('Current-HEAD judgment at line ' + (index + 1) + ' must carry a non-negative integer stop_wave_id.');
+  }
+  if (recordStopWaveId !== activeStopWaveId) continue;
   if (typeof parsed.can_stop !== 'boolean') {
     fail('Current-HEAD judgment at line ' + (index + 1) + ' must carry boolean can_stop.');
   }
@@ -98,10 +108,10 @@ if (!stopWaveActive && currentHeadJudgments.length === 0) {
 }
 
 if (currentHeadJudgments.length < requiredStopJudges) {
-  fail('Need ' + requiredStopJudges + ' valid current-HEAD judgments for HEAD ' + headSha + '; found ' + currentHeadJudgments.length + '.');
+  fail('Need ' + requiredStopJudges + ' valid current-HEAD judgments for HEAD ' + headSha + ' in stop_wave_id ' + activeStopWaveId + '; found ' + currentHeadJudgments.length + '.');
 }
 
-console.log('[completion] stop-wave policy unanimous-current-head-v1 satisfied for HEAD ' + headSha + ' with ' + currentHeadJudgments.length + ' valid current-HEAD judgments');
+console.log('[completion] stop-wave policy unanimous-current-head-v1 satisfied for HEAD ' + headSha + ' in stop_wave_id ' + activeStopWaveId + ' with ' + currentHeadJudgments.length + ' valid current-HEAD judgments');
 NODE
 
 echo "[completion] running repo-level verification: npm run release-check >/dev/null"

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 0.1.77
+
+### Fixed
+
+- introduced `current_stop_wave_id` / `stop_wave_id` stop-wave epochs so the same HEAD can restart stop evaluation after stale no-stop history without requiring a synthetic tracked commit
+- taught stop-judge transcription, verifier policy, protocol docs, and release regression coverage to scope stop-wave aggregation to the active epoch instead of permanently poisoning a HEAD on the first `can_stop=no`
+
 ## 0.1.76
 
 ### Fixed

package/README.md

@@ -236,6 +236,7 @@ Ignored execution-state files:
 - `.agent/active-slice.json`
 - `.agent/slice-history.jsonl`
 - `.agent/stop-check-history.jsonl`
+- `state.json current_stop_wave_id` defines the current stop-wave epoch so the same HEAD can restart stop evaluation without requiring a synthetic tracked commit.
 - `.agent/verification-evidence.json`
 - `.agent/*.log`
 - `.agent/tmp/`

package/agents/completion-regrounder.md

@@ -41,16 +41,18 @@ These lines are for workflow observability, not hidden reasoning. Keep them brie
 5. Reopen any previously `done` slice whose acceptance criteria no longer hold.
 6. Keep `.agent/state.json` and `.agent/active-slice.json` truthful, including `current_phase`, `continuation_policy`, `continuation_reason`, `next_mandatory_role`, and any exact implementer handoff snapshot fields.
 7. Reconcile canonical state after review, audit, and final stop verification waves when required.
-8. If the latest committed slice leaves the tracked and unignored worktree dirty, first classify the dirty tracked files against the latest slice's `implementation_surfaces` and the tracked reconciliation surfaces you need to touch now.
-9. If the dirty tracked files are unrelated and can be isolated safely, auto-preserve them yourself with a reversible mechanism such as a named git stash plus a `.agent/tmp/dirty-worktree-autostash.json` note, continue the mandatory reconciliation on a clean worktree, and restore them before handing control back. Do not ask the user for this routine unrelated-dirty-worktree case.
-10. If overlap, ownership ambiguity, or stash/restore conflicts make automatic isolation unsafe, treat that dirty state as a blocker, reopen or continue the latest slice for reconciliation, set `Next role to invoke` to `completion-implementer`, and do not select or hand off any different next slice until it is reconciled.
-11. When reconciling after review, audit, or dirty-worktree follow-up for the latest committed slice, emit an explicit reconciliation record decision:
+8. When entering a fresh stop wave after all implementation slices are done, set or increment `.agent/state.json current_stop_wave_id` for the new stop-wave epoch and reset `remaining_stop_judges` from `.agent/profile.json required_stop_judges`.
+9. If a prior stop-wave epoch on the same HEAD recorded `can_stop = no`, do not permanently poison that HEAD by itself. If canonical state, docs/state parity, or verification truth have changed enough to justify a fresh stop evaluation on the same HEAD, increment `current_stop_wave_id`, preserve the old judgments as history, and restart stop-wave collection for the new epoch.
+10. If the latest committed slice leaves the tracked and unignored worktree dirty, first classify the dirty tracked files against the latest slice's `implementation_surfaces` and the tracked reconciliation surfaces you need to touch now.
+11. If the dirty tracked files are unrelated and can be isolated safely, auto-preserve them yourself with a reversible mechanism such as a named git stash plus a `.agent/tmp/dirty-worktree-autostash.json` note, continue the mandatory reconciliation on a clean worktree, and restore them before handing control back. Do not ask the user for this routine unrelated-dirty-worktree case.
+12. If overlap, ownership ambiguity, or stash/restore conflicts make automatic isolation unsafe, treat that dirty state as a blocker, reopen or continue the latest slice for reconciliation, set `Next role to invoke` to `completion-implementer`, and do not select or hand off any different next slice until it is reconciled.
+13. When reconciling after review, audit, dirty-worktree follow-up, or stop-wave epoch restart for the latest committed slice, emit an explicit reconciliation record decision:
    - `accepted` only when the latest committed slice is truthfully accepted as-is
    - `reopened` only when the latest committed slice must be reopened for follow-up work
    - `none` when this re-ground was not a post-commit reconciliation decision
-12. If you emit `accepted` or `reopened`, also emit the exact reconciled slice id in the report.
-13. If a slice is already selected, ensure `.agent/active-slice.json` contains the exact implementer handoff snapshot and return that exact handoff payload for `completion-implementer` instead of implementing it yourself.
-14. If no slice is selected, return the exact next recommended slice and why.
+14. If you emit `accepted` or `reopened`, also emit the exact reconciled slice id in the report.
+15. If a slice is already selected, ensure `.agent/active-slice.json` contains the exact implementer handoff snapshot and return that exact handoff payload for `completion-implementer` instead of implementing it yourself.
+16. If no slice is selected, return the exact next recommended slice and why.
 
 Output format:
 

package/agents/completion-stop-judge.md

@@ -19,7 +19,7 @@ You must not:
 - append stop-check history yourself
 - create commits
 
-The workflow driver records your returned verdict into `.agent/stop-check-history.jsonl` during the final stop wave. Your output must therefore be explicit enough to transcribe faithfully as one canonical `judgment` record for the current HEAD.
+The workflow driver records your returned verdict into `.agent/stop-check-history.jsonl` during the final stop wave. Your output must therefore be explicit enough to transcribe faithfully as one canonical `judgment` record for the current HEAD and current `state.json current_stop_wave_id` epoch.
 
 During long work, emit short operator-facing progress lines when useful using these exact prefixes:
 - `PROGRESS: ...`

package/extensions/completion/role-reporting.js

@@ -46,6 +46,10 @@ 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 parseReportFields(text) {
   const fields = {};
   for (const rawLine of text.split("\n")) {
@@ -317,6 +321,16 @@ async function appendJsonlRecord(filePath, record) {
   await fs.appendFile(filePath, `${JSON.stringify(record)}\n`, "utf8");
 }
 
+async function readJsonFile(filePath) {
+  try {
+    const raw = await fs.readFile(filePath, "utf8");
+    const parsed = JSON.parse(raw);
+    return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
 async function transcribeCanonicalRoleReport({ role, output, reportFields = parseReportFields(output), snapshotFiles, headSha, sliceId, recordedAt = Date.now() }) {
   const result = { appended: [], skipped: [], errors: [] };
 
@@ -370,12 +384,18 @@ async function transcribeCanonicalRoleReport({ role, output, reportFields = pars
       result.errors.push("Missing required stop-judge fields for canonical judgment transcription.");
       return result;
     }
+    const state = snapshotFiles.statePath ? await readJsonFile(snapshotFiles.statePath) : undefined;
+    const currentStopWaveId = asNumber(state?.current_stop_wave_id) ?? 1;
+    if (!Number.isInteger(currentStopWaveId) || currentStopWaveId < 0) {
+      result.errors.push("Canonical state must carry a non-negative integer current_stop_wave_id before stop-judge transcription.");
+      return result;
+    }
     const history = await readJsonl(snapshotFiles.stopHistoryPath);
     const duplicate = history.some((entry) => {
-      return entry.type === "judgment" && entry.head_sha === headSha && entry.report_text === output.trim();
+      return entry.type === "judgment" && entry.head_sha === headSha && asNumber(entry.stop_wave_id) === currentStopWaveId && entry.report_text === output.trim();
     });
     if (duplicate) {
-      result.skipped.push(`Skipped duplicate judgment record at ${headSha.slice(0, 12)}.`);
+      result.skipped.push(`Skipped duplicate judgment record for stop_wave_id ${currentStopWaveId} at ${headSha.slice(0, 12)}.`);
       return result;
     }
     await appendJsonlRecord(snapshotFiles.stopHistoryPath, {
@@ -383,6 +403,7 @@ async function transcribeCanonicalRoleReport({ role, output, reportFields = pars
       type: "judgment",
       recorded_at: recordedAt,
       head_sha: headSha,
+      stop_wave_id: currentStopWaveId,
       can_stop: canStop,
       blocker_count: blockerCount,
       high_value_gap_count: highValueGapCount,
@@ -390,7 +411,7 @@ async function transcribeCanonicalRoleReport({ role, output, reportFields = pars
       report_fields: reportFields,
       report_text: output.trim(),
     });
-    result.appended.push(`judgment:${headSha.slice(0, 12)}`);
+    result.appended.push(`judgment:${headSha.slice(0, 12)}:wave:${currentStopWaveId}`);
     return result;
   }
 

package/extensions/completion/state-store.ts

@@ -272,6 +272,7 @@ export function defaultState(
 		next_mandatory_action: "Reconcile canonical state from current repo truth",
 		next_mandatory_role: "completion-regrounder",
 		remaining_stop_judges: requiredStopJudges,
+		current_stop_wave_id: 0,
 		last_reground_at: null,
 		last_auditor_verdict: null,
 		contract_status: "unknown",
@@ -367,7 +368,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/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`;
+	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}"\`. Canonical \`.agent/state.json current_stop_wave_id\` carries the current stop-wave epoch so the same HEAD may restart stop evaluation without requiring a synthetic tracked commit.\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 {
@@ -433,6 +434,11 @@ if (stopAggregationPolicy !== '${DEFAULT_STOP_AGGREGATION_POLICY}') {
 
 const currentPhase = asString(state.current_phase) ?? 'unknown';
 const stopWaveActive = currentPhase === 'stop_wave' || currentPhase === 'done';
+const currentStopWaveId = asNumber(state.current_stop_wave_id) ?? 0;
+if (!Number.isInteger(currentStopWaveId) || currentStopWaveId < 0) {
+  fail('.agent/state.json current_stop_wave_id must be a non-negative integer before stop verification can run.');
+}
+const activeStopWaveId = stopWaveActive ? currentStopWaveId || 1 : currentStopWaveId;
 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) {
@@ -455,6 +461,11 @@ for (const [index, rawLine] of rawHistory.split(/\\r?\\n/).entries()) {
   }
   if (parsed.type !== 'judgment') continue;
   if (asString(parsed.head_sha) !== headSha) continue;
+  const recordStopWaveId = asNumber(parsed.stop_wave_id) ?? 0;
+  if (!Number.isInteger(recordStopWaveId) || recordStopWaveId < 0) {
+    fail('Current-HEAD judgment at line ' + (index + 1) + ' must carry a non-negative integer stop_wave_id.');
+  }
+  if (recordStopWaveId !== activeStopWaveId) continue;
   if (typeof parsed.can_stop !== 'boolean') {
     fail('Current-HEAD judgment at line ' + (index + 1) + ' must carry boolean can_stop.');
   }
@@ -478,10 +489,10 @@ if (!stopWaveActive && currentHeadJudgments.length === 0) {
 }
 
 if (currentHeadJudgments.length < requiredStopJudges) {
-  fail('Need ' + requiredStopJudges + ' valid current-HEAD judgments for HEAD ' + headSha + '; found ' + currentHeadJudgments.length + '.');
+  fail('Need ' + requiredStopJudges + ' valid current-HEAD judgments for HEAD ' + headSha + ' in stop_wave_id ' + activeStopWaveId + '; found ' + currentHeadJudgments.length + '.');
 }
 
-console.log('[completion] stop-wave policy ${DEFAULT_STOP_AGGREGATION_POLICY} satisfied for HEAD ' + headSha + ' with ' + currentHeadJudgments.length + ' valid current-HEAD judgments');
+console.log('[completion] stop-wave policy ${DEFAULT_STOP_AGGREGATION_POLICY} satisfied for HEAD ' + headSha + ' in stop_wave_id ' + activeStopWaveId + ' with ' + currentHeadJudgments.length + ' valid current-HEAD judgments');
 NODE
 
 ${repoCheck}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@linimin/pi-letscook",
-  "version": "0.1.76",
+  "version": "0.1.77",
   "description": "Pi package for long-running completion workflows with canonical .agent state, role-based subagents, continuity, and verification helpers.",
   "license": "MIT",
   "private": false,
@@ -43,6 +43,7 @@
     "observability-status-test": "bash ./scripts/observability-status-test.sh",
     "completion-role-gating-test": "bash ./scripts/completion-role-gating-test.sh",
     "dirty-worktree-policy-test": "bash ./scripts/dirty-worktree-policy-test.sh",
+    "stop-wave-epoch-test": "bash ./scripts/stop-wave-epoch-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/evaluator-calibration-test.sh

@@ -44,9 +44,11 @@ const tempRootBase = path.join(process.cwd(), '.agent', 'tmp');
 fs.mkdirSync(tempRootBase, { recursive: true });
 const tempRoot = fs.mkdtempSync(path.join(tempRootBase, 'evaluator-calibration-'));
 const snapshotFiles = {
+  statePath: path.join(tempRoot, 'state.json'),
   sliceHistoryPath: path.join(tempRoot, 'slice-history.jsonl'),
   stopHistoryPath: path.join(tempRoot, 'stop-check-history.jsonl'),
 };
+fs.writeFileSync(snapshotFiles.statePath, JSON.stringify({ current_stop_wave_id: 1 }, null, 2));
 fs.writeFileSync(snapshotFiles.sliceHistoryPath, '');
 fs.writeFileSync(snapshotFiles.stopHistoryPath, '');
 
@@ -378,7 +380,7 @@ Brief justification: This should be rejected because remaining contracts still e
     recordedAt: 5,
   });
   assert(judged.errors.length === 0, `stop-judge passing fixture should transcribe cleanly: ${judged.errors.join(' | ')}`);
-  assert(judged.appended.includes('judgment:555555555555'), 'stop-judge passing fixture should append a judgment record');
+  assert(judged.appended.includes('judgment:555555555555:wave:1'), 'stop-judge passing fixture should append a judgment record for the active stop-wave epoch');
   assert(readJsonl(snapshotFiles.stopHistoryPath).length === 1, 'stop-judge passing fixture should create one judgment record');
 
   const judgeRejected = await transcribeCanonicalRoleReport({

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, completion-role gating, dirty-worktree policy, 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, dirty-worktree policy, stop-wave epoch, 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
 
@@ -85,6 +85,7 @@ bash ./scripts/active-slice-contract-test.sh
 npm run observability-status-test
 npm run completion-role-gating-test
 npm run dirty-worktree-policy-test
+npm run stop-wave-epoch-test
 bash ./scripts/legacy-cleanup-test.sh
 npm run evaluator-calibration-test
 npm run rubric-contract-test

package/scripts/rubric-contract-test.sh

@@ -117,9 +117,11 @@ const tempRootBase = path.join(process.cwd(), '.agent', 'tmp');
 fs.mkdirSync(tempRootBase, { recursive: true });
 const tempRoot = fs.mkdtempSync(path.join(tempRootBase, 'rubric-role-reporting-'));
 const snapshotFiles = {
+  statePath: path.join(tempRoot, 'state.json'),
   sliceHistoryPath: path.join(tempRoot, 'slice-history.jsonl'),
   stopHistoryPath: path.join(tempRoot, 'stop-check-history.jsonl'),
 };
+fs.writeFileSync(snapshotFiles.statePath, JSON.stringify({ current_stop_wave_id: 1 }, null, 2));
 fs.writeFileSync(snapshotFiles.sliceHistoryPath, '');
 fs.writeFileSync(snapshotFiles.stopHistoryPath, '');
 
@@ -204,7 +206,7 @@ const stopJudgeMalformedYesNo = `MISSION ANCHOR: test mission\nRemaining contrac
     recordedAt: 5,
   });
   assert(judged.errors.length === 0, `stop-judge valid report should transcribe cleanly: ${judged.errors.join(' | ')}`);
-  assert(judged.appended.includes('judgment:555555555555'), 'stop-judge transcription should append judgment record');
+  assert(judged.appended.includes('judgment:555555555555:wave:1'), 'stop-judge transcription should append judgment record for the active stop-wave epoch');
   assert(readJsonl(snapshotFiles.stopHistoryPath).length === 1, 'stop-judge transcription should create one judgment record');
 
   const judgeRejected = await transcribeCanonicalRoleReport({

package/scripts/stop-wave-epoch-test.sh

@@ -0,0 +1,222 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+cd "$ROOT"
+
+TMPDIR="$(mktemp -d)"
+trap 'rm -rf "$TMPDIR"' EXIT
+REPO="$TMPDIR/repo"
+mkdir -p "$REPO/.agent"
+cd "$REPO"
+
+git init -q
+git config user.name "stop-wave-epoch-test"
+git config user.email "stop-wave-epoch-test@example.invalid"
+printf '# stop wave epoch fixture\n' > README.md
+git add README.md
+git commit -q -m "fixture baseline"
+HEAD_SHA="$(git rev-parse HEAD)"
+
+cp "$ROOT/.agent/README.md" .agent/README.md
+cp "$ROOT/.agent/mission.md" .agent/mission.md
+cp "$ROOT/.agent/profile.json" .agent/profile.json
+cp "$ROOT/.agent/verify_completion_control_plane.sh" .agent/verify_completion_control_plane.sh
+cp "$ROOT/.agent/verify_completion_stop.sh" .agent/verify_completion_stop.sh
+chmod +x .agent/verify_completion_control_plane.sh .agent/verify_completion_stop.sh
+python3 - <<'PY'
+from pathlib import Path
+path = Path('.agent/verify_completion_stop.sh')
+text = path.read_text()
+path.write_text(text.replace('npm run release-check >/dev/null', 'true'))
+PY
+
+git add .agent/README.md .agent/mission.md .agent/profile.json .agent/verify_completion_control_plane.sh .agent/verify_completion_stop.sh
+git commit -q -m "scaffold tracked completion contract files"
+HEAD_SHA="$(git rev-parse HEAD)"
+
+HEAD_SHA="$HEAD_SHA" python3 - <<'PY'
+import json
+import os
+from pathlib import Path
+head = os.environ['HEAD_SHA']
+mission = 'Stop-wave epoch regression fixture.'
+profile = json.loads(Path('.agent/profile.json').read_text())
+state = {
+    'schema_version': 1,
+    'mission_anchor': mission,
+    'workflow_entry_status': 'active',
+    'workflow_entry_source': '/cook',
+    'workflow_entry_confirmed_at': '2026-05-24T00:00:00Z',
+    'workflow_session_id': 'stop-wave-epoch-fixture',
+    'startup_brief_path': '.agent/startup-brief.json',
+    'current_phase': 'stop_wave',
+    'continuation_policy': 'continue',
+    'continuation_reason': 'Restart stop wave on the same HEAD after earlier no-stop evidence became stale.',
+    'project_done': False,
+    'task_type': profile['task_type'],
+    'evaluation_profile': profile['evaluation_profile'],
+    'requires_reground': False,
+    'slices_since_last_reground': 0,
+    'remaining_release_blockers': 0,
+    'remaining_high_value_gaps': 0,
+    'unsatisfied_contract_ids': [],
+    'release_blocker_ids': [],
+    'next_mandatory_action': 'Collect stop-wave judgments for the restarted epoch.',
+    'next_mandatory_role': 'completion-stop-judge',
+    'remaining_stop_judges': 2,
+    'current_stop_wave_id': 2,
+    'last_reground_at': '2026-05-24T00:00:00Z',
+    'last_auditor_verdict': 'pass',
+    'contract_status': 'stop_wave_pending_judgments',
+    'latest_completed_slice': head,
+    'latest_verified_slice': head,
+}
+startup_brief = {
+    'schema_version': 1,
+    'artifact_type': 'completion-startup-brief',
+    'source': 'test',
+    'confirmed': True,
+    'confirmed_at': '2026-05-24T00:00:00Z',
+    'mission': mission,
+    'goal_text': f'Mission: {mission}',
+    'scope': [],
+    'constraints': [],
+    'acceptance': [],
+    'risks': [],
+    'notes': ['stop-wave epoch test fixture'],
+    'task_type': profile['task_type'],
+    'evaluation_profile': profile['evaluation_profile'],
+}
+plan = {
+    'schema_version': 1,
+    'mission_anchor': mission,
+    'task_type': profile['task_type'],
+    'evaluation_profile': profile['evaluation_profile'],
+    'last_reground_at': '2026-05-24T00:00:00Z',
+    'plan_basis': 'stop_wave_epoch_fixture',
+    'candidate_slices': [],
+}
+active = {
+    'schema_version': 1,
+    'mission_anchor': mission,
+    'task_type': profile['task_type'],
+    'evaluation_profile': profile['evaluation_profile'],
+    'status': 'idle',
+    'slice_id': None,
+    'goal': None,
+    'contract_ids': [],
+    'acceptance_criteria': [],
+    'priority': None,
+    'why_now': None,
+    'blocked_on': [],
+    'locked_notes': [],
+    'must_fix_findings': [],
+    'implementation_surfaces': [],
+    'verification_commands': [],
+    'basis_commit': None,
+    'remaining_contract_ids_before': [],
+    'release_blocker_count_before': None,
+    'high_value_gap_count_before': None,
+}
+evidence = {
+    'schema_version': 1,
+    'artifact_type': 'completion-verification-evidence',
+    'subject_type': 'none',
+    'slice_id': None,
+    'goal': None,
+    'contract_ids': [],
+    'basis_commit': None,
+    'head_sha': None,
+    'verification_commands': [],
+    'outcome': 'not_recorded',
+    'recorded_at': None,
+    'summary': 'No selected-slice verification evidence is required for the stop-wave epoch fixture.',
+}
+Path('.agent/state.json').write_text(json.dumps(state, indent=2) + '\n')
+Path('.agent/startup-brief.json').write_text(json.dumps(startup_brief, indent=2) + '\n')
+Path('.agent/plan.json').write_text(json.dumps(plan, indent=2) + '\n')
+Path('.agent/active-slice.json').write_text(json.dumps(active, indent=2) + '\n')
+Path('.agent/verification-evidence.json').write_text(json.dumps(evidence, indent=2) + '\n')
+Path('.agent/stop-check-history.jsonl').write_text(json.dumps({
+    'schema_version': 1,
+    'type': 'judgment',
+    'recorded_at': 1,
+    'head_sha': head,
+    'stop_wave_id': 1,
+    'can_stop': False,
+    'blocker_count': 1,
+    'high_value_gap_count': 0,
+}) + '\n')
+Path('.agent/slice-history.jsonl').write_text('')
+PY
+
+HEAD_SHA="$HEAD_SHA" python3 - <<'PY'
+import os, subprocess
+combined = subprocess.run(['bash', '.agent/verify_completion_stop.sh'], text=True, capture_output=True)
+text = combined.stdout + combined.stderr
+assert combined.returncode != 0, 'expected stop verifier to fail before current stop-wave judgments are recorded'
+assert f'Need 2 valid current-HEAD judgments for HEAD {os.environ["HEAD_SHA"]} in stop_wave_id 2; found 0.' in text, text
+assert 'Current HEAD has a can_stop=no judgment' not in text, text
+PY
+
+HEAD_SHA="$HEAD_SHA" python3 - <<'PY'
+import json, os
+from pathlib import Path
+head = os.environ['HEAD_SHA']
+records = [
+    {
+        'schema_version': 1,
+        'type': 'judgment',
+        'recorded_at': 2,
+        'head_sha': head,
+        'stop_wave_id': 2,
+        'can_stop': True,
+        'blocker_count': 0,
+        'high_value_gap_count': 0,
+    },
+    {
+        'schema_version': 1,
+        'type': 'judgment',
+        'recorded_at': 3,
+        'head_sha': head,
+        'stop_wave_id': 2,
+        'can_stop': True,
+        'blocker_count': 0,
+        'high_value_gap_count': 0,
+    },
+]
+with Path('.agent/stop-check-history.jsonl').open('a', encoding='utf8') as fh:
+    for record in records:
+        fh.write(json.dumps(record) + '\n')
+PY
+
+bash .agent/verify_completion_stop.sh >/dev/null
+
+ROOT_PATH="$ROOT" node - <<'NODE'
+const fs = require('node:fs');
+const path = require('node:path');
+const { parseReportFields, transcribeCanonicalRoleReport } = require(path.join(process.env.ROOT_PATH, 'extensions/completion/role-reporting.js'));
+(async () => {
+  const report = `MISSION ANCHOR: epoch mission\nRemaining contract IDs: none\nRubric:\n- Contract coverage: pass - All implementation slices are accepted on HEAD.\n- Correctness risk: pass - No remaining blocker or high-value gap is evident.\n- Verification evidence: pass - Final verification passes for the current head.\n- Docs/state parity: pass - Docs, config, and canonical state match shipped behavior.\nCan the project stop now: yes\nExact remaining open top-level contract IDs: none\nBlocker count: 0\nHigh-value gap count: 0\nLatest completed slice commit: abcdef1234567890abcdef1234567890abcdef12\nDocs/config/runbooks match shipped behavior: yes\nTracked and unignored worktree is clean: yes\nBrief justification: Stop-wave epoch transcription should capture the active stop_wave_id.`;
+  const headSha = require('node:child_process').execFileSync('git', ['rev-parse', 'HEAD'], { encoding: 'utf8' }).trim();
+  const result = await transcribeCanonicalRoleReport({
+    role: 'completion-stop-judge',
+    output: report,
+    reportFields: parseReportFields(report),
+    snapshotFiles: {
+      statePath: path.join(process.cwd(), '.agent/state.json'),
+      stopHistoryPath: path.join(process.cwd(), '.agent/stop-check-history.jsonl'),
+      sliceHistoryPath: path.join(process.cwd(), '.agent/slice-history.jsonl'),
+    },
+    headSha,
+    recordedAt: 4,
+  });
+  if (result.errors.length > 0) throw new Error(result.errors.join(' | '));
+  const lines = fs.readFileSync('.agent/stop-check-history.jsonl', 'utf8').trim().split('\n').map((line) => JSON.parse(line));
+  const last = lines[lines.length - 1];
+  if (last.stop_wave_id !== 2) throw new Error('transcribed stop judgment must include current stop_wave_id 2');
+})();
+NODE
+
+echo "stop-wave epoch test passed"

package/skills/completion-protocol/SKILL.md

@@ -36,7 +36,7 @@ This skill defines shared protocol facts only. Role-specific behavior belongs in
 - 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.
+- Under `unanimous-current-head-v1`, only current-HEAD `judgment` records from the current stop-wave epoch count. Canonical `state.json current_stop_wave_id` tracks that epoch, may be incremented to restart stop evaluation on the same `HEAD`, and repo-level stop verification must wait until the required current-HEAD judgments for the current epoch 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.
@@ -86,7 +86,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 current-HEAD `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 for the current `current_stop_wave_id` 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

@@ -87,6 +87,7 @@ Required fields:
 - `next_mandatory_action`
 - `next_mandatory_role`
 - `remaining_stop_judges`
+- `current_stop_wave_id`
 - `last_reground_at`
 - `last_auditor_verdict`
 - `contract_status`
@@ -250,6 +251,7 @@ Minimum record shape:
 - `type`
 - `recorded_at`
 - `head_sha`
+- `stop_wave_id`
 - `can_stop`
 - `blocker_count`
 - `high_value_gap_count`
@@ -265,11 +267,12 @@ The packaged default stop policy is:
 
 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`
+- `state.json current_stop_wave_id` is the current stop-wave epoch for the current mission and may be incremented to restart stop evaluation on the same `HEAD`
+- count only `judgment` records whose `head_sha` matches the current `HEAD` and whose `stop_wave_id` matches `state.json current_stop_wave_id`
+- require at least two valid current-HEAD judgments for the current stop-wave epoch before repo-level stop verification may run
+- fail closed if any current-HEAD judgment in the current stop-wave epoch has `can_stop = false`
+- fail closed if a current-HEAD judgment in the current stop-wave epoch 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 for the current stop-wave epoch are faithfully recorded, then hand final reconciliation back to `completion-regrounder`
 
 ## Structured Evaluation Rubric Foundation