ultimate-pi 0.18.1 → 0.19.1

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.

package/.pi/skills/architecture/hexagonal-ports-adapters/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: hexagonal-ports-adapters
+description: "Use when implementing hexagonal architecture / ports and adapters: domain core isolated from delivery and infrastructure mechanisms, inbound and outbound ports, adapters for external interfaces, dependency inversion, and testable business logic."
+---
+
+# Hexagonal Architecture / Ports and Adapters
+
+Use this skill to make business logic independent of delivery mechanisms and infrastructure.
+
+## Fit
+
+Use when domain logic is valuable, tests are brittle due to delivery/infrastructure coupling, or adapters change often.
+Avoid if the system is a tiny CRUD wrapper where abstraction would be ceremony.
+
+## Agent Workflow
+
+1. Read `graphify-out/GRAPH_REPORT.md`.
+2. Run `graphify query "hexagonal architecture ports adapters domain operational coupling"`.
+3. Identify the core domain/application use case.
+4. Define inbound and outbound ports around it.
+5. Move delivery/infrastructure-specific code to adapters.
+6. Test the core through ports without infrastructure.
+
+## Target Shape
+
+```text
+codebase/
+  core/
+    domain/
+    application/
+    ports/
+      inbound-port
+      outbound-port
+  adapters/
+    inbound/external-interface/
+    inbound/operator-interface/
+    outbound/persistence/
+    outbound/messaging/
+```
+
+## Implementation Rules
+
+- Core owns domain and application behavior.
+- Inbound adapters translate external requests into use-case calls.
+- Outbound adapters implement core-defined ports for persistence, messaging, time, IDs, and external APIs.
+- Dependencies point inward: adapters reference core, core does not reference adapters.
+- Use dependency injection/composition at the edge.
+
+## Migration Steps
+
+1. Pick one use case entangled with delivery or persistence infrastructure.
+2. Extract its input/output contracts and port interfaces into core.
+3. Move business decisions into application/domain.
+4. Wrap existing persistence/integration code as an outbound adapter.
+5. Wire adapters in the composition root.
+6. Add core tests with fake outbound ports.
+
+## Verification
+
+- `graphify explain "core"` should show no outbound adapter or infrastructure references.
+- Search core paths for delivery, persistence, messaging, filesystem, environment, or platform dependencies.
+- Test core without starting external infrastructure.
+
+## Output Contract
+
+Return: core boundary, ports, adapters, composition root change, tests, and remaining coupling.

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

@@ -0,0 +1,68 @@
+---
+name: layered
+description: "Use when designing, refactoring, or validating a codebase as layered architecture: delivery/interface, application/use-case, domain, and infrastructure/data layers with one-way dependency rules and minimal cross-layer coupling."
+---
+
+# Layered Architecture
+
+Use this skill to help an agent implement layered architecture, not just describe it.
+
+## Fit
+
+Use when the system is mostly CRUD, workflow-oriented, or policy-heavy and benefits from clear dependency direction.
+Avoid when independent deployment, high autonomous scaling, or highly asynchronous collaboration is the main driver.
+
+## Agent Workflow
+
+1. Read `graphify-out/GRAPH_REPORT.md` before source files.
+2. Run `graphify query "layered architecture dependencies presentation application domain infrastructure"`.
+3. Infer the actual layers from packages, modules, and graph communities.
+4. Define allowed dependencies before moving code.
+5. Make the smallest refactor that improves directionality.
+6. Add a fitness check that prevents backsliding.
+
+## Target Shape
+
+Typical dependency direction:
+
+```text
+presentation/api -> application/use-cases -> domain -> infrastructure interfaces
+                                      infrastructure adapters -> domain/application ports
+```
+
+Prefer these directories when introducing structure:
+
+```text
+codebase/
+  delivery/           # external-interface adapters
+  application/        # use cases, commands, queries, units of work
+  domain/             # entities, value objects, policies, domain services
+  infrastructure/     # persistence, network, messaging, filesystem, platform adapters
+```
+
+## Implementation Rules
+
+- Domain code must not reference delivery mechanisms, persistence tooling, messaging systems, clocks, environment, or global configuration.
+- Application code orchestrates use cases and owns transaction boundaries.
+- Delivery/interface code maps external contracts to application inputs; it does not hold business rules.
+- Infrastructure implements interfaces/ports declared inward.
+- Shared utilities must be boring, stable, and dependency-free; do not create a junk drawer.
+
+## Migration Steps
+
+1. Pick one vertical use case.
+2. Move business decisions from entrypoint handlers into `domain/`.
+3. Create an application use-case routine around it.
+4. Place infrastructure behind explicit interfaces.
+5. Leave old entrypoints as thin adapters.
+6. Repeat by use case, not by sweeping folders.
+
+## Verification
+
+- Use `graphify explain "<domain symbol>"` to confirm it has no outbound delivery/infrastructure edges.
+- Search domain paths for forbidden references to delivery, persistence, messaging, environment, or platform mechanisms.
+- Add dependency-boundary tests with the repo's existing verification tooling.
+
+## Output Contract
+
+Return: inferred layers, violations, minimal migration patch, verification run, and remaining risks.

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

@@ -0,0 +1,62 @@
+---
+name: microkernel
+description: "Use when building plugin or extension architecture: a stable core kernel with explicit extension points, plugin contracts, registration, isolation, versioning, and compatibility checks."
+---
+
+# Microkernel / Plugin Architecture
+
+Use this skill when the codebase needs a small core and independently variable plugins.
+
+## Fit
+
+Use for CLIs, editors, rules engines, integrations, workflow engines, agent tools, and product variants.
+Avoid when variation is low or plugin isolation would add more complexity than it removes.
+
+## Agent Workflow
+
+1. Read `graphify-out/GRAPH_REPORT.md`.
+2. Run `graphify query "microkernel plugin extension points core adapters"`.
+3. Identify stable core responsibilities versus variable behavior.
+4. Define extension contracts before extracting plugins.
+5. Move one variable feature behind a plugin boundary.
+6. Add compatibility and registration checks.
+
+## Target Shape
+
+```text
+codebase/kernel/
+  contracts           # plugin interfaces, capabilities, lifecycle
+  registry            # discovery, validation, ordering
+  runtime             # core orchestration
+codebase/plugins/
+  <plugin-name>/
+    entrypoint        # manifest + implementation
+    tests/
+```
+
+## Implementation Rules
+
+- Kernel owns orchestration, lifecycle, contracts, capability negotiation, and safe defaults.
+- Plugins own optional behavior only; they must not mutate kernel internals.
+- Plugin APIs are versioned and narrow.
+- Registration validates name, version, capabilities, dependencies, and conflicts.
+- Side effects are exposed through kernel-provided services, not global imports.
+
+## Migration Steps
+
+1. Name the extension point.
+2. Create contract and manifest types.
+3. Implement an in-process registry.
+4. Wrap one existing variation as the first built-in plugin.
+5. Replace direct branching with registry dispatch.
+6. Add contract tests reused by every plugin.
+
+## Verification
+
+- `graphify explain "registry"` should show kernel-to-plugin direction, not plugin-to-kernel internals.
+- Add tests for plugin registration, invalid manifests, lifecycle failures, and version mismatch.
+- Search for plugin imports of kernel private paths.
+
+## Output Contract
+
+Return: kernel boundary, extension points, plugin contract, migrated plugin, compatibility tests, and known limitations.

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

@@ -0,0 +1,64 @@
+---
+name: microservices
+description: "Use when designing, extracting, or repairing microservices: independently deployable bounded-context services with owned data, explicit contracts, observability, resilience, distributed workflow choices, and operational readiness checks."
+---
+
+# Microservices Architecture
+
+Use this skill only when service independence is worth distributed-system cost.
+
+## Fit
+
+Use when services need independent deployability, independent scaling, domain autonomy, and separate data ownership.
+Avoid when boundaries are unclear, teams cannot operate services, or a modular monolith would solve the problem.
+
+## Agent Workflow
+
+1. Read `graphify-out/GRAPH_REPORT.md`.
+2. Run `graphify query "microservices bounded context data isolation choreography orchestration sagas"`.
+3. Identify bounded contexts and fracture planes.
+4. Choose one extraction candidate with high cohesion and low coupling.
+5. Define API/events/data ownership before moving code.
+6. Add production-readiness controls with the first extraction.
+
+## Target Shape
+
+```text
+services/
+  orders/
+    code/
+    contract/          # API specs, event schemas
+    migrations/
+    deploy/
+  billing/
+    ...
+shared/                # generated clients/contracts only; no shared domain model
+```
+
+## Implementation Rules
+
+- Each service owns its data; no cross-service table writes.
+- Contracts are explicit: API schema, event schema, or generated client.
+- Distributed workflows use choreography, orchestration, or saga intentionally.
+- Every network call has timeout, retry policy, circuit breaker/backoff as appropriate, and observability.
+- Avoid shared domain libraries; share contracts, not internals.
+- Extraction must include deployment, rollback, monitoring, and incident path.
+
+## Migration Steps
+
+1. Prove the boundary with a modular monolith facade first when possible.
+2. Create service contract and data ownership doc.
+3. Duplicate or migrate data behind an anti-corruption layer.
+4. Route one use case through the new service.
+5. Add contract tests and consumer-driven compatibility checks.
+6. Add traces, metrics, logs, health checks, and rollback.
+
+## Verification
+
+- `graphify explain "<service>"` should show contract edges, not private code sharing.
+- Test API compatibility, idempotency, failure, timeout, and degraded dependency behavior.
+- Verify no direct database access across service boundaries.
+
+## Output Contract
+
+Return: service boundary, contracts, data ownership, extraction patch, resilience controls, verification, and ops risks.