* 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
@@ -3551,3 +3551,26 @@ See [Resolve verify-command path findings](how-to/resolve-verify-command-path-fi
|
||||
**Known limits:** convergence cycles stay sequential by design (`review → replan → re-review` has a genuine data dependency), so this speeds up each pass rather than reducing the number of passes; there is no concurrency bound, so every selected lane dispatches at once; and reviewer instances sharing one adapter dispatch concurrently against that single provider, which is the most likely way to hit a limit.
|
||||
|
||||
**Reference:** [Configuration](CONFIGURATION.md#parallel-reviewer-lanes-for-gsd-review-3034) · [Enable parallel reviewer lanes](how-to/enable-parallel-reviewer-lanes.md) · [Commands](COMMANDS.md)
|
||||
|
||||
### 166. Machine-Readable State Contract (`.planning/state.json`)
|
||||
|
||||
**Purpose:** External tools that display GSD project state — a workbench, a dashboard, an editor extension — had to parse `STATE.md` and `ROADMAP.md` heuristically. Those are human surfaces: their shape drifts as the templates evolve, and every consumer ends up carrying a brittle second parser that silently reports wrong numbers after an upgrade. GSD now publishes a small, versioned JSON snapshot instead, so the reader binds to a contract rather than to markdown (#3227).
|
||||
|
||||
**Behavior:** At every step boundary, GSD writes `.planning/state.json` — `contract`, `flavor`, `milestone`, `phases[]`, `next`, `updated_at`. The boundaries are `state begin-phase` / `planned-phase` / `advance-plan` / `complete-phase` / `milestone-switch`, `phase add` / `add-batch` / `insert` / `remove` / `complete`, and `milestone complete`. The write is best-effort and completely invisible to the command that triggered it: it cannot change an exit code, cannot change stdout, and cannot fail a workflow. Readers prefer the file when it is present and fall back to markdown when it is not.
|
||||
|
||||
**Requirements:**
|
||||
- REQ-SC-01: `contract` is semver, `1.0.0` at introduction. Consumers gate on the MAJOR version; `1.x` changes are additive only. Every key is ALWAYS present — an unknown value is `null`, never an omitted key, because an omitted key is itself an observable a consumer would bind to.
|
||||
- REQ-SC-02: `phases[]` carries `{number, name, status}` per phase, `status` drawn from exactly `complete | in_progress | pending`. `number` is a string (`"01"` and `"2.1"` are both real ids and neither survives a number cast); `name` is `null` when the roadmap gives a phase no name, never a fabricated placeholder.
|
||||
- REQ-SC-03: `next` is the same recommended action the `/gsd` front door routes, derived from the smart-entry classifier itself rather than from a second copy of its routing table.
|
||||
- REQ-SC-04: A missing `ROADMAP.md`, a missing or unreadable `.planning/`, an unwritable target, or any other failure NEVER errors the parent command. A directory that is not a GSD project stays untouched — the publisher will not create `.planning/` in order to publish into it.
|
||||
- REQ-SC-05: The skills own the file; readers never write it. It is a derived cache — safe to delete, regenerated at the next boundary.
|
||||
|
||||
**Composed, never re-derived.** Milestone identity comes from `getMilestoneInfo`; phase rows from `locateProgressTable`, the same `## Progress` locator the progress counters use, so `state.json` can never disagree with the rest of GSD about which phases are complete; the recommended action from `classifyProject`. This module introduces no second answer to any question GSD already answers.
|
||||
|
||||
**Why it does not reuse `planning inspect`'s schema.** The two surfaces answer different questions and have opposite shapes. `planning inspect` is a rich, diagnostic-carrying **pull** query a consumer runs; this is a small **push** artifact a consumer watches. Publishing `planning inspect`'s payload at every `phase add` would mean opening every plan, summary and requirements document on a hot path, and freezing a much larger surface as a contract.
|
||||
|
||||
**It costs up to three bounded git calls per boundary.** Deriving `next` from the smart-entry classifier means inheriting its git signals — `git status --porcelain`, and `git log @{u}..HEAD`. Each is timeout-bounded and swallows every error, so nothing can hang or fail because of it, but a command like `phase add` did not previously touch git at all. "Invisible to the parent command" is exact about exit code and output; it is not a claim about latency.
|
||||
|
||||
**Known limits:** an empty `phases: []` cannot be told apart from "no `ROADMAP.md`" or "roadmap unreadable" — the `1.0` schema carries no diagnostic channel, and `planning inspect` is the surface that does. A roadmap phase marked `Deferred` is reported as `pending`, because the roadmap vocabulary has four values and this contract has three; inventing a fourth wire value would break every existing reader. `phases[]` is not milestone-scoped, so a long-running project lists every phase it has ever had.
|
||||
|
||||
**Reference:** [Consume the state contract](how-to/consume-the-state-contract.md) · [Consume the planning snapshot](how-to/consume-the-planning-snapshot.md)
|
||||
|
||||
@@ -501,6 +501,7 @@
|
||||
"spec-section.cjs",
|
||||
"stale-bake-guard.cjs",
|
||||
"state-command-router.cjs",
|
||||
"state-contract.cjs",
|
||||
"state-document.cjs",
|
||||
"state-io.cjs",
|
||||
"state-transition.cjs",
|
||||
|
||||
@@ -631,6 +631,7 @@ Full listing: `gsd-core/bin/lib/*.cjs`.
|
||||
| `spec-section.cjs` | SPEC section-status helper (compiled from `src/spec-section.cts`, gitignored) — the single source of truth for the canonical SPEC headings (suffix-tolerant) and markdown-table row counting; `specSectionStatus`/`countSectionDataRows` decide per-section "supplied" for plan-phase's spec-less probe fallback, replacing ad-hoc awk (contract pinned by `tests/spec-section.test.cjs`) |
|
||||
| `stale-bake-guard.cjs` | Warns when configuration changes after a static-frontmatter runtime bake (#1688) |
|
||||
| `state-command-router.cjs` | Thin CJS subcommand router adapter for `gsd-tools state` |
|
||||
| `state-contract.cjs` | Machine-readable state contract v1 published to `.planning/state.json` at every step boundary (compiled from `src/state-contract.cts`, gitignored; #3227) — `buildStateContract(cwd, deps?)` is pure, `publishStateContract(cwd, deps?)` writes and never throws. `contract: "1.0.0"` is the wire version consumers gate on; frozen `PHASE_STATUS` (`complete`/`in_progress`/`pending`) and `PUBLISH_REASON` (`published`/`no_planning_dir`/`write_failed`) are the closed vocabularies. Composed from `locateProgressTable`, `getMilestoneInfo` and `classifyProject` so it can never disagree with GSD's own progress counters or front-door routing; owners are required lazily to avoid the `state → state-contract → smart-entry → state` require cycle. Best-effort by contract: it cannot change the exit code, stdout, or success of the boundary command that triggered it |
|
||||
| `health-diagnostic-rules/state-consistency.cjs` | Health-diagnostic rules: STATE.md consistency checks (W002, W011, W021, W026) against config/ROADMAP/disk, ported behavior-preserving from `cmdValidateHealth`; W024 (state_head freshness) is a documented gap, deliberately not migrated (ADR-3180 §8.2/§8.3/§8.5, Phase 11, #3309) |
|
||||
| `state-io.cjs` | Abstracts state IO modes — filesystem, sandboxed storage, or session log (#1680) |
|
||||
| `state-transition.cjs` | Implements the STATE.md field-classification table and the pure `transitionCore` mutation path (#1769) |
|
||||
|
||||
@@ -31,6 +31,7 @@ Language versions: [English](README.md) · [Português (pt-BR)](pt-BR/README.md)
|
||||
- [Resolve an ESLint glob-coverage finding](how-to/resolve-eslint-coverage-findings.md) — bring a source file that matches no lint rule under coverage, or record a reasoned exemption
|
||||
- [Read the statusline freshness marker](how-to/read-the-statusline-freshness-marker.md) — turn on `state ~N commits back`, and tell "STATE.md is fresh" apart from "freshness could not be established"
|
||||
- [Consume the planning snapshot](how-to/consume-the-planning-snapshot.md) — read `planning inspect` from a dashboard or harness, and tell "nothing to report" apart from "could not look"
|
||||
- [Consume the state contract](how-to/consume-the-state-contract.md) — read `.planning/state.json` from a workbench or editor extension, gate on the contract version, and tell "nothing to show" apart from "could not look"
|
||||
- [Keep planning docs out of a shared repo](how-to/keep-planning-docs-private.md) — make `.planning/` local-only, including untracking files git already tracks (the step `.gitignore` alone cannot do)
|
||||
- [Publish PRs without planning artifacts](how-to/publish-prs-without-planning-artifacts.md) — keep `.planning/` committed locally, so worktrees and `/gsd-undo` keep working, while `planning.pr_strict` keeps every planning path out of the branch you push
|
||||
- [Plan a phase](how-to/plan-a-phase.md) — run research, decompose work, and verify plan quality
|
||||
|
||||
199
docs/how-to/consume-the-state-contract.md
Normal file
199
docs/how-to/consume-the-state-contract.md
Normal 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)
|
||||
Reference in New Issue
Block a user