@sayknow-cli/coding-agent 0.3.6 → 0.3.8

package/src/skc-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/skc-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, "skc 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, "skc deep-interview score-round");
 	await syncRecorderHud(cwd, envelope, options.sessionId);
 	return { record };

package/src/skc-runtime/deep-interview-state.ts

@@ -31,6 +31,13 @@ export interface DeepInterviewEstablishedFact {
 	dimension?: string;
 	evidence?: string;
 	disputed: boolean;
+	/**
+	 * Resolution pointer for a disputed fact: the id of the fact that replaced it
+	 * after the user confirmed a pivot. A disputed fact without `superseded_by`
+	 * keeps the deterministic ambiguity floor elevated; setting it releases the
+	 * pressure while preserving the contradicted fact for audit.
+	 */
+	superseded_by?: string;
 }
 
 export interface DeepInterviewTriggerMetadata {
@@ -66,7 +73,12 @@ export interface DeepInterviewRoundRecord {
 	answered_at: string;
 	scored_at?: string;
 	scores?: Record<string, number>;
+	/** Effective ambiguity after the deterministic floor clamp (`max(reported, floor)`). */
 	ambiguity?: number;
+	/** Original LLM-reported ambiguity, preserved for audit when the floor clamped it. */
+	reported_ambiguity?: number;
+	/** Deterministic floor in effect when this round was scored, when it clamped. */
+	ambiguity_floor?: number;
 	triggers?: DeepInterviewTriggerMetadata[];
 }
 
@@ -125,6 +137,7 @@ const TRANSCRIPT_STATE_FIELDS = [
 	"rounds",
 	"established_facts",
 	"current_ambiguity",
+	"ambiguity_floor",
 	"topology",
 	"ontology_snapshots",
 	"auto_researched_rounds",
@@ -150,13 +163,39 @@ const HOISTED_STATE_FIELDS = [
 	"threshold_source",
 ] as const;
 
+/**
+ * Envelope-reserved keys that are never legitimate interview `state` fields.
+ *
+ * A malformed write that wraps a whole envelope under `state`
+ * (`skc state deep-interview write --input '{"state": <envelope>}'`) leaks these
+ * into the nested state. Because normalization otherwise preserves unknown
+ * nested fields, they would accrete a recursive `state.state` chain (plus stale
+ * `receipt`/`skill`/`version`/... duplicates) that no later merge or write ever
+ * removes, permanently corrupting the shape. They are stripped from `state` on
+ * normalize so the canonical envelope self-heals on the next write.
+ */
+const ENVELOPE_RESERVED_STATE_KEYS = [
+	"state",
+	"receipt",
+	"skill",
+	"version",
+	"updated_at",
+	"active",
+	"current_phase",
+	"state_revision",
+	"session_id",
+] as const;
+
 /**
  * Canonicalize a deep-interview envelope: interview data nested under `state`,
  * legacy flattened fields hoisted in losslessly, transcript duplicates removed
  * from the top level, and `rounds`/`established_facts` guaranteed to be arrays.
  *
- * Idempotent: a canonical envelope is returned unchanged in shape. Never deletes
- * unknown envelope or nested fields, and never mutates the input.
+ * Idempotent: a canonical envelope is returned unchanged in shape. Preserves all
+ * unknown envelope and nested fields except the envelope-reserved keys that leak
+ * into `state` (see `ENVELOPE_RESERVED_STATE_KEYS`), which are stripped so a
+ * malformed envelope-in-state write cannot permanently nest state. Never mutates
+ * the input.
  */
 export function normalizeDeepInterviewEnvelope(value: unknown): DeepInterviewStateEnvelope {
 	const envelope: DeepInterviewStateEnvelope = isPlainObject(value) ? { ...value } : {};
@@ -169,6 +208,9 @@ export function normalizeDeepInterviewEnvelope(value: unknown): DeepInterviewSta
 	for (const field of HOISTED_STATE_FIELDS) {
 		if (inner[field] === undefined && envelope[field] !== undefined) inner[field] = envelope[field];
 	}
+	for (const field of ENVELOPE_RESERVED_STATE_KEYS) {
+		if (field in inner) delete inner[field];
+	}
 
 	if (!Array.isArray(inner.rounds)) inner.rounds = [];
 	if (!Array.isArray(inner.established_facts)) inner.established_facts = [];

package/src/skc-runtime/ralplan-runtime.ts

@@ -11,7 +11,7 @@ import {
 	type RalplanIndexRow,
 	summarizeRalplanIndex,
 } from "./ledger-event-renderer";
-import { isRestrictedRoleAgentBash } from "./restricted-role-agent-bash";
+import { isRestrictedRoleAgentBash, SKC_RALPLAN_ARTIFACT_ENV } from "./restricted-role-agent-bash";
 import { modeStatePath, sessionPlansDir } from "./session-layout";
 import { resolveSkcSessionForWrite, writeSessionActivityMarker } from "./session-resolution";
 import { migrateWorkflowState } from "./state-migrations";
@@ -35,8 +35,9 @@ import {
  *    that lives in the bundled `/skill:ralplan` skill — but it accepts every documented flag so
  *    scripted users see a useful response and the active run is visible to the TUI.
  *
- * 2. **Artifact write**: `skc ralplan --write --stage <type> --stage_n <N> --artifact
- *    <path-or-string> [--run-id <id>] [--session-id <id>] [--json]` persists Planner / Architect
+ * 2. **Artifact write**: `skc ralplan --write --stage <type> --stage_n <N>
+ *    (--artifact <path-or-string> | --artifact-env SKC_RALPLAN_ARTIFACT)
+ *    [--run-id <id>] [--session-id <id>] [--json]` persists Planner / Architect
  *    / Critic / revision / post-interview / ADR / final markdown under `.skc/plans/ralplan/<run-id>/`, maintains
  *    an `index.jsonl` audit log, copies `final` stages to `pending-approval.md`, and advances
  *    the HUD chip to reflect the latest persisted stage.
@@ -81,6 +82,7 @@ const VALUE_FLAGS = new Set([
 	"--stage",
 	"--stage_n",
 	"--artifact",
+	"--artifact-env",
 	"--run-id",
 	"--session-id",
 	"--architect",
@@ -409,8 +411,16 @@ async function resolveArtifactArgs(args: readonly string[], cwd: string): Promis
 	const stageN = parseStageN(flagValue(args, "--stage_n"));
 
 	const rawArtifact = flagValue(args, "--artifact");
-	if (rawArtifact === undefined || rawArtifact === "") {
-		throw new RalplanCommandError(2, "--artifact is required for ralplan --write");
+	const artifactEnvName = flagValue(args, "--artifact-env");
+	const artifactSources = [rawArtifact, artifactEnvName].filter(value => value !== undefined);
+	if (artifactSources.length === 0 || artifactSources.some(value => value === "")) {
+		throw new RalplanCommandError(2, "--artifact or --artifact-env is required for ralplan --write");
+	}
+	if (artifactSources.length > 1) {
+		throw new RalplanCommandError(2, "--artifact and --artifact-env are mutually exclusive");
+	}
+	if (artifactEnvName !== undefined && artifactEnvName !== SKC_RALPLAN_ARTIFACT_ENV) {
+		throw new RalplanCommandError(2, `--artifact-env must be ${SKC_RALPLAN_ARTIFACT_ENV}`);
 	}
 
 	const session = resolveSkcSessionForWrite(cwd, {
@@ -430,7 +440,13 @@ async function resolveArtifactArgs(args: readonly string[], cwd: string): Promis
 	const runId = explicitRunId || (await readActiveRunId(cwd, sessionId)) || sessionIdRaw || defaultRunId();
 	assertSafePathComponent(runId, "run-id");
 
-	const artifact = await resolveArtifactContent(rawArtifact, cwd);
+	const artifact =
+		artifactEnvName !== undefined
+			? (process.env[SKC_RALPLAN_ARTIFACT_ENV] ?? "")
+			: await resolveArtifactContent(rawArtifact!, cwd);
+	if (artifact === "") {
+		throw new RalplanCommandError(2, "artifact content is empty");
+	}
 	return { stage: stage as RalplanStage, stageN, runId, artifact, sessionId, json: hasFlag(args, "--json") };
 }
 

package/src/skc-runtime/restricted-role-agent-bash.ts

@@ -1,4 +1,5 @@
 export const SKC_RESTRICTED_ROLE_AGENT_BASH_ENV = "SKC_RESTRICTED_ROLE_AGENT_BASH";
+export const SKC_RALPLAN_ARTIFACT_ENV = "SKC_RALPLAN_ARTIFACT";
 
 export function isRestrictedRoleAgentBash(): boolean {
 	return process.env[SKC_RESTRICTED_ROLE_AGENT_BASH_ENV] === "1";