@viccydev/pi-fpa 0.9.0 → 0.9.1

package/README.md

@@ -80,7 +80,7 @@ Extension 内置的关键防护：
 
 ## Artifact 与看板 Extension
 
-`fpa-artifacts` 提供 `fpa_artifact_commit`，对 `approved_cycle_forecast` 和 `execution_receipt` 做严格字段校验、对账、稳定指纹和原子落盘。只有工具返回成功后的 JSON 才是冻结产物，Markdown 不是正式数据源。
+`fpa-artifacts` 提供 `fpa_forecast_finalize`，把紧凑 Forecast plan 一次性合成、校验、按目标周期推导生命周期角色并冻结；模型无需在 Graph handoff 与 ledger 枚举之间转译 `forecast_role`。通用的 `fpa_artifact_commit` 仍负责 `approved_cycle_forecast` 和 `execution_receipt` 的严格字段校验、对账、稳定指纹和原子落盘。只有工具返回成功后的 JSON 才是冻结产物，Markdown 不是正式数据源。
 
 `fpa-dashboard` 提供分模块发布工具和兼容的闭环刷新工具：
 
@@ -159,12 +159,12 @@ pi list
 团队分发建议使用固定 Git tag：
 
 ```bash
-pi install git:github.com/linyqh/pi-fpa@v0.9.0
+pi install git:github.com/linyqh/pi-fpa@v0.9.1
 ```
 
 ## 发布到 npm
 
-发布动作由 GitHub Release 触发。Release 标签必须严格使用 `v<package.json version>`，例如版本 `0.9.0` 对应 `v0.9.0`。工作流会检出该标签，执行 `npm ci`、`npm test` 和包内容预检，全部通过后发布公开包 `@viccydev/pi-fpa`。普通 Release 发布到 `latest`，Prerelease 发布到 `next`。
+发布动作由 GitHub Release 触发。Release 标签必须严格使用 `v<package.json version>`，例如版本 `0.9.1` 对应 `v0.9.1`。工作流会检出该标签，执行 `npm ci`、`npm test` 和包内容预检，全部通过后发布公开包 `@viccydev/pi-fpa`。普通 Release 发布到 `latest`，Prerelease 发布到 `next`。
 
 发布认证使用 npm Trusted Publishing / OIDC，不使用长期 npm Token。npm 包后台的 Trusted Publisher 配置为：
 

package/extensions/fpa-artifacts/compose.ts

@@ -34,11 +34,10 @@ import {
 // derived. So the plan carries just those, and this module computes the rest —
 // which makes the identities true by construction rather than true if checked.
 //
-// Deliberately returns the artifact instead of writing it. A node that writes
-// is a mutating node, and the engine bars mutating nodes from automatic retry
-// and from failure routes that lead back to themselves. Keeping composition
-// read-only is what lets a bad plan be repaired and recomposed automatically,
-// while the irreversible freeze stays in its own node.
+// Deliberately returns the artifact instead of writing it, so isolated callers
+// can inspect diagnostics without mutation. The forecast-freeze Graph uses the
+// finalizer as its one mutation seam; malformed plans fail once with the full
+// actionable limitation report instead of entering a repair loop.
 // ============================================================================
 
 /** Distinct dimension values a plan's slice keys must be drawn from. */
@@ -328,19 +327,45 @@ export async function composeApprovedForecast(plan: unknown, options: ComposeOpt
 		);
 	}
 	if (status === "complete_with_limits") {
+		const limitationErrors: string[] = [];
+		const capture = (check: () => void): void => {
+			try {
+				check();
+			} catch (error) {
+				limitationErrors.push(error instanceof Error ? error.message : String(error));
+			}
+		};
 		for (const [index, value] of unsupported.entries()) {
-			const item = record(value, `plan.unsupported_metrics[${index}]`);
-			text(item.metric, `plan.unsupported_metrics[${index}].metric`);
-			text(item.reason, `plan.unsupported_metrics[${index}].reason`);
+			const path = `plan.unsupported_metrics[${index}]`;
+			let item: Record<string, unknown>;
+			try {
+				item = record(value, path);
+			} catch (error) {
+				limitationErrors.push(error instanceof Error ? error.message : String(error));
+				continue;
+			}
+			capture(() => { text(item.metric, `${path}.metric`); });
+			capture(() => { text(item.reason, `${path}.reason`); });
 			if (!Array.isArray(item.affected_scope) || item.affected_scope.length === 0) {
-				throw new Error(`plan.unsupported_metrics[${index}].affected_scope must be a non-empty array.`);
+				limitationErrors.push(`${path}.affected_scope must be a non-empty array.`);
+			} else {
+				for (const [scopeIndex, scope] of item.affected_scope.entries()) {
+					capture(() => { text(scope, `${path}.affected_scope[${scopeIndex}]`); });
+				}
 			}
-			for (const [scopeIndex, scope] of item.affected_scope.entries()) text(scope, `plan.unsupported_metrics[${index}].affected_scope[${scopeIndex}]`);
-			const evidence = Array.isArray(item.evidence) ? item.evidence : [item.evidence];
-			if (evidence.length === 0) throw new Error(`plan.unsupported_metrics[${index}].evidence must not be empty.`);
-			for (const [evidenceIndex, entry] of evidence.entries()) text(entry, `plan.unsupported_metrics[${index}].evidence[${evidenceIndex}]`);
-			text(item.remediation, `plan.unsupported_metrics[${index}].remediation`);
-			text(item.owner_role, `plan.unsupported_metrics[${index}].owner_role`);
+			const evidence = item.evidence === undefined ? [] : Array.isArray(item.evidence) ? item.evidence : [item.evidence];
+			if (evidence.length === 0) {
+				limitationErrors.push(`${path}.evidence must not be empty.`);
+			} else {
+				for (const [evidenceIndex, entry] of evidence.entries()) {
+					capture(() => { text(entry, `${path}.evidence[${evidenceIndex}]`); });
+				}
+			}
+			capture(() => { text(item.remediation, `${path}.remediation`); });
+			capture(() => { text(item.owner_role, `${path}.owner_role`); });
+		}
+		if (limitationErrors.length > 0) {
+			throw new Error(`Forecast plan limitations are invalid:\n- ${limitationErrors.join("\n- ")}`);
 		}
 	}
 

package/extensions/fpa-artifacts/finalize.ts

@@ -0,0 +1,99 @@
+import { composeApprovedForecast, type ComposeOptions, type ComposeResult } from "./compose.ts";
+import {
+	commitArtifact,
+	type ArtifactCommitContext,
+	type CommitArtifactResult,
+	type ForecastRole,
+} from "./store.ts";
+
+export interface ForecastFinalizeContext {
+	scope_id: string;
+	cycle_id: string;
+}
+
+export interface ForecastFinalizeResult extends ComposeResult {
+	forecastRole: Extract<ForecastRole, "eac" | "next_plan" | "backtest">;
+	committed: CommitArtifactResult;
+}
+
+function withoutCallerFrozenAt(plan: unknown): unknown {
+	if (plan === null || typeof plan !== "object" || Array.isArray(plan)) return plan;
+	const { frozen_at: _ignored, ...decisionPlan } = plan as Record<string, unknown>;
+	return decisionPlan;
+}
+
+/**
+ * The forecast-freeze workflow owns next-cycle planning, in-period reforecast,
+ * and historical reruns. Its ledger role follows from when the immutable body
+ * is frozen relative to its own target period; callers do not translate a
+ * business label into storage vocabulary.
+ */
+export function deriveFreezeForecastRole(
+	targetPeriod: { start_inclusive: string; end_exclusive: string },
+	frozenAt: string,
+): ForecastFinalizeResult["forecastRole"] {
+	const start = Date.parse(targetPeriod.start_inclusive);
+	const end = Date.parse(targetPeriod.end_exclusive);
+	const frozen = Date.parse(frozenAt);
+	if (!Number.isFinite(start) || !Number.isFinite(end) || !Number.isFinite(frozen) || end <= start) {
+		throw new Error("Cannot derive forecast role from an invalid target period or frozen_at timestamp.");
+	}
+	if (frozen >= end) return "backtest";
+	if (frozen >= start) return "eac";
+	return "next_plan";
+}
+
+export async function finalizeApprovedForecast(
+	projectRoot: string,
+	plan: unknown,
+	context: ForecastFinalizeContext,
+	options: ComposeOptions = {},
+): Promise<ForecastFinalizeResult> {
+	const composed = await composeApprovedForecast(withoutCallerFrozenAt(plan), options);
+	if (composed.artifact.status === "blocked") {
+		throw new Error("A blocked forecast plan cannot be finalized or committed.");
+	}
+	const forecastRole = deriveFreezeForecastRole(
+		composed.artifact.target_period,
+		composed.artifact.frozen_at,
+	);
+	const commitContext: ArtifactCommitContext = {
+		scope_id: context.scope_id,
+		cycle_id: context.cycle_id,
+		forecast_role: forecastRole,
+	};
+	const committed = await commitArtifact(projectRoot, composed.artifact, { context: commitContext });
+	return { ...composed, forecastRole, committed };
+}
+
+/** Keep the Graph result actionable without returning the full canonical artifact. */
+export function forecastFinalizeDetails(result: ForecastFinalizeResult): Record<string, unknown> {
+	const artifactRef = result.committed.artifactRef;
+	const dashboardHandoff = result.forecastRole === "backtest"
+		? {
+			status: "not_applicable",
+			reason: "backtest forecasts are immutable evidence and are not enqueued for an operating dashboard",
+		}
+		: artifactRef
+			? {
+				status: "deferred",
+				tool: "fpa_dashboard_refresh_queue",
+				action: "enqueue_artifact",
+				artifact_ref: artifactRef,
+			}
+			: undefined;
+	return {
+		status: "committed",
+		artifact_type: result.committed.artifactType,
+		forecast_role: result.forecastRole,
+		immutable_fingerprint: result.committed.fingerprint,
+		path: result.committed.path,
+		ledger_status: result.committed.ledgerStatus,
+		diagnostics: result.diagnostics as unknown as Record<string, unknown>,
+		data_quality: result.artifact.data_quality,
+		unsupported_metrics: result.artifact.unsupported_metrics,
+		conclusion: result.artifact.conclusion,
+		...(artifactRef ? { artifact_ref: artifactRef } : {}),
+		...(dashboardHandoff ? { dashboard_handoff: dashboardHandoff } : {}),
+	};
+}

package/extensions/fpa-artifacts/index.ts

@@ -4,6 +4,7 @@ import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 
 import { composeApprovedForecast } from "./compose.ts";
+import { finalizeApprovedForecast, forecastFinalizeDetails } from "./finalize.ts";
 import {
 	commitArtifact,
 	commitArtifactFromPath,
@@ -170,4 +171,37 @@ export default function fpaArtifactsExtension(pi: ExtensionAPI): void {
 			});
 		},
 	});
+
+	pi.registerTool({
+		name: "fpa_forecast_finalize",
+		label: "Finalize Approved Forecast",
+		description:
+			"Compose, validate, assign the lifecycle role, and atomically commit an approved forecast from its compact plan. " +
+			"The role is derived from frozen_at relative to the target period: future is next_plan, in-period is eac, and ended periods are backtest. " +
+			"Use this as the single mutation seam for fpa-forecast-freeze; callers do not pass or translate forecast_role.",
+		promptSnippet: "Finalize and freeze a compact approved forecast plan",
+		promptGuidelines: [
+			"Pass only the compact plan path and immutable scope/cycle identity; forecast_role is derived deterministically.",
+			"A historical target is committed as backtest evidence and never promoted as an operating forecast.",
+		],
+		parameters: Type.Object({
+			plan_path: Type.String({
+				minLength: 1,
+				description: "Project-relative path to the compact forecast plan JSON file.",
+			}),
+			scope_id: Type.String({ minLength: 1, maxLength: 256 }),
+			cycle_id: Type.String({ minLength: 1, maxLength: 256 }),
+		}, { additionalProperties: false }),
+		executionMode: "sequential",
+		async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+			const plan = await readProjectJsonFile(ctx.cwd, params.plan_path, "plan_path");
+			const finalized = await finalizeApprovedForecast(
+				ctx.cwd,
+				plan,
+				{ scope_id: params.scope_id, cycle_id: params.cycle_id },
+				{ signal },
+			);
+			return toolResult(forecastFinalizeDetails(finalized));
+		},
+	});
 }

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

@@ -168,9 +168,11 @@ function graphContextError(event: ToolCallEvent, graph: FpaGraph): string | unde
 		return "graph_run requires a context object whose values are strings.";
 	}
 	const values = context as Record<string, unknown>;
-	const required = graph === "fpa-strategy-planning" || graph === "fpa-forecast-freeze"
+	const required = graph === "fpa-strategy-planning"
 		? ["scope_id", "cycle_id", "forecast_role"]
-		: [];
+		: graph === "fpa-forecast-freeze"
+			? ["scope_id", "cycle_id"]
+			: [];
 	const missing = required.filter((key) => !(key in values) || (typeof values[key] === "string" && values[key].trim().length === 0));
 	if (missing.length > 0) return `graph_run requires non-empty string context keys: ${missing.join(", ")}.`;
 	const nonStrings = Object.entries(values)
@@ -188,9 +190,12 @@ function routingInstruction(graph: FpaGraph, resumeCompletedGraph = false): stri
 		"Call graph_list first, then graph_run with that exact graph. All graph_run context values must be strings; never pass arrays, objects, numbers, booleans, or null.",
 		"Graph nodes own business phase execution. After a successful Graph handoff, only the main Agent may call the matching fpa_dashboard_publish_* tool; Graphs must never publish dashboard data.",
 	];
-	if (graph === "fpa-strategy-planning" || graph === "fpa-forecast-freeze") {
+	if (graph === "fpa-strategy-planning") {
 		instructions.push("Provide the immutable non-empty string context keys scope_id, cycle_id, and forecast_role. Put structured planning details in goal, not context.");
 	}
+	if (graph === "fpa-forecast-freeze") {
+		instructions.push("Provide only the immutable non-empty string context keys scope_id and cycle_id. The ledger forecast_role is derived from the frozen forecast target period; do not translate or pass a business role label.");
+	}
 	if (graph === "fpa-strategy-planning") {
 		instructions.push(resumeCompletedGraph
 			? "A completed combined Graph handoff was restored from this session. Continue modular publication from its persisted artifacts; do not rerun the Graph unless those artifacts are unavailable or the user changed the planning requirements. Publish period-review before next-strategy."

package/graphs/fpa-forecast-freeze.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@viccydev/pi-fpa",
-  "version": "0.9.0",
+  "version": "0.9.1",
   "type": "module",
   "description": "Full-cycle FP&A planning, strategy, forecast, and review prompts, skills, and data tools for Pi",
   "license": "UNLICENSED",
@@ -31,9 +31,9 @@
 		"fpa-dashboard-worker": "./bin/fpa-dashboard-worker.mjs"
 	},
   "scripts": {
-		"test": "node tests/package-structure.test.mjs && node tests/workflow-routing.test.mjs && node --test tests/workflow-routing-guard.test.mjs tests/graph-contract.test.mjs tests/graph-installer.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/dashboard-module-publisher.test.mjs tests/dashboard-stage-projector.test.mjs tests/strategy-decision.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 tests/graph-contract.test.mjs tests/graph-installer.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/forecast-finalize.test.mjs tests/dashboard-actuals.test.mjs tests/dashboard-projector.test.mjs tests/dashboard-module-publisher.test.mjs tests/dashboard-stage-projector.test.mjs tests/strategy-decision.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/dashboard-module-publisher.test.mjs tests/dashboard-stage-projector.test.mjs tests/strategy-decision.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/forecast-finalize.test.mjs tests/dashboard-actuals.test.mjs tests/dashboard-projector.test.mjs tests/dashboard-module-publisher.test.mjs tests/dashboard-stage-projector.test.mjs tests/strategy-decision.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"

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

@@ -26,8 +26,10 @@ writing artifacts. It applies only when the current agent exposes both
    | Exact Forecast and Execution refs plus newly arrived comparable Actuals | `fpa-cycle-review` |
 
 3. Call `graph_run` with the user's complete goal. Every `context` value must
-   be a string; provide exact `scope_id`, `cycle_id`, and `forecast_role`, and
-   keep structured planning details in `goal`. The parent agent must not
+   be a string. Provide exact `scope_id` and `cycle_id`; planning additionally
+   requires its business `forecast_role`, while forecast freeze derives the
+   ledger role from the target period and freeze time. Keep structured planning
+   details in `goal`. The parent agent must not
    reproduce Graph nodes or pre-run their `fpa_*` calls. After the combined
    planning Graph succeeds, the main Agent publishes `period-review` and then
    `next-strategy` with their matching `fpa_dashboard_publish_*` tools. Graph

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

@@ -24,8 +24,11 @@ ready handoff plus the exact confirmed strategy-decision fingerprint:
 
 `reviewed_strategy_handoff + strategy_decision -> forecast_plan -> approved_cycle_forecast`
 
-The main Agent owns approval recording; the forecast Graph owns deterministic
-composition and artifact freezing. A rejected approval reruns
+The main Agent owns approval recording; the forecast Graph writes the approved
+plan and delegates deterministic composition, lifecycle-role derivation, and
+artifact freezing to `fpa_forecast_finalize`. A business role recorded in an
+older handoff is lineage metadata, not a storage role that the model must
+translate. A rejected approval reruns
 `fpa-strategy-planning` with the exact feedback and produces a new version
 rather than modifying the reviewed proposal in place.
 

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

@@ -36,34 +36,28 @@ from it, return `blocked`; never reconstruct or substitute the handoff.
 4. Provide downside, base, and upside values for each supported KPI.
 5. Reconcile allocation totals, formulas, and cross-metric identities.
 6. Write the forecast plan to `artifacts/forecast_plan.json` using [artifact-contract.md](references/artifact-contract.md).
-7. Derive the artifact with `fpa_forecast_compose`, then freeze it with
-   `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` 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
+7. Call `fpa_forecast_finalize` with the plan path and the exact `scope_id` and
+   `cycle_id`. Do not choose or pass `forecast_role`: the tool derives
+   `next_plan` before period start, `eac` during the period, and `backtest`
+   after period end, then composes and commits the artifact atomically. A
+   historical rerun is immutable evidence, not an operating plan, and must not
    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.
+   user explicitly requests a backtest dashboard publication.
 
 ## Write the decision, not the arithmetic
 
 The only judgement in a forecast is the allocation and each slice's ROAS
 assumption. Revenue, the consolidated roll-up, units, windows, and `frozen_at`
-all follow from those, and `fpa_forecast_compose` derives them — which is what
+all follow from those, and `fpa_forecast_finalize` derives them — which is what
 makes the identities the commit checks true by construction rather than
 dependent on transcribing several hundred numbers without a slip.
 
 So do not hand-compute revenue, totals, or ratios, and do not emit the full
 artifact as one tool argument: that is the shape that gets cut off at the model
-output limit and leaves a turn that reads finished but committed nothing. If a
-later node in this graph composes and commits for you, stop after writing the
-plan and say so; never claim a fingerprint you were not handed.
+output limit and leaves a turn that reads finished but committed nothing. Stop
+after writing the plan; the finalizer owns composition and commit. Never claim
+a fingerprint you were not handed.
 
 ## Status and the publish gate
 
@@ -86,7 +80,7 @@ gate.
 
 Upstream identity or coverage defects are non-blocking data limits. Preserve
 the full approved allocation, leave affected revenue and ROAS values `NULL`,
-and let `fpa_forecast_compose` emit `data_quality`, a coverage-labelled partial
+and let `fpa_forecast_finalize` emit `data_quality`, a coverage-labelled partial
 `conclusion`, and actionable repair items. Never delete a bad slice, turn it
 into zero spend, or renormalize the remaining allocation. The affected slice
 remains ineligible for Actuals comparison and execution until its mapping is
@@ -105,7 +99,7 @@ governance failures.
 
 ## Completion
 
-The forecast-freeze workflow ends only after `fpa_artifact_commit` returns
+The forecast-freeze workflow ends only after `fpa_forecast_finalize` 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.

package/skills/fpa-forecast-approved-strategy/references/artifact-contract.md

@@ -73,9 +73,10 @@ Do not include `immutable_fingerprint` in the tool input; a draft that carries o
 Almost none of the artifact above is a decision. The decision is the allocation
 and the ROAS assumption behind each slice; revenue, the ROAS write-back, the
 consolidated roll-up, every unit and window string, and `frozen_at` all follow
-from those by arithmetic. Write the plan and let `fpa_forecast_compose` derive
-the rest — it makes the identities the commit checks true by construction
-instead of true if you typed them correctly.
+from those by arithmetic. Write the plan and let `fpa_forecast_finalize` derive
+the rest, choose the lifecycle role from time, and commit it — it makes the
+identities the commit checks true by construction instead of true if you typed
+them correctly.
 
 ```yaml
 # artifacts/forecast_plan.json
@@ -111,10 +112,12 @@ Then:
 
 ```
 write  artifacts/forecast_plan.json
-fpa_forecast_compose  { "plan_path": "artifacts/forecast_plan.json" }
-fpa_artifact_commit   { "artifact": <the artifact compose returned> }
+fpa_forecast_finalize  { "plan_path": "artifacts/forecast_plan.json", "scope_id": "<exact scope>", "cycle_id": "<exact cycle>" }
 ```
 
+The finalizer derives `next_plan` before the target period, `eac` during it,
+and `backtest` after it. The model does not pass or translate `forecast_role`.
+
 Rules the plan has to respect, because compose enforces them:
 
 - **Spend is a decision, not a prediction.** It is identical in all three scenarios, so a slice carries one `approved_spend`. Only revenue moves, through `roas`.

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

@@ -32,9 +32,12 @@ preserve every other module revision.
 3. Stop and wait for the dashboard action. The Web host sends a canonical
    decision message back to the bound original session. In that session call
    `fpa_strategy_decision_commit` with the exact `action_id`.
-4. On `confirm`, run `fpa-forecast-freeze`; after it returns an exact committed
-   forecast ref, preview then publish `next-forecast` with
-   `fpa_dashboard_publish_forecast`.
+4. On `confirm`, run `fpa-forecast-freeze`. For an operating Forecast, preview
+   then publish `next-forecast` with `fpa_dashboard_publish_forecast`. If the
+   finalizer returns `forecast_role: backtest` and a `not_applicable` dashboard
+   handoff, stop after reporting its immutable ref; do not attempt operating
+   publication unless the user explicitly requested the separate backtest
+   display path.
 5. On `request_changes`, pass the verbatim feedback back into strategy planning,
    publish the replacement `next-strategy` module, and wait for a new decision.
 
@@ -57,19 +60,21 @@ only part of this tuple or fall back to a mutable current pointer.
 This path remains only for legacy execution-evidence refreshes. It must not be
 used to replace review, strategy, or forecast modules.
 
-1. Take the exact `artifact_ref` from `fpa_artifact_commit.dashboard_handoff`.
+1. For an operating forecast, take the exact `artifact_ref` from a deferred
+   `fpa_forecast_finalize.dashboard_handoff` (or the compatible
+   `fpa_artifact_commit.dashboard_handoff` path). A backtest handoff is
+   `not_applicable` and must not be queued automatically.
 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`, 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.
+4. A compatible legacy `fpa_artifact_commit` handoff may still return
+   `not_applicable` for a `backtest`; do not treat that as a failed artifact or
+   retry it. If the user explicitly asked to display that backtest, continue
+   through the exact backtest display path below. Otherwise report that it
+   remains in the ledger without changing the operating dashboard.
 
 ### Human-requested rebuild