@viccydev/pi-fpa 0.8.0 → 0.9.0

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

@@ -1,3 +1,5 @@
+import { createHash } from "node:crypto";
+
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 
@@ -7,6 +9,7 @@ import {
 	commitArtifactFromPath,
 	readArtifactByRef,
 	readProjectJsonFile,
+	stableJson,
 	type ArtifactRefV2,
 } from "./store.ts";
 
@@ -115,12 +118,32 @@ export default function fpaArtifactsExtension(pi: ExtensionAPI): void {
 		},
 	});
 
+	pi.registerTool({
+		name: "fpa_json_fingerprint",
+		label: "Fingerprint FP&A JSON Artifacts",
+		description: "Read project-local JSON artifacts and return deterministic SHA-256 fingerprints over their canonical JSON form. Use this to bind reviewed handoffs to exact proposal and review bodies.",
+		promptSnippet: "Fingerprint exact FP&A JSON artifacts for a version-bound handoff",
+		parameters: Type.Object({
+			paths: Type.Array(Type.String({ minLength: 1 }), { minItems: 1, maxItems: 8 }),
+		}, { additionalProperties: false }),
+		executionMode: "parallel",
+		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+			if (new Set(params.paths).size !== params.paths.length) throw new Error("Fingerprint paths must be unique.");
+			const entries = await Promise.all(params.paths.map(async (path) => {
+				const value = await readProjectJsonFile(ctx.cwd, path, "path");
+				return [path, createHash("sha256").update(stableJson(value)).digest("hex")] as const;
+			}));
+			return toolResult({ status: "fingerprinted", fingerprints: Object.fromEntries(entries) });
+		},
+	});
+
 	pi.registerTool({
 		name: "fpa_forecast_compose",
 		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: [

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

@@ -114,7 +114,11 @@ export default function fpaDashboardExtension(pi: ExtensionAPI): void {
 		parameters: Type.Object({
 			mode: StringEnum(["preview", "publish"] as const),
 			proposal_path: Type.String({ minLength: 1 }),
+			review_path: Type.String({ minLength: 1 }),
 			handoff_path: Type.String({ minLength: 1 }),
+			scope_id: Type.String({ minLength: 1, maxLength: 256 }),
+			cycle_id: Type.String({ minLength: 1, maxLength: 256 }),
+			forecast_role: Type.String({ minLength: 1, maxLength: 64 }),
 			expected_preview_fingerprint: Type.Optional(Type.String({ pattern: "^[a-f0-9]{64}$" })),
 			expected_dashboard_revision: Type.Optional(Type.Union([Type.String({ pattern: "^[a-f0-9]{64}$" }), Type.Null()])),
 			dashboard_title: Type.Optional(Type.String({ minLength: 1, maxLength: 256 })),
@@ -122,8 +126,13 @@ export default function fpaDashboardExtension(pi: ExtensionAPI): void {
 		executionMode: "sequential",
 		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
 			const proposal = await readProjectJsonFile(ctx.cwd, params.proposal_path, "proposal_path");
+			const review = await readProjectJsonFile(ctx.cwd, params.review_path, "review_path");
 			const handoff = await readProjectJsonFile(ctx.cwd, params.handoff_path, "handoff_path");
-			const module = projectStrategyModule(proposal, handoff);
+			const module = projectStrategyModule(proposal, handoff, review, {
+				scope_id: params.scope_id,
+				cycle_id: params.cycle_id,
+				forecast_role: params.forecast_role,
+			});
 			const previewFingerprint = dashboardModuleBuildFingerprint(module);
 			const current = await readDashboardModuleManifest(ctx.cwd);
 			if (params.mode === "preview") return toolResult({
@@ -375,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

@@ -6,6 +6,20 @@ import type { TableCell } from "./projector.ts";
 import type { ApprovedCycleForecast } from "../fpa-artifacts/contracts.ts";
 import type { ArtifactRefV2 } from "../fpa-artifacts/store.ts";
 
+const STRATEGY_ACTION_LABELS = {
+	grow: "增长",
+	hold: "保持",
+	cut: "削减",
+	stop: "止损",
+} as const;
+type StrategyAction = keyof typeof STRATEGY_ACTION_LABELS;
+
+export interface StrategyModuleContext {
+	scope_id: string;
+	cycle_id: string;
+	forecast_role: string;
+}
+
 function record(value: unknown, label: string): Record<string, unknown> {
 	if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error(`${label} must be an object.`);
 	return value as Record<string, unknown>;
@@ -37,6 +51,11 @@ function lines(value: unknown): string {
 	return value.map((item) => typeof item === "string" ? item : JSON.stringify(item)).join("\n");
 }
 
+function strategyAction(value: unknown, label: string): StrategyAction {
+	if (typeof value === "string" && value in STRATEGY_ACTION_LABELS) return value as StrategyAction;
+	throw new Error(`${label} must be one of grow, hold, cut, stop.`);
+}
+
 export function projectReviewModule(input: unknown): DashboardModuleBuild {
 	const analysis = record(input, "driver_analysis");
 	if (analysis.artifact_type !== "driver_analysis") throw new Error("Review publication requires artifact_type=driver_analysis.");
@@ -93,32 +112,74 @@ export function projectReviewModule(input: unknown): DashboardModuleBuild {
 	};
 }
 
-export function projectStrategyModule(proposalInput: unknown, handoffInput: unknown): DashboardModuleBuild {
+export function projectStrategyModule(
+	proposalInput: unknown,
+	handoffInput: unknown,
+	reviewInput: unknown,
+	expectedContext: StrategyModuleContext,
+): DashboardModuleBuild {
 	const proposal = record(proposalInput, "strategy_proposal");
 	const handoff = record(handoffInput, "reviewed_strategy_handoff");
+	const review = record(reviewInput, "strategy_review");
 	if (proposal.artifact_type !== "strategy_proposal") throw new Error("Strategy publication requires artifact_type=strategy_proposal.");
 	if (handoff.kind !== "fpa.reviewed-strategy-handoff") throw new Error("Strategy publication requires kind=fpa.reviewed-strategy-handoff.");
+	if (review.artifact_type !== "strategy_review") throw new Error("Strategy publication requires artifact_type=strategy_review.");
 	const strategyVersion = requiredString(proposal.strategy_version, "strategy_proposal.strategy_version");
 	if (handoff.strategy_version !== strategyVersion || handoff.reviewed_strategy_version !== strategyVersion) {
 		throw new Error("Reviewed handoff version does not match the strategy proposal version.");
 	}
 	if (handoff.status !== "ready") throw new Error("Reviewed strategy handoff is not ready for a human decision.");
+	if (review.reviewed_strategy_version !== strategyVersion) throw new Error("Strategy review version does not match the strategy proposal version.");
+	if (review.status !== "complete" && review.status !== "complete_with_limits") throw new Error("Strategy review is not complete.");
+	if (review.independence_confirmed !== true || handoff.independence_confirmed !== true) throw new Error("Strategy publication requires an independently reviewed proposal.");
+	const reviewerIdentity = requiredString(review.reviewer_identity, "strategy_review.reviewer_identity");
+	if (handoff.reviewer_identity !== reviewerIdentity) throw new Error("Reviewed handoff reviewer identity does not match the strategy review.");
+	if (review.opinion !== "support" && review.opinion !== "support_with_conditions") throw new Error("Strategy review opinion does not support human approval.");
+	if (handoff.review_opinion !== review.opinion) throw new Error("Reviewed handoff opinion does not match the strategy review.");
+	if (handoff.next_graph !== "fpa-forecast-freeze") throw new Error("Reviewed handoff next_graph must be fpa-forecast-freeze.");
+	for (const key of ["scope_id", "cycle_id", "forecast_role"] as const) {
+		const expected = requiredString(expectedContext[key], `strategy publication ${key}`);
+		if (handoff[key] !== expected) throw new Error(`Reviewed handoff ${key} does not match the publication context.`);
+	}
+	if (handoff.proposal_fingerprint !== fingerprint(proposal)) throw new Error("Reviewed handoff proposal_fingerprint does not match the strategy proposal.");
+	if (handoff.review_fingerprint !== fingerprint(review)) throw new Error("Reviewed handoff review_fingerprint does not match the strategy review.");
+	const reviewConditions = array(review.conditions_for_human_approval ?? [], "strategy_review.conditions_for_human_approval");
+	const residualRisks = array(review.residual_risks ?? [], "strategy_review.residual_risks");
+	if (stableJson(handoff.review_conditions ?? []) !== stableJson(reviewConditions)) throw new Error("Reviewed handoff conditions do not match the strategy review.");
+	if (stableJson(handoff.review_residual_risks ?? []) !== stableJson(residualRisks)) throw new Error("Reviewed handoff residual risks do not match the strategy review.");
 	const allocations = array(proposal.allocation, "strategy_proposal.allocation");
 	const outcomes = record(proposal.expected_outcomes, "strategy_proposal.expected_outcomes");
 	const base = record(outcomes.base ?? {}, "strategy_proposal.expected_outcomes.base");
-	const totalSpend = allocations.reduce((sum, item, index) => {
+	const parsedAllocations = allocations.map((item, index) => {
 		const allocation = record(item, `strategy_proposal.allocation[${index}]`);
-		if (typeof allocation.spend !== "number" || !Number.isFinite(allocation.spend)) throw new Error(`strategy_proposal.allocation[${index}].spend must be a finite number.`);
-		return sum + allocation.spend;
-	}, 0);
+		if (typeof allocation.spend !== "number" || !Number.isFinite(allocation.spend) || allocation.spend < 0) throw new Error(`strategy_proposal.allocation[${index}].spend must be a finite non-negative number.`);
+		if (typeof allocation.change_from_baseline !== "number" || !Number.isFinite(allocation.change_from_baseline)) throw new Error(`strategy_proposal.allocation[${index}].change_from_baseline must be a finite number.`);
+		const action = strategyAction(allocation.action, `strategy_proposal.allocation[${index}].action`);
+		const consistent = action === "grow"
+			? allocation.change_from_baseline > 0
+			: action === "hold"
+				? allocation.change_from_baseline === 0
+				: action === "cut"
+					? allocation.change_from_baseline < 0 && allocation.spend > 0
+					: allocation.change_from_baseline <= 0 && allocation.spend === 0;
+		if (!consistent) throw new Error(`strategy_proposal.allocation[${index}].action ${action} conflicts with spend and change_from_baseline.`);
+		return { allocation, action };
+	});
+	const totalSpend = parsedAllocations.reduce((sum, { allocation }) => sum + (allocation.spend as number), 0);
+	const actionCounts = Object.fromEntries(Object.keys(STRATEGY_ACTION_LABELS).map((action) => [action, 0])) as Record<StrategyAction, number>;
+	for (const { action } of parsedAllocations) actionCounts[action] += 1;
+	const actionHeadline = (Object.entries(STRATEGY_ACTION_LABELS) as [StrategyAction, string][])
+		.map(([action, label]) => `${label} ${actionCounts[action]} 项`)
+		.join("；");
 	return {
 		id: "next-strategy",
 		title: "下周期执行策略",
 		status: "awaiting_decision",
 		source: {
 			artifact_type: "reviewed_strategy",
-			artifact_fingerprint: fingerprint({ proposal, handoff }),
+			artifact_fingerprint: fingerprint({ proposal, review, handoff }),
 			proposal_fingerprint: fingerprint(proposal),
+			review_fingerprint: fingerprint(review),
 			handoff_fingerprint: fingerprint(handoff),
 			strategy_version: strategyVersion,
 			review_opinion: handoff.review_opinion,
@@ -137,6 +198,7 @@ export function projectStrategyModule(proposalInput: unknown, handoffInput: unkn
 						{ metric: "总预算", value: totalSpend.toFixed(2) },
 						{ metric: "Base 收入", value: cell(base.revenue) },
 						{ metric: "Base ROAS", value: cell(base.roas) },
+						{ metric: "执行结论", value: actionHeadline },
 						{ metric: "决策理由", value: lines(proposal.decision_rationale) },
 					],
 				},
@@ -150,12 +212,13 @@ export function projectStrategyModule(proposalInput: unknown, handoffInput: unkn
 					label: "预算分配",
 					columns: [
 						{ key: "app", label: "App" }, { key: "store", label: "商店" }, { key: "channel", label: "渠道" },
+						{ key: "action", label: "动作" },
 						{ key: "spend", label: "预算", align: "right" }, { key: "change", label: "较基线变化", align: "right" },
 					],
-					rows: allocations.map((item, index) => {
-						const allocation = record(item, `strategy_proposal.allocation[${index}]`);
+					rows: parsedAllocations.map(({ allocation, action }) => {
 						return {
 							app: cell(allocation.app_id), store: cell(allocation.store), channel: cell(allocation.channel_group),
+							action: STRATEGY_ACTION_LABELS[action],
 							spend: (allocation.spend as number).toFixed(2), change: cell(allocation.change_from_baseline),
 						};
 					}),
@@ -182,6 +245,61 @@ export function projectStrategyModule(proposalInput: unknown, handoffInput: unkn
 
 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: "下周期数据预测",
@@ -196,6 +314,7 @@ export function projectForecastModule(forecast: ApprovedCycleForecast, artifactR
 			data_as_of: forecast.data_as_of,
 		},
 		widgets: [
+			...qualityWidgets,
 			{
 				id: "forecast-summary",
 				type: "table",
@@ -204,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" ? " · 部分口径" : ""}`,
 				},
 			},
 			{
@@ -236,6 +355,8 @@ export function projectForecastModule(forecast: ApprovedCycleForecast, artifactR
 					}),
 				},
 			},
+			...issueWidgets,
+			...limitWidgets,
 		],
 	};
 }