@viccydev/pi-fpa 0.7.1 → 0.7.2

package/README.md

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

package/extensions/fpa-dashboard/index.ts

@@ -58,11 +58,13 @@ export default function fpaDashboardExtension(pi: ExtensionAPI): void {
 		label: "Refresh FP&A Dashboard",
 		description:
 			"Build the forecast closed-loop dashboard from a committed approved forecast, optional committed execution receipt, and current read-only FP&A Actuals. " +
-			"Preview computes and validates without publishing; publish requires the exact preview fingerprint and atomically promotes a content-addressed generation.",
+			"Preview computes and validates without publishing; publish requires the exact preview fingerprint and atomically promotes a content-addressed generation. " +
+			"A backtest can be displayed only from an exact committed artifact when the user explicitly requests it.",
 		promptSnippet: "Preview or atomically publish the forecast closed-loop FP&A dashboard",
 		promptGuidelines: [
 			"Always call fpa_dashboard_refresh with mode=preview before mode=publish and carry forward the exact preview_fingerprint.",
 			"Never write .fpa-dashboard files with generic file or shell tools; use fpa_dashboard_refresh so calculations, lineage, and atomic publication stay consistent.",
+			"Set allow_backtest_display=true only when the user explicitly asks to display or publish an exact committed backtest; never infer this authorization from Graph completion.",
 		],
 		parameters: Type.Object(
 			{
@@ -70,6 +72,7 @@ export default function fpaDashboardExtension(pi: ExtensionAPI): void {
 				mode: StringEnum(["preview", "publish"] as const),
 				locale: Type.Optional(StringEnum(["zh-CN", "en-US"] as const)),
 				expected_preview_fingerprint: Type.Optional(Type.String({ pattern: "^[a-f0-9]{64}$" })),
+				allow_backtest_display: Type.Optional(Type.Boolean()),
 				scope_id: Type.Optional(Type.String({ minLength: 1, maxLength: 256 })),
 				cycle_id: Type.Optional(Type.String({ minLength: 1, maxLength: 256 })),
 				forecast_ref: Type.Optional(artifactRefSchema),
@@ -86,6 +89,9 @@ export default function fpaDashboardExtension(pi: ExtensionAPI): void {
 			if (hasAnyExactField && exactFields.some((value) => value === undefined)) {
 				throw new Error("scope_id, cycle_id, and forecast_ref must be supplied together; exact refresh never falls back to current artifacts.");
 			}
+			if (params.allow_backtest_display && !hasAnyExactField) {
+				throw new Error("allow_backtest_display requires an exact scope_id, cycle_id, and forecast_ref.");
+			}
 			const exact = hasAnyExactField ? {
 				scopeId: params.scope_id as string,
 				cycleId: params.cycle_id as string,
@@ -96,19 +102,24 @@ export default function fpaDashboardExtension(pi: ExtensionAPI): void {
 			} : undefined;
 			if (exact) {
 				const exactForecast = await readArtifactByRef(ctx.cwd, exact.forecastRef);
-				if (exactForecast.ledgerContext?.forecast_role === "backtest") {
-					throw new Error("A backtest forecast cannot be previewed or published as the operating dashboard.");
+				const exactRole = exactForecast.ledgerContext?.forecast_role;
+				if (exactRole === "backtest" && params.allow_backtest_display !== true) {
+					throw new Error("Displaying a backtest requires explicit user authorization through allow_backtest_display=true.");
+				}
+				if (params.allow_backtest_display === true && exactRole !== "backtest") {
+					throw new Error("allow_backtest_display is valid only for an exact committed backtest.");
 				}
 			}
 			const { build, forecast, actuals, sliceKeyMismatch, projector, runtime } = await buildDashboardProjection(ctx.cwd, params.preset, params.locale ?? "zh-CN", exact, signal);
-			if (build.source.forecast_role === "backtest") {
-				throw new Error("A backtest forecast cannot be previewed or published as the operating dashboard.");
+			if (build.source.forecast_role === "backtest" && params.allow_backtest_display !== true) {
+				throw new Error("Displaying a backtest requires explicit user authorization through allow_backtest_display=true.");
 			}
 			const previewFingerprint = dashboardBuildFingerprint(build, projector);
 			const summary = {
 				preset: params.preset,
 				preview_fingerprint: previewFingerprint,
 				forecast_version: forecast.forecast_version,
+				forecast_role: build.source.forecast_role,
 				forecast_fingerprint: build.source.forecast_fingerprint,
 				execution_fingerprint: build.source.execution_fingerprint,
 				data_as_of: build.source.data_as_of,
@@ -146,7 +157,14 @@ export default function fpaDashboardExtension(pi: ExtensionAPI): void {
 			if (params.expected_preview_fingerprint !== previewFingerprint) {
 				throw new Error("Dashboard inputs changed after preview; run preview again before publishing.");
 			}
-			const published = await publishDashboard({ cwd: ctx.cwd, build, projector, runtime, actualsSnapshot: actuals });
+			const published = await publishDashboard({
+				cwd: ctx.cwd,
+				build,
+				projector,
+				runtime,
+				actualsSnapshot: actuals,
+				allowBacktestDisplay: params.allow_backtest_display === true,
+			});
 			return toolResult({ status: "published", ...summary, dashboard_dir: published.dashboardDir, published_datasets: published.publishedDatasets });
 		},
 	});

package/extensions/fpa-dashboard/publisher.ts

@@ -22,6 +22,7 @@ export interface PublishDashboardOptions {
 	runtime: DashboardProjectorRuntime;
 	publishedAt?: string;
 	actualsSnapshot?: DashboardActualsSnapshot;
+	allowBacktestDisplay?: boolean;
 }
 
 export interface PublishDashboardResult {
@@ -177,8 +178,8 @@ export function dashboardBuildFingerprint(build: DashboardBuild, projector: Dash
 
 export async function publishDashboard(options: PublishDashboardOptions): Promise<PublishDashboardResult> {
 	assertBuild(options.build);
-	if (options.build.source.forecast_role === "backtest") {
-		throw new Error("A backtest forecast cannot replace the operating dashboard.");
+	if (options.build.source.forecast_role === "backtest" && options.allowBacktestDisplay !== true) {
+		throw new Error("A backtest cannot replace the operating dashboard without explicit user authorization.");
 	}
 	const projector = validateProjectorProvenance(options.projector);
 	const runtime = validateProjectorRuntime(options.runtime);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@viccydev/pi-fpa",
-  "version": "0.7.1",
+  "version": "0.7.2",
   "type": "module",
   "description": "Full-cycle FP&A planning, strategy, forecast, and review prompts, skills, and data tools for Pi",
   "license": "UNLICENSED",

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

@@ -40,7 +40,9 @@ from it, return `blocked`; never reconstruct or substitute the handoff.
    period start and is the approved direct successor of the active cycle. Use
    `backtest` for a historical rerun frozen after its target
    period; it is immutable evidence, not an operating plan, and it must not
-   replace the current pointer or enter the operating dashboard queue. A
+   replace the current pointer or enter the automatic operating dashboard
+   queue. It may be displayed from its exact immutable reference only when the
+   user explicitly requests a backtest dashboard publication. A
    `next_plan` is likewise stored as forward lineage and does not replace the
    legacy current pointer; its explicit dashboard handoff links it to the
    active cycle after successor validation.

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

@@ -26,14 +26,21 @@ only part of this tuple or fall back to a mutable current pointer.
 3. If the result is `enqueued` or `already_pending` and the current task expects
    the dashboard immediately, call one bounded `drain`, then verify with
    `fpa_dashboard_status`.
-4. If the result is `not_applicable` for a `backtest`, report that the historical
-   forecast is frozen and the operating dashboard intentionally remains
-   unchanged. Never relabel the artifact to force it into the active lineage.
+4. If the result is `not_applicable` for a `backtest`, do not treat that as a
+   failed artifact. Automatic post-Graph handoff intentionally leaves the
+   operating dashboard unchanged. If the user explicitly asked to display or
+   publish that backtest, continue through the exact backtest display path
+   below; otherwise report that the frozen historical forecast remains in the
+   ledger without changing the dashboard.
 
 ### Human-requested rebuild
 
 1. Call `fpa_dashboard_status` to inspect the current generation and diagnostics.
-2. Call `fpa_dashboard_refresh` with `preset: forecast-closed-loop-v1` and `mode: preview`.
+2. Call `fpa_dashboard_refresh` with `preset: forecast-closed-loop-v1` and
+   `mode: preview`. For a user-requested backtest display, pass the exact
+   `scope_id`, `cycle_id`, and `forecast_ref` from its immutable ledger handoff
+   together with `allow_backtest_display: true`. Never set that flag merely
+   because a Graph completed.
 3. Review the returned lineage, coverage, query receipts, warnings, widget list, and `preview_fingerprint`.
 4. If the user asked only to inspect or preview, stop without publishing.
 5. Publish only when the user explicitly asked to rebuild or publish the dashboard. Call the same tool with `mode: publish` and the exact preview fingerprint.
@@ -55,6 +62,10 @@ answer, and do not describe it as "the period has no data yet".
 - Never write `.fpa-dashboard` with generic file or shell tools.
 - 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.
+- `allow_backtest_display` is explicit user authorization to make that exact
+  immutable backtest the displayed dashboard generation. Omit it for automatic
+  handoff and for every non-backtest forecast.
 - If inputs change between preview and publish, preview again rather than bypassing the fingerprint check.
 - Artifact commit never performs dashboard I/O. The calling main Agent explicitly
   enqueues its exact handoff. Actuals watermark changes remain monitored by the

package/skills/fpa-refresh-dashboard/references/dashboard-policy.md

@@ -8,5 +8,5 @@ The dashboard is a deterministic projection, not a second planning model.
 - Coverage: retain the Actuals cutoff and query receipts. Planned slices with no Actuals remain null; paid Actuals outside the approved allocation are reported as warnings.
 - Comparison: the prior-period window must contain the same number of covered calendar days as the current Actuals window, using the forecast timezone.
 - Execution truth: `reported` means reported, not verified. Only `verified` external evidence may be labelled verified.
-- Publication: preview first, then atomically publish content-addressed datasets and promote `manifest.json` last.
+- Publication: preview first, then atomically publish content-addressed datasets and promote `manifest.json` last. Automatic handoff never promotes a backtest; an exact committed backtest may be displayed only after explicit user authorization through `allow_backtest_display` on both preview and publish.
 - Ownership: only `fpa_dashboard_refresh` may publish this projection.