@viccydev/pi-fpa 0.3.3 → 0.4.0

package/README.md

@@ -115,7 +115,7 @@ pi install git:github.com/linyqh/pi-fpa@v0.3.2
 
 ## 发布到 npm
 
-发布动作由 GitHub Release 触发。Release 标签必须严格使用 `v<package.json version>`，例如版本 `0.3.3` 对应 `v0.3.3`。工作流会检出该标签，执行 `npm ci`、`npm test` 和包内容预检，全部通过后发布公开包 `@viccydev/pi-fpa`。普通 Release 发布到 `latest`，Prerelease 发布到 `next`。
+发布动作由 GitHub Release 触发。Release 标签必须严格使用 `v<package.json version>`，例如版本 `0.4.0` 对应 `v0.4.0`。工作流会检出该标签，执行 `npm ci`、`npm test` 和包内容预检，全部通过后发布公开包 `@viccydev/pi-fpa`。普通 Release 发布到 `latest`，Prerelease 发布到 `next`。
 
 首次发布前需要完成一次仓库配置：
 

package/extensions/fpa-artifacts/index.ts

@@ -1,7 +1,7 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 
-import { commitArtifact } from "./store.ts";
+import { commitArtifact, commitArtifactFromPath } from "./store.ts";
 
 function toolResult(value: Record<string, unknown>) {
 	return {
@@ -16,21 +16,34 @@ export default function fpaArtifactsExtension(pi: ExtensionAPI): void {
 		label: "Commit FP&A Artifact",
 		description:
 			"Validate, reconcile, fingerprint, and atomically commit a canonical FP&A artifact under the current project's artifacts directory. " +
-			"Use this instead of claiming a Markdown report is frozen. Supported v1 artifacts are approved_cycle_forecast and execution_receipt.",
+			"Use this instead of claiming a Markdown report is frozen. Supported v1 artifacts are approved_cycle_forecast and execution_receipt. " +
+			"Supply the artifact inline, or write it to a JSON file first and pass artifact_path — prefer the file for anything large.",
 		promptSnippet: "Validate and durably freeze a canonical FP&A artifact",
 		promptGuidelines: [
 			"Use fpa_artifact_commit before calling an approved forecast immutable or using it to publish a dashboard.",
 			"Do not supply immutable_fingerprint; the tool calculates it after validation and reconciliation.",
+			"Write a large artifact to a JSON file across turns and commit it with artifact_path; a single inline argument can be cut off at the model output limit.",
 		],
 		parameters: Type.Object(
 			{
-				artifact: Type.Unknown({ description: "Canonical artifact object matching the referenced FP&A artifact contract" }),
+				artifact: Type.Optional(Type.Unknown({ description: "Canonical artifact object matching the referenced FP&A artifact contract" })),
+				artifact_path: Type.Optional(Type.String({
+					minLength: 1,
+					description: "Project-relative path to a JSON file holding the canonical artifact. Mutually exclusive with artifact.",
+				})),
 			},
 			{ additionalProperties: false },
 		),
 		executionMode: "sequential",
 		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
-			const committed = await commitArtifact(ctx.cwd, params.artifact);
+			const hasInline = params.artifact !== undefined;
+			const hasPath = params.artifact_path !== undefined;
+			if (hasInline === hasPath) {
+				throw new Error("Supply exactly one of artifact or artifact_path.");
+			}
+			const committed = hasPath
+				? await commitArtifactFromPath(ctx.cwd, params.artifact_path as string)
+				: await commitArtifact(ctx.cwd, params.artifact);
 			return toolResult({
 				status: "committed",
 				artifact_type: committed.artifactType,

package/extensions/fpa-artifacts/store.ts

@@ -1,6 +1,6 @@
 import { createHash, randomUUID } from "node:crypto";
 import { lstat, mkdir, open, readFile, realpath, rename, unlink } from "node:fs/promises";
-import { join } from "node:path";
+import { isAbsolute, join, relative, resolve } from "node:path";
 
 import {
 	validateArtifact,
@@ -10,6 +10,8 @@ import {
 	type CanonicalArtifactInput,
 } from "./contracts.ts";
 
+export const ARTIFACT_MAX_BYTES = 2 * 1024 * 1024;
+
 export interface CommitArtifactResult {
 	artifactType: ArtifactType;
 	fingerprint: string;
@@ -58,6 +60,47 @@ async function existingArtifactDirectory(projectRoot: string): Promise<string> {
 	return artifactsDir;
 }
 
+/**
+ * Resolve a caller-supplied draft path inside the project.
+ *
+ * Same fail-closed posture as the committed artifacts themselves: no escaping
+ * the project root, no symlinks, no unbounded reads.
+ */
+async function resolveDraftPath(projectRoot: string, artifactPath: string): Promise<string> {
+	if (!artifactPath.trim()) throw new Error("artifact_path must be a non-empty path.");
+	const root = await realpath(projectRoot);
+	const resolved = resolve(root, artifactPath);
+	const relation = relative(root, resolved);
+	if (relation === "" || relation.startsWith("..") || isAbsolute(relation)) {
+		throw new Error("artifact_path must stay inside the project directory.");
+	}
+	const stat = await lstat(resolved);
+	if (stat.isSymbolicLink() || !stat.isFile()) throw new Error("artifact_path must point at a regular file, not a symlink.");
+	if (stat.size > ARTIFACT_MAX_BYTES) throw new Error(`artifact_path exceeds the ${ARTIFACT_MAX_BYTES / (1024 * 1024)}MB artifact limit.`);
+	return resolved;
+}
+
+/**
+ * Commit a canonical artifact an agent wrote to disk instead of passing inline.
+ *
+ * A full `approved_cycle_forecast` runs to tens of thousands of tokens, and
+ * emitting one as a single tool argument is exactly the shape that gets cut off
+ * at the model output limit — leaving the caller convinced it committed
+ * something it never did. A draft file can be written and corrected across as
+ * many turns as it takes, and this entry point keeps the validation,
+ * reconciliation, fingerprinting, and atomic write identical to the inline path.
+ */
+export async function commitArtifactFromPath(projectRoot: string, artifactPath: string): Promise<CommitArtifactResult> {
+	const path = await resolveDraftPath(projectRoot, artifactPath);
+	let parsed: unknown;
+	try {
+		parsed = JSON.parse(await readFile(path, "utf8"));
+	} catch (error) {
+		throw new Error(`artifact_path is not valid JSON: ${error instanceof Error ? error.message : String(error)}`);
+	}
+	return commitArtifact(projectRoot, parsed);
+}
+
 export async function commitArtifact(projectRoot: string, input: unknown): Promise<CommitArtifactResult> {
 	const artifact = validateArtifact(input);
 	if (artifact.artifact_type === "execution_receipt") {
@@ -98,7 +141,7 @@ export async function readCommittedArtifact(projectRoot: string, artifactType: A
 	const path = join(await existingArtifactDirectory(projectRoot), `${artifactType}.json`);
 	const stat = await lstat(path);
 	if (stat.isSymbolicLink() || !stat.isFile()) throw new Error(`${artifactType} must be a regular file, not a symlink.`);
-	if (stat.size > 2 * 1024 * 1024) throw new Error(`${artifactType} exceeds the 2MB artifact limit.`);
+	if (stat.size > ARTIFACT_MAX_BYTES) throw new Error(`${artifactType} exceeds the ${ARTIFACT_MAX_BYTES / (1024 * 1024)}MB artifact limit.`);
 	let parsed: unknown;
 	try {
 		parsed = JSON.parse(await readFile(path, "utf8"));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@viccydev/pi-fpa",
-  "version": "0.3.3",
+  "version": "0.4.0",
   "type": "module",
   "description": "Full-cycle FP&A planning, strategy, forecast, and review prompts, skills, and data tools for Pi",
   "license": "UNLICENSED",

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

@@ -29,7 +29,7 @@ If any requirement is missing, return `blocked` and make no external call. Never
 4. Present or record the dry-run result when the adapter supports it.
 5. Execute only the approved mutation set.
 6. Read back the resulting state and reconcile it with the requested state.
-7. Build the canonical `execution_receipt` using [artifact-contract.md](references/artifact-contract.md), then call `fpa_artifact_commit`.
+7. Build the canonical `execution_receipt` using [artifact-contract.md](references/artifact-contract.md), writing it to `artifacts/execution_receipt.input.json`, then commit it with `fpa_artifact_commit` using `artifact_path`.
 
 ## Stop conditions
 
@@ -37,4 +37,4 @@ Stop before or during execution on version mismatch, target ambiguity, budget mi
 
 ## Boundary
 
-Execution ends after reconciliation and a successful canonical receipt commit. A Markdown report is not an execution receipt. Do not continuously monitor performance. Performance review begins only when the next cycle's Actuals arrive and uses `$fpa-review-cycle`.
+Execution ends after reconciliation and a successful canonical receipt commit. A Markdown report is not an execution receipt, and neither is a written draft file — the receipt is frozen only when `fpa_artifact_commit` returns a fingerprint. Do not continuously monitor performance. Performance review begins only when the next cycle's Actuals arrive and uses `$fpa-review-cycle`.

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

@@ -40,3 +40,12 @@ blockers: []
 ```
 
 Only adapter responses or independently verified external evidence may populate `applied_mutations`, applied spend, external receipt IDs, and resulting-state evidence. `verification_status: verified` requires a passing reconciliation, resulting-state fingerprint, `executed_at`, and evidence plus applied spend for every receipt slice. A manual report remains `reported` until independently verified, and therefore cannot use `status: complete`. A blocked receipt must have no applied mutations, applied spend, or `executed_at`. Do not include `immutable_fingerprint`; `fpa_artifact_commit` supplies it after strict validation and durable storage.
+
+Pass this artifact by path, not inline:
+
+```
+write  artifacts/execution_receipt.input.json
+fpa_artifact_commit  { "artifact_path": "artifacts/execution_receipt.input.json" }
+```
+
+`artifact_path` is project-relative, must stay inside the project, and must be a regular file. Emitting a full receipt as one inline argument risks being cut off at the model output limit, which leaves nothing committed while the turn still reads as finished.

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

@@ -25,7 +25,37 @@ If approval evidence is absent, ambiguous, expired, conditional but unmet, or re
 3. Recalculate future-period operating outcomes from that allocation using the declared model.
 4. Provide downside, base, and upside values for each supported KPI.
 5. Reconcile allocation totals, formulas, and cross-metric identities.
-6. Build the canonical `approved_cycle_forecast` input using [artifact-contract.md](references/artifact-contract.md), then call `fpa_artifact_commit`.
+6. Build the canonical `approved_cycle_forecast` input using [artifact-contract.md](references/artifact-contract.md), writing it to `artifacts/approved_cycle_forecast.input.json`.
+7. Commit it with `fpa_artifact_commit` using `artifact_path`.
+
+## Why the draft file
+
+A full forecast is far too large to emit as a single inline tool argument: the
+call gets cut off at the model output limit, and what is left behind reads like
+a finished turn. Write the draft with the file tools instead — across as many
+turns and corrections as it takes — then commit the finished file by path. If a
+later step in this graph already commits the draft for you, stop after writing
+it and say so; do not claim a fingerprint you were not handed.
+
+## Status and the publish gate
+
+`status` describes the quality of what this forecast promised to deliver, not
+how much it promised.
+
+- Everything promised was delivered, and every approval condition is met → `complete`.
+- Something promised could not be delivered, or carries a known defect → `complete_with_limits`, with that item and its reason in `unsupported_metrics`.
+- Approval evidence is missing or mismatched → `blocked`.
+
+Work the planning stage explicitly placed outside this cycle's scope is neither
+a limit nor a defect: it does not belong in `unsupported_metrics` and does not
+downgrade `status`.
+
+This matters downstream: `fpa_dashboard_refresh` with `mode: publish` accepts
+only `complete`, so `complete_with_limits` blocks the dashboard. Do not
+misreport a narrowed scope as a limit and stall the publish, and do not hide a
+real defect to get through the gate. When something that was promised cannot be
+delivered, report `complete_with_limits` honestly and say that the scope
+declaration upstream needs correcting.
 
 ## Boundaries
 
@@ -36,4 +66,4 @@ If approval evidence is absent, ambiguous, expired, conditional but unmet, or re
 
 ## Completion
 
-The planning workflow ends only after `fpa_artifact_commit` returns `status: committed` and an `immutable_fingerprint`. A Markdown report is optional context, not the frozen source of truth. Execution, if requested, is a separate workflow using `$fpa-execute-approved-strategy`. Review waits for the next cycle's Actuals and uses `$fpa-review-cycle`.
+The planning workflow ends only after `fpa_artifact_commit` returns `status: committed` and an `immutable_fingerprint`. A Markdown report is optional context, not the frozen source of truth. Never report a forecast as frozen on the strength of a written file alone — the file is a draft until the tool returns a fingerprint. Execution, if requested, is a separate workflow using `$fpa-execute-approved-strategy`. Review waits for the next cycle's Actuals and uses `$fpa-review-cycle`.

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

@@ -43,4 +43,13 @@ reconciliation_checks: []
 frozen_at: timestamp
 ```
 
-Do not include `immutable_fingerprint` in the tool input. `fpa_artifact_commit` validates exact fields, approval state, allocation totals, every scenario's slice-to-consolidated totals, and supplied ROAS against aggregated revenue/spend. It computes the fingerprint and returns it after durable storage. The agent must not claim the artifact is frozen until that tool succeeds.
+Do not include `immutable_fingerprint` in the tool input; a draft that carries one is rejected. `fpa_artifact_commit` validates exact fields, approval state, allocation totals, every scenario's slice-to-consolidated totals, and supplied ROAS against aggregated revenue/spend. It computes the fingerprint and returns it after durable storage. The agent must not claim the artifact is frozen until that tool succeeds.
+
+Pass this artifact by path, not inline:
+
+```
+write  artifacts/approved_cycle_forecast.input.json
+fpa_artifact_commit  { "artifact_path": "artifacts/approved_cycle_forecast.input.json" }
+```
+
+`artifact_path` is project-relative, must stay inside the project, and must be a regular file. The inline `artifact` parameter still works and is fine for small artifacts, but a forecast of any real size will be truncated at the model output limit if you try to emit it in one call.