@shipispec/tsfix 0.1.0 → 0.3.0

package/CHANGELOG.md

@@ -0,0 +1,104 @@
+# Changelog
+
+All notable changes to `@shipispec/tsfix` are documented here. Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); versioning follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.3.0] - 2026-05-07
+
+Phase 2 contract release. **Establishes the public types `MendContext`, `LayerEvent`, and `Diagnostic` so a downstream LLM-mend package (e.g. `@shipispec/tsmend`) can consume tsfix's output without redefining the shape.** No behavior changes; purely additive types. Also collapses several dev-only improvements that landed since v0.2.0 into a single release.
+
+### Added
+- **`MendContext` interface** — public type defining the input contract for a Layer 2–4 LLM-mend agent. Required fields: `workspaceRoot`, `diagnostics`, `erroredFiles`. Optional fields: `taskDescription`, `featureSpecText`, `acceptanceCriteria`, `siblingTasks`, `priorTaskExports`, `installedTypes`.
+- **`LayerEvent` interface** — per-layer event shape for streaming telemetry. Designed for an `onLayerEvent` callback in a future minor release; the type is published now so downstream callers can construct events themselves.
+- **`Diagnostic` type alias** — public re-export of `InProcessTscResult["diagnostics"][number]`. Convenience for consumers building `MendContext`.
+- **Project-shape matrix** (`scripts/run-matrix.mjs`, `npm run matrix`) — pre-publish gate that builds the local tarball and exercises it cold against 6 distinct project shapes: `monorepo-refs` (project references — pinned as a documented limitation), `next-app` (App Router, `paths` alias, `jsx: preserve`), `plain-ts-bundler` (esnext + bundler), `plain-ts-commonjs` (legacy CJS + ES2015 + node10), `plain-ts-nodenext` (nodenext resolution), `react-vite` (TSX + `jsx: react-jsx`). 6/6 pass. Dev-only — not shipped in the tarball.
+- **Capture script** (`scripts/capture-fixture.mjs`, `npm run capture`) — Phase 3b tooling for snapshotting real broken workspaces into `fixtures/real-<name>/`. Awaits first real failure to produce fixtures.
+- **GitHub Actions CI** (`.github/workflows/test.yml`) — runs check-types, vitest, benchmark, and the matrix on every PR + main push.
+
+### Changed
+- **Repository moved.** `tsc-defense-stack/` was extracted from the `spectoship-meta` monorepo into its own repository at <https://github.com/owgreen-dev/tsfix>. All `repository.url`, `homepage`, `bugs.url` fields point at the new repo. Internal git history pre-2026-05-06 lives in the original monorepo; the CHANGELOG narrates v0.1.0–v0.2.0 in detail.
+- **Public README rewritten** for an OSS audience — tagline, before/after, 30-second cold start, four-layer model, library API, trust model, contributing protocol. Previous internal-orientation README preserved at `docs/internal-orientation.md`.
+
+### Engines
+- Node `>=20.9.0` (unchanged)
+- TypeScript `>=5.0.0` peer (unchanged)
+
+## [0.2.0] - 2026-05-04
+
+Phase 1a complete. **Plain Node consumers can now `import` the package without a TypeScript loader, and `npx @shipispec/tsfix` works cold.** Folds in everything that was queued for v0.1.1 (which was never published — its commit is now part of v0.2.0).
+
+### Added
+- **esbuild bundle** in `dist/`. Three artifacts: `dist/index.js` (library, ESM bundle), `dist/cli.js` (CLI, ESM with shebang, executable), `dist/index.d.ts` (public type declarations from `tsc --emitDeclarationOnly`). Per-file `.d.ts` files in `dist/types/` for callers wanting subpath types.
+- `npm run build` → `node scripts/build.mjs`. Also runs as `prepublishOnly` so `npm publish` always ships fresh `dist/`.
+- **`--dry-run` flag** on the CLI and `dryRun` option on `runValidationLoop` and `runLSPFixerPass`. Runs the full LSP fix loop in memory; reports what *would* be edited; no disk writes. Resolves the documented footgun where pointing tsfix at a fixture irreversibly mutated it. (Audit M-E4.)
+- **Trust model section** in README: `tsfix` loads `typescript` from your workspace's `node_modules`. Only run on workspaces you trust. (Audit M-S1.)
+- **Troubleshooting section** in README covering the most likely user errors (`ERR_MODULE_NOT_FOUND` for typescript; missing `tsconfig.json`).
+- **Dev-vs-consumer guidance** in README. (Audit M-E3.)
+- **3 dryRun unit tests** in `src/dryRun.test.ts`.
+
+### Changed
+- **Package shape**: `main`/`types`/`exports` now point at `dist/`, not `src/`. `bin.tsfix` points at `dist/cli.js` directly. `files` array ships `dist/` only (no more `src/`, `cli/`, `bin/` in tarball). Tarball: 10 files, 16.8 KB packed.
+- **Removed `bin/tsfix.mjs` wrapper** — replaced by the bundled `dist/cli.js`. The wrapper was a Phase 0c bridge that depended on local `tsx`; the bundle drops that dependency.
+- **Dropped `./validation` and `./lsp-fixer` subpath exports** — unused; the only consumer (spectoship2 shims) imports from the main entry. Easy to re-add if needed.
+- README CLI section rewritten to reflect Phase 0c standalone install (no longer references the old `cd spectoship2 && tsx ../tsc-defense-stack/...` flow).
+
+### Fixed
+- **Plain Node `import { runValidationLoop } from "@shipispec/tsfix"` now works.** Was previously blocked by Node 22+ refusing to type-strip `.ts` files in `node_modules` (audit H-E1). Verified end-to-end via `npm install` from tarball + `node use-as-library.mjs`.
+- **`npx @shipispec/tsfix --workspace ./project` now works cold.** Was previously blocked by the bin wrapper requiring `tsx` from the package's own `node_modules` (audit M-E2).
+- `bin/tsfix.mjs` error message no longer references the old `tsc-defense` name (n/a in 0.2.0 — wrapper deleted entirely; audit M-E1).
+- `cli/run-stack.ts` no longer ships with executable permission bits (the bundled `dist/cli.js` does, which is correct since it's the actual entry; audit L-S2).
+
+### Engines
+- Node `>=20.9.0` (unchanged)
+- TypeScript `>=5.0.0` peer (unchanged; npm 7+ auto-installs)
+
+### Outstanding from audit (deferred)
+- L-S1 (npm `--provenance` for supply-chain attestation) — Phase 1b CI publish.
+
+## [0.1.1] - 2026-05-04
+
+Patch release addressing the medium-severity findings from the post-publish audit (`docs/audit-2026-05-04.md`). No API breaks; consumers can upgrade with `npm install @shipispec/tsfix@latest`.
+
+### Added
+- **`--dry-run` flag** on the CLI and a corresponding `dryRun` option on `runValidationLoop` and `runLSPFixerPass`. Runs the full LSP fix loop in memory and reports what *would* be edited, but does not write to disk. Resolves the documented footgun where running `tsfix` against a fixture directory irreversibly mutated the broken code. (Audit M-E4.)
+- **Trust model section** in README: explicit disclosure that `tsfix` loads `typescript` from the workspace's `node_modules`, with the standard "only run on workspaces you trust" warning. (Audit M-S1.)
+- **Dev-vs-consumer guidance** in README: clarifies that `npm scripts` shipped in the published `package.json` (benchmark/test/setup-fixtures) are for contributors only — consumer-side `node_modules/@shipispec/tsfix/` doesn't have `tsx`/`vitest`/`fixtures/`. (Audit M-E3.)
+
+### Fixed
+- `bin/tsfix.mjs` error message no longer references the old `tsc-defense` name; now describes the correct `tsfix` flow when `tsx` cannot be resolved. (Audit M-E1.)
+- `cli/run-stack.ts` no longer ships with executable permission bits (was `-rwxr-xr-x`, now `-rw-r--r--`). The file is loaded by `tsx`, never run directly. (Audit L-S2.)
+
+### Changed
+- README CLI section rewritten to reflect Phase 0c standalone install (no longer references the old monorepo `cd spectoship2 && tsx ../tsc-defense-stack/...` flow).
+
+## [0.1.0] - 2026-05-04
+
+Initial public release. **Layers 0–1 only** (deterministic detection + auto-fix). LLM-driven mend layers stay in `spectoship2/` until v0.2.
+
+### Added
+- **`runValidationLoop(opts)`** — full deterministic loop (validate → auto-fix → re-validate). Recommended entry point.
+- **`runInProcessTsc(opts)`** — in-process `tsc --noEmit` returning structured diagnostics. No subprocess spawn, no Node 23 startup-pause issue. Workspace lib-path override (uses the workspace's `node_modules/typescript` so globals resolve under esbuild bundling).
+- **`runLSPFixerPass(opts)`** — Layer 0 deterministic auto-fixer using `ts.LanguageService.getCodeFixesAtPosition`. Strictly opt-in by error code and fix name:
+  - `SAFE_FIXABLE_CODES`: `TS2304`, `TS2305`, `TS2551`, `TS2552`, `TS2724`
+  - `SAFE_FIX_NAMES`: `import`, `fixImport`, `spelling`, `fixSpelling`
+  - 5-iteration cap with signature-set progress check (stops when the `(file, start, code)` set repeats)
+  - Multi-fix equivalence check abstains when candidate fixes produce different edits
+- **`discoverTsFiles(workspaceRoot)`** — file-discovery helper. Includes `.ts`/`.tsx`; excludes `.d.ts` and `node_modules`/`.next`/`dist`/`build`/`out`/`coverage`/`.git`.
+- **CLI** (`tsfix --workspace <path>`, after `npm link`). Flags: `--json`, `--no-lsp`, `--verbose`, `--files <comma-list>`, `--help`. Exit 0 = clean, 1 = errors remain, 2 = bad args.
+- **MIT license**, no runtime deps except peer `typescript >=5.0.0`.
+
+### Known limitations
+- **`npx @shipispec/tsfix ./project`** does not work for cold-start. The bin wrapper requires `tsx` to be resolvable from the package's own `node_modules`. Use `npm install @shipispec/tsfix && npm link` for now. Phase 1a (esbuild bundle) addresses this.
+- **`export { X } from "./mod"`** — TS LanguageService returns zero code-fixes for typos in this syntactic position. Documented in `fixtures/synthetic-cross-file-typo-ts2305/`.
+- **Footgun:** the CLI mutates files in place with no snapshot/restore. Don't point it at the package's own `fixtures/` directories during dev — use `npm run benchmark` instead, which snapshots and restores.
+
+### Engines
+- Node `>=20.9.0` (matches VS Code Extension Host runtime)
+- TypeScript `>=5.0.0` (peer dep, must be installed in the consuming workspace)
+
+[Unreleased]: https://github.com/owgreen-dev/tsfix/compare/v0.3.0...HEAD
+[0.3.0]: https://github.com/owgreen-dev/tsfix/compare/v0.2.0...v0.3.0
+[0.2.0]: https://github.com/owgreen-dev/tsfix/compare/v0.1.1...v0.2.0
+[0.1.1]: https://github.com/owgreen-dev/tsfix/compare/v0.1.0...v0.1.1
+[0.1.0]: https://github.com/owgreen-dev/tsfix/releases/tag/v0.1.0

package/README.md

@@ -1,120 +1,178 @@
-# TSC Defense Stack — `@shipispec/tsfix`
+# tsfix
 
-Standalone npm package implementing **Layers 0–1** of the TypeScript error-recovery stack: in-process tsc validation + deterministic LSP auto-fix. Layers 2–4 (LLM mend) currently live in `spectoship2/src/pipeline/` and will move to a sister package `@shipispec/tsmend` per the roadmap.
+> Headless TypeScript error recovery — auto-resolve `TS2304`, `TS2305`, `TS2551`, `TS2552`, `TS2724` before they reach a human.
 
-Read first:
-- `STATUS.md` — what's working, what's planned, current gaps
-- `ARCHITECTURE.md` — why the package is shaped the way it is
-- `tsc-defense-roadmap.md` — phased plan with open decisions
-- `CLAUDE.md` — working principles (small allowlist, fixture-pinned trust model)
+`@shipispec/tsfix` borrows the same TypeScript Language Service that powers VS Code's "Quick Fix" lightbulb and runs it as a CLI. Point it at a workspace, it fixes typos, missing imports, and did-you-mean errors deterministically — no LLM, no calls home, no config.
 
----
+Built for the case where you've just generated a few hundred files of TypeScript with an LLM and `tsc --noEmit` is screaming at you.
 
-## Source-of-truth map
+## Before / after
 
-This package owns its TypeScript-error handling code outright. The shims in `spectoship2/` re-export from here, not the reverse.
+```
+$ tsc --noEmit
+src/api.ts:5:2  - error TS2552: Cannot find name 'consol'. Did you mean 'console'?
+src/api.ts:8:5  - error TS2305: Module '"react"' has no exported member 'ueState'.
+src/api.ts:12:14 - error TS2551: Property 'lenght' does not exist on type 'string[]'. Did you mean 'length'?
 
-| Path | Role |
-|---|---|
-| `src/index.ts` | Public API (`runValidationLoop`, `runInProcessTsc`, `runLSPFixerPass`, `discoverTsFiles`) |
-| `src/validatorInProcess.ts` | In-process tsc with lib-path workaround (Layer 0) |
-| `src/tsLanguageServiceFixer.ts` | LSP auto-fixer using `getCodeFixesAtPosition` (Layer 1) |
-| `cli/run-stack.ts` | CLI: `tsx cli/run-stack.ts --workspace <path>` |
-| `benchmark/run-benchmark.ts` | Fixture harness (auto-discovers `fixtures/*/`) |
-| `fixtures/` | 14 hand-authored synthetic fixtures across 3 tiers |
-| `spectoship2/src/pipeline/validatorInProcess.ts` | **Re-export shim** → `@shipispec/tsfix` |
-| `spectoship2/src/pipeline/tsLanguageServiceFixer.ts` | **Re-export shim** → `@shipispec/tsfix` |
+Found 3 errors in 1 file.
 
----
+$ npx @shipispec/tsfix --workspace .
+[ts-lsp-fixer] applied 3 fixes across 1 file
 
-## How the layers fit together
+$ tsc --noEmit
+$ # 0 errors
+```
 
-Per `ARCHITECTURE.md`, a TSC error has up to four chances to die before reaching a user. Layers -1 (prevention) and 2-4 (mend) live outside this package.
+## 30-second cold start
 
+```bash
+cd your-broken-project
+npx @shipispec/tsfix --workspace .
 ```
-                    ┌─────────────────────────────────────────────────┐
-                    │ Layer -1: PREVENTION (in spectoship2/, not here)│
-                    │   packageGotchas, installedExports, priorExports│
-                    │   codeGenPrompts (rules injected into prompt)    │
-                    └────────────────────┬────────────────────────────┘
-                                         │ files written to disk
-                                         ▼
-  ┌────── @shipispec/tsfix ───────┴──────────────────────────┐
-  │                                                                  │
-  │   ┌─────────────────────────────────────────────┐               │
-  │   │ Layer 0: src/validatorInProcess.ts           │               │
-  │   │   in-process tsc → structured diagnostics    │               │
-  │   │   workspace lib-path override                │               │
-  │   └─────────────────────┬───────────────────────┘               │
-  │                         │ if errors                              │
-  │                         ▼                                        │
-  │   ┌─────────────────────────────────────────────┐               │
-  │   │ Layer 1: src/tsLanguageServiceFixer.ts       │               │
-  │   │   getCodeFixesAtPosition (5 SAFE codes)      │               │
-  │   │   signature-set progress check, max 5 iters  │               │
-  │   └─────────────────────┬───────────────────────┘               │
-  │                         │ re-validate; if errors remain          │
-  └─────────────────────────┼─────────────────────────────────────────┘
-                            ▼
-                 ┌─────────────────────────────────┐
-                 │ Layers 2-4: LLM MEND            │
-                 │   mendAgent / mendArchitect /   │
-                 │   multiFileMend / repairAgent   │
-                 │   (in spectoship2/, not here;   │
-                 │    moves to @shipispec/tsmend│
-                 │    in v0.2 per roadmap)         │
-                 └─────────────────────────────────┘
+
+No config file. Exit code conventions:
+
+| Code | Meaning |
+|---|---|
+| 0 | Workspace is clean |
+| 1 | Errors remain (printed to stderr) |
+| 2 | Bad arguments / harness error |
+
+Preview what *would* change without writing to disk:
+
+```bash
+npx @shipispec/tsfix --workspace . --dry-run
 ```
 
----
+Machine-readable output for piping into other tools:
+
+```bash
+npx @shipispec/tsfix --workspace . --json
+```
+
+### All flags
+
+| Flag | Meaning |
+|---|---|
+| `--workspace <path>` | Required. Directory containing your `tsconfig.json`. |
+| `--dry-run` | Run the fixer in memory, report counts, write nothing. |
+| `--no-lsp` | Validate only — skip auto-fix. |
+| `--files <a.ts,b.ts>` | Restrict fixing to a comma-separated list. |
+| `--json` | Machine-readable output. |
+| `--verbose` | Per-fix logging. |
+| `--help` | Print usage. |
+
+## What it fixes
+
+| TS code | Meaning | What tsfix does |
+|---|---|---|
+| `TS2304` | Cannot find name | Auto-imports |
+| `TS2305` | Module has no exported member | Did-you-mean rename |
+| `TS2551` | Property does not exist on T, did you mean Y | Spelling fix |
+| `TS2552` | Cannot find name, did you mean Y | Spelling fix |
+| `TS2724` | Module member did-you-mean | Import rename |
+
+Against a 14-fixture benchmark spanning typos, did-you-mean cases, multi-file ripples, and 4 API-drift scenarios: **14/14 fixtures pass and 14/25 errors are auto-fixed (56%).** The remaining errors are intentionally outside Layer 0's scope (see below).
+
+## What it does *not* fix
 
-## What to read first
+By design, tsfix only applies fixes that are **deterministic** and **non-structural**. It will refuse to:
 
-1. **`STATUS.md`** — current state, fixture catalog, recent fixes
-2. **`ARCHITECTURE.md`** — why the package is shaped the way it is (12 sections)
-3. **`tsc-defense-roadmap.md`** — phased plan with open decisions
-4. **`src/index.ts`** — public API entry point (`runValidationLoop`)
-5. **`src/tsLanguageServiceFixer.ts`** — Layer 1 fixer; understand `SAFE_FIXABLE_CODES`, the signature-set progress check, and the iteration loop
-6. **`src/validatorInProcess.ts`** — in-process tsc with the lib-path workaround that makes the package work inside the VS Code Extension Host
+- Add or remove function declarations
+- Insert type annotations or change types
+- Modify control flow (`await` insertions, async propagation)
+- Rewrite JSX trees
+- Add object-literal stub properties
 
----
+The internal allowlist is two-layered: error codes (`SAFE_FIXABLE_CODES`) and Quick Fix names (`SAFE_FIX_NAMES = ['import', 'fixImport', 'spelling', 'fixSpelling']`). When the language service offers anything outside that allowlist, tsfix abstains and surfaces the error in the result so a higher layer (LLM, human) can pick it up.
 
-## Standalone harness
+## The four-layer model
+
+tsfix is **Layer 0–1** of a larger error-recovery stack. The other layers are LLM-driven and live elsewhere (in your own code, or in companion packages):
 
 ```
-cli/run-stack.ts             # CLI: run stack on any workspace
-benchmark/run-benchmark.ts   # benchmark across all fixtures
-fixtures/                    # 14 hand-authored synthetic workspaces
-  _shared/                   # shared node_modules symlink target
-  clean-baseline/            # regression check (must stay green)
-  synthetic-*/               # 9 LSP-behavior fixtures (positive + negative)
-  api-drift-*/               # 4 version-drift fixtures (Zod 3 vs 4, React 18 vs 19, etc.)
+Layer 0 — Prevention      (prompt rules, exported-API injection — your problem)
+Layer 1 — tsfix           (this package: deterministic auto-fix)
+─────────────────────────────────────────────────────────────────────────
+Layer 2 — Single-file LLM mend (architect + editor split)
+Layer 3 — Multi-file LLM mend  (blast-radius search/replace)
+Layer 4 — Stub-and-continue    (escape hatch)
 ```
 
-### Run the CLI
+The bet: roughly half of TypeScript errors in LLM output are deterministically fixable. By catching them in Layer 1, you dodge the LLM tax (latency, cost, nondeterminism) on the easy half.
 
+## Library API
+
+```typescript
+import { runValidationLoop } from '@shipispec/tsfix';
+
+const result = runValidationLoop({
+  workspaceRoot: '/path/to/your/project',
+  // Optional:
+  // targetFiles: ['src/api.ts'],
+  // dryRun: true,
+  // logger: { info: console.log, warn: console.warn, error: console.error },
+});
+
+result.errorsBefore;          // number
+result.errorsAfter;           // number
+result.lspFixer.fixesApplied; // number
+result.lspFixer.filesEdited;  // string[]
+result.passed;                // boolean — true if errorsAfter === 0
 ```
-cd /Users/ogg/Documents/microservices/Meta/spectoship2
-./node_modules/.bin/tsx ../tsc-defense-stack/cli/run-stack.ts --workspace <path>
-```
 
-Flags: `--json`, `--no-lsp`, `--verbose`, `--files <comma-list>`. Exit 0 = clean, 1 = errors remain, 2 = bad args.
+Other exports:
+
+- `runInProcessTsc(opts)` — validation only, no fixer. Returns structured diagnostics.
+- `runLSPFixerPass(opts)` — Layer 0 fixer alone, no validation loop wrapper.
+- `discoverTsFiles(workspaceRoot)` — file-walking helper. Skips `node_modules`, `.next`, `dist`, `build`, `out`, `coverage`, `.git`.
+
+## Trust model
+
+tsfix loads `typescript` from your workspace's `node_modules` — it does **not** bundle its own. This is intentional: it ensures the fixer behaves identically to the `tsc` your project actually compiles with.
 
-> Note: per Phase 0c of `tsc-defense-roadmap.md`, this package will gain its own local `node_modules` so commands run from inside the package directory. Today it shares `spectoship2/node_modules`.
+> **Run tsfix only on workspaces you trust.** Loading `typescript` from an attacker-controlled `node_modules` is equivalent to running `node_modules/.bin/tsc` against it.
 
-### Run the benchmark
+Other surface:
+
+- No network calls.
+- No telemetry.
+- No background processes.
+- No config files written or modified outside `--workspace`.
+
+## Engines
+
+- Node `>=20.9.0`
+- TypeScript `>=5.0.0` (peer dep — must be installed in your workspace)
+
+If your workspace has no `node_modules/typescript`, tsfix will fail with a clear error:
 
 ```
-cd /Users/ogg/Documents/microservices/Meta/spectoship2
-./node_modules/.bin/tsx ../tsc-defense-stack/benchmark/run-benchmark.ts
+error: this workspace has no TypeScript installed.
+run: npm install --save-dev typescript
 ```
 
-`--fixture <name>` to run a single fixture in isolation.
+## Contributing
+
+The contract for adding a fix:
+
+1. **Probe** — write a tiny test workspace with the exact error you want fixable. Drop it under `fixtures/<descriptive-name>/` with an `expected.json` declaring `errorsBefore`, `errorsAfterMax`, `lspFixesAppliedMin/Max`, and `mustPass`.
+2. **Verify** — run `npm run benchmark -- --fixture <name>` and inspect what the language service offers (the `fix.fixName` field).
+3. **Allowlist change** — if `fixName` is unsafe (`fixMissingFunctionDeclaration`, `addMissingPropertyAndOptional`, etc.), document why we don't trust it. Otherwise, add the error code to `SAFE_FIXABLE_CODES` and the fix name to `SAFE_FIX_NAMES` in `src/tsLanguageServiceFixer.ts`.
+4. **Lock it in** — confirm all existing fixtures still pass (`npm run benchmark`). Open a PR.
+
+Each new code/fix-name pair gets its own fixture. We don't trust the language service blindly — we trust it under specific, pinned conditions.
+
+`npm run matrix` runs the same package against 6 distinct project shapes (Next.js, Vite + React, plain `nodenext`, plain `bundler`, plain CommonJS, monorepo with project references). It builds the local tarball and exercises it cold; pre-publish gate.
 
-### Current baseline
+## License
 
-**14/14 synthetic fixtures pass. LSP fixer auto-resolves 14/25 errors (56%).** The remaining errors are intentional non-fixes — TS7006 implicit-any, TS2741 missing prop, API-drift errors that need the mend layer. See `STATUS.md` § Fixture catalog for the full list.
+MIT.
 
-### Capturing real-failure fixtures
+## See also
 
-Phase 3b in the roadmap. When a real spec-pipeline run produces a TSC error Layer 0-1 doesn't fix, snapshot the broken `.ts(x)` files into `fixtures/real-<timestamp>-<hash>/` with an `expected.json`. The fixture set then grows from production failures, not just synthetic ones.
+- `CHANGELOG.md` — release notes per version.
+- `ARCHITECTURE.md` — internal design rationale (the four-layer model, the workspace lib-path workaround).
+- `STATUS.md` — current snapshot, gaps, and roadmap state.
+- `tsc-defense-roadmap.md` — phased plan.
+- `docs/internal-orientation.md` — the original SpecToShip-context README, kept for contributors who want the design history.