@viccydev/pi-fpa 0.2.0 → 0.3.0

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

@@ -25,7 +25,7 @@ If approval evidence is absent, ambiguous, expired, conditional but unmet, or re
 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. Freeze the forecast inputs and write `approved_cycle_forecast` using [artifact-contract.md](references/artifact-contract.md).
+6. Build the canonical `approved_cycle_forecast` input using [artifact-contract.md](references/artifact-contract.md), then call `fpa_artifact_commit`.
 
 ## Boundaries
 
@@ -36,4 +36,4 @@ If approval evidence is absent, ambiguous, expired, conditional but unmet, or re
 
 ## Completion
 
-The planning workflow ends after this artifact is durably frozen by the runtime. Execution, if requested, is a separate workflow using `$fpa-execute-approved-strategy`. Review waits for the next cycle's Actuals and uses `$fpa-review-cycle`.
+The planning workflow ends only after `fpa_artifact_commit` returns `status: committed` and an `immutable_fingerprint`. A Markdown report is optional context, not the frozen source of truth. Execution, if requested, is a separate workflow using `$fpa-execute-approved-strategy`. Review waits for the next cycle's Actuals and uses `$fpa-review-cycle`.

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

@@ -14,7 +14,13 @@ source_snapshot_ids: []
 assumption_version: string
 model_version: string
 reporting_currency: string
-approved_allocation: []
+approved_allocation:
+  - app_id: string
+    store: string
+    channel_group: string
+    baseline_spend: number | null
+    approved_spend: number
+    action: stop | decrease | hold | increase | explore
 forecast_by_slice:
   - app_id: string
     store: string
@@ -25,12 +31,16 @@ forecast_by_slice:
         base: number | null
         upside: number | null
         unit: string
-        window: string
+        window: string # exactly <start_inclusive>..<end_exclusive>@<timezone>
 consolidated_forecast: {}
+calibration_policy:
+  stop_loss_roas_lt: number
+  deviation_warning_abs_gte: number
+  deviation_trigger_abs_gt: number
+  policy_version: string
 unsupported_metrics: []
 reconciliation_checks: []
 frozen_at: timestamp
-immutable_fingerprint: string
 ```
 
-The runtime supplies or verifies the immutable fingerprint. The agent must not claim the artifact is frozen until storage confirms it.
+Do not include `immutable_fingerprint` in the tool input. `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.

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

@@ -0,0 +1,29 @@
+---
+name: fpa-refresh-dashboard
+description: Preview, validate, and atomically publish the forecast closed-loop FP&A dashboard from a committed approved forecast, optional execution receipt, and current read-only Actuals. Use when the user asks to inspect, rebuild, or publish the tenant dashboard.
+---
+
+# FP&A Dashboard Refresh
+
+Load `$fpa-apply-core-rules` first. Follow [dashboard-policy.md](references/dashboard-policy.md).
+
+## Entry gate
+
+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.
+
+## Procedure
+
+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`.
+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.
+6. Report the published generation, source forecast fingerprint, data cutoff, warnings, and dashboard path.
+
+## 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.

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

@@ -0,0 +1,12 @@
+# Dashboard projection policy
+
+The dashboard is a deterministic projection, not a second planning model.
+
+- Source of truth: committed `approved_cycle_forecast`, optional committed `execution_receipt`, and read-only Actuals returned by the FP&A data Extension. Like-for-like totals are scoped to the exact approved App + Store + Channel tuples; other paid slices generate warnings and stay out of forecast comparisons.
+- Join grain: `app_id + store + channel_group`.
+- Ratios: aggregate additive numerators and denominators first, then divide. Division by zero or unavailable inputs returns `NULL`.
+- 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.
+- Ownership: only `fpa_dashboard_refresh` may publish this projection.