ultimate-pi 0.20.0 → 0.22.0

package/.pi/lib/ask-user/validate-core.mjs

@@ -1,7 +1,12 @@
-/** Keep in sync with validate.ts — test entrypoint for node --test */
+/** Keep in sync with validate.ts + format.ts — test entrypoint for node --test */
+
+import { createRequire } from "node:module";
+import { MAX_QUESTIONNAIRE_QUESTIONS } from "./constants.mjs";
+
+const require = createRequire(import.meta.url);
 
 /**
- * @param {string | { title: string, description?: string }} raw
+ * @param {string | { title: string, description?: string, recommended?: boolean }} raw
  */
 export function normalizeOption(raw) {
 	if (typeof raw === "string") {
@@ -10,6 +15,26 @@ export function normalizeOption(raw) {
 	return {
 		title: raw.title.trim(),
 		description: raw.description?.trim() || undefined,
+		recommended: raw.recommended === true ? true : undefined,
+	};
+}
+
+function normalizeQuestion(raw) {
+	const title = raw.title?.trim();
+	if (!title) return "ask_user: each questions[] item requires title";
+
+	const options = (raw.options ?? [])
+		.map(normalizeOption)
+		.filter((o) => o.title);
+	if (options.length > 0 && options.length < 2) {
+		return `ask_user: question "${title}" needs at least 2 options or omit options for freeform`;
+	}
+
+	return {
+		title,
+		description: raw.description?.trim() || undefined,
+		options,
+		allowMultiple: raw.allowMultiple === true,
 	};
 }
 
@@ -20,6 +45,22 @@ export function validateAskParams(params) {
 		return "ask_user: question is required";
 	}
 
+	const rawQuestions = params.questions ?? [];
+	if (rawQuestions.length > MAX_QUESTIONNAIRE_QUESTIONS) {
+		return `ask_user: at most ${MAX_QUESTIONNAIRE_QUESTIONS} questions in questionnaire mode`;
+	}
+
+	if (rawQuestions.length > 0 && (params.options?.length ?? 0) > 0) {
+		return "ask_user: use either options or questions[], not both";
+	}
+
+	const questions = [];
+	for (const q of rawQuestions) {
+		const normalized = normalizeQuestion(q);
+		if (typeof normalized === "string") return normalized;
+		questions.push(normalized);
+	}
+
 	const options = (params.options ?? [])
 		.map(normalizeOption)
 		.filter((o) => o.title);
@@ -28,7 +69,9 @@ export function validateAskParams(params) {
 	}
 
 	const allowFreeform = params.allowFreeform !== false;
-	if (options.length === 0 && !allowFreeform) {
+	const mode = questions.length > 0 ? "questionnaire" : "flat";
+
+	if (mode === "flat" && options.length === 0 && !allowFreeform) {
 		return "ask_user: options required when allowFreeform is false";
 	}
 
@@ -42,9 +85,15 @@ export function validateAskParams(params) {
 	return {
 		question,
 		context: params.context?.trim() || undefined,
+		contextFormat:
+			params.contextFormat === "html" ? "html" : "markdown",
 		options,
+		questions,
+		mode,
 		allowMultiple: params.allowMultiple === true,
 		allowFreeform,
+		allowComment: params.allowComment === true,
+		allowSkip: params.allowSkip === true,
 		displayMode,
 		timeout:
 			typeof params.timeout === "number" && params.timeout > 0
@@ -53,14 +102,30 @@ export function validateAskParams(params) {
 	};
 }
 
-/** @param {import('./types.js').AskResponse | null} response @param {boolean} cancelled */
-export function formatResultText(response, cancelled) {
+/** @param {import('./types.js').AskResponse | null} response @param {boolean} cancelled @param {{ ui_degraded?: boolean }} [opts] */
+export function formatResultText(response, cancelled, opts) {
 	if (cancelled || !response) {
 		return "User cancelled (no answer)";
 	}
+	if (opts?.ui_degraded) {
+		return `Rich ask UI unavailable; using terminal prompt.\n\n${formatResponseBody(response)}`;
+	}
+	return formatResponseBody(response);
+}
+
+/** @param {import('./types.js').AskResponse} response */
+function formatResponseBody(response) {
 	if (response.kind === "freeform") {
 		return `User wrote: ${response.text}`;
 	}
+	if (response.kind === "questionnaire") {
+		const lines = response.questionnaireDetails.map((d) => {
+			let line = `- ${d.question}: ${d.answer}`;
+			if (d.comment) line += ` (comment: ${d.comment})`;
+			return line;
+		});
+		return `User answered questionnaire:\n${lines.join("\n")}`;
+	}
 	if (response.selections.length === 1) {
 		return `User selected: ${response.selections[0]}`;
 	}
@@ -68,12 +133,133 @@ export function formatResultText(response, cancelled) {
 }
 
 /** @param {import('./types.js').ValidatedAskParams} validated */
-export function toToolDetails(validated, response, cancelled) {
+export function toToolDetails(validated, response, cancelled, ui_backend = "headless", opts = {}) {
+	const options =
+		validated.mode === "questionnaire"
+			? validated.questions.map((q) => q.title)
+			: validated.options.map((o) => o.title);
 	return {
 		question: validated.question,
 		context: validated.context,
-		options: validated.options.map((o) => o.title),
+		contextFormat: validated.contextFormat,
+		options,
 		response,
 		cancelled,
+		ui_backend,
+		ui_degraded: opts.ui_degraded,
+	};
+}
+
+export { isPlanApprovalAskUser } from "./policy.mjs";
+
+/** @param {import('./types.js').ValidatedAskParams} validated */
+export function buildGlimpsePayload(validated, sessionName) {
+	const hasQuestions = validated.mode === "questionnaire";
+	const hasOptions = validated.options.length > 0;
+	let payloadType;
+	if (hasQuestions) payloadType = "questionnaire";
+	else if (!hasOptions) payloadType = "freeform";
+	else if (validated.allowMultiple) payloadType = "multi-select";
+	else payloadType = "single-select";
+
+	let question = validated.question;
+	let context = validated.context;
+	if (!context && validated.question.length > 120) {
+		const match = validated.question.match(/^(.+?[.?!])(\s+|$)/);
+		if (match && match[0].length < validated.question.length) {
+			question = match[1].trim();
+			context = validated.question.slice(match[0].length).trim();
+		}
+	}
+
+	return {
+		type: payloadType,
+		question,
+		context,
+		contextFormat: validated.contextFormat,
+		options: validated.options.map((o) => ({
+			title: o.title,
+			description: o.description,
+			recommended: o.recommended,
+		})),
+		questions: validated.questions.map((q) => ({
+			title: q.title,
+			description: q.description,
+			allowMultiple: q.allowMultiple,
+			options: q.options.map((o) => ({
+				title: o.title,
+				description: o.description,
+				recommended: o.recommended,
+			})),
+		})),
+		allowMultiple: validated.allowMultiple,
+		allowFreeform: validated.allowFreeform,
+		allowComment: validated.allowComment,
+		allowSkip: validated.allowSkip,
+		sessionName,
+	};
+}
+
+function isGlimpseAvailable() {
+	try {
+		require.resolve("@alexleekt/pi-ask-user-glimpse/package.json");
+		require.resolve("glimpseui");
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+/** @param {import('./types.js').ValidatedAskParams} validated @param {boolean} hasUI */
+export function resolvePresenterChoice(validated, hasUI) {
+	if (validated.displayMode === "inline") return "tui";
+
+	const forced = process.env.HARNESS_ASK_USER_UI?.toLowerCase();
+	if (forced === "tui") return "tui";
+	if (forced === "glimpse") return "glimpse";
+	if (forced === "headless") return "headless";
+	if (hasUI && isGlimpseAvailable()) return "glimpse";
+	if (hasUI) return "tui";
+	return "headless";
+}
+
+/** @param {Record<string, unknown>} doc @param {import('./types.js').AskToolDetails} details */
+export function applyAskUserToTaskClarification(doc, details) {
+	const next = { ...doc };
+	const assumptions = Array.isArray(next.assumptions) ? [...next.assumptions] : [];
+	if (!details.response || details.cancelled) return next;
+
+	const applyPair = (question, answer) => {
+		const n = question.toLowerCase();
+		if (n.includes("done") || n.includes("success")) {
+			next.success_definition = answer;
+			return;
+		}
+		if (n.includes("risk")) {
+			const a = answer.toLowerCase();
+			if (/\blow\b/.test(a)) next.risk_level = "low";
+			else if (/\bhigh\b/.test(a)) next.risk_level = "high";
+			else if (/\bmed/.test(a) || /\bmedium\b/.test(a)) next.risk_level = "med";
+			return;
+		}
+		if (n.includes("scope") || n.includes("in scope")) {
+			const items = answer.split(/[,;\n]/).map((s) => s.trim()).filter(Boolean);
+			if (items.length) next.in_scope = items;
+			return;
+		}
+		assumptions.push(`${question}: ${answer}`);
 	};
+
+	const r = details.response;
+	if (r.kind === "questionnaire") {
+		for (const d of r.questionnaireDetails) applyPair(d.question, d.answer);
+	} else if (r.kind === "freeform") {
+		applyPair(details.question, r.text);
+	} else if (r.kind === "selection") {
+		applyPair(details.question, r.selections.join(", "));
+	}
+
+	if (assumptions.length) next.assumptions = assumptions;
+	if (Array.isArray(next.unresolved_questions)) next.unresolved_questions = [];
+	return next;
 }

package/.pi/lib/ask-user/validate.ts

@@ -1,15 +1,15 @@
+import { MAX_QUESTIONNAIRE_QUESTIONS } from "./constants.js";
 import type {
-	AskResponse,
-	AskToolDetails,
 	AskUserParams,
 	NormalizedOption,
+	NormalizedQuestion,
 	ValidatedAskParams,
 } from "./types.js";
 
 export type { ValidatedAskParams };
 
 export function normalizeOption(
-	raw: string | { title: string; description?: string },
+	raw: string | { title: string; description?: string; recommended?: boolean },
 ): NormalizedOption {
 	if (typeof raw === "string") {
 		return { title: raw.trim() };
@@ -17,6 +17,28 @@ export function normalizeOption(
 	return {
 		title: raw.title.trim(),
 		description: raw.description?.trim() || undefined,
+		recommended: raw.recommended === true ? true : undefined,
+	};
+}
+
+function normalizeQuestion(
+	raw: NonNullable<AskUserParams["questions"]>[number],
+): NormalizedQuestion | string {
+	const title = raw.title?.trim();
+	if (!title) return "ask_user: each questions[] item requires title";
+
+	const options = (raw.options ?? [])
+		.map(normalizeOption)
+		.filter((o) => o.title);
+	if (options.length > 0 && options.length < 2) {
+		return `ask_user: question "${title}" needs at least 2 options or omit options for freeform`;
+	}
+
+	return {
+		title,
+		description: raw.description?.trim() || undefined,
+		options,
+		allowMultiple: raw.allowMultiple === true,
 	};
 }
 
@@ -28,6 +50,22 @@ export function validateAskParams(
 		return "ask_user: question is required";
 	}
 
+	const rawQuestions = params.questions ?? [];
+	if (rawQuestions.length > MAX_QUESTIONNAIRE_QUESTIONS) {
+		return `ask_user: at most ${MAX_QUESTIONNAIRE_QUESTIONS} questions in questionnaire mode`;
+	}
+
+	if (rawQuestions.length > 0 && (params.options?.length ?? 0) > 0) {
+		return "ask_user: use either options or questions[], not both";
+	}
+
+	const questions: NormalizedQuestion[] = [];
+	for (const q of rawQuestions) {
+		const normalized = normalizeQuestion(q);
+		if (typeof normalized === "string") return normalized;
+		questions.push(normalized);
+	}
+
 	const options = (params.options ?? [])
 		.map(normalizeOption)
 		.filter((o) => o.title);
@@ -36,10 +74,16 @@ export function validateAskParams(
 	}
 
 	const allowFreeform = params.allowFreeform !== false;
-	if (options.length === 0 && !allowFreeform) {
+	const mode = questions.length > 0 ? "questionnaire" : "flat";
+
+	if (mode === "flat" && options.length === 0 && !allowFreeform) {
 		return "ask_user: options required when allowFreeform is false";
 	}
 
+	if (mode === "questionnaire" && questions.length === 0) {
+		return "ask_user: questions[] must not be empty";
+	}
+
 	const displayMode =
 		process.env.HARNESS_ASK_USER_DISPLAY_MODE === "inline"
 			? "inline"
@@ -50,9 +94,14 @@ export function validateAskParams(
 	return {
 		question,
 		context: params.context?.trim() || undefined,
+		contextFormat: params.contextFormat === "html" ? "html" : "markdown",
 		options,
+		questions,
+		mode,
 		allowMultiple: params.allowMultiple === true,
 		allowFreeform,
+		allowComment: params.allowComment === true,
+		allowSkip: params.allowSkip === true,
 		displayMode,
 		timeout:
 			typeof params.timeout === "number" && params.timeout > 0
@@ -60,33 +109,3 @@ export function validateAskParams(
 				: undefined,
 	};
 }
-
-export function formatResultText(
-	response: AskResponse | null,
-	cancelled: boolean,
-): string {
-	if (cancelled || !response) {
-		return "User cancelled (no answer)";
-	}
-	if (response.kind === "freeform") {
-		return `User wrote: ${response.text}`;
-	}
-	if (response.selections.length === 1) {
-		return `User selected: ${response.selections[0]}`;
-	}
-	return `User selected: ${response.selections.join(", ")}`;
-}
-
-export function toToolDetails(
-	validated: ValidatedAskParams,
-	response: AskResponse | null,
-	cancelled: boolean,
-): AskToolDetails {
-	return {
-		question: validated.question,
-		context: validated.context,
-		options: validated.options.map((o) => o.title),
-		response,
-		cancelled,
-	};
-}

package/.pi/lib/harness-anchored-edit/package.json

@@ -0,0 +1,3 @@
+{
+	"type": "module"
+}

package/.pi/lib/harness-artifact-gate.ts

@@ -7,6 +7,10 @@ import { access, readFile, stat } from "node:fs/promises";
 import { join } from "node:path";
 import { parse as parseYaml } from "yaml";
 import { validateAgainstHarnessSchema } from "./harness-schema-validate.js";
+import {
+	TASK_CLARIFICATION_ARTIFACT,
+	validateTaskClarificationDoc,
+} from "./plan-task-clarification.js";
 
 export interface ArtifactGateResult {
 	ok: boolean;
@@ -19,12 +23,15 @@ const ARTIFACT_SCHEMA: Record<string, string> = {
 	"artifacts/implementation-research.yaml":
 		"plan-implementation-research-brief.schema.json",
 	"artifacts/stack.yaml": "plan-stack-brief.schema.json",
+	"artifacts/task-clarification.yaml": "plan-task-clarification.schema.json",
 	"artifacts/planning-context.yaml": "plan-planning-context.schema.json",
 	"artifacts/eval-verdict.yaml": "eval-verdict.schema.json",
 	"artifacts/adversary-report.yaml": "adversary-report.schema.json",
+	"artifacts/sentrux-repair-plan.yaml": "sentrux-repair-plan.schema.json",
 };
 
 const PREREQUISITE_ORDER: Record<string, string[]> = {
+	"artifacts/planning-context.yaml": [TASK_CLARIFICATION_ARTIFACT],
 	"artifacts/hypothesis.yaml": ["artifacts/decomposition.yaml"],
 	"artifacts/implementation-research.yaml": [
 		"artifacts/decomposition.yaml",
@@ -53,6 +60,63 @@ function artifactStatusBad(doc: Record<string, unknown>): string | null {
 	return null;
 }
 
+async function validatePlanningContextArtifact(
+	normalized: string,
+	doc: Record<string, unknown>,
+): Promise<string[]> {
+	const errors: string[] = [];
+	if (normalized !== "artifacts/planning-context.yaml") return errors;
+	const statusErr = artifactStatusBad(doc);
+	if (statusErr) errors.push(`${normalized}: ${statusErr}`);
+	const coverage = doc.coverage as Record<string, unknown> | undefined;
+	if (!coverage || typeof coverage !== "object") return errors;
+	for (const lane of ["architecture", "structure"] as const) {
+		const laneDoc = coverage[lane] as Record<string, unknown> | undefined;
+		const laneStatus = String(laneDoc?.status ?? "").toLowerCase();
+		if (laneStatus !== "ok" && laneStatus !== "partial") {
+			errors.push(
+				`${normalized}: coverage.${lane}.status must be ok or partial (got "${laneStatus || "missing"}")`,
+			);
+		}
+	}
+	return errors;
+}
+
+async function validateArtifactPrerequisites(
+	runRoot: string,
+	normalized: string,
+	prereqs: string[],
+): Promise<string[]> {
+	const errors: string[] = [];
+	for (const prereq of prereqs) {
+		const prereqPath = join(runRoot, prereq);
+		if (!(await fileExists(prereqPath))) {
+			errors.push(`${normalized}: prerequisite missing (${prereq})`);
+			continue;
+		}
+		if (prereq !== TASK_CLARIFICATION_ARTIFACT) continue;
+		try {
+			const raw = await readFile(prereqPath, "utf-8");
+			const prereqDoc = parseYaml(raw) as Record<string, unknown>;
+			const clar = validateTaskClarificationDoc(prereqDoc, {
+				requireReady: true,
+			});
+			if (!clar.ok) {
+				errors.push(
+					...clar.errors.map(
+						(e) => `${normalized}: prerequisite ${prereq} — ${e}`,
+					),
+				);
+			}
+		} catch {
+			errors.push(
+				`${normalized}: prerequisite ${prereq} invalid or unreadable`,
+			);
+		}
+	}
+	return errors;
+}
+
 export async function validateHarnessArtifactFile(
 	runRoot: string,
 	relPath: string,
@@ -102,32 +166,22 @@ export async function validateHarnessArtifactFile(
 		}
 	}
 
-	if (doc && normalized === "artifacts/planning-context.yaml") {
-		const statusErr = artifactStatusBad(doc);
-		if (statusErr) {
-			errors.push(`${normalized}: ${statusErr}`);
-		}
-		const coverage = doc.coverage as Record<string, unknown> | undefined;
-		if (coverage && typeof coverage === "object") {
-			for (const lane of ["architecture", "structure"] as const) {
-				const laneDoc = coverage[lane] as Record<string, unknown> | undefined;
-				const laneStatus = String(laneDoc?.status ?? "").toLowerCase();
-				if (laneStatus !== "ok" && laneStatus !== "partial") {
-					errors.push(
-						`${normalized}: coverage.${lane}.status must be ok or partial (got "${laneStatus || "missing"}")`,
-					);
-				}
-			}
+	if (doc && normalized === TASK_CLARIFICATION_ARTIFACT) {
+		const clar = validateTaskClarificationDoc(doc, { requireReady: true });
+		if (!clar.ok) {
+			errors.push(...clar.errors.map((e) => `${normalized}: ${e}`));
 		}
 	}
 
-	const prereqs = PREREQUISITE_ORDER[normalized] ?? [];
-	for (const prereq of prereqs) {
-		if (!(await fileExists(join(runRoot, prereq)))) {
-			errors.push(`${normalized}: prerequisite missing (${prereq})`);
-		}
+	if (doc) {
+		errors.push(...(await validatePlanningContextArtifact(normalized, doc)));
 	}
 
+	const prereqs = PREREQUISITE_ORDER[normalized] ?? [];
+	errors.push(
+		...(await validateArtifactPrerequisites(runRoot, normalized, prereqs)),
+	);
+
 	return { ok: errors.length === 0, errors };
 }