@gajae-code/coding-agent 0.8.0 → 0.8.2

package/src/config/file-lock.ts

@@ -1,3 +1,4 @@
+import type { Stats } from "node:fs";
 import * as fs from "node:fs/promises";
 import { isEnoent } from "@gajae-code/utils/fs-error";
 
@@ -22,9 +23,10 @@ function getLockPath(filePath: string): string {
 	return `${filePath}.lock`;
 }
 
-async function writeLockInfo(lockPath: string): Promise<void> {
+async function writeLockInfo(lockPath: string): Promise<LockInfo> {
 	const info: LockInfo = { pid: process.pid, timestamp: Date.now() };
 	await Bun.write(`${lockPath}/info`, JSON.stringify(info));
+	return info;
 }
 
 async function readLockInfo(lockPath: string): Promise<LockInfo | null> {
@@ -51,17 +53,30 @@ export interface FileLockOwnerToken {
 	timestamp: number;
 }
 
-/** Outcome of a guarded GC removal attempt (`removeFileLockDirForGc`). */
+/** Outcome of a guarded lock-dir removal attempt (`removeFileLockDirForGc`). */
 export type FileLockGcRemoval = "removed" | "owner_changed" | "missing";
 
+interface LockDirStatToken {
+	dev: number;
+	ino: number;
+	mtimeMs: number;
+	ctimeMs: number;
+}
+
+type LockStaleSnapshot =
+	| { stale: false }
+	| { stale: true; owner: FileLockOwnerToken }
+	| { stale: true; owner: null; stat: LockDirStatToken };
+
 /**
  * @internal
- * Fail-closed removal of a dead lock dir for GC. Re-reads the on-disk owner
- * token as close to the unlink as possible and only deletes the dir when it
- * STILL holds the exact `{pid, timestamp}` identity the caller observed dead.
+ * Fail-closed removal of a lock dir whose owner is expected to be dead or
+ * finished. Re-reads the on-disk owner token as close to the unlink as possible
+ * and only deletes the dir when it STILL holds the exact `{pid, timestamp}`
+ * identity the caller observed.
  *
- * Closes the prune-time TOCTOU window (#606): between GC's dead re-read/probe
- * and the unlink, a live process can reclaim a stale lock at the same path
+ * Closes stale-cleanup TOCTOU windows (#606): between a dead/stale re-read and
+ * the unlink, a live process can reclaim a stale lock at the same path
  * (`acquireLock` rms the stale dir, then re-`mkdir`s and rewrites `info` with a
  * fresh pid+timestamp). Deleting by path alone would reap that LIVE lock. Any
  * mismatch (`owner_changed`) or absent/unreadable info (`missing` — e.g. a
@@ -99,14 +114,28 @@ function ownerLiveness(pid: number): OwnerLiveness {
 	}
 }
 
-async function isLockStale(lockPath: string, staleMs: number): Promise<boolean> {
+function statToken(stats: Stats): LockDirStatToken {
+	return {
+		dev: stats.dev,
+		ino: stats.ino,
+		mtimeMs: stats.mtimeMs,
+		ctimeMs: stats.ctimeMs,
+	};
+}
+
+function sameStatToken(a: LockDirStatToken, b: LockDirStatToken): boolean {
+	return a.dev === b.dev && a.ino === b.ino && a.mtimeMs === b.mtimeMs && a.ctimeMs === b.ctimeMs;
+}
+
+async function staleLockSnapshot(lockPath: string, staleMs: number): Promise<LockStaleSnapshot> {
 	const info = await readLockInfo(lockPath);
 	if (!info) {
 		try {
 			const stats = await fs.stat(lockPath);
-			return Date.now() - stats.mtimeMs > staleMs;
+			if (Date.now() - stats.mtimeMs <= staleMs) return { stale: false };
+			return { stale: true, owner: null, stat: statToken(stats) };
 		} catch (err) {
-			if (isEnoent(err)) return false;
+			if (isEnoent(err)) return { stale: false };
 			throw err;
 		}
 	}
@@ -115,53 +144,63 @@ async function isLockStale(lockPath: string, staleMs: number): Promise<boolean>
 	// not have its lock stolen (#652). Reclaim a dead owner immediately. Only when owner
 	// liveness is indeterminate do we fall back to the staleMs elapsed-time heuristic.
 	const liveness = ownerLiveness(info.pid);
-	if (liveness === "dead") return true;
-	if (liveness === "alive") return false;
-	return Date.now() - info.timestamp > staleMs;
+	if (liveness === "alive") return { stale: false };
+	if (liveness === "dead" || Date.now() - info.timestamp > staleMs) {
+		return { stale: true, owner: { pid: info.pid, timestamp: info.timestamp } };
+	}
+	return { stale: false };
 }
 
-async function tryAcquireLock(lockPath: string): Promise<boolean> {
+async function removeStaleLockForAcquire(lockPath: string, snapshot: LockStaleSnapshot): Promise<boolean> {
+	if (!snapshot.stale) return false;
+	if (snapshot.owner) {
+		return (await removeFileLockDirForGc(lockPath, snapshot.owner)) === "removed";
+	}
+
+	const currentInfo = await readLockInfo(lockPath);
+	if (currentInfo) return false;
 	try {
-		await fs.mkdir(lockPath);
-		await writeLockInfo(lockPath);
+		const currentStats = await fs.stat(lockPath);
+		if (!sameStatToken(statToken(currentStats), snapshot.stat)) return false;
+		await fs.rm(lockPath, { recursive: true, force: true });
 		return true;
+	} catch (err) {
+		if (isEnoent(err)) return false;
+		throw err;
+	}
+}
+
+async function tryAcquireLock(lockPath: string): Promise<LockInfo | null> {
+	try {
+		await fs.mkdir(lockPath);
+		return await writeLockInfo(lockPath);
 	} catch (error) {
 		if ((error as NodeJS.ErrnoException).code === "EEXIST") {
-			return false;
+			return null;
 		}
 		throw error;
 	}
 }
 
-async function releaseLock(lockPath: string): Promise<void> {
+async function releaseLock(lockPath: string, owner: FileLockOwnerToken): Promise<void> {
 	try {
-		await fs.rm(lockPath, { recursive: true });
+		await removeFileLockDirForGc(lockPath, owner);
 	} catch {
 		// Ignore errors on release
 	}
 }
-
-async function lockExists(lockPath: string): Promise<boolean> {
-	try {
-		await fs.stat(lockPath);
-		return true;
-	} catch (err) {
-		if (isEnoent(err)) return false;
-		throw err;
-	}
-}
-
 async function acquireLock(filePath: string, options: FileLockOptions = {}): Promise<() => Promise<void>> {
 	const opts = { ...DEFAULT_OPTIONS, ...options };
 	const lockPath = getLockPath(filePath);
 
 	for (let attempt = 0; attempt < opts.retries; attempt++) {
-		if (await tryAcquireLock(lockPath)) {
-			return () => releaseLock(lockPath);
+		const owner = await tryAcquireLock(lockPath);
+		if (owner) {
+			return () => releaseLock(lockPath, owner);
 		}
 
-		if ((await lockExists(lockPath)) && (await isLockStale(lockPath, opts.staleMs))) {
-			await releaseLock(lockPath);
+		const stale = await staleLockSnapshot(lockPath, opts.staleMs);
+		if (await removeStaleLockForAcquire(lockPath, stale)) {
 			continue;
 		}
 

package/src/config/keybindings.ts

@@ -134,8 +134,8 @@ export const KEYBINDINGS = {
 		description: "Queue message for next turn",
 	},
 	"app.message.dequeue": {
-		defaultKeys: "alt+up",
-		description: "Dequeue message",
+		defaultKeys: ["alt+up", "alt+down"],
+		description: "Select queued message to edit",
 	},
 	"app.clipboard.pasteImage": {
 		defaultKeys: process.platform === "win32" ? "alt+v" : "ctrl+v",

package/src/config/model-profile-activation.ts

@@ -76,6 +76,34 @@ export interface MaterializeModelProfileAssignmentOptions {
 	selector: string;
 }
 
+export interface MaterializeModelProfileAssignmentsOptions {
+	session: Pick<
+		ModelProfileActivationSession,
+		"model" | "thinkingLevel" | "setActiveModelProfile" | "getActiveModelProfile"
+	>;
+	settings: Pick<Settings, "clearOverride" | "get" | "override" | "set">;
+	assignments: ReadonlyMap<GjcModelAssignmentTargetId, string> | Partial<Record<GjcModelAssignmentTargetId, string>>;
+}
+
+function isReadonlyAssignmentMap(
+	assignments: ReadonlyMap<GjcModelAssignmentTargetId, string> | Partial<Record<GjcModelAssignmentTargetId, string>>,
+): assignments is ReadonlyMap<GjcModelAssignmentTargetId, string> {
+	return typeof (assignments as { entries?: unknown }).entries === "function";
+}
+
+function getMaterializedAssignments(
+	assignments: ReadonlyMap<GjcModelAssignmentTargetId, string> | Partial<Record<GjcModelAssignmentTargetId, string>>,
+): Array<[GjcModelAssignmentTargetId, string]> {
+	if (isReadonlyAssignmentMap(assignments)) return [...assignments.entries()];
+	const assignmentRecord: Partial<Record<GjcModelAssignmentTargetId, string>> = assignments;
+	const result: Array<[GjcModelAssignmentTargetId, string]> = [];
+	for (const role of Object.keys(assignmentRecord) as GjcModelAssignmentTargetId[]) {
+		const selector = assignmentRecord[role];
+		if (selector !== undefined) result.push([role, selector]);
+	}
+	return result;
+}
+
 export function materializeActiveModelProfileAssignment(options: MaterializeModelProfileAssignmentOptions): boolean {
 	const activeProfile = options.session.getActiveModelProfile?.() ?? options.settings.get("modelProfile.default");
 	if (!activeProfile) return false;
@@ -109,6 +137,43 @@ export function materializeActiveModelProfileAssignment(options: MaterializeMode
 	return true;
 }
 
+export function materializeActiveModelProfileAssignments(options: MaterializeModelProfileAssignmentsOptions): boolean {
+	const activeProfile = options.session.getActiveModelProfile?.() ?? options.settings.get("modelProfile.default");
+	if (!activeProfile) return false;
+
+	const materializedAssignments = getMaterializedAssignments(options.assignments);
+	if (materializedAssignments.length === 0) return true;
+
+	const nextModelRoles = { ...options.settings.get("modelRoles") };
+	const nextAgentModelOverrides = { ...options.settings.get("task.agentModelOverrides") };
+	const includesDefault = materializedAssignments.some(([role]) => role === "default");
+
+	if (!includesDefault && !nextModelRoles.default && options.session.model) {
+		nextModelRoles.default = formatModelSelectorValue(
+			`${options.session.model.provider}/${options.session.model.id}`,
+			options.session.thinkingLevel,
+		);
+	}
+
+	for (const [role, selector] of materializedAssignments) {
+		const target = GJC_MODEL_ASSIGNMENT_TARGETS[role];
+		if (target.settingsPath === "modelRoles") {
+			nextModelRoles[role] = selector;
+		} else {
+			nextAgentModelOverrides[role] = selector;
+		}
+	}
+
+	options.settings.set("modelRoles", nextModelRoles);
+	options.settings.set("task.agentModelOverrides", nextAgentModelOverrides);
+	options.settings.set("modelProfile.default", undefined);
+	options.settings.clearOverride("modelProfile.default");
+	options.settings.override("modelRoles", nextModelRoles);
+	options.settings.override("task.agentModelOverrides", nextAgentModelOverrides);
+	options.session.setActiveModelProfile?.(undefined);
+	return true;
+}
+
 export function formatModelProfileCredentialError(profileLabel: string, providers: readonly string[]): string {
 	return `Model profile "${profileLabel}" requires credentials for: ${providers.join(", ")}. Run /login and configure the missing provider(s), then retry.`;
 }

package/src/config/model-registry.ts

@@ -923,10 +923,22 @@ function resolveCustomModelReference(modelId: string): Model<Api> | undefined {
 }
 
 function applyStandaloneCustomModelPolicies(model: CustomModelOverlay): CustomModelOverlay {
-	if (model.id !== "gpt-5.4" || model.provider === "github-copilot" || model.contextWindow !== undefined) {
+	if (model.contextWindow !== undefined) {
 		return model;
 	}
-	return { ...model, contextWindow: 1_000_000 };
+	if (model.id === "gpt-5.4" && model.provider !== "github-copilot") {
+		return { ...model, contextWindow: 1_000_000 };
+	}
+	// Custom GPT-5.5 endpoints that are not first-party `openai-responses` are
+	// typically Codex passthrough proxies (e.g. CLIProxyAPI fronting
+	// chatgpt.com/backend-api/codex), where the request path enforces the 272K
+	// prompt budget even though the model advertises a 1M total window.
+	// Without this default the bundled reference resolves to 1M, compaction
+	// never fires in time, and requests die with context_length_exceeded.
+	if (model.id === "gpt-5.5" && model.api !== "openai-responses") {
+		return { ...model, contextWindow: 272_000 };
+	}
+	return model;
 }
 
 function finalizeCustomModel(model: CustomModelOverlay, options: CustomModelBuildOptions): Model<Api> {

package/src/config/settings.ts

@@ -475,6 +475,28 @@ export class Settings {
 			this.override("modelRoles", { ...shallowStringRecord(runtimeOverrides), [role]: modelId });
 		}
 	}
+	/**
+	 * Set an agent model override while keeping any live runtime override aligned.
+	 *
+	 * Runtime model profiles override `task.agentModelOverrides` for the current
+	 * session. A user-selected role assignment must win immediately in that same
+	 * session, but only the explicit agent change should be persisted.
+	 */
+	setAgentModelOverride(agentName: string, modelId: string): void {
+		const current = shallowStringRecord(getByPath(this.#global, ["task", "agentModelOverrides"]));
+		const runtimeOverrides = getByPath(this.#overrides, ["task", "agentModelOverrides"]);
+		const updateRuntimeOverride =
+			!!runtimeOverrides && typeof runtimeOverrides === "object" && !Array.isArray(runtimeOverrides);
+
+		this.set("task.agentModelOverrides", { ...current, [agentName]: modelId });
+
+		if (updateRuntimeOverride) {
+			this.override("task.agentModelOverrides", {
+				...shallowStringRecord(runtimeOverrides),
+				[agentName]: modelId,
+			});
+		}
+	}
 
 	/**
 	 * Get a model role (helper for modelRoles record).

package/src/coordinator-mcp/server.ts

@@ -175,6 +175,7 @@ type CoordinatorEventKind =
 	| "turn.queued"
 	| "turn.delivering"
 	| "turn.active"
+	| "turn.acknowledged"
 	| "turn.waiting_for_answer"
 	| "turn.completed"
 	| "turn.failed"
@@ -966,24 +967,53 @@ function hasTmuxIdentity(session: Record<string, unknown>): boolean {
 	);
 }
 
+function unavailableSessionReason(turn: TurnRecord, reason: string): string {
+	if (
+		reason === "tmux_session_missing" &&
+		turn.delivery.tmux_keys_sent === true &&
+		turn.delivery.prompt_acknowledged === true
+	) {
+		return "tmux_session_missing_after_prompt_acknowledgement";
+	}
+	return reason;
+}
+
+function unavailableSessionEvidence(turn: TurnRecord, reason: string, timestamp: string): Record<string, unknown>[] {
+	if (reason !== "tmux_session_missing_after_prompt_acknowledgement") return turn.evidence;
+	return [
+		...turn.evidence,
+		{
+			type: reason,
+			message:
+				"The tmux session disappeared after GJC runtime acknowledged the prompt, before any terminal final_response or error was recorded. Treat this as an in-flight vanished session and inspect/restart with recovery evidence rather than resubmitting blindly.",
+			tmux_keys_sent: true,
+			prompt_acknowledged: true,
+			prior_status: turn.status,
+			created_at: timestamp,
+		},
+	];
+}
+
 async function markTurnFailedForUnavailableSession(
 	namespaceDir: string,
 	turn: TurnRecord,
 	reason: string,
 ): Promise<TurnRecord> {
 	const timestamp = new Date().toISOString();
+	const durableReason = unavailableSessionReason(turn, reason);
 	const failed: TurnRecord = {
 		...turn,
 		status: "failed",
 		final_response: {
-			text: `Coordinator session unavailable: ${reason}`,
+			text: `Coordinator session unavailable: ${durableReason}`,
 			format: "markdown",
 			source: "coordinator_liveness",
 			artifact_path: null,
 			truncated: false,
 		},
-		error: { code: "session_unavailable", message: reason, recoverable: true },
-		liveness: { checked_at: timestamp, live: false, reason },
+		evidence: unavailableSessionEvidence(turn, durableReason, timestamp),
+		error: { code: "session_unavailable", message: durableReason, recoverable: true },
+		liveness: { checked_at: timestamp, live: false, reason: durableReason },
 		updated_at: timestamp,
 		completed_at: timestamp,
 	};
@@ -992,7 +1022,7 @@ async function markTurnFailedForUnavailableSession(
 	await writeSessionState(namespaceDir, failed.session_id, "stale", {
 		lastTurnId: failed.turn_id,
 		live: false,
-		reason,
+		reason: durableReason,
 	});
 	return failed;
 }
@@ -1092,6 +1122,18 @@ async function markTurnAcknowledgedFromRuntimeState(
 	};
 	await writeTurnRecord(namespaceDir, acknowledged);
 	await writeActiveTurn(namespaceDir, acknowledged);
+	await appendCoordinatorEvent(namespaceDir, {
+		kind: "turn.acknowledged",
+		sessionId: acknowledged.session_id,
+		turnId: acknowledged.turn_id,
+		summary: `Turn ${acknowledged.turn_id} was acknowledged by the GJC runtime`,
+		payloadRef: path.relative(namespaceDir, turnFile(namespaceDir, acknowledged.turn_id)),
+		metadata: {
+			status: acknowledged.status,
+			tmux_keys_sent: acknowledged.delivery.tmux_keys_sent ?? null,
+			prompt_acknowledged: true,
+		},
+	});
 	return acknowledged;
 }
 
@@ -1504,14 +1546,27 @@ async function waitForCoordinatorEvents(namespaceDir: string, timeoutMs: number)
 	};
 	const timer = setTimeout(finish, Math.max(timeoutMs, 0));
 	timer.unref?.();
-	await ensureDir(eventsDir(namespaceDir));
-	try {
-		const watcher = nodeFs.watch(eventsDir(namespaceDir), (_eventType, filename) => {
-			if (filename === "event-journal.jsonl" || filename === "latest-seq.json") finish();
-		});
-		watchers.push(watcher);
-	} catch {
-		// Directory may not exist yet; the timeout remains a bounded fallback.
+	const eventDir = eventsDir(namespaceDir);
+	const watchedDirs = [
+		eventDir,
+		turnsDir(namespaceDir),
+		path.join(namespaceDir, "active-turns"),
+		path.join(namespaceDir, "session-states"),
+	];
+	for (const dir of watchedDirs) {
+		await ensureDir(dir);
+		try {
+			const watcher = nodeFs.watch(dir, (_eventType, filename) => {
+				if (dir === eventDir) {
+					if (filename === "event-journal.jsonl" || filename === "latest-seq.json") finish();
+					return;
+				}
+				if (typeof filename === "string" && filename.endsWith(".json")) finish();
+			});
+			watchers.push(watcher);
+		} catch {
+			// Directory may not be watchable on this platform; the timeout remains a bounded fallback.
+		}
 	}
 	return deferred.promise;
 }

package/src/defaults/gjc/skills/deep-interview/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: deep-interview
 description: Socratic deep interview with mathematical ambiguity gating before explicit execution approval
-argument-hint: "[--quick|--standard|--deep] <idea or vague description>"
+argument-hint: "[--trace] [--quick|--standard|--deep] <idea or vague description>"
 pipeline: [deep-interview, plan]
 handoff-policy: approval-required
 handoff: .gjc/_session-{sessionid}/specs/deep-interview-{slug}.md
@@ -20,12 +20,15 @@ Deep Interview implements Ouroboros-inspired Socratic questioning with mathemati
 - User says "ouroboros", "socratic", "I have a vague idea", "not sure exactly what I want"
 - User wants to avoid "that's not what I meant" outcomes from autonomous execution
 - Task is complex enough that jumping to code would waste cycles on scope discovery
+- User asks for implementation but the target, scope, acceptance criteria, or safety boundary is ambiguous enough that mutation would require guessing
 - User wants mathematically-validated clarity before committing to execution
 - User explicitly requests deep-interview even after being told the request is already clear, bounded, and low-risk
+- User requests a trace/research pre-step before the interview, e.g. `/skill:deep-interview --trace <idea>`
 </Use_When>
 
 <Do_Not_Use_When>
 - User has a detailed, specific request with file paths, function names, or acceptance criteria -- execute directly
+- User has an explicit concrete low-risk implementation request with enough target, scope, and acceptance criteria to execute safely -- execute directly
 - User wants to explore options or brainstorm -- use `ralplan` skill instead
 - User wants a quick fix or single change -- use direct execution, not deep-interview or role-agent delegation
 - User says "just do it" or "skip the questions" without an explicit execution path -- respect their intent by exiting deep-interview, not by writing a `pending approval` spec
@@ -51,6 +54,7 @@ Inspired by the [Ouroboros project](https://github.com/Q00/ouroboros) which demo
 - When the locked topology has multiple active components, score and target each component explicitly so depth-first clarity on one component cannot hide ambiguity in siblings
 - Keep prompt payloads budgeted: summarize or trim oversized initial context/history before composing question, scoring, spec, or handoff prompts
 - If the user's initial context is oversized, create a concise prompt-safe summary first and wait for that summary before ambiguity scoring, question generation, or downstream execution handoff
+- Route ambiguous implementation asks to clarification, deep-interview, or downstream `ralplan` before mutation; do not infer missing target, scope, acceptance criteria, or safety boundary just to start coding.
 - Do not proceed to execution until ambiguity ≤ the resolved threshold for this run and the user explicitly approves a scoped execution path
 - Treat user wording such as `implementation`, "implementation plan", Korean `구현`, or "구현 계획" as describing the eventual target, not permission to implement now.
 - While still in deep-interview, do not implement, edit/write code, launch implementation workers, or start task/skill/ultragoal implementation; continue interviewing for scope, risks, acceptance criteria, and unknowns.
@@ -62,6 +66,7 @@ Inspired by the [Ouroboros project](https://github.com/Q00/ouroboros) which demo
 - Refine free-text answers into a structured interpretation and confirm nothing is lost before scoring
 - After 3 consecutive agent-resolved answers (accepted auto-research candidates or auto-answers), route the next question to the user (dialectic rhythm guard)
 - Run an independent closure audit and a one-sentence goal restatement, each requiring explicit user confirmation, before crystallizing the spec
+- When `--trace` is active, use the bounded trace evidence summary as pre-question context; never dump raw logs, raw files, or unbounded search output into questions, scoring, specs, or handoffs
 </Execution_Policy>
 
 <Internal_Auto_Mode_Protocol>
@@ -133,6 +138,16 @@ If `{{ARGUMENTS}}` is already clear, bounded, low-risk, and asks for a quick fix
 
 This gate exists to prevent deep-interview from making easy problems harder. A small verification need does not make a request interview-worthy.
 
+## Phase 0.75: Optional Trace Pre-Step
+
+Run this phase only when the active deep-interview state or invocation indicates `--trace` / `state.trace.enabled === true`. It is a pre-interview research step, not an implementation phase.
+
+1. Read the native trace summary from active deep-interview state (`trace`, `state.trace`, or `state.trace_summary`). The native seed must have produced this summary before any interview question.
+2. Treat the summary as compact evidence: project hints, relevant paths, and path-level findings only. Do not expand it by dumping raw files, raw logs, or unbounded command output.
+3. Store or preserve it under `state.trace_summary` and fold it into `codebase_context` with citations to the summarized paths.
+4. Use trace findings to influence Round 0 topology, Phase 2 question targeting, requirement wording, acceptance criteria, and final Technical Context. Normal no-trace interviews must behave exactly as before.
+5. If `--trace` was requested but no valid bounded summary exists, increment `architect_failures` or record an internal audit note, then continue with the normal no-trace path without surfacing tool noise.
+
 ## Phase 1: Initialize
 
 1. **Parse the user's idea** from `{{ARGUMENTS}}`
@@ -177,6 +192,7 @@ This gate exists to prevent deep-interview from making easy problems harder. A s
     "threshold": <resolvedThreshold>,
     "threshold_source": "<resolvedThresholdSource>",
     "language": "<existing language object from active state, if present>",
+    "trace_summary": "<bounded trace summary when --trace is active, else null>",
     "codebase_context": null,
     "topology": {
       "status": "pending|confirmed|legacy_missing",
@@ -222,6 +238,7 @@ Run this gate exactly once after Phase 1 initialization and before any Phase 2 a
    - Extract top-level verbs/nouns, workstreams, surfaces, integrations, or deliverables that can succeed or fail independently.
    - Prefer 1-6 components. If more than 6 candidates appear, group siblings at the highest useful level and note the grouping rationale.
    - Do not treat implementation tasks, fields, or sub-features as top-level components unless the user framed them as independent outcomes.
+   - When `--trace` is active, include trace-summarized paths as topology evidence, but do not add implementation sub-tasks as top-level components solely because trace found files.
 2. **Ask one confirmation question** before Round 1:
 
 ```
@@ -289,6 +306,7 @@ Build the question generation prompt with:
 - Current clarity scores per dimension (which is weakest?)
 - Lateral-review panel findings (if convened this round -- see Phase 3)
 - Brownfield codebase context (if applicable), summarized to cited paths/symbols/patterns instead of raw dumps
+- Bounded trace summary (when `--trace` is active): project hints, relevant paths, and findings only; cite paths instead of raw content
 - Locked topology from Round 0, including active components, deferred components, prior per-component scores, and `last_targeted_component_id`
 
 - `language` from active state when present; apply `language.instruction` to all natural-language user-facing question text, rationale, and options
@@ -370,11 +388,22 @@ Ambiguity-raising triggers:
 
 Use **mechanism A** for every ambiguity rise: a trigger LOWERS the affected component/dimension clarity score, and the existing weighted formula raises ambiguity. There is **no separate penalty term**; ambiguity remains bounded by the same greenfield/brownfield formula.
 
+**Deterministic ambiguity floor (runtime-enforced).** The runtime independently computes a code-level floor from persisted state and clamps every reported ambiguity to `max(reported, floor)` at write time — the scorer cannot under-report below what code can objectively measure:
+
+- `+0.10` per established fact marked `disputed` that has no `superseded_by` resolution (contradiction pressure)
+- `+0.05` per active topology component whose goal/constraints/criteria clarity is still unscored (gap pressure — persist `topology.components[].clarity_scores` every round or the floor blocks convergence)
+- `+0.05 × (auto-answered rounds / scored rounds)` (assumption dilution)
+
+Cooperate with the floor rather than fight it:
+- Replacing an already-scored answer for the same round (a retraction/pivot) automatically marks that round's established facts as disputed; ambiguity rises mechanically even when no trigger is reported. Treat a floor-driven rise as trigger evidence and score the affected dimensions accordingly.
+- A disputed fact keeps the floor at or above `0.10` — above the default threshold — so convergence is blocked until the dispute is resolved: either the user re-confirms the original fact (set `disputed: false`) or the superseding decision is recorded as a new established fact and the old fact gets `superseded_by: <new fact id>`. Never delete the contradicted fact.
+- When the effective score was clamped upward, the persisted round carries `reported_ambiguity` (your raw score) and `ambiguity_floor`; report the floor and its dominant cause in the Step 2d table instead of pretending the raw score held.
+
 The rise is SILENT: no modal, no forced-resolution step, and no dedicated conflict UI. Surface it through the normal per-round report and by targeting the next question at the affected component/dimension.
 
 Structured scorer output is required. Include `triggers`, `trigger_status`, `affected_component`, `affected_dimension`, `prior_dimension_score`, `new_dimension_score`, `prior_ambiguity`, `new_ambiguity`, `evidence`, `contradicted_established_fact` when relevant, and `disputed_unresolved_rationale` when applicable.
 
-Established-facts maintenance: promote stable confirmed decisions into `state.established_facts` with source/evidence; when a new answer contradicts an established fact, mark the fact disputed and preserve the contradicted fact instead of deleting it.
+Established-facts maintenance: promote stable confirmed decisions into `state.established_facts` with source/evidence; when a new answer contradicts an established fact, mark the fact disputed and preserve the contradicted fact instead of deleting it. When the user later confirms the new direction, record the superseding decision as a new established fact and set `superseded_by: <new fact id>` on the disputed fact — that is the only way to release the deterministic floor pressure while keeping the audit trail.
 
 TRANSITION VALIDATION: if a trigger is present, the affected dimension must not improve and overall ambiguity must rise vs the prior scored round, unless the trigger is explicitly marked disputed or unresolved with rationale.
 
@@ -396,6 +425,9 @@ Locked topology:
 Established facts:
 {state.established_facts}
 
+Trace summary:
+{state.trace_summary if --trace was active, else "not requested"}
+
 Score each active component on each dimension, then provide the overall dimension scores as the minimum or coverage-weighted weakest score across active components. Deferred components are excluded from ambiguity math but must remain listed in topology and the final spec.
 
 Score each dimension:
@@ -465,6 +497,7 @@ Round {n} complete.
 | Success Criteria | {s} | {w} | {s*w} | {gap or "Clear"} |
 | Context (brownfield) | {s} | {w} | {s*w} | {gap or "Clear"} |
 | **Ambiguity** | | | **{prior_score}% -> {score}% {up|down|flat}** | {if up: trigger name such as "A direct contradiction"} |
+| **Floor** (only when clamped) | | | **{floor}%** | {dominant cause: disputed fact / unscored component / auto-answer dilution} |
 
 **Topology:** Targeted {target_component_name} | Active: {active_component_count} | Deferred: {deferred_component_count} | Next rotation after: {last_targeted_component_id}
 
@@ -525,7 +558,7 @@ When ambiguity ≤ threshold (or hard cap / early exit):
 
 **Before generating the spec, two gates must pass, in order:**
 
-**4a. Closure / Acceptance Guard.** Even when ambiguity ≤ threshold, do not treat the math as completion. Run an independent readiness audit from the full main-session perspective (including explore findings, established facts, and triggers the scorer may not have fully weighed). Confirm every active topology component has goal/constraint/criteria coverage, no unresolved or disputed trigger remains on a path that matters, and no low-confidence auto-answer is standing in for user-confirmed truth above the clarity cap. If a material gap exists, explicitly override the gate to the user — "The math says ready, but I am not accepting it yet because {gap}" — and ask the single highest-impact follow-up, returning to Phase 2. Record any override in `state.closure_overrides`.
+**4a. Closure / Acceptance Guard.** Even when ambiguity ≤ threshold, do not treat the math as completion. Run an independent readiness audit from the full main-session perspective (including explore findings, established facts, and triggers the scorer may not have fully weighed). Confirm every active topology component has goal/constraint/criteria coverage, no unresolved or disputed trigger remains on a path that matters, no disputed established fact lacks a `superseded_by` resolution, and no low-confidence auto-answer is standing in for user-confirmed truth above the clarity cap. If a material gap exists, explicitly override the gate to the user — "The math says ready, but I am not accepting it yet because {gap}" — and ask the single highest-impact follow-up, returning to Phase 2. Record any override in `state.closure_overrides`.
 
 **4b. Restate gate.** Once closure passes, collapse the agreed answers into ONE sentence goal that covers every active component, and confirm it with a single `ask`: "If someone read only this line, would they reach the same outcome you have in mind?" Offer **Yes, crystallize**, **Adjust wording**, and **Missing scope**, plus free-text, applying `language.instruction` when present. Because this gate has options, it MUST go through `ask`: do not print the Restate question and options as assistant prose with `Question:`/`Options:` labels. If the Restate gate was already printed that way, immediately call `ask` with the same question/options before accepting or waiting for any answer. On "Adjust wording" / "Missing scope", collect the exact correction with one follow-up `ask`, route it back through Step 2c scoring and established-facts maintenance (a correction can change ambiguity), then re-run closure and ask the Restate gate again. Cap at two loops; if alignment is not reached, return to Phase 2 with a targeted question instead of forcing a goal line. Persist the confirmed line as `state.restated_goal`.
 
@@ -615,8 +648,8 @@ Spec structure:
 | {assumption} | {how it was questioned} | {what was decided} |
 
 ## Technical Context
-{brownfield: relevant codebase findings from focused repo inspection or canonical role-agent fact-finding}
-{greenfield: technology choices and constraints}
+{brownfield: relevant codebase findings from focused repo inspection, canonical role-agent fact-finding, and bounded trace summary when --trace was active}
+{greenfield: technology choices and constraints, plus bounded trace findings when --trace was active and relevant}
 
 ## Ontology (Key Entities)
 {Fill from the FINAL round's ontology extraction, not just crystallization-time generation}