Files

Tom Boucher ddde001af6 enhance(#3873 ): the STATE.md schema — one owner, generated artifacts (#3880 )

* test(#3873): failing-first locale parity, plus tripwires for what must not move

Pins ADR-3473 §8.8 at the artifact a reader actually sees. The English STATE.md
reference carries a Status lifecycle section that is missing from all four
translations — the section documenting the status enum whose clobbering is
#3853. The test derives the heading set rather than hard-coding the missing
one, and names the locale and the heading when it fails.

Two tripwires that must pass today and after. The field-drift guard still
catches a re-derived fallback ladder: §8.8 instructs deleting that script, and
that instruction rests on a wrong premise about what it guards, so the test
stops a future reader from deleting it on the ADR's word. And last_activity's
label resolution is pinned to what ships today, because it is declared in one
of the two tables this phase consolidates and not the other — the
consolidation must not silently pick a side.

The locale test buckets under docs rather than state, which is what it tests;
that bucket is allowlisted with justification rather than folded into an
unrelated docs suite. It reads only markdown, so it carries no allow-test-rule
marker — a marker there would suppress nothing and would grow the unverified
pool against its ceiling.

Refs #3873

* feat(#3873): one schema owns the STATE.md key set, three tables become projections

ADR-3473 §8.8. The key set was declared in four places that had to agree by
hand and already did not: FIELD_CLASSIFICATION, FRONTMATTER_BODY_SOURCE,
FRONTMATTER_KEY_TO_BODY_LABEL and buildStateFrontmatter's emit behavior. One
frozen null-prototype schema now declares each key's type, enum, cardinality,
source, preservation, body source, body label, accepted parse shapes and
whether it is emitted unconditionally; the three tables are derived from it at
module load.

The projections are byte-identical to the literals they replace, key order
included, and the parity tests compare against verbatim copies of today's
tables rather than re-deriving both sides from the schema — a parity test fed
from one source proves nothing, which is how a consolidation ships a changed
policy under a green test.

last_activity was the live disagreement: present in one table, absent from the
other. The schema declares what ships today rather than the tidier answer, and
a test pins it.

The schema is a leaf module and owns the four field-policy types, re-exported
from state-transition so existing importers are untouched — the same split
health-diagnostic-types made to break a CJS require cycle.

Refs #3873

* feat(#3873): generate the schema-derived regions, parity-check the prose tables

ADR-3473 §8.8's generator half. gen-state-md-docs.cjs owns marked regions in
the shipped template and all five reference docs, follows gen-features.cjs's
fail-closed contract, and is wired into regen:derived and lint:generated-sync.

The Status lifecycle section was missing from all four translations — the
section documenting the status enum behind #3853 — and is now generated into
every locale. Field cardinality is a new generated table: pure schema data,
no prose, so nothing to lose.

The Field-reference and Status-values tables are parity-CHECKED rather than
generated. Their Purpose, When-populated and Matched-text columns are
genuinely hand-translated per locale, and §8.8 itself says prose stays
hand-translated; generating them from an English registry would overwrite four
locales' translations on every write. The row set is checked against the schema
instead, so a key added to one and not the other fails, which is what field
drift actually means. Building that check found last_activity_desc
undocumented in all five tables.

Three keys the docs describe are absent from the schema — active_phase,
next_action, next_phases. They are grandfathered by name, not by wildcard, so a
fourth fails: a declared gap with a forcing function rather than a silent one.

Refs #3873

* fix(#3873): declare what the parsers do, and close the shape-parity gap

Two declarations in the new schema described intended behavior rather than
actual — the defect class this epic exists to end, committed inside the epic.
Both were caught by executing the parsers instead of reading their docstrings.

current_plan.acceptedShapes claimed ['N', 'N of M']. Standalone, the hybrid
shape errors; the path that looks like support is parseInt truncating '2 of 5'
to 2 and discarding the rest. Narrowed to ['N']. The parser is deliberately NOT
fixed here: that is #3784 and PR #3791 is already doing it. When #3791 lands
this row must widen, and the shape test will go red until it does — the schema
and the parser cannot drift apart quietly, which is what §8.8's checked-not-
generated rule is for.

STATUS_LIFECYCLE_ENUM claimed to be the closed set status can hold.
normalizeStateStatus passes unrecognized prose through unchanged, so it is not
closed at runtime. The seven members are the canonical values it maps onto; the
docstring now says that and the test asserts the real lenient contract.

Closes the acceptance item that a test asserts the parsers accept exactly the
declared shapes: the check is table-driven over every row carrying
acceptedShapes, guarded against passing vacuously on an empty set, and fails
loudly if a future row has no registered driver. Adds the unwired-label throw
and the fast-check property that every projection agrees with its schema row.

Refs #3873

* fix(#3873): keep the shipped template's frontmatter first, and make row 27 able to fail

The remote matrix caught 12 failures with one cause. Making the template's
frontmatter a generated region wrapped it in its own yaml fence ahead of the
markdown fence, so extractFileTemplate and readShippedStateTemplateBody — which
both match the single markdown block — found the heading first, not the
frontmatter. That breaks the contract every new project's STATE.md is created
from: bug #21 and epic #1969 B8 pin that the File Template block starts with
frontmatter and carries gsd_state_version.

The markers now sit inside the single markdown fence, so the fence opens before
the frontmatter and the region still ends ahead of the heading. Same layout as
before this phase, with markers embedded rather than a second fence.

Row 27 existed to catch exactly this and did not, because it was writer-seeded:
it asserted against the generator's own output shape, so it passed on the broken
template. It now parses the fence the way production does and was verified to
fail against the broken shape before being trusted against the fixed one. A test
that would not have caught the bug it exists to prevent is worse than no test.

The emitted-attribution failure was separate and the fragment was the wrong
remedy: gsd-core/templates/state.md self-attributes under a verbatim-copy
identity rule, so a diff touching it needs no acknowledgment. Fragment deleted
rather than left explaining nothing.

Refs #3873

* docs(#3873): how to change the STATE.md schema

The phase gate was right and my docs artifact was wrong. I listed
lint:generated-sync as the second enablement step, which is a verification
command dressed as one, and then claimed a one-step sequence owed no how-to.

The real sequence is build:lib then regen:derived, and the ordering is a trap:
the generator reads the COMPILED schema, so regenerating before building
regenerates against the previous schema and commits artifacts that look
plausible while disagreeing with the code just written. A reference table
cannot carry an ordering dependency; that is what the how-to test is for.

The page covers adding, changing and removing a key, every reason code the
check emits and what to do about each, what is generated versus hand-translated
and why the two prose-bearing tables are parity-checked instead of generated,
adding a language, and the three grandfathered keys. Indexed from docs/README.md.

Refs #3873

* chore(#3873): backfill changeset PR number

---------

Co-authored-by: sim <sim@local>

2026-08-26 01:57:47 -04:00

14 KiB

Raw Blame History

GSD Core documentation

Documentation is organised into four quadrants: tutorials help you learn by doing, how-to guides solve specific tasks, reference states authoritative facts, and explanation explores concepts and design decisions.

Language versions: English · Português (pt-BR) · 日本語 · 简体中文

Tutorials

Your first project — install to first shipped phase, one guaranteed path
Onboarding an existing codebase — bring GSD Core to a brownfield repo
Build your first capability — author a tiny declarative capability and watch it act in the loop
Install your first capability — install a third-party capability end-to-end: consent, verify, check for updates, remove

How-to guides

Install on your runtime — runtime-specific install steps for all 16 supported runtimes
Install a minimal GSD and add skills later — install only the core skills, then grow the surface with profiles and /gsd-surface
Attach a plugin-provided skill to a GSD agent — use the global:plugin:skill entry form to load Claude Code plugin skills into agent prompts
Discuss a phase — capture implementation decisions before planning begins
Resolve edge-coverage findings — turn the spec phase's surfaced domain-boundary edges into covered, dismissed, or backstopped spec decisions
Probe edges in a non-English project — get real edge coverage on a spec written in another language, and tell "no edges here" apart from "the probe could not read it"
Resolve prohibition findings — turn the spec phase's surfaced must-NOT constraints into resolved, dismissed, or deferred spec decisions
Resolve an unreachable-workflow finding — wire or fully sweep a shipped workflow that no command, agent, or skill references
Change the STATE.md schema — add, change or remove a STATE.md frontmatter key and keep the template and all five reference documents in step
Resolve verify-command path findings — fix an <automated> verify command whose target directory does not resolve from the executor's cwd
State a failing direction — say what output constitutes failure for an <automated> verify command, and migrate a phase planned before the rule
Resolve a contract-drift finding — bring an agent's completion contract, read-tag gate, or deleted-file test reference back into agreement with the registry
Resolve unreachable-guard findings — fix shell guards whose fallback arm cannot run, and tell "nothing to report" apart from "could not look"
Diagnose which gsd-tools is running — tell this package's tool apart from the predecessor's colliding binary and from a gsd-core too old to identify itself
Resolve an ESLint glob-coverage finding — bring a source file that matches no lint rule under coverage, or record a reasoned exemption
Read the statusline freshness marker — turn on state ~N commits back, and tell "STATE.md is fresh" apart from "freshness could not be established"
Consume the planning snapshot — read planning inspect from a dashboard or harness, and tell "nothing to report" apart from "could not look"
Consume the state contract — 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 — make .planning/ local-only, including untracking files git already tracks (the step .gitignore alone cannot do)
Publish PRs without planning artifacts — 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 — run research, decompose work, and verify plan quality
Verify a dependency-compatibility claim — act on a compatibility claim the researcher left [ASSUMED], and tell "nothing declared" apart from "a constraint is declared" and "the lookup failed"
Execute a phase — run plans in parallel waves with fresh-context subagents
Enable parallel reviewer lanes — cut a multi-reviewer /gsd-review pass toward its slowest lane, and tell a rate-limited lane apart from one that was never selected
Verify and ship — walk through completed work, diagnose failures, and create the PR
Catch complexity before it compounds — enable the post-execute refactor hook, read a proposal's score vs. anchor delta, and accept or decline it
Run phases autonomously — use autonomous mode for unattended phase execution
Handle quick and fast tasks — use /gsd-quick and /gsd-fast for ad-hoc work outside the phase loop
Configure model profiles — switch between quality, balanced, and budget model tiers
Control which host runtime GSD reports — read the agent_runtime ladder, understand what host detection looks at, and pin the runtime when detection is not what you want
Set up cross-AI review — configure a second AI to review code produced by the primary agent
Scope code review depth by path — escalate /gsd-code-review to deep for sensitive directories while the rest of the repo stays at the default depth
Work in parallel with workstreams — run independent lines of work simultaneously using workstreams
Isolate work with workspaces — use workspaces to sandbox experimental or risky changes
Debug a failed execution — diagnose and recover from broken or incomplete phase execution
Interpret scope-conformance warnings — read the advisory the worktree-wave merge emits when a plan branch commits outside its declared scope
Interpret install-shadow warnings — read the advisory GSD Core emits when a /gsd-* trigger is installed at both scopes and one silently wins, and tell "nothing to report" apart from "could not look"
Interpret state validate results — read the scope reason codes and tell "nothing to report" apart from "could not look"
Spike and sketch — use /gsd-spike and /gsd-sketch for exploratory work before committing to a plan
Design a UI phase — use the UI phase loop for frontend and visual work
Enable live-DOM verification — opt a project into browser-backed UI acceptance checks during execution, handle the browser-profile lock, and tell "nothing to report" apart from "could not look"
Develop a Capability for GSD 1.5+ — add feature Capabilities, hook fragments, and registry entries
Ship a reviewer lane in your capability — declare a reviewer body so /gsd-review discovers, invokes, and renders your external review CLI or model endpoint
List your reviewer lane in the registry — publish a lane you have built to the Reviewer Lane Registry so other people can find and install it
Take over a capability or EoS integration — assume maintainership of an existing third-party capability, reviewer lane, or EoS host integration through a handoff, an adoption fork, first-party absorption, or a de-listing
Add or update a host's integration — set a host's documentation-sourced runtime.hostIntegration axes (ADR-1239 Phase A), with the undocumented sentinel rule
Migrate an install test to the executed plan — convert an fs.existsSync-probing install test group to a value assertion against installRuntimeArtifacts's executed-plan return, and test against a fake fs adapter
Turn a capability off (and keep it off) — disable a capability via the surface, or gate individual hooks off without removing the capability
Drive GSD from a tracker issue — start a phase from a GitHub, Linear, or Jira issue
Migrate from GSD 2 — upgrade an existing GSD 2 project to GSD Core
Update GSD — re-run the installer to pick up the latest release
Clean up get-shit-done-cc — remove leftover old-package artifacts that cause a spurious ⬆ /gsd-update indicator after migrating to @opengsd/gsd-core
Fix the worktree base-mismatch (exit 42) error — resolve the branch-divergence condition that halts parallel phase execution
Recover and troubleshoot — fix common problems, rebuild context, and uninstall

Reference

Commands — every command with flags and examples
Configuration — full config schema, model profiles, git branching strategies
CLI tools — gsd-tools.cjs programmatic API for workflows and agents
JSON error mode — gsd-tools failure channels: faults (stderr, exit 1) vs degraded results (stdout, exit 0), and the reason-code taxonomy
Features — complete feature index
Inventory — installed skills and surface map
STATE.md schema — field-by-field reference for .planning/STATE.md
CONTEXT.md schema — field-by-field reference for .planning/phases/<N>/CONTEXT.md
PLAN.md schema — field-by-field reference for .planning/phases/<N>/PLAN.md
Planning artifacts — all .planning/ files and their roles
Review and verification capabilities — code review, security, and Nyquist capability ownership and hook contracts
Gate predicates — canonical specification of the phase-gate predicate vocabulary
Capability matrix — generated catalogue of every capability's role, tier, extension points, hook kinds, and engines.gsd
Capability manifest — the full capability.json schema and validation rules
gsd capability command — install / update / remove / list reference for third-party capabilities
Workflow fragments — in-file  marker grammar for fragmentizing workflow markdown at emission time
Reviewer Lane Registry — generated catalogue of third-party reviewer lanes, with their flags, transport, and install commands

Explanation

Context engineering — how context rot forms and how GSD Core prevents it
The phase loop — design rationale for the Discuss → Plan → Execute → Verify → Ship cycle
Multi-agent orchestration — how subagents are spawned, scoped, and coordinated
Security model — trust boundaries, permissions, and safe automation
The capability trust model — why third-party capabilities are gated by consent + integrity + reversibility, not a sandbox
How overlay capabilities compose — why first-party always wins and how the loader resolves precedence, conflicts, and fail-open load-failure warnings
Architecture — system architecture, agent model, and data flow
The Embeddable Orchestration System — one public, versioned contract for embedding GSD across many hosts
Discuss modes — assumptions mode vs interview mode for /gsd-discuss-phase
Context monitoring — context window monitoring hook architecture
Issue-driven orchestration — recipe for driving GSD from a tracker issue using existing primitives

What's new in 1.7.0 — curated highlights of the 1.7.0 release
Root README — landing page, quickstart, and documentation overview
Changelog — release history

14 KiB Raw Blame History