@viccydev/pi-fpa 0.7.2 → 0.8.0

package/extensions/fpa-dashboard/strategy-decision.ts

@@ -0,0 +1,192 @@
+import { createHash, randomUUID } from "node:crypto";
+import { link, lstat, mkdir, open, readFile, realpath, unlink } from "node:fs/promises";
+import { join } from "node:path";
+
+import { stableJson } from "../fpa-artifacts/store.ts";
+import { resolveDashboardDir } from "./publisher.ts";
+
+const SHA256_RE = /^[a-f0-9]{64}$/;
+
+export interface StrategyDecisionRequestInput {
+	sessionId: string;
+	strategyVersion: string;
+	handoffFingerprint: string;
+	createdAt?: string;
+}
+
+export interface StrategyDecisionRequest {
+	kind: "fpa.strategy.decision.request";
+	schema_version: 1;
+	action_id: string;
+	session_id: string;
+	strategy_version: string;
+	handoff_fingerprint: string;
+	created_at: string;
+}
+
+export interface CommitStrategyDecisionInput {
+	actionId: string;
+	sessionId: string;
+	decision: "confirm" | "request_changes";
+	feedback?: string;
+	decidedAt?: string;
+}
+
+export interface CommitStrategyDecisionResult {
+	decisionFingerprint: string;
+	path: string;
+	decision: "confirm" | "request_changes";
+	strategyVersion: string;
+	handoffFingerprint: string;
+}
+
+export interface CommittedStrategyDecision {
+	kind: "fpa.strategy.decision";
+	schema_version: 1;
+	action_id: string;
+	strategy_version: string;
+	handoff_fingerprint: string;
+	decision: "confirm" | "request_changes";
+	feedback?: string;
+	decision_fingerprint: string;
+	decided_at: string;
+}
+
+function sha256(value: string): string {
+	return createHash("sha256").update(value).digest("hex");
+}
+
+function requiredString(value: string, label: string): string {
+	if (typeof value !== "string" || value.trim() === "" || value.length > 512 || /[\u0000-\u001f\u007f]/.test(value)) {
+		throw new Error(`${label} must be a non-empty bounded string without control characters.`);
+	}
+	return value;
+}
+
+async function ensureDirectory(parent: string, name: string): Promise<string> {
+	const path = join(parent, name);
+	try {
+		const stat = await lstat(path);
+		if (stat.isSymbolicLink() || !stat.isDirectory()) throw new Error(`${name} must be a regular directory, not a symlink.`);
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+		await mkdir(path, { mode: 0o700 });
+	}
+	return path;
+}
+
+async function appendOnlyWrite(directory: string, destination: string, contents: string): Promise<"created" | "exists"> {
+	const temporary = join(directory, `.${randomUUID()}.tmp`);
+	const handle = await open(temporary, "wx", 0o600);
+	try {
+		await handle.writeFile(contents, "utf8");
+		await handle.sync();
+		await handle.close();
+		try {
+			await link(temporary, destination);
+			return "created";
+		} catch (error) {
+			if ((error as NodeJS.ErrnoException).code === "EEXIST") return "exists";
+			throw error;
+		}
+	} finally {
+		await handle.close().catch(() => undefined);
+		await unlink(temporary).catch(() => undefined);
+	}
+}
+
+export async function createStrategyDecisionRequest(cwd: string, input: StrategyDecisionRequestInput): Promise<{ actionId: string; path: string }> {
+	const sessionId = requiredString(input.sessionId, "sessionId");
+	const strategyVersion = requiredString(input.strategyVersion, "strategyVersion");
+	if (!SHA256_RE.test(input.handoffFingerprint)) throw new Error("handoffFingerprint must be a SHA-256 digest.");
+	const dashboardDir = await resolveDashboardDir(cwd);
+	try {
+		const stat = await lstat(dashboardDir);
+		if (stat.isSymbolicLink() || !stat.isDirectory()) throw new Error("Dashboard directory must be a regular directory, not a symlink.");
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+		await mkdir(dashboardDir, { mode: 0o700 });
+	}
+	const actionsDir = await ensureDirectory(dashboardDir, "actions");
+	const createdAt = input.createdAt ?? new Date().toISOString();
+	const actionId = sha256(stableJson({ sessionId, strategyVersion, handoffFingerprint: input.handoffFingerprint, createdAt, nonce: randomUUID() }));
+	const request: StrategyDecisionRequest = {
+		kind: "fpa.strategy.decision.request",
+		schema_version: 1,
+		action_id: actionId,
+		session_id: sessionId,
+		strategy_version: strategyVersion,
+		handoff_fingerprint: input.handoffFingerprint,
+		created_at: createdAt,
+	};
+	const path = join(actionsDir, `${actionId}.json`);
+	await appendOnlyWrite(actionsDir, path, `${JSON.stringify(request, null, 2)}\n`);
+	return { actionId, path };
+}
+
+export async function readStrategyDecisionRequest(cwd: string, actionId: string): Promise<StrategyDecisionRequest> {
+	if (!SHA256_RE.test(actionId)) throw new Error("actionId must be a SHA-256 digest.");
+	const dashboardDir = await resolveDashboardDir(cwd);
+	const path = join(dashboardDir, "actions", `${actionId}.json`);
+	const stat = await lstat(path);
+	if (stat.isSymbolicLink() || !stat.isFile()) throw new Error("Strategy decision request must be a regular file.");
+	const request = JSON.parse(await readFile(path, "utf8")) as StrategyDecisionRequest;
+	if (request.kind !== "fpa.strategy.decision.request" || request.schema_version !== 1 || request.action_id !== actionId) throw new Error("Strategy decision request is invalid.");
+	return request;
+}
+
+export async function commitStrategyDecision(cwd: string, input: CommitStrategyDecisionInput): Promise<CommitStrategyDecisionResult> {
+	const sessionId = requiredString(input.sessionId, "sessionId");
+	const request = await readStrategyDecisionRequest(cwd, input.actionId);
+	if (request.session_id !== sessionId) throw new Error("Strategy decision must be committed from the originating session.");
+	const feedback = input.feedback?.trim();
+	if (input.decision === "request_changes" && !feedback) throw new Error("request_changes requires non-empty feedback.");
+	if (input.decision === "confirm" && feedback) throw new Error("confirm must not include feedback.");
+
+	const projectRoot = await realpath(cwd);
+	const artifactsDir = await ensureDirectory(projectRoot, "artifacts");
+	const decisionsDir = await ensureDirectory(artifactsDir, "strategy-decisions");
+	const identity = {
+		action_id: request.action_id,
+		strategy_version: request.strategy_version,
+		handoff_fingerprint: request.handoff_fingerprint,
+		decision: input.decision,
+		...(feedback ? { feedback } : {}),
+	};
+	const decisionFingerprint = sha256(stableJson(identity));
+	const decision = {
+		kind: "fpa.strategy.decision",
+		schema_version: 1,
+		...identity,
+		decision_fingerprint: decisionFingerprint,
+		decided_at: input.decidedAt ?? new Date().toISOString(),
+	};
+	const path = join(decisionsDir, `${request.action_id}.json`);
+	const contents = `${JSON.stringify(decision, null, 2)}\n`;
+	const write = await appendOnlyWrite(decisionsDir, path, contents);
+	if (write === "exists") {
+		const existing = JSON.parse(await readFile(path, "utf8")) as typeof decision;
+		if (existing.decision_fingerprint !== decisionFingerprint) throw new Error("A different strategy decision is already committed for this action.");
+		return {
+			decisionFingerprint: existing.decision_fingerprint,
+			path,
+			decision: existing.decision,
+			strategyVersion: request.strategy_version,
+			handoffFingerprint: request.handoff_fingerprint,
+		};
+	}
+	return { decisionFingerprint, path, decision: input.decision, strategyVersion: request.strategy_version, handoffFingerprint: request.handoff_fingerprint };
+}
+
+export async function readCommittedStrategyDecision(cwd: string, actionId: string, decisionFingerprint: string): Promise<CommittedStrategyDecision> {
+	if (!SHA256_RE.test(actionId) || !SHA256_RE.test(decisionFingerprint)) throw new Error("Strategy decision identity must use SHA-256 digests.");
+	const projectRoot = await realpath(cwd);
+	const path = join(projectRoot, "artifacts", "strategy-decisions", `${actionId}.json`);
+	const stat = await lstat(path);
+	if (stat.isSymbolicLink() || !stat.isFile()) throw new Error("Committed strategy decision must be a regular file.");
+	const decision = JSON.parse(await readFile(path, "utf8")) as CommittedStrategyDecision;
+	if (decision.kind !== "fpa.strategy.decision" || decision.schema_version !== 1 || decision.action_id !== actionId || decision.decision_fingerprint !== decisionFingerprint) {
+		throw new Error("Committed strategy decision identity does not match the requested decision.");
+	}
+	return decision;
+}

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

@@ -7,6 +7,8 @@ import type {
 
 const GRAPH_TOOLS = ["graph_list", "graph_run"] as const;
 const FP_AND_A_GRAPHS = [
+	"fpa-period-analysis",
+	"fpa-strategy-recommendation",
 	"fpa-strategy-planning",
 	"fpa-forecast-freeze",
 	"fpa-strategy-execution",
@@ -19,6 +21,7 @@ interface RoutingState {
 	catalogLoaded: boolean;
 	availableGraphs: Set<string>;
 	graphRunStarted: boolean;
+	graphRunCompleted: boolean;
 }
 
 function emptyState(): RoutingState {
@@ -26,6 +29,7 @@ function emptyState(): RoutingState {
 		catalogLoaded: false,
 		availableGraphs: new Set(),
 		graphRunStarted: false,
+		graphRunCompleted: false,
 	};
 }
 
@@ -115,7 +119,7 @@ export function classifyFpaGraph(prompt: string): FpaGraph | undefined {
 		return "fpa-strategy-execution";
 	}
 
-	return hasFpaIntent(normalized) ? "fpa-strategy-planning" : undefined;
+	return hasFpaIntent(normalized) ? "fpa-period-analysis" : undefined;
 }
 
 function contentText(event: ToolResultEvent): string {
@@ -149,7 +153,7 @@ function routingInstruction(graph: FpaGraph): string {
 		"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.",
+		"Graph nodes own business phase execution. After a successful Graph handoff, only the main Agent may call the matching fpa_dashboard_publish_* tool; Graphs must never publish dashboard data.",
 	].join(" ");
 }
 
@@ -180,6 +184,15 @@ export default function fpaRoutingGuardExtension(pi: ExtensionAPI): void {
 				return { block: true, reason: `Call graph_list before graph_run for ${graph}.` };
 			}
 			const requested = "graph" in event.input ? event.input.graph : undefined;
+			if (graph === "fpa-period-analysis" && state.graphRunCompleted && requested === "fpa-strategy-recommendation") {
+				if (!state.availableGraphs.has("fpa-strategy-recommendation")) {
+					return { block: true, reason: "fpa-strategy-recommendation is unavailable; do not emulate strategy work in the parent Agent." };
+				}
+				state.requiredGraph = "fpa-strategy-recommendation";
+				state.graphRunStarted = true;
+				state.graphRunCompleted = false;
+				return;
+			}
 			if (requested !== graph) {
 				return { block: true, reason: `Run the first eligible ${graph} Graph; received ${String(requested)}.` };
 			}
@@ -190,9 +203,21 @@ export default function fpaRoutingGuardExtension(pi: ExtensionAPI): void {
 				};
 			}
 			state.graphRunStarted = true;
+			state.graphRunCompleted = false;
 			return;
 		}
 
+		if (event.toolName === "fpa_dashboard_module_status") return;
+		if ((graph === "fpa-forecast-freeze" || graph === "fpa-strategy-recommendation") && !state.graphRunStarted && event.toolName === "fpa_strategy_decision_commit") return;
+		const allowedPublication = graph === "fpa-period-analysis"
+			? "fpa_dashboard_publish_review"
+			: graph === "fpa-strategy-recommendation"
+				? "fpa_dashboard_publish_strategy"
+				: graph === "fpa-forecast-freeze"
+					? "fpa_dashboard_publish_forecast"
+					: "fpa_dashboard_refresh_queue";
+		if (event.toolName === allowedPublication && state.graphRunCompleted) return;
+
 		if (!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}.` };
@@ -213,8 +238,17 @@ export default function fpaRoutingGuardExtension(pi: ExtensionAPI): void {
 	});
 
 	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));
+		if (!state.requiredGraph || event.isError) return;
+		if (event.toolName === "graph_list") {
+			state.catalogLoaded = true;
+			state.availableGraphs = new Set(catalogNames(event));
+			return;
+		}
+		if (event.toolName === "graph_run" && state.graphRunStarted) {
+			const status = event.details && typeof event.details === "object" && "status" in event.details
+				? (event.details as { status?: unknown }).status
+				: undefined;
+			state.graphRunCompleted = status !== "failed" && status !== "blocked" && status !== "cancelled";
+		}
 	});
 }

package/graphs/fpa-forecast-freeze.json

@@ -0,0 +1,11 @@
+{
+  "name": "fpa-forecast-freeze",
+  "version": "2.0.0",
+  "start": "load_confirmed_strategy",
+  "nodes": [
+    { "id": "load_confirmed_strategy", "type": "subagent", "agentName": "load_confirmed_strategy", "next": "draft_forecast", "tools": ["read"], "prompt": "核验主 Agent 已提交的策略 decision 与 reviewed handoff 精确一致；不得审批或发布仪表盘。" },
+    { "id": "draft_forecast", "type": "subagent", "agentName": "draft_forecast", "next": "compose_forecast", "skills": ["fpa-forecast-approved-strategy"], "tools": ["read", "write", "fpa_calc"], "prompt": "只按已确认策略写预测计划；不得重新优化策略或发布仪表盘。" },
+    { "id": "compose_forecast", "type": "tool", "tool": "fpa_forecast_compose", "next": "commit_forecast", "args": { "plan_path": "artifacts/forecast_plan.json" } },
+    { "id": "commit_forecast", "type": "tool", "tool": "fpa_artifact_commit", "mutates": true, "args": { "artifact": "{{data.compose_forecast.details.artifact}}", "context": { "scope_id": "{{context.scope_id}}", "cycle_id": "{{context.cycle_id}}", "forecast_role": "{{context.forecast_role}}" } } }
+  ]
+}

package/graphs/fpa-period-analysis.json

@@ -0,0 +1,10 @@
+{
+  "name": "fpa-period-analysis",
+  "version": "1.0.0",
+  "start": "plan_cycle",
+  "nodes": [
+    { "id": "plan_cycle", "type": "subagent", "agentName": "plan_cycle", "next": "diagnose_actuals", "skills": ["fpa-plan-cycle"], "tools": ["read", "write", "fpa_data_catalog"], "prompt": "规划精确周期、范围、指标与边界；不得推荐策略或调用仪表盘工具。" },
+    { "id": "diagnose_actuals", "type": "subagent", "agentName": "diagnose_actuals", "next": "analyze_drivers", "skills": ["fpa-diagnose-actuals"], "tools": ["read", "write", "fpa_data_catalog", "fpa_query"], "prompt": "诊断 Actuals 完整性并写入工件；不得调用仪表盘工具。" },
+    { "id": "analyze_drivers", "type": "subagent", "agentName": "analyze_drivers", "skills": ["fpa-analyze-drivers"], "tools": ["read", "write", "fpa_query", "fpa_calc"], "prompt": "分析上周期驱动因素并写 artifacts/driver_analysis.json；不得推荐策略或调用仪表盘工具。" }
+  ]
+}

package/graphs/fpa-strategy-recommendation.json

@@ -0,0 +1,11 @@
+{
+  "name": "fpa-strategy-recommendation",
+  "version": "1.0.0",
+  "start": "simulate_strategies",
+  "nodes": [
+    { "id": "simulate_strategies", "type": "subagent", "agentName": "simulate_strategies", "next": "recommend_strategy", "skills": ["fpa-simulate-strategies"], "tools": ["read", "write", "fpa_query", "fpa_calc"], "prompt": "根据分析工件试算候选策略；不得批准、预测或发布仪表盘。" },
+    { "id": "recommend_strategy", "type": "subagent", "agentName": "recommend_strategy", "next": "review_strategy", "skills": ["fpa-recommend-strategy"], "tools": ["read", "write"], "prompt": "形成完整策略提案；不得自我批准或发布仪表盘。" },
+    { "id": "review_strategy", "type": "subagent", "agentName": "review_strategy", "next": "prepare_handoff", "skills": ["fpa-review-strategy"], "tools": ["read", "write", "fpa_calc"], "prompt": "独立复核策略并写审核工件；不得批准或发布仪表盘。" },
+    { "id": "prepare_handoff", "type": "subagent", "agentName": "prepare_handoff", "tools": ["read", "write"], "prompt": "仅在审核通过时形成 reviewed_strategy_handoff；停止，不批准、不预测、不发布仪表盘。" }
+  ]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@viccydev/pi-fpa",
-  "version": "0.7.2",
+  "version": "0.8.0",
   "type": "module",
   "description": "Full-cycle FP&A planning, strategy, forecast, and review prompts, skills, and data tools for Pi",
   "license": "UNLICENSED",
@@ -22,6 +22,7 @@
   "files": [
     "README.md",
 	"bin",
+	"graphs",
     "prompts",
     "skills",
     "extensions"
@@ -30,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 && node tests/extension-unit.test.mjs && node --test tests/catalog-timeout.test.mjs tests/artifact-store.test.mjs tests/artifact-ledger.test.mjs tests/artifact-handoff.test.mjs tests/forecast-compose.test.mjs tests/dashboard-actuals.test.mjs tests/dashboard-projector.test.mjs tests/cycle-operating-projection.test.mjs tests/forward-outlook.test.mjs tests/forecast-accuracy.test.mjs tests/dashboard-publisher.test.mjs tests/dashboard-provenance.test.mjs tests/dashboard-coordinator.test.mjs && node tests/pi-loader-smoke.mjs && node tests/worker-loader-smoke.mjs && node tests/publish-workflow.test.mjs",
+		"test": "node tests/package-structure.test.mjs && node tests/workflow-routing.test.mjs && node --test tests/workflow-routing-guard.test.mjs tests/graph-contract.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:structure": "node tests/package-structure.test.mjs",
-		"test:unit": "node tests/extension-unit.test.mjs && node --test tests/catalog-timeout.test.mjs tests/artifact-store.test.mjs tests/artifact-ledger.test.mjs tests/artifact-handoff.test.mjs tests/forecast-compose.test.mjs tests/dashboard-actuals.test.mjs tests/dashboard-projector.test.mjs tests/cycle-operating-projection.test.mjs tests/forward-outlook.test.mjs tests/forecast-accuracy.test.mjs tests/dashboard-publisher.test.mjs tests/dashboard-provenance.test.mjs tests/dashboard-coordinator.test.mjs",
+		"test: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: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/prompts/fpa-plan-cycle.md

@@ -17,10 +17,20 @@ argument-hint: "<project-root> <cycle-id> [instructions]"
 ## 强制 Graph 路由
 
 先读取 `fpa-apply-core-rules`。如果当前 Agent 提供 `graph_list` 和
-`graph_run`，必须先调用 `graph_list`，确认 `fpa-strategy-planning` 后再以
-完整用户目标、已解析的项目根、周期边界、业务范围和数据上下文调用
-`graph_run`。在这两步之前不得直接调用任何 `fpa_*` 工具或写 Artifact，
-父 Agent 也不得自行串行模拟 Graph 内的阶段。
+`graph_run`，必须先调用 `graph_list`，确认 `fpa-period-analysis` 与
+`fpa-strategy-recommendation` 后按以下边界执行：
+
+1. 以完整用户目标、项目根、周期边界、业务范围和数据上下文运行
+   `fpa-period-analysis`。Graph 返回 `artifacts/driver_analysis.json` 后，父
+   Agent 调用 `fpa_dashboard_publish_review` 先 preview，再用精确
+   fingerprint/revision 发布 `period-review`。
+2. 再运行 `fpa-strategy-recommendation`。Graph 返回
+   `strategy_proposal.json` 与 `reviewed_strategy_handoff.json` 后，父 Agent
+   调用 `fpa_dashboard_publish_strategy` preview/publish，发布
+   `next-strategy` 并等待仪表盘决策。
+
+两个 Graph 都不得拥有或调用任何 `fpa_dashboard_*` 工具。发布是父 Agent
+在 Graph 返回后的职责；父 Agent不得自行模拟 Graph 内的业务阶段。
 
 如果匹配 Graph 不在 catalog 中或无法加载，列出缺口并保持 `blocked`；不得把
 本多阶段入口自动降级为父 Agent 本地执行。用户之后可另行显式请求一个隔离阶段。
@@ -29,9 +39,12 @@ Graph 返回业务阻塞同样不构成降级理由。所需上下文缺失时
 ## 不可跳过的停点
 
 - 策略推荐者不得批准或独立复核自己的提案。若宿主不能证明复核上下文与提案作者独立，复核阶段必须报告 `blocked`。
-- 独立复核完成后，`fpa-strategy-planning` 必须生成精确绑定提案与复核版本的 `reviewed_strategy_handoff`，然后停止。
+- 独立复核完成后，`fpa-strategy-recommendation` 必须生成精确绑定提案与复核版本的 `reviewed_strategy_handoff`，然后停止。
 - 聊天中的认可、模型自我确认或 Forecast 授权都不等于策略执行授权。
-- 人工批准与正式预测属于后续独立的 `fpa-forecast-freeze` Graph；父 Agent 不得在本入口中继续执行。
+- 仪表盘响应回到原主会话后，先由主 Agent 调用
+  `fpa_strategy_decision_commit`。只有 `confirm` 成功才可在后续运行
+  `fpa-forecast-freeze`；Graph 返回 immutable forecast ref 后仍由主 Agent
+  调用 `fpa_dashboard_publish_forecast`。本入口发布策略后停止等待用户。
 - 本入口不得加载 Forecast 或策略执行 Skill，不得声称已经冻结 Forecast 或修改外部投放状态。
 
 ## 全局计算与证据底线

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

@@ -20,15 +20,18 @@ writing artifacts. It applies only when the current agent exposes both
 
    | 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` |
+   | New or changed objective requiring planning, Actuals diagnosis, and driver analysis | `fpa-period-analysis` |
+   | Completed `driver_analysis` requiring scenarios, recommendation, and independent review | `fpa-strategy-recommendation` |
+   | Ready `reviewed_strategy_handoff` plus an exact confirmed `strategy_decision` and a request for 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.
+   nodes or pre-run their `fpa_*` calls. After a successful Graph handoff, the
+   main Agent must publish only that stage's module with the matching
+   `fpa_dashboard_publish_*` tool. Graph nodes must never receive dashboard
+   publication tools.
 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.
 

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

@@ -2,20 +2,32 @@
 
 ## 1. Workflow and artifacts
 
-Strategy-planning workflow (`fpa-strategy-planning`):
+Period-analysis workflow (`fpa-period-analysis`):
 
-`planning_brief -> actuals_snapshot + data_issue_report -> driver_analysis -> strategy_scenarios -> strategy_proposal -> strategy_review -> reviewed_strategy_handoff`
+`planning_brief -> actuals_snapshot + data_issue_report -> driver_analysis`
 
-This Graph stops after an independently reviewed strategy handoff. It does not
+The calling main Agent publishes `period-review`, then starts the separate
+strategy-recommendation workflow (`fpa-strategy-recommendation`):
+
+`driver_analysis -> strategy_scenarios -> strategy_proposal -> strategy_review -> reviewed_strategy_handoff`
+
+Each Graph stops at its named handoff. Neither Graph may publish dashboard
+content. The strategy Graph does not
 approve the strategy, create an official forecast, or execute the allocation.
 
+The calling main Agent publishes the exact ready handoff through
+`fpa_dashboard_publish_strategy`, waits for the dashboard response in the
+originating main session, and commits it with `fpa_strategy_decision_commit`.
+Dashboard publishing and decision commit tools are forbidden from every Graph
+tool allowlist.
+
 Forecast-freeze workflow (`fpa-forecast-freeze`), entered only with that exact
-ready handoff:
+ready handoff plus the exact confirmed strategy-decision fingerprint:
 
-`reviewed_strategy_handoff -> human strategy_approval -> forecast_plan -> approved_cycle_forecast`
+`reviewed_strategy_handoff + strategy_decision -> forecast_plan -> approved_cycle_forecast`
 
-The forecast Graph owns approval recording, deterministic composition, and
-artifact freezing. A rejected approval returns to a new
+The main Agent owns approval recording; the forecast Graph owns deterministic
+composition and artifact freezing. A rejected approval returns to a new
 `fpa-strategy-planning` version rather than modifying the reviewed proposal in
 place.
 
@@ -28,7 +40,8 @@ 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
+The main agent routes to only the currently eligible Graph and is solely
+responsible for publishing the returned stage module. It must not emulate
 multiple phases itself or automatically cross a human approval or immutable
 artifact handoff.
 

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

@@ -17,7 +17,9 @@ Require all of the following:
   `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 exact immutable `strategy_decision` fingerprint returned by
+  `fpa_strategy_decision_commit` in the originating main session, confirming
+  the same version and handoff fingerprint;
 - 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.
@@ -26,7 +28,9 @@ from it, return `blocked`; never reconstruct or substitute the handoff.
 
 ## Procedure
 
-1. Verify approval and artifact lineage.
+1. Verify the committed strategy decision and artifact lineage. The Graph must
+   consume that decision as input; it must not display, request, or record a
+   second approval itself.
 2. Lock the approved allocation, accountable owner for each slice when known, and all approval conditions.
 3. Recalculate future-period operating outcomes from that allocation using the declared model.
 4. Provide downside, base, and upside values for each supported KPI.
@@ -74,12 +78,11 @@ Work the planning stage explicitly placed outside this cycle's scope is neither
 a limit nor a defect: it does not belong in `unsupported_metrics` and does not
 downgrade `status`.
 
-This matters downstream: `fpa_dashboard_refresh` with `mode: publish` accepts
-only `complete`, so `complete_with_limits` blocks the dashboard. Do not
-misreport a narrowed scope as a limit and stall the publish, and do not hide a
-real defect to get through the gate. When something that was promised cannot be
-delivered, report `complete_with_limits` honestly and say that the scope
-declaration upstream needs correcting.
+The calling main Agent publishes the committed result with
+`fpa_dashboard_publish_forecast`; the Graph itself never calls a dashboard
+tool. `complete_with_limits` remains publishable when its limitations are
+explicit, while `blocked` is not. Do not hide a real defect to get through the
+gate.
 
 ## Boundaries
 

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

@@ -1,13 +1,45 @@
 ---
 name: fpa-refresh-dashboard
-description: Preview, validate, and atomically publish the forecast closed-loop FP&A dashboard from a committed approved forecast, optional execution receipt, and current read-only Actuals. Use when the user asks to inspect, rebuild, or publish the tenant dashboard.
+description: Preview, validate, and publish independent FP&A dashboard modules for period review, reviewed strategy approval, confirmed forecast, and execution evidence. Use after each Graph stage returns or when the user asks to inspect, rebuild, or publish the tenant dashboard.
 ---
 
-# FP&A Dashboard Refresh
+# FP&A Dashboard Module Publication
 
 Load `$fpa-apply-core-rules` first. Follow [dashboard-policy.md](references/dashboard-policy.md).
 
-## Entry gate
+## Ownership boundary
+
+Dashboard publication belongs to the calling main Agent. A Graph may analyze,
+review, forecast, and return exact artifact paths or refs, but no Graph node or
+Graph tool allowlist may contain any `fpa_dashboard_*` tool. The main Agent must
+wait for the Graph result, then preview and publish the corresponding module.
+
+Do not publish the whole dashboard after every stage. The root manifest is only
+an atomic catalog of independently versioned modules; publishing one module must
+preserve every other module revision.
+
+## Module sequence
+
+1. After the analysis Graph returns `driver_analysis`, preview then publish
+   `period-review` with `fpa_dashboard_publish_review`.
+2. After the strategy Graph returns the exact `strategy_proposal` and
+   `reviewed_strategy_handoff`, preview then publish `next-strategy` with
+   `fpa_dashboard_publish_strategy`. Publication binds its decision action to
+   the current main session; never copy or expose a session id in dashboard data.
+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`.
+5. On `request_changes`, pass the verbatim feedback back into strategy planning,
+   publish the replacement `next-strategy` module, and wait for a new decision.
+
+Every preview returns both `preview_fingerprint` and `dashboard_revision`.
+Publish with both exact values. A `null` dashboard revision is an explicit CAS
+value for a dashboard that did not exist at preview time.
+
+## Legacy closed-loop entry gate
 
 Require a committed `approved_cycle_forecast` for the target project. Treat a committed `execution_receipt` as optional execution evidence; never describe manual reported execution as independently verified.
 
@@ -17,7 +49,10 @@ only part of this tuple or fall back to a mutable current pointer.
 
 ## Procedure
 
-### Post-Graph handoff
+### Legacy post-Graph handoff
+
+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`.
 2. Call `fpa_dashboard_refresh_queue` with `action: enqueue_artifact` and that
@@ -60,6 +95,11 @@ answer, and do not describe it as "the period has no data yet".
 ## Boundaries
 
 - Never write `.fpa-dashboard` with generic file or shell tools.
+- Never let pi-graph or a Graph node call dashboard publication tools.
+- Never accept caller-authored widgets; module tools project widgets from exact
+  business artifacts and immutable forecast refs.
+- Never start forecast generation before the strategy decision is durably
+  committed in the bound original main session.
 - Never fabricate Actuals, replace missing values with zero, or average row-level ratios.
 - Do not edit the approved forecast during projection.
 - Never relabel a backtest as `original`, `eac`, or `next_plan` to display it.