@iowarp/clio-coder 0.4.2 → 0.4.4

package/src/domains/agents/result-contract.ts

@@ -31,6 +31,7 @@ export type ResultContract =
 	| { kind: "council-ballot" }
 	| { kind: "debugger-report" }
 	| { kind: "research-report" }
+	| { kind: "world-knowledge-report" }
 	| { kind: "mutation-report" }
 	| { kind: "provenance-report" }
 	| { kind: "delegation-plan" }
@@ -594,6 +595,7 @@ const RESULT_CONTRACT_KINDS: ReadonlyArray<ResultContract["kind"]> = [
 	"council-report",
 	"debugger-report",
 	"research-report",
+	"world-knowledge-report",
 	"mutation-report",
 	"provenance-report",
 	"external-delegation",
@@ -1268,6 +1270,69 @@ function validateResearch(
 	return success(contract, "unmeasured", value);
 }
 
+function validateWorldKnowledge(
+	contract: ResultContract,
+	output: string | null,
+	externalSourcesAllowed: boolean,
+): ResultContractValidation {
+	const parsed = parseJson(output);
+	if (!parsed.ok) return failure(contract, "unmeasured", `World-knowledge payload failed: ${parsed.reason}`);
+	const value = parsed.value;
+	const legal = ["discovery", "facts", "synthesis", "uncertainties", "followUpVerification"];
+	const unknown = Object.keys(value).filter((key) => !legal.includes(key));
+	if (unknown.length > 0) {
+		return failure(contract, "unmeasured", `World-knowledge field '${unknown[0]}' is not legal`);
+	}
+	if (
+		value.discovery !== "performed" &&
+		value.discovery !== "caller-supplied-only" &&
+		value.discovery !== "unavailable"
+	) {
+		return failure(
+			contract,
+			"unmeasured",
+			'World-knowledge field "discovery" must be one of: performed | caller-supplied-only | unavailable',
+		);
+	}
+	if (value.discovery === "performed" && !externalSourcesAllowed) {
+		return failure(
+			contract,
+			"unmeasured",
+			'World-knowledge field "discovery" is performed but this run had no external-source posture',
+		);
+	}
+	if (!Array.isArray(value.facts)) {
+		return failure(contract, "unmeasured", 'World-knowledge field "facts" must be an array');
+	}
+	for (const [index, finding] of value.facts.entries()) {
+		if (!finding || typeof finding !== "object" || Array.isArray(finding)) {
+			return failure(contract, "unmeasured", `World-knowledge field "facts[${index}]" must be an object`);
+		}
+		const fact = finding as Record<string, unknown>;
+		const factUnknown = Object.keys(fact).filter((key) => !["claim", "evidence", "sources"].includes(key));
+		if (factUnknown.length > 0) {
+			return failure(contract, "unmeasured", `World-knowledge field "facts[${index}].${factUnknown[0]}" is not legal`);
+		}
+		if (!string(fact.claim) || !string(fact.evidence) || !Array.isArray(fact.sources)) {
+			return failure(
+				contract,
+				"unmeasured",
+				`World-knowledge field "facts[${index}]" requires non-empty claim/evidence strings and a sources array`,
+			);
+		}
+		if (fact.sources.some((source) => !string(source))) {
+			return failure(contract, "unmeasured", `World-knowledge field "facts[${index}].sources" must contain strings`);
+		}
+	}
+	for (const field of ["synthesis", "uncertainties", "followUpVerification"] as const) {
+		const entries = value[field];
+		if (!Array.isArray(entries) || entries.some((entry) => !string(entry))) {
+			return failure(contract, "unmeasured", `World-knowledge field "${field}" must be an array of non-empty strings`);
+		}
+	}
+	return success(contract, "unmeasured", value);
+}
+
 /** Paths this run wrote, as workspace-relative names, for a validator reason. */
 function describeWriteSet(effects: ObservedRunEffects, cwd: string): string {
 	if (effects.mutatedPaths.size === 0) return "this run wrote nothing";
@@ -1465,6 +1530,8 @@ export function validateResultContract(input: ResultContractValidationInput): Re
 			return validateDebugger(input.contract, input.output);
 		case "research-report":
 			return validateResearch(input.contract, input.output, input.networkAllowed);
+		case "world-knowledge-report":
+			return validateWorldKnowledge(input.contract, input.output, input.networkAllowed);
 		case "mutation-report":
 			return validateMutation(input.contract, input);
 		case "provenance-report":
@@ -1566,6 +1633,8 @@ export function resultContractShape(contract: ResultContract): string {
 			return 'one of {"diagnosis":"...","reproduction":"reproduced","evidence":["..."]}, {"diagnosis":"...","reproduction":"not-reproduced","evidence":["..."]}, or {"diagnosis":"...","reproduction":"unknown","evidence":["..."]}; reproduction legal values are reproduced | not-reproduced | unknown';
 		case "research-report":
 			return 'one of {"source":"local","findings":[{"claim":"...","evidence":"..."}]} or {"source":"external","findings":[{"claim":"...","evidence":"..."}]}; source legal values are local | external';
+		case "world-knowledge-report":
+			return '{"discovery":"performed|caller-supplied-only|unavailable","facts":[{"claim":"...","evidence":"...","sources":["URL or document id"]}],"synthesis":["comparison or advisory conclusion"],"uncertainties":["..."],"followUpVerification":["..."]}';
 		case "mutation-report":
 			return '{"mutatedPaths":["src/file.ts"],"validations":[{"name":"npm test","passed":true,"evidence":"exit 0"}],"commitMessage":"optional: the commit message for this change","summary":"optional: one line"}';
 		case "provenance-report":
@@ -1685,6 +1754,7 @@ const RECIPE_DECLARABLE_KINDS = [
 	"council-report",
 	"debugger-report",
 	"research-report",
+	"world-knowledge-report",
 	"mutation-report",
 	"provenance-report",
 	"oracle-report",

package/src/domains/context/extension.ts

@@ -2,8 +2,13 @@ import { existsSync } from "node:fs";
 import { isAbsolute, join, relative, resolve } from "node:path";
 import { BusChannels, type ContextActivityPayload } from "../../core/bus-events.js";
 import type { DomainBundle, DomainContext, DomainExtension } from "../../core/domain-loader.js";
-import { clioDataDir } from "../../core/xdg.js";
+import { clioDataDir, clioStateDir } from "../../core/xdg.js";
 import { loadMemoryRecordsSync } from "../memory/index.js";
+import { describeValidationContract, loadValidationContract } from "../safety/index.js";
+import { readSessionEntriesForId } from "../session/archive-readers.js";
+import type { SessionContract } from "../session/contract.js";
+import { foldDecisionBoard } from "../session/decision-board.js";
+import { filterEntriesToActivePath } from "../session/tree/active-path.js";
 import { detectProjectType, type ProjectType } from "../session/workspace/project-type.js";
 import { adoptionSourcesChanged } from "./adoption.js";
 import { runBootstrap } from "./bootstrap.js";
@@ -148,6 +153,12 @@ function collectStartupHints(cwd: string, options: ContextBundleOptions = {}): s
 	for (const issue of clio.errors) {
 		hints.push(`clio-coder: malformed ${issue.path} ignored: ${issue.error}`);
 	}
+	// An invalid validation contract leaves rigor at normal; say so once here
+	// rather than letting the finish gate quietly behave as if no contract existed.
+	const contract = loadValidationContract(cwd);
+	if (!contract.ok) {
+		hints.push(`clio-coder: validation contract ignored, rigor stays normal: ${describeValidationContract(contract)}`);
+	}
 	const state = readClioState(cwd);
 	if (!state) return hints;
 	if (state.contextSources !== undefined && adoptionSourcesChanged(state.contextSources, { cwd })) {
@@ -290,9 +301,11 @@ export function createContextBundle(
 				input?.onProgress?.(event);
 			};
 			try {
-				const result = await runContextRefresh(
-					input ? { ...input, onProgress: emitProgress } : { onProgress: emitProgress },
-				);
+				const result = await runContextRefresh({
+					...input,
+					...(input?.wiki ? { decisions: input.decisions ?? (await currentDecisions(_context)) } : {}),
+					onProgress: emitProgress,
+				});
 				const cwd = input?.cwd ?? process.cwd();
 				contextState.invalidate(cwd);
 				if (cwd === lastCwd) startupHints = collectStartupHints(cwd, options);
@@ -313,9 +326,11 @@ export function createContextBundle(
 				input?.onProgress?.(event);
 			};
 			try {
-				return await runWikiGenerate(
-					input ? { ...input, onProgress: emitProgress } : { model: "configured-clio-target", onProgress: emitProgress },
-				);
+				return await runWikiGenerate({
+					...(input ?? { model: "configured-clio-target" }),
+					decisions: input?.decisions ?? (await currentDecisions(_context)),
+					onProgress: emitProgress,
+				});
 			} catch (err) {
 				emitProgress({
 					phase: "done",
@@ -353,3 +368,12 @@ export function createContextBundle(
 
 	return { extension, contract };
 }
+
+async function currentDecisions(context: DomainContext) {
+	const session = context.getContract<SessionContract>("session");
+	const current = session?.current();
+	if (!session || !current) return [];
+	session.flushAppends?.();
+	const read = await readSessionEntriesForId(clioStateDir(), current.id);
+	return foldDecisionBoard(filterEntriesToActivePath(read.entries, session.tree(current.id).leafId ?? undefined));
+}

package/src/domains/context/refresh.ts

@@ -1,5 +1,6 @@
 import { writeFileSync } from "node:fs";
 import { join } from "node:path";
+import type { DecisionLedgerEntry } from "../session/entries.js";
 import { detectProjectType } from "../session/workspace/project-type.js";
 import { type BootstrapIo, type BootstrapProgressSink, codewikiSections } from "./bootstrap.js";
 import { serializeClioMd, tryReadClioMd } from "./clio-md.js";
@@ -18,6 +19,7 @@ import { wikiCompleteness, wikiStaleness } from "./wiki/staleness.js";
  */
 
 export interface RunContextRefreshInput {
+	decisions?: ReadonlyArray<DecisionLedgerEntry>;
 	cwd?: string;
 	io?: BootstrapIo;
 	now?: () => Date;
@@ -146,6 +148,7 @@ export async function runContextRefresh(input: RunContextRefreshInput = {}): Pro
 		wikiResult = await runWikiGenerate({
 			cwd,
 			mode: "update",
+			...(input.decisions ? { decisions: input.decisions } : {}),
 			model: input.wikiModel ?? "unresolved-documenter-target",
 			...(input.wikiGenerate ? { generate: input.wikiGenerate } : {}),
 			...(input.onProgress ? { onProgress: input.onProgress } : {}),

package/src/domains/context/wiki/frontmatter.ts

@@ -35,6 +35,8 @@ export interface WikiPageMetadata {
 	invariants: string[];
 	/** Narrowest non-destructive commands that check this area. */
 	validate: string[];
+	/** Stable refs for recorded decisions cited in the body. */
+	decisions?: string[];
 }
 
 export interface WikiPageDocument {
@@ -47,7 +49,7 @@ export interface WikiPageDocument {
 
 const FRONTMATTER_BLOCK = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/;
 
-const LIST_FIELDS = ["sources", "symbols", "tests", "invariants", "validate"] as const;
+const LIST_FIELDS = ["sources", "symbols", "tests", "invariants", "validate", "decisions"] as const;
 
 /** Longest generated summary, so an index line stays one line. */
 const SUMMARY_MAX_CHARS = 240;
@@ -166,6 +168,7 @@ export function readWikiPage(input: ReadWikiPageInput): WikiPageDocument {
 		tests: [],
 		invariants: stringList(authored.invariants),
 		validate: stringList(authored.validate),
+		...(authored.decisions === undefined ? {} : { decisions: stringList(authored.decisions) }),
 	};
 	const unresolvedPaths: string[] = [];
 	for (const field of ["sources", "tests"] as const) {
@@ -189,7 +192,7 @@ function renderList(name: string, values: ReadonlyArray<string>): string[] {
 function renderFrontmatter(metadata: WikiPageMetadata): string {
 	const lines = [`title: ${JSON.stringify(metadata.title)}`];
 	if (metadata.summary.length > 0) lines.push(`summary: ${JSON.stringify(metadata.summary)}`);
-	for (const field of LIST_FIELDS) lines.push(...renderList(field, metadata[field]));
+	for (const field of LIST_FIELDS) lines.push(...renderList(field, metadata[field] ?? []));
 	return `---\n${lines.join("\n")}\n---\n`;
 }
 

package/src/domains/context/wiki/generate.ts

@@ -14,6 +14,7 @@ import {
 } from "node:fs";
 import { dirname, join } from "node:path";
 import type { ContextActivityPayload } from "../../../core/bus-events.js";
+import type { DecisionLedgerEntry } from "../../session/entries.js";
 import { detectProjectType } from "../../session/workspace/project-type.js";
 import type { BootstrapProgressSink } from "../bootstrap.js";
 import { coordinateCodewikiWrite } from "../codewiki/coordinator.js";
@@ -44,6 +45,8 @@ import { changedPathsSince } from "./staleness.js";
 export type { WikiDepth, WikiGenerateMode };
 
 export interface WikiGenerateInput {
+	/** The current session board, already scoped to its active branch. */
+	decisions?: ReadonlyArray<DecisionLedgerEntry>;
 	cwd: string;
 	mode: WikiGenerateMode;
 	/**
@@ -76,6 +79,8 @@ export interface WikiGenerateInput {
 export type WikiGenerate = (input: WikiGenerateInput) => void | Promise<void>;
 
 export interface RunWikiGenerateInput {
+	/** The current session board, already scoped to its active branch. */
+	decisions?: ReadonlyArray<DecisionLedgerEntry>;
 	cwd?: string;
 	mode?: WikiGenerateMode;
 	/** Repository-detail policy. Auto scales decomposition from indexed files and lines. */
@@ -473,6 +478,7 @@ export async function runWikiGenerate(
 				plan: resolved.plan,
 				resumed: resolved.resumed,
 				unclaimedAreas: resolved.unclaimedAreas,
+				...(input.decisions ? { decisions: input.decisions } : {}),
 				gitHead: existingMeta?.gitHead ?? null,
 				...(input.onProgress ? { progress: input.onProgress } : {}),
 			});