Files

Tom Boucher adb46cdd85 feat(#2734 ): surface STATE.md commit-age on the statusline (#3700 )

* test(#2734): failing-first suite for the statusline STATE.md freshness marker

Binds the contract before any hook change exists: a `state ~N commits back`
segment gated on the state_head stamp landed by #2622, firing at the same
advisory threshold /gsd-health's W024 uses rather than at > 0.

Covers all five acceptance criteria — threshold parity (19/20/21 boundaries),
both renderers including formatGsdStateCompact, an exact spawn-count assertion,
repo-pinning and sub_repos degradation, and behavioral parity against
readStateHeadFreshness rather than a source-grep of the two fence copies.

52 example-based tests plus 5 seeded fast-check properties. Red now by design.

* feat(#2734): surface STATE.md commit-age on the statusline

Adds an opt-in `state ~N commits back` marker to the GSD-state segment,
consuming the `state_head` stamp and freshness contract landed by #2622.
A solo developer returning to a project reads "Phase 4, executing" in
STATE.md and acts on it, without noticing the codebase moved 40 commits
since that line was written. /gsd-health reports it as W024, but only if
you think to run it; the statusline is the surface you see without asking.

Fires at STATE_HEAD_ADVISORY_COMMITS (20), the same threshold W024 uses,
not at > 0: with commit_docs:true the commit carrying a STATE.md sync
advances HEAD by one, so > 0 would alarm permanently on a fresh project.

Costs exactly one bounded git subprocess per render and none when
disabled. `rev-list --left-right --count` answers ancestry and distance
together, and repo pinning is a filesystem check mirroring
projectOwnsItsRepo rather than a --show-toplevel compare, which is
unreliable on macOS /private/var and Windows 8.3 paths.

Every unresolvable input degrades to the tri-state unknown -- the marker
is absent, never a "fresh" claim the project cannot substantiate: a
malformed stamp, a root that does not own its .git, a sub_repos
workspace, history rewound past the stamp, or git being unavailable.

Also collapses statusline config resolution onto one resolveStatuslineOptions()
seam. runStatusline() and renderStatusline() duplicated it byte-for-byte;
one copy is what keeps a newly-added key from reaching only one of them.

* test(#2734): route the e2e spawn through the process seam and fix fixture leaks

Review findings from the two orthogonal passes:

- `bothEntryPointsResolveOptionsIdentically` spawned a child and substring-matched
  its stdout to test a pure function. It now calls resolveStatuslineOptions()
  directly — no subprocess, no text matching.
- `skipsFreshnessWorkWhenTodoTaskActive` genuinely needs a child (the !task gate
  lives in runStatusline, which reads stdin), so it now spawns through
  tests/helpers/process-seam.cjs and proves the negative with a filesystem fact:
  the git shim appends to a marker file on every invocation, and the assertion is
  that the marker never appears. Stronger than asserting text is missing, and it
  drops the last stdout substring match in the block.
- Every fixture-creating test now registers `t.after(() => cleanup(dir))` instead
  of a trailing cleanup(dir), which leaked the temp repo on assertion failure.
  derivationAgreesWithStateModule reassigns `dir` across five fixtures, so it
  binds each directory at scheduling time rather than cleaning only the last.

Also corrects markerCoexistsWithMilestoneComplete, which asserted the wrong
expectation rather than finding a code defect: `percent` drives the progress bar
too, so the milestone segment reads "v1.9 [##########] 100%". The marker appends
after it, which is what the test exists to prove.

CONTEXT.md's opt-in statusline key list was missing statusline.show_git as well
as the new key; both are now enumerated.

* docs(#2734): backfill changeset PR number (#3700)

---------

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

2026-08-20 00:35:01 -04:00

12 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
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
Resolve verify-command path findings — fix an <automated> verify command whose target directory does not resolve from the executor's cwd
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"
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"
Keep planning docs out of a shared repo — make .planning/ local-only, including untracking files git already tracks (the step .gitignore alone cannot do)
Plan a phase — run research, decompose work, and verify plan quality
Execute a phase — run plans in parallel waves with fresh-context subagents
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
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

12 KiB Raw Blame History