@iowarp/clio-coder 0.3.0 → 0.3.1

package/src/domains/evidence/types.ts

@@ -0,0 +1,325 @@
+import type { GateDecisionArtifact, RunEnvelope, RunReceipt, ToolCallStat } from "../dispatch/index.js";
+import type { RunPersonaOverride, RunPipelineProvenance, RunReceiptAutonomyEnforcement } from "../dispatch/types.js";
+import type { EvalCommandPhase, EvalFailureClass, EvalRunRecord } from "../eval/index.js";
+import type { ProtectedArtifact } from "../safety/protected-artifacts.js";
+import type { RunEscalationCounts } from "./provenance.js";
+
+export const EVIDENCE_VERSION = 1;
+
+export const EVIDENCE_TAGS = [
+	"audit-linked",
+	"audit-missing",
+	"best-effort-link",
+	"timeout",
+	"context-overflow",
+	"provider-transient",
+	"missing-dependency",
+	"wrong-runtime",
+	"proxy-validation",
+	"no-validation",
+	"destructive-cleanup",
+	"blocked-tool",
+	"escalation",
+	"external-bypass",
+	"external-approximation",
+	"receipt-integrity",
+	"protected-artifact",
+	"tool-loop",
+	"test-failure",
+	"build-failure",
+	"cwd-missing",
+	"session-linked",
+	"session-missing",
+	"auth-failure",
+	"unknown",
+] as const;
+
+export type EvidenceTag = (typeof EVIDENCE_TAGS)[number];
+
+/**
+ * Canonical failure-cause subset for receipt summaries and observability
+ * histograms. Provenance/quality tags such as `audit-linked`, `session-linked`,
+ * and `no-validation` remain evidence tags, but they are not failure causes.
+ */
+export const FAILURE_CAUSE_TAG_ORDER = [
+	"timeout",
+	"auth-failure",
+	"missing-dependency",
+	"build-failure",
+	"test-failure",
+	"blocked-tool",
+] as const satisfies readonly EvidenceTag[];
+
+export type FailureCauseTag = (typeof FAILURE_CAUSE_TAG_ORDER)[number];
+
+/** Fast membership test for the canonical failure-cause subset. */
+export const FAILURE_CAUSE_TAGS: ReadonlySet<EvidenceTag> = new Set(FAILURE_CAUSE_TAG_ORDER);
+
+export type EvidenceSource =
+	| { kind: "run"; runId: string }
+	| { kind: "session"; sessionId: string }
+	| { kind: "eval"; evalId: string };
+
+export interface EvidenceTotals {
+	runs: number;
+	receipts: number;
+	toolCalls: number;
+	toolErrors: number;
+	blockedToolCalls: number;
+	sessionEntries: number;
+	auditRows: number;
+	toolEvents: number;
+	linkedToolEvents: number;
+	protectedArtifacts: number;
+	tokens: number;
+	costUsd: number;
+	wallTimeMs: number;
+}
+
+export interface EvidenceOverview {
+	version: 1;
+	evidenceId: string;
+	source: EvidenceSource;
+	generatedAt: string;
+	runIds: string[];
+	sessionId: string | null;
+	statuses: string[];
+	startedAt: string | null;
+	endedAt: string | null;
+	tasks: string[];
+	cwds: string[];
+	agentIds: string[];
+	targetIds: string[];
+	runtimeIds: string[];
+	modelIds: string[];
+	totals: EvidenceTotals;
+	tags: EvidenceTag[];
+	files: string[];
+	/**
+	 * Number of secret-shaped values replaced with `[redacted:<kind>]` across
+	 * the bundle's export surfaces (previews, transcript, receipts) at build
+	 * time. Additive field: older bundles simply lack it. Zero means the
+	 * patterns matched nothing; raw local session files are never touched.
+	 */
+	redactionCount?: number;
+}
+
+export type EvidenceSeverity = "info" | "warn";
+
+export interface EvidenceFinding {
+	id: string;
+	severity: EvidenceSeverity;
+	tag: EvidenceTag;
+	runId: string | null;
+	message: string;
+}
+
+export interface EvidenceFindingsFile {
+	version: 1;
+	evidenceId: string;
+	findings: EvidenceFinding[];
+}
+
+export interface EvidenceGateDecisionsFile {
+	version: 1;
+	evidenceId: string;
+	decisions: GateDecisionArtifact[];
+}
+
+export interface EvidenceBuildResult {
+	evidenceId: string;
+	directory: string;
+	overview: EvidenceOverview;
+	findings: EvidenceFinding[];
+}
+
+export interface EvidenceInspectable {
+	overview: EvidenceOverview;
+	findings: EvidenceFinding[];
+}
+
+export interface EvidenceRunSource {
+	envelope: RunEnvelope;
+	receipt: RunReceipt | null;
+	receiptError: string | null;
+	/** True when the receipt was readable but failed cryptographic/ledger integrity verification. */
+	receiptIntegrityFailed: boolean;
+}
+
+export type EvidenceLinkConfidence = "exact" | "best-effort";
+
+/**
+ * How a row's `runId` was derived. `entry-run-id` is the run id the producer
+ * stamped on the record at write time and is exact. The others are timestamp
+ * windowing, which is a fallback: concurrent runs share one clock, so their
+ * windows overlap and containment cannot name an owner. A row inside more than
+ * one window is `ambiguous-timestamp-window`, reports a null `runId`, and lists
+ * every run it may belong to instead of picking one.
+ */
+export interface EvidenceRunLink {
+	kind: "entry-run-id" | "timestamp-window" | "ambiguous-timestamp-window" | "no-run-window";
+	confidence: EvidenceLinkConfidence;
+	candidateRunIds?: string[];
+}
+
+export type EvidenceToolEventSource = "session-entry" | "audit-row" | "receipt-aggregate" | "eval-command";
+
+export interface EvidenceToolEvent {
+	source: EvidenceToolEventSource;
+	runId: string | null;
+	sessionId: string | null;
+	tool: string;
+	count: number;
+	ok: number;
+	errors: number;
+	blocked: number;
+	totalDurationMs: number;
+	timestamp?: string;
+	toolCallId?: string;
+	linkKind?: string;
+	confidence?: EvidenceLinkConfidence;
+	decision?: string;
+	actionClass?: string;
+	argsPreview?: string;
+	resultPreview?: string;
+	/** How `runId` was derived. Present on events built from session ledger entries. */
+	runLink?: EvidenceRunLink;
+}
+
+export interface EvidenceAuditLinkedRow {
+	kind: "audit-linked";
+	auditKind: string;
+	ts: string | null;
+	runId: string | null;
+	sessionId: string | null;
+	linkKind: string;
+	confidence: EvidenceLinkConfidence;
+	reasons: string[];
+	candidateRunIds?: string[];
+	row: Record<string, unknown>;
+}
+
+export interface EvidenceTraceRunRow {
+	kind: "run";
+	runId: string;
+	task: string;
+	status: string;
+	exitCode: number | null;
+	startedAt: string;
+	endedAt: string | null;
+	wallTimeMs: number;
+	cwd: string;
+	agentId: string;
+	targetId: string;
+	runtimeId: string;
+	wireModelId: string;
+	tokenCount: number;
+	costUsd: number;
+	/** Pipeline threading provenance; present only for pipeline steps after the first. */
+	pipeline?: RunPipelineProvenance;
+	/** Ad-hoc specialist provenance; present only when a persona override composed the prompt. */
+	personaOverride?: RunPersonaOverride;
+	/** Worker permission-escalation counters; present only when the run saw an escalation. */
+	escalation?: RunEscalationCounts;
+	/** Autonomy enforcement grade recorded by the run receipt. */
+	autonomyEnforcement?: RunReceiptAutonomyEnforcement;
+}
+
+export interface EvidenceTraceToolRow extends EvidenceToolEvent {
+	kind: "tool-summary";
+}
+
+export interface EvidenceTraceFindingRow extends EvidenceFinding {
+	kind: "finding";
+}
+
+export interface EvidenceEvalTraceRow {
+	kind: "eval-result";
+	evalId: string;
+	runId: string;
+	taskId: string;
+	pass: boolean;
+	exitCode: number;
+	failureClass: EvalFailureClass | null;
+	wallTimeMs: number;
+	tokens: number;
+	costUsd: number;
+	cwd: string;
+	tags: string[];
+	evidenceId: string | null;
+}
+
+export interface EvidenceEvalCommandTraceRow {
+	kind: "eval-command";
+	evalId: string;
+	runId: string;
+	taskId: string;
+	phase: EvalCommandPhase;
+	index: number;
+	command: string;
+	exitCode: number;
+	timedOut: boolean;
+	wallTimeMs: number;
+}
+
+export type EvidenceCleanTraceRow =
+	| EvidenceTraceRunRow
+	| EvidenceTraceToolRow
+	| EvidenceTraceFindingRow
+	| EvidenceEvalTraceRow
+	| EvidenceEvalCommandTraceRow;
+
+export interface EvidenceReceiptFile {
+	version: 1;
+	receipts: RunReceipt[];
+}
+
+export interface EvidenceProtectedArtifactEvent {
+	kind: "protected-artifact";
+	sessionId: string;
+	runId: string | null;
+	timestamp: string;
+	turnId: string;
+	parentTurnId: string | null;
+	action: "protect";
+	artifact: ProtectedArtifact;
+	toolName?: string;
+	toolCallId?: string;
+	/** Run id the session ledger recorded on the entry itself at write time. */
+	sourceRunId?: string;
+	correlationId?: string;
+	/** How `runId` was derived. */
+	runLink?: EvidenceRunLink;
+}
+
+export interface EvidenceProtectedArtifactsFile {
+	version: 1;
+	artifacts: ProtectedArtifact[];
+	events: EvidenceProtectedArtifactEvent[];
+}
+
+export type EvidenceRawTraceRow =
+	| {
+			kind: "run-ledger";
+			runId: string;
+			envelope: RunEnvelope;
+	  }
+	| {
+			kind: "receipt";
+			runId: string;
+			receipt: RunReceipt;
+	  }
+	| {
+			kind: "receipt-error";
+			runId: string;
+			error: string;
+	  };
+
+export interface EvidenceEvalRawTraceRow {
+	kind: "eval-result";
+	evalId: string;
+	runId: string;
+	result: EvalRunRecord;
+}
+
+export type EvidenceToolStat = ToolCallStat;

package/src/domains/evolution/SELF_EDIT_GATE.md

@@ -0,0 +1,91 @@
+# Self-edit gate (Slice 5b) - deferred
+
+Status: deferred to a follow-up. Tracking note only. No enforcement code exists
+for this yet, by design.
+
+## What 5b would do
+
+Wire the self-development boundary so that when Clio edits her OWN harness paths
+at a high `authorityLevel` (the `HIGH_AUTHORITY_LEVELS` set in `manifest.ts`:
+`tool-implementation`, `middleware`, `runtime`, `safety`, `schema`, `cli`), the
+edit requires a current, validated, evidence-linked change manifest. The
+manifest must pass `validateChangeManifest` with a resolver bound to the local
+evidence store (the 5a behavior), so a high-authority self-edit cannot land
+without evidence that justifies it.
+
+## Why it is deferred
+
+There is no safe enforcement point with all required inputs yet. Clio's edits to
+local source go through the ordinary edit/middleware path, which can see tools,
+paths, and action classes, but does not distinguish "Clio editing her own
+harness in this repo" from "the user asked Clio to edit this repo's source". A
+naive gate keyed on path globs would block ordinary, user-requested edits, which
+the spec explicitly forbids
+(`v0.2.7-evidence-spine.md`, Slice 5: enforcement "must NOT block ordinary local
+source edits the user requests; it only applies to Clio editing her own harness
+paths"). The spec permits landing 5a in v0.2.7 and tracking 5b rather than
+forcing a fragile gate.
+
+## Concrete design
+
+The enforcement point should be a `before_tool` middleware registration, because
+the registry already supplies `toolName`, `toolArgs`, `runId`, `sessionId`,
+`turnId`, and `metadata.actionClass` before a mutating tool executes. The gate
+would run only when all of these are true:
+
+1. The process is running from the Clio repository root.
+2. The tool would mutate a harness-owned path. Reuse `toolMutationPaths()` for
+   `write` / `edit` / artifact writers, and the shell write-target extraction
+   already used by the safety classifier for `bash`.
+3. The target path maps to a high-authority manifest level:
+   `src/engine/**`, `src/tools/**`, `src/domains/safety/**`,
+   `src/domains/middleware/**`, `src/domains/context/**`,
+   `src/domains/prompts/**`, `src/interactive/**`, `src/worker/**`,
+   `skills/**`, `damage-control-rules.yaml`, and release / packaging surfaces
+   map to one of `HIGH_AUTHORITY_LEVELS`.
+4. The tool-call origin is an agent-initiated harness self-edit, not an
+   operator-requested local source edit.
+5. A current change manifest is available and validates with
+   `validateChangeManifest(value, { resolveEvidenceRef })`, including at least
+   one evidence ref that resolves against the local evidence store.
+
+If the gate fires and the manifest check fails, it should return one
+`block_tool` effect with a clear instruction to create or validate the manifest.
+It must not block ordinary user-requested local edits, even to the paths above.
+
+## Minimal missing signal
+
+The current middleware input does not provide item 4. The minimal signal is one
+typed scalar on `MiddlewareHookInput.metadata`, set by the engine/registry at
+tool admission time:
+
+```ts
+selfEditOrigin: "operator-requested" | "agent-initiated"
+```
+
+`operator-requested` means the current turn's accepted user request explicitly
+asked for the edit or command. `agent-initiated` means the model is modifying
+Clio's harness without a current user request that names or implies that
+modification. Unknown must be treated as `operator-requested` until the signal is
+implemented, because fail-closed would violate the spec by blocking normal local
+edits.
+
+This signal should be derived before tool invocation, next to the existing
+`ToolInvokeOptions` / `buildToolHookInput()` path in `src/tools/registry.ts`.
+The classifier cannot infer it from paths, action classes, or autonomy alone:
+those say what would be touched, not who initiated the intent.
+
+## Re-entry condition
+
+5b can land once there is a clean, unambiguous signal in middleware input that
+an edit is Clio modifying her own harness in this repository (as opposed to a
+user-directed source edit). At that point the gate reads: for a high-authority
+self-edit with
+`metadata.selfEditOrigin === "agent-initiated"`, require a manifest whose
+`evidenceRefs` resolve against the evidence store before the edit is permitted;
+otherwise block that tool call and re-prompt for the manifest. The 5a validator
+(`validateChangeManifest(value, { resolveEvidenceRef })`) is the check it would
+call; no manifest schema change is needed.
+
+Intended commit when it lands:
+`feat(evolution): require a manifest for high-authority self-edits`.

package/src/domains/evolution/index.ts

@@ -0,0 +1,26 @@
+export type {
+	BudgetImpactRisk,
+	ChangeManifest,
+	ChangeManifestSummary,
+	ExpectedBudgetImpact,
+	ManifestAuthorityLevel,
+	ManifestChange,
+} from "./manifest.js";
+export {
+	allowsEmptyEvidenceRefs,
+	BUDGET_IMPACT_RISKS,
+	CHANGE_MANIFEST_VERSION,
+	createChangeManifestTemplate,
+	FIRST_EXPLORATORY_ITERATION_ID,
+	HIGH_AUTHORITY_LEVELS,
+	isHighAuthorityLevel,
+	loadChangeManifestJson,
+	MANIFEST_AUTHORITY_LEVELS,
+	summarizeChangeManifest,
+} from "./manifest.js";
+export type {
+	ManifestValidationIssue,
+	ManifestValidationResult,
+	ValidateChangeManifestOptions,
+} from "./validate.js";
+export { validateChangeManifest } from "./validate.js";

package/src/domains/evolution/manifest.ts

@@ -0,0 +1,154 @@
+import { readFile } from "node:fs/promises";
+
+export const CHANGE_MANIFEST_VERSION = 1;
+
+export const FIRST_EXPLORATORY_ITERATION_ID = "exploratory-1";
+
+export const MANIFEST_AUTHORITY_LEVELS = [
+	"prompt",
+	"tool-description",
+	"tool-implementation",
+	"middleware",
+	"memory",
+	"runtime",
+	"safety",
+	"schema",
+	"cli",
+] as const;
+
+export type ManifestAuthorityLevel = (typeof MANIFEST_AUTHORITY_LEVELS)[number];
+
+export const HIGH_AUTHORITY_LEVELS = [
+	"tool-implementation",
+	"middleware",
+	"runtime",
+	"safety",
+	"schema",
+	"cli",
+] as const satisfies ReadonlyArray<ManifestAuthorityLevel>;
+
+export const BUDGET_IMPACT_RISKS = ["lower", "same", "higher"] as const;
+
+export type BudgetImpactRisk = (typeof BUDGET_IMPACT_RISKS)[number];
+
+export interface ChangeManifest {
+	version: 1;
+	iterationId: string;
+	baseGitSha: string;
+	createdAt: string;
+	changes: ManifestChange[];
+}
+
+export interface ManifestChange {
+	id: string;
+	componentIds: string[];
+	filesChanged: string[];
+	authorityLevel: ManifestAuthorityLevel;
+	evidenceRefs: string[];
+	rootCause: string;
+	targetedFix: string;
+	predictedFixes: string[];
+	predictedRegressions: string[];
+	validationPlan: string[];
+	rollbackPlan: string;
+	expectedBudgetImpact?: ExpectedBudgetImpact;
+}
+
+export interface ExpectedBudgetImpact {
+	tokenDelta?: number;
+	wallTimeDeltaMs?: number;
+	risk: BudgetImpactRisk;
+}
+
+export interface ChangeManifestSummary {
+	iterationId: string;
+	baseGitSha: string;
+	changeCount: number;
+	authorityLevels: ManifestAuthorityLevel[];
+	componentIds: string[];
+	filesChanged: string[];
+	predictedRegressions: string[];
+	validationPlanCount: number;
+}
+
+export async function loadChangeManifestJson(path: string): Promise<unknown> {
+	let raw: string;
+	try {
+		raw = await readFile(path, "utf8");
+	} catch (error) {
+		// Same voice as the invalid-JSON refusal below: name the artifact, then
+		// the path, rather than repeating node:fs at the operator.
+		if ((error as NodeJS.ErrnoException).code === "ENOENT") throw new Error(`change manifest not found: ${path}`);
+		throw error;
+	}
+	try {
+		return JSON.parse(raw) as unknown;
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		throw new Error(`${path}: invalid JSON: ${message}`);
+	}
+}
+
+export function createChangeManifestTemplate(): ChangeManifest {
+	return {
+		version: CHANGE_MANIFEST_VERSION,
+		iterationId: FIRST_EXPLORATORY_ITERATION_ID,
+		baseGitSha: "0000000000000000000000000000000000000000",
+		createdAt: "2026-04-29T00:00:00.000Z",
+		changes: [
+			{
+				id: "change-1",
+				componentIds: ["context-file:CLIO-CODER.md"],
+				filesChanged: ["CLIO-CODER.md"],
+				authorityLevel: "prompt",
+				evidenceRefs: [],
+				rootCause: "First exploratory iteration; no evidence corpus exists yet.",
+				targetedFix: "Describe the smallest proposed harness change.",
+				predictedFixes: ["One expected improvement."],
+				predictedRegressions: [],
+				validationPlan: ["npm run test"],
+				rollbackPlan: "Revert the filesChanged entries for this change.",
+				expectedBudgetImpact: {
+					risk: "same",
+				},
+			},
+		],
+	};
+}
+
+export function isHighAuthorityLevel(level: ManifestAuthorityLevel): boolean {
+	return (HIGH_AUTHORITY_LEVELS as ReadonlyArray<ManifestAuthorityLevel>).includes(level);
+}
+
+export function allowsEmptyEvidenceRefs(iterationId: string): boolean {
+	return iterationId === FIRST_EXPLORATORY_ITERATION_ID;
+}
+
+export function summarizeChangeManifest(manifest: ChangeManifest): ChangeManifestSummary {
+	const authoritySet = new Set<ManifestAuthorityLevel>();
+	const componentIds = new Set<string>();
+	const filesChanged = new Set<string>();
+	const predictedRegressions = new Set<string>();
+	let validationPlanCount = 0;
+	for (const change of manifest.changes) {
+		authoritySet.add(change.authorityLevel);
+		for (const componentId of change.componentIds) componentIds.add(componentId);
+		for (const file of change.filesChanged) filesChanged.add(file);
+		for (const regression of change.predictedRegressions) predictedRegressions.add(regression);
+		validationPlanCount += change.validationPlan.length;
+	}
+	return {
+		iterationId: manifest.iterationId,
+		baseGitSha: manifest.baseGitSha,
+		changeCount: manifest.changes.length,
+		authorityLevels: MANIFEST_AUTHORITY_LEVELS.filter((level) => authoritySet.has(level)),
+		componentIds: [...componentIds].sort(compareStrings),
+		filesChanged: [...filesChanged].sort(compareStrings),
+		predictedRegressions: [...predictedRegressions].sort(compareStrings),
+		validationPlanCount,
+	};
+}
+
+function compareStrings(a: string, b: string): number {
+	return a.localeCompare(b);
+}