docs: describe differences from gsd in readme

2026-10-18 00:13:14 +02:00
parent ec3f670162
commit e7ed5b4c9f
1 changed files with 33 additions and 0 deletions
--- a/README.md
+++ b/README.md
@@ -20,6 +20,39 @@ MSD Core is a context-engineering and spec-driven development framework that dri

 ---

+## Differences from GSD
+
+MSD Core is a hard fork of [GSD](https://github.com/open-gsd/gsd-core) (`gsd-core`). It contains all GSD changes up to the fork point (everything after GSD 1.14.0 shipped in MSD 2.0.0). The phase loop, workflows and `.planning/` artifacts work the same way. What differs:
+
+| | GSD | MSD |
+|---|---|---|
+| **Name** | `/gsd-*` commands, `gsd-tools` CLI, `gsd-core` package | `/msd-*` commands, `msd-tools` CLI, `@golem15/msd-core` package |
+| **Runtimes** | 18 runtimes | 6: Claude Code, Codex, OpenCode, Cursor, ZCode, Antigravity. The other 12 (including Kimi) were removed, together with their installer code, capabilities, hooks and docs |
+| **Distribution** | npm package | Not on npm. Installed with `curl -fsSL https://msd.golem15.com \| bash`, which clones, builds and installs from git |
+| **Releases and updates** | npm versions | `vX.Y.Z` git tags on `next`, with a `stable` branch pointing at the latest one. `/msd-update` and the update check read those tags and rerun the installer pinned to the chosen version. `/msd-update --next` also considers `-rc.N` tags |
+| **Hosting** | GitHub, with issue and PR governance | [git.golem15.com/golem15/msd-core](https://git.golem15.com/golem15/msd-core) (Gitea). PRs go against `next`, and GSD's issue and PR governance workflows were dropped |
+
+### Fixes that exist only in MSD
+
+**UAT verification loops (2.0.1).** In GSD, a phase whose human UAT had passed could loop forever between `/gsd-execute-phase` and `/gsd-verify-work`. A gap-closure plan, or a later phase editing a covered file, made the verification report stale. The re-run verifier could not see the UAT results and asked for human verification again, and execute-phase then rewrote `*-UAT.md` with every row back to `[pending]`. MSD fixes each link in that chain:
+
+- **The verifier reads recorded UAT results as evidence** (`verification.uat-evidence`). A row that passed on unchanged code counts as verified. Only rows whose covered implementation files changed since the UAT are requested again, each with a `retest_reason`.
+- **`*-UAT.md` is merged, never overwritten** (`verification.seed-uat`). Existing rows are kept byte-for-byte, and a pass is reset only with a recorded reason.
+- **One guarded `human_needed` → `passed` transition** (`verification.canonicalize-uat`). It applies only when the UAT rows are the only outstanding items, and it refuses a stale report.
+- **Stale reports are re-verified in place.** `verify-work` and `progress` re-run the verifier themselves instead of routing back to `execute-phase`. `verification.status` reports a `stale_reason`, and `progress` offers every executed-but-stale phase as one re-verify action.
+- **Gap-closure UAT answers are recorded first.** `execute-phase` writes a gap-closure checkpoint's UAT answers before it dispatches the verifier.
+
+Staleness still fails closed: a malformed fingerprint or a real change to covered code still marks the report stale.
+
+**Other fixes:**
+
+- **`/msd-update` and the update check work.** The inherited npm-based check looked for a package that was never published, so it never found an update. MSD reads git release tags instead.
+- **Plan-phase quota recovery.** `/msd-plan-phase` recovers safely when an agent run hits provider quota exhaustion.
+
+See [CHANGELOG.md](CHANGELOG.md) for the full 2.0.0 entry.
+
+---
+
 ## How it works

 Each milestone repeats the same five-step loop, one phase at a time: