ultimate-pi 0.11.0 → 0.13.0

package/.pi/harness/specs/plan-packet.schema.json

@@ -2,7 +2,7 @@
 	"$schema": "https://json-schema.org/draft/2020-12/schema",
 	"$id": "https://ultimate-pi.local/.pi/harness/specs/plan-packet.schema.json",
 	"title": "PlanPacket",
-	"description": "Plan-gated mutation contract emitted before execution.",
+	"description": "Plan-gated mutation contract emitted before execution (instance files: plan-packet.yaml).",
 	"type": "object",
 	"additionalProperties": false,
 	"required": [
@@ -14,7 +14,8 @@
 		"assumptions",
 		"risk_level",
 		"acceptance_checks",
-		"rollback_plan"
+		"rollback_plan",
+		"execution_plan"
 	],
 	"properties": {
 		"schema_version": {
@@ -23,7 +24,7 @@
 		},
 		"contract_version": {
 			"type": "string",
-			"const": "1.0.0"
+			"enum": ["1.0.0", "1.1.0"]
 		},
 		"plan_id": {
 			"type": "string",
@@ -52,8 +53,13 @@
 			"type": "array",
 			"minItems": 1,
 			"items": {
-				"type": "string",
-				"minLength": 1
+				"type": "object",
+				"additionalProperties": false,
+				"required": ["id", "description"],
+				"properties": {
+					"id": { "type": "string", "pattern": "^AC-[0-9]+$" },
+					"description": { "type": "string", "minLength": 1 }
+				}
 			}
 		},
 		"rollback_plan": {
@@ -85,6 +91,9 @@
 					}
 				}
 			}
+		},
+		"execution_plan": {
+			"$ref": "plan-execution-plan.schema.json"
 		}
 	}
 }

package/.pi/harness/specs/plan-review-round-draft.schema.json

@@ -0,0 +1,68 @@
+{
+	"$schema": "https://json-schema.org/draft/2020-12/schema",
+	"$id": "https://ultimate-pi.local/.pi/harness/specs/plan-review-round-draft.schema.json",
+	"title": "PlanReviewRoundDraft",
+	"type": "object",
+	"additionalProperties": false,
+	"required": [
+		"schema_version",
+		"round_index",
+		"round_summary",
+		"review_gate_ready",
+		"recommended_packet_patches"
+	],
+	"properties": {
+		"schema_version": { "type": "string", "const": "1.0.0" },
+		"round_index": { "type": "integer", "minimum": 1, "maximum": 4 },
+		"debate_round_focus": {
+			"type": "string",
+			"enum": ["spec", "wbs", "schedule", "quality"]
+		},
+		"round_summary": { "type": "string", "minLength": 1 },
+		"validation_summary": { "type": "string" },
+		"adversary_summary": { "type": "string" },
+		"disputes": {
+			"type": "array",
+			"items": { "type": "string", "minLength": 1 }
+		},
+		"recommended_packet_patches": {
+			"type": "array",
+			"items": {
+				"type": "object",
+				"required": ["path", "value"],
+				"properties": {
+					"path": { "type": "string", "minLength": 1 },
+					"value": {}
+				}
+			}
+		},
+		"review_gate_ready": { "type": "boolean" },
+		"participants": {
+			"type": "array",
+			"items": { "type": "string", "minLength": 1 }
+		},
+		"claims": { "type": "array", "items": { "type": "string" } },
+		"rebuttals": { "type": "array", "items": { "type": "string" } },
+		"evidence_refs": { "type": "array", "items": { "type": "string" } },
+		"token_usage": {
+			"type": "object",
+			"properties": {
+				"per_agent": {
+					"type": "object",
+					"additionalProperties": { "type": "number" }
+				},
+				"round_total": { "type": "number" }
+			}
+		},
+		"consensus_delta": { "type": "number" },
+		"severity_scores": {
+			"type": "object",
+			"properties": {
+				"correctness": { "type": "number" },
+				"security": { "type": "number" },
+				"architecture": { "type": "number" },
+				"test_integrity": { "type": "number" }
+			}
+		}
+	}
+}

package/.pi/harness/specs/plan-sprint-audit-turn.schema.json

@@ -0,0 +1,29 @@
+{
+	"$schema": "https://json-schema.org/draft/2020-12/schema",
+	"$id": "https://ultimate-pi.local/.pi/harness/specs/plan-sprint-audit-turn.schema.json",
+	"title": "PlanSprintAuditTurn",
+	"type": "object",
+	"additionalProperties": false,
+	"required": ["schema_version", "round_index", "gaps", "recommendation"],
+	"properties": {
+		"schema_version": { "type": "string", "const": "1.0.0" },
+		"round_index": { "type": "integer", "minimum": 1, "maximum": 4 },
+		"gaps": {
+			"type": "array",
+			"items": { "type": "string", "minLength": 1 }
+		},
+		"checkpoint_issues": {
+			"type": "array",
+			"items": { "type": "string", "minLength": 1 }
+		},
+		"done_criteria_issues": {
+			"type": "array",
+			"items": { "type": "string", "minLength": 1 }
+		},
+		"recommendation": {
+			"type": "string",
+			"enum": ["proceed", "revise"]
+		},
+		"human_summary": { "type": "string" }
+	}
+}

package/.pi/harness/specs/plan-stack-brief.schema.json

@@ -0,0 +1,65 @@
+{
+	"$schema": "https://json-schema.org/draft/2020-12/schema",
+	"$id": "https://ultimate-pi.local/.pi/harness/specs/plan-stack-brief.schema.json",
+	"title": "PlanStackBrief",
+	"type": "object",
+	"additionalProperties": false,
+	"required": [
+		"schema_version",
+		"problem_framing",
+		"constraints",
+		"options",
+		"recommended_primary",
+		"rationale"
+	],
+	"properties": {
+		"schema_version": { "type": "string", "const": "1.0.0" },
+		"problem_framing": { "type": "string", "minLength": 1 },
+		"constraints": {
+			"type": "array",
+			"items": { "type": "string", "minLength": 1 }
+		},
+		"options": {
+			"type": "array",
+			"minItems": 1,
+			"items": { "$ref": "#/$defs/stack_option" }
+		},
+		"recommended_primary": { "type": "string", "minLength": 1 },
+		"rationale": { "type": "string", "minLength": 1 },
+		"open_questions": {
+			"type": "array",
+			"items": { "type": "string", "minLength": 1 }
+		}
+	},
+	"$defs": {
+		"stack_option": {
+			"type": "object",
+			"additionalProperties": false,
+			"required": [
+				"name",
+				"category",
+				"fit_summary",
+				"tradeoffs",
+				"risks",
+				"evidence_refs",
+				"recommendation_rank"
+			],
+			"properties": {
+				"name": { "type": "string" },
+				"category": { "type": "string" },
+				"fit_summary": { "type": "string" },
+				"tradeoffs": {
+					"type": "object",
+					"required": ["pros", "cons"],
+					"properties": {
+						"pros": { "type": "array", "items": { "type": "string" } },
+						"cons": { "type": "array", "items": { "type": "string" } }
+					}
+				},
+				"risks": { "type": "array", "items": { "type": "string" } },
+				"evidence_refs": { "type": "array", "items": { "type": "string" } },
+				"recommendation_rank": { "type": "integer", "minimum": 1 }
+			}
+		}
+	}
+}

package/.pi/harness/specs/plan-validation-turn.schema.json

@@ -0,0 +1,42 @@
+{
+	"$schema": "https://json-schema.org/draft/2020-12/schema",
+	"$id": "https://ultimate-pi.local/.pi/harness/specs/plan-validation-turn.schema.json",
+	"title": "PlanValidationTurn",
+	"type": "object",
+	"additionalProperties": false,
+	"required": [
+		"schema_version",
+		"round_index",
+		"debate_round_focus",
+		"checks",
+		"overall_ready"
+	],
+	"properties": {
+		"schema_version": { "type": "string", "const": "1.0.0" },
+		"round_index": { "type": "integer", "minimum": 1, "maximum": 4 },
+		"debate_round_focus": {
+			"type": "string",
+			"enum": ["spec", "wbs", "schedule", "quality"]
+		},
+		"checks": {
+			"type": "array",
+			"items": {
+				"type": "object",
+				"required": ["id", "status", "evidence"],
+				"properties": {
+					"id": { "type": "string" },
+					"status": { "type": "string", "enum": ["pass", "warn", "fail"] },
+					"evidence": { "type": "string" },
+					"work_item_id": { "type": "string" },
+					"phase_id": { "type": "string" }
+				}
+			}
+		},
+		"mitigations": {
+			"type": "array",
+			"items": { "type": "string", "minLength": 1 }
+		},
+		"overall_ready": { "type": "boolean" },
+		"human_summary": { "type": "string" }
+	}
+}

package/.pi/harness/specs/round-result.schema.json

@@ -46,7 +46,17 @@
 			"minItems": 2,
 			"items": {
 				"type": "string",
-				"enum": ["EvaluatorAgent", "AdversaryAgent", "TieBreakerAgent"]
+				"enum": [
+					"EvaluatorAgent",
+					"AdversaryAgent",
+					"TieBreakerAgent",
+					"PlanEvaluatorAgent",
+					"PlanAdversaryAgent",
+					"HypothesisValidatorAgent",
+					"SprintContractAuditorAgent",
+					"ReviewIntegratorAgent",
+					"StackResearchAgent"
+				]
 			}
 		},
 		"claims": {
@@ -80,7 +90,7 @@
 					"additionalProperties": {
 						"type": "integer",
 						"minimum": 0,
-						"maximum": 2500
+						"maximum": 35000
 					}
 				},
 				"round_total": {
@@ -101,19 +111,16 @@
 			"properties": {
 				"name": {
 					"type": "string",
-					"const": "aggressive"
+					"enum": ["aggressive", "plan"]
 				},
 				"max_rounds": {
-					"type": "integer",
-					"const": 6
+					"type": "integer"
 				},
 				"round_token_cap": {
-					"type": "integer",
-					"const": 2500
+					"type": "integer"
 				},
 				"debate_global_cap": {
-					"type": "integer",
-					"const": 35000
+					"type": "integer"
 				}
 			}
 		},

package/.pi/lib/debate-orchestrator-types.ts

@@ -0,0 +1,38 @@
+/** Shared debate bus participant types (plan + post-execute). */
+
+export type PostExecuteDebateParticipant =
+	| "EvaluatorAgent"
+	| "AdversaryAgent"
+	| "TieBreakerAgent";
+
+export type PlanDebateParticipant =
+	| "PlanEvaluatorAgent"
+	| "PlanAdversaryAgent"
+	| "HypothesisValidatorAgent"
+	| "SprintContractAuditorAgent"
+	| "ReviewIntegratorAgent"
+	| "StackResearchAgent";
+
+export type DebateParticipant =
+	| PostExecuteDebateParticipant
+	| PlanDebateParticipant;
+
+export const PLAN_DEBATE_PARTICIPANTS: PlanDebateParticipant[] = [
+	"PlanEvaluatorAgent",
+	"PlanAdversaryAgent",
+	"HypothesisValidatorAgent",
+	"SprintContractAuditorAgent",
+	"ReviewIntegratorAgent",
+	"StackResearchAgent",
+];
+
+export const POST_EXECUTE_DEBATE_PARTICIPANTS: PostExecuteDebateParticipant[] =
+	["EvaluatorAgent", "AdversaryAgent", "TieBreakerAgent"];
+
+export function isPlanDebateId(debateId: string): boolean {
+	return debateId.startsWith("plan-");
+}
+
+export function debatePhaseFromId(debateId: string): "plan" | "post_execute" {
+	return isPlanDebateId(debateId) ? "plan" : "post_execute";
+}

package/.pi/lib/harness-agent-discovery.mjs

@@ -0,0 +1,81 @@
+/**
+ * Shared agent discovery helpers (manifest + tests).
+ */
+
+import { createHash } from "node:crypto";
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join, relative } from "node:path";
+
+export function isSafeAgentId(id) {
+	if (!id || id.includes("..") || id.startsWith("/") || id.includes("\\")) {
+		return false;
+	}
+	return /^[a-zA-Z0-9][a-zA-Z0-9/_-]*$/.test(id);
+}
+
+export function sha256Content(content) {
+	return createHash("sha256").update(content, "utf8").digest("hex");
+}
+
+export function walkAgentsDir(rootDir, source, out) {
+	if (!existsSync(rootDir)) return;
+	const stack = [rootDir];
+	while (stack.length > 0) {
+		const dir = stack.pop();
+		let entries;
+		try {
+			entries = readdirSync(dir, { withFileTypes: true });
+		} catch {
+			continue;
+		}
+		for (const entry of entries) {
+			const full = join(dir, entry.name);
+			if (entry.isDirectory()) {
+				stack.push(full);
+				continue;
+			}
+			if (!entry.name.endsWith(".md")) continue;
+			const rel = relative(rootDir, full).replace(/\\/g, "/");
+			const id = rel.replace(/\.md$/i, "");
+			if (!isSafeAgentId(id)) continue;
+			let content;
+			try {
+				content = readFileSync(full, "utf-8");
+			} catch {
+				continue;
+			}
+			out.set(id, { id, path: full, source, content });
+		}
+	}
+}
+
+export function discoverFromRoots(packageAgentsDir, projectAgentsDir, globalAgentsDir) {
+	const files = new Map();
+	walkAgentsDir(packageAgentsDir, "package", files);
+	if (globalAgentsDir) walkAgentsDir(globalAgentsDir, "global", files);
+	walkAgentsDir(projectAgentsDir, "project", files);
+	return files;
+}
+
+export function getDriftReport(manifest, onDiskHashes) {
+	const items = [];
+	if (!manifest) {
+		return { ok: false, items: [{ id: "*", kind: "missing_on_disk" }] };
+	}
+	for (const [id, entry] of onDiskHashes) {
+		const expected = manifest.agents[id];
+		if (!expected) {
+			items.push({ id, kind: "missing_in_manifest" });
+			continue;
+		}
+		if (expected.sha256 !== entry.sha256) {
+			items.push({ id, kind: "hash_mismatch" });
+		}
+	}
+	for (const id of Object.keys(manifest.agents)) {
+		if (!onDiskHashes.has(id)) {
+			items.push({ id, kind: "missing_on_disk" });
+		}
+	}
+	return { ok: items.length === 0, items };
+}

package/.pi/lib/harness-run-context.ts

@@ -2,12 +2,13 @@
  * harness-run-context — shared types and helpers for active harness runs.
  *
  * Session entry `harness-run-context` is the live source of truth; disk mirrors:
- * - `.pi/harness/runs/<run_id>/run-context.json`
+ * - `.pi/harness/runs/<run_id>/run-context.yaml`
  * - `.pi/harness/active-run.json` (cross-session pointer)
  */
 
 import { mkdir, readFile, realpath, writeFile } from "node:fs/promises";
 import { isAbsolute, join, relative, resolve } from "node:path";
+import { readYamlFile, writeYamlFile } from "./harness-yaml.js";
 
 export type HarnessPhase =
 	| "plan"
@@ -67,6 +68,7 @@ export interface PlanPacketLike {
 	risk_level?: string;
 	assumptions?: unknown[];
 	rollback_plan?: unknown;
+	execution_plan?: unknown;
 }
 
 interface SessionEntryLike {
@@ -107,11 +109,22 @@ export function activeRunPointerPath(projectRoot: string): string {
 }
 
 export function runContextDiskPath(runId: string, projectRoot: string): string {
-	return join(harnessRunsRoot(projectRoot), runId, "run-context.json");
+	return join(harnessRunsRoot(projectRoot), runId, RUN_CONTEXT_BASENAME);
 }
 
 export function canonicalPlanPath(runId: string, projectRoot: string): string {
-	return join(harnessRunsRoot(projectRoot), runId, "plan-packet.json");
+	return join(harnessRunsRoot(projectRoot), runId, PLAN_PACKET_BASENAME);
+}
+
+export function canonicalResearchBriefPath(
+	runId: string,
+	projectRoot: string,
+): string {
+	return join(harnessRunsRoot(projectRoot), runId, RESEARCH_BRIEF_BASENAME);
+}
+
+export function runArtifactsDir(runId: string, projectRoot: string): string {
+	return join(harnessRunsRoot(projectRoot), runId, "artifacts");
 }
 
 export const PLAN_REVIEW_BASENAME = "plan-review.md";
@@ -123,7 +136,16 @@ export function canonicalPlanReviewPath(
 	return join(harnessRunsRoot(projectRoot), runId, PLAN_REVIEW_BASENAME);
 }
 
-const PLAN_PACKET_BASENAME = "plan-packet.json";
+export const PLAN_PACKET_BASENAME = "plan-packet.yaml";
+export const RUN_CONTEXT_BASENAME = "run-context.yaml";
+export const RESEARCH_BRIEF_BASENAME = "research-brief.yaml";
+
+const PLAN_RUN_SCOPED_ROOT_FILES = new Set([
+	PLAN_PACKET_BASENAME,
+	RESEARCH_BRIEF_BASENAME,
+	"plan-dag-validation.yaml",
+	PLAN_REVIEW_BASENAME,
+]);
 
 const MUTATING_FILE_TOOLS = new Set(["write", "edit"]);
 
@@ -208,7 +230,21 @@ export function extractWritePathFromToolInput(
 	return raw.trim();
 }
 
-/** True when absPath is the canonical plan-packet.json for the active run. */
+/** True when absPath is a plan-phase artifact under the active run directory. */
+export function isPlanRunScopedRelativePath(rel: string): boolean {
+	if (rel.startsWith("..") || isAbsolute(rel)) return false;
+	const parts = rel.split(/[/\\]/);
+	if (parts.length === 2 && PLAN_RUN_SCOPED_ROOT_FILES.has(parts[1])) {
+		return true;
+	}
+	if (parts.length === 3 && parts[1] === "artifacts") {
+		const file = parts[2];
+		return file.endsWith(".yaml") || file.endsWith(".yml");
+	}
+	return false;
+}
+
+/** True when absPath is a writable plan-run artifact for the active run. */
 export async function isPlanPhaseScopedWrite(
 	absPath: string,
 	runCtx: HarnessRunContext | null,
@@ -229,11 +265,9 @@ export async function isPlanPhaseScopedWrite(
 		runsReal = runsRoot;
 	}
 	const rel = relative(runsReal, resolved);
-	if (rel.startsWith("..") || isAbsolute(rel)) return false;
+	if (!isPlanRunScopedRelativePath(rel)) return false;
 	const parts = rel.split(/[/\\]/);
-	if (parts.length !== 2 || parts[1] !== PLAN_PACKET_BASENAME) return false;
-	if (parts[0] !== runCtx.run_id) return false;
-	return isCanonicalPlanPacketPath(resolved, projectRoot, runCtx.run_id);
+	return parts[0] === runCtx.run_id;
 }
 
 export function getLatestHarnessTurn(
@@ -497,19 +531,6 @@ export async function isPlanPhaseAllowedMutation(
 					'policy-gate: no active harness run. Run /harness-plan "<task>" first.',
 			};
 		}
-		if (
-			!hasPlanUserApproval(opts.entries, {
-				sincePlanCommand: true,
-				planId: runCtx.plan_id,
-			})
-		) {
-			return {
-				allowed: false,
-				isScopedPlanWrite: true,
-				reason:
-					"policy-gate: plan-packet.json write blocked until the user approves via approve_plan or ask_user (present the full plan, then Approve).",
-			};
-		}
 		if (opts.aborted) {
 			return { allowed: true, isScopedPlanWrite: true };
 		}
@@ -522,7 +543,7 @@ export async function isPlanPhaseAllowedMutation(
 		return {
 			allowed: false,
 			isScopedPlanWrite: true,
-			reason: `harness-run-context: plan-packet.json is read-only in phase '${phase}'.`,
+			reason: `harness-run-context: plan-packet.yaml is read-only in phase '${phase}'.`,
 		};
 	}
 
@@ -530,7 +551,7 @@ export async function isPlanPhaseAllowedMutation(
 		return {
 			allowed: false,
 			reason:
-				"policy-gate: mutating tool blocked because harness-abort lock is active. Attach a new approved plan via plan-packet.json first.",
+				"policy-gate: mutating tool blocked because harness-abort lock is active. Attach a new approved plan via plan-packet.yaml first.",
 		};
 	}
 
@@ -548,7 +569,7 @@ export async function isPlanPhaseAllowedMutation(
 
 	const allowedPath = runCtx?.run_id
 		? canonicalPlanPath(runCtx.run_id, projectRoot)
-		: ".pi/harness/runs/<run_id>/plan-packet.json";
+		: `.pi/harness/runs/<run_id>/${PLAN_PACKET_BASENAME}`;
 	return {
 		allowed: false,
 		reason: `policy-gate: ${toolName} blocked in phase '${phase}'. In plan phase only ${allowedPath} is writable after ask_user approval.`,
@@ -754,8 +775,11 @@ export async function loadRunContextFromDisk(
 	projectRoot: string,
 ): Promise<HarnessRunContext | null> {
 	try {
-		const raw = await readFile(runContextDiskPath(runId, projectRoot), "utf-8");
-		return normalizeRunContext(JSON.parse(raw) as Partial<HarnessRunContext>);
+		const doc = await readYamlFile(
+			runContextDiskPath(runId, projectRoot),
+			"run-context",
+		);
+		return normalizeRunContext(doc as Partial<HarnessRunContext>);
 	} catch {
 		return null;
 	}
@@ -766,11 +790,7 @@ export async function saveRunContextToDisk(
 ): Promise<void> {
 	const dir = join(harnessRunsRoot(ctx.project_root), ctx.run_id);
 	await mkdir(dir, { recursive: true });
-	await writeFile(
-		runContextDiskPath(ctx.run_id, ctx.project_root),
-		`${JSON.stringify(ctx, null, 2)}\n`,
-		"utf-8",
-	);
+	await writeYamlFile(runContextDiskPath(ctx.run_id, ctx.project_root), ctx);
 }
 
 export async function loadProjectActiveRun(
@@ -828,8 +848,8 @@ export async function readPlanPacketFromPath(
 	planPath: string,
 ): Promise<PlanPacketLike | null> {
 	try {
-		const raw = await readFile(planPath, "utf-8");
-		return JSON.parse(raw) as PlanPacketLike;
+		const doc = await readYamlFile(planPath, planPath);
+		return doc as PlanPacketLike;
 	} catch {
 		return null;
 	}
@@ -844,8 +864,11 @@ export function validatePlanPacket(packet: PlanPacketLike | null): {
 	const errors: string[] = [];
 	if (packet.schema_version !== "1.0.0")
 		errors.push("schema_version must be 1.0.0");
-	if (packet.contract_version !== "1.0.0")
-		errors.push("contract_version must be 1.0.0");
+	if (
+		packet.contract_version !== "1.0.0" &&
+		packet.contract_version !== "1.1.0"
+	)
+		errors.push("contract_version must be 1.0.0 or 1.1.0");
 	if (!packet.plan_id || typeof packet.plan_id !== "string")
 		errors.push("plan_id required");
 	if (!packet.task_id || typeof packet.task_id !== "string")
@@ -859,6 +882,9 @@ export function validatePlanPacket(packet: PlanPacketLike | null): {
 		errors.push("acceptance_checks required");
 	if (!packet.risk_level) errors.push("risk_level required");
 	if (!packet.rollback_plan) errors.push("rollback_plan required");
+	if (packet.contract_version === "1.1.0" && !packet.execution_plan) {
+		errors.push("execution_plan required for contract_version 1.1.0");
+	}
 	return { valid: errors.length === 0, errors };
 }
 
@@ -957,7 +983,7 @@ export function formatActivePlanBlock(
 		);
 	} else {
 		lines.push(
-			"Plan is read-only in this phase. Do not edit plan-packet.json.",
+			"Plan is read-only in this phase. Do not edit plan-packet.yaml.",
 		);
 	}
 	if (ctx.plan_packet_path) {
@@ -1016,7 +1042,7 @@ export function validatePlanOverridePath(
 	if (!isCanonicalPlanPacketPath(absPlan, projectRoot, runId)) {
 		return {
 			ok: false,
-			reason: `--plan must be runs/${runId}/plan-packet.json (canonical plan packet only)`,
+			reason: `--plan must be runs/${runId}/${PLAN_PACKET_BASENAME} (canonical plan packet only)`,
 		};
 	}
 	return { ok: true };