@viccydev/pi-fpa 0.7.0 → 0.7.2

package/README.md

@@ -2,14 +2,14 @@
 
 面向 Pi 的完整 FP&A 周期资源包，目标运行时为 `@earendil-works/pi-coding-agent` 0.84.1。
 
-本包分发 Prompt Template、Skill、参考合同，以及数据读取、规范化 Artifact 和看板投影三个 Extension。包内不含业务数据与模型凭证，也不实现工作流状态机。多 Agent 隔离、人工审批和真实外部执行仍由宿主运行时或独立工作流承担。
+本包分发 Prompt Template、Skill、参考合同，以及 Graph 路由护栏、数据读取、规范化 Artifact 和看板投影四个 Extension。包内不含业务数据与模型凭证，也不实现工作流状态机；它声明并在工具调用边界执行主 Agent 必须遵守的 Graph-first 路由契约。Graph 的定义、状态、多 Agent 隔离、人工审批和真实外部执行仍由宿主运行时或独立工作流承担。
 
 ## 包含的资源
 
 Prompt Template：
 
-- `/fpa-plan-cycle`：从周期规划开始，经过 Actuals 诊断、驱动分析、策略模拟、推荐和独立复核；只有拿到匹配版本的外部人工批准后，才生成并冻结正式预测。
-- `/fpa-review-cycle`：新周期 Actuals 到达后，对比冻结的正式预测并形成周期复盘。
+- `/fpa-plan-cycle`：通过 `fpa-strategy-planning` Graph 完成 Actuals 诊断、驱动分析、策略模拟、推荐和独立复核，形成 `reviewed_strategy_handoff` 后停止；不跨越人工批准或冻结正式预测。
+- `/fpa-review-cycle`：在精确 Forecast/Execution refs 和新周期 Actuals 到达后，通过 `fpa-cycle-review` Graph 形成周期复盘。
 
 Skill：
 
@@ -27,6 +27,27 @@ Skill：
 
 执行 Skill 设置了 `disable-model-invocation: true`，不会出现在模型可主动调用的 Skill 摘要中，也没有对应 Prompt。只有用户显式输入 `/skill:fpa-execute-approved-strategy` 才能加载它；即使显式加载，缺少精确批准、单独执行授权、真实 adapter、幂等键或成功 preflight 时也必须保持 `blocked`，不得产生外部变更。
 
+## Graph-first 路由
+
+主 Agent 同时具备 `graph_list` 和 `graph_run` 时，任何跨两个或更多 FP&A
+阶段的请求都必须先查询 Graph catalog，再运行当前第一个满足入口条件的
+Graph；在此之前不得调用 `fpa_*` 工具或写 Artifact。四个工作流的边界为：
+
+- `fpa-strategy-planning`：规划至 `reviewed_strategy_handoff` 后停止。
+- `fpa-forecast-freeze`：只接受精确 handoff，经人工批准后冻结 Forecast。
+- `fpa-strategy-execution`：只接受精确 committed Forecast ref 和单独执行授权。
+- `fpa-cycle-review`：只接受精确 Forecast/Execution refs 与新 Actuals。
+
+Graph 的业务阻塞不能触发父 Agent 降级执行。Graph 工具不可用、catalog 不存在
+匹配 Graph 或匹配 Graph 无法加载时，多阶段入口保持 `blocked`；用户必须另行
+显式请求一个隔离阶段，父 Agent 不能自动把完整工作流改成本地串行执行。Graph
+节点只执行分配给自己的阶段，不得递归启动另一个 Graph。
+
+`fpa-routing-guard` Extension 会在 Pi 的 `tool_call` 执行前落实这条边界：
+它从展开后的请求识别多阶段 FP&A 意图，要求目标 Graph 与请求阶段一致，并
+阻断父 Agent 的提前 `fpa_*` 调用和 `artifacts/` 写入。Graph worker 没有
+`graph_list`/`graph_run` 时不会激活该护栏，因此节点仍可执行被分配的单一阶段。
+
 ## 数据 Extension（fpa-data）
 
 `extensions/fpa-data` 注册五个只读工具，连接 Supabase 数据集市：
@@ -127,12 +148,12 @@ pi list
 团队分发建议使用固定 Git tag：
 
 ```bash
-pi install git:github.com/linyqh/pi-fpa@v0.7.0
+pi install git:github.com/linyqh/pi-fpa@v0.7.2
 ```
 
 ## 发布到 npm
 
-发布动作由 GitHub Release 触发。Release 标签必须严格使用 `v<package.json version>`，例如版本 `0.7.0` 对应 `v0.7.0`。工作流会检出该标签，执行 `npm ci`、`npm test` 和包内容预检，全部通过后发布公开包 `@viccydev/pi-fpa`。普通 Release 发布到 `latest`，Prerelease 发布到 `next`。
+发布动作由 GitHub Release 触发。Release 标签必须严格使用 `v<package.json version>`，例如版本 `0.7.2` 对应 `v0.7.2`。工作流会检出该标签，执行 `npm ci`、`npm test` 和包内容预检，全部通过后发布公开包 `@viccydev/pi-fpa`。普通 Release 发布到 `latest`，Prerelease 发布到 `next`。
 
 发布认证使用 npm Trusted Publishing / OIDC，不使用长期 npm Token。npm 包后台的 Trusted Publisher 配置为：
 
@@ -148,14 +169,14 @@ pi install git:github.com/linyqh/pi-fpa@v0.7.0
 
 ```text
 /fpa-plan-cycle /path/to/project 2026-Q3 "按 App、Store、Channel Group 规划；预算上限见 planning input"
-/fpa-review-cycle /path/to/project 2026-Q3 "使用已冻结 forecast 和新到达的 Actuals snapshot"
+/fpa-review-cycle /path/to/project 2026-Q3 "使用精确 forecast/execution refs 和新到达的 Actuals snapshot"
 /skill:fpa-refresh-dashboard "预览并发布当前项目的预测闭环看板"
 ```
 
-规划入口不会进入真实策略执行。需要执行获批策略时，必须在单独、已授权的运行中显式调用：
+规划入口停在 `reviewed_strategy_handoff`，不会等待人工批准、冻结 Forecast 或进入真实策略执行。后续分别由 `fpa-forecast-freeze` 和 `fpa-strategy-execution` Graph 承担。若宿主没有 Graph 能力、且用户只请求一个隔离执行阶段，才可在单独、已授权的运行中显式调用：
 
 ```text
-/skill:fpa-execute-approved-strategy <exact strategy version and execution scope>
+/skill:fpa-execute-approved-strategy <exact committed forecast ref and execution scope>
 ```
 
 ## 资源迁移注意

package/extensions/fpa-dashboard/index.ts

@@ -58,11 +58,13 @@ export default function fpaDashboardExtension(pi: ExtensionAPI): void {
 		label: "Refresh FP&A Dashboard",
 		description:
 			"Build the forecast closed-loop dashboard from a committed approved forecast, optional committed execution receipt, and current read-only FP&A Actuals. " +
-			"Preview computes and validates without publishing; publish requires the exact preview fingerprint and atomically promotes a content-addressed generation.",
+			"Preview computes and validates without publishing; publish requires the exact preview fingerprint and atomically promotes a content-addressed generation. " +
+			"A backtest can be displayed only from an exact committed artifact when the user explicitly requests it.",
 		promptSnippet: "Preview or atomically publish the forecast closed-loop FP&A dashboard",
 		promptGuidelines: [
 			"Always call fpa_dashboard_refresh with mode=preview before mode=publish and carry forward the exact preview_fingerprint.",
 			"Never write .fpa-dashboard files with generic file or shell tools; use fpa_dashboard_refresh so calculations, lineage, and atomic publication stay consistent.",
+			"Set allow_backtest_display=true only when the user explicitly asks to display or publish an exact committed backtest; never infer this authorization from Graph completion.",
 		],
 		parameters: Type.Object(
 			{
@@ -70,6 +72,7 @@ export default function fpaDashboardExtension(pi: ExtensionAPI): void {
 				mode: StringEnum(["preview", "publish"] as const),
 				locale: Type.Optional(StringEnum(["zh-CN", "en-US"] as const)),
 				expected_preview_fingerprint: Type.Optional(Type.String({ pattern: "^[a-f0-9]{64}$" })),
+				allow_backtest_display: Type.Optional(Type.Boolean()),
 				scope_id: Type.Optional(Type.String({ minLength: 1, maxLength: 256 })),
 				cycle_id: Type.Optional(Type.String({ minLength: 1, maxLength: 256 })),
 				forecast_ref: Type.Optional(artifactRefSchema),
@@ -86,6 +89,9 @@ export default function fpaDashboardExtension(pi: ExtensionAPI): void {
 			if (hasAnyExactField && exactFields.some((value) => value === undefined)) {
 				throw new Error("scope_id, cycle_id, and forecast_ref must be supplied together; exact refresh never falls back to current artifacts.");
 			}
+			if (params.allow_backtest_display && !hasAnyExactField) {
+				throw new Error("allow_backtest_display requires an exact scope_id, cycle_id, and forecast_ref.");
+			}
 			const exact = hasAnyExactField ? {
 				scopeId: params.scope_id as string,
 				cycleId: params.cycle_id as string,
@@ -96,19 +102,24 @@ export default function fpaDashboardExtension(pi: ExtensionAPI): void {
 			} : undefined;
 			if (exact) {
 				const exactForecast = await readArtifactByRef(ctx.cwd, exact.forecastRef);
-				if (exactForecast.ledgerContext?.forecast_role === "backtest") {
-					throw new Error("A backtest forecast cannot be previewed or published as the operating dashboard.");
+				const exactRole = exactForecast.ledgerContext?.forecast_role;
+				if (exactRole === "backtest" && params.allow_backtest_display !== true) {
+					throw new Error("Displaying a backtest requires explicit user authorization through allow_backtest_display=true.");
+				}
+				if (params.allow_backtest_display === true && exactRole !== "backtest") {
+					throw new Error("allow_backtest_display is valid only for an exact committed backtest.");
 				}
 			}
 			const { build, forecast, actuals, sliceKeyMismatch, projector, runtime } = await buildDashboardProjection(ctx.cwd, params.preset, params.locale ?? "zh-CN", exact, signal);
-			if (build.source.forecast_role === "backtest") {
-				throw new Error("A backtest forecast cannot be previewed or published as the operating dashboard.");
+			if (build.source.forecast_role === "backtest" && params.allow_backtest_display !== true) {
+				throw new Error("Displaying a backtest requires explicit user authorization through allow_backtest_display=true.");
 			}
 			const previewFingerprint = dashboardBuildFingerprint(build, projector);
 			const summary = {
 				preset: params.preset,
 				preview_fingerprint: previewFingerprint,
 				forecast_version: forecast.forecast_version,
+				forecast_role: build.source.forecast_role,
 				forecast_fingerprint: build.source.forecast_fingerprint,
 				execution_fingerprint: build.source.execution_fingerprint,
 				data_as_of: build.source.data_as_of,
@@ -146,7 +157,14 @@ export default function fpaDashboardExtension(pi: ExtensionAPI): void {
 			if (params.expected_preview_fingerprint !== previewFingerprint) {
 				throw new Error("Dashboard inputs changed after preview; run preview again before publishing.");
 			}
-			const published = await publishDashboard({ cwd: ctx.cwd, build, projector, runtime, actualsSnapshot: actuals });
+			const published = await publishDashboard({
+				cwd: ctx.cwd,
+				build,
+				projector,
+				runtime,
+				actualsSnapshot: actuals,
+				allowBacktestDisplay: params.allow_backtest_display === true,
+			});
 			return toolResult({ status: "published", ...summary, dashboard_dir: published.dashboardDir, published_datasets: published.publishedDatasets });
 		},
 	});

package/extensions/fpa-dashboard/publisher.ts

@@ -22,6 +22,7 @@ export interface PublishDashboardOptions {
 	runtime: DashboardProjectorRuntime;
 	publishedAt?: string;
 	actualsSnapshot?: DashboardActualsSnapshot;
+	allowBacktestDisplay?: boolean;
 }
 
 export interface PublishDashboardResult {
@@ -177,8 +178,8 @@ export function dashboardBuildFingerprint(build: DashboardBuild, projector: Dash
 
 export async function publishDashboard(options: PublishDashboardOptions): Promise<PublishDashboardResult> {
 	assertBuild(options.build);
-	if (options.build.source.forecast_role === "backtest") {
-		throw new Error("A backtest forecast cannot replace the operating dashboard.");
+	if (options.build.source.forecast_role === "backtest" && options.allowBacktestDisplay !== true) {
+		throw new Error("A backtest cannot replace the operating dashboard without explicit user authorization.");
 	}
 	const projector = validateProjectorProvenance(options.projector);
 	const runtime = validateProjectorRuntime(options.runtime);

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

@@ -0,0 +1,220 @@
+import type {
+	BeforeAgentStartEvent,
+	ExtensionAPI,
+	ToolCallEvent,
+	ToolResultEvent,
+} from "@earendil-works/pi-coding-agent";
+
+const GRAPH_TOOLS = ["graph_list", "graph_run"] as const;
+const FP_AND_A_GRAPHS = [
+	"fpa-strategy-planning",
+	"fpa-forecast-freeze",
+	"fpa-strategy-execution",
+	"fpa-cycle-review",
+] as const;
+type FpaGraph = (typeof FP_AND_A_GRAPHS)[number];
+
+interface RoutingState {
+	requiredGraph?: FpaGraph;
+	catalogLoaded: boolean;
+	availableGraphs: Set<string>;
+	graphRunStarted: boolean;
+}
+
+function emptyState(): RoutingState {
+	return {
+		catalogLoaded: false,
+		availableGraphs: new Set(),
+		graphRunStarted: false,
+	};
+}
+
+function includesAny(prompt: string, patterns: RegExp[]): boolean {
+	return patterns.some((pattern) => pattern.test(prompt));
+}
+
+function isMetaRequest(prompt: string): boolean {
+	return includesAny(prompt, [
+		/(?:解释|说明).*(?:为何|为什么)/,
+		/(?:为何|为什么).*(?:未|没|没有|不)/,
+		/(?:排查|修复|分析).*(?:bug|路由|工作流未运行|工具顺序|代码问题)/i,
+		/(?:比较|对比|说明|解释).*(?:graph|工作流).*(?:职责|区别|差异|定义|作用|用途)/i,
+		/(?:修改|编辑|更新|创建|设计|删除).*(?:graph|工作流|fpa-(?:strategy|forecast|cycle)).*(?:定义|节点|配置|spec|graph)?/i,
+		/(?:查询|查看|解释|计算).*(?:不做|不要|无需).*(?:规划|预测|执行|复盘|推荐)/i,
+		/(?:不要|无需|不需|禁止)(?:执行|运行|调用).*(?:工作流|graph|fpa_)/i,
+		/(?:do not|don't|without) (?:run|execute|call)/i,
+	]);
+}
+
+function isSingleInformationalRequest(prompt: string): boolean {
+	const asksForOneFact = /(?:是什么|什么意思|定义|查询|查看).*(?:ROAS|Revenue|Actuals?|Forecast|FP&A|\bFPA\b|\bUA\b)|(?:ROAS|Revenue|Actuals?|Forecast|FP&A|\bFPA\b|\bUA\b).*(?:是什么|什么意思|定义)/i.test(prompt);
+	if (!asksForOneFact) return false;
+	return !/(?:然后|接着|随后|后(?:再)?|并(?:且)?|制定|规划|预算方案|分析驱动|策略建议|独立审核|冻结|执行|复盘)/i.test(prompt);
+}
+
+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;
+	return !/(?:然后|接着|随后|再进入|后再|直至|全流程|完整流程|end[- ]to[- ]end)/i.test(prompt);
+}
+
+function hasFpaIntent(prompt: string): boolean {
+	if (includesAny(prompt, [/分析数据.*(?:方案|计划)/, /下一周期.*(?:方案|计划)/, /完整.*(?:流程|工作流)/])) return true;
+	const businessSignals = [
+		/FP&A|\bFPA\b/i,
+		/\bUA\b/i,
+		/ROAS/i,
+		/Actuals?/i,
+		/\bspend\b/i,
+		/预算|budget/i,
+		/规划|\bplan(?:ning)?\b/i,
+		/投放|campaign/i,
+		/策略|strategy/i,
+		/预测|forecast/i,
+		/复盘|variance/i,
+		/归因|attribution/i,
+		/收入|revenue/i,
+		/花费|cost/i,
+	];
+	return businessSignals.filter((pattern) => pattern.test(prompt)).length >= 2;
+}
+
+export function classifyFpaGraph(prompt: string): FpaGraph | undefined {
+	const normalized = prompt.toLowerCase();
+	if (isMetaRequest(normalized) || isExplicitIsolatedPhase(prompt) || isSingleInformationalRequest(prompt)) return undefined;
+
+	for (const graph of FP_AND_A_GRAPHS) {
+		if (
+			normalized.includes(graph) &&
+			/(?:运行|执行|启动|调用|使用|通过|\brun\b|\bexecute\b|\bstart\b)/i.test(normalized)
+		) return graph;
+	}
+
+	const exactRef = /(?:精确|exact|immutable|committed|已提交|不可变).{0,24}(?:ref|引用)/i;
+	if (
+		includesAny(normalized, [/复盘/, /cycle[ -]?review/, /variance/, /偏差/]) &&
+		includesAny(normalized, [/actuals?/, /实际/]) &&
+		/(?:forecast|预测).{0,32}(?:execution|执行).{0,32}(?:refs?|引用)|(?:refs?|引用).{0,32}(?:forecast|预测).{0,32}(?:execution|执行)/i.test(normalized)
+	) {
+		return "fpa-cycle-review";
+	}
+
+	if (
+		/reviewed_strategy_handoff|(?:精确|exact|不可变).{0,24}handoff/i.test(normalized) &&
+		includesAny(normalized, [/冻结.*预测/, /正式预测/, /approved.*forecast/, /forecast.*freeze/])
+	) {
+		return "fpa-forecast-freeze";
+	}
+
+	if (
+		includesAny(normalized, [/执行/, /execute/, /投放变更/, /external mutation/]) &&
+		includesAny(normalized, [/授权/, /获批/, /approved/, /批准/]) &&
+		/(?:forecast|预测)/i.test(normalized) && exactRef.test(normalized)
+	) {
+		return "fpa-strategy-execution";
+	}
+
+	return hasFpaIntent(normalized) ? "fpa-strategy-planning" : undefined;
+}
+
+function contentText(event: ToolResultEvent): string {
+	return event.content
+		.filter((item): item is Extract<(typeof event.content)[number], { type: "text" }> => item.type === "text")
+		.map((item) => item.text)
+		.join("\n");
+}
+
+function catalogNames(event: ToolResultEvent): string[] {
+	const details = event.details;
+	if (details && typeof details === "object" && "names" in details) {
+		const names = (details as { names?: unknown }).names;
+		if (Array.isArray(names)) return names.filter((name): name is string => typeof name === "string");
+	}
+	return FP_AND_A_GRAPHS.filter((graph) => contentText(event).includes(graph));
+}
+
+function artifactWrite(event: ToolCallEvent): boolean {
+	if (event.toolName === "write" || event.toolName === "edit") {
+		const path = "path" in event.input && typeof event.input.path === "string" ? event.input.path : "";
+		return /(?:^|[\\/])artifacts?[\\/]/i.test(path);
+	}
+	if (event.toolName !== "bash") return false;
+	const command = "command" in event.input && typeof event.input.command === "string" ? event.input.command : "";
+	return /artifacts?[\\/]/i.test(command);
+}
+
+function routingInstruction(graph: FpaGraph): string {
+	return [
+		"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.",
+		"Do not call fpa_* tools or write artifacts in the parent agent; Graph nodes own phase execution.",
+	].join(" ");
+}
+
+export default function fpaRoutingGuardExtension(pi: ExtensionAPI): void {
+	let state = emptyState();
+
+	pi.on("before_agent_start", (event: BeforeAgentStartEvent) => {
+		const previousGraph = state.requiredGraph;
+		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);
+		if (!requiredGraph) return;
+		state.requiredGraph = requiredGraph;
+		return { systemPrompt: `${event.systemPrompt}\n\n${routingInstruction(requiredGraph)}` };
+	});
+
+	pi.on("tool_call", (event: ToolCallEvent) => {
+		const graph = state.requiredGraph;
+		if (!graph) return;
+
+		if (event.toolName === "graph_list") return;
+		if (event.toolName === "graph_run") {
+			if (!state.catalogLoaded) {
+				return { block: true, reason: `Call graph_list before graph_run for ${graph}.` };
+			}
+			const requested = "graph" in event.input ? event.input.graph : undefined;
+			if (requested !== graph) {
+				return { block: true, reason: `Run the first eligible ${graph} Graph; received ${String(requested)}.` };
+			}
+			if (!state.availableGraphs.has(graph)) {
+				return {
+					block: true,
+					reason: `${graph} is not available. Return blocked; local work requires a new, explicit isolated-phase request.`,
+				};
+			}
+			state.graphRunStarted = true;
+			return;
+		}
+
+		if (!event.toolName.startsWith("fpa_") && !artifactWrite(event)) return;
+		if (!state.catalogLoaded) {
+			return { block: true, reason: `Call graph_list before any FP&A phase tool for ${graph}.` };
+		}
+		if (!state.availableGraphs.has(graph)) {
+			return {
+				block: true,
+				reason: `${graph} is unavailable. Return blocked; do not automatically fall back to a multi-stage local workflow.`,
+			};
+		}
+		if (!state.graphRunStarted) {
+			return { block: true, reason: `Call graph_run with ${graph} before any FP&A phase tool.` };
+		}
+		return {
+			block: true,
+			reason: `The ${graph} Graph owns FP&A phase work; the parent agent must not execute FP&A phase tools or write artifacts.`,
+		};
+	});
+
+	pi.on("tool_result", (event: ToolResultEvent) => {
+		if (!state.requiredGraph || event.toolName !== "graph_list" || event.isError) return;
+		state.catalogLoaded = true;
+		state.availableGraphs = new Set(catalogNames(event));
+	});
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@viccydev/pi-fpa",
-  "version": "0.7.0",
+  "version": "0.7.2",
   "type": "module",
   "description": "Full-cycle FP&A planning, strategy, forecast, and review prompts, skills, and data tools for Pi",
   "license": "UNLICENSED",
@@ -30,7 +30,7 @@
 		"fpa-dashboard-worker": "./bin/fpa-dashboard-worker.mjs"
 	},
   "scripts": {
-		"test": "node tests/package-structure.test.mjs && node tests/extension-unit.test.mjs && node --test tests/catalog-timeout.test.mjs tests/artifact-store.test.mjs tests/artifact-ledger.test.mjs tests/artifact-handoff.test.mjs tests/forecast-compose.test.mjs tests/dashboard-actuals.test.mjs tests/dashboard-projector.test.mjs tests/cycle-operating-projection.test.mjs tests/forward-outlook.test.mjs tests/forecast-accuracy.test.mjs tests/dashboard-publisher.test.mjs tests/dashboard-provenance.test.mjs tests/dashboard-coordinator.test.mjs && node tests/pi-loader-smoke.mjs && node tests/worker-loader-smoke.mjs && node tests/publish-workflow.test.mjs",
+		"test": "node tests/package-structure.test.mjs && node tests/workflow-routing.test.mjs && node --test tests/workflow-routing-guard.test.mjs && node tests/extension-unit.test.mjs && node --test tests/catalog-timeout.test.mjs tests/artifact-store.test.mjs tests/artifact-ledger.test.mjs tests/artifact-handoff.test.mjs tests/forecast-compose.test.mjs tests/dashboard-actuals.test.mjs tests/dashboard-projector.test.mjs tests/cycle-operating-projection.test.mjs tests/forward-outlook.test.mjs tests/forecast-accuracy.test.mjs tests/dashboard-publisher.test.mjs tests/dashboard-provenance.test.mjs tests/dashboard-coordinator.test.mjs && node tests/pi-loader-smoke.mjs && node tests/worker-loader-smoke.mjs && node tests/publish-workflow.test.mjs",
     "test:structure": "node tests/package-structure.test.mjs",
 		"test:unit": "node tests/extension-unit.test.mjs && node --test tests/catalog-timeout.test.mjs tests/artifact-store.test.mjs tests/artifact-ledger.test.mjs tests/artifact-handoff.test.mjs tests/forecast-compose.test.mjs tests/dashboard-actuals.test.mjs tests/dashboard-projector.test.mjs tests/cycle-operating-projection.test.mjs tests/forward-outlook.test.mjs tests/forecast-accuracy.test.mjs tests/dashboard-publisher.test.mjs tests/dashboard-provenance.test.mjs tests/dashboard-coordinator.test.mjs",
     "test:loader": "node tests/pi-loader-smoke.mjs && node tests/worker-loader-smoke.mjs",
@@ -58,6 +58,7 @@
       "./skills"
     ],
     "extensions": [
+		"./extensions/fpa-routing-guard/index.ts",
       "./extensions/fpa-data/index.ts",
       "./extensions/fpa-artifacts/index.ts",
       "./extensions/fpa-dashboard/index.ts"

package/prompts/fpa-plan-cycle.md

@@ -1,5 +1,5 @@
 ---
-description: 启动完整 FP&A 策略规划，并在匹配版本获得外部人工批准后形成正式预测
+description: 通过 Graph 启动 FP&A 策略规划，并在复核交接点停止
 argument-hint: "<project-root> <cycle-id> [instructions]"
 ---
 
@@ -14,25 +14,25 @@ argument-hint: "<project-root> <cycle-id> [instructions]"
 - 明确周期的开始时间、结束时间、业务时区、报告币种、比较基线，以及 App、Store、Product Group、Channel Group 范围。不能从 `$2` 的名称暗自推断日期边界。
 - 关键输入缺失时列出缺口并保持 `blocked`；不得编造字段、表、数据、批准或 Artifact。
 
-## 能力路由
+## 强制 Graph 路由
 
-先读取可用 Skill 中的 `fpa-apply-core-rules`，再从 `fpa-plan-cycle` 开始。根据当前阶段依次按需读取：
+先读取 `fpa-apply-core-rules`。如果当前 Agent 提供 `graph_list` 和
+`graph_run`，必须先调用 `graph_list`，确认 `fpa-strategy-planning` 后再以
+完整用户目标、已解析的项目根、周期边界、业务范围和数据上下文调用
+`graph_run`。在这两步之前不得直接调用任何 `fpa_*` 工具或写 Artifact，
+父 Agent 也不得自行串行模拟 Graph 内的阶段。
 
-1. `fpa-diagnose-actuals`
-2. `fpa-analyze-drivers`
-3. `fpa-simulate-strategies`
-4. `fpa-recommend-strategy`
-5. `fpa-review-strategy`
-6. `fpa-forecast-approved-strategy`
-
-不要一次性加载所有 Skill，也不要在本 Prompt 中复述它们的完整规则。每一阶段只消费已完成的上游 Artifact，并按对应 `references/artifact-contract.md` 输出。
+如果匹配 Graph 不在 catalog 中或无法加载，列出缺口并保持 `blocked`；不得把
+本多阶段入口自动降级为父 Agent 本地执行。用户之后可另行显式请求一个隔离阶段。
+Graph 返回业务阻塞同样不构成降级理由。所需上下文缺失时也保持 `blocked`。
 
 ## 不可跳过的停点
 
 - 策略推荐者不得批准或独立复核自己的提案。若宿主不能证明复核上下文与提案作者独立，复核阶段必须报告 `blocked`。
-- 独立复核完成后停止并等待外部人工批准。聊天中的认可、模型自我确认或 Forecast 授权都不等于策略执行授权。
-- 只有人工批准明确引用同一 `strategy_proposal` 版本且批准条件已满足，才读取 `fpa-forecast-approved-strategy` 生成正式预测。
-- 本入口的终点是已确认持久化的 `approved_cycle_forecast`。不得加载或调用策略执行 Skill，不得声称已经修改任何外部投放状态。
+- 独立复核完成后，`fpa-strategy-planning` 必须生成精确绑定提案与复核版本的 `reviewed_strategy_handoff`，然后停止。
+- 聊天中的认可、模型自我确认或 Forecast 授权都不等于策略执行授权。
+- 人工批准与正式预测属于后续独立的 `fpa-forecast-freeze` Graph；父 Agent 不得在本入口中继续执行。
+- 本入口不得加载 Forecast 或策略执行 Skill，不得声称已经冻结 Forecast 或修改外部投放状态。
 
 ## 全局计算与证据底线
 
@@ -41,4 +41,4 @@ argument-hint: "<project-root> <cycle-id> [instructions]"
 - 区分 observed、assumed、modeled、judgment 和 approved；相关性不得冒充因果关系。
 - 每个结论记录实际表、字段、grain、join key、时间范围、`data_as_of`、版本和质量限制。
 
-最终交付应包含 `planning_brief`、`actuals_snapshot`、`data_issue_report`、`driver_analysis`、`strategy_scenarios`、`strategy_proposal`、独立 `strategy_review`、外部 `strategy_approval` 证据，以及批准后的 `approved_cycle_forecast`。任何未完成项都必须标注状态和阻塞原因。
+最终交付应包含 `planning_brief`、`actuals_snapshot`、`data_issue_report`、`driver_analysis`、`strategy_scenarios`、`strategy_proposal`、独立 `strategy_review` 和 `reviewed_strategy_handoff`。任何未完成项都必须标注状态和阻塞原因。

package/prompts/fpa-review-cycle.md

@@ -10,17 +10,21 @@ argument-hint: "<project-root> <cycle-id> [instructions]"
 ## 输入解析
 
 - 把 `$1` 作为项目根并确认它真实存在。
-- 找到该周期不可变的 `approved_cycle_forecast`、对应策略与批准证据，以及覆盖同一业务周期的新 Actuals snapshot。
+- 找到该周期精确不可变的 `approved_cycle_forecast` ref、同一周期精确不可变的 `execution_receipt` ref，以及覆盖同一业务周期的新 Actuals snapshot；不得用 mutable current pointer 或复制的 payload 代替。
 - 默认从项目根解析 `LOCAL_FPA_MART_FIELD_CATALOG.md` 和 `LOCAL_FPA_MART_SCHEMA.sql`；补充要求提供其他显式路径时使用显式路径。
 - 明确复盘周期的精确起止时间、业务时区、币种和业务范围。若 Forecast 与 Actuals 不可比，缩窄结论或保持 `blocked`，不得修写历史 Forecast。
 
-## 能力路由
+## 强制 Graph 路由
 
-1. 先读取 `fpa-apply-core-rules`。
-2. 使用 `fpa-diagnose-actuals` 验证新 Actuals 的 grain、完整性、成熟度和可比性。
-3. 使用 `fpa-review-cycle` 对比冻结 Forecast 与 Actuals，生成其 Artifact 合同要求的 `cycle_review`。
+先读取 `fpa-apply-core-rules`。如果当前 Agent 提供 `graph_list` 和
+`graph_run`，必须先调用 `graph_list`，确认 `fpa-cycle-review` 后再以完整用户
+目标、精确 Forecast ref、精确 Execution ref 和新 Actuals 上下文调用
+`graph_run`。在这两步之前不得直接调用任何 `fpa_*` 工具或写 Artifact，
+父 Agent 不得自行执行 Actuals 诊断或复盘阶段。
 
-只按需读取上述 Skill，不要把 Skill 正文复制到结果中。
+如果匹配 Graph 不在 catalog 中或无法加载，列出缺口并保持 `blocked`；不得把
+本多阶段入口自动降级为父 Agent 本地执行。用户之后可另行显式请求一个隔离阶段。
+Graph 返回业务阻塞同样不构成降级理由。关键 ref 或上下文缺失时保持 `blocked`。
 
 ## 复盘底线
 

package/skills/fpa-apply-core-rules/SKILL.md

@@ -7,9 +7,43 @@ description: Apply the shared period, source-grain, metric, quality, approval, a
 
 Use this skill together with the phase-specific FP&A skill. It is the common contract, not a complete workflow by itself.
 
+## Main-Agent Graph routing gate
+
+Apply this gate before reading phase references, calling business tools, or
+writing artifacts. It applies only when the current agent exposes both
+`graph_list` and `graph_run`.
+
+1. If the user's goal spans two or more FP&A phases, call `graph_list` before
+   any `fpa_*` tool or artifact write. A phase handoff in a Skill is not
+   permission for the parent agent to emulate the remaining phases itself.
+2. Select the first currently eligible workflow from the catalog:
+
+   | Eligible request and evidence | Required Graph |
+   | --- | --- |
+   | New or changed objective requiring planning, Actuals diagnosis, driver analysis, scenarios, recommendation, or independent review | `fpa-strategy-planning` |
+   | Ready `reviewed_strategy_handoff` plus a request for human approval and an official forecast | `fpa-forecast-freeze` |
+   | Exact committed approved Forecast ref plus an authorized execution request | `fpa-strategy-execution` |
+   | Exact Forecast and Execution refs plus newly arrived comparable Actuals | `fpa-cycle-review` |
+
+3. Call `graph_run` with the user's complete goal and the exact immutable
+   context required by that Graph. The parent agent must not reproduce its
+   nodes, pre-run their `fpa_*` calls, or automatically cross the next approval
+   or artifact handoff after the Graph returns.
+4. If required context is missing or ambiguous, return `blocked` and request
+   the exact identity or ref. Do not fall back to direct phase execution.
+
+Local phase execution is allowed when the user explicitly requests only one
+isolated phase, or inside a Graph node. If Graph tools are unavailable or the
+matching Graph is absent/unloadable for a multi-stage request, return `blocked`;
+do not automatically execute the workflow locally. The user may then submit a
+new, explicit isolated-phase request. A business validation failure or a
+blocked Graph result is never permission to fall back. A Graph node normally
+receives only its assigned phase tools and Skills; it must execute that phase
+locally and must not recursively start another Graph.
+
 ## Required procedure
 
-1. Read [core-rules.md](references/core-rules.md) before calculating or judging anything.
+1. After the routing gate permits local phase work, read [core-rules.md](references/core-rules.md) before calculating or judging anything.
 2. Identify the workflow phase and consume only artifacts that precede it.
 3. Bind the requested business period to exact start and end timestamps, timezone, currency, App, Store, and Channel scope.
 4. Check that every source grain can support the requested period. Never manufacture finer-grained results by prorating coarse facts.

package/skills/fpa-apply-core-rules/references/core-rules.md

@@ -2,19 +2,35 @@
 
 ## 1. Workflow and artifacts
 
-Planning workflow:
+Strategy-planning workflow (`fpa-strategy-planning`):
 
-`planning_brief -> actuals_snapshot + data_issue_report -> driver_analysis -> strategy_scenarios -> strategy_proposal -> strategy_review -> human strategy_approval -> approved_cycle_forecast`
+`planning_brief -> actuals_snapshot + data_issue_report -> driver_analysis -> strategy_scenarios -> strategy_proposal -> strategy_review -> reviewed_strategy_handoff`
 
-The planning workflow ends after the approved forecast is frozen.
+This Graph stops after an independently reviewed strategy handoff. It does not
+approve the strategy, create an official forecast, or execute the allocation.
 
-Execution is a separate workflow:
+Forecast-freeze workflow (`fpa-forecast-freeze`), entered only with that exact
+ready handoff:
 
-`strategy_approval + strategy_proposal -> execution_receipt`
+`reviewed_strategy_handoff -> human strategy_approval -> forecast_plan -> approved_cycle_forecast`
 
-Next-cycle review is another workflow, triggered only after new Actuals arrive:
+The forecast Graph owns approval recording, deterministic composition, and
+artifact freezing. A rejected approval returns to a new
+`fpa-strategy-planning` version rather than modifying the reviewed proposal in
+place.
 
-`approved_cycle_forecast + next actuals_snapshot -> cycle_review -> optional new planning_brief`
+Execution is a separate `fpa-strategy-execution` workflow:
+
+`exact approved_cycle_forecast ref -> execution_plan -> human confirmation -> execution_receipt`
+
+Next-cycle review is a separate `fpa-cycle-review` workflow, triggered only
+after new Actuals arrive:
+
+`exact approved_cycle_forecast ref + exact execution_receipt ref + next actuals_snapshot -> cycle_review -> optional new planning cycle`
+
+The main agent routes to only the currently eligible Graph. It must not emulate
+multiple phases itself or automatically cross a human approval or immutable
+artifact handoff.
 
 Artifact ownership belongs to the workflow runtime or artifact store. An agent produces content and metadata; it must not invent a successful save, approval, or external action.
 

package/skills/fpa-execute-approved-strategy/SKILL.md

@@ -12,6 +12,8 @@ Load `$fpa-apply-core-rules` first. This skill is intentionally fail-closed and
 
 Require all of the following before any external mutation:
 
+- the exact committed `approved_cycle_forecast` ref returned by
+  `fpa-forecast-freeze`, not a mutable current pointer or a copied payload;
 - explicit human `strategy_approval` for the exact `strategy_proposal` version;
 - exact target accounts, App, Store, Channel, budget, period, and permitted operations;
 - a named, currently available execution adapter/tool and its authentication context;
@@ -19,7 +21,9 @@ Require all of the following before any external mutation:
 - an idempotency key or adapter-supported equivalent;
 - a successful read-only preflight and, where supported, dry-run/preview.
 
-If any requirement is missing, return `blocked` and make no external call. Never simulate an adapter or fabricate a receipt.
+If any requirement is missing or the committed Forecast ref does not match the
+approved scope and proposal lineage, return `blocked` and make no external
+call. Never simulate an adapter or fabricate a receipt.
 
 ## Procedure
 

package/skills/fpa-forecast-approved-strategy/SKILL.md

@@ -5,18 +5,24 @@ description: Produce and freeze the official operating forecast for the next bus
 
 # FP&A Approved Strategy Forecast
 
-Load `$fpa-apply-core-rules` first. This is the final stage of the planning workflow.
+Load `$fpa-apply-core-rules` first. This is a post-approval phase inside the
+separate forecast-freeze workflow, not a continuation that the planning parent
+agent may start by itself.
 
 ## Entry gate
 
 Require all of the following:
 
+- the exact `reviewed_strategy_handoff` reference produced by
+  `fpa-strategy-planning`, including its bound proposal and review identities;
 - the exact `strategy_proposal` version;
 - a completed independent `strategy_review` supporting that version;
 - explicit human `strategy_approval` identifying the same version and any conditions;
 - the eligible data snapshot, assumptions, and model version used for forecasting.
 
 If approval evidence is absent, ambiguous, expired, conditional but unmet, or refers to another strategy version, return `blocked` without forecasting.
+If the handoff is missing or any supplied proposal/review identity differs
+from it, return `blocked`; never reconstruct or substitute the handoff.
 
 ## Procedure
 
@@ -34,7 +40,9 @@ If approval evidence is absent, ambiguous, expired, conditional but unmet, or re
    period start and is the approved direct successor of the active cycle. Use
    `backtest` for a historical rerun frozen after its target
    period; it is immutable evidence, not an operating plan, and it must not
-   replace the current pointer or enter the operating dashboard queue. A
+   replace the current pointer or enter the automatic operating dashboard
+   queue. It may be displayed from its exact immutable reference only when the
+   user explicitly requests a backtest dashboard publication. A
    `next_plan` is likewise stored as forward lineage and does not replace the
    legacy current pointer; its explicit dashboard handoff links it to the
    active cycle after successor validation.
@@ -82,4 +90,12 @@ declaration upstream needs correcting.
 
 ## Completion
 
-The planning workflow ends only after `fpa_artifact_commit` returns `status: committed`, an `immutable_fingerprint`, and (for assigned artifacts) a `dashboard_handoff`. Commit freezes the business artifact but does not enqueue or publish dashboard work. The calling main Agent owns that explicit handoff. A Markdown report is optional context, not the frozen source of truth. Never report a forecast as frozen on the strength of a written file alone — the file is a draft until the tool returns a fingerprint. Execution, if requested, is a separate workflow using `$fpa-execute-approved-strategy`. Review waits for the next cycle's Actuals and uses `$fpa-review-cycle`.
+The forecast-freeze workflow ends only after `fpa_artifact_commit` returns
+`status: committed`, an `immutable_fingerprint`, and (for assigned artifacts) a
+`dashboard_handoff`. Commit freezes the business artifact but does not enqueue
+or publish dashboard work. The calling main Agent owns that explicit handoff.
+A Markdown report is optional context, not the frozen source of truth. Never
+report a forecast as frozen on the strength of a written file alone — the file
+is a draft until the tool returns a fingerprint. Execution, if requested, is a
+separate `fpa-strategy-execution` Graph. Review waits for the next cycle's
+Actuals and uses the separate `fpa-cycle-review` Graph.

package/skills/fpa-plan-cycle/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: fpa-plan-cycle
-description: Convert a business objective into a bounded FP&A and UA planning brief for one configurable business period. Use when starting a planning cycle, changing targets or constraints, or deciding what the downstream analysis and recommendation must optimize.
+description: Convert a business objective into a bounded FP&A and UA planning brief for one configurable business period. This is a single planning phase; for a multi-stage planning request, use the core Graph routing gate.
 ---
 
 # FP&A Cycle Planning
@@ -26,4 +26,7 @@ Load `$fpa-apply-core-rules` first. Produce the goal contract that every downstr
 
 ## Handoff
 
-The next skill is `$fpa-diagnose-actuals`. Pass only the frozen `planning_brief`, not an informal summary.
+When a Graph node assigns this phase, return the frozen `planning_brief` to the
+Graph for `$fpa-diagnose-actuals`; pass the artifact, not an informal summary.
+A main agent handling a multi-stage request must not continue the remaining
+workflow in the parent agent.

package/skills/fpa-refresh-dashboard/SKILL.md

@@ -26,14 +26,21 @@ only part of this tuple or fall back to a mutable current pointer.
 3. If the result is `enqueued` or `already_pending` and the current task expects
    the dashboard immediately, call one bounded `drain`, then verify with
    `fpa_dashboard_status`.
-4. If the result is `not_applicable` for a `backtest`, report that the historical
-   forecast is frozen and the operating dashboard intentionally remains
-   unchanged. Never relabel the artifact to force it into the active lineage.
+4. If the result is `not_applicable` for a `backtest`, do not treat that as a
+   failed artifact. Automatic post-Graph handoff intentionally leaves the
+   operating dashboard unchanged. If the user explicitly asked to display or
+   publish that backtest, continue through the exact backtest display path
+   below; otherwise report that the frozen historical forecast remains in the
+   ledger without changing the dashboard.
 
 ### Human-requested rebuild
 
 1. Call `fpa_dashboard_status` to inspect the current generation and diagnostics.
-2. Call `fpa_dashboard_refresh` with `preset: forecast-closed-loop-v1` and `mode: preview`.
+2. Call `fpa_dashboard_refresh` with `preset: forecast-closed-loop-v1` and
+   `mode: preview`. For a user-requested backtest display, pass the exact
+   `scope_id`, `cycle_id`, and `forecast_ref` from its immutable ledger handoff
+   together with `allow_backtest_display: true`. Never set that flag merely
+   because a Graph completed.
 3. Review the returned lineage, coverage, query receipts, warnings, widget list, and `preview_fingerprint`.
 4. If the user asked only to inspect or preview, stop without publishing.
 5. Publish only when the user explicitly asked to rebuild or publish the dashboard. Call the same tool with `mode: publish` and the exact preview fingerprint.
@@ -55,6 +62,10 @@ answer, and do not describe it as "the period has no data yet".
 - Never write `.fpa-dashboard` with generic file or shell tools.
 - Never fabricate Actuals, replace missing values with zero, or average row-level ratios.
 - Do not edit the approved forecast during projection.
+- Never relabel a backtest as `original`, `eac`, or `next_plan` to display it.
+- `allow_backtest_display` is explicit user authorization to make that exact
+  immutable backtest the displayed dashboard generation. Omit it for automatic
+  handoff and for every non-backtest forecast.
 - If inputs change between preview and publish, preview again rather than bypassing the fingerprint check.
 - Artifact commit never performs dashboard I/O. The calling main Agent explicitly
   enqueues its exact handoff. Actuals watermark changes remain monitored by the

package/skills/fpa-refresh-dashboard/references/dashboard-policy.md

@@ -8,5 +8,5 @@ The dashboard is a deterministic projection, not a second planning model.
 - Coverage: retain the Actuals cutoff and query receipts. Planned slices with no Actuals remain null; paid Actuals outside the approved allocation are reported as warnings.
 - Comparison: the prior-period window must contain the same number of covered calendar days as the current Actuals window, using the forecast timezone.
 - Execution truth: `reported` means reported, not verified. Only `verified` external evidence may be labelled verified.
-- Publication: preview first, then atomically publish content-addressed datasets and promote `manifest.json` last.
+- Publication: preview first, then atomically publish content-addressed datasets and promote `manifest.json` last. Automatic handoff never promotes a backtest; an exact committed backtest may be displayed only after explicit user authorization through `allow_backtest_display` on both preview and publish.
 - Ownership: only `fpa_dashboard_refresh` may publish this projection.

package/skills/fpa-review-cycle/SKILL.md

@@ -9,7 +9,12 @@ Load `$fpa-apply-core-rules` first. This workflow is event-driven by a new perio
 
 ## Entry gate
 
-Require the immutable `approved_cycle_forecast` and a newly diagnosed `actuals_snapshot` covering the same period and comparable scope. If data is incomplete or source grain is incompatible, narrow the review or return `blocked`.
+Require the exact immutable `approved_cycle_forecast` ref, the exact immutable
+`execution_receipt` ref returned by `fpa-strategy-execution`, and a newly
+diagnosed `actuals_snapshot` covering the same period and comparable scope.
+All refs must carry matching scope and cycle lineage. If a ref is missing or
+mismatched, data is incomplete, or source grain is incompatible, return
+`blocked`; never resolve a mutable current pointer as a substitute.
 
 ## Procedure
 

package/skills/fpa-review-strategy/SKILL.md

@@ -25,4 +25,7 @@ Load `$fpa-apply-core-rules` first. The reviewer must be independent from the re
 
 ## Handoff
 
-If the reviewer supports the proposal, send both artifacts to the human approval gate. After explicit approval, `$fpa-forecast-approved-strategy` may run.
+If the reviewer supports the proposal, return both artifacts to the Graph so it
+can create the version-bound `reviewed_strategy_handoff`. Human approval and
+`$fpa-forecast-approved-strategy` belong to the separate
+`fpa-forecast-freeze` Graph; the reviewing agent must not start them.