@viccydev/pi-fpa 0.6.3 → 0.7.1

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 数据集市：
@@ -60,7 +81,7 @@ Extension 内置的关键防护：
 | --- | --- |
 | `fpa_dashboard_status` | 只读检查当前 manifest、构建回执和各数据集是否可读 |
 | `fpa_dashboard_refresh` | 从冻结预测、可选执行回执和实时 Actuals 生成固定的闭环看板；先 preview，再携带相同指纹原子 publish |
-| `fpa_dashboard_refresh_queue` | 检查或处理持久刷新队列；Forecast/Execution commit 自动入队，Actuals watermark 按 SLA 轮询并幂等发布 |
+| `fpa_dashboard_refresh_queue` | 检查或处理持久刷新队列；主 Agent 用 `enqueue_artifact` 显式交接 Forecast/Execution，Actuals watermark 按 SLA 轮询并幂等发布 |
 
 持续刷新由 package 自带的独立 worker 驱动，Web 保持严格只读：
 
@@ -127,12 +148,12 @@ pi list
 团队分发建议使用固定 Git tag：
 
 ```bash
-pi install git:github.com/linyqh/pi-fpa@v0.6.3
+pi install git:github.com/linyqh/pi-fpa@v0.7.1
 ```
 
 ## 发布到 npm
 
-发布动作由 GitHub Release 触发。Release 标签必须严格使用 `v<package.json version>`，例如版本 `0.6.3` 对应 `v0.6.3`。工作流会检出该标签，执行 `npm ci`、`npm test` 和包内容预检，全部通过后发布公开包 `@viccydev/pi-fpa`。普通 Release 发布到 `latest`，Prerelease 发布到 `next`。
+发布动作由 GitHub Release 触发。Release 标签必须严格使用 `v<package.json version>`，例如版本 `0.7.1` 对应 `v0.7.1`。工作流会检出该标签，执行 `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.6.3
 
 ```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-artifacts/index.ts

@@ -2,7 +2,6 @@ import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 
 import { composeApprovedForecast } from "./compose.ts";
-import { enqueueDashboardRefresh } from "../fpa-dashboard/coordinator.ts";
 import {
 	commitArtifact,
 	commitArtifactFromPath,
@@ -53,7 +52,7 @@ export default function fpaArtifactsExtension(pi: ExtensionAPI): void {
 				context: Type.Optional(Type.Object({
 					scope_id: Type.String({ minLength: 1, maxLength: 256 }),
 					cycle_id: Type.String({ minLength: 1, maxLength: 256 }),
-					forecast_role: Type.Optional(Type.Union([Type.Literal("original"), Type.Literal("eac"), Type.Literal("next_plan")])),
+					forecast_role: Type.Optional(Type.Union([Type.Literal("original"), Type.Literal("eac"), Type.Literal("next_plan"), Type.Literal("backtest")])),
 					upstream_refs: Type.Optional(Type.Array(artifactRefSchema, { maxItems: 16 })),
 					promote_legacy_pointer: Type.Optional(Type.Boolean()),
 				}, { additionalProperties: false })),
@@ -79,40 +78,21 @@ export default function fpaArtifactsExtension(pi: ExtensionAPI): void {
 			const committed = hasPath
 				? await commitArtifactFromPath(ctx.cwd, params.artifact_path as string, commitOptions)
 				: await commitArtifact(ctx.cwd, params.artifact, commitOptions);
-			let dashboardRefresh;
-			let dashboardRefreshError: string | undefined;
-			if (committed.artifactRef && params.context) {
-				try {
-					const forecastRef = committed.artifactType === "approved_cycle_forecast"
-						? committed.artifactRef
-						: params.context.upstream_refs?.find((ref) => ref.artifact_type === "approved_cycle_forecast") as ArtifactRefV2 | undefined;
-					if (!forecastRef) throw new Error("Assigned execution commit has no forecast ref for dashboard refresh.");
-					dashboardRefresh = await enqueueDashboardRefresh(ctx.cwd, {
-						preset: "forecast-closed-loop-v1",
-						locale: "zh-CN",
-						scope_id: params.context.scope_id,
-						cycle_id: params.context.cycle_id,
-						forecast_ref: forecastRef,
-						...(committed.artifactType === "approved_cycle_forecast" && params.context.forecast_role ? { forecast_role: params.context.forecast_role } : {}),
-						...(committed.artifactType === "execution_receipt" ? { execution_ref: committed.artifactRef } : {}),
-						reason: committed.artifactType === "approved_cycle_forecast" ? "forecast_committed" : "execution_committed",
-					});
-				} catch (error) {
-					// The immutable ledger commit is already durable. Report the
-					// secondary delivery failure explicitly instead of pretending the
-					// commit itself failed and encouraging an unsafe duplicate retry.
-					dashboardRefreshError = error instanceof Error ? error.message : String(error);
-				}
-			}
 			return toolResult({
-				status: dashboardRefreshError ? "committed_refresh_enqueue_failed" : "committed",
+				status: "committed",
 				artifact_type: committed.artifactType,
 				immutable_fingerprint: committed.fingerprint,
 				path: committed.path,
 				ledger_status: committed.ledgerStatus,
 				...(committed.artifactRef ? { artifact_ref: committed.artifactRef } : {}),
-				...(dashboardRefresh ? { dashboard_refresh: dashboardRefresh } : {}),
-				...(dashboardRefreshError ? { dashboard_refresh_error: dashboardRefreshError } : {}),
+				...(committed.artifactRef ? {
+					dashboard_handoff: {
+						status: "deferred",
+						tool: "fpa_dashboard_refresh_queue",
+						action: "enqueue_artifact",
+						artifact_ref: committed.artifactRef,
+					},
+				} : {}),
 			});
 		},
 	});

package/extensions/fpa-artifacts/store.ts

@@ -35,18 +35,25 @@ export interface ArtifactRefV2 {
 	body_fingerprint: string;
 }
 
+export const FORECAST_ROLES = ["original", "eac", "next_plan", "backtest"] as const;
+export type ForecastRole = typeof FORECAST_ROLES[number];
+
+export function isForecastRole(value: unknown): value is ForecastRole {
+	return typeof value === "string" && (FORECAST_ROLES as readonly string[]).includes(value);
+}
+
 export interface ArtifactCommitContext {
 	scope_id: string;
 	cycle_id: string;
 	upstream_refs?: ArtifactRefV2[];
-	forecast_role?: "original" | "eac" | "next_plan";
+	forecast_role?: ForecastRole;
 }
 
 export interface ArtifactLedgerContext {
 	scope_id: string;
 	cycle_id: string;
 	upstream_refs: ArtifactRefV2[];
-	forecast_role?: "original" | "eac" | "next_plan";
+	forecast_role?: ForecastRole;
 }
 
 export interface CommitArtifactOptions {
@@ -61,7 +68,7 @@ interface ArtifactLedgerEntry extends ArtifactRefV2 {
 	created_at: string;
 	available_at: string;
 	upstream_refs: ArtifactRefV2[];
-	forecast_role?: "original" | "eac" | "next_plan";
+	forecast_role?: ForecastRole;
 	assignment_status: "assigned";
 }
 
@@ -227,14 +234,14 @@ function validateCommitContext(value: ArtifactCommitContext): ArtifactLedgerCont
 	if (!Array.isArray(upstream) || upstream.length > 16) throw new Error("context.upstream_refs must be an array of at most 16 artifact refs.");
 	const upstreamRefs = upstream.map((ref, index) => validateArtifactRef(ref, `context.upstream_refs[${index}]`));
 	if (new Set(upstreamRefs.map((ref) => ref.entry_id)).size !== upstreamRefs.length) throw new Error("context.upstream_refs must not contain duplicates.");
-	if (source.forecast_role !== undefined && source.forecast_role !== "original" && source.forecast_role !== "eac" && source.forecast_role !== "next_plan") {
-		throw new Error("context.forecast_role must be original, eac, or next_plan.");
+	if (source.forecast_role !== undefined && !isForecastRole(source.forecast_role)) {
+		throw new Error("context.forecast_role must be original, eac, next_plan, or backtest.");
 	}
 	return {
 		scope_id: contextId(source.scope_id, "context.scope_id"),
 		cycle_id: contextId(source.cycle_id, "context.cycle_id"),
 		upstream_refs: upstreamRefs,
-		...(source.forecast_role ? { forecast_role: source.forecast_role as ArtifactLedgerContext["forecast_role"] } : {}),
+		...(isForecastRole(source.forecast_role) ? { forecast_role: source.forecast_role } : {}),
 	};
 }
 
@@ -326,7 +333,7 @@ function validateLedgerEntry(value: Record<string, unknown>, path: string): { re
 	}
 	if (!Array.isArray(value.upstream_refs) || value.upstream_refs.length > 16) throw new Error(`${path}.upstream_refs must be an array of at most 16 artifact refs.`);
 	const upstreamRefs = value.upstream_refs.map((item, index) => validateArtifactRef(item, `${path}.upstream_refs[${index}]`));
-	if (value.forecast_role !== undefined && value.forecast_role !== "original" && value.forecast_role !== "eac" && value.forecast_role !== "next_plan") {
+	if (value.forecast_role !== undefined && !isForecastRole(value.forecast_role)) {
 		throw new Error(`${path}.forecast_role is unsupported.`);
 	}
 	if (ref.artifact_type === "execution_receipt" && value.forecast_role !== undefined) throw new Error(`${path}.forecast_role is allowed only for forecasts.`);
@@ -334,7 +341,7 @@ function validateLedgerEntry(value: Record<string, unknown>, path: string): { re
 		scope_id: ref.scope_id,
 		cycle_id: ref.cycle_id,
 		upstream_refs: upstreamRefs,
-		...(value.forecast_role ? { forecast_role: value.forecast_role as ArtifactLedgerContext["forecast_role"] } : {}),
+		...(isForecastRole(value.forecast_role) ? { forecast_role: value.forecast_role } : {}),
 	};
 	const expectedEntryId = entryIdentity(context, ref.artifact_type, ref.body_fingerprint);
 	if (expectedEntryId !== ref.entry_id) throw new Error(`${path} identity does not match its upstream refs.`);
@@ -418,9 +425,22 @@ async function commitLedgerEntry(
 export async function commitArtifact(projectRoot: string, input: unknown, options: CommitArtifactOptions = {}): Promise<CommitArtifactResult> {
 	const artifact = validateArtifact(input);
 	const context = options.context ? validateCommitContext(options.context) : null;
-	if (artifact.artifact_type === "approved_cycle_forecast" && context?.forecast_role === "original"
-		&& Date.parse(artifact.frozen_at) > Date.parse(artifact.target_period.start_inclusive)) {
-		throw new Error("An original forecast must be frozen no later than the target period start; use forecast_role=eac for an in-period reforecast.");
+	if (artifact.artifact_type === "approved_cycle_forecast" && context?.forecast_role) {
+		const frozenAt = Date.parse(artifact.frozen_at);
+		const periodStart = Date.parse(artifact.target_period.start_inclusive);
+		const periodEnd = Date.parse(artifact.target_period.end_exclusive);
+		if (context.forecast_role === "original" && frozenAt > periodStart) {
+			throw new Error("An original forecast must be frozen no later than the target period start; use forecast_role=eac for an in-period reforecast.");
+		}
+		if (context.forecast_role === "eac" && (frozenAt < periodStart || frozenAt >= periodEnd)) {
+			throw new Error("An EAC forecast must be frozen during its target period.");
+		}
+		if (context.forecast_role === "next_plan" && frozenAt > periodStart) {
+			throw new Error("A next-plan forecast must be frozen no later than its target period start.");
+		}
+		if (context.forecast_role === "backtest" && frozenAt < periodEnd) {
+			throw new Error("A backtest forecast must be frozen after its target period has ended.");
+		}
 	}
 	if (artifact.artifact_type === "execution_receipt") {
 		if (context?.forecast_role !== undefined) throw new Error("context.forecast_role is allowed only for approved forecasts.");
@@ -442,9 +462,13 @@ export async function commitArtifact(projectRoot: string, input: unknown, option
 	}
 	const fingerprint = artifactFingerprint(artifact);
 	const committed = { ...artifact, immutable_fingerprint: fingerprint } as CanonicalArtifact;
+	const forwardOnlyRole = context?.forecast_role === "next_plan" || context?.forecast_role === "backtest";
+	const promoteLegacyPointer = options.promoteLegacyPointer ?? !forwardOnlyRole;
+	if (forwardOnlyRole && promoteLegacyPointer) {
+		throw new Error(`A ${context.forecast_role} forecast cannot replace the legacy operating pointer.`);
+	}
 	const ledgerCommit = context ? await commitLedgerEntry(projectRoot, committed, context) : undefined;
 	const artifactRef = ledgerCommit?.ref;
-	const promoteLegacyPointer = options.promoteLegacyPointer ?? true;
 	const destination = promoteLegacyPointer
 		? await writeLegacyPointer(projectRoot, committed)
 		: ledgerCommit?.bodyPath ?? join(await ensureArtifactDirectory(projectRoot), `${artifact.artifact_type}.json`);

package/extensions/fpa-dashboard/coordinator.ts

@@ -2,7 +2,13 @@ import { createHash, randomUUID } from "node:crypto";
 import { lstat, mkdir, open, readFile, readdir, realpath, rename, stat, unlink } from "node:fs/promises";
 import { basename, dirname, isAbsolute, join, relative, resolve } from "node:path";
 
-import { readArtifactByRef, stableJson, validateArtifactRef, type ArtifactRefV2 } from "../fpa-artifacts/store.ts";
+import {
+	readArtifactByRef,
+	stableJson,
+	validateArtifactRef,
+	type ArtifactRefV2,
+	type ForecastRole,
+} from "../fpa-artifacts/store.ts";
 import { dashboardBuildFingerprint, publishDashboard, resolveDashboardDir } from "./publisher.ts";
 import { buildDashboardProjection } from "./service.ts";
 
@@ -19,7 +25,7 @@ export interface DashboardRefreshRequest {
 	scope_id: string;
 	cycle_id: string;
 	forecast_ref: ArtifactRefV2;
-	forecast_role?: "original" | "eac" | "next_plan";
+	forecast_role?: OperatingForecastRole;
 	execution_ref?: ArtifactRefV2;
 	next_forecast_ref?: ArtifactRefV2;
 	forward_forecast_refs?: ArtifactRefV2[];
@@ -52,6 +58,80 @@ export interface EnqueueDashboardRefreshResult {
 	queue_dir: string;
 }
 
+export interface DashboardRefreshNotApplicableResult {
+	status: "not_applicable";
+	reason: "backtest_forecasts_do_not_update_the_operating_dashboard";
+	artifact_ref: ArtifactRefV2;
+}
+
+type OperatingForecastRole = Exclude<ForecastRole, "backtest">;
+
+function isOperatingForecastRole(value: unknown): value is OperatingForecastRole {
+	return value === "original" || value === "eac" || value === "next_plan";
+}
+
+function backtestNotApplicable(artifactRef: ArtifactRefV2): DashboardRefreshNotApplicableResult {
+	return {
+		status: "not_applicable",
+		reason: "backtest_forecasts_do_not_update_the_operating_dashboard",
+		artifact_ref: artifactRef,
+	};
+}
+
+/**
+ * Resolve one exact committed artifact into durable dashboard work.
+ *
+ * This is the package-owned handoff seam used by the main Agent after a Graph
+ * finishes. Callers provide only the immutable artifact ref; role and upstream
+ * lineage are read from the ledger rather than guessed or copied from prompts.
+ */
+export async function enqueueDashboardRefreshForArtifact(
+	cwd: string,
+	value: unknown,
+	locale: "zh-CN" | "en-US" = "zh-CN",
+): Promise<EnqueueDashboardRefreshResult | DashboardRefreshNotApplicableResult> {
+	const artifactRef = validateArtifactRef(value);
+	const committed = await readArtifactByRef(cwd, artifactRef);
+	const context = committed.ledgerContext;
+	if (!context) throw new Error("Dashboard handoff requires an assigned ledger artifact.");
+
+	if (committed.artifact.artifact_type === "approved_cycle_forecast") {
+		if (!context.forecast_role) throw new Error("Dashboard handoff requires the committed forecast_role from ledger context.");
+		if (context.forecast_role === "backtest") {
+			return backtestNotApplicable(artifactRef);
+		}
+		return enqueueDashboardRefresh(cwd, {
+			preset: "forecast-closed-loop-v1",
+			locale,
+			scope_id: artifactRef.scope_id,
+			cycle_id: artifactRef.cycle_id,
+			forecast_ref: artifactRef,
+			forecast_role: context.forecast_role,
+			reason: "forecast_committed",
+		});
+	}
+
+	if (context.upstream_refs.length !== 1 || context.upstream_refs[0].artifact_type !== "approved_cycle_forecast") {
+		throw new Error("Execution dashboard handoff requires exactly one approved forecast upstream ref.");
+	}
+	const forecastRef = context.upstream_refs[0];
+	const forecast = await readArtifactByRef(cwd, forecastRef);
+	if (!forecast.ledgerContext?.forecast_role) throw new Error("Execution dashboard handoff requires the upstream forecast_role from ledger context.");
+	if (forecast.ledgerContext.forecast_role === "backtest") {
+		return backtestNotApplicable(artifactRef);
+	}
+	return enqueueDashboardRefresh(cwd, {
+		preset: "forecast-closed-loop-v1",
+		locale,
+		scope_id: artifactRef.scope_id,
+		cycle_id: artifactRef.cycle_id,
+		forecast_ref: forecastRef,
+		forecast_role: forecast.ledgerContext.forecast_role,
+		execution_ref: artifactRef,
+		reason: "execution_committed",
+	});
+}
+
 export interface DashboardRefreshQueueStatus {
 	queue_dir: string;
 	pending: number;
@@ -122,7 +202,7 @@ interface DashboardRefreshSubscription {
 	scope_id: string;
 	cycle_id: string;
 	forecast_ref: ArtifactRefV2;
-	forecast_role?: "original" | "eac" | "next_plan";
+	forecast_role?: OperatingForecastRole;
 	execution_ref?: ArtifactRefV2;
 	next_forecast_ref?: ArtifactRefV2;
 	forward_forecast_refs?: ArtifactRefV2[];
@@ -160,7 +240,7 @@ function validateRequest(value: DashboardRefreshRequest): DashboardRefreshReques
 	const scopeId = boundedId(source.scope_id, "refresh request.scope_id");
 	const cycleId = boundedId(source.cycle_id, "refresh request.cycle_id");
 	const forecastRef = validateArtifactRef(source.forecast_ref, "refresh request.forecast_ref");
-	if (source.forecast_role !== undefined && source.forecast_role !== "original" && source.forecast_role !== "eac" && source.forecast_role !== "next_plan") {
+	if (source.forecast_role !== undefined && !isOperatingForecastRole(source.forecast_role)) {
 		throw new Error("refresh request.forecast_role is unsupported.");
 	}
 	if (forecastRef.artifact_type !== "approved_cycle_forecast" || forecastRef.scope_id !== scopeId || forecastRef.cycle_id !== cycleId) {
@@ -193,7 +273,7 @@ function validateRequest(value: DashboardRefreshRequest): DashboardRefreshReques
 		scope_id: scopeId,
 		cycle_id: cycleId,
 		forecast_ref: forecastRef,
-		...(source.forecast_role ? { forecast_role: source.forecast_role as DashboardRefreshRequest["forecast_role"] } : {}),
+		...(isOperatingForecastRole(source.forecast_role) ? { forecast_role: source.forecast_role } : {}),
 		...(executionRef ? { execution_ref: executionRef } : {}),
 		...(nextForecastRef ? { next_forecast_ref: nextForecastRef } : {}),
 		...(forwardForecastRefs.length > 0 ? { forward_forecast_refs: forwardForecastRefs } : {}),
@@ -494,13 +574,45 @@ async function enqueueEventOnly(
 
 async function sortForwardForecastRefs(projectRoot: string, refs: ArtifactRefV2[]): Promise<ArtifactRefV2[]> {
 	const dated = await Promise.all(refs.map(async (ref) => {
-		const read = await readArtifactByRef(projectRoot, ref);
+		let read;
+		try {
+			read = await readArtifactByRef(projectRoot, ref);
+		} catch (error) {
+			throw new Error(
+				`Forward forecast lineage is incomplete at ${ref.entry_id}: ${error instanceof Error ? error.message : String(error)}`,
+				{ cause: error },
+			);
+		}
 		if (read.artifact.artifact_type !== "approved_cycle_forecast") throw new Error("A forward forecast ref resolved to the wrong artifact type.");
 		return { ref, start: Date.parse(read.artifact.target_period.start_inclusive) };
 	}));
 	return dated.sort((left, right) => left.start - right.start).map((item) => item.ref).slice(0, 6);
 }
 
+function canonicalTimezone(timezone: string): string {
+	return new Intl.DateTimeFormat("en-US", { timeZone: timezone }).resolvedOptions().timeZone;
+}
+
+async function assertExactNextPlanSuccessor(
+	projectRoot: string,
+	active: DashboardRefreshSubscription,
+	nextRef: ArtifactRefV2,
+): Promise<void> {
+	const [currentRead, nextRead] = await Promise.all([
+		readArtifactByRef(projectRoot, active.forecast_ref),
+		readArtifactByRef(projectRoot, nextRef),
+	]);
+	if (currentRead.artifact.artifact_type !== "approved_cycle_forecast" || nextRead.artifact.artifact_type !== "approved_cycle_forecast") {
+		throw new Error("Next-plan dashboard handoff must resolve two approved forecasts.");
+	}
+	const current = currentRead.artifact;
+	const next = nextRead.artifact;
+	if (Date.parse(next.target_period.start_inclusive) !== Date.parse(current.target_period.end_exclusive)
+		|| canonicalTimezone(next.target_period.timezone) !== canonicalTimezone(current.target_period.timezone)) {
+		throw new Error("Next-plan forecast must be the exact successor of the active cycle in the same timezone.");
+	}
+}
+
 export async function enqueueDashboardRefresh(cwd: string, value: DashboardRefreshRequest): Promise<EnqueueDashboardRefreshResult> {
 	const request = validateRequest(value);
 	const projectRoot = await realpath(cwd);
@@ -516,13 +628,16 @@ export async function enqueueDashboardRefresh(cwd: string, value: DashboardRefre
 	)) {
 		throw new Error("Next-plan dashboard refresh requires an active current-cycle subscription in the same project and scope.");
 	}
-	const subscription = await persistSubscription(directories, projectName, request, now);
+	if (request.forecast_role === "next_plan" && active) {
+		await assertExactNextPlanSuccessor(projectRoot, active, request.forecast_ref);
+	}
 	if (request.forecast_role === "next_plan") {
 		if (active) {
 			const unsortedForwardRefs = [...(active.forward_forecast_refs ?? (active.next_forecast_ref ? [active.next_forecast_ref] : [])), request.forecast_ref]
 				.filter((ref, index, refs) => refs.findIndex((candidate) => candidate.entry_id === ref.entry_id) === index)
 				.slice(0, 6);
 			const forwardRefs = await sortForwardForecastRefs(projectRoot, unsortedForwardRefs);
+			await persistSubscription(directories, projectName, request, now);
 			const linked = { ...active, next_forecast_ref: forwardRefs[0], forward_forecast_refs: forwardRefs, updated_at: now };
 			await atomicReplace(join(directories.subscriptions, `${active.subscription_id}.json`), `${JSON.stringify(linked, null, 2)}\n`);
 			return enqueueEventOnly(directories, projectName, validateRequest({
@@ -538,7 +653,9 @@ export async function enqueueDashboardRefresh(cwd: string, value: DashboardRefre
 				reason: "forecast_committed",
 			}), now);
 		}
-	} else if (request.reason === "forecast_committed" || request.reason === "execution_committed") {
+	}
+	const subscription = await persistSubscription(directories, projectName, request, now);
+	if (request.reason === "forecast_committed" || request.reason === "execution_committed") {
 		await atomicReplace(join(directories.root, "active-subscription.json"), `${JSON.stringify({
 			kind: "fpa.dashboard.active-subscription",
 			schema_version: 1,

package/extensions/fpa-dashboard/cycle-operating-projection.ts

@@ -5,6 +5,7 @@ import {
 	type ExecutionReceiptInput,
 	type ScenarioMetric,
 } from "../fpa-artifacts/contracts.ts";
+import type { ForecastRole } from "../fpa-artifacts/store.ts";
 import {
 	ACTUALS_DATA_AS_OF_UNAVAILABLE,
 	validateActualsSnapshot,
@@ -16,11 +17,11 @@ export interface CycleOperatingProjectionInput {
 	scope_id: string;
 	cycle_id: string;
 	current_forecast: unknown;
-	current_forecast_role?: "original" | "eac" | "next_plan";
+	current_forecast_role?: ForecastRole;
 	actuals: unknown;
 	execution?: unknown;
 	next_forecast?: unknown;
-	next_forecast_role?: "original" | "eac" | "next_plan";
+	next_forecast_role?: ForecastRole;
 }
 
 interface ScenarioValues {

package/extensions/fpa-dashboard/index.ts

@@ -2,10 +2,11 @@ import { StringEnum } from "@earendil-works/pi-ai";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 
-import type { ArtifactRefV2 } from "../fpa-artifacts/store.ts";
+import { readArtifactByRef, type ArtifactRefV2 } from "../fpa-artifacts/store.ts";
 import { dashboardBuildFingerprint, publishDashboard } from "./publisher.ts";
 import {
 	enqueueDashboardRefresh,
+	enqueueDashboardRefreshForArtifact,
 	inspectDashboardRefreshQueue,
 	processDashboardRefreshQueue,
 } from "./coordinator.ts";
@@ -34,7 +35,7 @@ export default function fpaDashboardExtension(pi: ExtensionAPI): void {
 		promptSnippet: "Inspect the current FP&A dashboard generation and diagnostics",
 		parameters: Type.Object({
 			expected_lineage: Type.Optional(Type.Object({
-				forecast_role: Type.Union([Type.Literal("original"), Type.Literal("eac"), Type.Literal("next_plan")]),
+				forecast_role: Type.Union([Type.Literal("original"), Type.Literal("eac"), Type.Literal("next_plan"), Type.Literal("backtest")]),
 				forecast_ref: Type.String({ pattern: "^[a-f0-9]{64}$" }),
 			}, { additionalProperties: false })),
 			require_lineage_match: Type.Optional(Type.Boolean()),
@@ -93,7 +94,16 @@ export default function fpaDashboardExtension(pi: ExtensionAPI): void {
 				...(params.next_forecast_ref ? { nextForecastRef: params.next_forecast_ref as ArtifactRefV2 } : {}),
 				...(params.forward_forecast_refs ? { forwardForecastRefs: params.forward_forecast_refs as ArtifactRefV2[] } : {}),
 			} : 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 { 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.");
+			}
 			const previewFingerprint = dashboardBuildFingerprint(build, projector);
 			const summary = {
 				preset: params.preset,
@@ -144,11 +154,12 @@ export default function fpaDashboardExtension(pi: ExtensionAPI): void {
 	pi.registerTool({
 		name: "fpa_dashboard_refresh_queue",
 		label: "FP&A Dashboard Refresh Queue",
-		description: "Inspect or drain the durable dashboard refresh queue, or enqueue an Actuals-watermark refresh against exact immutable artifact refs.",
+		description: "Inspect or drain the durable dashboard refresh queue, enqueue an exact committed artifact after Graph handoff, or enqueue an Actuals-watermark refresh.",
 		promptSnippet: "Inspect or process durable FP&A dashboard refresh work",
 		parameters: Type.Object({
-			action: StringEnum(["status", "drain", "enqueue_actuals"] as const),
+			action: StringEnum(["status", "drain", "enqueue_artifact", "enqueue_actuals"] as const),
 			locale: Type.Optional(StringEnum(["zh-CN", "en-US"] as const)),
+			artifact_ref: Type.Optional(artifactRefSchema),
 			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),
@@ -162,6 +173,14 @@ export default function fpaDashboardExtension(pi: ExtensionAPI): void {
 		async execute(_toolCallId, params, signal, _onUpdate, ctx) {
 			if (params.action === "status") return toolResult(await inspectDashboardRefreshQueue(ctx.cwd) as unknown as Record<string, unknown>);
 			if (params.action === "drain") return toolResult(await processDashboardRefreshQueue(ctx.cwd, { limit: params.limit, signal }) as unknown as Record<string, unknown>);
+			if (params.action === "enqueue_artifact") {
+				if (!params.artifact_ref) throw new Error("enqueue_artifact requires artifact_ref from fpa_artifact_commit.");
+				return toolResult(await enqueueDashboardRefreshForArtifact(
+					ctx.cwd,
+					params.artifact_ref,
+					params.locale ?? "zh-CN",
+				) as unknown as Record<string, unknown>);
+			}
 			if (!params.scope_id || !params.cycle_id || !params.forecast_ref || !params.actuals_watermark) {
 				throw new Error("enqueue_actuals requires scope_id, cycle_id, forecast_ref, and actuals_watermark.");
 			}

package/extensions/fpa-dashboard/projector.ts

@@ -7,6 +7,7 @@ import {
 	type ForecastAllocation,
 	type ForecastSlice,
 } from "../fpa-artifacts/contracts.ts";
+import type { ForecastRole } from "../fpa-artifacts/store.ts";
 import { validateActualsSnapshot, ACTUALS_DATA_AS_OF_UNAVAILABLE, type DashboardActualsSnapshot, type DashboardActualSlice } from "./source.ts";
 import type { CycleOperatingProjection } from "./cycle-operating-projection.ts";
 import type { ForwardOutlookProjection } from "./forward-outlook.ts";
@@ -67,7 +68,7 @@ export interface DashboardBuild {
 		forecast_ref?: string;
 		next_forecast_ref?: string;
 		execution_ref?: string;
-		forecast_role?: "original" | "eac" | "next_plan";
+		forecast_role?: ForecastRole;
 		forecast_version: string;
 		forecast_fingerprint?: string;
 		next_forecast_fingerprint?: string;

package/extensions/fpa-dashboard/publisher.ts

@@ -177,6 +177,9 @@ 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.");
+	}
 	const projector = validateProjectorProvenance(options.projector);
 	const runtime = validateProjectorRuntime(options.runtime);
 	const dashboardDir = await resolveDashboardDir(options.cwd);

package/extensions/fpa-dashboard/status.ts

@@ -9,7 +9,7 @@ import {
 	type DashboardProjectorProvenance,
 	type DashboardProjectorRuntime,
 } from "./provenance.ts";
-import { stableJson } from "../fpa-artifacts/store.ts";
+import { isForecastRole, stableJson, type ForecastRole } from "../fpa-artifacts/store.ts";
 import { DASHBOARD_WIDGET_TYPES, validateDatasetForWidget, type DashboardWidgetType } from "./schema.ts";
 import { validateActualsSnapshot } from "./source.ts";
 
@@ -31,7 +31,7 @@ export interface DashboardStatus {
 }
 
 export interface DashboardLineageExpectation {
-	forecast_role: "original" | "eac" | "next_plan";
+	forecast_role: ForecastRole;
 	forecast_ref: string;
 }
 
@@ -47,7 +47,7 @@ export interface DashboardReceiptSummary {
 		cycle_id?: string;
 		forecast_version: string;
 		forecast_ref?: string;
-		forecast_role?: "original" | "eac" | "next_plan";
+		forecast_role?: ForecastRole;
 		next_forecast_ref?: string;
 		forward_forecast_refs: string[];
 		execution_ref?: string;
@@ -80,7 +80,7 @@ function buildReceiptSummary(receipt: Record<string, unknown>): DashboardReceipt
 	const dataAsOf = optionalBoundedString(source?.data_as_of, 256);
 	if (!source || !forecastVersion || !dataAsOf) return undefined;
 	const role = source.forecast_role;
-	const forecastRole = role === "original" || role === "eac" || role === "next_plan" ? role : undefined;
+	const forecastRole = isForecastRole(role) ? role : undefined;
 	const forwardForecastRefs = Array.isArray(source.forward_forecast_refs)
 		? source.forward_forecast_refs.filter((value): value is string => typeof value === "string" && /^[a-f0-9]{64}$/.test(value)).slice(0, 6)
 		: [];

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.6.3",
+  "version": "0.7.1",
   "type": "module",
   "description": "Full-cycle FP&A planning, strategy, forecast, and review prompts, skills, and data tools for Pi",
   "license": "UNLICENSED",
@@ -30,9 +30,9 @@
 		"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/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/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: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",
     "test:live": "node tests/live-smoke.mjs",
     "pack:check": "npm pack --dry-run"
@@ -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
 
@@ -30,8 +36,14 @@ If approval evidence is absent, ambiguous, expired, conditional but unmet, or re
    `fpa_artifact_commit` and an assigned context containing the explicit
    `scope_id`, `cycle_id`, and `forecast_role`. Use `original` only when the
    forecast is frozen no later than period start; use `eac` for an in-period
-   reforecast and `next_plan` when it is the approved direct successor of the
-   active cycle.
+   reforecast and `next_plan` only when it is frozen no later than its target
+   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
+   `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.
 
 ## Write the decision, not the arithmetic
 
@@ -76,4 +88,12 @@ declaration upstream needs correcting.
 
 ## Completion
 
-The planning workflow ends only after `fpa_artifact_commit` returns `status: committed` and an `immutable_fingerprint`. 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

@@ -17,6 +17,21 @@ only part of this tuple or fall back to a mutable current pointer.
 
 ## Procedure
 
+### Post-Graph handoff
+
+1. Take the exact `artifact_ref` from `fpa_artifact_commit.dashboard_handoff`.
+2. Call `fpa_dashboard_refresh_queue` with `action: enqueue_artifact` and that
+   ref. Do not restate scope, cycle, role, or upstream refs; the package resolves
+   them from the immutable ledger.
+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.
+
+### 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`.
 3. Review the returned lineage, coverage, query receipts, warnings, widget list, and `preview_fingerprint`.
@@ -41,8 +56,9 @@ answer, and do not describe it as "the period has no data yet".
 - Never fabricate Actuals, replace missing values with zero, or average row-level ratios.
 - Do not edit the approved forecast during projection.
 - If inputs change between preview and publish, preview again rather than bypassing the fingerprint check.
-- This skill performs one bounded human-requested refresh. Assigned artifact
-  commits and Actuals watermark changes are monitored separately by the durable
-  package coordinator running in the package-owned `fpa-dashboard-worker`
-  process (never in the read-only Web host); inspect or drain that queue with
-  `fpa_dashboard_refresh_queue` rather than recreating its writes manually.
+- Artifact commit never performs dashboard I/O. The calling main Agent explicitly
+  enqueues its exact handoff. Actuals watermark changes remain monitored by the
+  durable package coordinator running in the package-owned
+  `fpa-dashboard-worker` process (never in the read-only Web host); inspect or
+  drain that queue with `fpa_dashboard_refresh_queue` rather than recreating its
+  writes manually.

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.