@viccydev/pi-fpa 0.2.0

package/extensions/fpa-data/sql.ts

@@ -0,0 +1,412 @@
+/**
+ * Read-only SQL builder for the FP&A Supabase mart.
+ *
+ * The builder only emits SELECT statements over datasets, dimensions, and
+ * measures declared in registry.ts. Identifiers are validated against the
+ * registry and literal values are escaped, so the LLM can never inject SQL.
+ */
+
+import {
+	type DatasetDef,
+	type DerivedDef,
+	getDataset,
+} from "./registry.ts";
+
+export type TimeGrain = "day" | "week" | "month";
+export type CohortBucket = "day" | "week" | "month" | "total";
+
+export interface QuerySpec {
+	dataset: string;
+	metrics: string[];
+	dimensions?: string[];
+	timeGrain?: TimeGrain;
+	dateFrom?: string;
+	dateTo?: string;
+	filters?: Record<string, string | number | Array<string | number>>;
+	sort?: { by: string; direction?: "asc" | "desc" };
+	limit?: number;
+}
+
+export interface BuiltQuery {
+	sql: string;
+	dataset: DatasetDef;
+	measures: string[];
+	derived: DerivedDef[];
+	dimensions: string[];
+	timeGrain?: TimeGrain;
+	notes: string[];
+}
+
+export const DEFAULT_LIMIT = 200;
+export const MAX_LIMIT = 1000;
+
+const DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
+const SORT_DIRECTIONS = new Set(["asc", "desc"]);
+
+export function escapeLiteral(value: string | number): string {
+	if (typeof value === "number") {
+		if (!Number.isFinite(value)) {
+			throw new Error("Filter values must be finite numbers or strings.");
+		}
+		return String(value);
+	}
+	return `'${value.replace(/'/g, "''")}'`;
+}
+
+export function assertDate(value: string, label: string): string {
+	if (!DATE_RE.test(value)) {
+		throw new Error(`${label} must be an ISO date (YYYY-MM-DD), got "${value}".`);
+	}
+	return value;
+}
+
+export function assertReadOnly(sql: string): string {
+	if (!/^\s*(select|with)\b/i.test(sql)) {
+		throw new Error("Internal error: generated SQL is not a SELECT statement.");
+	}
+	return sql;
+}
+
+function normalizeFilterValues(
+	value: string | number | Array<string | number>,
+): Array<string | number> {
+	const values = Array.isArray(value) ? value : [value];
+	if (values.length === 0) {
+		throw new Error("Filter arrays must contain at least one value.");
+	}
+	return values;
+}
+
+interface ResolvedDataset {
+	dataset: DatasetDef;
+	measures: string[];
+	derived: DerivedDef[];
+	notes: string[];
+}
+
+function resolveMetrics(dataset: DatasetDef, metrics: string[], useEventName: boolean): ResolvedDataset {
+	if (metrics.length === 0) {
+		throw new Error("At least one metric is required.");
+	}
+	const notes: string[] = [];
+	const baseNames = new Set(dataset.measures.map((m) => m.name));
+	if (useEventName && !dataset.eventName) {
+		throw new Error(`Dataset "${dataset.id}" does not support the event_name dimension.`);
+	}
+	const pool =
+		useEventName && dataset.eventName
+			? new Set(Object.keys(dataset.eventName.measures))
+			: baseNames;
+	const derivedByName = new Map(
+		dataset.derived
+			.filter((d) => pool.has(d.numerator) && pool.has(d.denominator))
+			.map((d) => [d.name, d]),
+	);
+	const selected = new Set<string>();
+	const derived: DerivedDef[] = [];
+
+	for (const metric of metrics) {
+		if (pool.has(metric)) {
+			selected.add(metric);
+		} else if (derivedByName.has(metric)) {
+			const def = derivedByName.get(metric) as DerivedDef;
+			derived.push(def);
+			selected.add(def.numerator);
+			selected.add(def.denominator);
+		} else if (useEventName && (baseNames.has(metric) || dataset.derived.some((d) => d.name === metric))) {
+			throw new Error(
+				`Metric "${metric}" is not available with the event_name dimension on "${dataset.id}". ` +
+					`Allowed: ${[...pool, ...derivedByName.keys()].join(", ")}.`,
+			);
+		} else {
+			const available = [...pool, ...derivedByName.keys()].join(", ");
+			throw new Error(
+				`Unknown metric "${metric}" for dataset "${dataset.id}". Available metrics: ${available}.`,
+			);
+		}
+	}
+
+	if (useEventName && dataset.eventName) {
+		notes.push(`Metrics are read from the per-event breakdown in ${dataset.eventName.jsonbColumn}.`);
+	}
+
+	return { dataset, measures: [...selected], derived, notes };
+}
+
+function measureSql(dataset: DatasetDef, name: string, useEventName: boolean): string {
+	if (useEventName && dataset.eventName) {
+		return dataset.eventName.measures[name];
+	}
+	const def = dataset.measures.find((m) => m.name === name);
+	if (!def) throw new Error(`Internal error: unresolved measure "${name}".`);
+	return def.sql;
+}
+
+function resolveBreakdown(
+	dataset: DatasetDef,
+	dimensionNames: string[],
+	filterKeys: string[],
+): { predicate?: string; note?: string } {
+	if (!dataset.breakdown) return {};
+	const used = new Set([...dimensionNames, ...filterKeys]);
+	const matches = Object.entries(dataset.breakdown.byDimension).filter(([dim]) => used.has(dim));
+	if (matches.length > 1) {
+		throw new Error(
+			`Dimensions ${matches.map(([d]) => d).join(" and ")} cannot be combined: ` +
+				"the source table has no breakdown that carries both.",
+		);
+	}
+	const value = matches.length === 1 ? matches[0][1] : dataset.breakdown.base;
+	return {
+		predicate: `${dataset.breakdown.column} = ${escapeLiteral(value)}`,
+		note: `Pinned ${dataset.breakdown.column} = ${value} to avoid double counting.`,
+	};
+}
+
+export function buildQuery(spec: QuerySpec): BuiltQuery {
+	const dataset = getDataset(spec.dataset);
+	const dimensionNames = spec.dimensions ?? [];
+	const useEventName =
+		dimensionNames.includes("event_name") || "event_name" in (spec.filters ?? {});
+
+	const dimensionDefs = dimensionNames.map((name) => {
+		const def = dataset.dimensions.find((d) => d.name === name);
+		if (!def) {
+			throw new Error(
+				`Unknown dimension "${name}" for dataset "${dataset.id}". ` +
+					`Available: ${dataset.dimensions.map((d) => d.name).join(", ")}.`,
+			);
+		}
+		return def;
+	});
+
+	const resolved = resolveMetrics(dataset, spec.metrics, useEventName);
+	const notes = [...resolved.notes];
+
+	const where: string[] = [];
+	if (spec.dateFrom) where.push(`${dataset.dateColumn} >= ${escapeLiteral(assertDate(spec.dateFrom, "dateFrom"))}`);
+	if (spec.dateTo) where.push(`${dataset.dateColumn} <= ${escapeLiteral(assertDate(spec.dateTo, "dateTo"))}`);
+
+	const filterKeys: string[] = [];
+	for (const [key, raw] of Object.entries(spec.filters ?? {})) {
+		const def = dataset.dimensions.find((d) => d.name === key);
+		if (!def) {
+			throw new Error(
+				`Unknown filter field "${key}" for dataset "${dataset.id}". ` +
+					`Filterable fields: ${dataset.dimensions.map((d) => d.name).join(", ")}. ` +
+					"Use dateFrom/dateTo for the date range.",
+			);
+		}
+		filterKeys.push(key);
+		const values = normalizeFilterValues(raw).map(escapeLiteral);
+		where.push(values.length === 1 ? `${def.sql} = ${values[0]}` : `${def.sql} in (${values.join(", ")})`);
+	}
+
+	const breakdown = resolveBreakdown(dataset, dimensionNames, filterKeys);
+	if (breakdown.predicate) {
+		where.push(breakdown.predicate);
+		if (breakdown.note) notes.push(breakdown.note);
+	}
+
+	const selectParts: string[] = [];
+	const groupParts: string[] = [];
+	if (spec.timeGrain) {
+		selectParts.push(`date_trunc('${spec.timeGrain}', ${dataset.dateColumn})::date as period`);
+		groupParts.push("1");
+	}
+	for (const def of dimensionDefs) {
+		selectParts.push(`${def.sql} as ${def.name}`);
+		groupParts.push(String(selectParts.length));
+	}
+	for (const name of resolved.measures) {
+		selectParts.push(`${measureSql(dataset, name, useEventName)} as ${name}`);
+	}
+	selectParts.push(`min(${dataset.dateColumn})::text as date_min`);
+	selectParts.push(`max(${dataset.dateColumn})::text as date_max`);
+	selectParts.push("count(*) as source_rows");
+
+	let from = dataset.table;
+	if (useEventName && dataset.eventName) {
+		from += ` cross join lateral jsonb_each(${dataset.eventName.jsonbColumn}) as e(k, v)`;
+	} else if (dataset.lateral) {
+		from += ` ${dataset.lateral}`;
+	}
+
+	const sortable = new Set([
+		...(spec.timeGrain ? ["period"] : []),
+		...dimensionNames,
+		...resolved.measures,
+	]);
+	let orderBy: string;
+	if (spec.sort) {
+		if (!sortable.has(spec.sort.by)) {
+			throw new Error(
+				`sort.by must be one of the selected columns: ${[...sortable].join(", ")}. ` +
+					"Derived metrics are computed after SQL and cannot be sorted server-side.",
+			);
+		}
+		const direction = spec.sort.direction ?? "desc";
+		if (!SORT_DIRECTIONS.has(direction)) {
+			throw new Error(`sort.direction must be "asc" or "desc".`);
+		}
+		orderBy = `${spec.sort.by} ${direction}`;
+	} else if (spec.timeGrain) {
+		orderBy = "period asc";
+	} else if (resolved.measures.length > 0) {
+		orderBy = `${resolved.measures[0]} desc`;
+	} else {
+		orderBy = "1";
+	}
+
+	const limit = Math.max(1, Math.min(spec.limit ?? DEFAULT_LIMIT, MAX_LIMIT));
+	if ((spec.limit ?? DEFAULT_LIMIT) > MAX_LIMIT) {
+		notes.push(`limit was capped at ${MAX_LIMIT}.`);
+	}
+
+	const sql = [
+		`select ${selectParts.join(", ")}`,
+		`from ${from}`,
+		where.length > 0 ? `where ${where.join(" and ")}` : "",
+		groupParts.length > 0 ? `group by ${groupParts.join(", ")}` : "",
+		`order by ${orderBy}`,
+		`limit ${limit}`,
+	]
+		.filter(Boolean)
+		.join(" ");
+
+	return {
+		sql: assertReadOnly(sql),
+		dataset,
+		measures: resolved.measures,
+		derived: resolved.derived,
+		dimensions: dimensionNames,
+		timeGrain: spec.timeGrain,
+		notes,
+	};
+}
+
+export interface CohortSpec {
+	appCodes?: string[];
+	platforms?: string[];
+	installFrom: string;
+	installTo: string;
+	horizons?: number[];
+	bucket?: CohortBucket;
+	/** Extra grouping keys kept in the output. Defaults to app_code + platform. */
+	groupBy?: Array<"app_code" | "platform">;
+}
+
+export interface BuiltCohortQuery {
+	sql: string;
+	spendSql: string;
+	asOfSql: string;
+	horizons: number[];
+	bucket: CohortBucket;
+	groupBy: Array<"app_code" | "platform">;
+}
+
+export const DEFAULT_HORIZONS = [0, 3, 7, 14, 30];
+export const MAX_HORIZON = 365;
+
+function bucketExpr(bucket: CohortBucket, column: string): string {
+	if (bucket === "total") return "'total'";
+	return `date_trunc('${bucket}', ${column})::date::text`;
+}
+
+export function buildCohortQuery(spec: CohortSpec): BuiltCohortQuery {
+	const installFrom = assertDate(spec.installFrom, "installFrom");
+	const installTo = assertDate(spec.installTo, "installTo");
+	const bucket: CohortBucket = spec.bucket ?? "week";
+	const groupBy = spec.groupBy ?? ["app_code", "platform"];
+	for (const key of groupBy) {
+		if (key !== "app_code" && key !== "platform") {
+			throw new Error(`groupBy supports only app_code and platform, got "${key}".`);
+		}
+	}
+
+	const horizons = [...new Set(spec.horizons ?? DEFAULT_HORIZONS)].sort((a, b) => a - b);
+	if (horizons.length === 0) {
+		throw new Error("At least one horizon is required.");
+	}
+	for (const n of horizons) {
+		if (!Number.isInteger(n) || n < 0 || n > MAX_HORIZON) {
+			throw new Error(`Horizons must be integers between 0 and ${MAX_HORIZON}, got ${n}.`);
+		}
+	}
+
+	const scope: string[] = [
+		`install_date >= ${escapeLiteral(installFrom)}`,
+		`install_date <= ${escapeLiteral(installTo)}`,
+	];
+	if (spec.appCodes && spec.appCodes.length > 0) {
+		scope.push(`app_code in (${spec.appCodes.map(escapeLiteral).join(", ")})`);
+	}
+	if (spec.platforms && spec.platforms.length > 0) {
+		scope.push(`platform in (${spec.platforms.map(escapeLiteral).join(", ")})`);
+	}
+
+	const perInstallMeasures = horizons
+		.flatMap((n) => [
+			`sum(net_proceeds_usd) filter (where event_date <= install_date + ${n}) as net_d${n}`,
+			`max(active_user_count) filter (where event_date = install_date + ${n}) as active_d${n}`,
+		])
+		.join(", ");
+
+	const outerKeys = ["bucket", ...groupBy];
+	const outerMeasures = horizons
+		.flatMap((n) => [`sum(net_d${n}) as net_d${n}`, `sum(active_d${n}) as active_d${n}`])
+		.join(", ");
+
+	const sql = assertReadOnly(
+		`with per_install as (` +
+			`select app_code, platform, install_date, max(installed_user_count) as cohort_size, ${perInstallMeasures} ` +
+			`from appsflyer_install_cohort_daily where ${scope.join(" and ")} group by 1, 2, 3` +
+			`) select ${bucketExpr(bucket, "install_date")} as bucket` +
+			(groupBy.length > 0 ? `, ${groupBy.join(", ")}` : "") +
+			`, count(*) as install_days` +
+			`, count(*) filter (where cohort_size is null) as days_missing_cohort_size` +
+			`, sum(cohort_size) as cohort_size` +
+			`, min(install_date)::text as install_min, max(install_date)::text as install_max` +
+			`, ${outerMeasures} ` +
+			`from per_install group by ${outerKeys.map((_, i) => i + 1).join(", ")} ` +
+			`order by ${outerKeys.map((_, i) => i + 1).join(", ")}`,
+	);
+
+	const spendSql = assertReadOnly(
+		`select ${bucketExpr(bucket, "install_date")} as bucket` +
+			(groupBy.length > 0 ? `, ${groupBy.join(", ")}` : "") +
+			`, sum(cost_usd) as spend, sum(installs) as ua_installs` +
+			`, count(distinct install_date) as spend_days ` +
+			`from appsflyer_ua_campaign_daily ` +
+			`where breakdown_type = 'CAMPAIGN' and ${scope.join(" and ")} ` +
+			`group by ${outerKeys.map((_, i) => i + 1).join(", ")}`,
+	);
+
+	const asOfSql = assertReadOnly(
+		`select min(event_date)::text as min_event_date, max(event_date)::text as max_event_date, ` +
+			`max(updated_at)::text as updated_at from appsflyer_install_cohort_daily`,
+	);
+
+	return { sql, spendSql, asOfSql, horizons, bucket, groupBy };
+}
+
+/** Coverage catalog query used by fpa_data_catalog. */
+export function buildCoverageSql(): string {
+	const parts = [
+		`select 'ua_spend' as dataset, count(*) as row_count, min(install_date)::text as date_min, max(install_date)::text as date_max, count(distinct app_code) as apps, max(updated_at)::text as updated_at from appsflyer_ua_campaign_daily`,
+		`select 'revenue_activity', count(*), min(event_date)::text, max(event_date)::text, count(distinct app_code), max(updated_at)::text from appsflyer_install_cohort_daily`,
+		`select 'cohort (fpa_cohort)', count(*), min(install_date)::text, max(install_date)::text, count(distinct app_code), max(updated_at)::text from appsflyer_install_cohort_daily`,
+		`select 'apple_store', count(*), min(metric_date)::text, max(metric_date)::text, count(distinct adam_id), max(updated_at)::text from apple_app_daily`,
+		`select 'product_events', count(*), min(event_date)::text, max(event_date)::text, count(distinct app_code), max(updated_at)::text from appsflyer_event_daily`,
+		`select 'mixpanel_product', count(*), min(business_date)::text, max(business_date)::text, count(distinct app_code), max(updated_at)::text from mixpanel_app_daily`,
+	];
+	return assertReadOnly(parts.join(" union all "));
+}
+
+/** Cohort-size availability window, reported by fpa_data_catalog. */
+export function buildCohortSizeCoverageSql(): string {
+	return assertReadOnly(
+		`select min(install_date)::text as cohort_size_from, max(install_date)::text as cohort_size_to ` +
+			`from appsflyer_install_cohort_daily where installed_user_count is not null`,
+	);
+}

package/extensions/fpa-data/supabase.ts

@@ -0,0 +1,96 @@
+/**
+ * Minimal read-only client for the Supabase Management API query endpoint.
+ *
+ * Credentials come from the environment; nothing is embedded in the package:
+ *   SUPABASE_PROJECT_REF  - project ref, e.g. abcdefghijklmnopqrst
+ *   SUPABASE_ACCESS_TOKEN - personal access token (sbp_...)
+ */
+
+import { assertReadOnly } from "./sql.ts";
+
+const API_BASE = "https://api.supabase.com";
+const DEFAULT_TIMEOUT_MS = 30_000;
+const MAX_RESPONSE_BYTES = 5 * 1024 * 1024;
+
+export interface SupabaseConfig {
+	projectRef: string;
+	accessToken: string;
+}
+
+export function resolveConfig(env: Record<string, string | undefined> = process.env): SupabaseConfig {
+	const projectRef = env.SUPABASE_PROJECT_REF?.trim();
+	const accessToken = env.SUPABASE_ACCESS_TOKEN?.trim();
+	if (!projectRef || !accessToken) {
+		throw new Error(
+			"Supabase credentials are not configured. Set SUPABASE_PROJECT_REF and " +
+				"SUPABASE_ACCESS_TOKEN in the environment before starting Pi. " +
+				"No query was sent.",
+		);
+	}
+	if (!/^[a-z0-9]{16,32}$/.test(projectRef)) {
+		throw new Error("SUPABASE_PROJECT_REF does not look like a valid project ref.");
+	}
+	return { projectRef, accessToken };
+}
+
+export type SqlRow = Record<string, unknown>;
+
+export async function runQuery(
+	sql: string,
+	options: { signal?: AbortSignal; timeoutMs?: number; config?: SupabaseConfig } = {},
+): Promise<SqlRow[]> {
+	assertReadOnly(sql);
+	const config = options.config ?? resolveConfig();
+	const signals = [AbortSignal.timeout(options.timeoutMs ?? DEFAULT_TIMEOUT_MS)];
+	if (options.signal) signals.push(options.signal);
+
+	let response: Response;
+	try {
+		response = await fetch(
+			`${API_BASE}/v1/projects/${config.projectRef}/database/query`,
+			{
+				method: "POST",
+				headers: {
+					Authorization: `Bearer ${config.accessToken}`,
+					"Content-Type": "application/json",
+				},
+				body: JSON.stringify({ query: sql, read_only: true }),
+				signal: AbortSignal.any(signals),
+			},
+		);
+	} catch (error) {
+		if (error instanceof Error && error.name === "TimeoutError") {
+			throw new Error("Supabase query timed out. Narrow the date range or filters.");
+		}
+		throw new Error(
+			`Could not reach the Supabase Management API: ${error instanceof Error ? error.message : String(error)}`,
+		);
+	}
+
+	const body = await response.text();
+	if (new TextEncoder().encode(body).byteLength > MAX_RESPONSE_BYTES) {
+		throw new Error(
+			`Supabase response exceeds ${MAX_RESPONSE_BYTES} bytes. Narrow the query with filters, a shorter date range, or a lower limit.`,
+		);
+	}
+
+	let payload: unknown;
+	try {
+		payload = body ? JSON.parse(body) : null;
+	} catch {
+		throw new Error(`Supabase returned non-JSON data (HTTP ${response.status}).`);
+	}
+
+	if (!response.ok) {
+		const detail =
+			payload && typeof payload === "object" && "message" in payload
+				? String((payload as { message: unknown }).message)
+				: body.slice(0, 500);
+		throw new Error(`Supabase Management API error ${response.status}: ${detail}`);
+	}
+
+	if (!Array.isArray(payload)) {
+		throw new Error("Unexpected Supabase response shape: expected an array of rows.");
+	}
+	return payload as SqlRow[];
+}

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@viccydev/pi-fpa",
+  "version": "0.2.0",
+  "type": "module",
+  "description": "Full-cycle FP&A planning, strategy, forecast, and review prompts, skills, and data tools for Pi",
+  "license": "UNLICENSED",
+  "keywords": [
+    "pi-package",
+    "fpa"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/linyqh/pi-fpa.git"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "files": [
+    "README.md",
+    "prompts",
+    "skills",
+    "extensions"
+  ],
+  "scripts": {
+    "test": "node tests/package-structure.test.mjs && node tests/extension-unit.test.mjs && node tests/pi-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",
+    "test:loader": "node tests/pi-loader-smoke.mjs",
+    "test:live": "node tests/live-smoke.mjs",
+    "pack:check": "npm pack --dry-run"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*",
+    "typebox": "*"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-ai": "0.84.1",
+    "@earendil-works/pi-coding-agent": "0.84.1",
+    "typebox": "1.3.7"
+  },
+  "pi": {
+    "prompts": [
+      "./prompts"
+    ],
+    "skills": [
+      "./skills"
+    ],
+    "extensions": [
+      "./extensions/fpa-data/index.ts"
+    ]
+  }
+}

package/prompts/fpa-plan-cycle.md

@@ -0,0 +1,44 @@
+---
+description: 启动完整 FP&A 策略规划，并在匹配版本获得外部人工批准后形成正式预测
+argument-hint: "<project-root> <cycle-id> [instructions]"
+---
+
+为项目 `$1` 启动 FP&A 周期 `$2`。
+
+补充要求：`${@:3}`
+
+## 输入解析
+
+- 把 `$1` 作为项目根；先确认它真实存在，不得猜测或替换成开发者机器上的其他目录。
+- 默认从项目根解析 `LOCAL_FPA_MART_FIELD_CATALOG.md` 和 `LOCAL_FPA_MART_SCHEMA.sql`。如果补充要求提供其他字段目录、Schema、数据快照或 Artifact 路径，以显式路径为准。
+- 明确周期的开始时间、结束时间、业务时区、报告币种、比较基线，以及 App、Store、Product Group、Channel Group 范围。不能从 `$2` 的名称暗自推断日期边界。
+- 关键输入缺失时列出缺口并保持 `blocked`；不得编造字段、表、数据、批准或 Artifact。
+
+## 能力路由
+
+先读取可用 Skill 中的 `fpa-apply-core-rules`，再从 `fpa-plan-cycle` 开始。根据当前阶段依次按需读取：
+
+1. `fpa-diagnose-actuals`
+2. `fpa-analyze-drivers`
+3. `fpa-simulate-strategies`
+4. `fpa-recommend-strategy`
+5. `fpa-review-strategy`
+6. `fpa-forecast-approved-strategy`
+
+不要一次性加载所有 Skill，也不要在本 Prompt 中复述它们的完整规则。每一阶段只消费已完成的上游 Artifact，并按对应 `references/artifact-contract.md` 输出。
+
+## 不可跳过的停点
+
+- 策略推荐者不得批准或独立复核自己的提案。若宿主不能证明复核上下文与提案作者独立，复核阶段必须报告 `blocked`。
+- 独立复核完成后停止并等待外部人工批准。聊天中的认可、模型自我确认或 Forecast 授权都不等于策略执行授权。
+- 只有人工批准明确引用同一 `strategy_proposal` 版本且批准条件已满足，才读取 `fpa-forecast-approved-strategy` 生成正式预测。
+- 本入口的终点是已确认持久化的 `approved_cycle_forecast`。不得加载或调用策略执行 Skill，不得声称已经修改任何外部投放状态。
+
+## 全局计算与证据底线
+
+- 先聚合可加的分子和分母，再重算比率；不得平均 CPI、CAC、留存率、付费率、LTV 或 ROAS。
+- 缺失、未成熟 cohort 或零分母指标使用 `NULL`，不得写成 `0`。
+- 区分 observed、assumed、modeled、judgment 和 approved；相关性不得冒充因果关系。
+- 每个结论记录实际表、字段、grain、join key、时间范围、`data_as_of`、版本和质量限制。
+
+最终交付应包含 `planning_brief`、`actuals_snapshot`、`data_issue_report`、`driver_analysis`、`strategy_scenarios`、`strategy_proposal`、独立 `strategy_review`、外部 `strategy_approval` 证据，以及批准后的 `approved_cycle_forecast`。任何未完成项都必须标注状态和阻塞原因。

package/prompts/fpa-review-cycle.md

@@ -0,0 +1,33 @@
+---
+description: 在新周期 Actuals 到达后复盘冻结预测，并形成下一周期输入
+argument-hint: "<project-root> <cycle-id> [instructions]"
+---
+
+复盘项目 `$1` 的 FP&A 周期 `$2`。
+
+补充要求：`${@:3}`
+
+## 输入解析
+
+- 把 `$1` 作为项目根并确认它真实存在。
+- 找到该周期不可变的 `approved_cycle_forecast`、对应策略与批准证据，以及覆盖同一业务周期的新 Actuals snapshot。
+- 默认从项目根解析 `LOCAL_FPA_MART_FIELD_CATALOG.md` 和 `LOCAL_FPA_MART_SCHEMA.sql`；补充要求提供其他显式路径时使用显式路径。
+- 明确复盘周期的精确起止时间、业务时区、币种和业务范围。若 Forecast 与 Actuals 不可比，缩窄结论或保持 `blocked`，不得修写历史 Forecast。
+
+## 能力路由
+
+1. 先读取 `fpa-apply-core-rules`。
+2. 使用 `fpa-diagnose-actuals` 验证新 Actuals 的 grain、完整性、成熟度和可比性。
+3. 使用 `fpa-review-cycle` 对比冻结 Forecast 与 Actuals，生成其 Artifact 合同要求的 `cycle_review`。
+
+只按需读取上述 Skill，不要把 Skill 正文复制到结果中。
+
+## 复盘底线
+
+- 使用冻结 Forecast，不得看到结果后重算基线。
+- 使用 `variance = actual - frozen_forecast`；百分比差异的分母为零时返回 `NULL`。
+- 将偏差区分为执行、量、效率、转化、留存/LTV、结构、外部因素、模型和数据影响；证据不足时标记 unknown，不强行归因。
+- 执行回执只证明动作记录，不证明策略导致结果。
+- 本入口只输出复盘与 `next_cycle_inputs`，不得自动开始下一规划周期，也不得加载或调用策略执行 Skill。
+
+最终交付为可追溯的 `cycle_review`：包含 Forecast/Actual 可比性检查、差异与驱动、假设评价、经验、下一周期输入和未决问题。关键输入缺失时列出缺口并保持 `blocked`。

package/skills/fpa-analyze-drivers/SKILL.md

@@ -0,0 +1,30 @@
+---
+name: fpa-analyze-drivers
+description: Explain the measurable operating drivers behind period-over-period changes in revenue, subscriptions, UA, user activity, and First Open cohorts. Use after Actuals pass diagnosis and before constructing or simulating candidate UA strategies.
+---
+
+# FP&A Driver Analysis
+
+Load `$fpa-apply-core-rules` first. Explain what changed and why the data supports that conclusion; do not recommend a plan yet.
+
+## Procedure
+
+1. Consume `planning_brief`, `actuals_snapshot`, and `data_issue_report`.
+2. Recompute headline metrics from eligible additive components with `fpa_query` (cohort metrics with `fpa_cohort`).
+3. Compare the requested period with its declared baseline at like-for-like scope with `fpa_compare`, which returns deltas, percentage changes, and per-slice contribution.
+4. Build metric bridges by App, Store, Product Group, and Channel Group where supported.
+5. Separate volume, rate/efficiency, mix, and data-coverage effects.
+6. Distinguish observed relationships from causal claims and untested hypotheses.
+7. Rank drivers by materiality and decision relevance, then write `driver_analysis` using [artifact-contract.md](references/artifact-contract.md).
+
+## Mathematical discipline
+
+- For additive metrics, contribution is slice Actual minus slice baseline after scope alignment.
+- For ratios, decompose using their underlying numerator and denominator; never compare averaged ratios.
+- For multiplicative identities such as `spend = paid_installs × CPI`, name the decomposition method and include an interaction/residual term when the chosen method does not allocate it.
+- Reconcile every bridge to the total change within a declared tolerance, using `fpa_calc` for the reconciliation arithmetic.
+- Treat a correlation as a hypothesis unless a causal design or validated response model exists.
+
+## Handoff
+
+Pass the ranked controllable drivers, non-controllable drivers, risks, and evidence gaps to `$fpa-simulate-strategies`.