Planning store (.planning/) has no concurrency model for multi-developer / monorepo use

[ptdecker]

The concern

The .planning/ store doesn't have a concurrency model, and neither value of commit_docs works well for a large, multi-developer monorepo:

• commit_docs: true — STATE.md and the ROADMAP.md progress table are rewritten on essentially every phase transition. When two developers advance phases in parallel against a shared, top-level .planning/, those files conflict constantly. They behave like a lock file that everyone edits — exactly the thing you don't want under version control in a busy repo.
• commit_docs: false — avoids the conflicts, but drops the shared planning intent out of the repo entirely (no one else sees the roadmap/requirements) and removes the recovery net (see companion discussion Planning artifacts have no recovery path when commit_docs: false (a subagent overwrote ROADMAP.md irrecoverably) #2541).

So in a monorepo with several developers, there's no configuration that gives you both shared, reviewable planning intent and conflict-free concurrent execution.

Root cause (as I see it)

.planning/ conflates three kinds of data that have opposite version-control needs:

1. Durable human intent — PROJECT.md, REQUIREMENTS.md, and the structure of ROADMAP.md. Low churn, authored deliberately, genuinely wants to be shared and reviewed → belongs in VCS.
2. Volatile machine state — STATE.md, the ROADMAP.md progress table, SUMMARY.md/VERIFICATION.md. High churn, rewritten mid-run, conflict-prone → behaves like a cache/lock.
3. Ephemera — checkpoints, review screenshots.

Because they live in one bucket toggled by a single commit_docs flag, you can only make the same VCS decision for all three, and there's no right answer for the set.

Ideas

• Split volatile state from durable intent so only category 1 is versioned by default, and category 2 can be local/ignored without losing shared planning.
• Make progress derived or append-only rather than a rewritten shared table — an append-only event log per phase merges cleanly; a rewritten table does not.
• Scope planning roots per team/workstream rather than one top-level .planning/, so independent teams in a monorepo don't write to the same files. GSD already has workstreams and a sub_repos config, but as far as I can tell neither actually resolves concurrent writes to a shared STATE.md/ROADMAP.md.

Questions for maintainers

• Is a multi-developer / monorepo story on the roadmap, or is GSD's design deliberately scoped to a single planner-of-record per .planning/ root?
• Do workstreams / sub_repos already address concurrent phase execution in ways I've missed?

Version note

Observed reasoning is against the @opengsd/get-shit-done-redux 1.1.0 install; latest release appears to be v1.8.0. If newer versions already separate volatile state from durable intent, or otherwise address monorepo concurrency, I'd be glad to be pointed at it. Companion discussion on the recovery half of this: #2541.

[aturleyIdeem]

I'm very curious about this as well. GSD is a very useful tool for a single developer, and it does a lot of things for us that we should be doing anyway like capturing decisions, documenting dependencies, etc. But with the current structure and behavior it feels difficult to even try to add a second developer to a project.

[ericknyoto]

What I did on my developer teams on a brownfield project with 6 developers.

1. We keep .planning/codebase and commit for teams.
2. Phases, roadmap, project, state only live on development cycle. When development cycle end, this document should be moved to another place (e.g Gdrive), it shouldn't be commited.
3. We use ADR document, to record all decisions there.

[deinspanjer]

I also have a related question, but with a simple focus on just looking at contributing to gsd-core as a reasonable example.
I'm going to go ahead and open a separate discussion thread, but I do acknowledge it and this thread have a lot of overlap.