@viccydev/pi-fpa 0.4.1 → 0.6.0

package/extensions/fpa-dashboard/source.ts

@@ -1,4 +1,7 @@
+import { createHash } from "node:crypto";
+
 import { sliceKey, type Period } from "../fpa-artifacts/contracts.ts";
+import { stableJson } from "../fpa-artifacts/store.ts";
 
 export interface QueryReceipt {
 	dataset: string;
@@ -18,6 +21,27 @@ export interface DashboardActualSlice {
 /** Sentinel used when no Actuals row exists yet, so no calendar date can be reported. */
 export const ACTUALS_DATA_AS_OF_UNAVAILABLE = "unavailable";
 
+function canonicalCalendarDate(value: string, label: string): string {
+	if (!/^\d{4}-\d{2}-\d{2}$/.test(value)) throw new Error(`${label} must use YYYY-MM-DD.`);
+	const parsed = new Date(`${value}T00:00:00Z`);
+	if (Number.isNaN(parsed.getTime()) || parsed.toISOString().slice(0, 10) !== value) {
+		throw new Error(`${label} must be a real canonical calendar date.`);
+	}
+	return value;
+}
+
+function finalPeriodDate(value: Period): string {
+	const finalInstant = new Date(Date.parse(value.end_exclusive) - 1);
+	const parts = new Intl.DateTimeFormat("en-US", {
+		timeZone: value.timezone,
+		year: "numeric",
+		month: "2-digit",
+		day: "2-digit",
+	}).formatToParts(finalInstant);
+	const byType = new Map(parts.map((part) => [part.type, part.value]));
+	return `${byType.get("year")}-${byType.get("month")}-${byType.get("day")}`;
+}
+
 /**
  * How Actuals were scoped against the frozen forecast.
  *
@@ -37,8 +61,32 @@ export interface DashboardDailyPoint {
 export interface DashboardActualsSnapshot {
 	period: Period;
 	data_as_of: string;
+	snapshot_evidence: {
+		snapshot_id: string | null;
+		available_at: string | null;
+		consistency: "single_statement" | "multi_query_unverified" | "legacy_unverified";
+		/** Explicit close signal emitted by the source ETL; time elapsed is never treated as closure. */
+		source_close_signal_id: string | null;
+		source_closed_through: string | null;
+		source_close_emitted_at: string | null;
+		source_close_signal_sha256: string | null;
+		period_complete: boolean;
+		reconciled: boolean;
+	};
 	reporting_currency: string;
 	scope_mode: DashboardScopeMode;
+	/**
+	 * Whether ua_spend holds any paid rows in the target window at all, ignoring
+	 * the approved slice keys.
+	 *
+	 * A forecast whose slice keys do not exist in the mart produces exactly the
+	 * same empty Actuals as a cycle that simply has not started yet, and the two
+	 * are indistinguishable from the scoped queries alone — the scoped query is
+	 * what determines coverage, so a wrong key erases its own evidence. Probing
+	 * once without the key predicate separates them: data in the window plus no
+	 * matching slice means the keys are wrong, not that the period is early.
+	 */
+	period_has_unscoped_actuals: boolean;
 	coverage: {
 		date_min: string | null;
 		date_max: string | null;
@@ -100,10 +148,12 @@ function period(value: unknown, path: string): Period {
 
 export function validateActualsSnapshot(value: unknown): DashboardActualsSnapshot {
 	const source = record(value, "actuals");
+	const snapshotPeriod = period(source.period, "actuals.period");
 	const coverage = record(source.coverage, "actuals.coverage");
 	const dailySource = source.daily;
 	const slicesSource = source.slices;
 	const receiptsSource = source.query_receipts;
+	const evidenceSource = source.snapshot_evidence === undefined ? null : record(source.snapshot_evidence, "actuals.snapshot_evidence");
 	if (!Array.isArray(dailySource)) throw new Error("actuals.daily must be an array.");
 	if (!Array.isArray(slicesSource)) throw new Error("actuals.slices must be an array.");
 	if (!Array.isArray(receiptsSource)) throw new Error("actuals.query_receipts must be an array.");
@@ -143,11 +193,96 @@ export function validateActualsSnapshot(value: unknown): DashboardActualsSnapsho
 	if (!/^[A-Z]{3}$/.test(reportingCurrency)) throw new Error("actuals.reporting_currency must be an ISO-4217 currency code.");
 	const scopeMode = source.scope_mode === undefined ? "app" : string(source.scope_mode, "actuals.scope_mode");
 	if (scopeMode !== "app" && scopeMode !== "portfolio") throw new Error('actuals.scope_mode must be "app" or "portfolio".');
+	if (source.period_has_unscoped_actuals !== undefined && typeof source.period_has_unscoped_actuals !== "boolean") {
+		throw new Error("actuals.period_has_unscoped_actuals must be a boolean.");
+	}
+	let snapshotEvidence: DashboardActualsSnapshot["snapshot_evidence"] = {
+		snapshot_id: null,
+		available_at: null,
+		consistency: "legacy_unverified",
+		source_close_signal_id: null,
+		source_closed_through: null,
+		source_close_emitted_at: null,
+		source_close_signal_sha256: null,
+		period_complete: false,
+		reconciled: false,
+	};
+	if (evidenceSource) {
+		const consistency = string(evidenceSource.consistency, "actuals.snapshot_evidence.consistency");
+		if (consistency !== "single_statement" && consistency !== "multi_query_unverified" && consistency !== "legacy_unverified") {
+			throw new Error("actuals.snapshot_evidence.consistency is unsupported.");
+		}
+		if (evidenceSource.snapshot_id !== null && typeof evidenceSource.snapshot_id !== "string") throw new Error("actuals.snapshot_evidence.snapshot_id must be a string or null.");
+		if (evidenceSource.available_at !== null && (typeof evidenceSource.available_at !== "string" || Number.isNaN(Date.parse(evidenceSource.available_at)))) {
+			throw new Error("actuals.snapshot_evidence.available_at must be an ISO timestamp or null.");
+		}
+		if (typeof evidenceSource.period_complete !== "boolean" || typeof evidenceSource.reconciled !== "boolean") {
+			throw new Error("actuals.snapshot_evidence period_complete and reconciled must be booleans.");
+		}
+		const sourceCloseSignalId = evidenceSource.source_close_signal_id === undefined || evidenceSource.source_close_signal_id === null
+			? null
+			: string(evidenceSource.source_close_signal_id, "actuals.snapshot_evidence.source_close_signal_id");
+		const sourceClosedThrough = evidenceSource.source_closed_through === undefined || evidenceSource.source_closed_through === null
+			? null
+			: string(evidenceSource.source_closed_through, "actuals.snapshot_evidence.source_closed_through");
+		if (sourceClosedThrough !== null) canonicalCalendarDate(sourceClosedThrough, "actuals.snapshot_evidence.source_closed_through");
+		const sourceCloseEmittedAt = evidenceSource.source_close_emitted_at === undefined || evidenceSource.source_close_emitted_at === null
+			? null
+			: string(evidenceSource.source_close_emitted_at, "actuals.snapshot_evidence.source_close_emitted_at");
+		if (sourceCloseEmittedAt !== null && (Number.isNaN(Date.parse(sourceCloseEmittedAt)) || new Date(sourceCloseEmittedAt).toISOString() !== sourceCloseEmittedAt)) {
+			throw new Error("actuals.snapshot_evidence.source_close_emitted_at must be a canonical ISO timestamp or null.");
+		}
+		const sourceCloseSignalSha256 = evidenceSource.source_close_signal_sha256 === undefined || evidenceSource.source_close_signal_sha256 === null
+			? null
+			: string(evidenceSource.source_close_signal_sha256, "actuals.snapshot_evidence.source_close_signal_sha256");
+		if (sourceCloseSignalSha256 !== null && !/^[a-f0-9]{64}$/.test(sourceCloseSignalSha256)) throw new Error("actuals.snapshot_evidence.source_close_signal_sha256 must be a SHA-256 digest or null.");
+		const closeTuple = [sourceCloseSignalId, sourceClosedThrough, sourceCloseEmittedAt, sourceCloseSignalSha256];
+		if (closeTuple.some((item) => item !== null) && closeTuple.some((item) => item === null)) {
+			throw new Error("actuals.snapshot_evidence source close evidence must be entirely present or entirely null.");
+		}
+		if (sourceCloseSignalId && sourceClosedThrough && sourceCloseEmittedAt && sourceCloseSignalSha256) {
+			const expectedDigest = createHash("sha256").update(stableJson({
+				kind: "fpa.actuals.source-close",
+				schema_version: 1,
+				dataset: "ua_spend",
+				signal_id: sourceCloseSignalId,
+				closed_through: sourceClosedThrough,
+				emitted_at: sourceCloseEmittedAt,
+			})).digest("hex");
+			if (sourceCloseSignalSha256 !== expectedDigest) throw new Error("actuals.snapshot_evidence source close digest does not match its canonical evidence.");
+		}
+		if (evidenceSource.period_complete && (!sourceCloseSignalId || !sourceClosedThrough || !sourceCloseEmittedAt || !sourceCloseSignalSha256)) {
+			throw new Error("period_complete requires complete explicit source close evidence.");
+		}
+		if (evidenceSource.period_complete && (
+			consistency !== "single_statement"
+			|| evidenceSource.available_at === null
+			|| (sourceClosedThrough as string) < finalPeriodDate(snapshotPeriod)
+			|| Date.parse(evidenceSource.available_at as string) < Date.parse(sourceCloseEmittedAt as string)
+		)) {
+			throw new Error("period_complete requires single-statement evidence observed after a source close signal covering the target period.");
+		}
+		snapshotEvidence = {
+			snapshot_id: evidenceSource.snapshot_id as string | null,
+			available_at: evidenceSource.available_at as string | null,
+			consistency,
+			source_close_signal_id: sourceCloseSignalId,
+			source_closed_through: sourceClosedThrough,
+			source_close_emitted_at: sourceCloseEmittedAt,
+			source_close_signal_sha256: sourceCloseSignalSha256,
+			period_complete: evidenceSource.period_complete,
+			reconciled: evidenceSource.reconciled,
+		};
+	}
 	return {
-		period: period(source.period, "actuals.period"),
+		period: snapshotPeriod,
 		data_as_of: string(source.data_as_of, "actuals.data_as_of"),
+		snapshot_evidence: snapshotEvidence,
 		reporting_currency: reportingCurrency,
 		scope_mode: scopeMode,
+		// Absent means the probe was never run, which is only ever the benign
+		// reading: nothing here may invent evidence that the keys are wrong.
+		period_has_unscoped_actuals: source.period_has_unscoped_actuals === true,
 		coverage: {
 			date_min: coverage.date_min === null ? null : string(coverage.date_min, "actuals.coverage.date_min"),
 			date_max: coverage.date_max === null ? null : string(coverage.date_max, "actuals.coverage.date_max"),

package/extensions/fpa-dashboard/status.ts

@@ -3,17 +3,27 @@ import { lstat, readFile } from "node:fs/promises";
 import { dirname, join, resolve } from "node:path";
 
 import { resolveDashboardDir } from "./publisher.ts";
+import {
+	validateProjectorProvenance,
+	validateProjectorRuntime,
+	type DashboardProjectorProvenance,
+	type DashboardProjectorRuntime,
+} from "./provenance.ts";
 import { stableJson } from "../fpa-artifacts/store.ts";
 import { DASHBOARD_WIDGET_TYPES, validateDatasetForWidget, type DashboardWidgetType } from "./schema.ts";
+import { validateActualsSnapshot } from "./source.ts";
 
-const DATASET_FILE_RE = /^[a-zA-Z0-9][a-zA-Z0-9._-]{0,63}\.json$/;
-const GENERATION_RECEIPT_RE = /^build-receipt\.([a-f0-9]{12})\.([a-f0-9]{12})\.json$/;
+const DATASET_FILE_RE = /^[a-zA-Z0-9][a-zA-Z0-9._-]{0,191}\.json$/;
+const GENERATION_RECEIPT_RE = /^build-receipt\.([a-f0-9]{64})\.([a-f0-9]{64})\.json$/;
 
 export interface DashboardStatus {
 	dashboard_exists: boolean;
 	dashboard_dir: string;
 	generation_id?: string;
 	updated_at?: string;
+	projector?: DashboardProjectorProvenance;
+	runtime?: DashboardProjectorRuntime;
+	provenance_status?: "verified" | "legacy_missing" | "invalid";
 	widget_count: number;
 	diagnostics: Array<{ target: string; message: string }>;
 }
@@ -50,6 +60,9 @@ export async function inspectDashboard(cwd: string): Promise<DashboardStatus> {
 		return { dashboard_exists: false, dashboard_dir: dashboardDir, widget_count: 0, diagnostics: [{ target: "manifest.json", message: "unsupported dashboard kind/schema or widgets shape" }] };
 	}
 	const receiptDatasets = new Map<string, string>();
+	let projector: DashboardProjectorProvenance | undefined;
+	let runtime: DashboardProjectorRuntime | undefined;
+	let provenanceStatus: DashboardStatus["provenance_status"];
 	const receiptFilename = typeof source.buildReceipt === "string" && DATASET_FILE_RE.test(source.buildReceipt)
 		? source.buildReceipt
 		: "build-receipt.json";
@@ -62,6 +75,23 @@ export async function inspectDashboard(cwd: string): Promise<DashboardStatus> {
 		if (receiptSource.kind !== "fpa.dashboard.build" || receiptSource.schema_version !== 1) {
 			throw new Error("has an unsupported build receipt kind or schema");
 		}
+		if (receiptSource.projector === undefined && receiptSource.runtime === undefined) {
+			provenanceStatus = "legacy_missing";
+		} else {
+			provenanceStatus = "verified";
+			try {
+				projector = validateProjectorProvenance(receiptSource.projector);
+			} catch (error) {
+				provenanceStatus = "invalid";
+				diagnostics.push({ target: `${receiptFilename} projector`, message: error instanceof Error ? error.message : String(error) });
+			}
+			try {
+				runtime = validateProjectorRuntime(receiptSource.runtime);
+			} catch (error) {
+				provenanceStatus = "invalid";
+				diagnostics.push({ target: `${receiptFilename} runtime`, message: error instanceof Error ? error.message : String(error) });
+			}
+		}
 		if (typeof source.generationId === "string" && receiptSource.generation_id !== source.generationId) {
 			diagnostics.push({ target: receiptFilename, message: "generation does not match manifest.json" });
 		}
@@ -70,15 +100,33 @@ export async function inspectDashboard(cwd: string): Promise<DashboardStatus> {
 		}
 		const receiptNameMatch = receiptFilename.match(GENERATION_RECEIPT_RE);
 		if (receiptNameMatch) {
-			if (typeof source.generationId !== "string" || receiptNameMatch[1] !== source.generationId.slice(0, 12)) {
-				diagnostics.push({ target: receiptFilename, message: "filename generation prefix does not match manifest.json" });
+			if (typeof source.generationId !== "string" || receiptNameMatch[1] !== source.generationId) {
+				diagnostics.push({ target: receiptFilename, message: "filename generation digest does not match manifest.json" });
 			}
 			const receiptDigest = createHash("sha256").update(stableJson(receipt)).digest("hex");
-			if (receiptNameMatch[2] !== receiptDigest.slice(0, 12)) {
+			if (receiptNameMatch[2] !== receiptDigest) {
 				diagnostics.push({ target: receiptFilename, message: "receipt content digest does not match its filename" });
 			}
 		}
 		if (!Array.isArray(receiptSource.datasets)) throw new Error("datasets must be an array");
+		if (receiptSource.source && typeof receiptSource.source === "object" && !Array.isArray(receiptSource.source)) {
+			const actualsRef = (receiptSource.source as Record<string, unknown>).actuals_snapshot_ref;
+			if (actualsRef !== undefined) {
+				if (typeof actualsRef !== "string" || !/^[a-f0-9]{64}$/.test(actualsRef)) {
+					diagnostics.push({ target: `${receiptFilename} source.actuals_snapshot_ref`, message: "must be a sha256 digest" });
+				} else {
+					try {
+						const snapshot = await readJson(join(dashboardDir, "actuals", `${actualsRef}.json`), 2 * 1024 * 1024);
+						const validated = validateActualsSnapshot(snapshot);
+						if (createHash("sha256").update(stableJson(validated)).digest("hex") !== actualsRef) {
+							diagnostics.push({ target: `actuals/${actualsRef}.json`, message: "Actuals snapshot content digest does not match its immutable ref" });
+						}
+					} catch (error) {
+						diagnostics.push({ target: `actuals/${actualsRef}.json`, message: error instanceof Error ? error.message : String(error) });
+					}
+				}
+			}
+		}
 		for (const [index, raw] of receiptSource.datasets.entries()) {
 			if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
 				diagnostics.push({ target: `${receiptFilename} datasets[${index}]`, message: "must be an object" });
@@ -148,6 +196,9 @@ export async function inspectDashboard(cwd: string): Promise<DashboardStatus> {
 		dashboard_dir: dashboardDir,
 		...(typeof source.generationId === "string" ? { generation_id: source.generationId } : {}),
 		...(typeof source.updatedAt === "string" ? { updated_at: source.updatedAt } : {}),
+		...(projector ? { projector } : {}),
+		...(runtime ? { runtime } : {}),
+		...(provenanceStatus ? { provenance_status: provenanceStatus } : {}),
 		widget_count: source.widgets.length,
 		diagnostics,
 	};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@viccydev/pi-fpa",
-  "version": "0.4.1",
+  "version": "0.6.0",
   "type": "module",
   "description": "Full-cycle FP&A planning, strategy, forecast, and review prompts, skills, and data tools for Pi",
   "license": "UNLICENSED",
@@ -16,20 +16,30 @@
     "access": "public",
     "registry": "https://registry.npmjs.org"
   },
+  "engines": {
+    "node": ">=22.19"
+  },
   "files": [
     "README.md",
+	"bin",
     "prompts",
     "skills",
     "extensions"
   ],
+	"bin": {
+		"fpa-dashboard-worker": "./bin/fpa-dashboard-worker.mjs"
+	},
   "scripts": {
-    "test": "node tests/package-structure.test.mjs && node tests/extension-unit.test.mjs && node --test tests/catalog-timeout.test.mjs tests/artifact-store.test.mjs tests/dashboard-actuals.test.mjs tests/dashboard-projector.test.mjs tests/dashboard-publisher.test.mjs && node tests/pi-loader-smoke.mjs && node tests/publish-workflow.test.mjs",
+    "test": "node tests/package-structure.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/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: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/dashboard-actuals.test.mjs tests/dashboard-projector.test.mjs tests/dashboard-publisher.test.mjs",
-    "test:loader": "node tests/pi-loader-smoke.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/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: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"
   },
+  "dependencies": {
+    "jiti": "2.7.0"
+  },
   "peerDependencies": {
     "@earendil-works/pi-ai": "*",
     "@earendil-works/pi-coding-agent": "*",

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

@@ -29,7 +29,7 @@ If any requirement is missing, return `blocked` and make no external call. Never
 4. Present or record the dry-run result when the adapter supports it.
 5. Execute only the approved mutation set.
 6. Read back the resulting state and reconcile it with the requested state.
-7. Build the canonical `execution_receipt` using [artifact-contract.md](references/artifact-contract.md), writing it to `artifacts/execution_receipt.input.json`, then commit it with `fpa_artifact_commit` using `artifact_path`.
+7. Build the canonical `execution_receipt` using [artifact-contract.md](references/artifact-contract.md), writing it to `artifacts/execution_receipt.input.json`, then commit it with `fpa_artifact_commit` using `artifact_path` and the exact `scope_id`, `cycle_id`, and approved Forecast `upstream_refs` entry returned by planning. Never validate against a mutable current pointer.
 
 ## Stop conditions
 

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

@@ -21,21 +21,31 @@ If approval evidence is absent, ambiguous, expired, conditional but unmet, or re
 ## Procedure
 
 1. Verify approval and artifact lineage.
-2. Lock the approved allocation and all approval conditions.
+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.
 5. Reconcile allocation totals, formulas, and cross-metric identities.
-6. Build the canonical `approved_cycle_forecast` input using [artifact-contract.md](references/artifact-contract.md), writing it to `artifacts/approved_cycle_forecast.input.json`.
-7. Commit it with `fpa_artifact_commit` using `artifact_path`.
-
-## Why the draft file
-
-A full forecast is far too large to emit as a single inline tool argument: the
-call gets cut off at the model output limit, and what is left behind reads like
-a finished turn. Write the draft with the file tools instead — across as many
-turns and corrections as it takes — then commit the finished file by path. If a
-later step in this graph already commits the draft for you, stop after writing
-it and say so; do not claim a fingerprint you were not handed.
+6. Write the forecast plan to `artifacts/forecast_plan.json` using [artifact-contract.md](references/artifact-contract.md).
+7. Derive the artifact with `fpa_forecast_compose`, then freeze it with
+   `fpa_artifact_commit` and an assigned context containing the explicit
+   `scope_id`, `cycle_id`, and `forecast_role`. Use `original` only when the
+   forecast is frozen no later than period start; use `eac` for an in-period
+   reforecast and `next_plan` when it is the approved direct successor of the
+   active cycle.
+
+## Write the decision, not the arithmetic
+
+The only judgement in a forecast is the allocation and each slice's ROAS
+assumption. Revenue, the consolidated roll-up, units, windows, and `frozen_at`
+all follow from those, and `fpa_forecast_compose` derives them — which is what
+makes the identities the commit checks true by construction rather than
+dependent on transcribing several hundred numbers without a slip.
+
+So do not hand-compute revenue, totals, or ratios, and do not emit the full
+artifact as one tool argument: that is the shape that gets cut off at the model
+output limit and leaves a turn that reads finished but committed nothing. If a
+later node in this graph composes and commits for you, stop after writing the
+plan and say so; never claim a fingerprint you were not handed.
 
 ## Status and the publish gate
 

package/skills/fpa-forecast-approved-strategy/references/artifact-contract.md

@@ -21,6 +21,7 @@ approved_allocation:
     baseline_spend: number | null
     approved_spend: number
     action: stop | decrease | hold | increase | explore
+	owner: string  # optional accountable operator
 forecast_by_slice:
   - app_id: string
     store: string
@@ -45,11 +46,61 @@ frozen_at: timestamp
 
 Do not include `immutable_fingerprint` in the tool input; a draft that carries one is rejected. `fpa_artifact_commit` validates exact fields, approval state, allocation totals, every scenario's slice-to-consolidated totals, and supplied ROAS against aggregated revenue/spend. It computes the fingerprint and returns it after durable storage. The agent must not claim the artifact is frozen until that tool succeeds.
 
-Pass this artifact by path, not inline:
+## Author the plan, not the artifact
 
+Almost none of the artifact above is a decision. The decision is the allocation
+and the ROAS assumption behind each slice; revenue, the ROAS write-back, the
+consolidated roll-up, every unit and window string, and `frozen_at` all follow
+from those by arithmetic. Write the plan and let `fpa_forecast_compose` derive
+the rest — it makes the identities the commit checks true by construction
+instead of true if you typed them correctly.
+
+```yaml
+# artifacts/forecast_plan.json
+status: complete | complete_with_limits | blocked
+forecast_version: string
+strategy_version: string
+strategy_review_id: string
+human_approval_id: string
+approval_conditions_satisfied: boolean
+target_period: {start_inclusive: timestamp, end_exclusive: timestamp, timezone: string}
+data_as_of: timestamp
+source_snapshot_ids: []
+assumption_version: string
+model_version: string
+reporting_currency: string
+calibration_policy: {stop_loss_roas_lt, deviation_warning_abs_gte, deviation_trigger_abs_gt, policy_version}
+unsupported_metrics: []
+reconciliation_checks: []
+slices:
+  - app_id: string          # ua_spend.app_code
+    store: string           # ua_spend.platform — ios | android, never a store name
+    channel_group: string   # ua_spend.media_source, verbatim
+    baseline_spend: number | null
+    approved_spend: number
+    action: stop | decrease | hold | increase | explore
+	owner: string  # optional; shown as the accountable operator on the CEO dashboard
+    roas: {downside: number|null, base: number|null, upside: number|null}
+consolidated_extra_metrics:   # optional; measured portfolio series only
+  metric_name: {downside, base, upside, unit}
 ```
-write  artifacts/approved_cycle_forecast.input.json
-fpa_artifact_commit  { "artifact_path": "artifacts/approved_cycle_forecast.input.json" }
+
+Then:
+
+```
+write  artifacts/forecast_plan.json
+fpa_forecast_compose  { "plan_path": "artifacts/forecast_plan.json" }
+fpa_artifact_commit   { "artifact": <the artifact compose returned> }
 ```
 
-`artifact_path` is project-relative, must stay inside the project, and must be a regular file. The inline `artifact` parameter still works and is fine for small artifacts, but a forecast of any real size will be truncated at the model output limit if you try to emit it in one call.
+Rules the plan has to respect, because compose enforces them:
+
+- **Spend is a decision, not a prediction.** It is identical in all three scenarios, so a slice carries one `approved_spend`. Only revenue moves, through `roas`.
+- **A stopped slice has no ROAS.** `approved_spend: 0` means revenue 0 and `roas` null in all three scenarios — the contract derives ROAS as revenue/spend and calls a zero denominator null.
+- **Slice keys must be values `ua_spend` actually uses.** A plan naming `google_play` where the mart says `android` is rejected with the valid values listed. The single-placeholder App axis for a scoped-out portfolio is the one permitted exception.
+- **`status` and `unsupported_metrics` must agree.** `complete` requires an empty list; `complete_with_limits` requires a non-empty one. Scope excluded upstream is neither.
+- **Do not hand-compute anything derived.** A ROAS rounded to four decimals misses the commit tolerance and costs a re-draft.
+
+## Committing an artifact you already hold
+
+`fpa_artifact_commit` also takes `artifact_path` for an artifact written to disk, and `artifact` for one passed inline. Both are project-relative and fail closed. Emitting a full artifact by hand in a single tool call is what gets cut off at the model output limit — prefer the plan above.

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

@@ -11,6 +11,10 @@ Load `$fpa-apply-core-rules` first. Follow [dashboard-policy.md](references/dash
 
 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.
 
+For an assigned ledger cycle, pass `scope_id`, `cycle_id`, and the exact
+`forecast_ref`; pass exact execution/forward refs when available. Never provide
+only part of this tuple or fall back to a mutable current pointer.
+
 ## Procedure
 
 1. Call `fpa_dashboard_status` to inspect the current generation and diagnostics.
@@ -20,10 +24,25 @@ Require a committed `approved_cycle_forecast` for the target project. Treat a co
 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.
 6. Report the published generation, source forecast fingerprint, data cutoff, warnings, and dashboard path.
 
+## When preview returns `blocked_slice_key_mismatch`
+
+Every approved slice is missing its Actuals while the target window demonstrably
+holds paid rows. That is not an early cycle and not a scope limitation: the
+frozen forecast is keyed on dimension values `ua_spend` never uses, so the
+dashboard would publish complete-looking and entirely empty. Publish is refused.
+
+Report it as a failure, name the offending key axis, and send the work back to
+the node that froze the forecast. Do not re-preview hoping for a different
+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 fabricate Actuals, replace missing values with zero, or average row-level ratios.
 - Do not edit the approved forecast during projection.
 - If inputs change between preview and publish, preview again rather than bypassing the fingerprint check.
-- This skill performs one bounded refresh; it does not continuously monitor the dashboard.
+- This skill performs one bounded human-requested refresh. Assigned artifact
+  commits and Actuals watermark changes are monitored separately by the durable
+  package coordinator running in the package-owned `fpa-dashboard-worker`
+  process (never in the read-only Web host); inspect or drain that queue with
+  `fpa_dashboard_refresh_queue` rather than recreating its writes manually.