golem15/msd-core
4
0
Fork 0
Code Issues 1 Pull Requests Actions Packages Projects Releases Wiki Activity

refactor: hard-fork GSD -> MSD (Make Software Done)

Browse Source 
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:
Jakub Zych
2026-10-06 01:47:40 +02:00
parent fe069b2a56
commit a9a7a328e6
2763 changed files with 78465 additions and 78434 deletions
Download Patch File Download Diff File Expand all files Collapse all files

44
docs/reference/state-md.md
View File

@@ -1,14 +1,14 @@
# STATE.md schema reference
`STATE.md` is GSD Core's living project-memory file — a single Markdown document that records where a project stands, what happened last, and what to run next. This page documents its structure. See [docs index](../README.md).
`STATE.md` is MSD Core's living project-memory file — a single Markdown document that records where a project stands, what happened last, and what to run next. This page documents its structure. See [docs index](../README.md).
---
## Overview
Every project managed by GSD Core keeps one `STATE.md` at `.planning/STATE.md`. It is read at the start of every workflow and written after every significant action. The file combines:
Every project managed by MSD Core keeps one `STATE.md` at `.planning/STATE.md`. It is read at the start of every workflow and written after every significant action. The file combines:
- **YAML frontmatter** — machine-readable fields consumed by the status-line hook (`parseStateMd`) and the `gsd-tools state` commands.
- **YAML frontmatter** — machine-readable fields consumed by the status-line hook (`parseStateMd`) and the `msd-tools state` commands.
- **Markdown body** — human-readable sections covering current position, accumulated context, session continuity, and performance metrics.
The file is intentionally small (target: under 100 lines). It is a digest of the project's state, not an archive.
@@ -17,13 +17,13 @@ The file is intentionally small (target: under 100 lines). It is a digest of the
## YAML frontmatter
Frontmatter appears between `---` delimiters at the very start of the file. All fields except `gsd_state_version` and `status` are optional; fields may be absent when their data is not yet available.
Frontmatter appears between `---` delimiters at the very start of the file. All fields except `msd_state_version` and `status` are optional; fields may be absent when their data is not yet available.
### Annotated example
```yaml
---
gsd_state_version: '1.0'
msd_state_version: '1.0'
milestone: v2.0
milestone_name: Code Quality
status: executing
@@ -56,7 +56,7 @@ paused_at: null
| Field | Type | When populated | Purpose |
|---|---|---|---|
| `gsd_state_version` | string (`'1.0'`) | Always | Schema version; written on first `state.*` call by `syncStateFrontmatter`. |
| `msd_state_version` | string (`'1.0'`) | Always | Schema version; written on first `state.*` call by `syncStateFrontmatter`. |
| `milestone` | string (e.g. `v2.0`) | When a milestone is configured | Current milestone version, read from the project's config. |
| `milestone_name` | string | When a milestone is configured | Human-readable milestone label (e.g. `Code Quality`). |
| `status` | string | Always | Current lifecycle stage. Normalised by `normalizeStateStatus()` — see [status values](#status-values). |
@@ -83,7 +83,7 @@ paused_at: null
| Field | Cardinality |
|---|---|
| `gsd_state_version` | one |
| `msd_state_version` | one |
| `milestone` | optional |
| `milestone_name` | optional |
| `current_phase` | optional |
@@ -114,7 +114,7 @@ paused_at: null
### Status values
`normalizeStateStatus()` in `gsd-core/bin/lib/state-document.cjs` maps raw body text to these canonical values:
`normalizeStateStatus()` in `msd-core/bin/lib/state-document.cjs` maps raw body text to these canonical values:
| Canonical value | Matched text (case-insensitive) |
|---|---|
@@ -130,10 +130,10 @@ When an orchestrator command is in flight, the convention (issue #2833) is to wr
| Command | `status` while in flight |
|---|---|
| `/gsd-discuss-phase` | `discussing` |
| `/gsd-plan-phase` | `planning` |
| `/gsd-execute-phase` | `executing` |
| `/gsd-verify-work` | `verifying` |
| `/msd-discuss-phase` | `discussing` |
| `/msd-plan-phase` | `planning` |
| `/msd-execute-phase` | `executing` |
| `/msd-verify-work` | `verifying` |
<!-- STATE-MD-SCHEMA:START:status-lifecycle — generated by scripts/gen-state-md-docs.cjs from src/state-md-schema.cts; do not edit by hand -->
### Status lifecycle (ADR-2207)
@@ -154,7 +154,7 @@ Phase-completion verbs never write `Milestone complete` (the overloaded bare val
## Status-line rendering scenes
`formatGsdState()` in `hooks/gsd-statusline.js` reads the parsed frontmatter and emits the **first matching scene**. If no new lifecycle fields apply, rendering falls through to the original format byte-for-byte unchanged from v1.38.x.
`formatMsdState()` in `hooks/msd-statusline.js` reads the parsed frontmatter and emits the **first matching scene**. If no new lifecycle fields apply, rendering falls through to the original format byte-for-byte unchanged from v1.38.x.
| Scene | Trigger | Display example |
|---|---|---|
@@ -163,11 +163,11 @@ Phase-completion verbs never write `Milestone complete` (the overloaded bare val
| **3. Milestone complete** | `percent` is `100` OR `completed_phases == total_phases` | `v2.0 [██████████] 100% · milestone complete` |
| **4. Default fallback** | None of the above match | `v1.9 Code Quality · executing · ph 1/5` (existing format) |
**Scene priority:** when both `active_phase` and `next_action` are populated, Scene 1 wins — an orchestrator is in flight, so a "next recommendation" would be misleading. This priority is enforced by check order in `formatGsdState()` and covered by the `"scene priority"` suite in `tests/gsd-statusline.test.cjs`.
**Scene priority:** when both `active_phase` and `next_action` are populated, Scene 1 wins — an orchestrator is in flight, so a "next recommendation" would be misleading. This priority is enforced by check order in `formatMsdState()` and covered by the `"scene priority"` suite in `tests/msd-statusline.test.cjs`.
When `phase_id_convention` is exactly `"bracket"` and `project_code` is set,
the full and compact renderers replace the legacy milestone/phase labels with
the canonical identity: `[GSD.02] · [GSD.02] 05.03 executing`. They do not emit
the canonical identity: `[MSD.02] · [MSD.02] 05.03 executing`. They do not emit
the `vX.Y`, `Phase`, or compact `P` labels on that gated path. Any other
convention, or a bracket config missing the metadata needed to form an ID,
falls back to the strings shown in the table above.
@@ -178,7 +178,7 @@ The progress bar (`[██░░░░░░░░] 20%`) is appended to the mil
## Frontmatter parsing constraints
The status-line hook uses regex-based parsing (no full YAML library), so the following constraints apply. They are tested in `tests/gsd-statusline.test.cjs`.
The status-line hook uses regex-based parsing (no full YAML library), so the following constraints apply. They are tested in `tests/msd-statusline.test.cjs`.
1. **Frontmatter must start at the very first character of the file.** Anything — including comments — above the opening `---` invalidates the match. The opening `---` line must be exactly that, with no trailing spaces.
@@ -192,7 +192,7 @@ If a future change replaces the regex parser with a full YAML library, these con
## Markdown body sections
The body (everything after the closing `---`) follows the template in `gsd-core/templates/state.md`. The standard sections are:
The body (everything after the closing `---`) follows the template in `msd-core/templates/state.md`. The standard sections are:
### Project Reference
@@ -216,7 +216,7 @@ Where the project stands right now:
Progress *history* does not belong here. It accumulates in [`### Performance Metrics`](#performance-metrics) below, which is the section designed to grow.
The `Status:` and `Last activity:` fields in this section are updated by GSD handlers when the existing value is a known template default (Knuth invariant: executor-authored values are preserved). The full list of known handler defaults is in `KNOWN_TEMPLATE_DEFAULTS` inside `gsd-core/bin/lib/state-document.cjs`.
The `Status:` and `Last activity:` fields in this section are updated by MSD handlers when the existing value is a known template default (Knuth invariant: executor-authored values are preserved). The full list of known handler defaults is in `KNOWN_TEMPLATE_DEFAULTS` inside `msd-core/bin/lib/state-document.cjs`.
### Performance Metrics
@@ -229,11 +229,11 @@ Updated after each plan completion.
### Accumulated Context
**Decisions** — a summary of recent decisions affecting current work (full log lives in `PROJECT.md`). Added via `gsd-tools state add-decision`.
**Decisions** — a summary of recent decisions affecting current work (full log lives in `PROJECT.md`). Added via `msd-tools state add-decision`.
**Pending Todos** — one bullet per pending todo (`- [date] [area] title — [todo file](repo-relative path) — Needs ...`, capped at 240 characters; repo-relative link keeps the cap independent of checkout path length). Captured via `/gsd-capture`.
**Pending Todos** — one bullet per pending todo (`- [date] [area] title — [todo file](repo-relative path) — Needs ...`, capped at 240 characters; repo-relative link keeps the cap independent of checkout path length). Captured via `/msd-capture`.
**Blockers/Concerns** — issues affecting future work, prefixed with the originating phase. Added via `gsd-tools state add-blocker`; resolved via `gsd-tools state resolve-blocker`.
**Blockers/Concerns** — issues affecting future work, prefixed with the originating phase. Added via `msd-tools state add-blocker`; resolved via `msd-tools state resolve-blocker`.
### Session Continuity
@@ -252,7 +252,7 @@ The phase-lifecycle fields (`active_phase`, `next_action`, `next_phases`, and `p
- Adding any lifecycle field is opt-in — the renderer degrades gracefully when fields are absent.
- The progress bar is opt-in even when the `progress` block exists: only `progress.percent` triggers the bar; `total_phases` and `completed_phases` alone do not.
The `formatGsdState #2833 backward compatibility` test suite in `tests/gsd-statusline.test.cjs` locks this guarantee; any change that breaks legacy `STATE.md` rendering will fail the suite.
The `formatMsdState #2833 backward compatibility` test suite in `tests/msd-statusline.test.cjs` locks this guarantee; any change that breaks legacy `STATE.md` rendering will fail the suite.
---