@viccydev/pi-fpa 0.9.1 → 0.9.3

package/README.md

@@ -159,12 +159,12 @@ pi list
 团队分发建议使用固定 Git tag：
 
 ```bash
-pi install git:github.com/linyqh/pi-fpa@v0.9.1
+pi install git:github.com/linyqh/pi-fpa@v0.9.3
 ```
 
 ## 发布到 npm
 
-发布动作由 GitHub Release 触发。Release 标签必须严格使用 `v<package.json version>`，例如版本 `0.9.1` 对应 `v0.9.1`。工作流会检出该标签，执行 `npm ci`、`npm test` 和包内容预检，全部通过后发布公开包 `@viccydev/pi-fpa`。普通 Release 发布到 `latest`，Prerelease 发布到 `next`。
+发布动作由 GitHub Release 触发。Release 标签必须严格使用 `v<package.json version>`，例如版本 `0.9.3` 对应 `v0.9.3`。工作流会检出该标签，执行 `npm ci`、`npm test` 和包内容预检，全部通过后发布公开包 `@viccydev/pi-fpa`。普通 Release 发布到 `latest`，Prerelease 发布到 `next`。
 
 发布认证使用 npm Trusted Publishing / OIDC，不使用长期 npm Token。npm 包后台的 Trusted Publisher 配置为：
 

package/extensions/fpa-dashboard/coordinator.ts

@@ -11,6 +11,7 @@ import {
 } from "../fpa-artifacts/store.ts";
 import { dashboardBuildFingerprint, resolveDashboardDir } from "./publisher.ts";
 import { publishDashboardProjection } from "./compat-publisher.ts";
+import { readDashboardModuleManifest } from "./module-publisher.ts";
 import { buildDashboardProjection } from "./service.ts";
 
 const EVENT_MAX_BYTES = 64 * 1024;
@@ -178,6 +179,13 @@ export interface DashboardCoordinatorStatus {
 	scope_id: string | null;
 	cycle_id: string | null;
 	generation_id: string | null;
+	/**
+	 * The modular manifest's current `dashboardRevision`, read from disk rather
+	 * than from the subscription. `generation_id` only ever identifies a legacy
+	 * whole-dashboard generation, so a consumer on a v2 manifest has nothing in
+	 * the same hash space to compare against without this.
+	 */
+	dashboard_revision: string | null;
 	pending: number;
 	processing: number;
 	dead: number;
@@ -384,6 +392,13 @@ async function writeCoordinatorStatus(
 	await ensureDirectory(dashboardDir, "Dashboard directory");
 	const previous = await readCoordinatorStatus(cwd);
 	const queue = options.queue ?? await inspectDashboardRefreshQueue(cwd);
+	// Read the revision off the manifest instead of tracking it in the
+	// subscription: every publish path (legacy refresh, module publish,
+	// strategy transition) rewrites the manifest, so this is the one value that
+	// is correct no matter who wrote last.
+	const dashboardRevision = await readDashboardModuleManifest(cwd)
+		.then((manifest) => manifest?.dashboardRevision ?? null)
+		.catch(() => previous?.dashboard_revision ?? null);
 	const status: DashboardCoordinatorStatus = {
 		kind: "fpa.dashboard.coordinator-status",
 		schema_version: 1,
@@ -397,6 +412,7 @@ async function writeCoordinatorStatus(
 		scope_id: options.subscription?.scope_id ?? null,
 		cycle_id: options.subscription?.cycle_id ?? null,
 		generation_id: options.subscription?.last_generation_id ?? null,
+		dashboard_revision: dashboardRevision,
 		pending: queue.pending,
 		processing: queue.processing,
 		dead: queue.dead,

package/extensions/fpa-dashboard/module-publisher.ts

@@ -6,7 +6,14 @@ import { stableJson } from "../fpa-artifacts/store.ts";
 import type { DashboardWidget } from "./projector.ts";
 import { validateDatasetForWidget } from "./schema.ts";
 
-export type DashboardModuleId = "period-review" | "next-strategy" | "next-forecast" | "execution-evidence";
+export type DashboardModuleId =
+	| "portfolio-overview"
+	| "period-review"
+	| "next-strategy"
+	| "next-forecast"
+	| "forecast-accuracy"
+	| "decision-ledger"
+	| "execution-evidence";
 export type DashboardModuleStatus = "published" | "awaiting_decision" | "approved" | "changes_requested" | "generating" | "superseded";
 
 export interface DashboardModuleInteraction {
@@ -20,6 +27,14 @@ export interface DashboardModuleBuild {
 	status: DashboardModuleStatus;
 	source: Record<string, unknown>;
 	widgets: DashboardWidget[];
+	/**
+	 * Decision limits the projector found while building this module — an
+	 * unverified execution receipt, approved slices with no Actuals, an
+	 * incomplete close. They belong to the module they were computed for, so
+	 * the consumer can show them next to the numbers they qualify instead of
+	 * pooling every module's caveats into one banner nobody reads.
+	 */
+	warnings?: string[];
 	interaction?: DashboardModuleInteraction;
 }
 
@@ -64,7 +79,15 @@ export interface DashboardManifestV2 {
 	modules: Partial<Record<DashboardModuleId, DashboardModuleManifestEntry>>;
 }
 
-const MODULE_IDS: DashboardModuleId[] = ["period-review", "next-strategy", "next-forecast", "execution-evidence"];
+const MODULE_IDS: DashboardModuleId[] = [
+	"portfolio-overview",
+	"period-review",
+	"next-strategy",
+	"next-forecast",
+	"forecast-accuracy",
+	"decision-ledger",
+	"execution-evidence",
+];
 const MODULE_ID_SET = new Set<string>(MODULE_IDS);
 const DATASET_FILE_RE = /^[a-zA-Z0-9][a-zA-Z0-9._-]{0,191}\.json$/;
 
@@ -136,6 +159,12 @@ function assertModule(module: DashboardModuleBuild): void {
 	if (!MODULE_ID_SET.has(module.id)) throw new Error(`Unsupported dashboard module id "${module.id}".`);
 	if (!module.title?.trim()) throw new Error("Dashboard module title is required.");
 	if (!Array.isArray(module.widgets) || module.widgets.length === 0 || module.widgets.length > 64) throw new Error("Dashboard module must contain between 1 and 64 widgets.");
+	if (module.warnings !== undefined) {
+		if (!Array.isArray(module.warnings) || module.warnings.length > 128) throw new Error("Dashboard module warnings must be an array of at most 128 entries.");
+		for (const warning of module.warnings) {
+			if (typeof warning !== "string" || warning.length > 4_096) throw new Error("Each dashboard module warning must be a string of at most 4096 characters.");
+		}
+	}
 	if (module.interaction && (module.id !== "next-strategy" || module.status !== "awaiting_decision")) {
 		throw new Error("Strategy decisions are available only on an awaiting next-strategy module.");
 	}
@@ -209,6 +238,9 @@ async function normalizeLegacyModuleReceipt(
 	if (stat.isSymbolicLink() || !stat.isFile()) throw new Error("Legacy dashboard build receipt must be a regular file.");
 	const old = JSON.parse(await readFile(sourcePath, "utf8")) as { source?: unknown; warnings?: unknown; datasets?: unknown };
 	if (!Array.isArray(old.datasets)) throw new Error("Legacy dashboard build receipt datasets are invalid.");
+	// The legacy generation receipt carried warnings at the top level too, so
+	// they migrate straight across rather than being buried inside `source`.
+	const legacyWarnings = Array.isArray(old.warnings) ? old.warnings.filter((entry): entry is string => typeof entry === "string") : [];
 	const receipt = {
 		kind: "fpa.dashboard.module.build",
 		schema_version: 1,
@@ -216,7 +248,8 @@ async function normalizeLegacyModuleReceipt(
 		module_revision: legacy.revision,
 		published_at: legacy.updatedAt,
 		status: legacy.status,
-		source: { ...(old.source && typeof old.source === "object" ? old.source : {}), warnings: old.warnings ?? [], legacy_generation_id: legacy.revision },
+		source: { ...(old.source && typeof old.source === "object" ? old.source : {}), legacy_generation_id: legacy.revision },
+		warnings: legacyWarnings,
 		datasets: old.datasets,
 	};
 	const contents = `${JSON.stringify(receipt, null, 2)}\n`;
@@ -290,6 +323,7 @@ export async function publishDashboardModule(options: PublishDashboardModuleOpti
 			published_at: publishedAt,
 			status: options.module.status,
 			source: options.module.source,
+			warnings: options.module.warnings ?? [],
 			datasets: datasets.map(({ widget, filename, digest }) => ({ logical: widget.dataset, filename, sha256: digest })),
 		};
 		const receiptContents = `${JSON.stringify(receipt, null, 2)}\n`;

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

@@ -2,7 +2,7 @@ import { createHash } from "node:crypto";
 
 import { stableJson } from "../fpa-artifacts/store.ts";
 import type { DashboardModuleBuild } from "./module-publisher.ts";
-import type { TableCell } from "./projector.ts";
+import type { TableCell, TableDataset } from "./projector.ts";
 import type { ApprovedCycleForecast } from "../fpa-artifacts/contracts.ts";
 import type { ArtifactRefV2 } from "../fpa-artifacts/store.ts";
 
@@ -56,10 +56,80 @@ function strategyAction(value: unknown, label: string): StrategyAction {
 	throw new Error(`${label} must be one of grow, hold, cut, stop.`);
 }
 
+function signedPercent(value: unknown): TableCell {
+	if (typeof value !== "number" || !Number.isFinite(value)) return cell(value);
+	return `${value > 0 ? "+" : ""}${(value * 100).toFixed(1)}%`;
+}
+
+/** `metric` repeats across scopes, so the scope is what makes a headline row identifiable. */
+function headlineLabel(entry: Record<string, unknown>, index: number): string {
+	const metric = requiredString(entry.metric ?? `Metric ${index + 1}`, `driver_analysis.headline_results[${index}].metric`);
+	return typeof entry.scope === "string" && entry.scope.trim() !== "" ? `${metric} · ${entry.scope}` : metric;
+}
+
+/**
+ * The `driver_analysis` contract publishes `headline_results` as a list of metric rows
+ * carrying actual/baseline/variance. Earlier artifacts used a flat `{ metric: value }`
+ * map, so both shapes are projected here rather than rejecting the contract shape.
+ */
+function headlineTable(value: unknown): TableDataset {
+	if (Array.isArray(value)) {
+		return {
+			label: "核心结果",
+			columns: [
+				{ key: "metric", label: "指标" },
+				{ key: "actual", label: "实际", align: "right" },
+				{ key: "baseline", label: "基准", align: "right" },
+				{ key: "variance", label: "变化", align: "right" },
+				{ key: "variance_pct", label: "变化率", align: "right" },
+			],
+			rows: value.map((item, index) => {
+				const entry = record(item, `driver_analysis.headline_results[${index}]`);
+				return {
+					metric: headlineLabel(entry, index),
+					actual: cell(entry.actual),
+					baseline: cell(entry.baseline),
+					variance: cell(entry.variance),
+					variance_pct: signedPercent(entry.variance_pct),
+				};
+			}),
+		};
+	}
+	const headline = record(value ?? {}, "driver_analysis.headline_results");
+	return {
+		label: "核心结果",
+		columns: [{ key: "metric", label: "指标" }, { key: "value", label: "结果", align: "right" }],
+		rows: Object.entries(headline).map(([metric, entry]) => ({ metric, value: cell(entry) })),
+	};
+}
+
+/** Evidence is a list in the contract; a bare JSON dump of it is unreadable in a table cell. */
+function listCell(value: unknown): TableCell {
+	return Array.isArray(value) ? lines(value) : cell(value);
+}
+
+/**
+ * `data_limits` is the contract field and `limitations` is what older artifacts wrote.
+ * They are merged instead of ranked so a published module never silently drops one set.
+ */
+function limitationRows(analysis: Record<string, unknown>): Array<Record<string, TableCell>> {
+	const seen = new Set<string>();
+	const rows: Array<Record<string, TableCell>> = [];
+	for (const key of ["data_limits", "limitations", "risks"] as const) {
+		if (analysis[key] === undefined) continue;
+		for (const item of array(analysis[key], `driver_analysis.${key}`)) {
+			const dedupe = stableJson(item);
+			if (seen.has(dedupe)) continue;
+			seen.add(dedupe);
+			rows.push({ item: cell(item) });
+		}
+	}
+	return rows;
+}
+
 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.");
-	const headline = record(analysis.headline_results ?? {}, "driver_analysis.headline_results");
 	const drivers = array(analysis.drivers ?? [], "driver_analysis.drivers");
 	return {
 		id: "period-review",
@@ -75,25 +145,25 @@ export function projectReviewModule(input: unknown): DashboardModuleBuild {
 			{
 				id: "review-headline",
 				type: "table",
-				span: "half",
+				span: "full",
 				dataset: "review-headline.json",
-				data: {
-					label: "核心结果",
-					columns: [{ key: "metric", label: "指标" }, { key: "value", label: "结果", align: "right" }],
-					rows: Object.entries(headline).map(([metric, value]) => ({ metric, value: cell(value) })),
-				},
+				data: headlineTable(analysis.headline_results),
 			},
 			{
 				id: "review-drivers",
 				type: "table",
-				span: "half",
+				span: "full",
 				dataset: "review-drivers.json",
 				data: {
 					label: "关键驱动",
-					columns: [{ key: "driver", label: "驱动" }, { key: "impact", label: "影响" }, { key: "evidence", label: "证据" }],
+					columns: [{ key: "driver", label: "驱动" }, { key: "impact", label: "影响", align: "right" }, { key: "evidence", label: "证据" }],
 					rows: drivers.map((item, index) => {
 						const driver = record(item, `driver_analysis.drivers[${index}]`);
-						return { driver: cell(driver.driver ?? driver.name ?? `Driver ${index + 1}`), impact: cell(driver.impact ?? driver.effect), evidence: cell(driver.evidence ?? driver.evidence_ids) };
+						return {
+							driver: cell(driver.driver ?? driver.name ?? `Driver ${index + 1}`),
+							impact: cell(driver.impact ?? driver.effect ?? driver.quantified_contribution),
+							evidence: listCell(driver.evidence ?? driver.evidence_ids),
+						};
 					}),
 				},
 			},
@@ -105,7 +175,7 @@ export function projectReviewModule(input: unknown): DashboardModuleBuild {
 				data: {
 					label: "限制与风险",
 					columns: [{ key: "item", label: "说明" }],
-					rows: array(analysis.limitations ?? analysis.risks ?? [], "driver_analysis.limitations").map((item) => ({ item: cell(item) })),
+					rows: limitationRows(analysis),
 				},
 			},
 		],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@viccydev/pi-fpa",
-  "version": "0.9.1",
+  "version": "0.9.3",
   "type": "module",
   "description": "Full-cycle FP&A planning, strategy, forecast, and review prompts, skills, and data tools for Pi",
   "license": "UNLICENSED",
@@ -19,17 +19,20 @@
   "engines": {
     "node": ">=22.19"
   },
+  "fpaDashboard": {
+    "contractVersion": 1
+  },
   "files": [
     "README.md",
-	"bin",
-	"graphs",
+    "bin",
+    "graphs",
     "prompts",
     "skills",
     "extensions"
   ],
-	"bin": {
-		"fpa-dashboard-worker": "./bin/fpa-dashboard-worker.mjs"
-	},
+  "bin": {
+    "fpa-dashboard-worker": "./bin/fpa-dashboard-worker.mjs"
+  },
   "scripts": {
     "test": "node tests/package-structure.test.mjs && node tests/workflow-routing.test.mjs && node --test tests/workflow-routing-guard.test.mjs tests/graph-contract.test.mjs tests/graph-installer.test.mjs && node tests/extension-unit.test.mjs && node --test tests/catalog-timeout.test.mjs tests/artifact-store.test.mjs tests/artifact-ledger.test.mjs tests/artifact-handoff.test.mjs tests/forecast-compose.test.mjs tests/forecast-finalize.test.mjs tests/dashboard-actuals.test.mjs tests/dashboard-projector.test.mjs tests/dashboard-module-publisher.test.mjs tests/dashboard-stage-projector.test.mjs tests/strategy-decision.test.mjs tests/cycle-operating-projection.test.mjs tests/forward-outlook.test.mjs tests/forecast-accuracy.test.mjs tests/dashboard-publisher.test.mjs tests/dashboard-provenance.test.mjs tests/dashboard-coordinator.test.mjs && node tests/pi-loader-smoke.mjs && node tests/worker-loader-smoke.mjs && node tests/publish-workflow.test.mjs",
     "test:structure": "node tests/package-structure.test.mjs",
@@ -59,7 +62,7 @@
       "./skills"
     ],
     "extensions": [
-		"./extensions/fpa-routing-guard/index.ts",
+      "./extensions/fpa-routing-guard/index.ts",
       "./extensions/fpa-data/index.ts",
       "./extensions/fpa-artifacts/index.ts",
       "./extensions/fpa-dashboard/index.ts"

package/skills/fpa-analyze-drivers/references/artifact-contract.md

@@ -8,6 +8,7 @@ actuals_snapshot_id: string
 comparison_basis: string
 headline_results:
   - metric: string
+    scope: string | absent   # required when the same metric is reported for more than one scope
     actual: number | null
     baseline: number | null
     variance: number | null