openspec update --dry-run --json: say what an update would change, without changing it #2088

The ask

Add a way to ask openspec update what it would change, without changing anything:

openspec update --dry-run --json

It prints the list of files it would add, change or delete. It writes nothing.

Why

OpenSpec Desktop shows people what an update will change before they agree to it.

Today the CLI can't tell us that. So the app does a workaround:

1. Copy the repository's agent folders (.claude, .cursor, …) into a temp folder
2. Run openspec update on the copy
3. Compare the copy before and after

This workaround keeps breaking:

• It's slow and can fail. Claude Code keeps whole copies of the repo in .claude/worktrees (81 GB on one machine). The copy hit its size limit, and the update check failed for every repository. Fixed for now in Fission-AI/openspec-desktop#100 by skipping that folder.
• It has to guess what to copy. If we copy too little, the preview is wrong and nobody notices. If we copy too much, it's slow or fails.

If the CLI tells us the plan itself, there's no copy, no size limit and no guessing.

What the output could look like

{
  "changes": [
    { "path": ".claude/skills/openspec-explore/SKILL.md", "action": "update", "tool": "claude" },
    { "path": ".claude/commands/opsx/old-name.md", "action": "delete", "tool": "claude" },
    { "path": "~/.codex/skills/openspec-propose/SKILL.md", "action": "add", "tool": "codex" }
  ]
}

It needs to:

• Cover every file update would touch, including files outside the repository (home-folder skills, OpenSpec's settings file).
• Write nothing.
• Give the same answer the real update would act on.

Done when

• openspec update --dry-run --json exists and writes nothing
• Its list matches what a real openspec update then changes (a test runs both and compares)
• OpenSpec Desktop can stop making scratch copies