@gajae-code/coding-agent 0.8.1 → 0.9.0

package/src/extensibility/gjc-plugins/runtime-adapters.ts

@@ -1,14 +1,161 @@
+import { createHash } from "node:crypto";
+import * as fs from "node:fs/promises";
 import * as path from "node:path";
 import { loadCustomTools } from "../custom-tools/loader";
 import type { CustomTool } from "../custom-tools/types";
-import { loadEffectiveGjcPluginRegistry } from "./registry";
-import { type SessionQuarantine, validateSessionBundles, verifyEntryHashes } from "./session-validation";
+import { loadEffectiveGjcPluginRegistry, registryPathForScope } from "./registry";
+import { type SessionQuarantine, type SessionValidationResult, validateSessionBundles } from "./session-validation";
+import type { GjcPluginRegistryEntry, GjcPluginScope } from "./types";
 
 export interface AlwaysOnPluginTools {
 	tools: CustomTool[];
 	quarantine: SessionQuarantine[];
 }
 
+interface FileSnapshot {
+	path: string;
+	mtimeMs: number;
+	ctimeMs: number;
+	size: number;
+	ino: number;
+}
+
+interface ValidatedPluginRegistry {
+	effective: GjcPluginRegistryEntry[];
+	active: GjcPluginRegistryEntry[];
+	quarantine: SessionQuarantine[];
+	validation: SessionValidationResult;
+	registryFiles: FileSnapshot[];
+	pluginFiles: FileSnapshot[];
+}
+
+interface CachedValidatedPluginRegistry extends ValidatedPluginRegistry {
+	registryKey: string;
+	pluginKey: string;
+}
+
+const validatedRegistryCache = new Map<string, CachedValidatedPluginRegistry>();
+const hashCache = new Map<string, string>();
+// Bound the digest memo so long sessions with plugin churn cannot grow it
+// unboundedly; entries are re-derivable from disk at the cost of one read.
+const HASH_CACHE_MAX_ENTRIES = 512;
+const registryScopes: GjcPluginScope[] = ["user", "project"];
+
+async function snapshotExistingFile(filePath: string): Promise<FileSnapshot | null> {
+	try {
+		const stat = await fs.stat(filePath);
+		return { path: filePath, mtimeMs: stat.mtimeMs, ctimeMs: stat.ctimeMs, size: stat.size, ino: stat.ino };
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException)?.code === "ENOENT") return null;
+		throw error;
+	}
+}
+
+function snapshotsKey(snapshots: readonly FileSnapshot[]): string {
+	return snapshots.map(s => `${s.path}:${s.mtimeMs}:${s.ctimeMs}:${s.size}:${s.ino}`).join("|");
+}
+
+async function snapshotRegistryFiles(cwd: string): Promise<FileSnapshot[]> {
+	const snapshots = await Promise.all(
+		registryScopes.map(scope => snapshotExistingFile(registryPathForScope(scope, cwd))),
+	);
+	return snapshots.filter((s): s is FileSnapshot => s !== null);
+}
+
+async function snapshotPluginFiles(entries: readonly GjcPluginRegistryEntry[]): Promise<FileSnapshot[]> {
+	const snapshots: FileSnapshot[] = [];
+	for (const entry of entries) {
+		if (!entry.enabled) continue;
+		for (const file of entry.copiedFiles) {
+			const abs = path.join(entry.pluginRoot, file.relativePath);
+			const snapshot = await snapshotExistingFile(abs);
+			if (!snapshot) {
+				snapshots.push({ path: abs, mtimeMs: Number.NaN, ctimeMs: Number.NaN, size: Number.NaN, ino: Number.NaN });
+			} else {
+				snapshots.push(snapshot);
+			}
+		}
+	}
+	return snapshots;
+}
+
+function sha256(buf: Buffer): string {
+	return createHash("sha256").update(buf).digest("hex");
+}
+
+async function hashFile(snapshot: FileSnapshot): Promise<string> {
+	const key = `${snapshot.path}:${snapshot.mtimeMs}:${snapshot.ctimeMs}:${snapshot.size}:${snapshot.ino}`;
+	const cached = hashCache.get(key);
+	if (cached) return cached;
+	const digest = sha256(await fs.readFile(snapshot.path));
+	if (hashCache.size >= HASH_CACHE_MAX_ENTRIES) {
+		// FIFO eviction is sufficient: the memo only avoids re-reads within a
+		// session; correctness never depends on a hit.
+		const oldest = hashCache.keys().next().value;
+		if (oldest !== undefined) hashCache.delete(oldest);
+	}
+	hashCache.set(key, digest);
+	return digest;
+}
+
+async function verifyEntryHashesCached(entry: GjcPluginRegistryEntry): Promise<SessionQuarantine | null> {
+	for (const file of entry.copiedFiles) {
+		const abs = path.join(entry.pluginRoot, file.relativePath);
+		const snapshot = await snapshotExistingFile(abs);
+		if (!snapshot) {
+			return {
+				plugin: entry.name,
+				surfaceId: `plugin:${entry.name}`,
+				code: "runtime_mismatch",
+				message: `Installed file missing: ${file.relativePath}`,
+			};
+		}
+		if ((await hashFile(snapshot)) !== file.sha256) {
+			return {
+				plugin: entry.name,
+				surfaceId: `plugin:${entry.name}`,
+				code: "runtime_mismatch",
+				message: `Installed file hash drift: ${file.relativePath}`,
+			};
+		}
+	}
+	return null;
+}
+
+async function loadValidatedPluginRegistry(cwd: string): Promise<ValidatedPluginRegistry> {
+	const registryFiles = await snapshotRegistryFiles(cwd);
+	const registryKey = snapshotsKey(registryFiles);
+	const cached = validatedRegistryCache.get(cwd);
+	if (cached && cached.registryKey === registryKey) {
+		const pluginFiles = await snapshotPluginFiles(cached.effective);
+		const pluginKey = snapshotsKey(pluginFiles);
+		if (cached.pluginKey === pluginKey) return cached;
+	}
+
+	const effective = await loadEffectiveGjcPluginRegistry(cwd);
+	const currentRegistryFiles = await snapshotRegistryFiles(cwd);
+	const preQuarantine: SessionQuarantine[] = [];
+	for (const entry of effective) {
+		if (!entry.enabled) continue;
+		const drift = await verifyEntryHashesCached(entry);
+		if (drift) preQuarantine.push(drift);
+	}
+	const validation = validateSessionBundles(effective, {}, preQuarantine);
+	const pluginFiles = await snapshotPluginFiles(effective);
+	const next: CachedValidatedPluginRegistry = {
+		effective,
+		active: validation.active,
+		quarantine: validation.quarantine,
+		validation,
+		registryFiles: currentRegistryFiles,
+		pluginFiles,
+		registryKey: snapshotsKey(currentRegistryFiles),
+		pluginKey: snapshotsKey(pluginFiles),
+	};
+	validatedRegistryCache.set(cwd, next);
+	return next;
+}
+
 /**
  * Load the always-on plugin tool surfaces for the effective registry at `cwd`.
  *
@@ -26,22 +173,15 @@ export async function loadAlwaysOnPluginTools(input: {
 	cwd: string;
 	reservedToolNames: string[];
 }): Promise<AlwaysOnPluginTools> {
-	const effective = await loadEffectiveGjcPluginRegistry(input.cwd);
+	const validated = await loadValidatedPluginRegistry(input.cwd);
+	const { effective } = validated;
 	if (effective.length === 0) return { tools: [], quarantine: [] };
 
-	// Hash-drift quarantine before importing any plugin code.
-	const preQuarantine: SessionQuarantine[] = [];
-	for (const entry of effective) {
-		if (!entry.enabled) continue;
-		const drift = await verifyEntryHashes(entry);
-		if (drift) preQuarantine.push(drift);
-	}
-
 	const reserved = new Set(input.reservedToolNames);
 	const { active, quarantine } = validateSessionBundles(
 		effective,
 		{ toolNames: input.reservedToolNames },
-		preQuarantine,
+		validated.quarantine,
 	);
 
 	// Map declared (path -> name) for every active always-on tool surface.
@@ -109,15 +249,8 @@ export async function loadAlwaysOnPluginTools(input: {
  * plugins are installed/enabled. Safe to call unconditionally at session start.
  */
 export async function renderAlwaysOnSystemAppendices(input: { cwd: string }): Promise<string> {
-	const effective = await loadEffectiveGjcPluginRegistry(input.cwd);
+	const { effective, active } = await loadValidatedPluginRegistry(input.cwd);
 	if (effective.length === 0) return "";
-	const preQuarantine: SessionQuarantine[] = [];
-	for (const entry of effective) {
-		if (!entry.enabled) continue;
-		const drift = await verifyEntryHashes(entry);
-		if (drift) preQuarantine.push(drift);
-	}
-	const { active } = validateSessionBundles(effective, {}, preQuarantine);
 	const { renderPluginAppendices } = await import("./prompt-appendix");
 	return (await renderPluginAppendices(active)).system;
 }
@@ -131,15 +264,8 @@ export async function renderAgentPromptAdditions(input: {
 	cwd: string;
 	agentName: string;
 }): Promise<{ appendix: string; advertisement: string }> {
-	const effective = await loadEffectiveGjcPluginRegistry(input.cwd);
+	const { effective, active } = await loadValidatedPluginRegistry(input.cwd);
 	if (effective.length === 0) return { appendix: "", advertisement: "" };
-	const preQuarantine: SessionQuarantine[] = [];
-	for (const entry of effective) {
-		if (!entry.enabled) continue;
-		const drift = await verifyEntryHashes(entry);
-		if (drift) preQuarantine.push(drift);
-	}
-	const { active } = validateSessionBundles(effective, {}, preQuarantine);
 	const { renderPluginAppendices } = await import("./prompt-appendix");
 	const { buildAgentSubskillAdvertisement } = await import("./injection");
 	const rendered = await renderPluginAppendices(active);
@@ -158,15 +284,8 @@ export async function renderSkillAdvertisement(input: {
 	skillName: string;
 	phase?: string;
 }): Promise<string> {
-	const effective = await loadEffectiveGjcPluginRegistry(input.cwd);
+	const { effective, active } = await loadValidatedPluginRegistry(input.cwd);
 	if (effective.length === 0) return "";
-	const preQuarantine: SessionQuarantine[] = [];
-	for (const entry of effective) {
-		if (!entry.enabled) continue;
-		const drift = await verifyEntryHashes(entry);
-		if (drift) preQuarantine.push(drift);
-	}
-	const { active } = validateSessionBundles(effective, {}, preQuarantine);
 	const { buildSubskillAdvertisement } = await import("./injection");
 	return buildSubskillAdvertisement(active, input.skillName, input.phase);
 }
@@ -181,15 +300,8 @@ export async function buildPluginMcpConfigs(input: { cwd: string }): Promise<{
 	configs: Record<string, any>;
 	quarantine: SessionQuarantine[];
 }> {
-	const effective = await loadEffectiveGjcPluginRegistry(input.cwd);
+	const { effective, active, quarantine } = await loadValidatedPluginRegistry(input.cwd);
 	if (effective.length === 0) return { configs: {}, quarantine: [] };
-	const preQuarantine: SessionQuarantine[] = [];
-	for (const entry of effective) {
-		if (!entry.enabled) continue;
-		const drift = await verifyEntryHashes(entry);
-		if (drift) preQuarantine.push(drift);
-	}
-	const { active, quarantine } = validateSessionBundles(effective, {}, preQuarantine);
 	const { assertMcpInstallPolicy, assertDnsResolvesPublic, assertUrlAllowed } = await import("./mcp-policy");
 	const nodePath = await import("node:path");
 

package/src/gjc-runtime/deep-interview-ambiguity.ts

@@ -0,0 +1,206 @@
+import {
+	type DeepInterviewEstablishedFact,
+	type DeepInterviewRoundRecord,
+	type DeepInterviewStateEnvelope,
+	normalizeDeepInterviewEnvelope,
+} from "./deep-interview-state";
+
+/**
+ * Deterministic ambiguity floor for deep-interview.
+ *
+ * The interview's ambiguity score is reported by an LLM scorer, which anchors on
+ * prior scores and under-reports rises when the user pivots or contradicts earlier
+ * answers. Following the Ouroboros `max(llm_score, deterministic_floor(ledger))`
+ * principle, this pure leaf module computes a code-level lower bound from evidence
+ * already persisted in deep-interview state, so the reported score can never fall
+ * below what code can objectively measure:
+ *
+ * - `0.10` per established fact marked disputed with no `superseded_by` resolution
+ *   (contradiction pressure — a pivot keeps ambiguity elevated until resolved);
+ * - `0.05` per active topology component whose goal/constraints/criteria clarity
+ *   is still unscored (gap pressure — a sibling component cannot hide);
+ * - `0.05 × (auto-answered rounds / scored rounds)` (assumption dilution).
+ *
+ * Like `deep-interview-state`, this module MUST stay pure and dependency-free
+ * (no filesystem, no state-writer, no CLI runtime) so every writer can apply it.
+ */
+
+// =============================================================================
+// Weights (mirrors the Ouroboros deterministic_floor coefficients)
+// =============================================================================
+
+const DISPUTED_FACT_WEIGHT = 0.1;
+const UNSCORED_COMPONENT_WEIGHT = 0.05;
+const AUTO_ANSWER_DILUTION_WEIGHT = 0.05;
+
+const CORE_CLARITY_DIMENSIONS = ["goal", "constraints", "criteria"] as const;
+
+export interface AmbiguityFloorBreakdown {
+	floor: number;
+	disputed_fact_count: number;
+	unscored_active_component_count: number;
+	auto_answer_ratio: number;
+}
+
+export interface AmbiguityClampResult {
+	effective: number;
+	clamped: boolean;
+}
+
+// =============================================================================
+// Pure helpers
+// =============================================================================
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+	return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
+function asArray(value: unknown): unknown[] {
+	return Array.isArray(value) ? value : [];
+}
+
+function round2(value: number): number {
+	return Math.round(value * 100) / 100;
+}
+
+/** A disputed fact contributes pressure until it is resolved via `superseded_by` or re-confirmation. */
+function isUnresolvedDisputedFact(value: unknown): boolean {
+	if (!isPlainObject(value)) return false;
+	const fact = value as Partial<DeepInterviewEstablishedFact>;
+	if (fact.disputed !== true) return false;
+	return typeof fact.superseded_by !== "string" || fact.superseded_by.trim() === "";
+}
+
+/**
+ * An active component is unscored while any core clarity dimension lacks a finite
+ * numeric score. Deferred components are excluded (they are outside ambiguity math),
+ * and the gate only arms once the topology was explicitly confirmed in Round 0.
+ */
+function countUnscoredActiveComponents(topology: unknown): number {
+	if (!isPlainObject(topology) || topology.status !== "confirmed") return 0;
+	let unscored = 0;
+	for (const component of asArray(topology.components)) {
+		if (!isPlainObject(component) || component.status === "deferred") continue;
+		const clarity = isPlainObject(component.clarity_scores) ? component.clarity_scores : {};
+		const incomplete = CORE_CLARITY_DIMENSIONS.some(dimension => {
+			const score = clarity[dimension];
+			return typeof score !== "number" || !Number.isFinite(score);
+		});
+		if (incomplete) unscored += 1;
+	}
+	return unscored;
+}
+
+function autoAnswerRatio(inner: Record<string, unknown>): number {
+	const autoAnswered = asArray(inner.auto_answered_rounds).length;
+	if (autoAnswered === 0) return 0;
+	const scored = asArray(inner.rounds).filter(round => isPlainObject(round) && round.lifecycle === "scored").length;
+	return Math.min(1, autoAnswered / Math.max(scored, 1));
+}
+
+// =============================================================================
+// Floor computation + clamping
+// =============================================================================
+
+/** Compute the deterministic floor from the inner deep-interview `state` object. */
+export function computeAmbiguityFloor(inner: unknown): AmbiguityFloorBreakdown {
+	const state = isPlainObject(inner) ? inner : {};
+	const disputedFactCount = asArray(state.established_facts).filter(isUnresolvedDisputedFact).length;
+	const unscoredActiveComponentCount = countUnscoredActiveComponents(state.topology);
+	const ratio = autoAnswerRatio(state);
+	const floor =
+		DISPUTED_FACT_WEIGHT * disputedFactCount +
+		UNSCORED_COMPONENT_WEIGHT * unscoredActiveComponentCount +
+		AUTO_ANSWER_DILUTION_WEIGHT * ratio;
+	return {
+		floor: round2(Math.min(1, Math.max(0, floor))),
+		disputed_fact_count: disputedFactCount,
+		unscored_active_component_count: unscoredActiveComponentCount,
+		auto_answer_ratio: round2(ratio),
+	};
+}
+
+/** Clamp an LLM-reported ambiguity to the deterministic floor: `max(reported, floor)`. */
+export function clampReportedAmbiguity(reported: number, floor: number): AmbiguityClampResult {
+	const bounded = Math.min(1, Math.max(0, reported));
+	if (floor > bounded) return { effective: Math.min(1, floor), clamped: true };
+	return { effective: bounded, clamped: false };
+}
+
+/**
+ * Mark every established fact recorded in `retractedRound` as disputed. This is the
+ * mechanical contradiction signal for answer retraction: when the user replaces an
+ * already-scored answer (A -> B pivot), the facts that answer established can no
+ * longer be trusted, so they raise the floor until re-confirmed or superseded.
+ * Returns new arrays/objects; never mutates the input.
+ */
+export function disputeFactsFromRetractedRound(
+	facts: readonly unknown[],
+	retractedRound: number,
+): { facts: Record<string, unknown>[]; disputedIds: string[] } {
+	const disputedIds: string[] = [];
+	const next = facts.filter(isPlainObject).map(fact => {
+		const record = fact as Record<string, unknown>;
+		if (record.round !== retractedRound || record.disputed === true) return { ...record };
+		if (typeof record.superseded_by === "string" && record.superseded_by.trim() !== "") return { ...record };
+		if (typeof record.id === "string") disputedIds.push(record.id);
+		return { ...record, disputed: true };
+	});
+	return { facts: next, disputedIds };
+}
+
+export interface AppliedAmbiguityFloor {
+	envelope: DeepInterviewStateEnvelope;
+	breakdown: AmbiguityFloorBreakdown;
+	clamped: boolean;
+}
+
+/**
+ * Enforce the floor invariant on a full deep-interview envelope: recompute the floor
+ * from persisted evidence, clamp `state.current_ambiguity`, and clamp the latest
+ * scored round (preserving the original value as `reported_ambiguity` for audit).
+ * Historical rounds are never rewritten. Idempotent and non-mutating; every writer
+ * (state CLI write/reconcile, recorder) applies this immediately before persisting.
+ */
+export function applyAmbiguityFloorToEnvelope(value: unknown): AppliedAmbiguityFloor {
+	const envelope = normalizeDeepInterviewEnvelope(value);
+	const inner = { ...(envelope.state as Record<string, unknown>) };
+	const breakdown = computeAmbiguityFloor(inner);
+	let clamped = false;
+
+	const rounds = asArray(inner.rounds).filter(isPlainObject) as unknown as DeepInterviewRoundRecord[];
+	let latestScoredIndex = -1;
+	for (let index = 0; index < rounds.length; index += 1) {
+		const candidate = rounds[index];
+		if (candidate.lifecycle !== "scored" || !Number.isFinite(candidate.round)) continue;
+		if (latestScoredIndex < 0 || candidate.round >= rounds[latestScoredIndex].round) latestScoredIndex = index;
+	}
+	if (latestScoredIndex >= 0) {
+		const latest = rounds[latestScoredIndex];
+		if (typeof latest.ambiguity === "number") {
+			const clampedRound = clampReportedAmbiguity(latest.ambiguity, breakdown.floor);
+			if (clampedRound.clamped) {
+				const nextRounds = [...rounds];
+				nextRounds[latestScoredIndex] = {
+					...latest,
+					reported_ambiguity: latest.reported_ambiguity ?? latest.ambiguity,
+					ambiguity: clampedRound.effective,
+					ambiguity_floor: breakdown.floor,
+				};
+				inner.rounds = nextRounds;
+				clamped = true;
+			}
+		}
+	}
+
+	if (typeof inner.current_ambiguity === "number") {
+		const clampedCurrent = clampReportedAmbiguity(inner.current_ambiguity, breakdown.floor);
+		if (clampedCurrent.clamped) {
+			inner.current_ambiguity = clampedCurrent.effective;
+			clamped = true;
+		}
+	}
+
+	inner.ambiguity_floor = breakdown;
+	return { envelope: { ...envelope, state: inner }, breakdown, clamped };
+}

package/src/gjc-runtime/deep-interview-recorder.ts

@@ -1,6 +1,11 @@
 import { syncSkillActiveState } from "../skill-state/active-state";
 import { deriveDeepInterviewHud } from "../skill-state/workflow-hud";
 import { WORKFLOW_STATE_VERSION } from "../skill-state/workflow-state-contract";
+import {
+	clampReportedAmbiguity,
+	computeAmbiguityFloor,
+	disputeFactsFromRetractedRound,
+} from "./deep-interview-ambiguity";
 import {
 	answerHash,
 	type DeepInterviewEstablishedFact,
@@ -14,6 +19,7 @@ import {
 import { writeSessionActivityMarker } from "./session-resolution";
 import { readExistingStateForMutation, writeGuardedWorkflowEnvelopeAtomic } from "./state-writer";
 
+export * from "./deep-interview-ambiguity";
 export * from "./deep-interview-state";
 
 /**
@@ -395,30 +401,55 @@ export async function syncDeepInterviewRecorderHud(
 	await syncRecorderHud(cwd, normalizeDeepInterviewEnvelope(read.value), sessionId);
 }
 
-/** Record an `answered` shell for one round (append-or-merge by durable key). */
+/**
+ * Record an `answered` shell for one round (append-or-merge by durable key).
+ *
+ * Retraction dynamics: replacing an already-`scored` answer is a mechanical
+ * contradiction signal (the user pivoted). The facts that round established are
+ * marked disputed, which raises the deterministic ambiguity floor immediately —
+ * without waiting for the LLM scorer to self-report a trigger.
+ */
 export async function appendOrMergeDeepInterviewRound(
 	cwd: string,
 	statePath: string,
 	input: DeepInterviewAnswerInput,
 	options: { sessionId?: string } = {},
-): Promise<{ action: AppendOrMergeAction; record: DeepInterviewRoundRecord }> {
+): Promise<{ action: AppendOrMergeAction; record: DeepInterviewRoundRecord; disputedFactIds?: string[] }> {
 	const envelope = await readEnvelope(statePath);
 	const interviewId = input.interviewId ?? interviewIdOf(envelope);
 	const shell = buildAnswerShell({ ...input, interviewId });
 	const rounds = readRounds(envelope);
+	const priorRecord = rounds.find(r => r.round_key === shell.round_key);
 	const result = appendOrMergeRound(rounds, shell);
 	if (result.action === "noop") {
 		await repairRecorderHudFromPersisted(cwd, statePath, options.sessionId);
 		return { action: result.action, record: result.record };
 	}
-	(envelope.state as Record<string, unknown>).rounds = result.rounds;
+	const inner = envelope.state as Record<string, unknown>;
+	inner.rounds = result.rounds;
+	let disputedFactIds: string[] | undefined;
+	if (result.action === "replaced" && priorRecord?.lifecycle === "scored") {
+		const facts = Array.isArray(inner.established_facts) ? inner.established_facts : [];
+		const disputed = disputeFactsFromRetractedRound(facts, shell.round);
+		if (disputed.disputedIds.length > 0) {
+			inner.established_facts = disputed.facts;
+			disputedFactIds = disputed.disputedIds;
+			// Surface the rise right away: the retraction changed the evidence, so the
+			// gating score must reflect the new floor before the next scoring pass.
+			const breakdown = computeAmbiguityFloor(inner);
+			inner.ambiguity_floor = breakdown;
+			if (typeof inner.current_ambiguity === "number") {
+				inner.current_ambiguity = clampReportedAmbiguity(inner.current_ambiguity, breakdown.floor).effective;
+			}
+		}
+	}
 	await persistEnvelope(cwd, statePath, envelope, options.sessionId, "gjc deep-interview record-answer");
 	try {
 		await syncRecorderHud(cwd, envelope, options.sessionId);
 	} catch {
 		// HUD sync is best-effort cache maintenance and must not change record semantics.
 	}
-	return { action: result.action, record: result.record };
+	return { action: result.action, record: result.record, disputedFactIds };
 }
 
 /**
@@ -459,12 +490,34 @@ export async function enrichDeepInterviewRoundScoring(
 	const envelope = await readEnvelope(statePath);
 	const interviewId = input.interviewId ?? interviewIdOf(envelope);
 	const rounds = readRounds(envelope);
-	const { rounds: nextRounds, record } = enrichRoundWithScoring(rounds, { ...input, interviewId });
+	const { rounds: enrichedRounds, record: reportedRecord } = enrichRoundWithScoring(rounds, {
+		...input,
+		interviewId,
+	});
+	// Deterministic floor (Ouroboros principle): the LLM-reported ambiguity is only a
+	// lower-bound input. Evidence persisted in state — unresolved disputed facts,
+	// unscored active components, auto-answer dilution — sets a code-computed floor
+	// the reported score can never fall under, so a pivot mechanically raises the
+	// gating score even when the scorer omits triggers.
+	const inner = envelope.state as Record<string, unknown>;
+	const breakdown = computeAmbiguityFloor({ ...inner, rounds: enrichedRounds });
+	const clampResult = clampReportedAmbiguity(input.ambiguity, breakdown.floor);
+	let record = reportedRecord;
+	let nextRounds = enrichedRounds;
+	if (clampResult.clamped) {
+		record = {
+			...reportedRecord,
+			ambiguity: clampResult.effective,
+			reported_ambiguity: input.ambiguity,
+			ambiguity_floor: breakdown.floor,
+		};
+		nextRounds = enrichedRounds.map(item => (item.round_key === record.round_key ? record : item));
+	}
 	// Fail closed: a scored transition that violates the bidirectional invariant
 	// (an active trigger that improves the affected dimension or fails to raise
 	// overall ambiguity, or a disputed/unresolved trigger lacking a rationale) must
 	// never be persisted — storing it lets the interview falsely converge. Validate
-	// against the most recent prior scored round before writing any durable state.
+	// the effective (floor-clamped) record against the most recent prior scored round.
 	const prior = latestPriorScoredRound(rounds, record.round_key, record.round);
 	const validation = validateDeepInterviewScoredTransition(prior, record);
 	if (!validation.ok) {
@@ -472,8 +525,9 @@ export async function enrichDeepInterviewRoundScoring(
 			`deep-interview scored transition for round ${record.round} is invalid and was refused: ${validation.violations.join("; ")}`,
 		);
 	}
-	(envelope.state as Record<string, unknown>).rounds = nextRounds;
-	(envelope.state as Record<string, unknown>).current_ambiguity = input.ambiguity;
+	inner.rounds = nextRounds;
+	inner.current_ambiguity = clampResult.effective;
+	inner.ambiguity_floor = breakdown;
 	await persistEnvelope(cwd, statePath, envelope, options.sessionId, "gjc deep-interview score-round");
 	await syncRecorderHud(cwd, envelope, options.sessionId);
 	return { record };