ultimate-pi 0.18.0 → 0.19.0

package/.pi/scripts/harness-sentrux-cli.mjs

@@ -0,0 +1,142 @@
+#!/usr/bin/env node
+/**
+ * Run the Sentrux CLI against the harness project root.
+ *
+ * Sentrux resolves `.sentrux/rules.toml` relative to the PATH argument, so
+ * harness commands must not rely on the current working directory. This helper
+ * finds the nearest ancestor with harness Sentrux config and passes that root
+ * explicitly to `sentrux check` / `sentrux gate`.
+ *
+ * Usage:
+ *   node "$UP_PKG/.pi/scripts/harness-sentrux-cli.mjs" check [--root <PROJECT_ROOT>]
+ *   node "$UP_PKG/.pi/scripts/harness-sentrux-cli.mjs" gate [--save] [--root <PROJECT_ROOT>]
+ *   node "$UP_PKG/.pi/scripts/harness-sentrux-cli.mjs" --print-root
+ */
+
+import { access } from "node:fs/promises";
+import { constants } from "node:fs";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+import { spawn } from "node:child_process";
+
+const ROOT_MARKERS = [
+	join(".sentrux", "rules.toml"),
+	join(".pi", "harness", "sentrux", "architecture.manifest.json"),
+];
+
+async function fileExists(path) {
+	try {
+		await access(path, constants.R_OK);
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+async function hasRootMarker(dir) {
+	for (const marker of ROOT_MARKERS) {
+		if (await fileExists(join(dir, marker))) return true;
+	}
+	return false;
+}
+
+async function findProjectRoot(startDir) {
+	let dir = resolve(startDir || process.cwd());
+	while (true) {
+		if (await hasRootMarker(dir)) return dir;
+		const parent = dirname(dir);
+		if (parent === dir) return null;
+		dir = parent;
+	}
+}
+
+function takeRootArg(args) {
+	const next = [];
+	let explicitRoot = process.env.HARNESS_PROJECT_ROOT || "";
+	for (let i = 0; i < args.length; i++) {
+		const arg = args[i];
+		if (arg === "--root") {
+			explicitRoot = args[i + 1] || "";
+			i++;
+			continue;
+		}
+		if (arg.startsWith("--root=")) {
+			explicitRoot = arg.slice("--root=".length);
+			continue;
+		}
+		next.push(arg);
+	}
+	return { args: next, explicitRoot };
+}
+
+async function resolveProjectRoot(explicitRoot) {
+	if (explicitRoot) {
+		const root = isAbsolute(explicitRoot)
+			? resolve(explicitRoot)
+			: resolve(process.cwd(), explicitRoot);
+		if (!(await hasRootMarker(root))) {
+			console.error(
+				`harness-sentrux-cli: ${root} has no .sentrux/rules.toml or .pi/harness/sentrux/architecture.manifest.json`,
+			);
+			process.exit(1);
+		}
+		return root;
+	}
+
+	const root = await findProjectRoot(process.cwd());
+	if (!root) {
+		console.error(
+			"harness-sentrux-cli: could not find a harness project root above the current directory",
+		);
+		process.exit(1);
+	}
+	return root;
+}
+
+function normalizeSentruxArgs(args, projectRoot) {
+	const command = args[0];
+	if (!command || command === "--help" || command === "-h") {
+		console.log(`Usage: node harness-sentrux-cli.mjs <check|gate> [sentrux flags] [--root PROJECT_ROOT]
+
+Runs Sentrux with PROJECT_ROOT passed explicitly so .sentrux/rules.toml is found even when invoked from .pi/harness/runs/*.`);
+		process.exit(0);
+	}
+	if (command !== "check" && command !== "gate") {
+		console.error(
+			`harness-sentrux-cli: unsupported command "${command}" (expected check or gate)`,
+		);
+		process.exit(2);
+	}
+	return [command, ...args.slice(1), projectRoot];
+}
+
+async function main() {
+	const parsed = takeRootArg(process.argv.slice(2));
+	const printRoot = parsed.args.includes("--print-root");
+	const sentruxArgs = parsed.args.filter((arg) => arg !== "--print-root");
+	const projectRoot = await resolveProjectRoot(parsed.explicitRoot);
+
+	if (printRoot) {
+		console.log(projectRoot);
+		return;
+	}
+
+	const child = spawn("sentrux", normalizeSentruxArgs(sentruxArgs, projectRoot), {
+		cwd: projectRoot,
+		stdio: "inherit",
+		env: process.env,
+	});
+	child.on("error", (err) => {
+		if (err?.code === "ENOENT") {
+			console.error("harness-sentrux-cli: sentrux not installed");
+			process.exit(127);
+		}
+		console.error(`harness-sentrux-cli: ${err.message}`);
+		process.exit(1);
+	});
+	child.on("close", (code) => process.exit(code ?? 1));
+}
+
+main().catch((err) => {
+	console.error(err);
+	process.exit(1);
+});

package/.pi/scripts/harness-verify.mjs

@@ -5,7 +5,7 @@
 
 import { readFile, access } from "node:fs/promises";
 import { constants } from "node:fs";
-import { join, dirname, resolve } from "node:path";
+import { join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
 import { spawn } from "node:child_process";
 
@@ -42,6 +42,10 @@ const REQUIRED_ADRS = [
 	"0037-subagent-submit-tools.md",
 	"0038-budget-telemetry-only.md",
 	"0040-practice-grounded-orchestration.md",
+	"0045-harness-lens-minimal-contract.md",
+	"0046-agt-policy-engine.md",
+	"0047-agt-layered-security.md",
+	"0048-tool-call-hook-order.md",
 ];
 
 const REQUIRED_EXTENSIONS = [
@@ -148,32 +152,59 @@ async function checkSentruxRules() {
 	ok(".sentrux/rules.toml present");
 }
 
-async function checkModelRouterThinkingOnly() {
-	const path = join(ROOT, ".pi", "model-router.json");
-	if (!(await fileExists(path))) {
-		ok("model-router.json absent (skip thinking-only tier check)");
-		return;
+async function checkHarnessLens(pkgJson) {
+	if (!pkgJson.files?.includes(".pi/lib/harness-lens")) {
+		fail(
+			'package.json "files" must include .pi/lib/harness-lens (npm publish ships harness lens extension)',
+		);
 	}
-	let raw;
-	try {
-		raw = JSON.parse(await readFile(path, "utf-8"));
-	} catch {
-		fail("invalid .pi/model-router.json");
-	}
-	const profiles = raw.profiles ?? {};
-	for (const [name, profile] of Object.entries(profiles)) {
-		const high = profile?.high?.model;
-		const medium = profile?.medium?.model;
-		const low = profile?.low?.model;
-		if (
-			!(high && medium && low && high === medium && medium === low)
-		) {
-			fail(
-				`model-router profile "${name}" must use the same model on high/medium/low (thinking-only tiers)`,
-			);
-		}
+	ok('package.json files includes .pi/lib/harness-lens');
+
+	const piExtensions = pkgJson.pi?.extensions ?? [];
+	if (!piExtensions.includes("./.pi/extensions")) {
+		fail('package.json pi.extensions must include ./.pi/extensions');
+	}
+	if (piExtensions.includes("./vendor/pi-lens/index.ts")) {
+		fail('package.json pi.extensions must not load vendor/pi-lens directly');
+	}
+	ok("package.json loads harness extension directory");
+
+	const harnessLens = join(ROOT, ".pi", "extensions", "harness-lens.ts");
+	if (!(await fileExists(harnessLens))) fail("missing .pi/extensions/harness-lens.ts");
+	ok("harness lens extension wrapper");
+
+	const lensIndex = join(ROOT, ".pi", "lib", "harness-lens", "index.ts");
+	if (!(await fileExists(lensIndex))) {
+		fail("missing .pi/lib/harness-lens/index.ts");
+	}
+	ok(".pi/lib/harness-lens/index.ts");
+
+	const legacyExtLib = join(ROOT, ".pi", "extensions", "lib");
+	if (await fileExists(legacyExtLib)) {
+		fail(".pi/extensions/lib must not exist (shared code lives in .pi/lib/)");
+	}
+	ok("no legacy .pi/extensions/lib directory");
+
+	const lensIndexSource = await readFile(lensIndex, "utf8");
+	if (lensIndexSource.includes("ast_grep_search")) {
+		fail("harness-lens index must not register ast_grep_search");
+	}
+	if (lensIndexSource.includes("lib/lens")) {
+		fail("harness-lens index must not import lib/lens");
+	}
+	ok("harness-lens index contract (no ast_grep, no lib/lens imports)");
+
+	const rulesDir = join(ROOT, ".pi", "lib", "harness-lens", "rules");
+	if (await fileExists(rulesDir)) {
+		fail("harness-lens bundled rules/ directory must not exist");
+	}
+	ok("no bundled harness-lens rules/ directory");
+
+	const upstreamPin = join(ROOT, ".pi", "lib", "harness-lens", "UPSTREAM_PIN.md");
+	if (await fileExists(upstreamPin)) {
+		fail("harness-lens UPSTREAM_PIN.md must not exist (harness-native, no upstream sync)");
 	}
-	ok("model-router.json thinking-only (same model per profile)");
+	ok("no harness-lens UPSTREAM_PIN.md");
 }
 
 async function checkSentruxGate() {
@@ -235,7 +266,7 @@ async function main() {
 		ok(`extension ${name}`);
 	}
 
-	const libPath = join(ROOT, ".pi", "extensions", "lib", "harness-posthog.ts");
+	const libPath = join(ROOT, ".pi", "lib", "harness-posthog.ts");
 	if (!(await fileExists(libPath))) fail("missing lib/harness-posthog.ts");
 	ok("lib/harness-posthog.ts");
 
@@ -246,6 +277,8 @@ async function main() {
 	const pkgJson = JSON.parse(
 		await readFile(join(ROOT, "package.json"), "utf-8"),
 	);
+	await checkHarnessLens(pkgJson);
+
 	if (!pkgJson.files?.includes("vendor/pi-subagents")) {
 		fail(
 			'package.json "files" must include vendor/pi-subagents (npm publish ships subagents vendor)',
@@ -263,13 +296,7 @@ async function main() {
 	if (!(await fileExists(subagentsVendor))) {
 		fail("missing vendor/pi-subagents/src/subagents.ts");
 	}
-	const bridgePath = join(
-		ROOT,
-		".pi",
-		"extensions",
-		"lib",
-		"harness-subagents-bridge.ts",
-	);
+	const bridgePath = join(ROOT, ".pi", "lib", "harness-subagents-bridge.ts");
 	if (!(await fileExists(bridgePath))) {
 		fail("missing harness-subagents-bridge.ts");
 	}
@@ -280,6 +307,14 @@ async function main() {
 	if (!bridgeSrc.includes("packageRoot")) {
 		fail("harness-subagents-bridge must pass packageRoot for agent discovery");
 	}
+	if (
+		!bridgeSrc.includes("subprocessGovernanceExtensionPath") &&
+		!bridgeSrc.includes("subagentGovernanceExtensionPath")
+	) {
+		fail(
+			"harness-subagents-bridge must set subprocessGovernanceExtensionPath for all subagents",
+		);
+	}
 	const subagentsSrc = await readFile(subagentsVendor, "utf-8");
 	if (!subagentsSrc.includes("discoverAgents")) {
 		fail("vendor subagents.ts must implement discoverAgents");
@@ -301,12 +336,46 @@ async function main() {
 	if (!policyGateSrc.includes('pi.on("tool_call", async (event, ctx)')) {
 		fail("policy-gate tool_call must receive ctx for run context");
 	}
-	if (!policyGateSrc.includes("evaluateContextModeMutation")) {
-		fail(
-			"policy-gate.ts must evaluate context-mode execute tools via evaluateContextModeMutation",
-		);
+	if (!policyGateSrc.includes("evaluateAgtHarnessToolCall")) {
+		fail("policy-gate.ts must delegate tool_call to AGT evaluateAgtHarnessToolCall");
 	}
-	ok("policy-gate plan-phase writes");
+	const govPath = join(ROOT, ".pi", "extensions", "subagent-governance.ts");
+	const govAlias = join(
+		ROOT,
+		".pi",
+		"extensions",
+		"harness-subagent-governance.ts",
+	);
+	if (!(await fileExists(govPath))) {
+		fail("missing subagent-governance.ts subprocess bundle");
+	}
+	if (!(await fileExists(govAlias))) {
+		fail("missing harness-subagent-governance.ts re-export alias");
+	}
+	ok("policy-gate + subprocess governance");
+
+	const agtDoctorPath = join(ROOT, ".pi", "scripts", "harness-agt-doctor.ts");
+	const { code: agtDoctorCode, out: agtDoctorOut } = await new Promise(
+		(resolve) => {
+			const child = spawn(
+				"npx",
+				["-y", "tsx", agtDoctorPath],
+				{ cwd: ROOT, stdio: ["ignore", "pipe", "pipe"], shell: true },
+			);
+			let out = "";
+			child.stdout?.on("data", (d) => {
+				out += d.toString();
+			});
+			child.stderr?.on("data", (d) => {
+				out += d.toString();
+			});
+			child.on("close", (code) => resolve({ code: code ?? 1, out }));
+		},
+	);
+	if (agtDoctorCode !== 0) {
+		fail(agtDoctorOut.trim() || "AGT policy doctor failed");
+	}
+	ok("AGT policy doctor");
 
 	const runCtxFixture = join(SMOKE, "run-context.fixture.json");
 	if (!(await fileExists(runCtxFixture))) {
@@ -332,7 +401,12 @@ async function main() {
 	ok("test-diff-golden.json");
 
 	await checkSentruxGate();
-	await checkModelRouterThinkingOnly();
+
+	const AGENTS_POLICY = join(ROOT, ".pi", "harness", "agents.policy.yaml");
+	if (!(await fileExists(AGENTS_POLICY))) {
+		fail("missing .pi/harness/agents.policy.yaml");
+	}
+	ok("agents.policy.yaml present");
 
 	if (!(await fileExists(AGENTS_MANIFEST))) {
 		fail(

package/.pi/scripts/harness-web-policy-guard.mjs

@@ -12,9 +12,9 @@ const ROOT = resolve(new URL("../..", import.meta.url).pathname);
 const ALLOWED_FILES = new Set([
 	".pi/extensions/harness-web-guard.ts",
 	".pi/extensions/harness-web-tools.ts",
-	".pi/extensions/lib/harness-web/run-cli.ts",
+	".pi/lib/harness-web/run-cli.ts",
 	".pi/extensions/harness-run-context.ts",
-	".pi/extensions/lib/ask-user/schema.ts",
+	".pi/lib/ask-user/schema.ts",
 	".pi/scripts/harness-web.py",
 	".pi/scripts/harness-web-search.md",
 	".pi/scripts/harness-web-policy-guard.mjs",

package/.pi/scripts/validate-plan-dag.mjs

@@ -88,49 +88,31 @@ function computeCriticalPath(workItems) {
 	return path;
 }
 
-export function validateExecutionPlan(packet, projectRoot = ROOT) {
+function validateMinimumShape(packet, ep, phases, workItems) {
 	const errors = [];
-	const ep = packet.execution_plan;
-	if (!ep) {
-		errors.push("execution_plan required");
-		return { status: "fail", errors, report: null };
-	}
-
 	const risk = packet.risk_level ?? "med";
 	const min = MINIMUMS[risk] ?? MINIMUMS.med;
-	const phases = ep.phases ?? [];
-	const workItems = ep.work_items ?? [];
-	const conflicts = [];
-
-	if (phases.length < min.phases) {
-		errors.push(`need >= ${min.phases} phases for risk ${risk}`);
-	}
-	if (workItems.length < min.work_items) {
-		errors.push(`need >= ${min.work_items} work_items for risk ${risk}`);
-	}
 	const ac = packet.acceptance_checks ?? [];
-	if (ac.length < min.acceptance_checks) {
-		errors.push(`need >= ${min.acceptance_checks} acceptance_checks`);
-	}
-	if ((ep.risk_register ?? []).length < min.risks) {
-		errors.push(`need >= ${min.risks} risks for risk ${risk}`);
-	}
+	if (phases.length < min.phases) errors.push(`need >= ${min.phases} phases for risk ${risk}`);
+	if (workItems.length < min.work_items) errors.push(`need >= ${min.work_items} work_items for risk ${risk}`);
+	if (ac.length < min.acceptance_checks) errors.push(`need >= ${min.acceptance_checks} acceptance_checks`);
+	if ((ep.risk_register ?? []).length < min.risks) errors.push(`need >= ${min.risks} risks for risk ${risk}`);
+	return errors;
+}
 
+function validatePhaseAndWorkItemLinks(phases, workItems) {
+	const errors = [];
 	const phaseIds = new Set(phases.map((p) => p.phase_id));
-	const phaseIndex = new Map(phases.map((p, i) => [p.phase_id, i]));
 	const wiIds = new Set(workItems.map((w) => w.work_item_id));
-
 	for (const p of phases) {
 		if (!p.exit_criteria?.length) errors.push(`phase ${p.phase_id} missing exit_criteria`);
 		if (!p.work_item_ids?.length) errors.push(`phase ${p.phase_id} has no work items`);
+		for (const wid of p.work_item_ids ?? []) {
+			if (!wiIds.has(wid)) errors.push(`phase ${p.phase_id} references missing ${wid}`);
+		}
 	}
-
-	const wiInPhase = new Set();
 	for (const w of workItems) {
-		if (!phaseIds.has(w.phase_id)) {
-			errors.push(`work_item ${w.work_item_id} unknown phase_id`);
-		}
-		wiInPhase.add(w.work_item_id);
+		if (!phaseIds.has(w.phase_id)) errors.push(`work_item ${w.work_item_id} unknown phase_id`);
 		for (const d of w.depends_on ?? []) {
 			if (!wiIds.has(d)) errors.push(`work_item ${w.work_item_id} depends_on missing ${d}`);
 		}
@@ -138,17 +120,23 @@ export function validateExecutionPlan(packet, projectRoot = ROOT) {
 			errors.push(`work_item ${w.work_item_id} needs files[] or non_code: true`);
 		}
 	}
+	return errors;
+}
 
-	for (const p of phases) {
-		for (const wid of p.work_item_ids ?? []) {
-			if (!wiIds.has(wid)) errors.push(`phase ${p.phase_id} references missing ${wid}`);
-		}
+function isReachable(workItems, from, to, seen = new Set()) {
+	if (from === to) return true;
+	if (seen.has(from)) return false;
+	seen.add(from);
+	const w = workItems.find((x) => x.work_item_id === from);
+	for (const d of w?.depends_on ?? []) {
+		if (isReachable(workItems, d, to, seen)) return true;
 	}
+	return false;
+}
 
-	const { order, cycles } = topoSort(workItems);
-	if (cycles.length) errors.push(`cycle detected: ${JSON.stringify(cycles[0])}`);
-
-	// File conflicts
+function findFileConflicts(phases, workItems) {
+	const conflicts = [];
+	const phaseIndex = new Map(phases.map((p, i) => [p.phase_id, i]));
 	for (let i = 0; i < workItems.length; i++) {
 		for (let j = i + 1; j < workItems.length; j++) {
 			const a = workItems[i];
@@ -156,42 +144,34 @@ export function validateExecutionPlan(packet, projectRoot = ROOT) {
 			const filesA = new Set(a.files ?? []);
 			const overlap = (b.files ?? []).filter((f) => filesA.has(f));
 			if (overlap.length === 0) continue;
-			const reachable = (from, to, seen = new Set()) => {
-				if (from === to) return true;
-				if (seen.has(from)) return false;
-				seen.add(from);
-				const w = workItems.find((x) => x.work_item_id === from);
-				for (const d of w?.depends_on ?? []) {
-					if (reachable(d, to, seen)) return true;
-				}
-				return false;
-			};
-			if (!reachable(a.work_item_id, b.work_item_id) && !reachable(b.work_item_id, a.work_item_id)) {
-				if ((phaseIndex.get(a.phase_id) ?? 0) === (phaseIndex.get(b.phase_id) ?? 0)) {
-					conflicts.push(
-						`file overlap ${overlap.join(",")} between ${a.work_item_id} and ${b.work_item_id} without dependency`,
-					);
-				}
+			const ordered =
+				isReachable(workItems, a.work_item_id, b.work_item_id) ||
+				isReachable(workItems, b.work_item_id, a.work_item_id);
+			const samePhase = (phaseIndex.get(a.phase_id) ?? 0) === (phaseIndex.get(b.phase_id) ?? 0);
+			if (!ordered && samePhase) {
+				conflicts.push(
+					`file overlap ${overlap.join(",")} between ${a.work_item_id} and ${b.work_item_id} without dependency`,
+				);
 			}
 		}
 	}
+	return conflicts;
+}
 
+function validateCriticalPath(ep, workItems) {
 	const computedCp = computeCriticalPath(workItems);
 	const authorCp = ep.schedule_metadata?.critical_path_work_item_ids ?? [];
-	if (computedCp.length >= 3 && authorCp.length) {
-		const same =
-			authorCp.length === computedCp.length &&
-			authorCp.every((id, i) => id === computedCp[i]);
-		if (!same) {
-			errors.push(
-				`critical_path mismatch author=${authorCp.join("→")} computed=${computedCp.join("→")}`,
-			);
-		}
-	}
+	const same =
+		authorCp.length === computedCp.length &&
+		authorCp.every((id, i) => id === computedCp[i]);
+	if (computedCp.length < 3 || !authorCp.length || same) return [];
+	return [`critical_path mismatch author=${authorCp.join("→")} computed=${computedCp.join("→")}`];
+}
 
-	const acIds = new Set(
-		ac.map((c) => (typeof c === "string" ? c : c.id)).filter(Boolean),
-	);
+function validateAcceptanceCheckLinks(packet, workItems) {
+	const errors = [];
+	const ac = packet.acceptance_checks ?? [];
+	const acIds = new Set(ac.map((c) => (typeof c === "string" ? c : c.id)).filter(Boolean));
 	for (const w of workItems) {
 		for (const acid of w.acceptance_check_ids ?? []) {
 			if (!acIds.has(acid)) errors.push(`${w.work_item_id} references orphan ${acid}`);
@@ -201,14 +181,25 @@ export function validateExecutionPlan(packet, projectRoot = ROOT) {
 		const used = workItems.some((w) => (w.acceptance_check_ids ?? []).includes(acid));
 		if (!used) errors.push(`orphan acceptance check ${acid}`);
 	}
+	return errors;
+}
 
+export function validateExecutionPlan(packet, projectRoot = ROOT) {
+	const ep = packet.execution_plan;
+	if (!ep) return { status: "fail", errors: ["execution_plan required"], report: null };
+	const phases = ep.phases ?? [];
+	const workItems = ep.work_items ?? [];
+	const { order, cycles } = topoSort(workItems);
+	const errors = [
+		...validateMinimumShape(packet, ep, phases, workItems),
+		...validatePhaseAndWorkItemLinks(phases, workItems),
+		...(cycles.length ? [`cycle detected: ${JSON.stringify(cycles[0])}`] : []),
+		...validateCriticalPath(ep, workItems),
+		...validateAcceptanceCheckLinks(packet, workItems),
+	];
+	const conflicts = findFileConflicts(phases, workItems);
 	const status = errors.length === 0 && conflicts.length === 0 ? "pass" : "fail";
-	const report = {
-		status,
-		topological_order: order,
-		cycles,
-		conflicts: [...conflicts, ...errors],
-	};
+	const report = { status, topological_order: order, cycles, conflicts: [...conflicts, ...errors] };
 	return { status, errors: [...errors, ...conflicts], report };
 }
 

package/.pi/scripts/vendor-pi-vcc-settings.stub.ts

@@ -1,8 +1,8 @@
 /**
  * ultimate-pi harness settings (env-only). Re-exported for vendored pi-vcc layout.
  */
-export type { PiVccSettings } from "../../../../.pi/extensions/lib/harness-vcc-settings.js";
+export type { PiVccSettings } from "../../../../.pi/lib/harness-vcc-settings.js";
 export {
 	loadSettings,
 	scaffoldSettings,
-} from "../../../../.pi/extensions/lib/harness-vcc-settings.js";
+} from "../../../../.pi/lib/harness-vcc-settings.js";

package/.pi/scripts/vendor-sync-pi-vcc.sh

@@ -29,7 +29,7 @@ cat >"$VEND/UPSTREAM_PIN.md" <<EOF
 - **License:** MIT (see upstream repository)
 - **Pinned upstream commit:** \`$COMMIT\`
 - **Local changes:**
-  - \`src/core/settings.ts\` re-exports env-only [\`harness-vcc-settings\`](../../.pi/extensions/lib/harness-vcc-settings.ts) (\`HARNESS_VCC_COMPACTION\`, \`HARNESS_VCC_DEBUG\`)
+  - \`src/core/settings.ts\` re-exports env-only [\`harness-vcc-settings\`](../../.pi/lib/harness-vcc-settings.ts) (\`HARNESS_VCC_COMPACTION\`, \`HARNESS_VCC_DEBUG\`)
   - No \`scaffoldSettings\` / no \`PI_VCC_CONFIG_PATH\`
   - Compaction \`details.compactor\` is \`ultimate-pi-vcc\`
 

package/.pi/skills/architecture/broker-domain/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: broker-domain
+description: "Use when implementing the Broker-Domain pattern: event-brokered integration around cohesive domain services, separating broker concerns from domain behavior, with explicit event contracts and bounded context ownership."
+---
+
+# Broker-Domain Pattern
+
+Use this skill when event-driven integration is needed but domain logic must stay inside cohesive domain boundaries.
+
+## Fit
+
+Use when multiple domains coordinate through events and you need to avoid both a god orchestrator and an anemic event-bus blob.
+Avoid when a simple in-process call or single workflow orchestrator is clearer.
+
+## Agent Workflow
+
+1. Read `graphify-out/GRAPH_REPORT.md`.
+2. Run `graphify query "Broker-Domain pattern event broker domain services bounded contexts"`.
+3. Identify domain services and event broker responsibilities separately.
+4. Keep event routing/transport out of domain decisions.
+5. Implement one domain event flow end to end.
+6. Add contract, idempotency, and ownership checks.
+
+## Target Shape
+
+```text
+codebase/domains/
+  orders/
+    domain/
+    application/
+    events            # domain-owned event contracts
+  billing/
+    ...
+codebase/broker/
+  bus
+  subscriptions
+  serializers
+```
+
+## Implementation Rules
+
+- Domains publish and consume meaningful business events.
+- Broker code owns transport, serialization, subscription wiring, retries, and delivery mechanics.
+- Domain code must not depend on broker vendor APIs.
+- Event contracts belong to the producing domain and are versioned.
+- Consumers translate external events into local application actions.
+
+## Migration Steps
+
+1. Select one cross-domain interaction.
+2. Define producer-owned event contract.
+3. Add broker adapter that maps domain event to transport message.
+4. Add consumer subscription that calls local application service.
+5. Add idempotency and dead-letter handling.
+6. Remove direct cross-domain call if the event path replaces it safely.
+
+## Verification
+
+- `graphify explain "broker"` should show broker-to-domain adapter edges, not domain-to-vendor lock-in.
+- Test event contract compatibility and duplicate delivery.
+- Check no domain imports broker implementation packages.
+
+## Output Contract
+
+Return: domains, broker responsibilities, event contracts, migrated interaction, failure handling, and verification.