ts-reviewer 3.6.1 → 3.7.1

package/README.md

@@ -4,6 +4,8 @@ An AI skill for deep code review and auto-fix of pure TypeScript codebases. Find
 
 Built for one fixed stack — **TypeScript 5.9.x, ES2024, Node 24** — without any framework-specific checks (no React, Vue, Angular, etc.). Anything below the stack is a finding, anything above it is never recommended.
 
+Supported AI agents: **Claude Code** and **Codex** only. Other agents are not supported by the installer or tested with the skill.
+
 ## What It Does
 
 Four modes, one skill:
@@ -17,6 +19,10 @@ Four modes, one skill:
 
 ## What's New
 
+**3.7.1 — 1 message on Codex.** Codex has no question menu outside Plan mode, so the start questions come as 1 chat message with a 1-line answer instead of 4 round trips.
+
+**3.7.0 — 3 questions before a scan.** A scan you start asks, in this order: which domains (2 pages, nothing pre-ticked — page 1 the 4 cheap groups, page 2 Security and Architecture), whether to run the skill lint, and which model runs the passes (every run, your last answer first). A flag answers its own question, a resumed scan asks nothing, and `--defaults` asks nothing at all — for an agent that starts the scan for you. The default set drops Security: 8 domains. `--pick` is gone: the menu now shows without it.
+
 **3.6.1 — the agent menu waits.** On Windows, after you picked the install scope, the agent menu took no keys: it confirmed both agents unasked or quit without installing. It now waits for your choice.
 
 **3.6.0 — install once for every project.** `npx ts-reviewer@latest install` asks whether to install globally or into the project, and `update` brings every install to the latest version without questions. Antigravity is no longer a target.
@@ -31,12 +37,12 @@ Four modes, one skill:
 
 Both are optional: a project with no `@hotpath` markers, no tests, and no history gets today's behaviour plus 1 verdict line per finding.
 
-The review covers nine domains by default, each with its own detailed checklist. Add `--arch` or `--full` to include architecture analysis:
+The review has ten domains, each with its own detailed checklist. A scan asks which to run; the default set, for `--defaults` or no answer, is the eight below without Security and Architecture:
 
 | Domain | Examples | Default |
 |---|---|---|
 | **Type Safety** | `any` abuse, unsafe casts, non-null assertions, `unknown` discipline, missing exhaustive checks | ✓ |
-| **Security** | Injection, SSRF, prototype pollution, ReDoS, path traversal, hardcoded secrets | ✓ |
+| **Security** | Injection, SSRF, prototype pollution, ReDoS, path traversal, hardcoded secrets | menu page 2 / `--full` |
 | **Async Patterns** | Floating promises, race conditions, missing timeouts, unbounded concurrency, `forEach(async...)` | ✓ |
 | **Modernization** | Numeric enums, `\|\|` vs `??`, mutating array methods, `satisfies`, `using` keyword | ✓ |
 | **Code Quality** | Dead code, complexity, duplication, debug artifacts, import-time side effects, testability | ✓ |
@@ -44,10 +50,12 @@ The review covers nine domains by default, each with its own detailed checklist.
 | **Boundary Validation** | `as T` on `JSON.parse`/`fetch`/env, DTO vs domain model separation, contract drift | ✓ |
 | **Error Handling** | Silent failures, throw hygiene, `cause` chaining, failure design at API seams | ✓ |
 | **Dependency Hygiene** | Lockfiles, wildcard versions, `npm audit`, duplicate-purpose and trivial deps | ✓ |
-| **Architecture** | Shallow modules, scattered concepts, tight coupling, dependency direction, layering | `--arch` / `--full` |
+| **Architecture** | Shallow modules, scattered concepts, tight coupling, dependency direction, layering | menu page 2 / `--arch` / `--full` |
 
 ## Installation
 
+The installer supports 2 AI agents: Claude Code and Codex. Antigravity was dropped in 3.6.0.
+
 ### Install with npx
 
 ```bash
@@ -127,18 +135,33 @@ The main agent writes its decisions, not the report: `tools/pass-prompts.mjs` fi
 
 The passes run in groups: Type Safety with Boundary Validation, Async Patterns with Error Handling, Config with Dependency Hygiene, Modernization with Code Quality, and Security and Architecture alone.
 
+#### Start questions
+
+A scan or auto run you start asks 3 questions before it reads the project, in this order:
+
+1. **Domains** — a multi-select in 2 pages, with nothing ticked in advance:
+   - page 1: Type Safety + Boundary Validation, Async Patterns + Error Handling, Config + Dependency Hygiene, Modernization + Code Quality — a usual scan ticks all 4;
+   - page 2: Security, Architecture — the expensive ones.
+2. **Skill lint** — whether to download and run the pinned ESLint config. Asked only when a picked domain has lint-owned lines; Knip and dependency-cruiser are approved in the same question when Architecture is picked and missing locally.
+3. **Pass model** — the model and effort for the analysis passes, your last answer first.
+
+A resumed scan asks none of them: the queue holds the answers. Leaving a question unanswered takes the default, except the skill lint, which an unanswered approval declines.
+
+**On Codex** there is no question menu outside Plan mode, so the scan asks all of them in 1 chat message: the 6 groups as 1 numbered list, then the lint and the model. Answer in 1 line, e.g. `1-4,6; lint yes; sonnet high`. `codex exec` has nobody to answer: pass `--defaults`.
+
 #### Domain flags
 
-By default, only the nine core domains run. Use flags to control which domains are active:
+A flag answers its question, so the scan does not ask it:
 
-| Flag | What runs |
+| Flag | What it answers |
 |---|---|
-| *(none)* | Type Safety, Security, Async, Modernization, Code Quality, Config, Boundary Validation, Error Handling, Dependency Hygiene |
+| `--defaults` | All 3: the 8 default domains, the skill lint on, the model of the scout file (or the default sub-agent). For an agent that starts the scan for you; another flag next to it still wins for its own question |
+| `--domains <slugs>` | Only the named domains, by slug (`security`, `type-safety`, `boundary-validation`, ...) or by pass group (`type-safety+boundary-validation`). `--no-arch` still removes Architecture |
 | `--arch` | Architecture only (shallow modules, coupling, dependency direction, seams) |
 | `--full` | All ten domains |
-| `--no-arch` | The nine core domains — overrides `--arch`, `--full`, and any phrase that would enable architecture |
-| `--domains <slugs>` | Only the named domains, by slug (`security`, `type-safety`, `boundary-validation`, ...) or by pass group (`type-safety+boundary-validation`). `--no-arch` still removes Architecture |
-| `--pick` | Asks which pass groups to run, in a multi-select (a numbered list on Codex). No answer runs the default set |
+| `--no-arch` | Removes Architecture from the set the other flags give, or runs the default set alone |
+| `--lint` / `--no-lint` | Runs or skips the skill lint |
+| `--scout <model>` | The pass model, for 1 run |
 
 Examples:
 
@@ -338,7 +361,7 @@ The test catches a check line that lost its severity, a block the profile does n
 
 ### Scan mode
 
-1. **Discovery** — detects domain flags, maps the project, reads tsconfig.json, detects linter and test runner, asks the pass model once per project, and asks once before downloading the skill lint or a missing architecture tool.
+1. **Discovery** — detects domain flags, maps the project, reads tsconfig.json, detects linter and test runner, after the 3 start questions: domains, the skill lint and any missing architecture tool, and the pass model.
 2. **Diagnostics** — runs `tsc --noEmit`, the project linter, the skill lint, and LSP diagnostics (if available). The skill lint's findings become the pass `lint-skill`; compiler and linter output is cached under `code-smells/passes/` and reused on a resume of the same commit.
 3. **Architecture pre-pass** — when active, writes bounded Knip, graph, metric, co-change, rule, and Mermaid artifacts under `code-smells/`, with project coverage and bounded failure diagnostics.
 4. **Analysis** — specialized passes, 1 per group of domains, judge the candidates against the active checklists, skipping the lines the skill lint owns, running in waves of `--agents` at a time; each pass writes its own `code-smells/passes/<id>.jsonl`, and `passes/queue.md` marks which are done, so a stopped run resumes from the last checkpoint. Tool output is never a finding by itself.
@@ -375,7 +398,7 @@ Validate a report directly with `node ts-reviewer/tools/validate-report.mjs --re
 
 - **Claude Code users** — `CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS` in `settings.json` under `env` caps sub-agents for every session on the host. It is independent of `--agents`, which caps one review run and works in every supported agent.
 
-- **Pick the pass model once** — the first scan asks which model and effort the analysis passes use, and writes the answer to `.claude/agents/ts-reviewer-scout.md` (Claude Code: `model`, `effort`) or `.codex/agents/ts-reviewer-scout.toml` (Codex: `model`, `model_reasoning_effort`). A smaller model there, for example Sonnet at `high`, costs less, while the main agent keeps verifying every finding. Delete the file to be asked again, or pass `--scout <model>` for 1 run. Architecture always runs on the main agent's model.
+- **Pick the pass model** — every scan asks which model and effort the analysis passes use, offers your last answer first, and writes the answer to `.claude/agents/ts-reviewer-scout.md` (Claude Code: `model`, `effort`) or `.codex/agents/ts-reviewer-scout.toml` (Codex: `model`, `model_reasoning_effort`). A smaller model there, for example Sonnet at `high`, costs less, while the main agent keeps verifying every finding. Pass `--scout <model>` to skip the question for 1 run. Architecture always runs on the main agent's model.
 
 - **Commit before running fix** — so you can `git diff` to review changes and `git checkout -- .` to revert if needed.
 

package/assets/skills/ts-reviewer/SKILL.md

@@ -7,7 +7,7 @@ description: >
   fix issues, fix the report, 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. Domain pick: --domains, --pick, pick domains,
+  find refactoring opportunities, full audit. Domain pick: --domains, --defaults, pick domains,
   choose domains. Pure TypeScript 5.9.x, ES2024, Node 24 only.
 ---
 
@@ -64,7 +64,7 @@ forbidden_behaviors:
 - do not emit the same file and line twice
 - do not boost severity in `full` scope mode: all code is treated alike
 - do not flag a config issue in a scoped mode unless `tsconfig.json` is in the diff
-- do not download and execute a missing analysis tool before the operator approves it once at discovery
+- do not download and execute a missing analysis tool before the operator approves it in `start_questions`
 - do not run `npm install` or `npm uninstall` for analysis: use an approved pinned-major `npx -y` command, or record the pre-pass as skipped
 - do not rename a report section, field, severity, confidence, or domain: `report_format` and `domains` hold exact identifiers
 - do not start a wave before every pass of the previous wave is marked `done`, `pending`, or `failed` in the queue
@@ -91,23 +91,55 @@ run_modes:
 | `auto` | review and fix, auto-fix, scan and fix, clean up | scan, then investigate, then fix, then a re-scan |
 
 domain_sets:
-- read `--domains` and `--pick` first, then the explicit `--arch`, `--full`, and `--no-arch` flags, then the phrases below, then fall back to the default set
-- Architecture is off in a default scan, and loads `references/architecture.md` only when it is active
+- read `--domains` first, then the explicit `--arch`, `--full`, and `--no-arch` flags, then the phrases below, then ask the domain menu of `start_questions`
+- Architecture and Security are off in the default set: both are expensive, and Architecture loads `references/architecture.md` only when it is active
 - `--domains` takes slugs joined by `,`: a domain name in lowercase with `-` for each space, or a `pass_groups` group id for every domain of the group
 - stop and list the valid slugs when `--domains` names a slug that is neither
-- the `--pick` options are the rows of `pass_groups` in row order, each naming its domains, and the operator picks 1 or more
-- ask the pick as a multi-select in questions of <= 4 options, or as a numbered list read from a reply such as `1,3` on a host with no multi-select
-- a pick with no operator answer runs the default set, and the discovery summary says so
-- a module joins `--domains` and `--pick` through its rows in `domains` and `pass_groups`, with no edit to this block
+- a module joins `--domains` and the domain menu through its rows in `domains` and `pass_groups`, with no edit to this block
 
 | Flag or phrase | Active domains |
 |---|---|
-| none | the 9 default domains: Type Safety, Security, Async Patterns, Modernization, Code Quality, Config, Boundary Validation, Error Handling, Dependency Hygiene |
+| `--defaults`, or no answer to the domain menu | the 8 default domains: Type Safety, Boundary Validation, Async Patterns, Error Handling, Config, Dependency Hygiene, Modernization, Code Quality |
+| the domain menu | the domains of the picked groups |
 | `--arch`, review architecture, find refactoring opportunities, deepening review | Architecture only |
 | `--full`, full audit, full review, review everything | all 10 domains |
 | `--domains <slugs>` | the named domains, and every domain of a named group |
-| `--pick`, pick domains, choose domains | the domains of the picked groups |
-| `--no-arch` | the set the rows above give, without Architecture, and it wins over any flag or phrase above |
+| `--no-arch` | the set the rows above give, without Architecture, and the default set when no row above answers |
+
+start_questions:
+- ask the 3 questions below in their order in a `scan` or `auto` run, after the resume ask of step 6 and before discovery
+- skip a question its flag answers, and skip all 3 on a resume: the plan holds the answers
+- `--defaults` answers all 3: the default set, the skill lint run, and the model of the scout file or the default sub-agent
+- a flag next to `--defaults` wins for its own question
+- a question with no operator answer takes the `--defaults` answer, except the skill lint: an unanswered approval is a decline
+- the domain menu has 2 pages, each 1 multi-select question holding the `pass_groups` rows of its page in row order, each option naming its domains
+- tick no option in advance, and say in the page 1 question that a usual scan ticks every option of page 1
+- ask every pending start question in 1 message on a host with no question tool, such as Codex in default mode: 1 chat round trip per question ends the agent's turn 4 times
+- write that message in the shape below, with the `pass_groups` rows of page 1 and then page 2, and leave out a line whose question a flag answers
+- offer no ready-made answer such as "defaults" in that message: the operator ticks the groups, as on a menu
+```text
+Before the scan, answer in 1 line, e.g. `1-4; lint yes; sonnet high`.
+Domains (a usual scan picks 1-4; 5 and 6 are expensive):
+  1. Type Safety, Boundary Validation
+  2. Async Patterns, Error Handling
+  3. Config, Dependency Hygiene
+  4. Modernization, Code Quality
+  5. Security
+  6. Architecture
+Skill lint: download and run the pinned ESLint config? yes / no
+Pass model: <the scout file's model and effort> / the main agent's model / another model and effort
+```
+- read every answer from 1 reply such as `1-4,6; lint yes; sonnet high`, and ask again only the part the reply leaves unreadable
+- ask a page as a numbered list in the question text on a host whose question tool takes 1 choice per question
+- ask the domain menu again when the operator ticks no option on either page: an empty scan is never the intent
+- ask the skill lint only when an active domain owns a line carrying "lint-owned by", and approve Knip and dependency-cruiser in the same question when Architecture is active and missing locally
+- ask the pass model as `pass_agent` states
+
+| Question | Answered by |
+|---|---|
+| domains | `--domains`, `--arch`, `--full`, `--no-arch`, and the phrases of `domain_sets` |
+| skill lint | `--lint` runs it, `--no-lint` declines it |
+| pass model | `--scout <model>` |
 
 scope_modes:
 
@@ -135,11 +167,11 @@ domains:
 
 workflow:
 1. identify the run mode from `run_modes`
-2. identify the active domain set from `domain_sets`
+2. identify the active domain set from `domain_sets`, and leave a question it does not answer to `start_questions`
 3. identify the scope mode from `scope_modes`, and default to `full` when the request names none
 4. build the file list with the command in `scope_commands` for that scope mode
 5. ask whether to fall back to `full` when a scoped mode yields 0 files
-6. ask once whether to resume or restart when `code-smells/passes/queue.md` exists, and delete `code-smells/passes/` on restart
+6. ask once whether to resume or restart when `code-smells/passes/queue.md` exists, delete `code-smells/passes/` on restart, then ask `start_questions` unless resuming
 7. warn when the `HEAD` in the queue header differs from the current `HEAD` on a resume: the line re-read below catches a stale line
 8. map the project tree in full, whatever the scope mode
 9. read `tsconfig.json`, and when Config is active read `references/tsconfig.md` and audit the config flags
@@ -149,7 +181,7 @@ workflow:
 13. read `package.json` for the dependencies and the module type, and verify the TypeScript version, `engines.node`, and `@types/node` against `target_stack`
 14. identify declared entry points from `package.json#exports`, `main`, `bin`, and the `start`, `dev`, and `serve` scripts
 15. count the markers `hot_marker` in `references/stack-cost.md` defines across the files in scope, and name the count in the discovery summary
-16. ask once before a pinned-major `npx -y` run: the skill lint when it runs, Knip and dependency-cruiser when Architecture is active and missing locally
+16. run a pinned-major `npx -y` tool only when `start_questions` approved it: the skill lint, Knip, and dependency-cruiser
 17. collect the context files named in `scope:` when the scope mode is scoped
 18. identify feature slices and public entry points when Architecture is active, leaving graph discovery to its mechanical pre-pass
 19. collect machine-readable dependency rules and prose from ADR directories, `ARCHITECTURE.md`, README, and `CONTRIBUTING.md`
@@ -279,7 +311,7 @@ Hot paths: <N> marked / none: hot rests on loop bodies alone
 Files in scope: <N> .ts files (+ <M> context files)
 Excluded framework packages: <package names, or none>
 Agents per wave: <N>
-Domains: <the active domains> from the default set / a flag / --domains / the pick / an unanswered pick
+Domains: <the active domains> from the domain menu / a flag / --domains / --defaults / an unanswered menu / the resumed plan
 Main agent: <model>
 Pass agent: ts-reviewer-scout <model> <effort> / the default sub-agent; Architecture on the main agent
 Skill lint: <N> findings / declined / failed: <reason>
@@ -342,10 +374,11 @@ pass_queue:
 - the pass id is the group id of `pass_groups`, or `<group id>.<directory slug>` for a split pass
 - the pass order is the row order of `pass_groups`, after the row `lint-skill` of `skill_lint`
 - the plan names every pass with its domains and files, and `lint-skill` with its files and no prompt
+- the plan holds the start answers a resume reuses: `lint`, the domains of each pass, and the pass `model` and `effort`, or no `model` for the default sub-agent
 - `pass-prompts.mjs` fills `subagent_template` for each pass, and keeps the status, attempts, and findings of a pass the queue already holds: a resume writes the same plan
 ```json
 {
-  "head": "<sha>", "scope": "full", "agents": 3, "lint": true,
+  "head": "<sha>", "scope": "full", "agents": 3, "lint": true, "model": "sonnet", "effort": "medium",
   "passes": [
     { "id": "security.src-auth", "domains": ["Security"], "files": ["src/auth/a.ts"], "context": ["src/types.ts"] }
   ]
@@ -362,6 +395,8 @@ pass_queue:
 HEAD: <sha>
 Scope: <mode>
 Agents per wave: <N>
+Lint: yes / no
+Pass model: <model> <effort> / default sub-agent
 
 | Pass | Domains | Files | Status | Attempts | Findings |
 |---|---|---|---|---|---|
@@ -376,24 +411,24 @@ pass_groups:
 - a filtered group takes the scoped files that the `workflow:` command of any of its references lists
 - a filtered group takes every scoped file when the skill lint did not run and the project linter enables no `no-floating-promises`
 
-| Group | Domains | Files |
-|---|---|---|
-| `security` | Security | every scoped file |
-| `type-safety+boundary-validation` | Type Safety, Boundary Validation | every scoped file |
-| `async-patterns+error-handling` | Async Patterns, Error Handling | filtered |
-| `config+dependency-hygiene` | Config, Dependency Hygiene | no `.ts` file: the project files each reference reads |
-| `modernization+code-quality` | Modernization, Code Quality | every scoped file |
-| `architecture` | Architecture | the inputs `references/architecture.md` names |
+| Group | Domains | Files | Menu page |
+|---|---|---|---|
+| `security` | Security | every scoped file | 2 |
+| `type-safety+boundary-validation` | Type Safety, Boundary Validation | every scoped file | 1 |
+| `async-patterns+error-handling` | Async Patterns, Error Handling | filtered | 1 |
+| `config+dependency-hygiene` | Config, Dependency Hygiene | no `.ts` file: the project files each reference reads | 1 |
+| `modernization+code-quality` | Modernization, Code Quality | every scoped file | 1 |
+| `architecture` | Architecture | the inputs `references/architecture.md` names | 2 |
 
 pass_agent:
 - every group runs as the `ts-reviewer-scout` agent when the scout file exists, except `architecture`, which runs as the default sub-agent on the main agent's model
 - the scout file is `.claude/agents/ts-reviewer-scout.md` on Claude Code and `.codex/agents/ts-reviewer-scout.toml` on Codex, in the project root
-- ask once for the scout model and effort when the scout file is absent, and write the answer to it
+- ask the scout model and effort on every run, by `start_questions`, offering the model of the scout file first, and write the answer to the scout file
 - offer the models the host's agent call lists, or take the name the operator types when the host lists none
 - the answer "the main agent's model" writes `inherit` on Claude Code and leaves `model` out on Codex
 - pass the scout model, and the effort where the call takes one, in each agent call: a host can load a new agent file late
 - `--scout <model>` in the request wins for 1 run: every group but `architecture` runs as the default sub-agent on that model, no scout file is written, and no scout question is asked
-- a run with no operator answer writes no scout file and runs every group as the default sub-agent
+- a run with no operator answer, or with `--defaults`, keeps the scout file, and runs every group as the default sub-agent when there is none
 - a host with no scout file format runs every group as the default sub-agent
 - start a new agent for every pass, and never send a second pass to an agent that ran one: a reused agent reads each pass with every earlier one in its context
 - close each agent once its `done` line is written
@@ -408,6 +443,7 @@ skill_lint:
 - add `--in-diff` to the `lint-pass.mjs` command in a scoped mode: the skill lint reads the scoped files only
 - run it after step 21, and write its findings as the pass `lint-skill` with `tools/lint-pass.mjs`, which takes category, severity, and fix from the owning line
 - a declined or failed run marks the pass `lint-skill` failed, and every analysis pass keeps the lint-owned lines
+- `start_questions` asks the approval at the start of the run, and `--lint` or `--no-lint` answers it
 - an approval question with no operator answer is a decline
 - the skill lint replaces no project linter: step 21 runs the project config as before
 - leave the pass `lint-skill` out of the queue when no active domain owns a line carrying "lint-owned by": the lint has nothing to decide

package/assets/skills/ts-reviewer/tools/pass-prompts.mjs

@@ -64,7 +64,8 @@ export function passPrompts(plan, root) {
     writeFileSync(path.join(prompts, `${pass.id}.md`), head + filled + "\n");
   }
   writeFileSync(path.join(dir, "queue.md"), [
-    "# Pass queue", "", `HEAD: ${plan.head}`, `Scope: ${plan.scope}`, `Agents per wave: ${plan.agents}`, "",
+    "# Pass queue", "", `HEAD: ${plan.head}`, `Scope: ${plan.scope}`, `Agents per wave: ${plan.agents}`,
+    `Lint: ${plan.lint ? "yes" : "no"}`, `Pass model: ${[plan.model ?? "default sub-agent", plan.effort].filter(Boolean).join(" ")}`, "",
     "| Pass | Domains | Files | Status | Attempts | Findings |", "|---|---|---|---|---|---|", ...rows, "",
   ].join("\n"));
   return rows.length;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ts-reviewer",
-  "version": "3.6.1",
+  "version": "3.7.1",
   "description": "Install the TypeScript Code Reviewer skill for Claude Code or Codex, globally or per project",
   "license": "MIT",
   "type": "module",