@viccydev/pi-fpa 0.8.1 → 0.9.1

package/graphs/fpa-forecast-freeze.json

@@ -1,6 +1,6 @@
 {
-  "description": "FP&A 正式预测冻结：消费已审核策略交接与主 Agent 已提交的精确 strategy_decision，生成、合成并冻结 approved_cycle_forecast；Graph 不请求审批、不发布仪表盘。",
-  "maxSteps": 10,
+  "description": "FP&A 正式预测冻结：消费已审核策略交接与主 Agent 已提交的精确 strategy_decision，生成预测决策计划并通过确定性 finalize module 冻结 approved_cycle_forecast；Graph 不请求审批、不发布仪表盘。",
+  "maxSteps": 6,
   "mutationPolicy": "mutating",
   "name": "fpa-forecast-freeze",
   "nodes": [
@@ -11,29 +11,29 @@
       "next": "route_confirmed_strategy",
       "outputKey": "confirmed_strategy",
       "parseJson": true,
-      "prompt": "操作备注：{{goal}}\n\n读取 artifacts/reviewed_strategy_handoff.json、其中绑定的 strategy_proposal 与 strategy_review，以及操作备注明确给出的 strategy_decision path。必须核验 handoff status=ready；scope_id/cycle_id/forecast_role 与 Graph context 一致；proposal、review、handoff 的 strategy_version 一致；decision.kind=fpa.strategy.decision、decision=confirm；decision 的 strategy_version、handoff_fingerprint、decision_fingerprint 与操作备注和当前 handoff 精确一致。任一不一致即 blocked。不得请求或记录第二次审批，不得调用任何 fpa_dashboard_* 工具。\n\n只输出 JSON：{\"status\":\"ready|blocked\",\"strategy_version\":\"...\",\"strategy_decision_path\":\"...\",\"strategy_decision_fingerprint\":\"...\",\"review_conditions\":[],\"blockers\":[]}",
+      "prompt": "操作备注：{{goal}}\n\n读取 artifacts/reviewed_strategy_handoff.json、其中绑定的 strategy_proposal 与 strategy_review，以及操作备注明确给出的 strategy_decision path。必须核验 handoff status=ready；scope_id/cycle_id 与 Graph context 一致；proposal、review、handoff 的 strategy_version 一致；decision.kind=fpa.strategy.decision、decision=confirm；decision 的 strategy_version、handoff_fingerprint、decision_fingerprint 与操作备注和当前 handoff 精确一致。handoff 中的旧业务 forecast_role 仅作为兼容元数据，不参与 ledger role 判断；最终角色由冻结 module 按目标周期确定。任一身份或审批不一致即 blocked。不得请求或记录第二次审批，不得调用任何 fpa_dashboard_* 工具。\n\n只输出 JSON：{\"status\":\"ready|blocked\",\"strategy_version\":\"...\",\"strategy_decision_path\":\"...\",\"strategy_decision_fingerprint\":\"...\",\"review_conditions\":[],\"blockers\":[]}",
       "skills": ["fpa-apply-core-rules"],
-      "systemPrompt": "你是 FP&A 已确认策略核验 Agent。只读核验主 Agent 已提交的不可变决策，不批准、不预测、不发布仪表盘。权威上下文为 scope_id={{context.scope_id}}、cycle_id={{context.cycle_id}}、forecast_role={{context.forecast_role}}。",
+      "systemPrompt": "你是 FP&A 已确认策略核验 Agent。只读核验主 Agent 已提交的不可变决策，不批准、不预测、不发布仪表盘。权威上下文为 scope_id={{context.scope_id}}、cycle_id={{context.cycle_id}}。",
       "tools": ["read"],
       "type": "subagent"
     },
     {
       "cases": [
         { "equals": "ready", "label": "确认有效", "to": "draft_forecast" },
-        { "equals": "blocked", "label": "确认无效", "to": "report_blocked" }
+        { "equals": "blocked", "label": "确认无效", "to": "report_strategy_blocked" }
       ],
-      "default": { "label": "其他结果", "to": "report_blocked" },
+      "default": { "label": "其他结果", "to": "report_strategy_blocked" },
       "id": "route_confirmed_strategy",
       "label": "判断是否可预测",
       "path": "data.confirmed_strategy.status",
       "type": "router"
     },
     {
-      "id": "report_blocked",
-      "label": "报告预测阻断",
+      "id": "report_strategy_blocked",
+      "label": "报告策略核验阻断",
       "outputKey": "forecast_blocked",
       "parseJson": true,
-      "prompt": "核验结果：{{data.confirmed_strategy}}\n\n只输出 JSON：{\"kind\":\"fpa.graph-handoff\",\"status\":\"blocked\",\"graph\":\"fpa-forecast-freeze\",\"blockers\":[],\"required_action\":\"由原主会话提交与当前 handoff 精确匹配的策略确认\"}",
+      "prompt": "策略核验结果：{{data.confirmed_strategy}}\n\n汇总实际阻断原因。只输出 JSON：{\"kind\":\"fpa.graph-handoff\",\"status\":\"blocked\",\"graph\":\"fpa-forecast-freeze\",\"blockers\":[],\"required_action\":\"需要主会话处理的治理或策略动作\"}",
       "systemPrompt": "用中文简洁报告预测阻断，只输出约定 JSON。",
       "type": "prompt"
     },
@@ -41,55 +41,51 @@
       "agentName": "draft_forecast",
       "id": "draft_forecast",
       "label": "正式预测决策计划",
-      "next": "compose_forecast",
+      "next": "route_draft_forecast",
       "outputKey": "draft_forecast",
-      "prompt": "操作备注：{{goal}}\n\n已核验策略与决策：{{data.confirmed_strategy}}\n\n读取 reviewed_strategy_handoff、strategy_proposal、strategy_review 和精确 strategy_decision，按 fpa-forecast-approved-strategy 写 artifacts/forecast_plan.json。不得重新优化策略；业务分配、范围、假设或审核条件需变化时必须 blocked 并回到策略规划。只写 allocation 与每个切片的 ROAS assumptions；revenue、汇总、单位和 frozen_at 由下游 fpa_forecast_compose 推导。切片键必须使用 ua_spend 的 app_code/platform/media_source 合法值。不得调用任何 fpa_dashboard_* 工具。",
+      "parseJson": true,
+      "prompt": "操作备注：{{goal}}\n\n已核验策略与决策：{{data.confirmed_strategy}}\n\n读取 reviewed_strategy_handoff、strategy_proposal、strategy_review 和精确 strategy_decision，按 fpa-forecast-approved-strategy 写 artifacts/forecast_plan.json。不得重新优化策略；业务分配、范围、假设或审核条件需变化时不得写入计划，必须返回 blocked 并回到策略规划。只写 allocation 与每个切片的 ROAS assumptions；revenue、汇总、单位、frozen_at、forecast_role、数据覆盖状态和修复提醒全部由下游 fpa_forecast_finalize 确定。优先使用 ua_spend 的 app_code/platform/media_source 真实组合；若已确认分配中的部分切片与当前上游映射不一致，不得擅自删除、置零、重分配或伪造映射，保留原切片交给 finalize 自动产出 complete_with_limits、覆盖率和数据修复项。不得调用任何 fpa_dashboard_* 工具。成功写入后只输出 JSON：{\"status\":\"ready\",\"plan_path\":\"artifacts/forecast_plan.json\",\"blockers\":[]}；需要治理处理时只输出 JSON：{\"status\":\"blocked\",\"plan_path\":null,\"blockers\":[]}。",
       "skills": ["fpa-apply-core-rules", "fpa-forecast-approved-strategy"],
       "systemPrompt": "你是 FP&A 正式预测 Agent。只按已确认策略写预测计划，不请求审批、不发布仪表盘、不手算派生值。",
       "tools": ["read", "write", "fpa_calc"],
       "type": "subagent"
     },
     {
-      "args": { "plan_path": "artifacts/forecast_plan.json" },
-      "failure": { "maxAttempts": 2, "onError": "repair_forecast_plan" },
-      "id": "compose_forecast",
-      "label": "合成正式预测",
-      "next": "commit_forecast",
-      "outputKey": "compose_forecast",
-      "tool": "fpa_forecast_compose",
-      "type": "tool"
+      "cases": [
+        { "equals": "ready", "label": "计划已写入", "to": "finalize_forecast" },
+        { "equals": "blocked", "label": "需要治理处理", "to": "report_plan_blocked" }
+      ],
+      "default": { "label": "其他结果", "to": "report_plan_blocked" },
+      "id": "route_draft_forecast",
+      "label": "判断预测计划是否可冻结",
+      "path": "data.draft_forecast.status",
+      "type": "router"
     },
     {
-      "agentName": "repair_forecast_plan",
-      "id": "repair_forecast_plan",
-      "label": "定点修正预测计划",
-      "next": "compose_forecast",
-      "outputKey": "repair_forecast_plan",
-      "prompt": "合成失败：{{data.__graphError}}\n\n读取 artifacts/forecast_plan.json、planning_brief 和 reviewed_strategy_handoff，只定点修正格式、合法切片键或 forecast plan 契约问题。不得改变已确认策略的业务分配、范围、假设或条件；若错误要求此类变化，报告 blocked。不得调用任何 fpa_dashboard_* 工具。",
-      "skills": ["fpa-forecast-approved-strategy"],
-      "systemPrompt": "你是预测计划修复 Agent，只按确定性合成报错做最小修正。",
-      "tools": ["read", "write", "edit"],
-      "type": "subagent"
+      "id": "report_plan_blocked",
+      "label": "报告预测计划阻断",
+      "outputKey": "forecast_blocked",
+      "parseJson": true,
+      "prompt": "预测计划结果：{{data.draft_forecast}}\n\n汇总实际阻断原因。只输出 JSON：{\"kind\":\"fpa.graph-handoff\",\"status\":\"blocked\",\"graph\":\"fpa-forecast-freeze\",\"blockers\":[],\"required_action\":\"需要主会话处理的治理或策略动作\"}",
+      "systemPrompt": "用中文简洁报告预测阻断，只输出约定 JSON。",
+      "type": "prompt"
     },
     {
       "args": {
-        "artifact": "{{data.compose_forecast.details.artifact}}",
-        "context": {
-          "cycle_id": "{{context.cycle_id}}",
-          "forecast_role": "{{context.forecast_role}}",
-          "scope_id": "{{context.scope_id}}"
-        }
+        "plan_path": "artifacts/forecast_plan.json",
+        "scope_id": "{{context.scope_id}}",
+        "cycle_id": "{{context.cycle_id}}"
       },
-      "id": "commit_forecast",
+      "id": "finalize_forecast",
       "label": "冻结正式预测",
       "mutates": true,
-      "outputKey": "commit_forecast",
-      "tool": "fpa_artifact_commit",
+      "outputKey": "finalize_forecast",
+      "tool": "fpa_forecast_finalize",
       "type": "tool"
     }
   ],
   "schemaVersion": 1,
   "start": "load_confirmed_strategy",
   "transitionLabels": { "default": "其他情况", "error": "失败", "next": "继续" },
-  "version": "2.1.0"
+  "version": "3.0.0"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@viccydev/pi-fpa",
-  "version": "0.8.1",
+  "version": "0.9.1",
   "type": "module",
   "description": "Full-cycle FP&A planning, strategy, forecast, and review prompts, skills, and data tools for Pi",
   "license": "UNLICENSED",
@@ -31,9 +31,9 @@
 		"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/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": "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",
-		"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/artifact-handoff.test.mjs tests/forecast-compose.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",
+    "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/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",
     "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"

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

@@ -26,8 +26,10 @@ writing artifacts. It applies only when the current agent exposes both
    | Exact Forecast and Execution refs plus newly arrived comparable Actuals | `fpa-cycle-review` |
 
 3. Call `graph_run` with the user's complete goal. Every `context` value must
-   be a string; provide exact `scope_id`, `cycle_id`, and `forecast_role`, and
-   keep structured planning details in `goal`. The parent agent must not
+   be a string. Provide exact `scope_id` and `cycle_id`; planning additionally
+   requires its business `forecast_role`, while forecast freeze derives the
+   ledger role from the target period and freeze time. Keep structured planning
+   details in `goal`. The parent agent must not
    reproduce Graph nodes or pre-run their `fpa_*` calls. After the combined
    planning Graph succeeds, the main Agent publishes `period-review` and then
    `next-strategy` with their matching `fpa_dashboard_publish_*` tools. Graph

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

@@ -24,8 +24,11 @@ ready handoff plus the exact confirmed strategy-decision fingerprint:
 
 `reviewed_strategy_handoff + strategy_decision -> forecast_plan -> approved_cycle_forecast`
 
-The main Agent owns approval recording; the forecast Graph owns deterministic
-composition and artifact freezing. A rejected approval reruns
+The main Agent owns approval recording; the forecast Graph writes the approved
+plan and delegates deterministic composition, lifecycle-role derivation, and
+artifact freezing to `fpa_forecast_finalize`. A business role recorded in an
+older handoff is lineage metadata, not a storage role that the model must
+translate. A rejected approval reruns
 `fpa-strategy-planning` with the exact feedback and produces a new version
 rather than modifying the reviewed proposal in place.
 

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

@@ -31,6 +31,8 @@ checks:
     affected_scope: []
     evidence: string
     remediation: string
+    owner_role: data_steward
+    disposition: excluded_from_calculation | warning_only | blocking
 blocking_issues: []
 non_blocking_limits: []
 ```

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

@@ -36,34 +36,28 @@ from it, return `blocked`; never reconstruct or substitute the handoff.
 4. Provide downside, base, and upside values for each supported KPI.
 5. Reconcile allocation totals, formulas, and cross-metric identities.
 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` only when it is frozen no later than its target
-   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
+7. Call `fpa_forecast_finalize` with the plan path and the exact `scope_id` and
+   `cycle_id`. Do not choose or pass `forecast_role`: the tool derives
+   `next_plan` before period start, `eac` during the period, and `backtest`
+   after period end, then composes and commits the artifact atomically. A
+   historical rerun is immutable evidence, not an operating plan, and must not
    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.
+   user explicitly requests a backtest dashboard publication.
 
 ## 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
+all follow from those, and `fpa_forecast_finalize` 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.
+output limit and leaves a turn that reads finished but committed nothing. Stop
+after writing the plan; the finalizer owns composition and commit. Never claim
+a fingerprint you were not handed.
 
 ## Status and the publish gate
 
@@ -84,16 +78,28 @@ tool. `complete_with_limits` remains publishable when its limitations are
 explicit, while `blocked` is not. Do not hide a real defect to get through the
 gate.
 
+Upstream identity or coverage defects are non-blocking data limits. Preserve
+the full approved allocation, leave affected revenue and ROAS values `NULL`,
+and let `fpa_forecast_finalize` emit `data_quality`, a coverage-labelled partial
+`conclusion`, and actionable repair items. Never delete a bad slice, turn it
+into zero spend, or renormalize the remaining allocation. The affected slice
+remains ineligible for Actuals comparison and execution until its mapping is
+fixed. Approval mismatch, duplicate or negative allocation, budget mismatch,
+invalid period/currency/role, and unauthorized execution remain blocking
+governance failures.
+
 ## 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.
+- A partial conclusion must say it covers only calculable slices and must show
+  `calculable_spend_pct`; it must never be labelled portfolio ROAS.
 - Do not execute the strategy and do not start continuous monitoring.
 
 ## Completion
 
-The forecast-freeze workflow ends only after `fpa_artifact_commit` returns
+The forecast-freeze workflow ends only after `fpa_forecast_finalize` returns
 `status: committed`, an `immutable_fingerprint`, and (for assigned artifacts) a
 `dashboard_handoff`. Commit freezes the business artifact but does not enqueue
 or publish dashboard work. The calling main Agent owns that explicit handoff.

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

@@ -41,6 +41,28 @@ calibration_policy:
   policy_version: string
 unsupported_metrics: []
 reconciliation_checks: []
+data_quality:
+  status: complete | partial | unavailable
+  planned_spend: number
+  calculable_spend: number
+  calculable_spend_pct: number  # 0..1; never renormalized
+  excluded_spend: number
+  issue_count: number
+  issues:
+    - issue_id: string
+      code: slice_key_not_in_actuals
+      severity: warning
+      slice: {app_id: string, store: string, channel_group: string}
+      affected_metrics: [actuals_comparison, revenue, roas, execution]
+      disposition: excluded_from_calculation
+      evidence: []
+      remediation: string
+      owner_role: data_steward
+conclusion:
+  status: available | available_with_limits | unavailable
+  scope: portfolio | calculable_slices | none
+  metrics: {spend: scenario_metric, revenue: scenario_metric, roas: scenario_metric}
+  warning: string | null
 frozen_at: timestamp
 ```
 
@@ -51,9 +73,10 @@ Do not include `immutable_fingerprint` in the tool input; a draft that carries o
 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.
+from those by arithmetic. Write the plan and let `fpa_forecast_finalize` derive
+the rest, choose the lifecycle role from time, and commit it — it makes the
+identities the commit checks true by construction instead of true if you typed
+them correctly.
 
 ```yaml
 # artifacts/forecast_plan.json
@@ -89,15 +112,20 @@ Then:
 
 ```
 write  artifacts/forecast_plan.json
-fpa_forecast_compose  { "plan_path": "artifacts/forecast_plan.json" }
-fpa_artifact_commit   { "artifact": <the artifact compose returned> }
+fpa_forecast_finalize  { "plan_path": "artifacts/forecast_plan.json", "scope_id": "<exact scope>", "cycle_id": "<exact cycle>" }
 ```
 
+The finalizer derives `next_plan` before the target period, `eac` during it,
+and `backtest` after it. The model does not pass or translate `forecast_role`.
+
 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.
+- **Slice keys are checked as real triples.** `app_code`, `platform`, and `media_source` must occur together in `ua_spend`; validating three independent value lists is insufficient. A mismatch is isolated as a data-quality limit: approved spend remains in the allocation and consolidated spend, while affected revenue/ROAS are `NULL`. The single-placeholder App axis for a scoped-out portfolio remains permitted.
+- **Do not hide partiality.** Compose reports planned, calculable, and excluded spend. Its partial conclusion covers only calculable slices; remaining spend is never scaled to 100%, and partial ROAS is never labelled portfolio ROAS.
+- **Data quality does not weaken governance.** Missing/mismatched approval, duplicate or negative allocation, invalid period/currency/forecast role, and budget reconciliation failures still block.
+- **Describe other upstream limits actionably.** For non-identity defects, each `unsupported_metrics` item should name the affected metric/scope, evidence, remediation, and data owner. Dashboard publication keeps these items visible even when `data_quality.status` is otherwise complete.
 - **`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.
 

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

@@ -32,9 +32,12 @@ preserve every other module revision.
 3. Stop and wait for the dashboard action. The Web host sends a canonical
    decision message back to the bound original session. In that session call
    `fpa_strategy_decision_commit` with the exact `action_id`.
-4. On `confirm`, run `fpa-forecast-freeze`; after it returns an exact committed
-   forecast ref, preview then publish `next-forecast` with
-   `fpa_dashboard_publish_forecast`.
+4. On `confirm`, run `fpa-forecast-freeze`. For an operating Forecast, preview
+   then publish `next-forecast` with `fpa_dashboard_publish_forecast`. If the
+   finalizer returns `forecast_role: backtest` and a `not_applicable` dashboard
+   handoff, stop after reporting its immutable ref; do not attempt operating
+   publication unless the user explicitly requested the separate backtest
+   display path.
 5. On `request_changes`, pass the verbatim feedback back into strategy planning,
    publish the replacement `next-strategy` module, and wait for a new decision.
 
@@ -57,19 +60,21 @@ only part of this tuple or fall back to a mutable current pointer.
 This path remains only for legacy execution-evidence refreshes. It must not be
 used to replace review, strategy, or forecast modules.
 
-1. Take the exact `artifact_ref` from `fpa_artifact_commit.dashboard_handoff`.
+1. For an operating forecast, take the exact `artifact_ref` from a deferred
+   `fpa_forecast_finalize.dashboard_handoff` (or the compatible
+   `fpa_artifact_commit.dashboard_handoff` path). A backtest handoff is
+   `not_applicable` and must not be queued automatically.
 2. Call `fpa_dashboard_refresh_queue` with `action: enqueue_artifact` and that
    ref. Do not restate scope, cycle, role, or upstream refs; the package resolves
    them from the immutable ledger.
 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`, 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.
+4. A compatible legacy `fpa_artifact_commit` handoff may still return
+   `not_applicable` for a `backtest`; do not treat that as a failed artifact or
+   retry it. If the user explicitly asked to display that backtest, continue
+   through the exact backtest display path below. Otherwise report that it
+   remains in the ledger without changing the operating dashboard.
 
 ### Human-requested rebuild