Planning artifacts have no recovery path when commit_docs: false (a subagent overwrote ROADMAP.md irrecoverably)

[ptdecker]

The concern

When commit_docs: false (and .planning/ is gitignored), there is no recovery path if a subagent makes a destructive write to a planning artifact. A single bad overwrite of ROADMAP.md, STATE.md, REQUIREMENTS.md, etc. is permanent, because there is no committed copy and no local snapshot to fall back on.

What happened (field report)

During an autonomous run (/gsd-autonomous --interactive) on a project configured with commit_docs: false, the gsd-planner subagent — invoked via /gsd-plan-phase <N> --gaps — overwrote .planning/ROADMAP.md with a fragment, then reconstructed the file from REQUIREMENTS.md, STATE.md, the phase SUMMARY.md files, and VERIFICATION.md. The reconstruction was structurally correct, but the original phase-goal prose and the progress-table dates were lost — they could only be approximated. Because .planning/ was gitignored, git checkout couldn't restore it, and there were no editor local-history entries for that path.

Why it happens

This isn't a permissions escalation — it's the absence of a guardrail. Every GSD subagent (planner, executor, roadmapper) runs with the same Write/Edit tools on the same working tree, and writing to .planning/ is expected behavior (the roadmapper creates ROADMAP.md; executors rewrite its progress table each phase). So two things stacked:

1. A behavioral slip — a planning agent rewrote ROADMAP.md wholesale when it should have made a targeted edit to the progress table.
2. No safety net — commit_docs: false removed the git copy that normally makes such a slip a one-command restore.

With commit_docs: true this is a non-issue (git is the backup). The gap is specific to the commit_docs: false configuration, which is otherwise a reasonable choice (and, for multi-developer/monorepo setups, sometimes the only workable one — see the companion discussion on concurrency).

Ideas

• Snapshot before destructive writes. When commit_docs: false, have the orchestrator copy planning artifacts to a local, non-gitignored backup (e.g. .planning/.backups/<timestamp>/) before a subagent step that may rewrite them. Cheap, local, and gives a restore point without involving git.
• Constrain planning agents to patch, not replace. A planner updating a progress table should append/patch rather than re-emit the whole ROADMAP.md. A full rewrite of a human-authored file by a planning subagent is almost never intended.
• Warn on wholesale rewrites. If a subagent's write to ROADMAP.md/REQUIREMENTS.md changes more than some threshold of lines, surface it for confirmation rather than applying silently.

Version note

Observed on the @opengsd/get-shit-done-redux 1.1.0 install; I see the latest release is v1.8.0. I haven't verified whether newer versions already snapshot planning artifacts or constrain planner writes — if this is already addressed, apologies for the noise, and a pointer to the relevant change would be appreciated. Raising it because the failure mode (irrecoverable planning-doc loss under commit_docs: false) is architectural enough that it seemed worth surfacing regardless.

[ptdecker]

Companion discussion on the multi-developer / monorepo concurrency half of this: #2542.