@viccydev/pi-fpa 0.8.1 → 0.9.1

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/forecast-quality.ts

@@ -0,0 +1,138 @@
+import {
+	sliceKey,
+	type ForecastDataQuality,
+	type ForecastDataQualityIssue,
+} from "./contracts.ts";
+
+export interface ForecastQualitySlice {
+	app_id: string;
+	store: string;
+	channel_group: string;
+	approved_spend: number;
+}
+
+export interface ForecastDimensionSnapshot {
+	app_code: Set<string>;
+	platform: Set<string>;
+	media_source: Set<string>;
+	/** Canonical app_code / platform / media_source combinations observed in ua_spend. */
+	tuples?: Set<string>;
+}
+
+export interface ForecastQualityAssessment {
+	portfolioAppId: string | null;
+	eligibleSliceKeys: Set<string>;
+	limitedSliceKeys: Set<string>;
+	dataQuality: ForecastDataQuality;
+}
+
+function sample(values: Set<string>, limit = 8): string {
+	const list = [...values].sort();
+	return list.length <= limit ? list.join(", ") : `${list.slice(0, limit).join(", ")}, … (${list.length} total)`;
+}
+
+function issueForSlice(
+	slice: ForecastQualitySlice,
+	index: number,
+	evidence: string[],
+): ForecastDataQualityIssue {
+	return {
+		issue_id: `DQ-SLICE-${String(index + 1).padStart(3, "0")}`,
+		code: "slice_key_not_in_actuals",
+		severity: "warning",
+		slice: {
+			app_id: slice.app_id,
+			store: slice.store,
+			channel_group: slice.channel_group,
+		},
+		affected_metrics: ["actuals_comparison", "revenue", "roas", "execution"],
+		disposition: "excluded_from_calculation",
+		evidence,
+		remediation:
+			"请由数据工作人员修正 ua_spend 的 app_code/platform/media_source 映射，或更新计划切片为数据集中真实存在的组合。",
+		owner_role: "data_steward",
+	};
+}
+
+/**
+ * Classify slice identity problems as data-quality limits, not governance
+ * failures. The allocation remains intact; callers use eligibleSliceKeys to
+ * decide which derived metrics may be calculated and which slices may execute.
+ */
+export function assessForecastQuality(
+	slices: ForecastQualitySlice[],
+	values: ForecastDimensionSnapshot,
+): ForecastQualityAssessment {
+	const appIds = new Set(slices.map((slice) => slice.app_id));
+	const collapsed = appIds.size === 1 ? [...appIds][0] : null;
+	const portfolioAppId = collapsed !== null && !values.app_code.has(collapsed) ? collapsed : null;
+	const eligibleSliceKeys = new Set<string>();
+	const limitedSliceKeys = new Set<string>();
+	const issues: ForecastDataQualityIssue[] = [];
+
+	for (const [index, slice] of slices.entries()) {
+		const evidence: string[] = [];
+		if (portfolioAppId === null && !values.app_code.has(slice.app_id)) {
+			evidence.push(`app_id ${JSON.stringify(slice.app_id)} is not a ua_spend.app_code value. Valid values: ${sample(values.app_code)}.`);
+		}
+		if (!values.platform.has(slice.store)) {
+			evidence.push(`store ${JSON.stringify(slice.store)} is not a ua_spend.platform value. Valid values: ${sample(values.platform)}.`);
+		}
+		if (!values.media_source.has(slice.channel_group)) {
+			evidence.push(`channel_group ${JSON.stringify(slice.channel_group)} is not a ua_spend.media_source value. Valid values: ${sample(values.media_source)}.`);
+		}
+		if (
+			evidence.length === 0
+			&& portfolioAppId === null
+			&& values.tuples
+			&& !values.tuples.has(sliceKey(slice))
+		) {
+			evidence.push(
+				`The app_code/platform/media_source combination ${slice.app_id} / ${slice.store} / ${slice.channel_group} does not occur in ua_spend.`,
+			);
+		}
+		if (
+			evidence.length === 0
+			&& portfolioAppId !== null
+			&& values.tuples
+			&& ![...values.tuples].some((tuple) => tuple.endsWith(`\u0000${slice.store}\u0000${slice.channel_group}`))
+		) {
+			evidence.push(
+				`The platform/media_source combination ${slice.store} / ${slice.channel_group} does not occur in ua_spend portfolio data.`,
+			);
+		}
+
+		const key = sliceKey(slice);
+		if (evidence.length === 0) eligibleSliceKeys.add(key);
+		else {
+			limitedSliceKeys.add(key);
+			issues.push(issueForSlice(slice, index, evidence));
+		}
+	}
+
+	const plannedSpend = slices.reduce((total, slice) => total + slice.approved_spend, 0);
+	const calculableSpend = slices
+		.filter((slice) => eligibleSliceKeys.has(sliceKey(slice)))
+		.reduce((total, slice) => total + slice.approved_spend, 0);
+	const excludedSpend = plannedSpend - calculableSpend;
+	const status = issues.length === 0
+		? "complete"
+		: calculableSpend === 0
+			? "unavailable"
+			: "partial";
+
+	return {
+		portfolioAppId,
+		eligibleSliceKeys,
+		limitedSliceKeys,
+		dataQuality: {
+			status,
+			planned_spend: plannedSpend,
+			calculable_spend: calculableSpend,
+			calculable_spend_pct: plannedSpend === 0 ? (issues.length === 0 ? 1 : 0) : calculableSpend / plannedSpend,
+			excluded_spend: excludedSpend,
+			issue_count: issues.length,
+			issues,
+		},
+	};
+}

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,
@@ -142,7 +143,8 @@ export default function fpaArtifactsExtension(pi: ExtensionAPI): void {
 		label: "Compose Approved Forecast",
 		description:
 			"Derive a complete, self-consistent approved_cycle_forecast from a compact plan file holding only the approved allocation and its per-slice ROAS assumptions. " +
-			"Computes every scenario metric, the consolidated roll-up, units, windows, and frozen_at, and checks the plan's slice keys against the dimension values ua_spend actually uses. " +
+			"Computes every scenario metric, the consolidated roll-up, units, windows, and frozen_at, and checks plan slice keys against the exact dimension combinations ua_spend actually uses. " +
+			"Data-quality mismatches are isolated into complete_with_limits with coverage and repair diagnostics; approved allocation is never dropped or renormalized. " +
 			"Returns the artifact for fpa_artifact_commit to freeze; writes nothing.",
 		promptSnippet: "Derive a complete approved forecast from a compact plan",
 		promptGuidelines: [
@@ -169,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-dashboard/coordinator.ts

@@ -717,8 +717,8 @@ async function defaultWorker(event: DashboardRefreshEvent, projectRoot: string,
 		...(event.forward_forecast_refs ? { forwardForecastRefs: event.forward_forecast_refs } : {}),
 	}, signal);
 	if (result.sliceKeyMismatch) throw new Error(`Dashboard publish refused. ${result.sliceKeyMismatch}`);
-	if (result.forecast.status !== "complete" || !result.forecast.approval_conditions_satisfied) {
-		throw new Error("Dashboard publish requires a complete approved forecast with all approval conditions satisfied.");
+	if (result.forecast.status === "blocked" || !result.forecast.approval_conditions_satisfied) {
+		throw new Error("Dashboard publish requires a completed approved forecast with all approval conditions satisfied.");
 	}
 	const generationId = dashboardBuildFingerprint(result.build, result.projector);
 	if (event.desired_generation_id && generationId !== event.desired_generation_id) {

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

@@ -218,8 +218,8 @@ export function projectCycleOperatingProjection(input: CycleOperatingProjectionI
 		throw new Error("next_forecast target period must be the exact successor of the current cycle in the same timezone.");
 	}
 	if (next && next.reporting_currency !== current.reporting_currency) throw new Error("next_forecast reporting_currency must match current_forecast.");
-	if (next && (next.status !== "complete" || !next.approval_conditions_satisfied)) {
-		throw new Error("next_forecast must be complete with approval conditions satisfied.");
+	if (next && (next.status === "blocked" || !next.approval_conditions_satisfied)) {
+		throw new Error("next_forecast must be completed with approval conditions satisfied.");
 	}
 
 	const forecastSpend = scenario(current.consolidated_forecast.spend, "current_forecast.consolidated_forecast.spend");
@@ -253,9 +253,10 @@ export function projectCycleOperatingProjection(input: CycleOperatingProjectionI
 	const nextSpend = next ? scenario(next.consolidated_forecast.spend, "next_forecast.consolidated_forecast.spend") : null;
 	const nextRevenue = next ? scenario(next.consolidated_forecast.revenue, "next_forecast.consolidated_forecast.revenue") : null;
 	const nextRoas = next ? scenario(next.consolidated_forecast.roas, "next_forecast.consolidated_forecast.roas") : null;
-	const nextHasLimits = !!next && (nextSpend?.base === null || nextRevenue?.base === null || nextRoas?.base === null
+	const nextHasLimits = !!next && (next.status === "complete_with_limits"
+		|| nextSpend?.base === null || nextRevenue?.base === null || nextRoas?.base === null
 		|| next.approved_allocation.some((item) => !item.owner));
-	if (nextHasLimits) warnings.push("The next-cycle forecast is approved with unsupported base metrics; unavailable expectations remain null.");
+	if (nextHasLimits) warnings.push("The next-cycle forecast is approved with limits; unsupported expectations remain null and documented data issues still require remediation.");
 	if (next?.approved_allocation.some((item) => !item.owner)) warnings.push("At least one next-cycle allocation has no accountable owner; strategy readiness is limited.");
 
 	return {

package/extensions/fpa-dashboard/forward-outlook.ts

@@ -26,7 +26,7 @@ export interface ForwardOutlookProjection {
 function approvedForecast(value: unknown, path: string): ApprovedCycleForecastInput {
 	const artifact = validateArtifact(value);
 	if (artifact.artifact_type !== "approved_cycle_forecast") throw new Error(`${path} must be an approved_cycle_forecast.`);
-	if (artifact.status !== "complete" || !artifact.approval_conditions_satisfied) throw new Error(`${path} must be complete and approved.`);
+	if (artifact.status === "blocked" || !artifact.approval_conditions_satisfied) throw new Error(`${path} must be completed and approved.`);
 	return artifact;
 }
 
@@ -46,6 +46,7 @@ export function projectForwardOutlook(input: {
 	const current = approvedForecast(input.current_forecast, "current_forecast");
 	if (!Array.isArray(input.forward_forecasts) || input.forward_forecasts.length > 6) throw new Error("forward_forecasts must contain at most six approved forecasts.");
 	const months: ForwardOutlookProjection["months"] = [];
+	const warnings: string[] = [];
 	let expectedStart = current.target_period.end_exclusive;
 	for (const [index, item] of input.forward_forecasts.entries()) {
 		const forecast = approvedForecast(item.forecast, `forward_forecasts[${index}].forecast`);
@@ -63,8 +64,10 @@ export function projectForwardOutlook(input: {
 			expected_revenue: values(forecast.consolidated_forecast.revenue, `forward_forecasts[${index}].revenue`),
 			expected_roas: values(forecast.consolidated_forecast.roas, `forward_forecasts[${index}].roas`),
 		});
+		if (forecast.status === "complete_with_limits") {
+			warnings.push(`${forecast.forecast_version} has data limits; unsupported expectations remain null.`);
+		}
 	}
-	const warnings: string[] = [];
 	if (months.length < 6) warnings.push(`Only ${months.length} of 6 forward monthly forecasts are approved and linked.`);
 	if (months.some((month) => month.expected_revenue.base === null || month.expected_spend.base === null || month.expected_roas.base === null)) {
 		warnings.push("At least one forward month has unsupported base metrics; its expectation remains unavailable.");

package/extensions/fpa-dashboard/index.ts

@@ -384,8 +384,8 @@ export default function fpaDashboardExtension(pi: ExtensionAPI): void {
 			}
 
 			if (sliceKeyMismatch) throw new Error(`Dashboard publish refused. ${sliceKeyMismatch}`);
-			if (forecast.status !== "complete" || !forecast.approval_conditions_satisfied) {
-				throw new Error("Dashboard publish requires a complete approved forecast with all approval conditions satisfied.");
+			if (forecast.status === "blocked" || !forecast.approval_conditions_satisfied) {
+				throw new Error("Dashboard publish requires a completed approved forecast with all approval conditions satisfied.");
 			}
 			if (!params.expected_preview_fingerprint) throw new Error("Publish requires expected_preview_fingerprint from a preceding preview.");
 			if (params.expected_preview_fingerprint !== previewFingerprint) {

package/extensions/fpa-dashboard/projector.ts

@@ -226,10 +226,11 @@ function joinSlices(
 	const forecastByKey = new Map(forecast.forecast_by_slice.map((slice) => [sliceKey(slice), slice]));
 	const actualByKey = new Map(actuals.slices.map((slice) => [sliceKey(slice), slice]));
 	const executionByKey = new Map((execution?.slices ?? []).map((slice) => [sliceKey(slice), slice]));
+	const isolatedKeys = new Set((forecast.data_quality?.issues ?? []).map((issue) => sliceKey(issue.slice)));
 	return forecast.approved_allocation.map((allocation) => {
 		const forecastSlice = forecastByKey.get(sliceKey(allocation));
 		if (!forecastSlice) throw new Error(`Forecast slice is missing for ${allocation.app_id} / ${allocation.store} / ${allocation.channel_group}.`);
-		const actual = actualByKey.get(sliceKey(allocation)) ?? null;
+		const actual = isolatedKeys.has(sliceKey(allocation)) ? null : actualByKey.get(sliceKey(allocation)) ?? null;
 		const forecastRoas = safeDiv(
 			forecastSlice.metrics.revenue?.base ?? null,
 			forecastSlice.metrics.spend?.base ?? null,
@@ -390,8 +391,64 @@ export function projectDashboard(input: ProjectionInput): DashboardBuild {
 	const deviationCount = alerts.rows.length - stopCount;
 	const window = `${formatPeriodDate(forecast.target_period.start_inclusive, forecast.target_period.timezone, locale)} → ${formatPeriodDate(forecast.target_period.end_exclusive, forecast.target_period.timezone, locale)}（end exclusive）`;
 	const asOfNote = actuals.data_as_of === ACTUALS_DATA_AS_OF_UNAVAILABLE ? "本周期暂无 Actuals" : `Actuals 截至 ${actuals.data_as_of}`;
+	const quality = forecast.data_quality;
+	const qualityWidgets: DashboardWidget[] = !quality || quality.status === "complete" ? [] : [
+		{
+			id: "forecast-data-coverage",
+			type: "stat",
+			span: "full",
+			dataset: "forecast-data-coverage.json",
+			data: {
+				label: "预测数据覆盖率",
+				value: `${(quality.calculable_spend_pct * 100).toFixed(2)}%`,
+				description: `可计算预算 ${formatCurrency(quality.calculable_spend, forecast.reporting_currency, locale)} / 计划预算 ${formatCurrency(quality.planned_spend, forecast.reporting_currency, locale)}`,
+				footnote: forecast.conclusion?.warning ?? "异常切片未参与收入与 ROAS 计算，批准预算未被删除或重分配。",
+				progress: { fraction: quality.calculable_spend_pct, label: `${quality.issue_count} 个待修复切片`, tone: "warning" },
+			},
+		},
+		{
+			id: "forecast-data-issues",
+			type: "table",
+			span: "full",
+			dataset: "forecast-data-issues.json",
+			data: {
+				label: "数据待修复项",
+				description: "问题切片保持在批准计划中，但不参与预测计算、Actuals 比较或执行。",
+				columns: [
+					{ key: "slice", label: "App / 商店 / 渠道" },
+					{ key: "problem", label: "数据问题" },
+					{ key: "remediation", label: "修复建议" },
+					{ key: "owner", label: "负责人" },
+				],
+				rows: quality.issues.map((issue) => ({
+					slice: `${issue.slice.app_id} · ${issue.slice.store} · ${issue.slice.channel_group}`,
+					problem: issue.evidence.join("\n"),
+					remediation: issue.remediation,
+					owner: issue.owner_role,
+				})),
+			},
+		},
+	];
+	const generalLimits = forecast.unsupported_metrics.filter((item) => {
+		return !(item && typeof item === "object" && !Array.isArray(item)
+			&& (item as Record<string, unknown>).reason === "slice_key_not_in_actuals");
+	});
+	const limitWidgets: DashboardWidget[] = generalLimits.length === 0 ? [] : [{
+		id: "forecast-limitations",
+		type: "table",
+		span: "full",
+		dataset: "forecast-limitations.json",
+		data: {
+			label: "预测限制提醒",
+			description: "以下上游数据或指标限制未阻断预测；不支持的值保持为空，待数据工作人员修复。",
+			columns: [{ key: "item", label: "限制与修复信息" }],
+			rows: generalLimits.map((item) => ({ item: typeof item === "string" ? item : JSON.stringify(item) })),
+		},
+	}];
 
 	const widgets: DashboardWidget[] = [
+		...qualityWidgets,
+		...limitWidgets,
 		{
 			id: "revenue-vs-forecast",
 			type: "stat",

package/extensions/fpa-dashboard/service.ts

@@ -173,7 +173,18 @@ export async function buildDashboardProjection(
 	if (actuals.query_receipts.some((receipt) => receipt.dataset === "ua_spend.slices.discovery" && receipt.row_count >= 1000)) build.warnings.push("Unplanned-slice discovery reached its 1000-row safety limit; approved slices and like-for-like totals remain complete, but additional warnings may be omitted.");
 	if (actuals.data_as_of === "unavailable") build.warnings.push("No current-period UA Actuals are available.");
 
-	const sliceKeyMismatch = detectSliceKeyMismatch(forecast.approved_allocation, actuals);
-	if (sliceKeyMismatch) build.warnings.push(sliceKeyMismatch);
+	const detectedSliceKeyMismatch = detectSliceKeyMismatch(forecast.approved_allocation, actuals);
+	const qualityIssueKeys = new Set((forecast.data_quality?.issues ?? []).map((issue) => sliceKey(issue.slice)));
+	const qualityAcknowledgesMismatch = forecast.data_quality !== undefined
+		&& forecast.data_quality.status !== "complete"
+		&& forecast.approved_allocation
+			.filter((allocation) => allocation.approved_spend > 0)
+			.every((allocation) => qualityIssueKeys.has(sliceKey(allocation)));
+	const sliceKeyMismatch = detectedSliceKeyMismatch && !qualityAcknowledgesMismatch ? detectedSliceKeyMismatch : null;
+	if (detectedSliceKeyMismatch) {
+		build.warnings.push(qualityAcknowledgesMismatch
+			? `${detectedSliceKeyMismatch} The affected slices are already isolated by forecast data quality, so dashboard publication continues with limits.`
+			: detectedSliceKeyMismatch);
+	}
 	return { build, forecast, forecastRead, executionRead, actuals, sliceKeyMismatch, ...provenance };
 }

package/extensions/fpa-dashboard/stage-projector.ts

@@ -245,6 +245,61 @@ export function projectStrategyModule(
 
 export function projectForecastModule(forecast: ApprovedCycleForecast, artifactRef: ArtifactRefV2): DashboardModuleBuild {
 	const allocationByKey = new Map(forecast.approved_allocation.map((item) => [`${item.app_id}\u0000${item.store}\u0000${item.channel_group}`, item]));
+	const quality = forecast.data_quality;
+	const summary = quality?.status !== "complete" && forecast.conclusion
+		? forecast.conclusion.metrics
+		: forecast.consolidated_forecast;
+	const qualityWidgets: DashboardModuleBuild["widgets"] = !quality || quality.status === "complete" ? [] : [{
+		id: "forecast-data-coverage",
+		type: "stat",
+		span: "full",
+		dataset: "forecast-data-coverage.json",
+		data: {
+			label: "预测数据覆盖率",
+			value: `${(quality.calculable_spend_pct * 100).toFixed(2)}%`,
+			description: `可计算预算 ${quality.calculable_spend.toFixed(2)} / 计划预算 ${quality.planned_spend.toFixed(2)}；异常切片 ${quality.issue_count} 个。`,
+			footnote: forecast.conclusion?.warning ?? "异常切片未参与收入与 ROAS 计算，批准预算未被删除或重分配。",
+			progress: { fraction: quality.calculable_spend_pct, label: `${(quality.calculable_spend_pct * 100).toFixed(2)}%`, tone: "warning" },
+		},
+	}];
+	const issueWidgets: DashboardModuleBuild["widgets"] = !quality || quality.issues.length === 0 ? [] : [{
+		id: "forecast-data-issues",
+		type: "table",
+		span: "full",
+		dataset: "forecast-data-issues.json",
+		data: {
+			label: "数据待修复项",
+			description: "这些问题不阻断预测结论，但对应切片不参与计算且不可执行。",
+			columns: [
+				{ key: "slice", label: "App / 商店 / 渠道" },
+				{ key: "problem", label: "问题" },
+				{ key: "remediation", label: "修复建议" },
+				{ key: "owner", label: "负责人" },
+			],
+			rows: quality.issues.map((issue) => ({
+				slice: `${issue.slice.app_id} · ${issue.slice.store} · ${issue.slice.channel_group}`,
+				problem: issue.evidence.join("\n"),
+				remediation: issue.remediation,
+				owner: issue.owner_role,
+			})),
+		},
+	}];
+	const generalLimits = forecast.unsupported_metrics.filter((item) => {
+		return !(item && typeof item === "object" && !Array.isArray(item)
+			&& (item as Record<string, unknown>).reason === "slice_key_not_in_actuals");
+	});
+	const limitWidgets: DashboardModuleBuild["widgets"] = generalLimits.length === 0 ? [] : [{
+		id: "forecast-limitations",
+		type: "table",
+		span: "full",
+		dataset: "forecast-limitations.json",
+		data: {
+			label: "预测限制提醒",
+			description: "以下上游数据或指标限制未阻断预测；不支持的值保持为空，待数据工作人员修复。",
+			columns: [{ key: "item", label: "限制与修复信息" }],
+			rows: generalLimits.map((item) => ({ item: typeof item === "string" ? item : JSON.stringify(item) })),
+		},
+	}];
 	return {
 		id: "next-forecast",
 		title: "下周期数据预测",
@@ -259,6 +314,7 @@ export function projectForecastModule(forecast: ApprovedCycleForecast, artifactR
 			data_as_of: forecast.data_as_of,
 		},
 		widgets: [
+			...qualityWidgets,
 			{
 				id: "forecast-summary",
 				type: "table",
@@ -267,13 +323,13 @@ export function projectForecastModule(forecast: ApprovedCycleForecast, artifactR
 				data: {
 					label: "预测摘要",
 					columns: [{ key: "metric", label: "指标" }, { key: "downside", label: "Downside", align: "right" }, { key: "base", label: "Base", align: "right" }, { key: "upside", label: "Upside", align: "right" }],
-					rows: Object.entries(forecast.consolidated_forecast).map(([metric, scenario]) => ({
+					rows: Object.entries(summary).map(([metric, scenario]) => ({
 						metric,
 						downside: cell(scenario.downside),
 						base: cell(scenario.base),
 						upside: cell(scenario.upside),
 					})),
-					description: `${forecast.target_period.start_inclusive} → ${forecast.target_period.end_exclusive}`,
+					description: `${forecast.target_period.start_inclusive} → ${forecast.target_period.end_exclusive}${quality?.status !== "complete" ? " · 部分口径" : ""}`,
 				},
 			},
 			{
@@ -299,6 +355,8 @@ export function projectForecastModule(forecast: ApprovedCycleForecast, artifactR
 					}),
 				},
 			},
+			...issueWidgets,
+			...limitWidgets,
 		],
 	};
 }

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."