ultimate-pi 0.18.1 → 0.19.0

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.

package/.pi/skills/architecture/cqrs/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: cqrs
+description: "Use when implementing CQRS: separate command and query models, explicit write invariants, optimized read projections, consistency boundaries, projection rebuilds, and tests for command/query behavior."
+---
+
+# CQRS
+
+Use this skill when reads and writes need different models, scaling, permissions, or performance profiles.
+
+## Fit
+
+Use for complex domains with strong write invariants and read-heavy/query-specific views.
+Avoid when simple CRUD is adequate; CQRS can double code paths and consistency work.
+
+## Agent Workflow
+
+1. Read `graphify-out/GRAPH_REPORT.md`.
+2. Run `graphify query "CQRS command query responsibility segregation projections events"`.
+3. Identify commands that change state and queries that read views.
+4. Separate write model from read model incrementally.
+5. Define consistency and projection rebuild rules.
+6. Add tests for commands, projections, and stale reads.
+
+## Target Shape
+
+```text
+codebase/<bounded-context>/
+  commands/
+    handlers/
+    model/
+  queries/
+    handlers/
+    projections/
+  events/              # optional but common
+```
+
+## Implementation Rules
+
+- Commands express intent and enforce invariants through the write model.
+- Queries never mutate state.
+- Read models are optimized for consumers and may be denormalized.
+- Projection lag and stale-read behavior must be explicit.
+- Do not expose write entities directly as read DTOs.
+- Keep command and query contracts versioned if external.
+
+## Migration Steps
+
+1. Pick one painful read or one complex command.
+2. Create command handler and query handler folders.
+3. Move invariant logic into command handler/write model.
+4. Create a read projection or query representation.
+5. Wire projection update from transaction, event, or scheduled rebuild.
+6. Add tests for stale/missing projection behavior.
+
+## Verification
+
+- Use graphify to confirm query handlers do not call command mutation paths.
+- Test command invariants independently from query projection shape.
+- Test projection rebuild from durable source.
+
+## Output Contract
+
+Return: command/query split, consistency model, projection path, migration patch, and verification evidence.

package/.pi/skills/architecture/event-driven/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: event-driven
+description: "Use when implementing event-driven architecture: domain/integration events, producers, consumers, broker or mediator topology, eventual consistency, idempotency, ordering, retries, and observable asynchronous flows."
+---
+
+# Event-Driven Architecture
+
+Use this skill when agents need to decouple producers and consumers with events safely.
+
+## Fit
+
+Use for asynchronous workflows, multi-consumer reactions, integration boundaries, audit trails, and high-throughput decoupling.
+Avoid when immediate consistency and simple request/response are enough.
+
+## Agent Workflow
+
+1. Read `graphify-out/GRAPH_REPORT.md`.
+2. Run `graphify query "event-driven architecture broker mediator topology eventual consistency"`.
+3. Identify facts worth publishing, not commands disguised as events.
+4. Choose broker/choreography or mediator/orchestration intentionally.
+5. Implement one event path end to end.
+6. Add idempotency, retry, and observability before expanding.
+
+## Target Shape
+
+```text
+codebase/events/
+  contracts/          # event schemas and versions
+  event-bus           # publish/subscribe port
+  handlers/           # consumers
+  outbox/             # reliable publish if DB-backed
+```
+
+## Implementation Rules
+
+- Events are past-tense facts: `OrderPlaced`, not `PlaceOrder`.
+- Event schemas are versioned and backward-compatible.
+- Consumers are idempotent and handle duplicate/out-of-order delivery.
+- Use an outbox/inbox pattern when database state and publishing must be reliable.
+- Prefer correlation IDs and causation IDs for traceability.
+- Do not hide core business invariants in eventually consistent consumers.
+
+## Migration Steps
+
+1. Name one event from a real business fact.
+2. Define schema, version, producer, and consumers.
+3. Publish after the owning transaction commits.
+4. Add one consumer with idempotency storage.
+5. Add retry/dead-letter behavior.
+6. Add tests for duplicate, missing, and stale events.
+
+## Verification
+
+- `graphify explain "<event name>"` should show producer and consumers.
+- Contract-test event schema compatibility.
+- Test retry and idempotency paths.
+
+## Output Contract
+
+Return: event catalog, topology choice, producer/consumer patch, consistency guarantees, failure handling, and verification.