get-shit-done 的 CJS↔SDK 硬缝（Hard Seam）：每个 Shared Module 单一事实源的架构治理方案

本文聚焦 get-shit-done 项目围绕“CJS 工具层与 SDK 双层运行时”之间的边界加固决策（对应 docs/adr/3524-cjs-sdk-hard-seam.md）。核心议题是：当同一份逻辑在 CommonJS 工具层（get-shit-done/bin/lib/*.cjs）与 TypeScript SDK（sdk/src/**/*.ts）各存一份手写副本时，如何用“单一事实源 + 生成产物 + 多层强制校验”根治长期反复出现的双端漂移缺陷。读完你将掌握该方案的政策定义、模块归属表、五层执行机制，以及如何据此新增一个 Shared Module。

背景：双层运行时与反复发作的“漂移缺陷”类别

get-shit-done 采用双运行时架构：CJS 工具层（gsd-tools 及其 get-shit-done/bin/lib/*.cjs 家族）用于 Shell 脚本向后兼容；SDK（sdk/src/**/*.ts）则承载查询/运行时表面。二者共享多个逻辑模块——即 Shared Module：其 Interface 被 CJS 工具集与 SDK 以相同方式消费。项目根目录 CONTEXT.md 的领域词汇表早已显式标注此类模块，例如 STATE.md Document Module 被明确定义为 “Shared CJS/SDK pure transform Module”。

问题在于，这些 Shared Module 长期以 手写同步对（hand-synced pair） 的形式存在：.cjs 与 .ts 各存一份逐字符相同的实现。边界仅靠少数测试“巡逻”，例如 tests/config-schema-sdk-parity.test.cjs（命名一致性测试）与 sdk/src/golden/ 下的只读处理器输出奇偶黄金测试。这类防护能捕捉部分漂移，却系统性漏掉了：默认值结构漂移、警告/错误文案漂移、变更路径漂移以及“新增模块”漂移（只加在某一侧的新常量对另一侧完全不可见）。

由此形成一整个重复缺陷类别：#1535、#1542、#2047/#2052、#2638/#2655、#2653/#2670、#2687/#2706、#2798/#2816、#3055/#3116、#3523——每一次都是“修复只落在其中一侧，另一侧照旧出错”。最典型的是 #3523：SDK 侧 #3116 已将顶层旧版 branching_strategy 归一化进 git.branching_strategy，而 CJS 侧仍对同一合法键发出“将被忽略”的错误警告；根源是两侧维护了各自独立的 VALID_CONFIG_KEYS/KNOWN_TOP_LEVEL 推导逻辑。

底层架构背景可参见既有的接缝全景图 ADR： docs/adr/0005-sdk-architecture-seam-map.md。本 ADR 属于其接缝家族的扩展，并将 Shared-Module 单一事实源政策（Shared-Module Source Policy）纳入该体系；Dispatch Policy（docs/adr/0001-dispatch-policy-module.md）、Model Catalog（docs/adr/0003-model-catalog-module.md）、Planning Workspace（docs/adr/0004-worktree-workstream-seam-module.md）、Planning Path Projection（docs/adr/0006-planning-path-projection-module.md）与 Shell Command Projection（docs/adr/0009-shell-command-projection-module.md）模块保持既有权威，本文只做引用而不重述。

仓库里已有的先例：Command-Alias 生成模式

本 ADR 并非提出全新工具链，而是把仓库中已然运转的一个模式推广到全部 Shared Module。这个先例是命令别名生成：

• 单一 TypeScript 源 sdk/scripts/gen-command-aliases.ts 一次性发射两种产物：
  • TS 侧 sdk/src/query/command-aliases.generated.ts
  • CJS 侧 get-shit-done/bin/lib/command-aliases.generated.cjs
• sdk/scripts/check-command-aliases-fresh.mjs 是 CI 层的“新鲜度闸门”：它重新运行生成器逻辑（从 sdk/dist/query/command-manifest.*.js 推导期望值）并逐项 JSON.stringify 比对 TS 产物与 CJS 产物，任一不一致立即抛出 drift detected 错误。

从实现上看，两个消费侧都是对生成产物的纯 Adapter：CJS 路由器 require 那份 .generated.cjs，SDK 侧 import 那份 .generated.ts，不再有人手写别名表。Command-Alias Module 因此被本 ADR 标记为 “Already sealed by this pattern's precedent”，无需任何改动。

核心决策 1：Shared-Module Source Policy（五项规则）

凡是“Interface 被 CJS 工具集与 SDK 以相同方式消费”的 Module，一律遵守以下五项规则：

1. 恰有一个手写事实源。 模块有行为时，事实源落在 sdk/src/<module-name>/，以 TypeScript 编写；模块是纯数据时，落在 sdk/shared/<module-name>.manifest.json。
2. 只允许生成产物。 CJS 侧文件固定为 get-shit-done/bin/lib/<module-name>.generated.cjs，必须由机器发射，永不手改。
3. 每模块一条新鲜度检查。 CI 脚本 sdk/scripts/check-<module>-fresh.mjs 重跑生成器，若发射产物与已提交文件不一致则失败。先例即 check-command-aliases-fresh.mjs。
4. 每模块漂移 lint。 当事实源是数据（而非生成器输出）、文件等价无法覆盖全部不变式时，使用漂移 lint 断言规范所有者不变式。先例为 scripts/lint-shell-command-projection-drift.cjs。
5. 禁止手写同步对。 合入前的 scripts/lint-shared-module-handsync.cjs 扫描 get-shit-done/bin/lib/，凡是基线名能与某个 sdk/src/query/<同名>.ts（或 sdk/src/<同名>.ts）匹配、却又不是 *.generated.* 产物的 .cjs 文件，一律使构建失败，除非该配对被显式加入允许列表。

仓库中已落地的手写同步 lint 实现 scripts/lint-shared-module-handsync.cjs 体现了更细的治理粒度：配对身份以 cjs路径::ts路径 为键，而不是只按同名 basename 匹配（避免放行一个允许条目却放过同名的另一个兄弟路径）。它区分三种分类：

• cooperatingSiblings（合法共存兄弟）：lint 静默接受，退出码 0；
• migrateMeBacklog（已知反模式、待迁移）：仅在 --warn-all 时输出警告，永不阻断 CI；
• 未列入名单的配对：报 ERROR，退出码 1，并提示开发者“迁移为 Shared Module”或“在允许列表中添加经维护者评审的说明”。

允许列表本体在 scripts/shared-module-handsync-allowlist.json，当前共 22 条 cooperating sibling、0 条 backlog（例如 state.cjs↔sdk/src/query/state.ts 被解释为“CJS 全量实现，SDK 经 executeForCjs 委托”的既有接缝委托模式；config.cjs↔sdk/src/config.ts 被分类为 CJS-CLI-ONLY，因为两者表面互不重叠）。lint 还支持 --root、--cjs-dir、--sdk-src、--allowlist、--json 等参数，便于 CI 与测试夹具树复用。

核心决策 2：以模块为索引的 canonical-owner 总表

与物理层相反，本 ADR 主张以 Module（而非 CJS/SDK 层）为索引来登记所有权。总表完整列出：每个 Shared Module 的状态、事实源位置、生成产物、Adapter 站点，以及其定义所属的 ADR 章节。

Module	状态	事实源	生成产物	Adapters
STATE.md Document Module	本 ADR 新增（Phase 1）——参见 CONTEXT.md "STATE.md Document Module"	sdk/src/state-document/index.ts（自 sdk/src/query/state-document.ts 提升；实现时决定保持原址亦可）	sdk/src/query/state-document.generated.ts、get-shit-done/bin/lib/state-document.generated.cjs	bin/lib/state.cjs 与 sdk/src/query/state*.ts 均 import 生成形态
Configuration Module	本 ADR 新增（Phase 2）——定义随 Phase 2 写入 CONTEXT.md	sdk/src/configuration/index.ts，外加数据清单 sdk/shared/config-schema.manifest.json、sdk/shared/config-defaults.manifest.json	sdk/src/query/config-schema.generated.ts、get-shit-done/bin/lib/config-schema.generated.cjs、get-shit-done/bin/lib/configuration.generated.cjs	bin/lib/config.cjs、bin/lib/core.cjs:loadConfig、sdk/src/config.ts
Workstream Inventory Module (Builder)	本 ADR 修订（Phase 3）——Builder 拆分记入 CONTEXT.md	sdk/src/workstream-inventory/builder.ts（纯投影：目录项 + 每 workstream 的 STATE.md 文本 + plan scan 结果 → 类型化 inventory）	sdk/src/query/workstream-inventory-builder.generated.ts、get-shit-done/bin/lib/workstream-inventory-builder.generated.cjs	两侧 fs Reader（同步的 workstream-inventory.cjs、异步的 workstream-inventory.ts）调用 Builder；Reader 保持手写，因为两侧 fs 惯用法本就不同
Project-Root Resolution Module	本 ADR 新增（Phase 4）——CONTEXT.md 短条目，行为已事实共享	sdk/src/project-root/index.ts	get-shit-done/bin/lib/project-root.generated.cjs	bin/lib/core.cjs（findProjectRoot、findEffectiveRoot）、sdk/src/helpers.ts
Frontmatter Module	条件性（Phase 3，仅当漂移目录确认存在配对复制）	sdk/src/frontmatter/index.ts	get-shit-done/bin/lib/frontmatter.generated.cjs	既有 handler 调用点
Plan Scan Module	条件性（Phase 3 或之后）	sdk/src/plan-scan/index.ts	get-shit-done/bin/lib/plan-scan.generated.cjs	Phase/roadmap 路由器
CJS Command Router Adapter Module	本 ADR 修订（Phase 5）。既有 Module（CONTEXT.md 已定义）扩展：per-family handlers 映射改为进程内委托给 SDK runtime bridge，而非平行 CJS handler 实现	sdk/src/query-runtime-bridge.ts（已存在）+ 每 family 委托发射器	get-shit-done/bin/lib/cjs-command-router-adapter.cjs（已有，约 40 行），外加各 family handlers 映射——它们 require('../../sdk/dist/query-runtime-bridge.cjs') 并调用 QueryRuntimeBridge.execute()	bin/gsd-tools.cjs 与七个 bin/lib/*-command-router.cjs 为消费者；各 family 的 CJS handler 文件（state.cjs、verify.cjs、init.cjs 等）在 SDK handler 成为唯一实现后退化为委托或被删除
Command-Alias Module	已被先例封口——sdk/scripts/gen-command-aliases.ts + check-command-aliases-fresh.mjs	无改动	无改动	无改动
Dispatch Policy Module	延期——见 ADR-0001（及 2026-05-05 的 SDK Runtime Bridge 修订）	n/a	n/a	n/a
Model Catalog Module	延期——见 ADR-0003；sdk/shared/model-catalog.json 清单已遵循事实源政策	n/a	n/a	n/a
Planning Workspace Module	延期——见 ADR-0004；withPlanningLock、workstream 指针政策、锁语义保持原处	n/a	n/a	n/a
Planning Path Projection Module	延期——见 ADR-0006；SDK 为规范侧，CJS 路径解析经 Phase 4 收敛	n/a	n/a	n/a
Shell Command Projection Module（含 Phase 3–4 扩展后的平台 fs + subprocess）	延期——见 ADR-0009；platformWriteSync、platformReadSync、platformEnsureDir、execGit、execNpm、execTool、probeTty、normalizeContent 的规范所有者	n/a	n/a	n/a
Skill Surface Budget Module	延期——见 ADR-0011（已接受的 0011，而非被取代的草稿）	n/a	n/a	n/a

决策 3：接缝之外的模块——按运行时归属，无共享事实源

以下模块保持 CJS-only。因为不存在 SDK 对应物，漂移在结构上不可能发生；若将来某个模块需要 SDK 移植，那是新的 enhancement，而不是“平行实现”：

• bin/lib/graphify.cjs
• bin/lib/gsd2-import.cjs
• bin/lib/schema-detect.cjs
• bin/lib/fallow-runner.cjs
• bin/lib/intel.cjs
• bin/lib/drift.cjs
• bin/lib/installer-migrations.cjs（installer 运行时是 CJS 原生的；SDK 经由 sdk-package-compatibility.ts Adapter 消费）

决策 4：两侧 I/O Adapter 的差异是合法的

两侧的 state Adapter、verify Adapter 等处理器不在 Shared-Module 总表中：CJS 调用方使用同步 fs/exec；SDK 调用方使用异步 I/O 与 SDK 可观测性装饰器。关键在于——它们背后的纯变换（解析、投影、归一化）按总表抽入 Shared Module，I/O 则留在各自一侧。跨接缝的可观测行为由 sdk/src/golden/ 下的 golden parity 测试钉死。这是 Workstream Inventory 采用 Builder/Reader 拆分的根本原因：投影逻辑纯函数化、可共享；目录遍历则因同步（CJS）与异步（SDK）语义不同而必须各自实现。

决策 5：三层执行强制（均照既有仓库先例，而非新约定）

漂移在三个层面被阻断，每一层都以仓库中已存在的脚本为模板：

1. 逐模块新鲜度检查 sdk/scripts/check-<module>-fresh.mjs，总表中每个 Shared Module 一条。仓库中已存在 check-command-aliases-fresh.mjs、check-state-document-fresh.mjs、check-configuration-fresh.mjs、check-workstream-inventory-builder-fresh.mjs、check-project-root-fresh.mjs 以及 Phase 6 追加的 check-plan-scan-fresh.mjs、check-secrets-fresh.mjs、check-schema-detect-fresh.mjs、check-decisions-fresh.mjs、check-workstream-name-policy-fresh.mjs 等，说明该模式已规模化落地。
2. 逐模块漂移 lint scripts/lint-<module>-drift.cjs，用于“不变式不是纯文件等价”的数据清单型模块，先例是 lint-shell-command-projection-drift.cjs。
3. 手写同步对 lint scripts/lint-shared-module-handsync.cjs：拒绝任何 get-shit-done/bin/lib/<name>.cjs 与 sdk/src/query/<name>.ts（或 sdk/src/<name>.ts）既非生成产物、又不在显式允许列表中的配对，在 PR 期即拦截 #3523 这类反模式。

配套治理包括：CODEOWNERS 扩展至每个 Shared Module 的 sdk/src/<module>/，改动事实源须经架构团队评审；每个生成器在发射的 .generated.cjs/.generated.ts 顶部自动插入 “GENERATED FILE — Source: …” 横幅（沿用 command-aliases.generated.* 的既有格式），不引入额外的横幅工具。

决策 6：本 ADR 各 Phase 向 CONTEXT.md 新增的条目

• Configuration Module（Phase 2 添加）：负责 config 加载、legacy 键归一化、默认值合并，以及对 .planning/config.json 的显式落盘迁移。接口契约：
  • loadConfig(cwd) → MergedConfig：纯读，不写盘；
  • normalizeLegacyKeys(parsed) → { parsed, normalizations[] }：幂等，返回已应用的归一化列表供迁移日志使用；
  • mergeDefaults(parsed) → MergedConfig；
  • migrateOnDisk(cwd) → MigrationReport：显式、可选，仅由 installer 与 gsd-tools migrate-config 调用。
  • 不变式：loadConfig 内部绝不改动磁盘；顶层旧键（branching_strategy、sub_repos、multiRepo、depth）在返回中被归一化进规范的嵌套位置；默认值来自共享的 config-defaults.manifest.json。
• Project-Root Resolution Module（Phase 4 添加）：负责 project-root / effective-root 解析启发式，包括自身 .planning 探测、父级 sub_repos 遍历、legacy multiRepo 与 .git 祖先回退。
• Workstream Inventory Module — Builder 拆分（Phase 3 修订 CONTEXT.md）：既有 Module 条目增加子段落，注明纯投影逻辑为事实源、两侧 Reader Adapter 是对生成 Builder 的手写包装。
• CJS Command Router Adapter Module — runtime-bridge 委托（Phase 5 修订 CONTEXT.md）：注明各 family 的 handlers 映射经 require('../../sdk/dist/query-runtime-bridge.cjs') 进程内委托给 QueryRuntimeBridge.execute()；此前持有平行实现的 per-side CJS handler 文件（state.cjs、verify.cjs 等）在其 SDK 对应实现成为唯一实现后退化为委托或被删除；无 SDK 对应物的 CJS-only handler（graphify、gsd2-import、schema-detect、fallow-runner、intel、drift）保留进程内 CJS 实现。

后果：架构收益与边界效应

• #3523 一类的手写同步对反模式变得无法合入：lint-shared-module-handsync.cjs 拒绝任何“非生成”的新配对；check-<module>-fresh.mjs 拒绝任何与源脱节的生成文件改动。
• 接缝词汇表保持在既有 CONTEXT.md / LANGUAGE.md 框架内：不新增“shared core”“shared data”等层次标签——接缝所有权的最小单位就是 Module，与仓库其他部分一致。
• 不引入新的构建工具链：生成器即既有 gen-command-aliases.ts 形态；没有双 CJS+ESM 打包器、没有 package.json exports 子路径改动、没有 tsup/rollup 决策。
• 每个 Phase 只交付一个 Shared Module：最小的 STATE.md Document Module 先交付，因其两侧文件已逐字符一致，“删除测试”一接触即通过；#3523 触发类在 Phase 2 由 Configuration Module 关闭；Phase 5 中 CJS 路由器不再持有平行 handler 实现后，接缝成为真正的墙。
• CJS 分发折叠到 SDK runtime bridge：Phase 5 落地后，经 gsd-tools 运行的每个 canonical 命令都执行与 gsd-sdk query 相同的 SDK handler——进程内执行、无 subprocess 跳转；CJS 侧 state/verify/init/phase/roadmap/validate handler 被替换为 QueryRuntimeBridge.execute() 之上的薄委托；结果形态契约保持 { exitCode, stdoutChunks, stderrLines }（依 ADR-0001 的 Query CLI Output Module）。
• 既有 ADR 只被引用、不被重述：ADR-0006、0003、0004、0001、0009 对其领域保持权威；本 ADR 只追加 Shared-Module 事实源政策、各模块条目与 CJS Command Router Adapter Module 修订。
• I/O Adapter 的差异保留在 runtime-bridge 边界：CJS 路由器的同步执行模型不变——QueryRuntimeBridge.execute() 为 CJS 调用方暴露同步入口（底层 SDK handler 为异步时，bridge 以进程内事件循环步进运行），不新增 subprocess；异步 SDK 调用点继续直接用异步 bridge。
• 执行强制复用既有脚本：三个新的 lint/check 原语全部以 scripts/ 与 sdk/scripts/ 中已有脚本为模板，CI 接线沿用既有先例。

从决策到落地：六阶段迁移与仓库现状

配套 PRD docs/prd/3524-cjs-sdk-hard-seam.md 将 ADR 的目标架构翻译成“不破坏运行系统的迁移路线”，每个 Phase 独立可交付、独立可回滚：

• Phase 1 — STATE.md Document Module（最小证明）：bin/lib/state-document.cjs 与 sdk/src/query/state-document.ts 是逐字符一致的手写同步纯变换对。落地后 CJS 侧退化为对 .generated.cjs 的再导出。
• Phase 2 — Configuration Module（关闭 #3523 类别）：先把配置键集/默认值抽到 sdk/shared/config-schema.manifest.json 与 sdk/shared/config-defaults.manifest.json 两份数据清单（先例：sdk/shared/model-catalog.json），再以 sdk/src/configuration/ 作为实现事实源，loadConfig/normalizeLegacyKeys/mergeDefaults/migrateOnDisk 四函数对外提供；删除 core.cjs 内联的 CONFIG_DEFAULTS、误报警告与重复的 _deepMergeConfig。
• Phase 3 — Workstream Inventory Builder + 剩余手写同步对：确立 Builder/Reader 拆分模板，并审计 frontmatter.cjs↔frontmatter-mutation.ts、plan-scan.cjs↔SDK 对应物等疑似配对。
• Phase 4 — Project-Root Resolution Module：findProjectRoot(startDir)、findEffectiveRoot(startDir, options) 只定义一次，两侧 import 生成模块；奇偶测试覆盖独立项目、monorepo 的 planning.sub_repos、legacy multiRepo: true、深层嵌套四种形态。
• Phase 5 — CJS Command Router Adapter 委托 SDK runtime bridge：为 CJS 暴露同步友好入口 executeForCjs(input) → { exitCode, stdoutChunks, stderrLines }；按 state.*、verify.*、phase.*、phases.*、validate.*、roadmap.*、init.*、frontmatter.*、config.* 及 command-manifest.non-family 中的非家族命令逐 family 子 PR 迁移，每 family 合入前先跑 golden parity 矩阵。
• Phase 6 — 强制加固 + 复盘：落地手写同步 lint、将每模块新鲜度检查接入 CI、补 CODEOWNERS 规则，并对 #1535…#3523 整条复现清单逐条复盘其会被哪一层防护拦截。

完整迁移实况记录在 docs/agents/cjs-sdk-seam.md：Phase 6 完成时共 22 个 cooperating sibling、0 个 backlog 配对，并在 Phase 6 又按同一模式迁移了 plan-scan、secrets、schema-detect、decisions、workstream-name-policy 五个 Shared Module；state.* 家族已完成 executeForCjs 委托（如 state.update 经 get-shit-done/bin/lib/cjs-command-router-adapter.cjs 调用 sdk/src/query-runtime-bridge.ts）。需要说明的是：ADR 文档头标注状态为 Proposed，但仓库内的生成器、新鲜度检查、允许列表与迁移复盘文档表明该方案已被大规模实现，可视为既定架构。

实战指南：如何新增一个 Shared Module

按 docs/agents/cjs-sdk-seam.md 的完整参考，新增 Shared Module 的标准步骤如下（Phase 1 的 state-document 迁移为完整范例）：

1. 建事实源文件 sdk/src/<module>/index.ts（或纯数据时 sdk/shared/<module>.manifest.json）：canonical 定义，不得 import CJS 或生成文件。
2. 写生成器 sdk/scripts/gen-<module>.mjs：读事实源、产出 .generated.ts/.generated.cjs、退出 0；必须幂等（跑两遍结果一致）。
3. 写新鲜度检查 sdk/scripts/check-<module>-fresh.mjs：重跑生成器到临时位置，与已提交文件 diff，不一致则退出 1 并给出清晰信息——这就是 CI 跑的脚本。
4. 写奇偶测试（可选但推荐）tests/<module>-parity.test.cjs：断言 CJS Adapter 与 SDK 事实源在所有关键字段上一致，弥补新鲜度检查无法捕获的生成器 bug。
5. 接线 CI：在 .github/workflows/test.yml 既有新鲜度检查块之后新增一步 node sdk/scripts/check-<module>-fresh.mjs。
6. 刷新清单：如模块影响 CONTEXT.md 模块目录则同步更新；并把 scripts/shared-module-handsync-allowlist.json 中对应条目从 migrateMeBacklog 移到 cooperatingSiblings（或直接删除已被删掉的手写副本条目）。
7. 更新 CODEOWNERS：在 Phase 6 块下登记新事实源路径，使架构归属显式化。

若你想新增的是 canonical 命令而非模块，则遵循：先在 sdk/src/query/command-manifest.<family>.ts 声明命令定义 → 在 sdk/src/query/<subcommand>.ts 实现 SDK handler（不得 shell out 回 CJS）→ 在家族 CJS 路由器中加 executeForCjs 委托分支 → 追加 golden parity 测试，确保两条路径输出一致。

范围之外与开放问题

本 ADR 明确不处理：CJS-only 模块（graphify、gsd2-import、schema-detect、fallow-runner、intel、drift）的 SDK 迁移（各自是独立 enhancement）；CJS state/verify Adapter 的 sync→async 迁移（保留 per-side Adapter 形态正是本决策的意义）；以及在 verify 表面尚无共享 Interface 前定义 Verify Module。Phase 5 的同步桥接机制（executeForCjs）在实现层面经历了一次务实收敛：可行性方案本是 deasync 原生绑定、Atomics.wait Worker 通道与“将 SDK handler 全部同步化”三选一，最终仓库落地为 runtime-bridge-sync worker 形态（见 sdk/src/runtime-bridge-sync/ 与 state.* 家族的既有委托实现）。

综上，CJS↔SDK 硬缝方案的本质是把“共享逻辑应存几份”从代码规范问题转化为可机械执行的结构约束：事实源唯一、产物自动生成、新鲜度与配对 lint 在 CI 拦截、既有 ADR 各司其职。对任何维护双运行时/双语言消费同一核心逻辑的仓库而言，这套“先例推广 + 模块级归属表 + 三层强制”的治理模式都具备直接的移植参考价值。