0d9a800e564b9228564e38b98a4fdb9684358ed5
2 Commits
| Author | SHA1 | Message | Date | |
|---|---|---|---|---|
Tom Boucher
|
e437ded6fc |
docs(3524): CJS↔SDK hard-seam ADR + phased PRD (#3529)
* 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 |
||
|
Tom Boucher
|
8b679959cc |
docs: adopt issue#-prefix naming for ADRs/PRDs to eliminate parallel-developer collisions (#3487)
* docs: adopt issue#-prefix naming for ADRs/PRDs (#3485) The repo's sequential ADR/PRD numbering convention has produced recurring collisions when developers compute "next number" locally and ship in parallel — currently visible on disk as duplicate docs/adr/0010-*.md and triplicate docs/adr/0011-*.md, plus a stack of "resolve ADR conflict" commits in git history. Replace the local-compute convention with issue#-prefix slug naming: docs/adr/<issue#>-<slug>.md (new ADRs) docs/prd/<issue#>-<slug>.md (new PRDs — directory introduced) GitHub issue numbers are server-assigned and atomic, so the reservation step the CONTRIBUTING.md issue-first rule already enforces also produces the artifact ID. One issue = one ADR-or-PRD = one PR. Same shape as the existing changeset random-name pattern (#2975) for CHANGELOG.md fragments, applied to a different artifact class. Migration policy: legacy ADRs 0001-* through 0011-* are preserved as immutable historical record. The new convention applies only to ADRs/PRDs created on or after this merge. Files updated: - docs/adr/README.md — naming convention + legacy note + link - docs/prd/README.md (new) — seeds the new directory + same convention - CONTRIBUTING.md — new "Proposing an ADR or PRD" section - docs/contributor-standards.md — formalize as contributor requirement No code surface — docs-only. Closes #3485 Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * docs(changeset): add Changed fragment for ADR/PRD naming convention (#3487) Per CONTRIBUTING.md "When unsure whether a change is user-facing, add the fragment" — the contributor process IS user-facing for the contributor user class. Drop the no-changelog opt-out, surface the naming-convention change in the next CHANGELOG so contributors see it before they hit it as a PR rejection. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * docs: address CodeRabbit findings on #3487 - CONTRIBUTING.md: rename heading to "Proposing an ADR or PRD" so its GitHub-anchor slug matches the #proposing-an-adr-or-prd link target used from docs/adr/README.md, docs/prd/README.md, and docs/contributor-standards.md (broken anchors) - docs/adr/README.md, docs/prd/README.md, docs/contributor-standards.md: add `text` language tag to the new naming-convention fenced blocks to satisfy markdownlint MD040 Pre-existing untyped fences elsewhere in the touched files are left alone per CONTRIBUTING.md "no drive-by formatting". Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> --------- Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com> |