@delegance/claude-autopilot 7.9.0 → 7.10.0

package/CHANGELOG.md

@@ -2,6 +2,34 @@
 
 - v5.6 Phase 7 (docs reconciliation) — pending.
 
+## 7.10.0 — 2026-05-13
+
+### Added
+- **Retry-loop sameness detector** (`src/core/run-state/sameness-detector.ts`) — new pure-TS module exporting `computeFingerprint`, `isSameFailure`, `shouldEscalate`, and `stripVolatileTokens`. A failure fingerprint is `{ phase, errorType, errorLocation, errorMessage, hash }` where `hash` is `sha256(JSON.stringify([phase, errorType, errorLocation, normalize(message[:200])]))`. JSON encoding is delimiter-safe — pipes, quotes, and embedded JSON in fields cannot produce cross-tuple collisions. `shouldEscalate(history)` returns `{ escalate: true }` when the last two entries have identical hashes — the signal that retries are making no progress.
+- **Volatile-token stripping built into the detector.** Both `errorLocation` and `errorMessage` are scrubbed of UUIDs, ISO timestamps, 13-digit epoch ms, sha1/sha256 hex digests, /tmp + /var/folders paths, and localhost:port before hashing — so a retry whose message differs only in a per-run UUID or temp directory still hashes to the same fingerprint. Exported as `stripVolatileTokens()` for callers that want to scrub before constructing a fingerprint.
+- **Public package subpath export.** `package.json` adds `./run-state/sameness-detector` pointing at `dist/src/core/run-state/sameness-detector.{js,d.ts}` so consumers can `import { computeFingerprint, shouldEscalate } from '@delegance/claude-autopilot/run-state/sameness-detector'` without deep-importing into compiled paths.
+- **Pipeline halts when retries make no progress, even if you have retries remaining.** `skills/autopilot/SKILL.md` Step 4 (validate), Step 7 (Codex PR review), and Step 8 (bugbot) now consult the detector before consuming a retry. If the same failure fingerprint fires twice in a row inside any retry loop, the pipeline stops and surfaces the matching fingerprint to the user instead of burning the remaining retry budget. This catches the class of bug where validate retries fix nothing because the underlying type error is unreachable from the change set.
+- Tests: `tests/run-state/sameness-detector.test.ts` (32 cases) covers the three issue-#181 acceptance scenarios (same × 2 escalates, same × 1 continues, different × 3 continues), edge cases (empty history, ABA pattern, message truncation, all three phases), delimiter-safety (fields containing `|`), and volatile-token scrubbing (UUIDs, timestamps, tmpdirs). `tests/run-state/sameness-detector-integration.test.ts` (7 cases) verifies SKILL.md retry-block references and that the compiled subpath export is importable + functional.
+
+### Notes
+- Persistence is intentionally in-memory only in v7.10.0. Per-retry-loop history is held in the autopilot skill execution scope; bugbot and validate do not share a history. The v6 run-state events.ndjson integration is tracked separately as issue #180.
+- Released as v7.10.0 even though issue #181 was originally labeled v7.11.0 — this ships before #178 and #179, so it gets the next minor.
+
+### Out of scope (still pending)
+- Expand/contract migration classification (additive vs destructive enforcement) — v7.11.0 candidate
+- v6 run-state engine integration into the autopilot skill (4,873 LOC of checkpoint/resume infra currently unused by the skill) — issue #180
+
+## 7.9.1 — 2026-05-13 (correctness hotfix)
+
+### Fixed
+- **`skills/autopilot/SKILL.md` ran migrate BEFORE validate.** On stacks that auto-promote (Supabase-script-specific), this could leave production with new schema and no working code if validate or PR review later failed. Resequenced: validate is now Step 4, migrate-dev is Step 5. PR + Codex + bugbot follow. Production migration is explicitly handed off to the user's CI/CD pipeline.
+- **Removed misleading "dev → QA → prod auto-promote" claim.** That behavior is Supabase-stack-specific, not a generic CLI capability. The skill now references the four real `migrate.policy` keys (`allow_prod_in_ci`, `require_clean_git`, `require_manual_approval`, `require_dry_run_first`) and explains how to wire them in `.autopilot/stack.md`.
+
+### Out of scope (filed as v7.10.0 + v7.11.0 candidates)
+- Expand/contract migration classification (additive vs destructive enforcement)
+- v6 run-state engine integration into the autopilot skill (4,873 LOC of checkpoint/resume infra currently unused by the skill)
+- Retry-loop sameness detector ("same fingerprint twice → escalate to human")
+
 ## 7.9.0 — 2026-05-12
 
 ### Changed

package/dist/src/core/run-state/sameness-detector.d.ts

@@ -0,0 +1,82 @@
+/** Which loop in the autopilot pipeline produced the failure. The three
+ *  Step-4 / Step-7 / Step-8 retry loops in `skills/autopilot/SKILL.md` are
+ *  the call sites that consult the detector before consuming a retry. */
+export type FailurePhase = 'validate' | 'codex-review' | 'bugbot';
+/** A normalized identity for a single failure occurrence. Two fingerprints
+ *  are "the same failure" iff their `hash` is equal — phase, errorType,
+ *  errorLocation, and the truncated/normalized errorMessage all feed into
+ *  the hash, so any meaningful change between retries produces a new hash. */
+export interface FailureFingerprint {
+    phase: FailurePhase;
+    /** Discriminator inside the phase. Examples:
+     *   - validate: 'tsc_error' | 'test_failure' | 'lint_error'
+     *   - codex-review: 'codex_critical' | 'codex_warning'
+     *   - bugbot: 'bugbot_high' | 'bugbot_medium' */
+    errorType: string;
+    /** Where the failure points. `file:line` for tsc/lint, test name for tests,
+     *  finding-id for codex, comment-id for bugbot. Whatever uniquely locates
+     *  the problem within the phase. */
+    errorLocation: string;
+    /** First 200 chars of the canonical message, whitespace-collapsed. The
+     *  truncation is what makes the fingerprint stable across runs that differ
+     *  only in trailing stack-frame noise. */
+    errorMessage: string;
+    /** sha256 hex of `${phase}|${errorType}|${errorLocation}|${errorMessage}`.
+     *  This is the equality key. */
+    hash: string;
+}
+/** Maximum length of the normalized error message that feeds the hash.
+ *  Anything beyond this is dropped — picked to match the issue spec and to
+ *  keep the hash stable across runs that differ only in trailing noise. */
+export declare const FINGERPRINT_MESSAGE_MAX = 200;
+export interface ComputeFingerprintInput {
+    phase: FailurePhase;
+    errorType: string;
+    errorLocation: string;
+    errorMessage: string;
+}
+/** Strip known volatile / per-run tokens from a free-form string so that two
+ *  retries that differ only in transient data (UUIDs, ports, epoch
+ *  timestamps, ISO timestamps, hex SHAs, absolute temp paths) produce the
+ *  same canonical form. Order matters — broader patterns run first so they
+ *  can swallow embedded delimiters before narrower patterns see them.
+ *
+ *  Exported because callers building locations/messages outside this module
+ *  may want to apply the same scrubbing before constructing a fingerprint
+ *  (e.g. when assembling an `errorLocation` from a tool output that embeds
+ *  a run-id). */
+export declare function stripVolatileTokens(s: string): string;
+/** Compute a stable fingerprint for a single failure occurrence. The
+ *  returned `hash` is the equality key — two failures with equal hashes
+ *  are considered "the same failure" for retry-loop escalation purposes. */
+export declare function computeFingerprint(input: ComputeFingerprintInput): FailureFingerprint;
+/** Compare two fingerprints. They are "the same failure" iff their hashes
+ *  match — phase/type/location/message all feed the hash, so equal hash
+ *  means equal across all observable identity. */
+export declare function isSameFailure(a: FailureFingerprint, b: FailureFingerprint): boolean;
+export interface EscalationDecision {
+    /** True iff the caller should STOP consuming retries and surface to a
+     *  human, because the last two recorded attempts produced the same
+     *  failure (no progress between retries). */
+    escalate: boolean;
+    /** Set when `escalate` is true — human-readable explanation. */
+    reason?: string;
+    /** Set when `escalate` is true — the offending fingerprint that fired
+     *  twice. Callers should display this to the operator so they can see
+     *  what's stuck. */
+    fingerprint?: FailureFingerprint;
+}
+/** Decide whether to escalate a retry loop to a human, given the history
+ *  of failure fingerprints recorded so far in this retry loop.
+ *
+ *  Rule (per issue #181): escalate iff `history.length >= 2` AND the last
+ *  two fingerprints have identical hashes. Anything else — first failure,
+ *  different failures across retries, longer streak of different failures
+ *  — returns `{ escalate: false }`.
+ *
+ *  Rationale: a single retry on the SAME failure means we tried, fixed
+ *  nothing, and failed identically. Retries that keep failing on
+ *  *different* things are still making progress (each one is a new fix).
+ *  Only no-progress retries should consume the escalation budget. */
+export declare function shouldEscalate(history: readonly FailureFingerprint[]): EscalationDecision;
+//# sourceMappingURL=sameness-detector.d.ts.map

package/dist/src/core/run-state/sameness-detector.js

@@ -0,0 +1,146 @@
+// src/core/run-state/sameness-detector.ts
+//
+// Retry-loop sameness detector — escalates when the same failure fingerprint
+// fires twice in a row during a retry loop (validate, codex PR review, or
+// bugbot). The pipeline halts when retries make no progress, even if you have
+// retries remaining.
+//
+// Issue: #181 (v7.11.0 — released as v7.10.0).
+//
+// Design:
+//   - `FailureFingerprint` is a hashable identity for a failure. Same hash
+//     across two attempts means "we tried, failed for the same reason, fixed
+//     nothing". That is the signal to stop burning retries and surface to a
+//     human.
+//   - Storage is in-memory only. The v6 run-state events.ndjson integration
+//     is tracked separately as issue #180; explicitly deferred here so the
+//     pipeline can adopt the detector without waiting on persistence.
+//   - All functions are pure (modulo `crypto.createHash`), making this easy
+//     to unit-test under node:test.
+//
+// Who calls this:
+//   The detector is consumed by the autopilot skill agent (an LLM following
+//   `skills/autopilot/SKILL.md`), NOT by the `scripts/validate.ts`,
+//   `scripts/codex-pr-review.ts`, or `scripts/bugbot.ts` CLI scripts. Those
+//   scripts are stateless per-invocation; the retry loop lives one layer
+//   above them, inside the skill execution. Wiring this into the CLIs would
+//   not catch repeated failures because each CLI invocation is a clean
+//   process. The skill agent is the durable retry-loop scope.
+import { createHash } from 'node:crypto';
+/** Maximum length of the normalized error message that feeds the hash.
+ *  Anything beyond this is dropped — picked to match the issue spec and to
+ *  keep the hash stable across runs that differ only in trailing noise. */
+export const FINGERPRINT_MESSAGE_MAX = 200;
+/** Strip known volatile / per-run tokens from a free-form string so that two
+ *  retries that differ only in transient data (UUIDs, ports, epoch
+ *  timestamps, ISO timestamps, hex SHAs, absolute temp paths) produce the
+ *  same canonical form. Order matters — broader patterns run first so they
+ *  can swallow embedded delimiters before narrower patterns see them.
+ *
+ *  Exported because callers building locations/messages outside this module
+ *  may want to apply the same scrubbing before constructing a fingerprint
+ *  (e.g. when assembling an `errorLocation` from a tool output that embeds
+ *  a run-id). */
+export function stripVolatileTokens(s) {
+    if (typeof s !== 'string')
+        return '';
+    return (s
+        // ISO-8601 timestamps (e.g. 2026-05-13T07:00:00.000Z)
+        .replace(/\b\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,6})?(?:Z|[+-]\d{2}:?\d{2})?\b/g, '<ts>')
+        // 13-digit epoch ms
+        .replace(/\b\d{13}\b/g, '<ts>')
+        // UUIDs (v1-v5)
+        .replace(/\b[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}\b/g, '<uuid>')
+        // 40-char (sha1) or 64-char (sha256) hex digests
+        .replace(/\b[0-9a-fA-F]{40}\b/g, '<sha>')
+        .replace(/\b[0-9a-fA-F]{64}\b/g, '<sha>')
+        // macOS / Linux temp paths (/tmp, /var/folders) up to the next whitespace
+        .replace(/\/(?:tmp|var\/folders)\/[^\s'"`]+/g, '<tmpdir>')
+        // localhost ports like :49213
+        .replace(/\b(?:127\.0\.0\.1|localhost):\d{2,5}\b/g, '<host:port>'));
+}
+/** Normalize a free-form error message: strip volatile tokens, trim, collapse
+ *  all runs of whitespace (including newlines/tabs) to single spaces, and
+ *  truncate to `FINGERPRINT_MESSAGE_MAX` characters. The truncation is what
+ *  makes the fingerprint stable across runs whose messages differ only in
+ *  trailing stack-frame noise. */
+function normalizeMessage(msg) {
+    if (typeof msg !== 'string') {
+        return '';
+    }
+    const scrubbed = stripVolatileTokens(msg);
+    const collapsed = scrubbed.replace(/\s+/g, ' ').trim();
+    if (collapsed.length <= FINGERPRINT_MESSAGE_MAX) {
+        return collapsed;
+    }
+    return collapsed.slice(0, FINGERPRINT_MESSAGE_MAX);
+}
+/** Normalize an `errorLocation` (file path / test name / etc.) by applying
+ *  the same volatile-token scrubbing as the message, plus whitespace trim.
+ *  Does NOT truncate — locations are short by construction. */
+function normalizeLocation(loc) {
+    if (typeof loc !== 'string')
+        return '';
+    return stripVolatileTokens(loc).trim();
+}
+/** Compute a stable fingerprint for a single failure occurrence. The
+ *  returned `hash` is the equality key — two failures with equal hashes
+ *  are considered "the same failure" for retry-loop escalation purposes. */
+export function computeFingerprint(input) {
+    const phase = input.phase;
+    const errorType = (input.errorType ?? '').toString();
+    const errorLocation = normalizeLocation((input.errorLocation ?? '').toString());
+    const errorMessage = normalizeMessage(input.errorMessage ?? '');
+    // Use JSON.stringify of a 4-tuple as the canonical pre-hash serialization.
+    // This is unambiguous under any field content — pipe characters, quotes,
+    // braces, embedded JSON, etc. all serialize unambiguously and cannot
+    // produce collisions across different `[phase, type, location, message]`
+    // tuples. (Earlier drafts used a pipe-delimited string; that was vulnerable
+    // to delimiter ambiguity when, e.g., a test name legitimately contained
+    // '|'. The JSON form has no such edge case.)
+    const canonical = JSON.stringify([phase, errorType, errorLocation, errorMessage]);
+    const hash = createHash('sha256').update(canonical).digest('hex');
+    return { phase, errorType, errorLocation, errorMessage, hash };
+}
+/** Compare two fingerprints. They are "the same failure" iff their hashes
+ *  match — phase/type/location/message all feed the hash, so equal hash
+ *  means equal across all observable identity. */
+export function isSameFailure(a, b) {
+    if (!a || !b)
+        return false;
+    return a.hash === b.hash;
+}
+/** Decide whether to escalate a retry loop to a human, given the history
+ *  of failure fingerprints recorded so far in this retry loop.
+ *
+ *  Rule (per issue #181): escalate iff `history.length >= 2` AND the last
+ *  two fingerprints have identical hashes. Anything else — first failure,
+ *  different failures across retries, longer streak of different failures
+ *  — returns `{ escalate: false }`.
+ *
+ *  Rationale: a single retry on the SAME failure means we tried, fixed
+ *  nothing, and failed identically. Retries that keep failing on
+ *  *different* things are still making progress (each one is a new fix).
+ *  Only no-progress retries should consume the escalation budget. */
+export function shouldEscalate(history) {
+    if (!Array.isArray(history) || history.length < 2) {
+        return { escalate: false };
+    }
+    const last = history[history.length - 1];
+    const prev = history[history.length - 2];
+    if (!last || !prev) {
+        return { escalate: false };
+    }
+    if (isSameFailure(prev, last)) {
+        return {
+            escalate: true,
+            reason: `Retry loop produced the same failure twice in a row ` +
+                `(phase=${last.phase}, errorType=${last.errorType}, ` +
+                `errorLocation=${last.errorLocation}). The pipeline is not making ` +
+                `progress — surfacing to human instead of consuming another retry.`,
+            fingerprint: last,
+        };
+    }
+    return { escalate: false };
+}
+//# sourceMappingURL=sameness-detector.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@delegance/claude-autopilot",
-  "version": "7.9.0",
+  "version": "7.10.0",
   "type": "module",
   "publishConfig": {
     "tag": "next"
@@ -39,6 +39,10 @@
       "types": "./dist/src/index.d.ts",
       "default": "./dist/src/index.js"
     },
+    "./run-state/sameness-detector": {
+      "types": "./dist/src/core/run-state/sameness-detector.d.ts",
+      "default": "./dist/src/core/run-state/sameness-detector.js"
+    },
     "./bin/claude-autopilot.js": "./bin/claude-autopilot.js",
     "./bin/guardrail.js": "./bin/guardrail.js",
     "./package.json": "./package.json"

package/skills/autopilot/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: autopilot
-description: End-to-end pipeline — brainstorm → spec → plan → implement → migrate → validate → PR → Codex review → bugbot. Risk-tiered. No manual intervention after spec approval.
+description: End-to-end pipeline — brainstorm → spec → plan → implement → validate → migrate dev → PR → Codex review → bugbot → merge. Risk-tiered. No manual intervention after spec approval until PR merge; production deploy/migration gates are handled by the user's CI/CD pipeline.
 ---
 
 # Autopilot — Idea to Merged PR Pipeline
@@ -209,26 +209,16 @@ For each task:
 - Skip formal spec/quality review to maintain speed (the validate step catches issues)
 - If subagent fails to write to worktree: implement directly
 
-### Step 4: Auto-migrate
+### Step 4: Validate
 
-For any `.sql` files created in `data/deltas/` during implementation:
+Run both checks in order. **Autofix runs first** so the static review sees the final post-autofix diff (otherwise the LLM review is stale on autofix mutations):
 
 ```bash
-/migrate
-```
-
-Run against dev → QA → prod with auto-promote. If migration fails, fix the SQL and retry.
-
-### Step 5: Validate
-
-Run both checks in order:
+# 1. Full project validation FIRST (autofix, tests, codex, gate) — mutates files
+npx tsx scripts/validate.ts --commit-autofix --allow-dirty
 
-```bash
-# 1. Static rules + LLM review on changed files
+# 2. THEN static rules + LLM review on the final diff
 npx autopilot run --base main
-
-# 2. Full project validation (autofix, tests, codex, gate)
-npx tsx scripts/validate.ts --commit-autofix --allow-dirty
 ```
 
 The `validate.ts` Phase 1 includes a **tsc regression check**: it runs `npx tsc --noEmit` against both the PR and the merge-base (cached at `.claude/.tsc-baseline-cache.json`) and surfaces only files where the PR introduces *new* TypeScript errors versus the baseline. Forward-pressure check — type errors are warnings, not blockers.
@@ -236,10 +226,83 @@ The `validate.ts` Phase 1 includes a **tsc regression check**: it runs `npx tsc
 If either FAIL:
 - Read findings / validation report at `.claude/validation-report.json`
 - Fix the blocking issues
+- **Before consuming a retry, compute the failure fingerprint** with `computeFingerprint({ phase: 'validate', errorType, errorLocation, errorMessage })` from `src/core/run-state/sameness-detector.ts`:
+  - `errorType`: `tsc_error` | `test_failure` | `lint_error` (whichever class caused the FAIL)
+  - `errorLocation`: prefer stable identifiers — `<repo-relative-path>:<line>` for tsc/lint, test-suite-name+test-name for tests. Avoid absolute paths and transient temp dirs; use the repo-relative form so the hash survives across working-tree moves.
+  - `errorMessage`: first 200 chars of the canonical message. Strip any embedded UUIDs, ports, or epoch timestamps from the message before computing — those rotate per run and will mask true sameness.
+
+  **Known limitation:** if the underlying fix shifts line numbers, two retries can produce different fingerprints even when the root cause is identical (false negative — no escalation). The current behavior is conservative: it never falsely escalates, but it may let the loop run its full retry budget on a shifting-line-number failure. If you see this pattern, prefer test name + diagnostic code over `file:line`.
+- Append the fingerprint to an in-memory list for this retry loop, then call `shouldEscalate(history)`. If `escalate === true` (the last two attempts produced the same fingerprint), STOP — do not consume another retry. Surface the matching fingerprint to the user and stop the pipeline.
 - Re-run the failing check
 - Max 3 retry iterations
 
-If both PASS: proceed to PR.
+If both PASS: proceed to Step 5.
+
+### Step 5: Migrate dev-only (verify SQL parses + applies)
+
+For any `.sql` files created in `data/deltas/` during implementation, run the migration against the dev database ONLY. Always invoke explicitly — do not rely on the CLI default:
+
+```bash
+/migrate --env=dev
+```
+
+This verifies the SQL parses and applies against the real schema shape before the PR opens. Prod migration is **deferred to the user's CI/CD pipeline** after the PR merges — autopilot does NOT orchestrate prod deploys or migrations directly, because deployment ordering varies wildly across user infrastructure (ECS, CodeBuild, blue/green, manual approvals).
+
+**Post-migration re-validate** (catches type/test failures that only surface after the schema actually changes):
+
+```bash
+# Regenerate any stack-specific DB types if migration introduced schema changes
+# (e.g. Supabase: scripts/gen-types.ts). Stack-specific — skip if N/A.
+# REQUIRED for any stack with generated DB-typed code: missing regeneration leaves
+# stale types and validate.ts may not catch runtime/schema mismatches if the PR
+# does not directly touch the changed columns.
+
+# Re-run validation against the post-migration dev state (no autofix this time):
+npx tsx scripts/validate.ts --allow-dirty
+
+# If migration or type generation produced new file changes, re-run the
+# static/LLM review against the final diff — the Step 4 review is now stale.
+git diff --quiet HEAD -- || npx autopilot run --base main
+```
+
+> **v7.10+ candidate:** automate detection by reading a `post_migrate_dev: [...]` hook list from `.autopilot/stack.md` and failing Step 5 if schema changes are detected but no type-generation hook is configured. Today this is advisory — operator responsibility.
+
+**Dev database drift** — `/migrate --env=dev` applies schema changes to dev BEFORE the PR is merged. If the PR is later rejected, substantially changed, or abandoned, dev will contain unmerged schema. Mitigations:
+
+- **Preferred:** target an isolated/ephemeral dev database per branch (per-PR Supabase project, Postgres schema namespace, or local container).
+- **Shared dev DB fallback:** before running Step 5, capture the current migration_state head; on PR abandonment, run a corrective migration that brings dev back to that head. Document the policy in `.autopilot/stack.md` so the team knows the cleanup contract.
+
+If migration fails:
+- **Before retrying:** confirm the dev migration rolled back cleanly. Some migration tools leave partial state on failure (non-transactional DDL, drift in migration_state table). If partial state exists, reset the dev database to the pre-migration baseline OR write a corrective migration that brings dev back to a known state.
+- Fix the SQL
+- Re-run Step 4 (validate) against the corrected code
+- Re-run Step 5 (migrate dev)
+- Max 3 retry iterations
+
+**For prod-safety policy**, projects should set in `.autopilot/stack.md`:
+
+```yaml
+migrate:
+  skill: <your-skill>@1
+  policy:
+    require_dry_run_first: true       # always preview before apply
+    require_manual_approval: true     # CI gates prod on human approval
+    require_clean_git: true           # never apply against dirty tree
+```
+
+As of v7.9.1, the valid keys per `presets/schemas/migrate.schema.json` are: `allow_prod_in_ci`, `require_clean_git`, `require_manual_approval`, `require_dry_run_first`. If the schema changes in a future release, that file is the source of truth.
+
+These keys are **declarative policy inputs**, not autopilot enforcement. Your CI/CD pipeline must explicitly invoke a migrate runner that reads `.autopilot/stack.md` AND enforces equivalent checks (e.g. require-clean-git, dry-run-before-apply, manual-approval-for-prod). Setting them in stack.md alone does not protect production unless your pipeline reads them.
+
+**Minimum CI/CD migrate-runner contract** (fail closed on all of these):
+
+1. Refuse to apply if `.autopilot/stack.md` cannot be read or parsed.
+2. Refuse to apply if the policy block contains unknown keys (schema-validate against `presets/schemas/migrate.schema.json`).
+3. If `require_dry_run_first: true`: refuse apply without a matching dry-run artifact for the current git head + target env.
+4. If `require_manual_approval: true` and `env != dev`: require an explicit human approval signal (CI approval gate, signed commit, etc.) before apply.
+5. If `require_clean_git: true`: refuse to apply against a dirty working tree (untracked or unstaged changes). This is intentionally limited to working-tree cleanliness — commit topology (squash vs rebase vs merge vs tag) is a separate concern not enforced by this key.
+6. If `allow_prod_in_ci: false` (the default): refuse prod apply from any CI context. **Note:** teams whose intended prod migration path is CI/CD with manual approval must explicitly set `allow_prod_in_ci: true` alongside `require_manual_approval: true` and `require_dry_run_first: true`. `allow_prod_in_ci: false` is for manual/operator-run production migration workflows only.
+7. On any policy-read or schema-validation failure, exit non-zero and surface the specific check that failed.
 
 ### Step 6: Push + create PR
 
@@ -257,6 +320,7 @@ npx tsx scripts/codex-pr-review.ts <pr-number>
 Posts Codex review as a GitHub PR comment. **This serves as the second risk-tiered pass for medium-risk specs and the third pass for high-risk specs.** Remediate CRITICAL findings:
 - Fix on the branch
 - Push
+- **Before consuming a re-review iteration, compute the failure fingerprint** with `computeFingerprint({ phase: 'codex-review', errorType: 'codex_critical', errorLocation, errorMessage })` from `src/core/run-state/sameness-detector.ts`. For `errorLocation` prefer a stable composite — `${normalized-title}::${repo-relative-path}` — over the transport-level finding ID (Codex regenerates finding IDs on each review run, so the raw ID is not stable). For `errorMessage` use the first sentence of the finding body, stripping any per-run identifiers (run-id, timestamps, file SHAs). Append to an in-memory list for this retry loop and call `shouldEscalate(history)`. If `escalate === true` — the same critical finding fired twice after a remediation attempt — STOP and surface to the user. Do not consume another re-review.
 - Re-run Codex review
 - Max 2 iterations
 
@@ -271,6 +335,7 @@ npx tsx scripts/bugbot.ts --pr <pr-number>
 Triages each finding (real bug vs false positive), auto-fixes real bugs, dismisses false positives with GitHub replies. If fixes applied:
 - Push
 - Wait for new bugbot comments (30s)
+- **Before consuming a bugbot retry, compute the failure fingerprint** with `computeFingerprint({ phase: 'bugbot', errorType: <'bugbot_high' | 'bugbot_medium'>, errorLocation, errorMessage })` from `src/core/run-state/sameness-detector.ts`. For `errorLocation` prefer the stable `<repo-relative-path>:<line>` rather than the GitHub comment ID — Cursor reposts findings with fresh comment IDs after each push, so comment ID is not stable across retries. The comment ID can be surfaced as metadata for human inspection but should not enter the hash. For `errorMessage` use the first 200 chars of the finding body. Append to an in-memory list for this retry loop and call `shouldEscalate(history)`. If `escalate === true` — a "fixed" finding re-fired identically — STOP and surface the fingerprint to the user. Do not consume another round.
 - Re-run /bugbot
 - Max 3 rounds
 
@@ -284,15 +349,44 @@ Tell the user:
 - Bugbot triage summary (fixed / dismissed / needs-human)
 - Any human-required items that couldn't be auto-resolved
 
+## Retry-loop sameness detector (Steps 4, 7, 8)
+
+As of v7.10.0, the three retry loops (Step 4 validate, Step 7 Codex PR review, Step 8 bugbot) MUST consult `src/core/run-state/sameness-detector.ts` before consuming a retry. The pipeline halts when retries make no progress — even if you have retries remaining.
+
+**The detector is consumed by the autopilot skill agent itself** (the LLM following this skill), not by the underlying `scripts/validate.ts` / `scripts/codex-pr-review.ts` / `scripts/bugbot.ts` CLI scripts. Those scripts are stateless per-invocation; the retry loop with its history lives inside this skill execution scope. That is why the integration is in this document and not in the CLI source.
+
+```ts
+// Public package import (uses the subpath export added in v7.10.0):
+import {
+  computeFingerprint,
+  shouldEscalate,
+} from '@delegance/claude-autopilot/run-state/sameness-detector';
+
+// Or from a local checkout:
+import { computeFingerprint, shouldEscalate } from './src/core/run-state/sameness-detector.ts';
+```
+
+How to use inside each retry loop:
+
+1. On a FAIL, derive `{ phase, errorType, errorLocation, errorMessage }` for the most salient blocker.
+2. `const fp = computeFingerprint({...})`.
+3. Append `fp` to an in-memory list for THIS retry loop (no cross-loop state — bugbot and validate keep separate histories).
+4. `const decision = shouldEscalate(history)` — if `decision.escalate === true`, STOP. Surface `decision.fingerprint` and `decision.reason` to the user. Do not consume another retry attempt even if the per-loop max isn't reached.
+5. Otherwise apply the fix, run again.
+
+Persistence is in-memory only in v7.10.0. The v6 run-state events.ndjson integration is tracked as issue #180.
+
 ## Error Recovery
 
 - **Preflight failure:** Surface the specific check, exit. Do not partially run.
 - **Missing skill/credential:** Exit with install/auth hint.
 - **Subagent failure:** Re-dispatch with more context or implement directly.
-- **Migration failure:** Fix SQL, re-run `/migrate`.
-- **Validate failure:** Fix issues, re-run (max 3 retries).
-- **Codex CRITICAL findings:** REMEDIATE (apply fix), push, re-review (max 2 retries). Do NOT continue past unremediated CRITICALs.
-- **Bugbot findings:** `/bugbot` handles triage + fix automatically (max 3 rounds).
+- **Migration failure (Step 5 — dev only):** Fix SQL, re-run Step 4 (validate) against corrected code, then re-run Step 5 (migrate dev). Prod stays untouched. Max 3 retries.
+- **Prod migration:** Out of scope for autopilot. Handed off to user's CI/CD pipeline via `migrate.policy` (require_manual_approval, require_dry_run_first).
+- **Validate failure:** Fix issues, re-run (max 3 retries, sameness-detector may halt earlier).
+- **Codex CRITICAL findings:** REMEDIATE (apply fix), push, re-review (max 2 retries, sameness-detector may halt earlier). Do NOT continue past unremediated CRITICALs.
+- **Bugbot findings:** `/bugbot` handles triage + fix automatically (max 3 rounds, sameness-detector may halt earlier).
+- **Sameness detector halt:** The same failure fingerprint fired in two consecutive retry attempts — the loop is not making progress. Stop, surface the fingerprint, ask the human to inspect.
 - **External hard-block** (TCC, network, etc.): Stop, report what was completed, surface the blocker.
 
 ## When NOT to use