ts-procedures 8.6.0 → 9.0.0

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

@@ -1,659 +0,0 @@
-# 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). ✅