e437ded6fc
* docs(3524): propose CJS↔SDK hard-seam ADR + phased PRD Adds docs/adr/3524-cjs-sdk-hard-seam.md (Proposed) and docs/prd/3524-cjs-sdk-hard-seam.md (Reference) tracking #3524. Updates the ADR and PRD index READMEs. The ADR defines one canonical owner per responsibility across the CJS (bin/lib/*.cjs) and SDK (sdk/src/**/*.ts) sides, eliminating the recurring drift bug class (#1535, #1542, #2047, #2638, #2653, #2687, #2798, #3055, #3523). Three layers: shared data (sdk/shared/*.json), shared core logic (sdk/src/core/ → dual CJS+ESM build), thin adapters. Enforcement is layered: build-time grep, type-level contract test, mutation parity test, CODEOWNERS gate, in-file banner. The PRD phases the migration in five independently shippable steps — shared data first (closes constant drift), then config consolidation (closes #3523 class), then project-root + path projection, then state and verify handlers, then enforcement hardening + retrospective. * docs(3524): revise seam ADR + PRD after architecture review Architecture-review pass (via /improve-codebase-architecture) found seven deepening opportunities; this commit applies all of them. 1. Re-anchor on the existing generator precedent. The repo already has sdk/scripts/gen-command-aliases.ts emitting both .generated.ts and .generated.cjs from one TS source, with sdk/scripts/check-command-aliases-fresh.mjs as the CI freshness gate. The ADR's invented dual CJS+ESM bundler pipeline is dropped. Each Shared Module gets one generator script and one freshness check, modeled on that precedent. 2. Drop the generic sdk/src/core/ container. The canonical-owner table is now indexed by Module, using the CONTEXT.md domain vocabulary (STATE.md Document Module, Configuration Module, etc.) rather than file-path-based pseudo-modules. 3. Split the coarse "State management" row into three: the pure STATE.md Document Module (already a character-identical hand-synced pair — perfect Phase 1 target), the Planning Workspace Module (defer to ADR-0004), and per-side state I/O Adapters (legitimately differ sync vs async). 4. Defer to existing ADRs. Planning Path Projection (ADR-0006), Model Catalog (ADR-0003), Planning Workspace (ADR-0004), Dispatch Policy (ADR-0001), Shell Command Projection (ADR-0009 post-Phase 3-4 expansion which absorbed superseded ADR-0010). The stale ADR-0010 reference is fixed. 5. Define a Configuration Module entry in CONTEXT.md as a Phase 2 deliverable, with explicit Interface contract for loadConfig, normalizeLegacyKeys, mergeDefaults, migrateOnDisk. 6. Split the Workstream Inventory Module into a pure Builder (generated, shared) and per-side Reader Adapters (hand-authored, sync vs async). Same pattern generalizes to other paired Modules. 7. Match enforcement to existing scripts. Per-Module freshness checks (precedent: check-command-aliases-fresh.mjs), per-Module drift lints (precedent: lint-shell-command-projection-drift.cjs), and one hand-sync pair lint that blocks the #3523 anti-pattern at PR time. PRD phases reordered: STATE.md Document Module ships first as a proof of pattern (two identical files become one source plus one generated artifact). Configuration Module ships second, closing the #3523 class. Workstream Inventory Builder split third. Project-Root Resolution fourth. Enforcement and retrospective fifth. * docs(3524): expand scope — CJS router delegates to SDK runtime bridge User flagged that the original "Out of scope" list was my unilateral scoping call, not theirs. After review, the CJS router consolidation (formerly out-of-scope item #1) is brought into scope. ADR additions: - CJS Command Router Adapter Module row added to canonical-owner table. Existing Module (per CONTEXT.md) is amended so the per-family `handlers` map delegates to `QueryRuntimeBridge.execute()` in-process. Per-side CJS handler files for canonical families (state.cjs, verify.cjs, init.cjs, phase.cjs, etc.) shrink to delegates or are deleted. - Per-side I/O Adapter consequence updated to clarify the bridge preserves the in-process model. No subprocess hop is added. - "Out of scope" stripped of router item; CJS-only seam migration and verify-Module-first work remain out of scope. PRD additions: - New Phase 5: CJS Command Router Adapter delegates to SDK runtime bridge, family-by-family, with golden parity matrix per family gating each PR. - Old Phase 5 (enforcement) renumbered to Phase 6, expanded to cover Phase 5's parity matrix and runtime-bridge CODEOWNERS. - Open question #4 added for the synchronous-bridging mechanism (`deasync` vs `Atomics.wait` vs sync-handler refactor) — resolved in the Phase 5 spike before any family migration begins. - Open question #5 added for family migration order (recommended: smallest read-only family first). - Risks table expanded with three Phase 5 rows: bridging-mechanism uncertainty, observable-output regression, startup-time impact. - Done-when updated for six phases and five enforcement layers. Non-goals updated: CJS-only Module migration and verify-Module deepening remain out of scope. CJS CLI removal explicitly stays off the table — the external `gsd-tools` contract is preserved. * docs(3524): address CodeRabbit review * docs(3524): fix PRD issue reference markdown
Product Requirements Documents
This directory contains Product Requirements Documents (PRDs) for GSD.
A PRD captures the what and why of a feature before implementation begins. ADRs (in docs/adr/) capture the how of architectural decisions. The two complement each other: a PRD makes the case for a feature and defines acceptance criteria; an ADR records the architectural mechanism chosen to deliver it.
Naming Convention
PRDs use the same issue#-prefix slug naming as ADRs:
docs/prd/<issue#>-<kebab-slug>.md
Example: docs/prd/3491-bar-feature.md for a feature tracked in issue #3491.
The GitHub-assigned issue number is the prefix. Do not compute a sequential number locally — see CONTRIBUTING.md — "Proposing an ADR or PRD" for the full process.
Historical note
docs/adr/0011-review-default-reviewers-prd.md predates this directory and is preserved as immutable historical record. It is not a pattern to follow. New PRDs live here.
Index
| PRD | Title | Status |
|---|---|---|
| 3524-cjs-sdk-hard-seam.md | CJS↔SDK hard seam — phased migration (#3524) | Reference |