refactor: hard-fork GSD -> MSD (Make Software Done)
Mechanical rename produced by scripts/msd-rename.cjs: gsd/Gsd/GSD -> msd/Msd/MSD across contents and paths, upstream package/repo coordinates -> @golem15/msd-core and golem15com/msd-core. Deep links into upstream history, sibling upstream packages, the GSD-2 import feature, CHANGELOG.md and .changeset/ are kept as-is. Hand edits on top: MSD block-letter banner and logos, LICENSE copyright line, package/plugin identity, regenerated lockfile, install-tree fixtures, derived registries and benchmark baseline; migration checksum baseline re-locked (MSD keeps its own install state, so no install had applied the old sums); sort-order and regex-escaped expectations in tests adjusted.
This commit is contained in:
42
msd-core/references/planner-coupling.md
Normal file
42
msd-core/references/planner-coupling.md
Normal file
@@ -0,0 +1,42 @@
|
||||
# Planner Coupling — Same-Wave Shared Mutable State
|
||||
|
||||
> Progressive-disclosure reference for `agents/msd-planner.md`. The planner agent
|
||||
> reads this file when assigning waves (issue #3724). The slim pointer in
|
||||
> `agents/msd-planner.md` → `assign_waves` routes here; the canonical schema row
|
||||
> for `coupling_justified` lives in `docs/reference/plan-md.md`. The verifying
|
||||
> side is `agents/msd-plan-checker.md` Dimension 3b (#1954).
|
||||
|
||||
## The rule
|
||||
|
||||
`files_modified`/`files_deleted` overlap is not the only coupling between
|
||||
same-wave plans. If two plans in the same wave touch the same **mutable
|
||||
resource** through their task actions — a config key, DB table/row, migration,
|
||||
env var, singleton, cache — with at least one writer, or one plan produces a
|
||||
prerequisite the other consumes, the pair is coupled through shared state even
|
||||
though no file overlaps: under parallel execution the outcome depends on which
|
||||
executor gets there first.
|
||||
|
||||
Resolve it one of three ways, in order of preference:
|
||||
|
||||
1. **Declare the edge** — add the producing plan to the consumer's
|
||||
`depends_on`. Wave assignment then orders them automatically.
|
||||
2. **Re-wave** — move one plan to a later wave when the dependency direction
|
||||
is unclear but an ordering is still wanted.
|
||||
3. **Justify the pair** — when the coupling is deliberate and genuinely
|
||||
order-independent (both orders produce a correct result), record it in
|
||||
either plan's frontmatter, one `"plan-id: reason"` entry per coupled peer:
|
||||
|
||||
```yaml
|
||||
coupling_justified: ["03-02: both plans append independent keys to config; order irrelevant"]
|
||||
```
|
||||
|
||||
The plan-checker's Dimension 3b recognizes the declaration and does not
|
||||
flag the pair, so a deliberately coupled plan set passes verification
|
||||
without serializing waves it was designed to run in parallel.
|
||||
|
||||
## Why declare it up front
|
||||
|
||||
Dimension 3b flags same-wave plan pairs with an undeclared shared-mutable-state
|
||||
dependency (advisory severity — it never blocks). Declaring the edge, re-waving,
|
||||
or justifying the pair at plan time means the first checker pass comes back
|
||||
clean instead of surfacing an advisory the planner then has to interpret.
|
||||
Reference in New Issue
Block a user