ts-procedures 8.3.0 → 8.5.0

package/docs/superpowers/plans/2026-06-06-shared-models-convention-and-diagnostics.md

@@ -0,0 +1,659 @@
+# Shared-Models Convention + Diagnostics Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Make the v8.4.0 `sharedTypesImport` single-source-of-truth path self-maintaining and footgun-free — collapse the hand-maintained `$id → {module,name}` map to a one-value `sharedModelsModule` convention, surface the silent generated-twin fallback via an always-on summary plus an opt-in `--strict-shared-models` hard-fail, and give all three a CLI flag + config + programmatic surface.
+
+**Architecture:** Keep the codegen **pure-envelope** — no consumer source-tree scanning. The convention and diagnostics live entirely in `collect-models.ts` (`resolveModelImports`) and `targets/ts/run.ts`, fed by two new options threaded through the existing `GenerateClientOptions → PipelineOptions → TargetRunInput` chain and the CLI. Precedence in `resolveModelImports`: explicit `sharedTypesImport[$id]` → `sharedModelsModule` convention → generate locally. The existing per-`$id` map stays as the multi-consumer / rename escape hatch (unchanged).
+
+**Tech Stack:** TypeScript (ESM, `.js` import specifiers), Vitest, ajsc (dynamic import). Branch: `dx-feedback` (already checked out).
+
+**Explicitly out of scope (decided with the user):**
+- `--shared-types-from <dir|glob>` source scanning — declined; breaks the envelope-decoupling invariant. Reasoning written up for downstream in Task 7.
+- `x-shared-import` schema keyword — deferred (adds a third overlapping mechanism; the convention + existing map cover the spectrum). Not built this round.
+- ts-channels parity / cross-package coordination — not this project's concern.
+
+**Conventions to follow:**
+- Run a single test file: `npx vitest run <path>`. Full suite: `npm run test`. Lint: `npm run lint`. Build: `npm run build`.
+- ESM imports use `.js` specifiers even for `.ts` sources.
+- Commit after each green task.
+
+---
+
+## File Structure
+
+| File | Responsibility | Tasks |
+|------|----------------|-------|
+| `src/codegen/collect-models.ts` (modify) | `resolveModelImports` gains the `sharedModelsModule` convention fallback | 1 |
+| `src/codegen/collect-models.test.ts` (modify) | Unit coverage for the convention precedence | 1 |
+| `src/codegen/targets/_shared/target-run.ts` (modify) | `TargetRunInput` carries `sharedModelsModule` + `strictSharedModels` | 2, 3 |
+| `src/codegen/pipeline.ts` (modify) | `PipelineOptions` + `base` thread both options | 2, 3 |
+| `src/codegen/index.ts` (modify) | `GenerateClientOptions` + `generateClient` pass-through | 2, 3 |
+| `src/codegen/targets/ts/run.ts` (modify) | Pass convention to `resolveModelImports`; emit summary log; strict hard-fail | 2, 3 |
+| `src/codegen/targets/ts/shared-models.test.ts` (modify) | End-to-end coverage for convention + diagnostics | 2, 3 |
+| `src/codegen/bin/flag-specs.ts` (modify) | `--shared-models-module` + `--strict-shared-models` spec entries | 4 |
+| `src/codegen/bin/flag-specs.test.ts` (modify) | Assert the new flags are catalogued | 4 |
+| `src/codegen/bin/cli.ts` (modify) | Config keys, `parseArgs` branches, `ParsedArgs`, watch + main pass-through | 5 |
+| `src/codegen/bin/cli.test.ts` (modify) | CLI parse coverage | 5 |
+| `CLAUDE.md` (modify) | Document the convention + diagnostics in the codegen section | 6 |
+| `docs/client-and-codegen.md` (modify) | Consumer-facing guidance for the convention | 6 |
+| `docs/handoffs/shared-models-auto-resolve-response.md` (new) | Downstream response: what shipped + why the scanner was declined | 7 |
+
+---
+
+## #A — `sharedModelsModule` convention
+
+### Task 1: `resolveModelImports` convention fallback
+
+**Files:**
+- Modify: `src/codegen/collect-models.ts:100-108`
+- Test: `src/codegen/collect-models.test.ts`
+
+- [ ] **Step 1: Write the failing test**
+
+Append to `src/codegen/collect-models.test.ts`:
+
+```ts
+it('resolveModelImports falls back to sharedModelsModule when no map entry matches', () => {
+  const models = collectModels([
+    { jsonSchema: { res: { body: { $id: 'urn:msg', title: 'Message', type: 'object', properties: {} } } } } as never,
+  ])
+  const resolved = resolveModelImports(models, {}, '@app/schemas')
+  expect(resolved[0]?.import).toEqual({ module: '@app/schemas', name: 'Message' })
+})
+
+it('resolveModelImports: explicit map entry wins over the convention', () => {
+  const models = collectModels([
+    { jsonSchema: { res: { body: { $id: 'urn:msg', title: 'Message', type: 'object', properties: {} } } } } as never,
+  ])
+  const resolved = resolveModelImports(
+    models,
+    { 'urn:msg': { module: '@override/pkg', name: 'Msg' } },
+    '@app/schemas',
+  )
+  expect(resolved[0]?.import).toEqual({ module: '@override/pkg', name: 'Msg' })
+})
+
+it('resolveModelImports: empty-string convention is treated as unset (generated locally)', () => {
+  const models = collectModels([
+    { jsonSchema: { res: { body: { $id: 'urn:msg', title: 'Message', type: 'object', properties: {} } } } } as never,
+  ])
+  expect(resolveModelImports(models, {}, '')[0]?.import).toBeUndefined()
+})
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `npx vitest run src/codegen/collect-models.test.ts`
+Expected: FAIL — `resolveModelImports` ignores the third argument; the first two new tests' `import` is `undefined`.
+
+- [ ] **Step 3: Implement the convention fallback**
+
+Replace `resolveModelImports` in `src/codegen/collect-models.ts` (lines 100-108):
+
+```ts
+/**
+ * Tags each collected model with its external import. Precedence:
+ *   1. an explicit `sharedTypesImport[$id]` entry (per-type override / rename),
+ *   2. otherwise, when `sharedModelsModule` is set, the convention
+ *      `{ module: sharedModelsModule, name: model.name }` — every shared model
+ *      re-exports from one module under its derived name (`$id`/`title` === export),
+ *   3. otherwise `import` stays undefined and the model is generated locally.
+ */
+export function resolveModelImports(
+  models: CollectedModel[],
+  map: SharedTypesImportMap = {},
+  sharedModelsModule?: string,
+): ResolvedModel[] {
+  return models.map((model) => {
+    const mapped = map[model.id]
+    if (mapped) return { ...model, import: mapped }
+    if (sharedModelsModule != null && sharedModelsModule !== '') {
+      return { ...model, import: { module: sharedModelsModule, name: model.name } }
+    }
+    return { ...model }
+  })
+}
+```
+
+- [ ] **Step 4: Run test to verify it passes**
+
+Run: `npx vitest run src/codegen/collect-models.test.ts`
+Expected: PASS (all existing + 3 new tests).
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/codegen/collect-models.ts src/codegen/collect-models.test.ts
+git commit -m "feat(codegen): sharedModelsModule convention fallback in resolveModelImports"
+```
+
+---
+
+### Task 2: Thread `sharedModelsModule` end-to-end and consume it in the TS run
+
+**Files:**
+- Modify: `src/codegen/targets/_shared/target-run.ts:14-33`
+- Modify: `src/codegen/pipeline.ts:14-36,61-75`
+- Modify: `src/codegen/index.ts:8-31,33-56`
+- Modify: `src/codegen/targets/ts/run.ts:22-64`
+- Test: `src/codegen/targets/ts/shared-models.test.ts`
+
+- [ ] **Step 1: Write the failing test**
+
+Append inside the existing `describe('shared models ...')` block in `src/codegen/targets/ts/shared-models.test.ts`:
+
+```ts
+it('sharedModelsModule re-exports every $id model from the convention module', async () => {
+  const files = await runPipeline({
+    envelope: modelEnvelope(),
+    outDir: 'out',
+    dryRun: true,
+    shareModels: true,
+    namespaceTypes: true,
+    selfContained: false,
+    sharedModelsModule: '@app/schemas',
+  })
+
+  const modelsFile = findFile(files, '_models.ts')!
+  // Re-exported, not generated.
+  expect(modelsFile.code).toContain("export { Message } from '@app/schemas'")
+  expect(countMatches(modelsFile.code, /export type Message =/g)).toBe(0)
+
+  // Scopes still import the shared name from ./_models.
+  expect(findFile(files, 'messages.ts')!.code).toContain("from './_models'")
+})
+
+it('explicit sharedTypesImport overrides the sharedModelsModule convention per $id', async () => {
+  const files = await runPipeline({
+    envelope: modelEnvelope(),
+    outDir: 'out',
+    dryRun: true,
+    shareModels: true,
+    namespaceTypes: true,
+    selfContained: false,
+    sharedModelsModule: '@app/schemas',
+    sharedTypesImport: { 'urn:msg': { module: '@override/pkg', name: 'Message' } },
+  })
+  expect(findFile(files, '_models.ts')!.code).toContain("export { Message } from '@override/pkg'")
+})
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `npx vitest run src/codegen/targets/ts/shared-models.test.ts`
+Expected: FAIL — `runPipeline` does not accept/forward `sharedModelsModule`; `_models.ts` still generates `export type Message = …` rather than re-exporting.
+
+- [ ] **Step 3a: Add the field to `TargetRunInput`**
+
+In `src/codegen/targets/_shared/target-run.ts`, add to the `TargetRunInput` interface (after the `sharedTypesImport` field, line 32):
+
+```ts
+  /** Single module every $id-bearing model re-exports from (convention; map entries override). */
+  sharedModelsModule?: string
+```
+
+- [ ] **Step 3b: Add to `PipelineOptions` and forward in `base`**
+
+In `src/codegen/pipeline.ts`, add to the `PipelineOptions` interface (after line 25, `sharedTypesImport?`):
+
+```ts
+  sharedModelsModule?: string
+```
+
+And add to the `base` object (after line 74, `sharedTypesImport: options.sharedTypesImport,`):
+
+```ts
+    sharedModelsModule: options.sharedModelsModule,
+```
+
+- [ ] **Step 3c: Add to `GenerateClientOptions` and forward in `generateClient`**
+
+In `src/codegen/index.ts`, add to `GenerateClientOptions` (after line 20, `sharedTypesImport?`):
+
+```ts
+  /** Single module every $id-bearing model re-exports from (convention; `sharedTypesImport` entries override). */
+  sharedModelsModule?: string
+```
+
+And in the `runPipeline({ ... })` call (after line 46, `sharedTypesImport: options.sharedTypesImport,`):
+
+```ts
+    sharedModelsModule: options.sharedModelsModule,
+```
+
+- [ ] **Step 3d: Consume in the TS run**
+
+In `src/codegen/targets/ts/run.ts`, add `sharedModelsModule` to the destructure (after line 35, `sharedTypesImport,`):
+
+```ts
+    sharedModelsModule,
+```
+
+And pass it to `resolveModelImports` (replace lines 62-64):
+
+```ts
+  const models = shareModels
+    ? resolveModelImports(collectModels(envelope.routes), sharedTypesImport, sharedModelsModule)
+    : []
+```
+
+- [ ] **Step 4: Run test to verify it passes**
+
+Run: `npx vitest run src/codegen/targets/ts/shared-models.test.ts`
+Expected: PASS (existing + 2 new tests).
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/codegen/targets/_shared/target-run.ts src/codegen/pipeline.ts src/codegen/index.ts src/codegen/targets/ts/run.ts src/codegen/targets/ts/shared-models.test.ts
+git commit -m "feat(codegen): thread sharedModelsModule convention through pipeline to TS run"
+```
+
+---
+
+## #B — Footgun diagnostics
+
+### Task 3: Always-on summary + `--strict-shared-models` hard-fail
+
+**Files:**
+- Modify: `src/codegen/targets/_shared/target-run.ts` (add `strictSharedModels?: boolean`)
+- Modify: `src/codegen/pipeline.ts` (`PipelineOptions` + `base`)
+- Modify: `src/codegen/index.ts` (`GenerateClientOptions` + pass-through)
+- Modify: `src/codegen/targets/ts/run.ts` (summary log + strict throw)
+- Test: `src/codegen/targets/ts/shared-models.test.ts`
+
+- [ ] **Step 1: Write the failing test**
+
+Append inside the existing `describe('shared models ...')` block in `src/codegen/targets/ts/shared-models.test.ts`:
+
+```ts
+it('logs a neutral summary of the re-exported / generated split', async () => {
+  const log = vi.spyOn(console, 'log').mockImplementation(() => {})
+  try {
+    await runPipeline({
+      envelope: modelEnvelope(),
+      outDir: 'out',
+      dryRun: true,
+      shareModels: true,
+      namespaceTypes: true,
+      selfContained: false,
+    })
+    expect(log).toHaveBeenCalledWith(
+      expect.stringContaining('Shared models: 1 total — 0 re-exported, 1 generated locally.'),
+    )
+  } finally {
+    log.mockRestore()
+  }
+})
+
+it('does not log a summary when there are no $id-bearing models', async () => {
+  const log = vi.spyOn(console, 'log').mockImplementation(() => {})
+  try {
+    await runPipeline({
+      envelope: noModelEnvelope(),
+      outDir: 'out',
+      dryRun: true,
+      shareModels: true,
+      namespaceTypes: true,
+      selfContained: false,
+    })
+    expect(log.mock.calls.flat().join('\n')).not.toContain('Shared models:')
+  } finally {
+    log.mockRestore()
+  }
+})
+
+it('strictSharedModels throws listing every $id generated as a local twin', async () => {
+  await expect(
+    runPipeline({
+      envelope: modelEnvelope(),
+      outDir: 'out',
+      dryRun: true,
+      shareModels: true,
+      namespaceTypes: true,
+      selfContained: false,
+      strictSharedModels: true,
+    }),
+  ).rejects.toThrow(/--strict-shared-models/)
+})
+
+it('strictSharedModels passes once every model is covered by the convention', async () => {
+  await expect(
+    runPipeline({
+      envelope: modelEnvelope(),
+      outDir: 'out',
+      dryRun: true,
+      shareModels: true,
+      namespaceTypes: true,
+      selfContained: false,
+      strictSharedModels: true,
+      sharedModelsModule: '@app/schemas',
+    }),
+  ).resolves.toBeDefined()
+})
+```
+
+Ensure `vi` is imported at the top of the file (change `import { describe, it, expect } from 'vitest'` to include `vi`):
+
+```ts
+import { describe, it, expect, vi } from 'vitest'
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `npx vitest run src/codegen/targets/ts/shared-models.test.ts`
+Expected: FAIL — no summary log is emitted; `strictSharedModels` is not accepted/enforced so the strict-throw test does not reject.
+
+- [ ] **Step 3a: Thread `strictSharedModels` through the type chain**
+
+In `src/codegen/targets/_shared/target-run.ts`, add to `TargetRunInput` (after the `sharedModelsModule` field added in Task 2):
+
+```ts
+  /** When true, hard-fail if any $id-bearing model has no shared-type mapping (would be a local twin). */
+  strictSharedModels?: boolean
+```
+
+In `src/codegen/pipeline.ts`, add to `PipelineOptions` (after `sharedModelsModule?: string`):
+
+```ts
+  strictSharedModels?: boolean
+```
+
+And to `base` (after `sharedModelsModule: options.sharedModelsModule,`):
+
+```ts
+    strictSharedModels: options.strictSharedModels,
+```
+
+In `src/codegen/index.ts`, add to `GenerateClientOptions` (after `sharedModelsModule?: string`):
+
+```ts
+  /** Hard-fail codegen if any $id-bearing model would be generated as a local structural twin. */
+  strictSharedModels?: boolean
+```
+
+And to the `runPipeline({ ... })` call (after `sharedModelsModule: options.sharedModelsModule,`):
+
+```ts
+    strictSharedModels: options.strictSharedModels,
+```
+
+- [ ] **Step 3b: Emit the summary + strict check in the TS run**
+
+In `src/codegen/targets/ts/run.ts`, add `strictSharedModels` to the destructure (after `sharedModelsModule,`):
+
+```ts
+    strictSharedModels = false,
+```
+
+Then insert this block immediately after the `_models` reserved-filename loop (after the closing `}` of the `if (shareModels) { for (const group of groups) { … } }` at line 75):
+
+```ts
+  if (shareModels && models.length > 0) {
+    const generated = models.filter((m) => m.import == null)
+    if (strictSharedModels && generated.length > 0) {
+      const list = generated.map((m) => `"${m.id}" (${m.name})`).join(', ')
+      throw new Error(
+        `[ts-procedures-codegen] --strict-shared-models: ${generated.length} $id-bearing schema(s) have no shared-type mapping and would be generated as local structural twins: ${list}. Add a sharedTypesImport entry, set sharedModelsModule, or drop --strict-shared-models.`,
+      )
+    }
+    const reExported = models.length - generated.length
+    console.log(
+      `[ts-procedures-codegen] Shared models: ${models.length} total — ${reExported} re-exported, ${generated.length} generated locally.`,
+    )
+  }
+```
+
+- [ ] **Step 4: Run test to verify it passes**
+
+Run: `npx vitest run src/codegen/targets/ts/shared-models.test.ts`
+Expected: PASS (existing + 4 new tests).
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/codegen/targets/_shared/target-run.ts src/codegen/pipeline.ts src/codegen/index.ts src/codegen/targets/ts/run.ts src/codegen/targets/ts/shared-models.test.ts
+git commit -m "feat(codegen): shared-models summary log + --strict-shared-models hard-fail"
+```
+
+---
+
+## #C — CLI surface
+
+### Task 4: Flag catalog entries
+
+**Files:**
+- Modify: `src/codegen/bin/flag-specs.ts:9-43`
+- Test: `src/codegen/bin/flag-specs.test.ts`
+
+- [ ] **Step 1: Write the failing test**
+
+Append to `src/codegen/bin/flag-specs.test.ts` (inside the existing `describe('flag-specs', …)` block):
+
+```ts
+it('catalogs the shared-models convention + strict flags', () => {
+  expect(KNOWN_FLAGS).toContain('--shared-models-module')
+  expect(KNOWN_FLAGS).toContain('--strict-shared-models')
+})
+
+it('documents the new flags in --help output', () => {
+  const help = formatHelp()
+  expect(help).toContain('--shared-models-module')
+  expect(help).toContain('--strict-shared-models')
+})
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `npx vitest run src/codegen/bin/flag-specs.test.ts`
+Expected: FAIL — neither flag is in `FLAG_SPECS`, so `KNOWN_FLAGS`/`formatHelp` lack them.
+
+- [ ] **Step 3: Add the spec entries**
+
+In `src/codegen/bin/flag-specs.ts`, add to the `FLAG_SPECS` array in the `Codegen` group (after the `--no-share-models` entry, line 29):
+
+```ts
+  { name: '--shared-models-module', arg: '<module>', description: 'Re-export every $id model from one module (convention; sharedTypesImport overrides)', group: 'Codegen' },
+  { name: '--strict-shared-models', description: 'Fail if any $id model would be generated as a local twin', group: 'Codegen' },
+```
+
+- [ ] **Step 4: Run test to verify it passes**
+
+Run: `npx vitest run src/codegen/bin/flag-specs.test.ts`
+Expected: PASS.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/codegen/bin/flag-specs.ts src/codegen/bin/flag-specs.test.ts
+git commit -m "feat(codegen): catalog --shared-models-module and --strict-shared-models flags"
+```
+
+---
+
+### Task 5: CLI parse, config, watch + main wiring
+
+**Files:**
+- Modify: `src/codegen/bin/cli.ts:14-33` (`CodegenConfig`), `35-54` (`ParsedArgs`), `152-340` (`parseArgs`), `360-441` (`runWithWatch`), `496-568` (`main`)
+- Test: `src/codegen/bin/cli.test.ts`
+
+- [ ] **Step 1: Write the failing test**
+
+Append to `src/codegen/bin/cli.test.ts` (match the file's existing `parseArgs` describe/import style):
+
+```ts
+it('parses --shared-models-module into sharedModelsModule', () => {
+  const parsed = parseArgs(['--out', 'gen', '--file', 'e.json', '--shared-models-module', '@app/schemas'])
+  expect(parsed.sharedModelsModule).toBe('@app/schemas')
+})
+
+it('parses --strict-shared-models as a boolean (default false)', () => {
+  expect(parseArgs(['--out', 'gen', '--file', 'e.json']).strictSharedModels).toBe(false)
+  expect(
+    parseArgs(['--out', 'gen', '--file', 'e.json', '--strict-shared-models']).strictSharedModels,
+  ).toBe(true)
+})
+
+it('CLI --shared-models-module overrides a config value', () => {
+  const parsed = parseArgs(
+    ['--out', 'gen', '--file', 'e.json', '--shared-models-module', '@cli/pkg'],
+    { sharedModelsModule: '@config/pkg' },
+  )
+  expect(parsed.sharedModelsModule).toBe('@cli/pkg')
+})
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `npx vitest run src/codegen/bin/cli.test.ts`
+Expected: FAIL — `parseArgs` rejects `--shared-models-module` as an unknown flag (and `ParsedArgs` lacks the fields).
+
+- [ ] **Step 3a: Extend `CodegenConfig` and `ParsedArgs`**
+
+In `src/codegen/bin/cli.ts`, add to `CodegenConfig` (after `sharedTypesImport?: SharedTypesImportMap`, line 32):
+
+```ts
+  sharedModelsModule?: string
+  strictSharedModels?: boolean
+```
+
+Add to `ParsedArgs` (after `sharedTypesImport?: SharedTypesImportMap`, line 53):
+
+```ts
+  sharedModelsModule?: string
+  strictSharedModels: boolean
+```
+
+- [ ] **Step 3b: Read config defaults + add parse branches**
+
+In `parseArgs`, add config-seeded locals (after line 172, `const sharedTypesImport = config?.sharedTypesImport`):
+
+```ts
+  let sharedModelsModule: string | undefined = config?.sharedModelsModule
+  let strictSharedModels = config?.strictSharedModels ?? false
+```
+
+Add parse branches (after the `--share-models` / `--no-share-models` branches, line 262):
+
+```ts
+    } else if (arg === '--shared-models-module') {
+      sharedModelsModule = argv[++i]
+    } else if (arg === '--strict-shared-models') {
+      strictSharedModels = true
+```
+
+Add to the returned object (after `...(sharedTypesImport !== undefined ? { sharedTypesImport } : {}),`, line 338):
+
+```ts
+    ...(sharedModelsModule !== undefined ? { sharedModelsModule } : {}),
+    strictSharedModels,
+```
+
+- [ ] **Step 3c: Forward through `runWithWatch` and `main`**
+
+In `runWithWatch`, add to the `runPipeline({ … })` call (after `...(parsed.sharedTypesImport !== undefined ? { sharedTypesImport: parsed.sharedTypesImport } : {}),`, line 427):
+
+```ts
+        ...(parsed.sharedModelsModule !== undefined ? { sharedModelsModule: parsed.sharedModelsModule } : {}),
+        strictSharedModels: parsed.strictSharedModels,
+```
+
+In `main`, add to the `generateClient({ … })` call (after `...(parsed.sharedTypesImport !== undefined ? { sharedTypesImport: parsed.sharedTypesImport } : {}),`, line 557):
+
+```ts
+      ...(parsed.sharedModelsModule !== undefined ? { sharedModelsModule: parsed.sharedModelsModule } : {}),
+      strictSharedModels: parsed.strictSharedModels,
+```
+
+- [ ] **Step 4: Run test to verify it passes**
+
+Run: `npx vitest run src/codegen/bin/cli.test.ts`
+Expected: PASS.
+
+- [ ] **Step 5: Full suite + lint + build**
+
+Run: `npm run test && npm run lint && npm run build`
+Expected: all green (catches any missed threading site, e.g. a type error in `runWithWatch`/`main`).
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add src/codegen/bin/cli.ts src/codegen/bin/cli.test.ts
+git commit -m "feat(codegen): CLI flags for sharedModelsModule + strict-shared-models"
+```
+
+---
+
+## #D — Documentation & downstream response
+
+### Task 6: Update repo docs
+
+**Files:**
+- Modify: `CLAUDE.md` (the `Client Code Generation` section, around the `shareModels` / `sharedTypesImport` bullets)
+- Modify: `docs/client-and-codegen.md`
+
+- [ ] **Step 1: Update CLAUDE.md**
+
+In the `Client Code Generation` section, after the existing `sharedTypesImport` bullet, add:
+
+```markdown
+  - `sharedModelsModule` (config / `--shared-models-module <module>`) is the convention form of `sharedTypesImport`: every `$id`-bearing model with no explicit map entry is re-exported from this single module under its derived name (`$id`/`title` === export). Precedence in `resolveModelImports`: explicit `sharedTypesImport[$id]` → `sharedModelsModule` → generate locally. Use the per-`$id` map only for overrides (rename, a different package per type, multi-consumer setups).
+  - **Shared-models diagnostics:** every run with `$id`-bearing models logs a neutral one-line summary (`Shared models: N total — X re-exported, Y generated locally.`) so a silently-generated structural twin is visible. `strictSharedModels` (`--strict-shared-models`, default off) turns that into a hard error listing each `$id` that would be generated locally — a CI guard against the single-source-of-truth silently degrading. (Source-tree scanning, e.g. `--shared-types-from <dir>`, was deliberately rejected: codegen stays pure-envelope so `--url`/offline `--file` codegen never depends on a local source tree.)
+```
+
+- [ ] **Step 2: Update docs/client-and-codegen.md**
+
+Locate the shared-types / `sharedTypesImport` subsection and add a short subsection documenting `sharedModelsModule` (the one-value convention) with a config + CLI example, plus the summary log and `--strict-shared-models` CI usage. Match the surrounding heading depth and prose style. Example block to include:
+
+```jsonc
+// ts-procedures-codegen.config.json — collapse the per-$id map to one module
+{ "sharedModelsModule": "@app/schemas" }
+```
+```bash
+# CI: fail the build if any domain entity is generated as a structural twin
+npx ts-procedures-codegen --file envelope.json --out gen --strict-shared-models
+```
+
+- [ ] **Step 3: Verify the docs gate passes**
+
+Run: `npm run lint`
+Expected: PASS (also satisfies any `check-docs` gate referenced in recent commits).
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add CLAUDE.md docs/client-and-codegen.md
+git commit -m "docs: document sharedModelsModule convention + shared-models diagnostics"
+```
+
+---
+
+### Task 7: Downstream response write-up
+
+**Files:**
+- Create: `docs/handoffs/shared-models-auto-resolve-response.md`
+
+- [ ] **Step 1: Write the response doc**
+
+Create `docs/handoffs/shared-models-auto-resolve-response.md` with:
+- **What shipped:** `sharedModelsModule` (one value replaces the hand-maintained map for the common single-module case), the always-on summary, and `--strict-shared-models` (replaces their hand-written `toEqualTypeOf` drift test with a CI flag). All available as CLI flag + config + `generateClient()` option.
+- **Maps their three pain points to the fix:** (1) two-places-in-lockstep → one `sharedModelsModule` value, derived not hand-maintained; (2) silent fallback → always-on summary + strict hard-fail; (3) redundant map → convention (`name = $id`, module supplied once).
+- **Why `--shared-types-from <dir|glob>` was declined:** the codegen's input contract is the DocEnvelope only — it never reads the consumer source tree. Scanning source breaks `--url`/offline `--file` (local source can disagree with the envelope, yielding a silently-wrong-but-typechecking single source of truth), fails for published-package consumers, and drags a TS parser/loader + glob + export-resolution heuristics into codegen. The convention achieves the same "define-once, no second table" goal without any of that.
+- **Escape hatch unchanged:** the per-`$id` `sharedTypesImport` map remains for rename / different-package-per-type / multi-consumer.
+
+- [ ] **Step 2: Commit**
+
+```bash
+git add docs/handoffs/shared-models-auto-resolve-response.md
+git commit -m "docs(handoff): shared-models auto-resolve response; rationale for declining source scanning"
+```
+
+---
+
+## Self-Review
+
+- **Spec coverage:** Pain #1 (two-places-in-lockstep, redundant map) → Tasks 1–2 (`sharedModelsModule` convention) + Task 5 (CLI) + Task 6 (docs). Pain #2 (silent fallback) → Task 3 (summary + strict). Secondary ask (config-only / no CLI flag) → Tasks 4–5. Declined primary (`--shared-types-from`) → Task 7 rationale. Out-of-scope items called out in the header. ✅
+- **Placeholder scan:** every code step shows the exact insertion; Task 6 step 2 references "the surrounding style" but provides concrete example blocks. No TODO/TBD. ✅
+- **Type consistency:** option names are identical across every layer — `sharedModelsModule: string`, `strictSharedModels: boolean` — in `TargetRunInput`, `PipelineOptions`, `GenerateClientOptions`, `CodegenConfig`, `ParsedArgs`; CLI flags `--shared-models-module`, `--strict-shared-models`; `resolveModelImports(models, map, sharedModelsModule)`. ✅
+- **Backward compatibility:** all new options default to unset/false; when neither is set, `resolveModelImports` and emitted output are byte-identical to today (summary only prints when `$id` models exist). ✅