docs(sdk): document runtime bridge seam, strict mode, and fallback policy

This commit is contained in:
Tom Boucher
2026-05-05 19:29:59 -04:00
parent 1bd11ab699
commit 54b06e653e
4 changed files with 40 additions and 2 deletions

View File

@@ -55,7 +55,7 @@ GSD is a **meta-prompting framework** that sits between the user and AI coding a
┌──────▼──────────────▼─────────────────▼──────────────┐
│ CLI TOOLS LAYER │
│ gsd-sdk query (sdk/src/query) + gsd-tools.cjs │
│ (State, config, phase, roadmap, verify, templates) │
│ SDK Runtime Bridge Module routes native vs fallback │
└──────────────────────┬───────────────────────────────┘
│
┌──────────────────────▼───────────────────────────────┐
@@ -266,6 +266,17 @@ Runtime hooks that integrate with the host AI agent:
See [`docs/INVENTORY.md`](INVENTORY.md#hooks-11-shipped) for the authoritative 11-hook roster.
### SDK Runtime Bridge Module (`sdk/src/query-runtime-bridge.ts`)
Programmatic SDK callers (`GSDTools`) route through one seam that owns query dispatch policy:
- Native registry dispatch preference
- Explicit subprocess fallback policy (`allowFallbackToSubprocess`)
- Strict SDK mode (`strictSdk`) for fail-fast native-only enforcement
- Structured dispatch observability (`onDispatchEvent`) with mode, reason, duration, and outcome
This keeps callers thin adapters and centralizes transport decisions for SDK publishability.
### CLI Tools (`get-shit-done/bin/`)
Node.js CLI utility (`gsd-tools.cjs`) with domain modules split across `get-shit-done/bin/lib/` (see [`docs/INVENTORY.md`](INVENTORY.md#cli-modules-33-shipped) for the authoritative roster):