ts-reviewer 1.0.0 → 1.2.0

package/README.md

@@ -14,16 +14,17 @@ Three modes, one skill:
 | **fix** | Reads the report and applies fixes file-by-file with tsc/lint/test verification |
 | **auto** | Runs scan, asks you to confirm, fixes everything, deletes the report if clean |
 
-The review covers six domains, each with its own detailed checklist:
-
-| Domain | Examples |
-|---|---|
-| **Type Safety** | `any` abuse, unsafe casts, non-null assertions, missing exhaustive checks |
-| **Security** | Injection, prototype pollution, ReDoS, path traversal, hardcoded secrets |
-| **Async Patterns** | Floating promises, race conditions, missing error propagation, `forEach(async...)` |
-| **Modernization** | `enum` → `as const`, missing `satisfies`, `using` keyword, `import type` |
-| **Code Quality** | Dead code, complexity, duplication, hacky patterns, error handling |
-| **Config** | tsconfig.json strict flags, module resolution, deprecated options |
+The review covers six domains by default, each with its own detailed checklist. Add `--arch` or `--full` to include architecture analysis:
+
+| Domain | Examples | Default |
+|---|---|---|
+| **Type Safety** | `any` abuse, unsafe casts, non-null assertions, missing exhaustive checks | ✓ |
+| **Security** | Injection, prototype pollution, ReDoS, path traversal, hardcoded secrets | ✓ |
+| **Async Patterns** | Floating promises, race conditions, missing error propagation, `forEach(async...)` | ✓ |
+| **Modernization** | `enum` → `as const`, missing `satisfies`, `using` keyword, `import type` | ✓ |
+| **Code Quality** | Dead code, complexity, duplication, hacky patterns, error handling | ✓ |
+| **Config** | tsconfig.json strict flags, module resolution, deprecated options | ✓ |
+| **Architecture** | Shallow modules, scattered concepts, tight coupling, dependency seams, testability | `--arch` / `--full` |
 
 ## Installation
 
@@ -75,7 +76,29 @@ Find issues in this project
 Audit the codebase for security and type safety problems
 ```
 
-Claude will analyze the project and write a report to `code-smells.md` in the project root (or `.claude/code-smells.md` if that directory exists).
+Claude will analyze the project and write a report to `code-smells.md` in the project root.
+
+#### Domain flags
+
+By default, only the six core domains run. Use flags to control which domains are active:
+
+| Flag | What runs |
+|---|---|
+| *(none)* | Type Safety, Security, Async, Modernization, Code Quality, Config |
+| `--arch` | Architecture only (shallow modules, coupling, dependency seams) |
+| `--full` | All seven domains |
+
+Examples:
+
+```
+Review my TypeScript code --arch
+```
+```
+Full audit --full
+```
+```
+Review architecture of this project
+```
 
 ### Fix — apply fixes from the report
 
@@ -136,6 +159,14 @@ Issues on unchanged lines are listed separately as pre-existing tech debt — in
 | **Medium** | Tech debt — clean up when you're already editing that file |
 | **Low** | Style and conventions — improve when convenient |
 
+Architecture findings use the same scale. Each candidate also carries a **Fixability** tag:
+
+| Fixability | Meaning |
+|---|---|
+| `auto` | Applied automatically during fix mode |
+| `needs-confirm` | Shown to you first — only applied after explicit approval |
+| `report-only` | Left as documentation — never auto-applied |
+
 ## Project Structure
 
 ```
@@ -153,21 +184,22 @@ ts-reviewer/
     ├── modernization.md              # Checklist: TS 5.9+ idioms, satisfies, using, as const
     ├── code-quality.md               # Checklist: complexity, dead code, naming, duplication
     ├── tsconfig.md                   # Checklist: strict flags, module resolution, deprecated
+    ├── architecture.md               # Checklist: shallow modules, coupling, seams, deepening
     └── fix-workflow.md               # Complete fix protocol: tests, verification, rollback
 ```
 
-**SKILL.md** (349 lines) is the orchestrator — it routes between scan/fix/auto modes, defines scope detection, severity scale, and report format. It stays under the 500-line recommended limit for Claude skills.
+**SKILL.md** is the orchestrator — it routes between scan/fix/auto modes, detects domain flags (`--arch`, `--full`), defines scope detection, severity scale, and report format.
 
-**Reference files** contain the detailed checklists and protocols. Each analysis agent reads only the reference file relevant to its domain, keeping context focused. The fix workflow is in its own reference file because it's a complex multi-step protocol.
+**Reference files** contain the detailed checklists and protocols. Each analysis agent reads only the reference file relevant to its domain, keeping context focused. Architecture analysis is opt-in and loaded only when the domain is active.
 
 ## How It Works Under the Hood
 
 ### Scan mode
 
-1. **Discovery** — maps the project, reads tsconfig.json, detects linter and test runner
+1. **Discovery** — detects domain flags, maps the project, reads tsconfig.json, detects linter and test runner. If architecture is active, also maps module relationships and checks for `docs/adr/`.
 2. **Diagnostics** — runs `tsc --noEmit`, linter, and LSP diagnostics (if available)
-3. **Analysis** — six specialized passes (sub-agents in Claude Code, sequential in Claude.ai), each with its own checklist
-4. **Report** — deduplicates, applies severity boost (scoped modes), consolidates recurring patterns, writes `code-smells.md`
+3. **Analysis** — specialized passes for each active domain (sub-agents in Claude Code, sequential in Claude.ai), each with its own checklist
+4. **Report** — deduplicates, applies severity boost (scoped modes), consolidates recurring patterns, writes `code-smells.md`. Architecture findings appear in a separate `## Architecture Opportunities` section at the end.
 
 ### Fix mode
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ts-reviewer",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "description": "Install the TypeScript Code Reviewer skill for Claude Code, Codex, or Antigravity",
   "license": "MIT",
   "repository": {

package/ts-reviewer/SKILL.md

@@ -1,18 +1,12 @@
 ---
 name: ts-reviewer
 description: >
-  Deep TypeScript code review and auto-fix tool. Three modes: scan (find issues),
-  fix (apply fixes from scan report), auto (scan + fix + verify in one pass).
-  Supports scoped review: full codebase, uncommitted changes, branch diff (PR review),
-  or last N commits. Outputs a prioritized report and can auto-fix issues with
-  regression tests and verification.
-  Use this skill whenever the user asks to "review", "audit", "check", "lint", "find issues",
-  "find problems", "find bugs", "fix issues", "fix code smells", "auto-fix",
-  "review and fix", "clean up code", or "review code quality" in a TypeScript project.
-  Also trigger when the user mentions "tech debt", "code health", "refactor candidates",
-  "security audit", "modernize", "review my changes", "review my PR", "check what I changed",
-  "review last commit", or "review uncommitted" in a TypeScript context. Works with pure
-  TypeScript 5.9+ codebases — no framework-specific checks (React, Vue, Angular, etc.).
+  TypeScript code review and auto-fix. Modes: scan, fix, auto. Scopes: full codebase,
+  uncommitted, branch diff, last N commits. Trigger on: review, audit, check, lint,
+  find issues, find bugs, fix issues, fix code smells, auto-fix, review and fix,
+  clean up code, tech debt, code health, security audit, modernize, review my changes,
+  review my PR, review last commit. Architecture review: --arch, --full, review architecture,
+  find refactoring opportunities, full audit. Pure TypeScript 5.9+ only.
 ---
 
 # TypeScript Code Reviewer
@@ -33,6 +27,22 @@ This skill operates in three modes. Detect the mode from the user's request:
 **`fix`** — Read `code-smells.md` and apply fixes with verification.
 **`auto`** — Run scan, then fix, then re-scan to verify. Delete report if clean.
 
+## Domain Set
+
+Controls which review domains are active. Detected from flags first, then natural-language phrases.
+
+| Flag / phrase | Active domains |
+|---|---|
+| (none / default) | Type Safety, Security, Async Patterns, Modernization, Code Quality, Config, Boundary Validation, Error Handling, Dependency Hygiene |
+| `--arch` / "review architecture" / "find refactoring opportunities" / "deepening review" | Architecture only |
+| `--full` / "full audit" / "full review" / "review everything" | All 10 domains (default 9 + Architecture) |
+
+Parse order: check for explicit `--arch` / `--full` / `--no-arch` flags in the user's message first.
+Fall back to phrase detection. If no flag or phrase matches → default domain set (no architecture).
+
+Architecture domain is **off** in default scans. It loads `references/architecture.md` and adds
+an `## Architecture Opportunities` section to `code-smells.md` only when active.
+
 ## Report File Location
 
 - Always write to `code-smells.md` in the project root (not in `.claude/`)
@@ -94,30 +104,34 @@ If not specified, default to **full codebase**.
 
 ### Git commands per scope
 
-**`full`** — all `.ts` files:
+**`full`** — all TypeScript files:
 ```bash
-npx glob '**/*.ts' --ignore '**/node_modules/**'
-# or: git ls-files '*.ts'
+npx glob '**/*.{ts,mts,cts}' --ignore '**/node_modules/**'
+# or: git ls-files '*.ts' '*.mts' '*.cts'
 ```
 
 **`uncommitted`** — staged + unstaged + untracked:
 ```bash
-git diff --name-only HEAD -- '*.ts'
-git ls-files --others --exclude-standard -- '*.ts'
+git diff --name-only HEAD -- '*.ts' '*.mts' '*.cts'
+git ls-files --others --exclude-standard -- '*.ts' '*.mts' '*.cts'
 ```
 
 **`branch`** — current branch vs base:
 ```bash
 BASE=$(git rev-parse --verify main 2>/dev/null && echo main || echo master)
-git diff --name-only "$BASE"...HEAD -- '*.ts'
-git diff --name-only HEAD -- '*.ts'
+git diff --name-only "$BASE"...HEAD -- '*.ts' '*.mts' '*.cts'
+git diff --name-only HEAD -- '*.ts' '*.mts' '*.cts'
 ```
 
 **`commits:N`** — last N commits:
 ```bash
-git diff --name-only HEAD~N..HEAD -- '*.ts'
+git diff --name-only HEAD~N..HEAD -- '*.ts' '*.mts' '*.cts'
 ```
 
+**File type policy:** `.mts`/`.cts` are reviewed like `.ts`. `.d.ts` files are reviewed
+only by the Type Safety and Config domains (declarations have no runtime behavior).
+`.tsx` is out of scope — pure TypeScript only, no frameworks.
+
 ### Context files (scoped reviews)
 
 Analysis scope = diff file list. Reading scope = wider. Always include as read-only:
@@ -133,7 +147,7 @@ Context files are NOT analyzed for issues.
 
 Collect changed hunks:
 ```bash
-git diff -U0 [appropriate range] -- '*.ts' | grep '^@@'
+git diff -U0 [appropriate range] -- '*.ts' '*.mts' '*.cts' | grep '^@@'
 ```
 
 - Issue on **new/modified line**: boost severity +1 (Low→Medium, Medium→High, High→Highest)
@@ -145,21 +159,31 @@ git diff -U0 [appropriate range] -- '*.ts' | grep '^@@'
 
 ## Phase 1 — Discovery (scan mode)
 
-1. **Detect scope mode** from user's request. Build file list.
+1. **Detect domain set** from flags and phrases (see Domain Set section above).
+
+2. **Detect scope mode** from user's request. Build file list.
    If scoped mode yields 0 files, ask whether to fall back to full.
 
-2. **Map project tree** — full structure regardless of scope.
+3. **Map project tree** — full structure regardless of scope.
 
-3. **Read `tsconfig.json`**. Load `references/tsconfig.md` and audit config flags.
+4. **Read `tsconfig.json`**. Load `references/tsconfig.md` and audit config flags.
    In scoped modes: only flag config if `tsconfig.json` is in diff or if full review.
+   Monorepos: detect workspaces (`workspaces` in package.json, `pnpm-workspace.yaml`) and
+   multiple tsconfigs (`tsconfig.build.json`, per-package configs, `references`). Audit the
+   config that actually governs the files in scope; note which config applies in the summary.
 
-4. **Check for linter configs** — `eslint.config.*`, `.eslintrc.*`, `biome.json`, `deno.json`.
+5. **Check for linter configs** — `eslint.config.*`, `.eslintrc.*`, `biome.json`, `deno.json`.
 
-5. **Read `package.json`** — TS version, dependencies, module type.
+6. **Read `package.json`** — TS version, dependencies, module type.
 
-6. **Identify entry points** — `index.ts`, `main.ts`, exports in `package.json`.
+7. **Identify entry points** — `index.ts`, `main.ts`, exports in `package.json`.
 
-7. **Collect context files** (scoped modes only).
+8. **Collect context files** (scoped modes only).
+
+9. **Architecture discovery** (only if Architecture is in active domain set):
+   - Map module relationships: note circular imports, deep relative imports, barrel-file cycles, feature slices, public entry points.
+   - Check if `docs/adr/` exists — if so, scan it for architectural decisions before proposing changes. Skip silently if absent.
+   - Do NOT require `CONTEXT.md` or any domain-doc files.
 
 Discovery summary:
 ```
@@ -183,7 +207,11 @@ Files in scope: <N> .ts files (+ <M> context files)
 npx tsc --noEmit 2>&1 | head -200
 ```
 
-Compiler errors -> **Highest**. Warnings -> **High**.
+All output lines are errors (tsc emits no warnings). Triage each error:
+- Indicates a runtime hazard (null/undefined access, wrong argument shape,
+  missing property) -> **Highest**
+- Hygiene errors (unused locals, unreachable code, implicit any on internals) -> **High**
+
 In scoped modes: run on full project, report only errors in scoped files.
 
 ### 2b. Linter
@@ -191,7 +219,11 @@ In scoped modes: run on full project, report only errors in scoped files.
 ESLint: `npx eslint [files] --format json 2>/dev/null | head -500`
 Biome: `npx biome check [files] --reporter json 2>/dev/null | head -500`
 
-Map: `error` -> **High**, `warning` -> **Medium**, `info` -> **Low**.
+Map linter severities conservatively — projects configure stylistic rules as `error`:
+- Rule matches a checklist item in a reference file -> use the checklist severity
+- Correctness-class rule (`no-floating-promises`, `no-misused-promises`,
+  `no-unsafe-*`) -> **High**
+- Anything else: `error` -> **Medium**, `warning` -> **Low**, `info` -> **Low**
 
 ### 2c. LSP diagnostics (if available)
 
@@ -203,14 +235,20 @@ Query TypeScript LSP via MCP if accessible. Merge with compiler output, deduplic
 
 Read the corresponding reference file before each analysis pass.
 
+Run only the agents whose domain is in the active domain set (see Domain Set section).
+
 | Agent | Reference file | Focus |
 |---|---|---|
 | Type Safety | `references/type-safety.md` | `any`, casts, `!`, exhaustiveness, generics |
 | Security | `references/security.md` | Injection, prototype pollution, ReDoS, path traversal |
 | Async Patterns | `references/async-patterns.md` | Floating promises, race conditions, error propagation |
 | Modernization | `references/modernization.md` | Outdated patterns vs TS 5.9+ idioms |
-| Code Quality | `references/code-quality.md` | Complexity, duplication, naming, dead code |
+| Code Quality | `references/code-quality.md` | Complexity, duplication, naming, dead code, testability |
 | Config | `references/tsconfig.md` | tsconfig.json flags and module setup |
+| Boundary Validation | `references/boundary-validation.md` | Runtime validation at system edges, DTO/domain separation |
+| Error Handling | `references/error-handling.md` | Silent failures, throw hygiene, failure design |
+| Dependency Hygiene | `references/dependency-hygiene.md` | package.json, versions, lockfiles, supply chain |
+| Architecture | `references/architecture.md` | Shallow modules, scattered concepts, coupling, dependency seams, layering |
 
 ### Sub-agent template (Claude Code)
 
@@ -233,7 +271,7 @@ Output JSONL, one object per line:
   "fix": "Concrete recommendation with code example",
   "auto_fixable": true|false,
   "in_diff": true|false,
-  "reference": "URL or docs ref"
+  "reference": "optional — omit unless allowed by the Evidence Protocol"
 }
 ```
 
@@ -254,8 +292,11 @@ Go through each domain one at a time. Same JSON structure.
 
 1. Apply severity boost (scoped modes only): `in_diff: true` -> boost +1 level.
 2. Deduplicate: same file + line + issue -> keep one.
-3. Merge overlapping: keep higher severity, note overlap.
+3. Merge overlapping: keep higher severity, note overlap. If two domains flag the same
+   file + line, merge into one entry attributing both categories — never emit twice.
 4. Consolidate patterns: 3+ identical issues -> one "Recurring Pattern" entry.
+5. Noise budget: if a single domain produces > 25 Medium/Low findings, keep its top 15
+   by severity and impact, consolidate the rest into Recurring Pattern entries with counts.
 
 ### Report structure
 
@@ -269,7 +310,7 @@ Write to `code-smells.md`:
 **TypeScript version:** <version>
 **Scope:** Full / Uncommitted / Branch `x` vs `y` / Last N commits
 **Files analyzed:** N (+ M context)
-**Total issues:** N (X critical, Y high, Z medium, W low)
+**Total issues:** N (X highest, Y high, Z medium, W low)
 **Severity-boosted:** N (scoped modes only)
 
 ## Summary
@@ -297,6 +338,23 @@ Write to `code-smells.md`:
 ## Recurring Patterns
 ## Config Issues
 ## Pre-existing Issues (scoped modes only)
+
+## Architecture Opportunities
+(only when Architecture is in active domain set AND at least one candidate found — omit entirely otherwise)
+
+### TITLE — Severity
+
+- **Files:** relative/path/a.ts, relative/path/b.ts
+- **Problem:** why this causes friction now
+- **Proposed deepening:** what would change
+- **Interface shape:** rough sketch of new interface
+- **Dependency category:** in-process | local-substitutable | remote-owned | true-external
+- **Test strategy:** how tests improve
+- **Benefits:** locality, leverage, test impact
+- **Trade-offs:** what gets harder
+- **Fixability:** auto | needs-confirm | report-only
+
+---
 ````
 
 ### Sorting
@@ -337,13 +395,43 @@ Key principles:
 
 In scoped modes: these are base severities before diff-aware boost.
 
+Architecture findings use the same severity scale with domain-specific criteria.
+See `references/architecture.md` → Severity Mapping for Architecture.
+
+---
+
+## Evidence Protocol
+
+Every finding must survive verification before it enters the report:
+
+1. **Re-read before reporting.** After drafting a finding, re-read the exact lines in the
+   current file state. The `snippet` must appear verbatim at the stated `line` (±2 lines).
+   If it doesn't, re-locate or drop the finding.
+2. **Check the surrounding context.** If a guard, validation, type narrowing, or comment
+   within the enclosing function/module already handles the case, the finding is a false
+   positive — drop it, don't downgrade it.
+3. **Confidence gate.** Report only findings you can defend with the code in front of you.
+   If a finding depends on runtime behavior you cannot see (external input actually reaching
+   a sink, concurrent callers actually existing), either verify the data flow by reading the
+   callers, or mark the finding's problem statement with "if <condition>" and cap severity
+   at Medium.
+4. **References must be real.** The `reference` field is optional. Only cite
+   typescriptlang.org, developer.mozilla.org, nodejs.org, or a file path inside this skill.
+   Never construct URLs from memory for anything else — omit the field instead.
+5. **Convention override.** If a flagged non-High pattern appears consistently 5+ times
+   across the codebase, treat it as an intentional convention: downgrade one severity level
+   and report it once as a Recurring Pattern, not per occurrence.
+6. **Version gate.** Every finding that recommends newer syntax or APIs must state the
+   minimum TS/runtime version required, verified against the project's actual TS version,
+   `target`/`lib`, and runtime. Never recommend a feature the project cannot use.
+
 ---
 
 ## Important Guidelines
 
 - **No framework checks.** Pure TypeScript only.
-- **No false positives from intentional patterns.** `// @ts-expect-error` with explanation = Low.
-  `// @ts-ignore` (legacy) = Medium. Without explanation = Medium.
+- **No false positives from intentional patterns.** Suppression-directive severities are
+  owned by `references/type-safety.md` (Suppression Directives) — follow it, don't improvise.
 - **Respect project conventions.** Don't flag consistent patterns unless harmful.
 - **Be concrete.** Every issue needs a snippet and a fix recommendation.
   "Consider refactoring" is not a valid fix.

package/ts-reviewer/references/architecture.md

@@ -0,0 +1,158 @@
+# Architecture Review Checklist
+
+Loaded only when architecture review is active (`--arch` or `--full` flag).
+
+## Glossary
+
+Use these terms in all architecture findings. Don't substitute "component", "service", "API", "boundary".
+
+- **Module** — anything with an interface and an implementation: function, class, package, feature slice.
+- **Interface** — everything a caller must know: types, invariants, error modes, ordering, config. Not just the TypeScript `interface` keyword.
+- **Implementation** — the code inside the module.
+- **Depth** — leverage at the interface. Deep = large behaviour behind small interface. Shallow = interface nearly as complex as implementation.
+- **Seam** — where the interface lives; a place behaviour can be altered without editing in place. Prefer over "boundary".
+- **Adapter** — a concrete thing satisfying an interface at a seam.
+- **Leverage** — what callers get from depth: more capability per unit of interface they must learn.
+- **Locality** — what maintainers get from depth: change, bugs, and knowledge concentrated in one place.
+
+## Principles
+
+- **Depth is a property of the interface, not the implementation.** A deep module can be internally complex — what matters is how small its interface is relative to what it hides.
+- **Deletion test.** Imagine deleting the module. If complexity vanishes → it was a pass-through. If complexity reappears across callers → it was earning its keep.
+- **The interface is the test surface.** Callers and tests cross the same seam. If tests must reach past the interface into internals, the module is the wrong shape.
+- **One adapter = hypothetical seam. Two adapters = real seam.** Don't introduce a port unless at least two adapters are justified (production + test at minimum). Single-adapter seams are just indirection.
+
+## Smell Checklist
+
+### Shallow Modules
+
+- Understanding one concept requires bouncing across many tiny modules. Severity: **Medium**.
+- Module interface is nearly as complex as its implementation (shallow). Severity: **Medium**.
+- Pass-through wrapper / manager / helper / service that adds no hidden complexity. Severity: **Medium**. Apply deletion test.
+- Pure functions extracted only for testability, but real bugs hide in orchestration — no locality. Severity: **Medium**.
+
+### Coupling and Boundaries
+
+- Tight coupling leaks across module interfaces (callers must know implementation details). Severity: **High**.
+- Tests must reach into module internals or mock too many neighbors to test one thing. Severity: **High**.
+- Public API exports implementation details, config, ordering constraints, or internal error modes that callers should not need to know. Severity: **Medium**.
+
+### Import and Module Structure
+
+*Note: circular imports and deep relative imports are also flagged by the Code Quality domain in all scan modes. Architecture domain provides deeper refactoring guidance when Code Quality flags them.*
+
+- Barrel-file cycles or circular import chains that can't be resolved by reordering. Severity: **High**.
+- Deep relative imports (`../../../`) indicating modules not co-located with what they depend on. Severity: **Low**. Suggest path aliases or co-location.
+
+### Locality
+
+- Shared utility module mixes unrelated domain concepts (a grab-bag util). Severity: **Medium**.
+- Feature logic split by technical layer (e.g. controller / service / repo per feature) in a way that destroys locality — change to one feature requires touching 4+ files. Severity: **Medium**.
+
+### Under-Engineering
+
+Depth cuts both ways — flag missing abstraction where it already hurts:
+
+- Identical business rule (same constants/branching) implemented in 2+ modules.
+  Severity: **Medium**. Under-abstraction; deepen one module to own the rule.
+- One module accreting unrelated concerns (imports from many unrelated domains, exports
+  serving disjoint caller groups). Severity: **Medium**. Split along caller groups.
+- Event/string-keyed indirection between two modules that only ever talk to each other —
+  a direct typed call would be simpler and checkable. Severity: **Low**.
+
+## Dependency Direction and Layering
+
+Direction matters more than layer count. Detect and flag:
+
+- Domain/computation modules importing IO directly (`node:fs`, `node:http`, DB clients,
+  `fetch`) when the dependency classification says the IO belongs behind a seam.
+  Severity: **Medium**. The domain owns logic; transport/storage is injected or
+  isolated at the edge.
+- Shared/leaf modules (`utils/`, `types/`, `core/`) importing from feature modules —
+  inverted direction; the "shared" code now depends on a specific feature.
+  Severity: **High** — this is how import cycles start.
+- Wire/DTO types from an external API imported deep into domain modules rather than
+  mapped to domain types at the boundary. Severity: **Medium**.
+  Cross-reference: `references/boundary-validation.md`.
+
+## Detection Heuristics
+
+Run these — don't guess from file names:
+
+- Grep feature-module imports inside `shared|common|core|utils` directories
+  (inverted dependency direction).
+- For each module, list its importers. A module whose every export has exactly one
+  importer is a pass-through candidate — apply the deletion test.
+- An interface/type re-exported through 3+ files unchanged marks a pass-through chain.
+- A utility file imported by the majority of modules is a grab-bag candidate — check
+  whether its exports share a domain concept.
+- Change-set locality: in `git log --name-only`, do commits touching one feature
+  consistently touch 4+ directories? That feature's logic is scattered.
+
+## Dependency Classification
+
+When proposing a deepening fix, classify the dependency to determine test strategy:
+
+**1. In-process** — pure computation or in-memory state, no I/O.
+- Strategy: merge modules, test through the deepened interface directly. No adapter needed.
+
+**2. Local-substitutable** — DB, filesystem, etc. with usable local stand-ins (PGLite, in-memory filesystem).
+- Strategy: deepen using the stand-in in tests. The seam is internal; no port at the external interface.
+
+**3. Remote but owned** — internal services across a network boundary.
+- Strategy: define a port (TypeScript interface) at the seam. Production adapter + in-memory adapter for tests.
+- The deep module owns the logic; only the transport is injected.
+
+**4. True external** — third-party services (Stripe, Twilio, etc.) you don't control.
+- Strategy: inject a port; provide a mock adapter for tests.
+
+**Rule:** don't introduce a port unless at least two adapters are justified. A single-adapter seam is indirection without benefit.
+
+## Candidate Report Format
+
+Each architecture finding uses this format in the `## Architecture Opportunities` section:
+
+```md
+### TITLE — Severity
+
+- **Files:** relative/path/a.ts, relative/path/b.ts
+- **Problem:** why this causes friction now (not just a pattern name)
+- **Proposed deepening:** plain-English description of what would change
+- **Interface shape:** rough sketch of the new interface (types, methods, key invariants)
+- **Dependency category:** in-process | local-substitutable | remote-owned | true-external
+- **Test strategy:** how tests would improve (what tests survive, what gets deleted, what's new)
+- **Benefits:** locality gained, leverage gained, test impact
+- **Trade-offs:** what gets harder, what is genuinely uncertain
+- **Fixability:** auto | needs-confirm | report-only
+```
+
+## Severity Mapping for Architecture
+
+| Level | Architecture criteria |
+|---|---|
+| **Highest** | Architecture issue directly causing a security vulnerability, data loss, or production correctness bug |
+| **High** | Circular imports or cross-module coupling that blocks reliable tests or causes recurring defects |
+| **Medium** | Shallow modules, scattered domain logic, pass-through abstractions, hard-to-test orchestration |
+| **Low** | Small interface leaks, minor naming drift between module interface and what it exposes |
+
+## Fixability Mapping
+
+| Fixability | Meaning | Fix mode behavior |
+|---|---|---|
+| `auto` | Local change: import path cleanup, narrow circular-import break, local module merge with co-located tests | Applied in normal fix loop |
+| `needs-confirm` | Interface change, dependency inversion, test replacement, feature-slice reorganization | Shown to user, NOT applied automatically |
+| `report-only` | Broad migration, ambiguous domain model, change requiring product/domain decision | Never applied, left as documentation |
+
+## Naming Guidance
+
+Use names that already exist in the codebase (function names, type names, file names, package names). Don't invent domain terms. If a deepened module needs a name, prefer a name already used in adjacent code.
+
+## Architecture Fix Rules
+
+When applying `auto` fixability architecture findings:
+
+- Write new tests at the deepened module's interface. Old unit tests on shallow modules that are now merged become redundant — delete them.
+- Tests assert observable behavior through the interface, not internal state.
+- Don't expose internal seams through the interface just because tests need them.
+- Tests that have to change when the implementation changes are testing past the interface.
+- For large architecture changes classified `needs-confirm`, show a diff/migration plan and wait for explicit go-ahead before touching code.

package/ts-reviewer/references/async-patterns.md

@@ -13,19 +13,59 @@
 
 ## Error Handling
 
-- `catch(e)` without typing as `unknown` (requires `useUnknownInCatchVariables`).
-  Severity: **Medium**.
-- Empty catch blocks: `catch(e) {}`. Severity: **High** (unless commented).
-- `catch` that only logs without rethrowing. Severity: **Medium**.
-- `Promise.allSettled()` ignoring `'rejected'` entries. Severity: **Medium**.
+All catch/throw/failure-design checks live in `references/error-handling.md` — do not
+duplicate them here. This domain only flags errors *lost to the async machinery*
+(floating promises above, allSettled below).
 
 ## Race Conditions
 
 - Multiple async ops modifying shared state without coordination.
-  Severity: **High**.
+  Severity: **High**. Fix: serialize via a promise chain / async mutex, or make the
+  operations idempotent so ordering doesn't matter.
 - `Promise.race()` where losing promise's side effects still execute.
   Severity: **Medium**.
 - Read-modify-write with `await` in the middle. Severity: **High** in concurrent contexts.
+- Overlapping requests writing to the same variable/state where the earlier response
+  can arrive last (last-write-wins clobbering). Severity: **High** in concurrent contexts.
+  Fix: request-sequence token check before applying the result, or abort the previous
+  request via AbortController.
+- Lazily-initialized async singleton where concurrent first callers each run the
+  initializer. Severity: **Medium**. Fix: memoize the *promise*, not the resolved value:
+  `init ??= doInit(); return init;`
+
+## Timeouts
+
+- `await` on network/IO (fetch, DB call, queue op) with no timeout and no AbortSignal.
+  Severity: **Medium** (internal tools), **High** (request-handling / server paths —
+  a hung dependency hangs every caller).
+  Fix: `fetch(url, { signal: AbortSignal.timeout(5000) })`, or `Promise.race` with a
+  timer for APIs without signal support (clear the timer in `finally`).
+- Timeout implemented with `Promise.race` but the losing operation keeps running and
+  holds resources (sockets, locks). Severity: **Medium**. Fix: abort the operation,
+  don't just abandon the promise.
+
+## Retries
+
+- Retry loop without a max-attempt cap. Severity: **High** (infinite loop under
+  persistent failure).
+- Retries without backoff (tight loop hammering a failing dependency). Severity: **Medium**.
+  Fix: exponential backoff with jitter.
+- Retrying a non-idempotent operation (payment, email send, resource creation).
+  Severity: **Highest** — duplicate side effects. Fix: idempotency key or check-then-act
+  on the server side; otherwise don't retry.
+
+## Concurrency Limits
+
+- `Promise.all(items.map(asyncFn))` where `items` is unbounded (user data, file lists,
+  API pages) and `asyncFn` does network/disk work. Severity: **Medium**.
+  Fix: process in chunks or use a concurrency limiter. Do NOT recommend converting
+  sequential awaits to unbounded `Promise.all` — recommend it only with an explicit
+  concurrency cap when the collection can exceed ~10 items.
+- `Promise.all` where one rejection should not discard sibling results, or where
+  siblings' later rejections become unhandled. Severity: **Medium**.
+  Fix: `Promise.allSettled` + explicit handling of `rejected` entries.
+- `Promise.allSettled()` results used without checking `status === 'rejected'` entries.
+  Severity: **Medium**.
 
 ## Cancellation
 
@@ -47,8 +87,10 @@
 - `async function() { return await bar(); }` — unnecessary await (except in try/catch).
   Severity: **Low**.
 - Mixing `await` and `.then()` chains in same function. Severity: **Low**.
-- Sequential `await` in loop when iterations are independent.
-  Severity: **Medium**. Fix: `Promise.all(items.map(...))` if order doesn't matter.
+- Sequential `await` in loop when iterations are independent AND the collection is small
+  and bounded (< ~10 known items). Severity: **Medium**. Fix: `Promise.all(items.map(...))`.
+  If the collection is unbounded or does network/disk work, require a concurrency cap
+  instead — see Concurrency Limits.
 
 ## Async Iterators