A working directory is disposable

[VeryComplexAndLongName]

Proposal and ADR only — no implementation. Independent of the two open proposals: they deliver shared-ui, this delivers ci-cli.

Why

C:\Prog used to hold repositories. It now holds seventeen entries, of which eleven are. One of the rest comes from this tool's default (<repo>.worktrees/<change>); the others have no .git at all and were made by something else. A new default will not tidy those, and this change does not pretend otherwise.

While looking, the larger half of the problem turned up.

A working directory's .openspec-ui/ is gitignored, so audit.jsonl — the run history every recommendation, timeline, cost figure and quality rating is derived from — cannot leave by commit. And git worktree remove without --force refuses uncommitted tracked work but does not see ignored files. Measured in a throwaway repository:

ignored .openspec-ui/audit.jsonl → git status: (clean)
git worktree remove (no --force)  → exit=0
audit.jsonl                       → GONE

The tool destroys its own evidence at the moment that evidence first becomes interesting — when the work is finished. So "where do these live" and "what has to leave one before it goes" are one question, and answering only the first would be choosing where to lose things.

The decisions (ADR 0027)

One root, at <root>/<repository>/<change> — one directory in a person's workspace folder for every repository instead of one beside each. Outside the repository, for the reason change-worktrees.ts already records: a second copy inside is what every recursive tool walks into.

Configured per machine, never in openspec/config.yaml. That file travels to every checkout, and one person's disk layout is not a fact about the project. A setting in the wrong file is a setting that arrives where nobody wanted it.

Not the system temporary directory. It was proposed, and the reasoning is sound as far as "these are disposable, and once their artifacts have been transferred the directory is worth nothing". It is rejected because of the once: the temporary directory is swept by Storage Sense, disk cleanup, anything deleting files past an age — and none of them can know whether the transfer happened. Deletion would be performed by the one mechanism unable to check the precondition for deleting safely. It would also bypass a refusal built on purpose, since a sweep refuses nothing where worktree remove refuses uncommitted work. Disposable is right; disposed of by the tool, after the transfer, is the part that has to stay true.

Removal harvests, then deletes. The directory's audit.jsonl merges into the repository's own first. Entries already carry their cwd and changeDir, so a combined log is unambiguous and de-duplicates by runId — harvesting twice adds nothing. Writes are unchanged: every run keeps writing to its own directory, which is what keeps two runs off one file.

What is not taken is named at the point of removal — the run journal, whose value expires when its runs end, and the checkpoints, whose purpose ends when the change archives. A destroyed thing that was announced is a decision; one that was not is a discovery, made later, by whoever needed it.

The log is the artifact. Asked what else should travel — timestamps, failures — both are already inside audit.jsonl: run identity, agent, agent version, timings, usage, outcome, summary. runTimestampsByChange, buildWorkspaceRunStats, buildVerifyQuality and the recommendations derive from it and nothing else.

Commits are not at risk, and saying so bounds the problem: a branch lives in the shared object store, so exactly two things can be lost — uncommitted work, which removal already refuses, and ignored files, which this change is about.

Not in this change

Tidying directories this tool did not create: what is in them is not known here, and acting on them would be acting on a guess. Changing how a run writes its log. Backing up a working directory.

Coordination

This delivers a ci-cli delta. Two proposals on another branch — a-doctor-says-what-would-stop-a-run and a-hint-says-what-can-run-together — deliver one too, and would meet this in openspec/specs/ci-cli/spec.md at archive. Proposals do not collide; implementations do. Noted at the top of tasks.md.

docs/adr/README.md will want a one-line conflict resolve against #419, whichever merges second.

🤖 Generated with Claude Code