[wan9chi]

Motivation

Once the work in #929 lands, vp run caches tasks that read and rewrite their own files without exclusions in cache.input or cache.output.

Humans and AI agents will need to see why a task missed, and what it was checked against, more than before.

Today there is also no way to ask what a run would do, or whether it would hit the cache, before running it (#791, voidzero-dev/vite-plus#2848), or to get the task graph without parsing the task list (#320, voidzero-dev/vite-plus#1182).

Two RFCs:

• docs/rfcs/task-graph-json.md: vp run --json prints every package and task in the workspace, and the dependsOn edges between tasks.
• docs/rfcs/dry-run.md: --dry-run stops before running anything, --json prints the plan as JSON, and -v/-vv make the cache check list every change and everything the cached run depends on.

---

Note

Low Risk
Documentation-only RFCs; they describe proposed CLI and JSON formats but do not change product code in this PR.

Overview
Adds two design RFCs under docs/rfcs/ that specify future vp run behavior for tooling and agents—no runtime changes in this PR.

task-graph-json.md defines vp run --json (no task): a versioned TaskGraph document with packages, tasks keyed by task ID, dependsOn edges, shared conventions (paths, $schema, absent fields, output rules), and which flag combinations are errors (e.g. --json with -r or --dry-run without a task).

dry-run.md defines --dry-run (plan + cache checks without executing or writing), --dry-run --json as a RunPlan with per-step cache status (hit / changed / unknown / noBaseline / etc.), structured changes, optional changesPartial, and -vv fingerprints/outputs. It also specifies behavior changes when implemented: -v/--verbose as a counted flag, and real runs with -v listing all cache miss reasons instead of stopping at the first file difference.

^{Reviewed by Cursor Bugbot for commit 408b97b. Bugbot is set up for automated code reviews on this repo. Configure here.}

[github-actions]

fspy benchmark

linux

dynamic/launch             change  +0.84%  [ -2.57% ..  +4.35%]  overhead   +56.25%
dynamic/access             change  +0.00%  [ -4.39% ..  +2.92%]  overhead   +22.39%
dynamic/access-relative    change  +0.61%  [ -2.94% ..  +2.71%]  overhead   +71.66%
dynamic/access-contended   change  +2.19%  [ -3.28% ..  +6.98%]  overhead   +45.34%
static/launch              change  +0.06%  [ -2.81% ..  +2.54%]  overhead  +187.37%
static/access              change  +0.24%  [ -1.07% ..  +1.40%]  overhead +1453.67%
static/access-relative     change  -0.17%  [ -1.53% ..  +1.48%]  overhead +1985.61%
static/access-contended    change  -0.31%  [ -1.33% ..  +1.74%]  overhead +2069.27%

macos

dynamic/launch             change  -0.44%  [ -6.23% ..  +4.79%]  overhead  +227.72%
dynamic/access             change  +0.01%  [ -3.06% ..  +3.96%]  overhead    +3.55%
dynamic/access-relative    change  -1.20%  [ -3.91% ..  +3.26%]  overhead  +250.18%
dynamic/access-contended   change  +2.34%  [ -4.30% ..  +6.39%]  overhead    +2.77%

windows

dynamic/launch             change  +0.36%  [ -4.28% ..  +3.64%]  overhead   +30.54%
dynamic/access             change  +0.00%  [ -3.35% ..  +1.97%]  overhead    +1.62%
dynamic/access-relative    change  +0.20%  [ -3.02% ..  +8.70%]  overhead    +1.41%
dynamic/access-contended   change  +0.59%  [ -2.78% ..  +3.32%]  overhead    +1.58%

[wan9chi]

@jasonkuhrt Thanks for the feedback. It's a very valid concern but also complex to implement. I'd prefer to do it in another RFC.

To avoid confusion in this RFC, I've added unknown status if any previous step misses cache or hit with outputs to restore.

[fengmk2]

LGTM