@viccydev/pi-fpa 0.2.0

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

@@ -0,0 +1,34 @@
+# `driver_analysis` contract
+
+```yaml
+artifact_type: driver_analysis
+status: complete | complete_with_limits | blocked
+planning_brief_id: string
+actuals_snapshot_id: string
+comparison_basis: string
+headline_results:
+  - metric: string
+    actual: number | null
+    baseline: number | null
+    variance: number | null
+    variance_pct: number | null
+drivers:
+  - rank: integer
+    name: string
+    type: volume | rate | efficiency | mix | coverage | external | unknown
+    controllable: boolean
+    affected_metrics: []
+    quantified_contribution: number | null
+    evidence: []
+    confidence: high | medium | low
+bridges:
+  - metric: string
+    total_change: number
+    explained_change: number
+    residual: number
+    method: string
+hypotheses_to_test: []
+data_limits: []
+```
+
+The bridge is invalid if its contributions plus residual do not reconcile to total change within the stated rounding tolerance.

package/skills/fpa-apply-core-rules/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: fpa-apply-core-rules
+description: Apply the shared period, source-grain, metric, quality, approval, and artifact rules for this project's FP&A and UA workflows. Use for any FP&A planning, actuals diagnosis, driver analysis, strategy simulation, recommendation, review, approved forecast, execution, or next-cycle variance review.
+---
+
+# FP&A Core Rules
+
+Use this skill together with the phase-specific FP&A skill. It is the common contract, not a complete workflow by itself.
+
+## Required procedure
+
+1. Read [core-rules.md](references/core-rules.md) before calculating or judging anything.
+2. Identify the workflow phase and consume only artifacts that precede it.
+3. Bind the requested business period to exact start and end timestamps, timezone, currency, App, Store, and Channel scope.
+4. Check that every source grain can support the requested period. Never manufacture finer-grained results by prorating coarse facts.
+5. Separate observed facts, assumptions, calculations, judgments, and approvals in the output.
+6. Preserve lineage: record `data_as_of`, source versions, assumption version, model version, and upstream artifact IDs when available.
+7. Fail closed when required data, maturity, approval, or execution authority is missing.
+
+## Non-negotiable boundaries
+
+- Use “周期” as the general planning unit; do not silently assume a month.
+- Treat the mart datasets (Supabase via the `fpa_*` tools, or the local Mart files fallback) as Actuals, not as a budget, forecast, scenario, or approval ledger.
+- Route every calculation through deterministic code: `fpa_query`/`fpa_cohort`/`fpa_compare` for aggregation and `fpa_calc` for ad-hoc formulas. Never perform arithmetic in model output.
+- Aggregate additive numerators and denominators first, then recompute ratios.
+- Return `NULL` for missing, immature, or zero-denominator metrics; never convert them to zero.
+- Keep pre-approval scenario simulation separate from the official post-approval forecast.
+- A recommendation agent cannot approve its own proposal. Human approval is external and explicit.
+- Do not continuously monitor execution. Review only when the next cycle's data snapshot arrives.
+- Do not mutate source facts or claim that an external campaign change occurred without a real authorized adapter receipt.
+
+## Completion check
+
+Before handing off, name the produced artifact, its status, the next eligible skill, and every blocker. Do not skip an approval gate by routing directly from recommendation to official forecast or execution.

package/skills/fpa-apply-core-rules/references/core-rules.md

@@ -0,0 +1,96 @@
+# Shared FP&A contract
+
+## 1. Workflow and artifacts
+
+Planning workflow:
+
+`planning_brief -> actuals_snapshot + data_issue_report -> driver_analysis -> strategy_scenarios -> strategy_proposal -> strategy_review -> human strategy_approval -> approved_cycle_forecast`
+
+The planning workflow ends after the approved forecast is frozen.
+
+Execution is a separate workflow:
+
+`strategy_approval + strategy_proposal -> execution_receipt`
+
+Next-cycle review is another workflow, triggered only after new Actuals arrive:
+
+`approved_cycle_forecast + next actuals_snapshot -> cycle_review -> optional new planning_brief`
+
+Artifact ownership belongs to the workflow runtime or artifact store. An agent produces content and metadata; it must not invent a successful save, approval, or external action.
+
+## 2. Period and source grain
+
+The business period can be a week, two weeks, a month, or another explicit interval. Every run must bind:
+
+- period ID, start inclusive, end exclusive, and business timezone;
+- comparison baseline and its exact interval;
+- reporting currency;
+- App, Store, Product Group, and Channel Group scope;
+- `data_as_of` cutoff.
+
+A requested period is calculable only when its boundaries and the relevant source grain permit exact aggregation. Do not divide coarse facts into finer periods. Mark unsupported metrics unavailable or request a finer-grained source. Source grain and date coverage differ per dataset; read them from the data authority below instead of assuming them.
+
+Project data authority is supplied by the caller and is never embedded as a developer-machine absolute path. Resolve it in this order:
+
+1. The `fpa_*` data tools from the `fpa-data` extension when they are loaded and credentialed: `fpa_data_catalog` is the field catalog and live-coverage authority; `fpa_query`, `fpa_cohort`, and `fpa_compare` are the query paths.
+2. Explicit field-catalog and schema paths supplied for the run.
+3. `<project-root>/LOCAL_FPA_MART_FIELD_CATALOG.md` and `<project-root>/LOCAL_FPA_MART_SCHEMA.sql`.
+
+For file-based authorities, verify the files exist before relying on them. If no authority is available, report the missing input and return `blocked` for claims that depend on it; do not silently fall back to another project or remembered schema.
+
+## 3. Metric rules
+
+Every number must be produced by deterministic code, never by model arithmetic. Aggregation and ratios come from `fpa_query`, cohort curves from `fpa_cohort`, period deltas from `fpa_compare`, and any remaining ad-hoc formula (variance, growth, run-rate, budget split) from `fpa_calc`. If the tools are unavailable, numbers may only be copied verbatim from a verified source; a metric that would require mental math is `NULL` with a named gap.
+
+Additive measures may be summed only after App, Store, Channel, timezone, currency, attribution, and period mappings are aligned.
+
+Recompute ratios from aggregated components:
+
+```text
+CPI = SUM(spend) / NULLIF(SUM(paid_installs), 0)
+CAC = SUM(spend) / NULLIF(SUM(attributed_new_paid_users), 0)
+retention_dN = SUM(retained_users_dN) / NULLIF(SUM(cohort_size), 0)
+paid_rate_dN = SUM(new_paid_users_dN) / NULLIF(SUM(cohort_size), 0)
+observed_ltv_dN = SUM(net_proceeds_dN_amount) / NULLIF(SUM(cohort_size), 0)
+cost_per_first_open = SUM(cohort_spend_amount) / NULLIF(SUM(cohort_size), 0)
+cohort_cac_dN = SUM(cohort_spend_amount) / NULLIF(SUM(new_paid_users_dN), 0)
+observed_roas_dN = SUM(net_proceeds_dN_amount) / NULLIF(SUM(cohort_spend_amount), 0)
+```
+
+Never average precomputed CPI, CAC, retention, paid rate, LTV, or ROAS across groups.
+
+Useful planning identities, applied only when components are comparable:
+
+```text
+paid_installs = spend / CPI
+new_paid_users = paid_installs * paid_rate
+cohort_net_proceeds_dN = cohort_size * observed_ltv_dN
+observed_roas_dN = cohort_net_proceeds_dN / cohort_spend
+variance = actual - frozen_forecast
+variance_pct = variance / NULLIF(ABS(frozen_forecast), 0)
+```
+
+These are identities, not causal models. Forecasting a changed spend level requires an explicit response/elasticity assumption; historical average efficiency alone is insufficient.
+
+## 4. Data quality and maturity
+
+- Preserve the natural key `(cohort_week, app_id, store, channel_group)` for Cohort Spend joins.
+- Aggregate Spend to the natural key before joining; never duplicate monthly Spend across cohort weeks.
+- Align First Open attribution and Spend on App, Store, Channel Group, business timezone, and attribution window.
+- Treat paid-channel Spend missing or unreconciled as `NULL`; only Organic Spend is structurally zero.
+- Treat unmatured D7, D30, and D90 cohort observations as `NULL`.
+- Do not use `UNATTRIBUTED` cohorts for channel-return claims until Spend is reliably assigned.
+- Record exclusions and reconciliation gaps; do not silently impute them.
+
+## 5. Modeling and governance
+
+- Show base, downside, and upside ranges or another explicitly defined uncertainty method.
+- Keep assumptions separate from observed values and attach an owner/source to each material assumption.
+- Do not extrapolate beyond historical support without naming and stress-testing the extrapolation.
+- Prefer marginal return estimates for reallocation; label average ROAS as descriptive, not marginal.
+- Freeze the approved strategy, approval evidence, data snapshot, assumptions, and model version before official forecasting.
+- Compare future Actuals with that frozen forecast, never with a forecast regenerated after outcomes are known.
+
+## 6. Output status vocabulary
+
+Use one of: `complete`, `complete_with_limits`, or `blocked`. Review opinions use `support`, `support_with_conditions`, or `reject`. Only the external human approval artifact may use `approved`.

package/skills/fpa-diagnose-actuals/SKILL.md

@@ -0,0 +1,30 @@
+---
+name: fpa-diagnose-actuals
+description: Validate the FP&A mart datasets and determine which Actuals are safe for a requested business period and decision scope. Use before driver analysis, forecasting, or cycle review, especially when checking grain, completeness, maturity, reconciliation, or join safety.
+---
+
+# FP&A Actuals Diagnosis
+
+Load `$fpa-apply-core-rules` first. This is a read-only quality gate.
+
+## Procedure
+
+1. Read the frozen `planning_brief` or review-period contract.
+2. Inspect the data authority actually available: start with `fpa_data_catalog` (datasets, metric semantics, live date coverage, caveats) when the data tools are loaded, otherwise the field catalog and schema files.
+3. Check required tables, fields, natural-key uniqueness, nullability, currency, timezone, `data_as_of`, and `aggregation_version`.
+4. Test whether the source grain exactly supports the requested period. Never prorate monthly facts into weekly or two-week Actuals.
+5. Check coverage and reconciliation by App, Store, Channel Group, and period.
+6. Check identity-dependent fields and D7/D30/D90 cohort maturity.
+7. Produce both `actuals_snapshot` eligibility metadata and `data_issue_report` using [artifact-contract.md](references/artifact-contract.md).
+
+## Classification
+
+- `usable`: safe for the stated metric and scope.
+- `usable_with_limits`: safe only after named exclusions or for a narrower claim.
+- `unusable`: missing, incompatible, duplicated, unreconciled, or immature.
+
+Do not “repair” a failed metric with undocumented imputation. A quality issue may narrow downstream analysis without blocking every other metric.
+
+## Handoff
+
+Pass eligible facts and explicit exclusions to `$fpa-analyze-drivers`. If no metric supporting the primary objective remains usable, return `blocked`.

package/skills/fpa-diagnose-actuals/references/artifact-contract.md

@@ -0,0 +1,38 @@
+# Actuals diagnosis contracts
+
+`actuals_snapshot` records the query boundary and eligible facts; it is not a copied ledger.
+
+```yaml
+artifact_type: actuals_snapshot
+status: complete | complete_with_limits | blocked
+planning_brief_id: string
+period: {start_inclusive: timestamp, end_exclusive: timestamp, timezone: string}
+data_as_of: timestamp
+sources:
+  - table: string
+    grain: string
+    aggregation_version: string
+    query_or_snapshot_id: string
+eligibility:
+  - metric: string
+    scope: string
+    classification: usable | usable_with_limits | unusable
+    reason: string
+excluded_slices: []
+```
+
+```yaml
+artifact_type: data_issue_report
+status: complete | complete_with_limits | blocked
+checks:
+  - check: string
+    result: pass | warn | fail
+    affected_metrics: []
+    affected_scope: []
+    evidence: string
+    remediation: string
+blocking_issues: []
+non_blocking_limits: []
+```
+
+Minimum checks: period/grain compatibility, natural-key uniqueness, missing periods, currency consistency, negative/impossible counts, Spend reconciliation, identity coverage, cohort maturity, `data_as_of`, and version presence.

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

@@ -0,0 +1,40 @@
+---
+name: fpa-execute-approved-strategy
+description: Execute a human-approved UA strategy through a declared external adapter with strict authorization, version, scope, dry-run, idempotency, and receipt checks. Use only for a separately authorized execution workflow; otherwise fail closed and make no external changes.
+disable-model-invocation: true
+---
+
+# FP&A Controlled Strategy Execution
+
+Load `$fpa-apply-core-rules` first. This skill is intentionally fail-closed and is not part of the planning workflow.
+
+## Mandatory entry gate
+
+Require all of the following before any external mutation:
+
+- explicit human `strategy_approval` for the exact `strategy_proposal` version;
+- exact target accounts, App, Store, Channel, budget, period, and permitted operations;
+- a named, currently available execution adapter/tool and its authentication context;
+- a user-authorized execution request, not merely an approval to forecast;
+- an idempotency key or adapter-supported equivalent;
+- a successful read-only preflight and, where supported, dry-run/preview.
+
+If any requirement is missing, return `blocked` and make no external call. Never simulate an adapter or fabricate a receipt.
+
+## Procedure
+
+1. Reconcile the approved allocation with requested external targets.
+2. Read current external state and detect stale assumptions, duplicate execution, or conflicting changes.
+3. Generate the exact proposed mutation set and validate limits.
+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. Write `execution_receipt` using [artifact-contract.md](references/artifact-contract.md).
+
+## Stop conditions
+
+Stop before or during execution on version mismatch, target ambiguity, budget mismatch, authentication failure, stale external state, partial failure, or unexpected adapter behavior. Do not broaden scope to “finish” the task.
+
+## Boundary
+
+Execution ends after reconciliation and receipt. Do not continuously monitor performance. Performance review begins only when the next cycle's Actuals arrive and uses `$fpa-review-cycle`.

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

@@ -0,0 +1,29 @@
+# `execution_receipt` contract
+
+```yaml
+artifact_type: execution_receipt
+status: complete | complete_with_limits | blocked
+strategy_version: string
+human_approval_id: string
+execution_request_id: string
+adapter: string
+target_accounts: []
+idempotency_key: string
+preflight:
+  result: pass | fail
+  observed_state_fingerprint: string
+dry_run:
+  supported: boolean
+  result: pass | fail | not_supported
+requested_mutations: []
+applied_mutations: []
+failed_mutations: []
+reconciliation:
+  result: pass | partial | fail
+  resulting_state_fingerprint: string | null
+external_receipt_ids: []
+executed_at: timestamp | null
+blockers: []
+```
+
+Only adapter responses may populate `applied_mutations`, external receipt IDs, and resulting-state evidence. A blocked receipt must have no applied mutations.

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

@@ -0,0 +1,39 @@
+---
+name: fpa-forecast-approved-strategy
+description: Produce and freeze the official operating forecast for the next business period from one explicitly human-approved UA strategy. Use after independent review and human approval; do not use for candidate scenario trial calculations.
+---
+
+# FP&A Approved Strategy Forecast
+
+Load `$fpa-apply-core-rules` first. This is the final stage of the planning workflow.
+
+## Entry gate
+
+Require all of the following:
+
+- the exact `strategy_proposal` version;
+- a completed independent `strategy_review` supporting that version;
+- explicit human `strategy_approval` identifying the same version and any conditions;
+- the eligible data snapshot, assumptions, and model version used for forecasting.
+
+If approval evidence is absent, ambiguous, expired, conditional but unmet, or refers to another strategy version, return `blocked` without forecasting.
+
+## Procedure
+
+1. Verify approval and artifact lineage.
+2. Lock the approved allocation 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. Freeze the forecast inputs and write `approved_cycle_forecast` using [artifact-contract.md](references/artifact-contract.md).
+
+## Boundaries
+
+- Do not optimize, revise, or substitute the approved strategy while forecasting.
+- A required change invalidates the current approval and routes back to recommendation and review.
+- Unsupported KPIs remain `NULL` with a reason.
+- Do not execute the strategy and do not start continuous monitoring.
+
+## 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`.

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

@@ -0,0 +1,36 @@
+# `approved_cycle_forecast` contract
+
+```yaml
+artifact_type: approved_cycle_forecast
+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
+approved_allocation: []
+forecast_by_slice:
+  - app_id: string
+    store: string
+    channel_group: string
+    metrics:
+      metric_name:
+        downside: number | null
+        base: number | null
+        upside: number | null
+        unit: string
+        window: string
+consolidated_forecast: {}
+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.

package/skills/fpa-plan-cycle/SKILL.md

@@ -0,0 +1,29 @@
+---
+name: fpa-plan-cycle
+description: Convert a business objective into a bounded FP&A and UA planning brief for one configurable business period. Use when starting a planning cycle, changing targets or constraints, or deciding what the downstream analysis and recommendation must optimize.
+---
+
+# FP&A Cycle Planning
+
+Load `$fpa-apply-core-rules` first. Produce the goal contract that every downstream agent uses.
+
+## Procedure
+
+1. Read the request and available prior `cycle_review` artifact.
+2. Define the period with exact dates and timezone; never infer “monthly”.
+3. State the decision to be made, controllable UA levers, and non-controllable assumptions.
+4. Establish baseline, target metrics, priorities, budget ceiling/floor, and risk guardrails.
+5. Define the dimensions where a decision is allowed: App, Store, Channel Group, and any supported sub-dimension.
+6. Check metric feasibility against current source grain and live coverage (`fpa_data_catalog` when the data tools are loaded). Separate supported targets from desired-but-unmeasurable targets.
+7. Write `planning_brief` using [artifact-contract.md](references/artifact-contract.md).
+
+## Guardrails
+
+- A target needs a baseline, direction, threshold/range, and measurement window.
+- Resolve conflicting targets by documenting priority or a trade-off rule.
+- Do not recommend a strategy, simulate results, or approve anything in this phase.
+- If exact period, primary objective, or hard budget boundary is absent and materially changes the decision, return `blocked` with the missing decision.
+
+## Handoff
+
+The next skill is `$fpa-diagnose-actuals`. Pass only the frozen `planning_brief`, not an informal summary.

package/skills/fpa-plan-cycle/references/artifact-contract.md

@@ -0,0 +1,41 @@
+# `planning_brief` contract
+
+Required fields:
+
+```yaml
+artifact_type: planning_brief
+status: complete | complete_with_limits | blocked
+period:
+  id: string
+  start_inclusive: timestamp
+  end_exclusive: timestamp
+  timezone: IANA timezone
+comparison_period: same shape
+reporting_currency: ISO-4217 code
+scope:
+  app_ids: []
+  stores: []
+  channel_groups: []
+decision_question: string
+primary_objective:
+  metric: string
+  baseline: number | null
+  target: number | range
+  direction: maximize | minimize | hold | range
+secondary_objectives: []
+controllable_levers: []
+constraints:
+  budget_floor: number | null
+  budget_ceiling: number | null
+  allocation_limits: []
+  business_constraints: []
+risk_guardrails: []
+measurement_feasibility:
+  supported: []
+  unsupported: []
+assumptions: []
+open_decisions: []
+created_at: timestamp
+```
+
+Every unsupported metric must name the grain, field, or maturity gap causing the limitation.

package/skills/fpa-recommend-strategy/SKILL.md

@@ -0,0 +1,29 @@
+---
+name: fpa-recommend-strategy
+description: Select and express an auditable UA strategy recommendation from validated objectives, Actuals, driver evidence, and simulated scenarios. Use after scenario simulation to create a proposal for independent review and human approval.
+---
+
+# FP&A Strategy Recommendation
+
+Load `$fpa-apply-core-rules` first. Recommend one plan while keeping alternatives and uncertainty visible.
+
+## Procedure
+
+1. Consume `planning_brief`, `driver_analysis`, and `strategy_scenarios`.
+2. Remove scenarios that breach hard constraints.
+3. Rank remaining scenarios using the objective priorities and declared trade-off rule.
+4. Select one recommendation and specify exact allocation, changes from baseline, expected ranges, assumptions, and risks.
+5. State why rejected alternatives were not chosen.
+6. Define next-cycle evaluation thresholds; do not create a real-time monitoring obligation.
+7. Write `strategy_proposal` using [artifact-contract.md](references/artifact-contract.md).
+
+## Boundaries
+
+- Do not add a new scenario whose results were never simulated.
+- Do not hide downside results or convert uncertainty into a single guaranteed number.
+- Do not approve, execute, or call the recommendation an official forecast.
+- If no scenario satisfies hard constraints, return `blocked` or recommend reopening planning assumptions.
+
+## Handoff
+
+Send the complete proposal and its cited upstream artifacts to `$fpa-review-strategy`. The recommending agent must not perform that independent review.

package/skills/fpa-recommend-strategy/references/artifact-contract.md

@@ -0,0 +1,30 @@
+# `strategy_proposal` contract
+
+```yaml
+artifact_type: strategy_proposal
+status: complete | complete_with_limits | blocked
+strategy_version: string
+planning_brief_id: string
+strategy_scenarios_id: string
+recommended_scenario_id: string
+target_period: {start_inclusive: timestamp, end_exclusive: timestamp, timezone: string}
+allocation:
+  - app_id: string
+    store: string
+    channel_group: string
+    spend: number
+    change_from_baseline: number
+expected_outcomes:
+  downside: {}
+  base: {}
+  upside: {}
+decision_rationale: []
+rejected_alternatives: []
+material_assumptions: []
+risks: []
+hard_constraints: []
+next_cycle_evaluation_thresholds: []
+required_human_decisions: []
+```
+
+The total allocation must reconcile to the proposed total budget, and every allocation row must map to a simulated scenario row.

package/skills/fpa-review-cycle/SKILL.md

@@ -0,0 +1,32 @@
+---
+name: fpa-review-cycle
+description: Compare newly arrived Actuals with the previously frozen approved forecast, explain variances, evaluate assumptions, and feed learning into the next planning cycle. Use only after the completed business period's data snapshot has arrived and passed diagnosis.
+---
+
+# FP&A Cycle Review
+
+Load `$fpa-apply-core-rules` first. This workflow is event-driven by a new period data snapshot, not by continuous monitoring.
+
+## Entry gate
+
+Require the immutable `approved_cycle_forecast` and a newly diagnosed `actuals_snapshot` covering the same period and comparable scope. If data is incomplete or source grain is incompatible, narrow the review or return `blocked`.
+
+## Procedure
+
+1. Verify that forecast and Actuals refer to the same period, timezone, currency, App, Store, Channel, and metric window.
+2. Compare against the frozen forecast; never regenerate it using known outcomes.
+3. Calculate absolute and percentage variance from additive components: Actuals via `fpa_query`/`fpa_compare`, forecast-vs-actual arithmetic via `fpa_calc`.
+4. Attribute variance to execution difference, volume, efficiency, conversion, retention/LTV, mix, external factors, model error, and data effects where evidence supports it.
+5. Score each material assumption as supported, weakened, rejected, or unresolved.
+6. Capture reusable learning and proposed changes for the next planning brief.
+7. Write `cycle_review` using [artifact-contract.md](references/artifact-contract.md).
+
+## Boundaries
+
+- Do not revise historical forecast values.
+- Do not equate an execution receipt with proof that the strategy caused the outcome.
+- Do not automatically start or approve the next strategy; emit recommended planning inputs only.
+
+## Handoff
+
+If another cycle is desired, pass `cycle_review` to `$fpa-plan-cycle` as prior-cycle evidence.

package/skills/fpa-review-cycle/references/artifact-contract.md

@@ -0,0 +1,30 @@
+# `cycle_review` contract
+
+```yaml
+artifact_type: cycle_review
+status: complete | complete_with_limits | blocked
+forecast_version: string
+actuals_snapshot_id: string
+review_period: {start_inclusive: timestamp, end_exclusive: timestamp, timezone: string}
+comparability_checks: []
+variance_summary:
+  - metric: string
+    forecast: number | null
+    actual: number | null
+    variance: number | null
+    variance_pct: number | null
+variance_drivers:
+  - category: execution | volume | efficiency | conversion | retention_ltv | mix | external | model | data | unknown
+    contribution: number | null
+    evidence: []
+    confidence: high | medium | low
+assumption_evaluation:
+  - assumption: string
+    outcome: supported | weakened | rejected | unresolved
+    evidence: string
+lessons: []
+next_cycle_inputs: []
+unresolved_questions: []
+```
+
+Use `variance = actual - frozen_forecast` and `variance_pct = variance / NULLIF(ABS(frozen_forecast), 0)`. Keep percentage variance `NULL` when the frozen forecast is zero.

package/skills/fpa-review-strategy/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: fpa-review-strategy
+description: Independently challenge a proposed UA strategy, its evidence, calculations, assumptions, feasibility, and governance before human approval. Use only with an independently authored strategy proposal; never use to self-approve a recommendation.
+---
+
+# FP&A Independent Strategy Review
+
+Load `$fpa-apply-core-rules` first. The reviewer must be independent from the recommendation agent and must receive the full evidence chain.
+
+## Procedure
+
+1. Verify artifact lineage from `planning_brief` through `strategy_proposal`.
+2. Recalculate material totals and ratios from cited components.
+3. Test source-grain compatibility, scenario-to-proposal traceability, model support, and uncertainty coverage.
+4. Challenge hidden assumptions, extrapolation, concentration risk, feasibility, and downside exposure.
+5. Check that the proposal satisfies hard constraints and contains no implied execution authority.
+6. Record findings by severity and issue one opinion: `support`, `support_with_conditions`, or `reject`.
+7. Write `strategy_review` using [artifact-contract.md](references/artifact-contract.md).
+
+## Authority boundary
+
+- `support` is a reviewer opinion, not approval.
+- Only an external human approval artifact can authorize the official forecast or execution.
+- Do not rewrite the proposal in place. Required changes create a new strategy version and a new review.
+
+## Handoff
+
+If the reviewer supports the proposal, send both artifacts to the human approval gate. After explicit approval, `$fpa-forecast-approved-strategy` may run.

package/skills/fpa-review-strategy/references/artifact-contract.md

@@ -0,0 +1,25 @@
+# `strategy_review` contract
+
+```yaml
+artifact_type: strategy_review
+status: complete | complete_with_limits | blocked
+reviewed_strategy_version: string
+reviewer_identity: string
+independence_confirmed: boolean
+opinion: support | support_with_conditions | reject
+recalculation_checks:
+  - check: string
+    result: pass | warn | fail
+    evidence: string
+findings:
+  - severity: critical | high | medium | low
+    category: data | math | model | feasibility | risk | governance
+    finding: string
+    evidence: string
+    required_action: string
+conditions_for_human_approval: []
+residual_risks: []
+reviewed_at: timestamp
+```
+
+Set `independence_confirmed: false` and `status: blocked` if the reviewer also authored the proposal. Any unresolved critical finding requires `reject`.