@viccydev/pi-fpa 0.8.0 → 0.9.0

package/extensions/fpa-routing-guard/graph-installer.ts

@@ -0,0 +1,234 @@
+import { createHash, randomUUID } from "node:crypto";
+import { lstat, mkdir, open, readFile, realpath, rename, unlink, writeFile } from "node:fs/promises";
+import { basename, dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const TEMPLATE_NAMES = ["fpa-strategy-planning", "fpa-forecast-freeze"] as const;
+const RETIRED_NAMES = ["fpa-period-analysis", "fpa-strategy-recommendation"] as const;
+const PACKAGE_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "../..");
+
+interface GraphInstallResult {
+	installed: string[];
+	upgraded: string[];
+	retired: string[];
+	backups: string[];
+	warnings: string[];
+}
+
+interface GraphIdentity {
+	name?: string;
+	version?: string;
+}
+
+async function pathStat(path: string) {
+	try {
+		return await lstat(path);
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === "ENOENT") return undefined;
+		throw error;
+	}
+}
+
+async function secureGraphsDirectory(cwd: string): Promise<{ agentGraph: string; graphs: string }> {
+	const cwdReal = await realpath(cwd);
+	const agentGraph = join(cwdReal, ".agent-graph");
+	const graphs = join(agentGraph, "graphs");
+	for (const directory of [agentGraph, graphs]) {
+		let existing = await pathStat(directory);
+		if (!existing) {
+			try {
+				await mkdir(directory);
+			} catch (error) {
+				if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
+			}
+			existing = await pathStat(directory);
+		}
+		if (!existing?.isDirectory() || existing.isSymbolicLink()) {
+			throw new Error(`FP&A Graph directory must be a real directory: ${directory}`);
+		}
+		if (await realpath(directory) !== directory) throw new Error(`FP&A Graph directory escapes the trusted cwd: ${directory}`);
+	}
+	return { agentGraph, graphs };
+}
+
+async function secureChildDirectory(parent: string, directory: string): Promise<void> {
+	if (dirname(directory) !== parent) throw new Error(`FP&A Graph backup directory escapes its parent: ${directory}`);
+	let existing = await pathStat(directory);
+	if (!existing) {
+		try {
+			await mkdir(directory);
+		} catch (error) {
+			if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
+		}
+		existing = await pathStat(directory);
+	}
+	if (!existing?.isDirectory() || existing.isSymbolicLink() || await realpath(directory) !== directory) {
+		throw new Error(`FP&A Graph backup directory must be a real directory inside the trusted cwd: ${directory}`);
+	}
+}
+
+function graphIdentity(content: string): GraphIdentity {
+	try {
+		const parsed = JSON.parse(content) as Record<string, unknown>;
+		return {
+			name: typeof parsed.name === "string" ? parsed.name : undefined,
+			version: typeof parsed.version === "string" ? parsed.version : undefined,
+		};
+	} catch {
+		return {};
+	}
+}
+
+function compareVersions(left: string | undefined, right: string | undefined): number | undefined {
+	const parse = (value: string | undefined) => value?.match(/^(\d+)\.(\d+)\.(\d+)$/)?.slice(1).map(Number);
+	const a = parse(left);
+	const b = parse(right);
+	if (!a || !b) return undefined;
+	for (let index = 0; index < 3; index += 1) {
+		if (a[index] !== b[index]) return a[index] - b[index];
+	}
+	return 0;
+}
+
+function safeVersion(value: string | undefined): string {
+	return value?.match(/^\d+\.\d+\.\d+$/)?.[0] ?? "unknown";
+}
+
+async function atomicCreate(path: string, content: string): Promise<void> {
+	await writeFile(path, content, { flag: "wx" });
+}
+
+async function backupFile(agentGraph: string, path: string, content: string, version: string | undefined, removeSource: boolean): Promise<string> {
+	const backupDirectory = join(agentGraph, `graphs_backup_v${safeVersion(version)}`);
+	await secureChildDirectory(agentGraph, backupDirectory);
+	let destination = join(backupDirectory, basename(path));
+	let existing = await pathStat(destination);
+	if (existing) {
+		if (!existing.isFile() || existing.isSymbolicLink()) throw new Error(`Unsafe FP&A Graph backup target: ${destination}`);
+		const existingContent = await readFile(destination, "utf8");
+		if (existingContent === content) {
+			if (removeSource) await unlink(path);
+			return destination;
+		}
+		const fingerprint = createHash("sha256").update(content).digest("hex").slice(0, 12);
+		destination = join(backupDirectory, `${basename(path, ".json")}.${fingerprint}.json`);
+		existing = await pathStat(destination);
+		if (existing) {
+			if (!existing.isFile() || existing.isSymbolicLink() || await readFile(destination, "utf8") !== content) {
+				throw new Error(`Conflicting FP&A Graph backup target: ${destination}`);
+			}
+			if (removeSource) await unlink(path);
+			return destination;
+		}
+	}
+	await atomicCreate(destination, content);
+	if (removeSource) await unlink(path);
+	return destination;
+}
+
+async function atomicWrite(path: string, content: string): Promise<void> {
+	const temporary = join(dirname(path), `.${basename(path)}.${process.pid}.${randomUUID()}.tmp`);
+	await writeFile(temporary, content, { flag: "wx" });
+	try {
+		await rename(temporary, path);
+	} catch (error) {
+		await unlink(temporary).catch(() => undefined);
+		throw error;
+	}
+}
+
+async function withInstallerLock<T>(agentGraph: string, timeoutMs: number, action: () => Promise<T>): Promise<T> {
+	const lockPath = join(agentGraph, ".fpa-graph-installer.lock");
+	let handle: Awaited<ReturnType<typeof open>> | undefined;
+	let ownership: { dev: number | bigint; ino: number | bigint } | undefined;
+	const deadline = Date.now() + Math.max(0, timeoutMs);
+	while (!handle) {
+		try {
+			const candidate = await open(lockPath, "wx", 0o600);
+			try {
+				await candidate.writeFile(`${process.pid} ${Date.now()}\n`);
+				const stat = await candidate.stat();
+				ownership = { dev: stat.dev, ino: stat.ino };
+				handle = candidate;
+			} catch (error) {
+				await candidate.close().catch(() => undefined);
+				await unlink(lockPath).catch(() => undefined);
+				throw error;
+			}
+		} catch (error) {
+			if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
+			const stat = await pathStat(lockPath);
+			if (!stat?.isFile() || stat.isSymbolicLink()) throw new Error(`Unsafe FP&A Graph installer lock: ${lockPath}`);
+			// Never steal a pathname from an unknown owner: an old holder could
+			// otherwise unlink the replacement lock from its own finally block.
+			if (Date.now() >= deadline) break;
+			await new Promise((resolve) => setTimeout(resolve, Math.min(25, Math.max(1, deadline - Date.now()))));
+		}
+	}
+	if (!handle) throw new Error(`Timed out waiting for FP&A Graph installer lock: ${lockPath}`);
+	try {
+		return await action();
+	} finally {
+		await handle.close();
+		const current = await pathStat(lockPath);
+		if (
+			ownership
+			&& current?.isFile()
+			&& !current.isSymbolicLink()
+			&& current.dev === ownership.dev
+			&& current.ino === ownership.ino
+		) await unlink(lockPath).catch(() => undefined);
+	}
+}
+
+export async function ensureFpaProjectGraphs(options: { cwd: string; trusted: boolean; lockTimeoutMs?: number }): Promise<GraphInstallResult> {
+	const result: GraphInstallResult = { installed: [], upgraded: [], retired: [], backups: [], warnings: [] };
+	if (!options.trusted) return result;
+	const { agentGraph, graphs } = await secureGraphsDirectory(options.cwd);
+	return withInstallerLock(agentGraph, options.lockTimeoutMs ?? 5_000, async () => {
+		for (const name of TEMPLATE_NAMES) {
+			const sourcePath = join(PACKAGE_ROOT, "graphs", `${name}.json`);
+			const sourceContent = await readFile(sourcePath, "utf8");
+			const sourceIdentity = graphIdentity(sourceContent);
+			if (sourceIdentity.name !== name || !sourceIdentity.version) throw new Error(`Invalid packaged FP&A Graph template: ${sourcePath}`);
+			const targetPath = join(graphs, `${name}.json`);
+			const targetStat = await pathStat(targetPath);
+			if (!targetStat) {
+				await atomicWrite(targetPath, sourceContent);
+				result.installed.push(name);
+				continue;
+			}
+			if (!targetStat.isFile() || targetStat.isSymbolicLink()) {
+				result.warnings.push(`Preserved unsafe or non-file Graph target: ${targetPath}`);
+				continue;
+			}
+			const targetContent = await readFile(targetPath, "utf8");
+			if (targetContent === sourceContent) continue;
+			const targetIdentity = graphIdentity(targetContent);
+			const comparison = compareVersions(targetIdentity.version, sourceIdentity.version);
+			if (targetIdentity.name === name && comparison !== undefined && comparison > 0) {
+				result.warnings.push(`Preserved newer project Graph ${name}@${targetIdentity.version}; package provides ${sourceIdentity.version}.`);
+				continue;
+			}
+			const backup = await backupFile(agentGraph, targetPath, targetContent, targetIdentity.version, false);
+			result.backups.push(backup);
+			await atomicWrite(targetPath, sourceContent);
+			result.upgraded.push(name);
+		}
+
+		for (const name of RETIRED_NAMES) {
+			const path = join(graphs, `${name}.json`);
+			const stat = await pathStat(path);
+			if (!stat) continue;
+			if (!stat.isFile() || stat.isSymbolicLink()) {
+				result.warnings.push(`Preserved unsafe or non-file retired Graph target: ${path}`);
+				continue;
+			}
+			const content = await readFile(path, "utf8");
+			const backup = await backupFile(agentGraph, path, content, graphIdentity(content).version, true);
+			result.backups.push(backup);
+			result.retired.push(name);
+		}
+		return result;
+	});
+}

package/extensions/fpa-routing-guard/index.ts

@@ -5,10 +5,11 @@ import type {
 	ToolResultEvent,
 } from "@earendil-works/pi-coding-agent";
 
+import { ensureFpaProjectGraphs } from "./graph-installer.ts";
+
 const GRAPH_TOOLS = ["graph_list", "graph_run"] as const;
+const ROUTING_STATE_CUSTOM_TYPE = "fpa-routing-guard-state";
 const FP_AND_A_GRAPHS = [
-	"fpa-period-analysis",
-	"fpa-strategy-recommendation",
 	"fpa-strategy-planning",
 	"fpa-forecast-freeze",
 	"fpa-strategy-execution",
@@ -22,6 +23,14 @@ interface RoutingState {
 	availableGraphs: Set<string>;
 	graphRunStarted: boolean;
 	graphRunCompleted: boolean;
+	reviewPublished: boolean;
+}
+
+interface PersistedRoutingState {
+	version: 1;
+	requiredGraph: FpaGraph;
+	graphRunCompleted: boolean;
+	reviewPublished: boolean;
 }
 
 function emptyState(): RoutingState {
@@ -30,6 +39,7 @@ function emptyState(): RoutingState {
 		availableGraphs: new Set(),
 		graphRunStarted: false,
 		graphRunCompleted: false,
+		reviewPublished: false,
 	};
 }
 
@@ -60,6 +70,10 @@ function isExplicitIsolatedPhase(prompt: string): boolean {
 	const skill = prompt.match(/^<skill name="(fpa-[^"]+)"/);
 	if (skill && skill[1] !== "fpa-apply-core-rules") return true;
 	if (!/(?:^|[。；;]\s*)(?:请)?(?:本次)?(?:只|仅)|\bonly\b/i.test(prompt)) return false;
+	if (
+		FP_AND_A_GRAPHS.some((graph) => prompt.toLowerCase().includes(graph))
+		&& /(?:运行|执行|启动|调用|使用|通过|\brun\b|\bexecute\b|\bstart\b)/i.test(prompt)
+	) return false;
 	return !/(?:然后|接着|随后|再进入|后再|直至|全流程|完整流程|end[- ]to[- ]end)/i.test(prompt);
 }
 
@@ -119,7 +133,7 @@ export function classifyFpaGraph(prompt: string): FpaGraph | undefined {
 		return "fpa-strategy-execution";
 	}
 
-	return hasFpaIntent(normalized) ? "fpa-period-analysis" : undefined;
+	return hasFpaIntent(normalized) ? "fpa-strategy-planning" : undefined;
 }
 
 function contentText(event: ToolResultEvent): string {
@@ -148,30 +162,93 @@ function artifactWrite(event: ToolCallEvent): boolean {
 	return /artifacts?[\\/]/i.test(command);
 }
 
-function routingInstruction(graph: FpaGraph): string {
-	return [
+function graphContextError(event: ToolCallEvent, graph: FpaGraph): string | undefined {
+	const context = "context" in event.input ? event.input.context : undefined;
+	if (!context || typeof context !== "object" || Array.isArray(context)) {
+		return "graph_run requires a context object whose values are strings.";
+	}
+	const values = context as Record<string, unknown>;
+	const required = graph === "fpa-strategy-planning" || graph === "fpa-forecast-freeze"
+		? ["scope_id", "cycle_id", "forecast_role"]
+		: [];
+	const missing = required.filter((key) => !(key in values) || (typeof values[key] === "string" && values[key].trim().length === 0));
+	if (missing.length > 0) return `graph_run requires non-empty string context keys: ${missing.join(", ")}.`;
+	const nonStrings = Object.entries(values)
+		.filter(([, value]) => typeof value !== "string")
+		.map(([key]) => key);
+	return nonStrings.length > 0
+		? `All graph_run context values must be strings; invalid keys: ${nonStrings.join(", ")}. Put structured data in goal.`
+		: undefined;
+}
+
+function routingInstruction(graph: FpaGraph, resumeCompletedGraph = false): string {
+	const instructions = [
 		"FP&A runtime routing guard is active for this request.",
 		`The first eligible workflow is ${graph}.`,
-		"Call graph_list first, then graph_run with that exact graph and the complete immutable context.",
+		"Call graph_list first, then graph_run with that exact graph. All graph_run context values must be strings; never pass arrays, objects, numbers, booleans, or null.",
 		"Graph nodes own business phase execution. After a successful Graph handoff, only the main Agent may call the matching fpa_dashboard_publish_* tool; Graphs must never publish dashboard data.",
-	].join(" ");
+	];
+	if (graph === "fpa-strategy-planning" || graph === "fpa-forecast-freeze") {
+		instructions.push("Provide the immutable non-empty string context keys scope_id, cycle_id, and forecast_role. Put structured planning details in goal, not context.");
+	}
+	if (graph === "fpa-strategy-planning") {
+		instructions.push(resumeCompletedGraph
+			? "A completed combined Graph handoff was restored from this session. Continue modular publication from its persisted artifacts; do not rerun the Graph unless those artifacts are unavailable or the user changed the planning requirements. Publish period-review before next-strategy."
+			: "After this combined Graph completes, the main Agent must publish period-review first from artifacts/driver_analysis.json, then publish next-strategy from artifacts/strategy_proposal.json, artifacts/strategy_review.json, and artifacts/reviewed_strategy_handoff.json with the exact scope_id, cycle_id, forecast_role, and a fresh dashboard revision. Stop for the dashboard decision; do not run forecast yet.");
+	}
+	return instructions.join(" ");
 }
 
 export default function fpaRoutingGuardExtension(pi: ExtensionAPI): void {
 	let state = emptyState();
+	let installWarning: string | undefined;
+
+	function persistState(): void {
+		if (!state.requiredGraph) return;
+		pi.appendEntry(ROUTING_STATE_CUSTOM_TYPE, {
+			version: 1,
+			requiredGraph: state.requiredGraph,
+			graphRunCompleted: state.graphRunCompleted,
+			reviewPublished: state.reviewPublished,
+		} satisfies PersistedRoutingState);
+	}
+
+	pi.on("session_start", async (_event, ctx) => {
+		state = emptyState();
+		installWarning = undefined;
+		try {
+			const installed = await ensureFpaProjectGraphs({ cwd: ctx.cwd, trusted: ctx.isProjectTrusted() });
+			if (installed.warnings.length > 0) installWarning = installed.warnings.join(" ");
+		} catch (error) {
+			installWarning = error instanceof Error ? error.message : String(error);
+		}
+		const restored = [...ctx.sessionManager.getBranch()].reverse().find((entry) => entry.type === "custom" && entry.customType === ROUTING_STATE_CUSTOM_TYPE);
+		if (!restored || restored.type !== "custom" || !restored.data || typeof restored.data !== "object" || Array.isArray(restored.data)) return;
+		const data = restored.data as Partial<PersistedRoutingState>;
+		if (data.version !== 1 || !FP_AND_A_GRAPHS.includes(data.requiredGraph as FpaGraph)) return;
+		state.requiredGraph = data.requiredGraph;
+		state.graphRunStarted = data.graphRunCompleted === true;
+		state.graphRunCompleted = data.graphRunCompleted === true;
+		state.reviewPublished = data.graphRunCompleted === true && data.reviewPublished === true;
+	});
 
 	pi.on("before_agent_start", (event: BeforeAgentStartEvent) => {
-		const previousGraph = state.requiredGraph;
+		const previousState = state;
 		state = emptyState();
 		const active = new Set(pi.getActiveTools());
 		if (!GRAPH_TOOLS.every((tool) => active.has(tool))) return;
 
 		const classified = classifyFpaGraph(event.prompt);
 		const isContinuation = /^(?:继续|接着|下一步|continue|go on)[。.!！\s]*$/i.test(event.prompt.trim());
-		const requiredGraph = classified ?? (isContinuation ? previousGraph : undefined);
+		const requiredGraph = classified ?? (isContinuation ? previousState.requiredGraph : undefined);
 		if (!requiredGraph) return;
 		state.requiredGraph = requiredGraph;
-		return { systemPrompt: `${event.systemPrompt}\n\n${routingInstruction(requiredGraph)}` };
+		if (isContinuation && previousState.requiredGraph === requiredGraph) {
+			state.graphRunStarted = previousState.graphRunCompleted;
+			state.graphRunCompleted = previousState.graphRunCompleted;
+			state.reviewPublished = previousState.reviewPublished;
+		}
+		return { systemPrompt: `${event.systemPrompt}\n\n${routingInstruction(requiredGraph, state.graphRunCompleted)}${installWarning ? `\n\nFP&A Graph provisioning warning: ${installWarning}` : ""}` };
 	});
 
 	pi.on("tool_call", (event: ToolCallEvent) => {
@@ -184,15 +261,6 @@ export default function fpaRoutingGuardExtension(pi: ExtensionAPI): void {
 				return { block: true, reason: `Call graph_list before graph_run for ${graph}.` };
 			}
 			const requested = "graph" in event.input ? event.input.graph : undefined;
-			if (graph === "fpa-period-analysis" && state.graphRunCompleted && requested === "fpa-strategy-recommendation") {
-				if (!state.availableGraphs.has("fpa-strategy-recommendation")) {
-					return { block: true, reason: "fpa-strategy-recommendation is unavailable; do not emulate strategy work in the parent Agent." };
-				}
-				state.requiredGraph = "fpa-strategy-recommendation";
-				state.graphRunStarted = true;
-				state.graphRunCompleted = false;
-				return;
-			}
 			if (requested !== graph) {
 				return { block: true, reason: `Run the first eligible ${graph} Graph; received ${String(requested)}.` };
 			}
@@ -202,21 +270,28 @@ export default function fpaRoutingGuardExtension(pi: ExtensionAPI): void {
 					reason: `${graph} is not available. Return blocked; local work requires a new, explicit isolated-phase request.`,
 				};
 			}
+			const contextError = graphContextError(event, graph);
+			if (contextError) return { block: true, reason: contextError };
 			state.graphRunStarted = true;
 			state.graphRunCompleted = false;
+			state.reviewPublished = false;
+			persistState();
 			return;
 		}
 
 		if (event.toolName === "fpa_dashboard_module_status") return;
-		if ((graph === "fpa-forecast-freeze" || graph === "fpa-strategy-recommendation") && !state.graphRunStarted && event.toolName === "fpa_strategy_decision_commit") return;
-		const allowedPublication = graph === "fpa-period-analysis"
-			? "fpa_dashboard_publish_review"
-			: graph === "fpa-strategy-recommendation"
-				? "fpa_dashboard_publish_strategy"
-				: graph === "fpa-forecast-freeze"
-					? "fpa_dashboard_publish_forecast"
-					: "fpa_dashboard_refresh_queue";
-		if (event.toolName === allowedPublication && state.graphRunCompleted) return;
+		if ((graph === "fpa-forecast-freeze" || graph === "fpa-strategy-planning") && !state.graphRunStarted && event.toolName === "fpa_strategy_decision_commit") return;
+		const allowedPublications = graph === "fpa-strategy-planning"
+			? new Set(["fpa_dashboard_publish_review", "fpa_dashboard_publish_strategy"])
+			: graph === "fpa-forecast-freeze"
+				? new Set(["fpa_dashboard_publish_forecast"])
+				: new Set(["fpa_dashboard_refresh_queue"]);
+		if (allowedPublications.has(event.toolName) && state.graphRunCompleted) {
+			if (graph === "fpa-strategy-planning" && event.toolName === "fpa_dashboard_publish_strategy" && !state.reviewPublished) {
+				return { block: true, reason: "Publish the period-review module successfully before previewing or publishing next-strategy." };
+			}
+			return;
+		}
 
 		if (!event.toolName.startsWith("fpa_") && !artifactWrite(event)) return;
 		if (!state.catalogLoaded) {
@@ -249,6 +324,17 @@ export default function fpaRoutingGuardExtension(pi: ExtensionAPI): void {
 				? (event.details as { status?: unknown }).status
 				: undefined;
 			state.graphRunCompleted = status !== "failed" && status !== "blocked" && status !== "cancelled";
+			persistState();
+			return;
+		}
+		if (event.toolName === "fpa_dashboard_publish_review" && state.graphRunCompleted) {
+			const status = event.details && typeof event.details === "object" && "status" in event.details
+				? (event.details as { status?: unknown }).status
+				: undefined;
+			if (status === "published") {
+				state.reviewPublished = true;
+				persistState();
+			}
 		}
 	});
 }

package/graphs/fpa-forecast-freeze.json

@@ -1,11 +1,107 @@
 {
+  "description": "FP&A 正式预测冻结：消费已审核策略交接与主 Agent 已提交的精确 strategy_decision，生成、合成并冻结 approved_cycle_forecast；Graph 不请求审批、不发布仪表盘。",
+  "maxSteps": 10,
+  "mutationPolicy": "mutating",
   "name": "fpa-forecast-freeze",
-  "version": "2.0.0",
-  "start": "load_confirmed_strategy",
   "nodes": [
-    { "id": "load_confirmed_strategy", "type": "subagent", "agentName": "load_confirmed_strategy", "next": "draft_forecast", "tools": ["read"], "prompt": "核验主 Agent 已提交的策略 decision 与 reviewed handoff 精确一致；不得审批或发布仪表盘。" },
-    { "id": "draft_forecast", "type": "subagent", "agentName": "draft_forecast", "next": "compose_forecast", "skills": ["fpa-forecast-approved-strategy"], "tools": ["read", "write", "fpa_calc"], "prompt": "只按已确认策略写预测计划；不得重新优化策略或发布仪表盘。" },
-    { "id": "compose_forecast", "type": "tool", "tool": "fpa_forecast_compose", "next": "commit_forecast", "args": { "plan_path": "artifacts/forecast_plan.json" } },
-    { "id": "commit_forecast", "type": "tool", "tool": "fpa_artifact_commit", "mutates": true, "args": { "artifact": "{{data.compose_forecast.details.artifact}}", "context": { "scope_id": "{{context.scope_id}}", "cycle_id": "{{context.cycle_id}}", "forecast_role": "{{context.forecast_role}}" } } }
-  ]
+    {
+      "agentName": "load_confirmed_strategy",
+      "id": "load_confirmed_strategy",
+      "label": "核验已确认策略",
+      "next": "route_confirmed_strategy",
+      "outputKey": "confirmed_strategy",
+      "parseJson": true,
+      "prompt": "操作备注：{{goal}}\n\n读取 artifacts/reviewed_strategy_handoff.json、其中绑定的 strategy_proposal 与 strategy_review，以及操作备注明确给出的 strategy_decision path。必须核验 handoff status=ready；scope_id/cycle_id/forecast_role 与 Graph context 一致；proposal、review、handoff 的 strategy_version 一致；decision.kind=fpa.strategy.decision、decision=confirm；decision 的 strategy_version、handoff_fingerprint、decision_fingerprint 与操作备注和当前 handoff 精确一致。任一不一致即 blocked。不得请求或记录第二次审批，不得调用任何 fpa_dashboard_* 工具。\n\n只输出 JSON：{\"status\":\"ready|blocked\",\"strategy_version\":\"...\",\"strategy_decision_path\":\"...\",\"strategy_decision_fingerprint\":\"...\",\"review_conditions\":[],\"blockers\":[]}",
+      "skills": ["fpa-apply-core-rules"],
+      "systemPrompt": "你是 FP&A 已确认策略核验 Agent。只读核验主 Agent 已提交的不可变决策，不批准、不预测、不发布仪表盘。权威上下文为 scope_id={{context.scope_id}}、cycle_id={{context.cycle_id}}、forecast_role={{context.forecast_role}}。",
+      "tools": ["read"],
+      "type": "subagent"
+    },
+    {
+      "cases": [
+        { "equals": "ready", "label": "确认有效", "to": "draft_forecast" },
+        { "equals": "blocked", "label": "确认无效", "to": "report_blocked" }
+      ],
+      "default": { "label": "其他结果", "to": "report_blocked" },
+      "id": "route_confirmed_strategy",
+      "label": "判断是否可预测",
+      "path": "data.confirmed_strategy.status",
+      "type": "router"
+    },
+    {
+      "id": "report_blocked",
+      "label": "报告预测阻断",
+      "outputKey": "forecast_blocked",
+      "parseJson": true,
+      "prompt": "策略核验结果：{{data.confirmed_strategy}}\n预测计划修复结果：{{data.repair_forecast_plan}}\n\n汇总实际阻断原因。只输出 JSON：{\"kind\":\"fpa.graph-handoff\",\"status\":\"blocked\",\"graph\":\"fpa-forecast-freeze\",\"blockers\":[],\"required_action\":\"需要主会话处理的治理或策略动作\"}",
+      "systemPrompt": "用中文简洁报告预测阻断，只输出约定 JSON。",
+      "type": "prompt"
+    },
+    {
+      "agentName": "draft_forecast",
+      "id": "draft_forecast",
+      "label": "正式预测决策计划",
+      "next": "compose_forecast",
+      "outputKey": "draft_forecast",
+      "prompt": "操作备注：{{goal}}\n\n已核验策略与决策：{{data.confirmed_strategy}}\n\n读取 reviewed_strategy_handoff、strategy_proposal、strategy_review 和精确 strategy_decision，按 fpa-forecast-approved-strategy 写 artifacts/forecast_plan.json。不得重新优化策略；业务分配、范围、假设或审核条件需变化时必须 blocked 并回到策略规划。只写 allocation 与每个切片的 ROAS assumptions；revenue、汇总、单位和 frozen_at 由下游 fpa_forecast_compose 推导。优先使用 ua_spend 的 app_code/platform/media_source 真实组合；若已确认分配中的部分切片与当前上游映射不一致，不得擅自删除、置零、重分配或伪造映射，保留原切片交给 compose 自动产出 complete_with_limits、覆盖率和数据修复项。不得调用任何 fpa_dashboard_* 工具。",
+      "skills": ["fpa-apply-core-rules", "fpa-forecast-approved-strategy"],
+      "systemPrompt": "你是 FP&A 正式预测 Agent。只按已确认策略写预测计划，不请求审批、不发布仪表盘、不手算派生值。",
+      "tools": ["read", "write", "fpa_calc"],
+      "type": "subagent"
+    },
+    {
+      "args": { "plan_path": "artifacts/forecast_plan.json" },
+      "failure": { "maxAttempts": 2, "onError": "repair_forecast_plan" },
+      "id": "compose_forecast",
+      "label": "合成正式预测",
+      "next": "commit_forecast",
+      "outputKey": "compose_forecast",
+      "tool": "fpa_forecast_compose",
+      "type": "tool"
+    },
+    {
+      "agentName": "repair_forecast_plan",
+      "id": "repair_forecast_plan",
+      "label": "定点修正预测计划",
+      "next": "route_repair_forecast_plan",
+      "outputKey": "repair_forecast_plan",
+      "parseJson": true,
+      "prompt": "合成失败：{{data.__graphError}}\n\n读取 artifacts/forecast_plan.json、planning_brief 和 reviewed_strategy_handoff，只定点修正格式或 forecast plan 契约问题。不得通过删除、置零、重分配或伪造映射来修正数据质量问题；这类问题应由 compose 降级为 complete_with_limits。不得改变已确认策略的业务分配、范围、假设或条件；若错误要求此类变化，返回 blocked。不得调用任何 fpa_dashboard_* 工具。只输出 JSON：{\"status\":\"repaired|blocked\",\"changes\":[],\"blockers\":[]}",
+      "skills": ["fpa-forecast-approved-strategy"],
+      "systemPrompt": "你是预测计划修复 Agent，只按确定性合成报错做最小修正。",
+      "tools": ["read", "write", "edit"],
+      "type": "subagent"
+    },
+    {
+      "cases": [
+        { "equals": "repaired", "label": "已修正契约", "to": "compose_forecast" },
+        { "equals": "blocked", "label": "需要治理处理", "to": "report_blocked" }
+      ],
+      "default": { "label": "其他结果", "to": "report_blocked" },
+      "id": "route_repair_forecast_plan",
+      "label": "判断能否重新合成",
+      "path": "data.repair_forecast_plan.status",
+      "type": "router"
+    },
+    {
+      "args": {
+        "artifact": "{{data.compose_forecast.details.artifact}}",
+        "context": {
+          "cycle_id": "{{context.cycle_id}}",
+          "forecast_role": "{{context.forecast_role}}",
+          "scope_id": "{{context.scope_id}}"
+        }
+      },
+      "id": "commit_forecast",
+      "label": "冻结正式预测",
+      "mutates": true,
+      "outputKey": "commit_forecast",
+      "tool": "fpa_artifact_commit",
+      "type": "tool"
+    }
+  ],
+  "schemaVersion": 1,
+  "start": "load_confirmed_strategy",
+  "transitionLabels": { "default": "其他情况", "error": "失败", "next": "继续" },
+  "version": "2.2.0"
 }