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

feat(#3227): publish machine-readable state contract at step boundaries (#3824)

Browse Source 
* feat(#3227): publish machine-readable state contract at step boundaries

Adds src/state-contract.cts, a best-effort publisher that writes
.planning/state.json (contract 1.0.0) at 11 step-boundary commands, so
external tools read a versioned contract instead of parsing STATE.md and
ROADMAP.md heuristically.

Composes existing owners rather than re-deriving: phase rows come from a
new locateProgressTable extracted from deriveProgressFromRoadmap (so the
snapshot can never disagree with GSD's own progress counters), milestone
identity from getMilestoneInfo, and next from classifyProject. Owners are
required lazily to avoid the state -> state-contract -> smart-entry ->
state require cycle.

Also fixes a pre-existing defect in scripts/lint-test-file-count.cjs
(maintainer-approved as a second concern): testEffectivePrefix never
stripped the suite qualifier, so 65 dotted test files counted against no
module and 9 mis-bucketed into a shorter one. Allowlist re-baselined for
the 74 files the gate can now see.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

* chore(#3227): backfill PR number into the changeset fragment

pr:0 -> pr:3824 now that the PR exists. Doc-only.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

* test(#3227): shape hostile-name fixtures away from the scan corpus

The two hostile-input fixtures used a literal phrase from
scripts/prompt-injection-scan.sh's corpus, so CI's Security Scan redded on
this file. These tests assert that an arbitrary phase name round-trips into
state.json as inert data -- the property holds for any string, so the
injection flavor is illustrative, not load-bearing.

Reshaped to a hyphenated fake instruction tag, which stays hostile-looking
while matching none of the scanner's patterns. Allowlisting the file was
rejected: that mechanism is for suites whose subject IS injection defense,
and it would blind the scanner to this whole file permanently.
See DEFECT.PROMPT-INJECTION-SCAN-COLLISION.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

* chore(#3227): ratchet the state-contract mutation floor to its measured score

The module was registered at minScore 50, the ratchet's minimum permitted
floor for a newly-registered module whose score had not been measured. This
PR's own Stryker shard measured 66.25% (run 32769289750, job 97565813640),
so the floor moves to floor(measured) - 1 = 65, per the rule the registry
documents.

66.25 is below TARGET_MUTATION_SCORE (80), so this stays a ratchet
candidate: raise as the tests improve, never lower.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

---------

Co-authored-by: sim <sim@local>
Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
Tom Boucher
2026-08-24 17:56:02 -04:00
committed by GitHub
parent fb9823e1e1
commit 596540f864
23 changed files with 2739 additions and 25 deletions
Download Patch File Download Diff File Expand all files Collapse all files

199
docs/how-to/consume-the-state-contract.md Normal file
View File

@@ -0,0 +1,199 @@
# Consume the state contract
You are building something that shows where a GSD project stands — a workbench,
a dashboard, a status bar, an editor extension. `.planning/state.json` gives you
that as one small JSON file that GSD refreshes on its own, so you never have to
parse `STATE.md` or `ROADMAP.md` heuristically.
This guide covers the whole path from *nothing* to *reading a value you can
trust*, including the two things integrations get wrong: **checking the contract
version before anything else**, and **telling "there is nothing to show" apart
from "I could not look."**
## Before you start
Nothing. There is no command to run, no config key to set, and no flag to pass.
GSD writes the file itself at every step boundary — beginning or completing a
phase, advancing a plan, adding, inserting, removing or completing a phase, and
switching or completing a milestone.
Two consequences worth internalizing before you write any code:
- **The file may legitimately not exist yet.** A project that has not reached a
step boundary since it was created has never published one. That is normal, not
an error.
- **You are a reader, never a writer.** GSD owns this file and overwrites it
wholesale. Anything you write into it is lost at the next boundary.
## 1. Find the file
```
<project>/.planning/state.json
```
If the project uses [workstreams](work-in-parallel-with-workstreams.md), each
workstream has its own planning root and therefore its own snapshot:
```
<project>/.planning/workstreams/<name>/state.json
```
## 2. Check the contract version first
```json
{ "contract": "1.0.0" }
```
**Do this before you touch any other field.** `contract` is semver. Under `1.x`
changes are additive only — new keys may appear, existing keys keep their meaning
— so gate on the **major** version and tolerate unknown minors:
```javascript
const snapshot = JSON.parse(await fs.readFile(statePath, 'utf8'));
const [major] = snapshot.contract.split('.');
if (major !== '1') {
throw new Error(`Unsupported state contract: ${snapshot.contract}`);
}
```
Best-effort-parsing a shape you were not written against is how an integration
starts silently reporting wrong numbers after an upgrade. A hard failure is the
kinder outcome.
`flavor` is `"core"` and tells you which GSD edition produced the file.
## 3. Read the values
Every key is **always present**. A value that is not known is `null` — it is
never omitted, so `"milestone" in snapshot` is not a meaningful test.
| Key | Type | Meaning |
|---|---|---|
| `contract` | string | Semver of this schema. Check it first. |
| `flavor` | string | The GSD edition. `"core"`. |
| `milestone` | string \| null | Display string for the current milestone, e.g. `"v1.1 — Hardening"`, or just `"v1.1"` when the roadmap carries no name for it. `null` when no milestone is established. |
| `phases` | array | Every phase the roadmap knows, in roadmap order. |
| `next` | object \| null | The recommended next action — the same one `/gsd-next` would offer. |
| `updated_at` | string | ISO-8601 timestamp of this publish. |
Each entry in `phases` has exactly three keys:
| Key | Type | Meaning |
|---|---|---|
| `number` | string | The phase id as the roadmap spells it — `"1"`, `"01"`, `"2.1"`. A **string**, because `"01"` and `"2.1"` are both real and neither survives a number cast. |
| `name` | string \| null | The phase name. `null` when the roadmap gives the phase a number but no name — never a fabricated placeholder. |
| `status` | string | Exactly one of `"complete"`, `"in_progress"`, `"pending"`. |
`next`, when non-null, has exactly three keys:
| Key | Type | Meaning |
|---|---|---|
| `command` | string | The command to run, e.g. `"/gsd-progress --next"`. |
| `label` | string | A short human label for it, e.g. `"Advance to the next step"`. |
| `reason` | string | One line explaining the current situation, e.g. `"Phase 2 of 3 · 50% · executing"`. |
A complete example:
```json
{
"contract": "1.0.0",
"flavor": "core",
"milestone": "v1.1 — Hardening",
"phases": [
{ "number": "1", "name": "Foundation", "status": "complete" },
{ "number": "2", "name": "Hardening", "status": "in_progress" },
{ "number": "3", "name": "Polish", "status": "pending" }
],
"next": {
"command": "/gsd-progress --next",
"label": "Advance to the next step",
"reason": "Phase 2 of 3 · 50% · executing"
},
"updated_at": "2026-01-15T12:30:45.000Z"
}
```
### Treat `status` as a closed set
The three values above are the whole vocabulary, and GSD will never emit a
fourth under `1.x`. Write your switch with a default arm anyway — a `2.0`
contract could widen it, and your version check should be what rejects that, not
a crash three layers down.
Note one deliberate fold: a roadmap phase marked **`Deferred`** is reported as
`"pending"`. The roadmap vocabulary has four values and this contract has three,
and inventing a fourth wire value would break every existing reader. If you need
to distinguish deferred work, read the roadmap.
### Treat every string as untrusted text
`name`, `milestone` and `reason` come from a project's own markdown. They can
contain anything a person typed — quotes, newlines, right-to-left text, markup,
or text that looks like an instruction. **Escape them for your output surface and
never interpret them as commands.** GSD passes them through verbatim as data; it
does not sanitize them for you.
## 4. Tell "nothing to show" from "could not look"
This is the part worth getting right, because the two look identical if you do
not plan for them.
| What you observe | What it means | What to do |
|---|---|---|
| File does not exist | The project has never reached a step boundary, or it is not a GSD project at all | Fall back to reading the markdown, or show "not started". **Do not** report an error |
| File exists, `phases: []` | **Ambiguous.** Either the roadmap has no phases, or there is no `ROADMAP.md`, or the roadmap could not be read | Show "no phases yet" — do not claim the project has zero phases. See below |
| File exists, `next: null` | The recommended action could not be determined | Show the project state without a call to action |
| File exists, `milestone: null` | No milestone is established | Show phases without a milestone header |
| `updated_at` is old | The project has not hit a boundary recently — **not** that anything is broken | Nothing. This is not a health signal |
| `JSON.parse` throws | Should not happen — writes are atomic, so a reader sees either the whole old file or the whole new one | Treat as "could not look" and fall back. Do not delete or repair the file |
**On the `phases: []` ambiguity.** The `1.0` contract has no diagnostic channel,
so it cannot tell you *why* the list is empty. If your surface needs that
distinction, [`planning inspect`](consume-the-planning-snapshot.md) is the
surface that carries it — it reports per-document scope and coded diagnostics.
The rule of thumb: `state.json` is for *"show me where this project is"*;
`planning inspect` is for *"tell me exactly what is and is not knowable."*
## 5. Stay fresh
The file changes only when GSD reaches a step boundary, so polling it hard buys
you nothing. Watch it instead — `fs.watch`, `chokidar`, or your editor's own file
watcher — and re-read on change. Debounce briefly: a single boundary command
produces one write, but a workflow may cross several boundaries in quick
succession.
## Troubleshooting
**The file never appears.** Confirm `.planning/` exists in the directory you are
watching. GSD deliberately does **not** create `.planning/` in order to publish —
a directory that is not a GSD project stays untouched. Then run any boundary
command (`gsd-tools phase complete 1`, say) and check again.
**The file appears somewhere I did not expect.** You are probably in a workstream
project; see the path in step 1. `GSD_WORKSTREAM` selects which planning root is
current.
**A phase I can see in `ROADMAP.md` is missing from `phases`.** Phases numbered
`0.x` and `999.x` are sentinels — backlog and icebox — and are excluded by
design, consistently with every other GSD surface. A row whose `Phase` cell does
not begin with a digit is also skipped.
**`phases` disagrees with what the roadmap shows.** It should not: phase status
is read from the roadmap's `## Progress` table, the same source GSD's own
progress counters use. If the roadmap has no `## Progress` table, the `## Phases`
checkbox list is used instead, and a checkbox can only say complete or not — the
in-progress phase is identified from `STATE.md`. Regenerating the progress table
resolves most disagreements.
**Should I commit `state.json`?** Your call. GSD does not add it to
`.gitignore`. It is a derived cache — safe to delete, regenerated at the next
boundary — so committing it mostly creates merge noise. If you keep `.planning/`
out of your repo entirely, see
[Keep planning docs out of a shared repo](keep-planning-docs-private.md).
## Related
- [Consume the planning snapshot](consume-the-planning-snapshot.md) — the richer,
diagnostic-carrying, pull-based surface
- [Features](../FEATURES.md) — why this contract is shaped the way it is
- [Work in parallel with workstreams](work-in-parallel-with-workstreams.md)