a56707a07b
* fix(#2613): preserve STATE.md frontmatter on write path (option 2) `readModifyWriteStateMd` strips frontmatter before invoking the modifier, so `syncStateFrontmatter` received body-only content and `existingFm` was always `{}`. The preservation branch never fired, and every mutation re-derived `status` (to `'unknown'` when body had no `Status:` line) and `progress.*` (to 0/0 when the shipped milestone's phase directories were archived), silently overwriting authoritative frontmatter values. Option 2 — write-side analogue of #2495 READ fix: `buildStateFrontmatter` reads the current STATE.md frontmatter from disk as a preservation backstop. Status preserved when derived is `'unknown'` and existing is non-unknown. Progress preserved when disk scan returns all zeros AND existing has non-zero counts. Legitimate body-driven status changes and non-zero disk counts still win. Milestone/milestone_name already preserved via `getMilestoneInfo`'s #2495 fix — regression test added to lock that in. Adds 5 regression tests covering status preservation, progress preservation, milestone preservation, legitimate status updates, and disk-scan-wins-when-non-zero. Closes #2613 * fix(sdk): double-cast WorkflowConfig to Record in loadGateConfig TypeScript error on main (introduced in #2611) blocks the install-smoke CI job: `WorkflowConfig` has no string index signature, so the direct cast to `Record<string, unknown>` fails type-check. The SDK build fails, `installSdkIfNeeded()` cannot install `gsd-sdk` from source, and the smoke job reports a false-positive installer regression. src/query/check-decision-coverage.ts(236,16): error TS2352: Conversion of type 'WorkflowConfig' to type 'Record<string, unknown>' may be a mistake because neither type sufficiently overlaps with the other. Apply the double-cast via `unknown` as the compiler suggests. Behavior is unchanged — this was already a cast.
@gsd-build/sdk
TypeScript SDK for Get Shit Done: deterministic query/mutation handlers, plan execution, and event-stream telemetry so agents focus on judgment, not shell plumbing.
Install
npm install @gsd-build/sdk
Quickstart — programmatic
import { GSD, createRegistry } from '@gsd-build/sdk';
const gsd = new GSD({ projectDir: process.cwd(), sessionId: 'my-run' });
const tools = gsd.createTools();
const registry = createRegistry(gsd.eventStream, 'my-run');
const { data } = await registry.dispatch('state.json', [], process.cwd());
Quickstart — CLI
From a project that depends on this package, invoke the CLI with Node (recommended in CI and local dev):
node ./node_modules/@gsd-build/sdk/dist/cli.js query state.json
node ./node_modules/@gsd-build/sdk/dist/cli.js query roadmap.analyze
If no native handler is registered for a command, the CLI can transparently shell out to get-shit-done/bin/gsd-tools.cjs (see stderr warning), unless GSD_QUERY_FALLBACK=off.
What ships
| Area | Entry |
|---|---|
| Query registry | createRegistry() in src/query/index.ts — same handlers as gsd-sdk query |
| Tools bridge | GSDTools — native dispatch with optional CJS subprocess fallback |
| Orchestrators | PhaseRunner, InitRunner, GSD |
| CLI | gsd-sdk — query, run, init, auto |
Guides
- Handler registry & contracts:
src/query/QUERY-HANDLERS.md - Repository docs (when present):
docs/ARCHITECTURE.md,docs/CLI-TOOLS.mdat repo root
Environment
| Variable | Purpose |
|---|---|
GSD_QUERY_FALLBACK |
off / never disables CLI fallback to gsd-tools.cjs for unknown commands |
GSD_AGENTS_DIR |
Override directory scanned for installed GSD agents (~/.claude/agents by default) |