@viccydev/pi-fpa 0.9.4 → 0.9.5

package/README.md

@@ -159,12 +159,12 @@ pi list
 团队分发建议使用固定 Git tag：
 
 ```bash
-pi install git:github.com/linyqh/pi-fpa@v0.9.4
+pi install git:github.com/linyqh/pi-fpa@v0.9.5
 ```
 
 ## 发布到 npm
 
-发布动作由 GitHub Release 触发。Release 标签必须严格使用 `v<package.json version>`，例如版本 `0.9.4` 对应 `v0.9.4`。工作流会检出该标签，执行 `npm ci`、`npm test` 和包内容预检，全部通过后发布公开包 `@viccydev/pi-fpa`。普通 Release 发布到 `latest`，Prerelease 发布到 `next`。
+发布动作由 GitHub Release 触发。Release 标签必须严格使用 `v<package.json version>`，例如版本 `0.9.5` 对应 `v0.9.5`。工作流会检出该标签，执行 `npm ci`、`npm test` 和包内容预检，全部通过后发布公开包 `@viccydev/pi-fpa`。普通 Release 发布到 `latest`，Prerelease 发布到 `next`。
 
 发布认证使用 npm Trusted Publishing / OIDC，不使用长期 npm Token。npm 包后台的 Trusted Publisher 配置为：
 

package/extensions/fpa-dashboard/decision-ledger-projector.ts

@@ -0,0 +1,323 @@
+import type { DashboardModuleBuild } from "./module-publisher.ts";
+import type { DashboardWidget, TableCell, TableDataset } from "./projector.ts";
+import type { DecisionEvent, DecisionPackage } from "./decision-package.ts";
+
+// ============================================================================
+// The decision ledger module.
+//
+// Answers "where did the approved decisions get to" — the question the
+// dashboard could not answer at all before, because confirming a strategy left
+// nothing behind to track.
+//
+// Spend is not computed here. It arrives measured, from the execution receipt
+// or the actuals source, and stays null when nothing has measured it yet. A
+// decision showing $0 spent looks like a decision nobody acted on, which is a
+// very different thing from one nobody has reported on.
+// ============================================================================
+
+const EVENT_TYPE_LABELS = {
+	approved: "批准",
+	parameters_locked: "参数锁定",
+	task_accepted: "任务接受",
+	task_completed: "任务完成",
+	parameter_adjusted: "参数调整",
+	threshold_breached: "阈值触发",
+	closed: "关闭",
+} as const;
+
+const TASK_STATUS_LABELS = {
+	not_started: "未开始",
+	in_progress: "进行中",
+	completed: "已完成",
+	adjusted: "已调整",
+	synced: "已同步",
+	configured: "已配置",
+	not_completed: "未完成",
+} as const;
+
+export interface DecisionSpend {
+	decision_id: string;
+	/** Measured spend to date, or null when nothing has measured it. */
+	actual_spend_usd: number | null;
+	/** 0..1 execution progress, or null when unknown. */
+	progress?: number | null;
+	/** Where the measurement came from, shown as evidence. */
+	source?: string;
+}
+
+export interface DecisionLedgerInput {
+	packages: DecisionPackage[];
+	events: Record<string, DecisionEvent[]>;
+	spend?: DecisionSpend[];
+	locale?: string;
+}
+
+export interface DecisionLedgerProjection {
+	module: DashboardModuleBuild;
+	/** Decisions whose measured spend has passed their approved threshold. */
+	breaches: Array<{ decision_id: string; title: string; over_pct: number }>;
+}
+
+function currency(value: number | null, code: string, locale: string): string | null {
+	if (value === null) return null;
+	return new Intl.NumberFormat(locale, { style: "currency", currency: code, maximumFractionDigits: 0 }).format(value);
+}
+
+function percent(value: number | null, locale: string): string | null {
+	if (value === null) return null;
+	return new Intl.NumberFormat(locale, { style: "percent", maximumFractionDigits: 1 }).format(value);
+}
+
+function toned(value: string | null, tone?: "positive" | "negative" | "warning" | "neutral"): TableCell {
+	return tone ? { value, tone } : value;
+}
+
+/**
+ * Over-budget fraction, or null when it cannot be computed.
+ *
+ * Returns null rather than 0 when the budget is missing or zero: "we cannot
+ * tell whether this is over budget" must not render as "this is exactly on
+ * budget", which is what a 0 here would claim.
+ */
+function overBudgetFraction(pkg: DecisionPackage, spend: number | null): number | null {
+	if (spend === null || pkg.approved_budget_usd === null || pkg.approved_budget_usd <= 0) return null;
+	return spend / pkg.approved_budget_usd - 1;
+}
+
+function summaryTable(
+	packages: DecisionPackage[],
+	spendById: Map<string, DecisionSpend>,
+	locale: string,
+): TableDataset {
+	return {
+		label: "决策归档包",
+		description: "已批准决策的批准预算、实际支出与执行进度",
+		columns: [
+			{ key: "decision", label: "决策包" },
+			{ key: "version", label: "版本" },
+			{ key: "approver", label: "批准人" },
+			{ key: "owner", label: "负责人" },
+			{ key: "budget", label: "批准预算", align: "right" },
+			{ key: "actual", label: "实际支出", align: "right" },
+			{ key: "variance", label: "偏差", align: "right" },
+			{ key: "progress", label: "执行进度", align: "right" },
+			{ key: "status", label: "状态" },
+		],
+		rows: packages.map((pkg) => {
+			const spend = spendById.get(pkg.decision_id);
+			const actual = spend?.actual_spend_usd ?? null;
+			const over = overBudgetFraction(pkg, actual);
+			const breached = over !== null && over > pkg.budget_threshold_pct;
+			return {
+				decision: `${pkg.decision_id} · ${pkg.title}`,
+				version: pkg.version,
+				approver: pkg.approver_role,
+				owner: pkg.owner,
+				budget: currency(pkg.approved_budget_usd, pkg.reporting_currency, locale),
+				actual: currency(actual, pkg.reporting_currency, locale),
+				variance: toned(
+					over === null ? null : `${over > 0 ? "+" : ""}${percent(over, locale)}`,
+					over === null ? undefined : breached ? "negative" : over > 0 ? "warning" : "positive",
+				),
+				progress: spend?.progress === null || spend?.progress === undefined ? null : percent(spend.progress, locale),
+				status: toned(
+					breached ? "超阈值" : spend?.progress === 1 ? "已完成" : "执行中",
+					breached ? "negative" : spend?.progress === 1 ? "positive" : "neutral",
+				),
+			};
+		}),
+	};
+}
+
+function approvalsTable(packages: DecisionPackage[]): TableDataset {
+	return {
+		label: "审批留痕",
+		description: "每个决策包的审批链与时间戳",
+		columns: [
+			{ key: "decision", label: "决策包" },
+			{ key: "step", label: "步骤", align: "right" },
+			{ key: "role", label: "角色" },
+			{ key: "approver", label: "审批人" },
+			{ key: "action", label: "动作" },
+			{ key: "at", label: "时间" },
+			{ key: "comment", label: "备注" },
+		],
+		rows: packages.flatMap((pkg) =>
+			pkg.approvals.map((approval) => ({
+				decision: pkg.decision_id,
+				step: String(approval.step_order),
+				role: approval.role,
+				approver: approval.approver,
+				action: approval.action === "approved" ? "批准" : approval.action === "acknowledged" ? "确认" : "驳回",
+				at: approval.decided_at,
+				comment: approval.comment ?? null,
+			})),
+		),
+	};
+}
+
+function tasksTable(packages: DecisionPackage[]): TableDataset {
+	return {
+		label: "执行任务清单",
+		columns: [
+			{ key: "decision", label: "决策包" },
+			{ key: "task", label: "任务" },
+			{ key: "owner", label: "负责人" },
+			{ key: "due", label: "截止" },
+			{ key: "status", label: "状态" },
+		],
+		rows: packages.flatMap((pkg) =>
+			pkg.tasks.map((task) => ({
+				decision: pkg.decision_id,
+				task: task.task_name,
+				owner: task.owner,
+				due: task.due_date,
+				status: toned(
+					TASK_STATUS_LABELS[task.status],
+					task.status === "completed" ? "positive" : task.status === "not_completed" ? "negative" : "neutral",
+				),
+			})),
+		),
+	};
+}
+
+function auditTable(packages: DecisionPackage[], events: Record<string, DecisionEvent[]>): TableDataset {
+	const rows = packages.flatMap((pkg) =>
+		(events[pkg.decision_id] ?? []).map((event) => ({
+			at: event.event_at,
+			decision: pkg.decision_id,
+			actor: `${event.actor}${event.actor_type === "system" ? " (系统)" : ""}`,
+			type: toned(
+				EVENT_TYPE_LABELS[event.event_type],
+				event.event_type === "threshold_breached" ? "negative" : event.event_type === "approved" ? "positive" : "neutral",
+			),
+			summary: event.summary,
+			reason: event.reason ?? null,
+			detail: event.change_detail ?? null,
+		})),
+	);
+	return {
+		label: "审计日志",
+		description: "谁在什么时候、因为什么、改了什么",
+		columns: [
+			{ key: "at", label: "时间" },
+			{ key: "decision", label: "决策包" },
+			{ key: "actor", label: "操作者" },
+			{ key: "type", label: "事件" },
+			{ key: "summary", label: "说明" },
+			{ key: "reason", label: "原因" },
+			{ key: "detail", label: "变更" },
+		],
+		// Newest first: the audit log is read to answer "what just happened".
+		rows: rows.sort((left, right) => String(right.at).localeCompare(String(left.at))),
+	};
+}
+
+export function projectDecisionLedger(input: DecisionLedgerInput): DecisionLedgerProjection {
+	const locale = input.locale ?? "zh-CN";
+	const packages = input.packages;
+	const spendById = new Map((input.spend ?? []).map((entry) => [entry.decision_id, entry]));
+	const warnings: string[] = [];
+
+	const breaches: DecisionLedgerProjection["breaches"] = [];
+	let unmeasured = 0;
+	for (const pkg of packages) {
+		const actual = spendById.get(pkg.decision_id)?.actual_spend_usd ?? null;
+		if (actual === null) {
+			unmeasured += 1;
+			continue;
+		}
+		const over = overBudgetFraction(pkg, actual);
+		if (over !== null && over > pkg.budget_threshold_pct) {
+			breaches.push({ decision_id: pkg.decision_id, title: pkg.title, over_pct: over });
+		}
+	}
+
+	// The limits belong to this module, next to the numbers they qualify.
+	if (unmeasured > 0) {
+		warnings.push(`${unmeasured} 个决策包尚无实际支出计量，其偏差与状态显示为缺失而非零。`);
+	}
+	for (const breach of breaches) {
+		warnings.push(`${breach.decision_id}「${breach.title}」实际支出超批准预算 ${(breach.over_pct * 100).toFixed(1)}%，已超过其阈值。`);
+	}
+	const missingBudget = packages.filter((pkg) => pkg.approved_budget_usd === null);
+	if (missingBudget.length > 0) {
+		warnings.push(`${missingBudget.length} 个决策包没有可追踪的批准预算，无法判断是否超支。`);
+	}
+
+	const measured = packages.length - unmeasured;
+	const widgets: DashboardWidget[] = [
+		{
+			id: "decision-active-count",
+			type: "stat",
+			span: "quarter",
+			dataset: "decision-active-count.json",
+			data: {
+				label: "进行中决策",
+				value: String(packages.filter((pkg) => (spendById.get(pkg.decision_id)?.progress ?? 0) < 1).length),
+				description: `共 ${packages.length} 个已批准决策包`,
+			},
+		},
+		{
+			id: "decision-breach-count",
+			type: "stat",
+			span: "quarter",
+			dataset: "decision-breach-count.json",
+			data: {
+				label: "需关注",
+				value: String(breaches.length),
+				...(breaches.length > 0
+					? { description: breaches.map((breach) => breach.decision_id).join("、") }
+					: {}),
+				...(measured === 0
+					? { footnote: "尚无实际支出计量，此计数仅覆盖已计量的决策包。" }
+					: {}),
+				delta: breaches.length > 0
+					? { direction: "up", label: `${breaches.length} 个超阈值`, sentiment: "negative" }
+					: { direction: "flat", label: "无超阈值", sentiment: "positive" },
+			},
+		},
+		{
+			id: "decision-measured-coverage",
+			type: "stat",
+			span: "quarter",
+			dataset: "decision-measured-coverage.json",
+			data: {
+				label: "支出计量覆盖",
+				value: packages.length === 0 ? null : `${measured}/${packages.length}`,
+				...(packages.length === 0 ? { missingReason: "还没有已批准的决策包。" } : {}),
+				...(packages.length > 0
+					? {
+						progress: {
+							fraction: measured / packages.length,
+							label: percent(measured / packages.length, locale) ?? "—",
+							tone: measured === packages.length ? "positive" : "warning",
+						},
+					}
+					: {}),
+			},
+		},
+		{ id: "decision-summary", type: "table", span: "full", dataset: "decision-summary.json", data: summaryTable(packages, spendById, locale) },
+		{ id: "decision-tasks", type: "table", span: "full", dataset: "decision-tasks.json", data: tasksTable(packages) },
+		{ id: "decision-approvals", type: "table", span: "full", dataset: "decision-approvals.json", data: approvalsTable(packages) },
+		{ id: "decision-audit", type: "table", span: "full", dataset: "decision-audit.json", data: auditTable(packages, input.events) },
+	];
+
+	return {
+		module: {
+			id: "decision-ledger",
+			title: "决策履约与审计",
+			status: "published",
+			source: {
+				artifact_type: "decision_package",
+				package_count: packages.length,
+				decision_ids: packages.map((pkg) => pkg.decision_id),
+				package_fingerprints: packages.map((pkg) => pkg.package_fingerprint),
+				measured_spend_count: measured,
+			},
+			warnings,
+			widgets,
+		},
+		breaches,
+	};
+}

package/extensions/fpa-dashboard/decision-package.ts

@@ -0,0 +1,437 @@
+import { createHash, randomUUID } from "node:crypto";
+import { link, lstat, mkdir, open, readFile, readdir, realpath, unlink } from "node:fs/promises";
+import { join } from "node:path";
+
+import { stableJson } from "../fpa-artifacts/store.ts";
+
+// ============================================================================
+// Decision packages.
+//
+// A confirmed strategy used to leave no trace a person could follow: the
+// dashboard posted an action, the agent re-ran a Graph, and the decision
+// itself stopped existing. A decision package is that decision made into an
+// object with a lifecycle — what was approved, by whom, against which budget,
+// and what happened afterwards.
+//
+// Two stores, because the data has two different natures:
+//
+//   * The package is written once and never edited. It carries the parameter
+//     snapshot as it stood at approval. If this were mutable, "what was
+//     approved" would drift into "what we ended up doing", and the ledger
+//     would lose the only thing it exists to prove.
+//
+//   * Events append. Execution progress, threshold breaches, and task
+//     transitions arrive over time and must never overwrite each other.
+//
+// Deliberately NOT an entry in the artifact ledger: that ledger holds the
+// immutable forecast/execution chain, addressed by content fingerprint. A
+// package accumulates history, so it would have to be re-committed on every
+// event, and each re-commit would mint a new identity for the same decision.
+// ============================================================================
+
+const SHA256_RE = /^[a-f0-9]{64}$/;
+const DECISION_ID_RE = /^DEC-\d{4}-\d{4}-[a-f0-9]{8}$/;
+const PACKAGES_DIR = "decision-packages";
+
+export const DECISION_STATUSES = ["in_progress", "completed", "variance", "cancelled"] as const;
+export type DecisionStatus = (typeof DECISION_STATUSES)[number];
+
+export const DECISION_EVENT_TYPES = [
+	"approved",
+	"parameters_locked",
+	"task_accepted",
+	"task_completed",
+	"parameter_adjusted",
+	"threshold_breached",
+	"closed",
+] as const;
+export type DecisionEventType = (typeof DECISION_EVENT_TYPES)[number];
+
+export const DECISION_TASK_STATUSES = ["not_started", "in_progress", "completed", "adjusted", "synced", "configured", "not_completed"] as const;
+export type DecisionTaskStatus = (typeof DECISION_TASK_STATUSES)[number];
+
+export interface DecisionApproval {
+	step_order: number;
+	role: string;
+	approver: string;
+	action: "approved" | "acknowledged" | "rejected";
+	decided_at: string;
+	comment?: string;
+}
+
+export interface DecisionTask {
+	task_id: string;
+	task_name: string;
+	owner: string;
+	due_date: string;
+	status: DecisionTaskStatus;
+	completed_at?: string;
+}
+
+export interface DecisionPackage {
+	kind: "fpa.decision.package";
+	schema_version: 1;
+	decision_id: string;
+	version: string;
+	title: string;
+	scope_id: string;
+	cycle_id: string;
+	strategy_version: string;
+	handoff_fingerprint: string;
+	action_id: string;
+	owner: string | null;
+	approver_role: string;
+	/** Null when the approved strategy carries no budget the ledger can track. */
+	approved_budget_usd: number | null;
+	/** Fraction over budget that trips an alert, e.g. 0.10 for +10%. */
+	budget_threshold_pct: number;
+	reporting_currency: string;
+	approved_at: string;
+	locked_at: string;
+	/** The parameters as approved. Never edited — see the note above. */
+	parameters: Record<string, unknown>;
+	approvals: DecisionApproval[];
+	tasks: DecisionTask[];
+	memo_ref: string | null;
+	/** Integrity over everything above. */
+	package_fingerprint: string;
+}
+
+export interface DecisionEvent {
+	kind: "fpa.decision.event";
+	schema_version: 1;
+	decision_id: string;
+	event_at: string;
+	actor: string;
+	actor_type: "human" | "system";
+	event_type: DecisionEventType;
+	summary: string;
+	reason?: string;
+	change_detail?: string;
+	estimated_impact_usd?: number;
+}
+
+/** Identifiers and titles: no control characters at all, DEL included. */
+const CONTROL_CHARS = new RegExp("[\\u0000-\\u001f\\u007f]");
+
+/**
+ * Free text a person wrote — an approval comment, a reason for a change.
+ * Newlines and tabs are content there, so only the remaining control
+ * characters are rejected.
+ */
+const CONTROL_CHARS_ALLOWING_NEWLINES = new RegExp("[\\u0000-\\u0008\\u000b\\u000c\\u000e-\\u001f\\u007f]");
+
+function sha256(value: string): string {
+	return createHash("sha256").update(value).digest("hex");
+}
+
+function boundedString(value: unknown, label: string, max = 512): string {
+	if (typeof value !== "string" || value.trim() === "" || value.length > max || CONTROL_CHARS.test(value)) {
+		throw new Error(`${label} must be a non-empty bounded string without control characters.`);
+	}
+	return value;
+}
+
+function optionalBoundedString(value: unknown, label: string, max = 4_096): string | undefined {
+	if (value === undefined || value === null) return undefined;
+	if (typeof value !== "string" || value.length > max || CONTROL_CHARS_ALLOWING_NEWLINES.test(value)) {
+		throw new Error(`${label} must be a bounded string without control characters.`);
+	}
+	return value;
+}
+
+function isoTimestamp(value: unknown, label: string): string {
+	const text = boundedString(value, label, 64);
+	if (Number.isNaN(Date.parse(text))) throw new Error(`${label} must be an ISO timestamp.`);
+	return text;
+}
+
+function finiteNumber(value: unknown, label: string): number {
+	if (typeof value !== "number" || !Number.isFinite(value)) throw new Error(`${label} must be a finite number.`);
+	return value;
+}
+
+function enumValue<T extends readonly string[]>(value: unknown, allowed: T, label: string): T[number] {
+	if (typeof value !== "string" || !allowed.includes(value)) {
+		throw new Error(`${label} must be one of ${allowed.join(", ")}.`);
+	}
+	return value as T[number];
+}
+
+async function ensureDirectory(parent: string, name: string): Promise<string> {
+	const path = join(parent, name);
+	try {
+		const stat = await lstat(path);
+		if (stat.isSymbolicLink() || !stat.isDirectory()) throw new Error(`${name} must be a regular directory, not a symlink.`);
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+		await mkdir(path, { recursive: true, mode: 0o700 });
+	}
+	return path;
+}
+
+async function appendOnlyWrite(directory: string, destination: string, contents: string): Promise<"created" | "exists"> {
+	const temporary = join(directory, `.${randomUUID()}.tmp`);
+	const handle = await open(temporary, "wx", 0o600);
+	try {
+		await handle.writeFile(contents, "utf8");
+		await handle.sync();
+		await handle.close();
+		try {
+			await link(temporary, destination);
+			return "created";
+		} catch (error) {
+			if ((error as NodeJS.ErrnoException).code === "EEXIST") return "exists";
+			throw error;
+		}
+	} finally {
+		await handle.close().catch(() => undefined);
+		await unlink(temporary).catch(() => undefined);
+	}
+}
+
+/**
+ * A human-readable id with a content-addressed tail.
+ *
+ * The ledger is read by people discussing a specific decision, so `DEC-2026-
+ * 0718-3f9a1c02` beats a bare digest in a meeting. The tail still binds the id
+ * to the approval it came from, so two decisions cannot collide on the same day.
+ */
+export function decisionIdFor(input: { actionId: string; strategyVersion: string; approvedAt: string }): string {
+	const date = new Date(input.approvedAt);
+	if (Number.isNaN(date.getTime())) throw new Error("approvedAt must be an ISO timestamp.");
+	const year = date.getUTCFullYear();
+	const monthDay = `${String(date.getUTCMonth() + 1).padStart(2, "0")}${String(date.getUTCDate()).padStart(2, "0")}`;
+	const tail = sha256(stableJson({ action_id: input.actionId, strategy_version: input.strategyVersion })).slice(0, 8);
+	return `DEC-${year}-${monthDay}-${tail}`;
+}
+
+export interface CreateDecisionPackageInput {
+	actionId: string;
+	strategyVersion: string;
+	handoffFingerprint: string;
+	title: string;
+	scopeId: string;
+	cycleId: string;
+	approverRole: string;
+	owner?: string | null;
+	approvedBudgetUsd?: number | null;
+	budgetThresholdPct?: number;
+	reportingCurrency?: string;
+	parameters?: Record<string, unknown>;
+	approvals?: DecisionApproval[];
+	tasks?: DecisionTask[];
+	memoRef?: string | null;
+	version?: string;
+	approvedAt?: string;
+}
+
+function validateApprovals(value: unknown): DecisionApproval[] {
+	if (value === undefined) return [];
+	if (!Array.isArray(value) || value.length > 16) throw new Error("approvals must be an array of at most 16 entries.");
+	return value.map((raw, index) => {
+		if (!raw || typeof raw !== "object" || Array.isArray(raw)) throw new Error(`approvals[${index}] must be an object.`);
+		const source = raw as Record<string, unknown>;
+		return {
+			step_order: finiteNumber(source.step_order, `approvals[${index}].step_order`),
+			role: boundedString(source.role, `approvals[${index}].role`, 128),
+			approver: boundedString(source.approver, `approvals[${index}].approver`, 128),
+			action: enumValue(source.action, ["approved", "acknowledged", "rejected"] as const, `approvals[${index}].action`),
+			decided_at: isoTimestamp(source.decided_at, `approvals[${index}].decided_at`),
+			...(optionalBoundedString(source.comment, `approvals[${index}].comment`) !== undefined
+				? { comment: optionalBoundedString(source.comment, `approvals[${index}].comment`) as string }
+				: {}),
+		};
+	});
+}
+
+function validateTasks(value: unknown): DecisionTask[] {
+	if (value === undefined) return [];
+	if (!Array.isArray(value) || value.length > 64) throw new Error("tasks must be an array of at most 64 entries.");
+	return value.map((raw, index) => {
+		if (!raw || typeof raw !== "object" || Array.isArray(raw)) throw new Error(`tasks[${index}] must be an object.`);
+		const source = raw as Record<string, unknown>;
+		return {
+			task_id: boundedString(source.task_id, `tasks[${index}].task_id`, 64),
+			task_name: boundedString(source.task_name, `tasks[${index}].task_name`, 256),
+			owner: boundedString(source.owner, `tasks[${index}].owner`, 128),
+			due_date: boundedString(source.due_date, `tasks[${index}].due_date`, 32),
+			status: enumValue(source.status, DECISION_TASK_STATUSES, `tasks[${index}].status`),
+			...(source.completed_at ? { completed_at: isoTimestamp(source.completed_at, `tasks[${index}].completed_at`) } : {}),
+		};
+	});
+}
+
+/**
+ * Write the package for a confirmed strategy. Idempotent: committing the same
+ * decision twice returns the existing package rather than minting a second one.
+ */
+export async function createDecisionPackage(cwd: string, input: CreateDecisionPackageInput): Promise<DecisionPackage> {
+	if (!SHA256_RE.test(input.actionId)) throw new Error("actionId must be a SHA-256 digest.");
+	if (!SHA256_RE.test(input.handoffFingerprint)) throw new Error("handoffFingerprint must be a SHA-256 digest.");
+	const approvedAt = input.approvedAt ?? new Date().toISOString();
+	const budgetThreshold = input.budgetThresholdPct ?? 0.1;
+	if (budgetThreshold < 0 || budgetThreshold > 1) throw new Error("budgetThresholdPct must be between 0 and 1.");
+	const approvedBudget = input.approvedBudgetUsd ?? null;
+	if (approvedBudget !== null) finiteNumber(approvedBudget, "approvedBudgetUsd");
+
+	const decisionId = decisionIdFor({ actionId: input.actionId, strategyVersion: input.strategyVersion, approvedAt });
+	const core = {
+		kind: "fpa.decision.package" as const,
+		schema_version: 1 as const,
+		decision_id: decisionId,
+		version: input.version ?? "v1",
+		title: boundedString(input.title, "title", 256),
+		scope_id: boundedString(input.scopeId, "scopeId", 256),
+		cycle_id: boundedString(input.cycleId, "cycleId", 256),
+		strategy_version: boundedString(input.strategyVersion, "strategyVersion"),
+		handoff_fingerprint: input.handoffFingerprint,
+		action_id: input.actionId,
+		owner: input.owner ? boundedString(input.owner, "owner", 128) : null,
+		approver_role: boundedString(input.approverRole, "approverRole", 128),
+		approved_budget_usd: approvedBudget,
+		budget_threshold_pct: budgetThreshold,
+		reporting_currency: input.reportingCurrency ?? "USD",
+		approved_at: approvedAt,
+		// The snapshot is sealed at the same instant it is approved: a gap
+		// between the two is a window in which the parameters could change.
+		locked_at: approvedAt,
+		parameters: input.parameters ?? {},
+		approvals: validateApprovals(input.approvals),
+		tasks: validateTasks(input.tasks),
+		memo_ref: input.memoRef ?? null,
+	};
+	const pkg: DecisionPackage = { ...core, package_fingerprint: sha256(stableJson(core)) };
+
+	const projectRoot = await realpath(cwd);
+	const artifactsDir = await ensureDirectory(projectRoot, "artifacts");
+	const packagesDir = await ensureDirectory(artifactsDir, PACKAGES_DIR);
+	const path = join(packagesDir, `${decisionId}.json`);
+	const write = await appendOnlyWrite(packagesDir, path, `${JSON.stringify(pkg, null, 2)}\n`);
+	if (write === "exists") {
+		const existing = await readDecisionPackage(cwd, decisionId);
+		if (existing.package_fingerprint !== pkg.package_fingerprint) {
+			throw new Error(`Decision package ${decisionId} already exists with different content.`);
+		}
+		return existing;
+	}
+	await appendDecisionEvent(cwd, {
+		decision_id: decisionId,
+		event_at: approvedAt,
+		actor: input.approverRole,
+		actor_type: "human",
+		event_type: "approved",
+		summary: `${input.approverRole} approved ${core.title}`,
+	});
+	await appendDecisionEvent(cwd, {
+		decision_id: decisionId,
+		event_at: approvedAt,
+		actor: "system",
+		actor_type: "system",
+		event_type: "parameters_locked",
+		summary: "Parameter snapshot locked; the approved parameters are now immutable.",
+	});
+	return pkg;
+}
+
+export function validateDecisionPackage(value: unknown, label = "decision package"): DecisionPackage {
+	if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error(`${label} must be an object.`);
+	const source = value as Record<string, unknown>;
+	if (source.kind !== "fpa.decision.package" || source.schema_version !== 1) throw new Error(`${label} kind or schema version is unsupported.`);
+	const decisionId = boundedString(source.decision_id, `${label}.decision_id`, 64);
+	if (!DECISION_ID_RE.test(decisionId)) throw new Error(`${label}.decision_id is malformed.`);
+	if (typeof source.package_fingerprint !== "string" || !SHA256_RE.test(source.package_fingerprint)) {
+		throw new Error(`${label}.package_fingerprint must be a SHA-256 digest.`);
+	}
+	const { package_fingerprint: fingerprint, ...core } = source;
+	if (sha256(stableJson(core)) !== fingerprint) throw new Error(`${label} fingerprint does not match its content.`);
+	return source as unknown as DecisionPackage;
+}
+
+export async function readDecisionPackage(cwd: string, decisionId: string): Promise<DecisionPackage> {
+	if (!DECISION_ID_RE.test(decisionId)) throw new Error("decisionId is malformed.");
+	const projectRoot = await realpath(cwd);
+	const path = join(projectRoot, "artifacts", PACKAGES_DIR, `${decisionId}.json`);
+	const stat = await lstat(path);
+	if (stat.isSymbolicLink() || !stat.isFile()) throw new Error("Decision package must be a regular file, not a symlink.");
+	if (stat.size > 512 * 1024) throw new Error("Decision package exceeds its 512KB limit.");
+	return validateDecisionPackage(JSON.parse(await readFile(path, "utf8")), `decision package ${decisionId}`);
+}
+
+export async function listDecisionPackages(cwd: string): Promise<DecisionPackage[]> {
+	const projectRoot = await realpath(cwd);
+	const packagesDir = join(projectRoot, "artifacts", PACKAGES_DIR);
+	let names: string[];
+	try {
+		names = await readdir(packagesDir);
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === "ENOENT") return [];
+		throw error;
+	}
+	const packages: DecisionPackage[] = [];
+	for (const name of names.filter((entry) => entry.endsWith(".json")).slice(0, 500)) {
+		const decisionId = name.slice(0, -".json".length);
+		if (!DECISION_ID_RE.test(decisionId)) continue;
+		packages.push(await readDecisionPackage(cwd, decisionId));
+	}
+	// Newest first: the decision someone is asking about is usually the last one.
+	return packages.sort((left, right) => right.approved_at.localeCompare(left.approved_at));
+}
+
+export async function appendDecisionEvent(cwd: string, event: Omit<DecisionEvent, "kind" | "schema_version">): Promise<DecisionEvent> {
+	if (!DECISION_ID_RE.test(event.decision_id)) throw new Error("decision_id is malformed.");
+	const record: DecisionEvent = {
+		kind: "fpa.decision.event",
+		schema_version: 1,
+		decision_id: event.decision_id,
+		event_at: isoTimestamp(event.event_at, "event_at"),
+		actor: boundedString(event.actor, "actor", 128),
+		actor_type: enumValue(event.actor_type, ["human", "system"] as const, "actor_type"),
+		event_type: enumValue(event.event_type, DECISION_EVENT_TYPES, "event_type"),
+		summary: boundedString(event.summary, "summary", 1_024),
+		...(optionalBoundedString(event.reason, "reason") !== undefined ? { reason: event.reason as string } : {}),
+		...(optionalBoundedString(event.change_detail, "change_detail") !== undefined ? { change_detail: event.change_detail as string } : {}),
+		...(event.estimated_impact_usd !== undefined ? { estimated_impact_usd: finiteNumber(event.estimated_impact_usd, "estimated_impact_usd") } : {}),
+	};
+
+	const projectRoot = await realpath(cwd);
+	const artifactsDir = await ensureDirectory(projectRoot, "artifacts");
+	const packagesDir = await ensureDirectory(artifactsDir, PACKAGES_DIR);
+	const path = join(packagesDir, `${event.decision_id}.events.jsonl`);
+	// Append with O_APPEND so concurrent writers interleave whole lines rather
+	// than overwriting each other's offsets.
+	const handle = await open(path, "a", 0o600);
+	try {
+		await handle.writeFile(`${JSON.stringify(record)}\n`, "utf8");
+		await handle.sync();
+	} finally {
+		await handle.close();
+	}
+	return record;
+}
+
+export async function readDecisionEvents(cwd: string, decisionId: string): Promise<DecisionEvent[]> {
+	if (!DECISION_ID_RE.test(decisionId)) throw new Error("decisionId is malformed.");
+	const projectRoot = await realpath(cwd);
+	const path = join(projectRoot, "artifacts", PACKAGES_DIR, `${decisionId}.events.jsonl`);
+	let raw: string;
+	try {
+		const stat = await lstat(path);
+		if (stat.isSymbolicLink() || !stat.isFile()) throw new Error("Decision event log must be a regular file, not a symlink.");
+		if (stat.size > 4 * 1024 * 1024) throw new Error("Decision event log exceeds its 4MB limit.");
+		raw = await readFile(path, "utf8");
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === "ENOENT") return [];
+		throw error;
+	}
+	const events: DecisionEvent[] = [];
+	for (const [index, line] of raw.split("\n").entries()) {
+		if (line.trim() === "") continue;
+		const parsed = JSON.parse(line) as DecisionEvent;
+		if (parsed.kind !== "fpa.decision.event" || parsed.schema_version !== 1 || parsed.decision_id !== decisionId) {
+			throw new Error(`Decision event log line ${index + 1} does not belong to ${decisionId}.`);
+		}
+		events.push(parsed);
+	}
+	return events.sort((left, right) => left.event_at.localeCompare(right.event_at));
+}

package/extensions/fpa-dashboard/index.ts

@@ -13,6 +13,8 @@ import {
 	transitionStrategyModule,
 } from "./module-publisher.ts";
 import { projectForecastModule, projectReviewModule, projectStrategyModule } from "./stage-projector.ts";
+import { projectDecisionLedger } from "./decision-ledger-projector.ts";
+import { listDecisionPackages, readDecisionEvents } from "./decision-package.ts";
 import type { ApprovedCycleForecast } from "../fpa-artifacts/contracts.ts";
 import { commitStrategyDecision, createStrategyDecisionRequest, readCommittedStrategyDecision } from "./strategy-decision.ts";
 import {
@@ -262,6 +264,71 @@ export default function fpaDashboardExtension(pi: ExtensionAPI): void {
 		},
 	});
 
+	pi.registerTool({
+		name: "fpa_dashboard_publish_decisions",
+		label: "Publish FP&A Decision Ledger Module",
+		description: "Preview or publish only the decision-ledger module from committed decision packages and their append-only event logs. Other dashboard modules are preserved.",
+		promptSnippet: "Publish the approved decision packages and their execution tracking",
+		promptGuidelines: [
+			"This tool is called by the main Agent; never add it to a Graph tool allowlist.",
+			"Preview first, then publish with the exact preview fingerprint and dashboard revision.",
+			"Supply measured spend only from an execution receipt or the actuals source. Never estimate it — an unmeasured decision must stay null, because a zero reads as 'nobody acted on this'.",
+		],
+		parameters: Type.Object({
+			mode: StringEnum(["preview", "publish"] as const),
+			expected_preview_fingerprint: Type.Optional(Type.String({ pattern: "^[a-f0-9]{64}$" })),
+			expected_dashboard_revision: Type.Optional(Type.Union([Type.String({ pattern: "^[a-f0-9]{64}$" }), Type.Null()])),
+			dashboard_title: Type.Optional(Type.String({ minLength: 1, maxLength: 256 })),
+			/** Measured spend per decision. Omitted decisions render as unmeasured. */
+			spend: Type.Optional(Type.Array(Type.Object({
+				decision_id: Type.String({ pattern: "^DEC-\\d{4}-\\d{4}-[a-f0-9]{8}$" }),
+				actual_spend_usd: Type.Union([Type.Number(), Type.Null()]),
+				progress: Type.Optional(Type.Union([Type.Number({ minimum: 0, maximum: 1 }), Type.Null()])),
+				source: Type.Optional(Type.String({ minLength: 1, maxLength: 512 })),
+			}, { additionalProperties: false }), { maxItems: 500 })),
+		}, { additionalProperties: false }),
+		executionMode: "sequential",
+		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+			const packages = await listDecisionPackages(ctx.cwd);
+			if (packages.length === 0) throw new Error("No decision packages exist yet; confirm a strategy before publishing the decision ledger.");
+			const events: Record<string, Awaited<ReturnType<typeof readDecisionEvents>>> = {};
+			for (const pkg of packages) events[pkg.decision_id] = await readDecisionEvents(ctx.cwd, pkg.decision_id);
+			const known = new Set(packages.map((pkg) => pkg.decision_id));
+			for (const entry of params.spend ?? []) {
+				if (!known.has(entry.decision_id)) throw new Error(`spend references unknown decision package ${entry.decision_id}.`);
+			}
+			const { module, breaches } = projectDecisionLedger({ packages, events, spend: params.spend ?? [] });
+			const previewFingerprint = dashboardModuleBuildFingerprint(module);
+			const current = await readDashboardModuleManifest(ctx.cwd);
+			if (params.mode === "preview") return toolResult({
+				status: "ready",
+				module_id: module.id,
+				preview_fingerprint: previewFingerprint,
+				dashboard_revision: current?.dashboardRevision ?? null,
+				widget_count: module.widgets.length,
+				package_count: packages.length,
+				threshold_breaches: breaches,
+				warnings: module.warnings ?? [],
+			});
+			if (params.expected_preview_fingerprint !== previewFingerprint) throw new Error("Decision ledger inputs changed after preview; preview again before publishing.");
+			if (params.expected_dashboard_revision === undefined) throw new Error("Publish requires expected_dashboard_revision from preview, including null for a new dashboard.");
+			const published = await publishDashboardModule({
+				cwd: ctx.cwd,
+				module,
+				dashboardTitle: params.dashboard_title,
+				expectedDashboardRevision: params.expected_dashboard_revision,
+			});
+			return toolResult({
+				status: "published",
+				module_id: module.id,
+				preview_fingerprint: previewFingerprint,
+				dashboard_revision: published.dashboardRevision,
+				module_revision: published.moduleRevision,
+				threshold_breaches: breaches,
+			});
+		},
+	});
+
 	pi.registerTool({
 		name: "fpa_dashboard_status",
 		label: "FP&A Dashboard Status",

package/extensions/fpa-dashboard/strategy-decision.ts

@@ -3,6 +3,7 @@ import { link, lstat, mkdir, open, readFile, realpath, unlink } from "node:fs/pr
 import { join } from "node:path";
 
 import { stableJson } from "../fpa-artifacts/store.ts";
+import { createDecisionPackage } from "./decision-package.ts";
 import { resolveDashboardDir } from "./publisher.ts";
 
 const SHA256_RE = /^[a-f0-9]{64}$/;
@@ -30,6 +31,21 @@ export interface CommitStrategyDecisionInput {
 	decision: "confirm" | "request_changes";
 	feedback?: string;
 	decidedAt?: string;
+	/**
+	 * Context for the decision package materialised on `confirm`. Optional so a
+	 * caller with no budget context still records the decision — the package
+	 * then carries a null budget and says so rather than inventing one.
+	 */
+	packageContext?: {
+		title?: string;
+		scopeId?: string;
+		cycleId?: string;
+		approverRole?: string;
+		owner?: string | null;
+		approvedBudgetUsd?: number | null;
+		budgetThresholdPct?: number;
+		parameters?: Record<string, unknown>;
+	};
 }
 
 export interface CommitStrategyDecisionResult {
@@ -38,6 +54,8 @@ export interface CommitStrategyDecisionResult {
 	decision: "confirm" | "request_changes";
 	strategyVersion: string;
 	handoffFingerprint: string;
+	/** Set only on `confirm` — a rejected strategy has nothing to track. */
+	decisionId?: string;
 }
 
 export interface CommittedStrategyDecision {
@@ -173,9 +191,62 @@ export async function commitStrategyDecision(cwd: string, input: CommitStrategyD
 			decision: existing.decision,
 			strategyVersion: request.strategy_version,
 			handoffFingerprint: request.handoff_fingerprint,
+			// The already-committed decision owns the timestamp. Re-deriving it
+			// here would change the package's content — and its id, across a UTC
+			// midnight — so a second submission would look like a different
+			// decision instead of the same one.
+			...(existing.decision === "confirm"
+				? { decisionId: await materialiseDecisionPackage(cwd, request, existing.decided_at, input.packageContext) }
+				: {}),
 		};
 	}
-	return { decisionFingerprint, path, decision: input.decision, strategyVersion: request.strategy_version, handoffFingerprint: request.handoff_fingerprint };
+	return {
+		decisionFingerprint,
+		path,
+		decision: input.decision,
+		strategyVersion: request.strategy_version,
+		handoffFingerprint: request.handoff_fingerprint,
+		...(input.decision === "confirm"
+			? { decisionId: await materialiseDecisionPackage(cwd, request, decision.decided_at, input.packageContext) }
+			: {}),
+	};
+}
+
+/**
+ * Turn a confirmed strategy into a trackable object.
+ *
+ * Runs after the decision record is durable, so a package can never exist for
+ * a decision that was not committed. `createDecisionPackage` is idempotent on
+ * the same inputs, which is what makes the re-commit path above safe to call.
+ */
+async function materialiseDecisionPackage(
+	cwd: string,
+	request: StrategyDecisionRequest,
+	decidedAt: string,
+	context: CommitStrategyDecisionInput["packageContext"],
+): Promise<string> {
+	const pkg = await createDecisionPackage(cwd, {
+		actionId: request.action_id,
+		strategyVersion: request.strategy_version,
+		handoffFingerprint: request.handoff_fingerprint,
+		title: context?.title ?? `执行策略 ${request.strategy_version}`,
+		scopeId: context?.scopeId ?? "unscoped",
+		cycleId: context?.cycleId ?? "uncycled",
+		approverRole: context?.approverRole ?? "CEO",
+		owner: context?.owner ?? null,
+		approvedBudgetUsd: context?.approvedBudgetUsd ?? null,
+		...(context?.budgetThresholdPct !== undefined ? { budgetThresholdPct: context.budgetThresholdPct } : {}),
+		parameters: context?.parameters ?? {},
+		approvals: [{
+			step_order: 1,
+			role: context?.approverRole ?? "CEO",
+			approver: context?.approverRole ?? "CEO",
+			action: "approved",
+			decided_at: decidedAt,
+		}],
+		approvedAt: decidedAt,
+	});
+	return pkg.decision_id;
 }
 
 export async function readCommittedStrategyDecision(cwd: string, actionId: string, decisionFingerprint: string): Promise<CommittedStrategyDecision> {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@viccydev/pi-fpa",
-  "version": "0.9.4",
+  "version": "0.9.5",
   "type": "module",
   "description": "Full-cycle FP&A planning, strategy, forecast, and review prompts, skills, and data tools for Pi",
   "license": "UNLICENSED",
@@ -34,9 +34,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/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": "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/decision-ledger.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/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: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/decision-ledger.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"