ts-reviewer 2.1.0 → 3.0.1

package/README.md

@@ -10,7 +10,7 @@ Three modes, one skill:
 
 | Mode | What happens |
 |---|---|
-| **scan** | Analyzes the codebase and writes a prioritized report to `code-smells.md` |
+| **scan** | Analyzes the codebase and writes a prioritized report to `code-smells/report.md` |
 | **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 |
 
@@ -81,7 +81,8 @@ 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.
+Claude will analyze the project and write a report to `code-smells/report.md` in the project root.
+With Architecture active, the same directory also holds project discovery, Knip, graph, metric, co-change, rule, and Mermaid artifacts.
 
 #### Domain flags
 
@@ -114,7 +115,7 @@ After reviewing the scan report, ask Claude to fix the issues:
 Fix the issues from the report
 ```
 ```
-Apply fixes from code-smells.md
+Apply fixes from code-smells/report.md
 ```
 
 The fix workflow:
@@ -124,7 +125,7 @@ The fix workflow:
 4. Runs linter, fixes lint errors
 5. Runs full test suite, compares with baseline, fixes any regressions it caused
 6. Repeats verification up to 5 iterations
-7. Updates the report: if all fixed → deletes `code-smells.md`; if some remain → keeps it as an audit trail with BEFORE/AFTER diffs for every fix
+7. Updates the report: if all fixed → deletes `code-smells/report.md`; if some remain → keeps it as an audit trail with BEFORE/AFTER diffs for every fix
 
 **Important:** fix never commits or stages anything. You review the changes and decide what to keep.
 
@@ -227,7 +228,7 @@ A check line looks like this:
 The format is enforced, not merely recommended:
 
 ```bash
-npm test        # typecheck + 5 conformance tests
+npm test        # typecheck + conformance and tool tests
 ```
 
 The test catches a check line that lost its severity, a block the profile does not declare, blocks out of order, a banned vague word, and a line over the limit — each reported with its file and line number.
@@ -238,29 +239,33 @@ 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. If architecture is active, also maps module relationships and checks for `docs/adr/`.
+1. **Discovery** — detects domain flags, maps the project, reads tsconfig.json, detects linter and test runner, and asks once before downloading a missing architecture tool.
 2. **Diagnostics** — runs `tsc --noEmit`, linter, and LSP diagnostics (if available)
-3. **Analysis** — specialized passes for each active domain (sub-agents in Claude Code, sequential in Claude.ai), each with its own checklist. Every finding passes an Evidence Protocol: verified against the actual file content, confidence-gated, version-gated against the project's TS/runtime.
-4. **Report** — deduplicates, applies severity boost (scoped modes), consolidates recurring patterns, enforces a noise budget, writes `code-smells.md`. Architecture findings appear in a separate `## Architecture Opportunities` section at the end.
+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 judge the candidates against the active checklists; tool output is never a finding by itself.
+5. **Report** — deduplicates, applies severity boost (scoped modes), consolidates recurring patterns, enforces a noise budget, writes `code-smells/report.md`, and validates its contract before the scan succeeds. Architecture findings appear in a separate `## Architecture Opportunities` section at the end.
+
+Validate a report directly with `node ts-reviewer/tools/validate-report.mjs --repo . --report code-smells/report.md`. It checks headings, counts, finding anchors, architecture fields, and linked artifacts without adding a dependency. An **error** is a defect of the report that rewriting it fixes; a **warning** names an outcome of the mechanical pre-pass — a graph with no diagram, say — that the report cannot fix, and warnings do not fail the run.
 
 ### Fix mode
 
-1. Parses `code-smells.md` as the work plan
-2. Captures test baseline (runs tests before changes)
-3. Applies fixes bottom-to-top within each file (so line numbers don't shift)
-4. Writes regression tests for each testable fix
-5. Runs `tsc --noEmit` after each file
-6. Full verification loop: tsc + linter + test suite (max 5 iterations)
-7. Compares test results with baseline — only fixes regressions it caused
-8. Updates or deletes the report
+1. Validates `code-smells/report.md` and stops before changing code when the report is invalid
+2. Parses the report as the work plan
+3. Captures test baseline (runs tests before changes)
+4. Applies fixes bottom-to-top within each file (so line numbers don't shift)
+5. Writes regression tests for each testable fix
+6. Runs `tsc --noEmit` after each file
+7. Runs the full verification loop: tsc + linter + test suite (max 5 iterations)
+8. Compares test results with baseline — only fixes regressions it caused
+9. Updates or deletes the report, keeps the remaining `code-smells/` artifacts, and asks before removing them
 
 ## Tips
 
-- **Add `code-smells.md` to `.gitignore`** — it's a review artifact, not part of your source code.
+- **Add `code-smells/` to `.gitignore`** — it contains review artifacts, not source code.
 
 - **Commit before running fix** — so you can `git diff` to review changes and `git checkout -- .` to revert if needed.
 
-- **Edit the report before fix** — since fix uses `code-smells.md` as its work plan, you can delete issues you don't want fixed, change severities, or add notes before running fix.
+- **Edit the report before fix** — since fix uses `code-smells/report.md` as its work plan, you can delete issues you don't want fixed, change severities, or add notes before running fix.
 
 - **Scoped review for PRs** — `"review my branch against main"` is the most practical mode for day-to-day use. Full codebase audits are better suited for periodic health checks.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ts-reviewer",
-  "version": "2.1.0",
+  "version": "3.0.1",
   "description": "Install the TypeScript Code Reviewer skill for Claude Code, Codex, or Antigravity",
   "license": "MIT",
   "type": "module",
@@ -22,7 +22,7 @@
     "build": "tsc -p tsconfig.json",
     "prepublishOnly": "npm run build && npm test",
     "typecheck": "tsc -p tsconfig.json --noEmit",
-    "test": "npm run typecheck && node --test cnlp/skill-format.test.js",
+    "test": "npm run typecheck && node --test cnlp/skill-format.test.js tools.test.mjs",
     "dev": "npm run build && node --enable-source-maps dist/cli.js"
   },
   "keywords": [

package/ts-reviewer/SKILL.md

@@ -28,13 +28,15 @@ inputs:
 - the reference checklists under `references/`
 
 preconditions:
-- `code-smells.md` exists before fix mode runs: it is the work plan, and fix stops with an error when it is absent
+- `code-smells/report.md` exists before fix mode runs: it is the work plan, and fix stops with an error when it is absent
 
 scope:
 - `.ts`, `.mts`, and `.cts` files are reviewed alike
 - `.d.ts` files are reviewed by the Type Safety and Config domains only: a declaration has no runtime behavior
 - `.tsx` is out of scope
 - the analysis scope in a scoped mode is the diff file list, and the reading scope is wider
+- `--affected` widens Architecture evidence to modules reaching a changed module, and does not widen the analysis scope
+- anchor each finding to 1 file, and set `in_diff: true` only when that file is in the diff list
 - read as read-only context: `tsconfig.json`, the configs it extends, and `package.json`
 - read as read-only context: the files the scoped files import 1 level deep, and the shared types in `types.ts`, `*.d.ts`, `interfaces/`, `shared/`
 
@@ -57,11 +59,16 @@ 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 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
 
 outputs:
-- `code-smells.md` in the project root: the scan report, and the work plan fix reads
-- the `## Architecture Opportunities` section of that report, only when Architecture is active and at least 1 candidate is found
-- the audit trail in `code-smells.md` when any issue remains: BEFORE/AFTER for each fixed issue, a status tag for each failed, reverted, or skipped issue, the original entry for each untouched issue
+- `code-smells/report.md` in the project root: the scan report, and the work plan fix reads
+- `code-smells/knip.json`, `projects.json`, `co-change.md`, `cruise-summary.md`, `metrics.md`, and graph and diagram directories when Architecture is active
+- `code-smells/suggested.dependency-cruiser.cjs` when prose declares dependency rules and no machine-readable declaration owns them
+- the `## Architecture Opportunities` section of the report only when Architecture is active and at least 1 confirmed finding exists
+- the audit trail in `code-smells/report.md` when any issue remains: BEFORE/AFTER for each fixed issue, a status tag for each failed, reverted, or skipped issue, the original entry for each untouched issue
 - a regression test for each fix that is testable
 
 run_modes:
@@ -119,40 +126,52 @@ workflow:
 9. audit the config that governs the files in scope, and name that config in the summary
 10. read the linter config: `eslint.config.*`, `.eslintrc.*`, `biome.json`, `deno.json`
 11. read `package.json` for the dependencies and the module type, and verify the TypeScript version, `engines.node`, and `@types/node` against `target_stack`
-12. identify the entry points: `index.ts`, `main.ts`, the `exports` of `package.json`
-13. collect the context files named in `scope:` when the scope mode is scoped
-14. map the module relationships when Architecture is active: circular imports, deep relative imports, barrel-file cycles, feature slices, public entry points
-15. scan `docs/adr/`, `doc/adr/`, `adr/`, and `docs/decisions/` for architectural decisions before proposing a change, and skip it silently when none of them exists
-16. report the discovery summary in the shape of `discovery_summary`
+12. identify declared entry points from `package.json#exports`, `main`, `bin`, and the `start`, `dev`, and `serve` scripts
+13. when Architecture is active, inspect local Knip and dependency-cruiser binaries and ask once before running either missing tool through pinned-major `npx -y`
+14. collect the context files named in `scope:` when the scope mode is scoped
+15. identify feature slices and public entry points when Architecture is active, leaving graph discovery to its mechanical pre-pass
+16. collect machine-readable dependency rules and prose from ADR directories, `ARCHITECTURE.md`, README, and `CONTRIBUTING.md`
 17. run `npx tsc --noEmit 2>&1 | head -200` over the full project, and report only the errors in the scoped files
 18. run the linter: `npx eslint [files] --format json` or `npx biome check [files] --reporter json`
 19. query the TypeScript LSP over MCP when it is reachable, then merge and deduplicate against the compiler output
 20. triage every compiler and linter diagnostic through `severity_mapping`
 21. read the reference file named in `domains` before each analysis pass
-22. run only the passes whose domain is in the active domain set, as sub-agents shaped by `subagent_template` or one domain at a time
-23. give every agent all the scoped files when scoped files <= 20, and split by directory above that, with the shared types visible to every agent
-24. re-read the exact lines in the current file state before a finding enters the report
-25. read the callers to verify a data flow a finding rests on, or mark its problem statement with "if <condition>" and cap its severity at Medium
-26. downgrade a flagged non-High pattern that appears 5+ times across the codebase by 1 level, and report it once as a Recurring Pattern
-27. boost a finding carrying `in_diff: true` by 1 level in a scoped mode, and mark it `High [boosted, was Medium — new code]`
-28. deduplicate the findings on the same file, line, and issue, keeping 1
-29. merge the findings 2 domains raise on the same file and line into 1 entry attributing both categories, at the higher severity
-30. consolidate 3+ identical issues into 1 Recurring Pattern entry
-31. keep the top 15 by severity and impact when a single domain produces more than 25 Medium or Low findings, and consolidate the rest into Recurring Pattern entries with their counts
-32. write `code-smells.md` in the shape of `report_format`
-33. sort by severity group, then category, then file path, and place `in_diff: true` before pre-existing in a scoped mode
-34. show the top 10 and summarize the rest in a table when Medium and Low together hold more than 15 issues
-35. recommend that the operator adds `code-smells.md` to `.gitignore`: it is a review artifact
-36. read `references/fix-workflow.md` before fix mode executes: it holds the complete protocol
-37. detect the test runner and run the baseline tests
-38. fix the issues file by file, and run `tsc --noEmit` after each file
-39. run the linter and fix the lint errors it reports
-40. run the full test suite, compare it against the baseline, and fix the regressions
-41. repeat the compiler, linter, and test verification with verification iterations <= 5
-42. update `code-smells.md`: remove what is fixed, mark what failed
-43. show the scan summary in auto mode, and ask the operator whether to proceed with the fix
-44. re-scan after the fix in auto mode with full scan-fix cycles <= 2, and stop when issues persist after the second
-45. delete `code-smells.md` and report success when every issue is fixed
+22. run the mechanical pre-pass in `references/architecture.md` when Architecture is active, passing the approved tool decision and scoped base
+23. report the discovery summary in the shape of `discovery_summary`, including skipped and clean mechanical results
+24. run only the passes whose domain is in the active domain set, as sub-agents shaped by `subagent_template` or one domain at a time
+25. give every agent all the scoped files when scoped files <= 20, and split by directory above that, with the shared types visible to every agent
+26. re-read the exact lines in the current file state before a finding enters the report
+27. read the callers to verify a data flow a finding rests on, or mark its problem statement with "if <condition>" and cap its severity at Medium
+28. downgrade a flagged non-High pattern that appears 5+ times across the codebase by 1 level, and report it once as a Recurring Pattern
+29. boost a finding carrying `in_diff: true` by 1 level in a scoped mode, and mark it `High [boosted, was Medium — new code]`
+30. deduplicate the findings on the same file, line, and issue, keeping 1
+31. merge the findings 2 domains raise on the same file and line into 1 entry attributing both categories, at the higher severity
+32. consolidate 3+ identical issues into 1 Recurring Pattern entry
+33. keep the top 15 by severity and impact when a single domain produces more than 25 Medium or Low findings, and consolidate the rest into Recurring Pattern entries with their counts
+34. write `code-smells/report.md` in the shape of `report_format`
+35. validate the report against `report_format` after writing it, and treat a `warning:` line as a pre-pass outcome the report cannot correct
+```bash
+# SKILL is the directory this file was loaded from.
+SKILL=<the directory this file was loaded from>
+node "$SKILL/tools/validate-report.mjs" --repo . --report code-smells/report.md
+```
+36. correct every named error and retry with report validation iterations <= 2
+37. keep `code-smells/report.md` when the second validation fails, write `> unvalidated: <the first error>` under its title, and name the errors to the operator
+38. sort by severity group, then category, then file path, and place `in_diff: true` before pre-existing in a scoped mode
+39. show the top 10 and summarize the rest in a table when Medium and Low together hold more than 15 issues
+40. recommend that the operator adds `code-smells/` to `.gitignore`: it holds review artifacts
+41. read `references/fix-workflow.md` before fix mode executes: it holds the complete protocol
+42. detect the test runner and run the baseline tests
+43. fix the issues file by file, and run `tsc --noEmit` after each file
+44. run the linter and fix the lint errors it reports
+45. run the full test suite, compare it against the baseline, and fix the regressions
+46. repeat the compiler, linter, and test verification with verification iterations <= 5
+47. rerun the Architecture mechanical pre-pass on the fixed tree when Architecture is active
+48. update `code-smells/report.md`: remove what is fixed, mark what failed
+49. show the scan summary in auto mode, and ask the operator whether to proceed with the fix
+50. re-scan after the fix in auto mode with full scan-fix cycles <= 2, and stop when issues persist after the second
+51. delete `code-smells/report.md` and report success when every issue is fixed
+52. retain the remaining `code-smells/` artifacts, state what they contain, and remove them only after the operator confirms
 
 scope_commands:
 ```bash
@@ -161,6 +180,7 @@ npx glob '**/*.{ts,mts,cts}' --ignore '**/node_modules/**'
 # or: git ls-files '*.ts' '*.mts' '*.cts'
 
 # uncommitted — staged, unstaged, and untracked
+BASE=HEAD
 git diff --name-only HEAD -- '*.ts' '*.mts' '*.cts'
 git ls-files --others --exclude-standard -- '*.ts' '*.mts' '*.cts'
 
@@ -170,6 +190,7 @@ git diff --name-only "$BASE"...HEAD -- '*.ts' '*.mts' '*.cts'
 git diff --name-only HEAD -- '*.ts' '*.mts' '*.cts'
 
 # commits:N — the last N commits
+BASE=HEAD~N
 git diff --name-only HEAD~N..HEAD -- '*.ts' '*.mts' '*.cts'
 
 # the changed hunks, for the severity boost in a scoped mode
@@ -211,6 +232,16 @@ Strict mode: yes / partial / no
 Linter: eslint / biome / none
 Test runner: vitest / jest / mocha / node:test / none
 Files in scope: <N> .ts files (+ <M> context files)
+Architecture projects: <config and source roots, when active>
+Architecture tools: <local or approved npx versions, when active>
+Architecture coverage: <successful>/<selected>, when active
+Mechanical results: <module and edge counts, cycles, orphans, and co-change pairs; name clean zeros>
+Skipped pre-passes: <tool and reason, or none>
+Speculative candidates: <names only, or none>
+Declared dependency rules:
+| Rule | Source file:line | Directories |
+|---|---|---|
+| <rule, or none> | <path:line> | <mapping> |
 ```
 
 subagent_template:
@@ -239,6 +270,11 @@ Output JSONL, one object per line:
 ```
 
 report_format:
+- the `##` sections of the block below are the whole set, in that order, and a heading outside it is a renamed section
+- Discovery, Pre-existing Issues, Architecture Opportunities, Verification, and Generated artifacts are optional, and the other 5 are always present
+- `Total issues` counts the `###` findings, the summary-table rows, and the Architecture Opportunities entries, and the severity breakdown counts the same 3
+- a `Recurring Patterns` row is a pattern rather than an issue, and no row of that table is counted
+- a summary table is read by its `Category` and `Location` columns, and a pattern table by its `Pattern` and `Occurrences` columns
 ````markdown
 # TypeScript Code Review Report
 
@@ -247,6 +283,7 @@ report_format:
 **Stack:** TypeScript 5.9.x / ES2024 / Node 24 — matches / <deviation>
 **Scope:** Full / Uncommitted / Branch `x` vs `y` / Last N commits
 **Files analyzed:** N (+ M context)
+**Architecture coverage:** N/M (when active)
 **Total issues:** N (X highest, Y high, Z medium, W low)
 **Severity-boosted:** N (scoped modes only)
 
@@ -254,6 +291,10 @@ report_format:
 
 <2-3 sentences on codebase health and key patterns>
 
+## Discovery
+
+<optional; the `discovery_summary` block as it was reported>
+
 ## Highest + High Issues
 
 ### TITLE — Severity [boosted info if applicable]
@@ -261,7 +302,7 @@ report_format:
 **Category:** cat | **File:** `path` | **Line:** N | **Auto-fixable:** Yes/No | **New code:** Yes/No
 
 ```typescript
-// snippet
+// snippet: 3-7 lines copied from the file, within its own length of the stated line
 ```
 
 **Problem:** explanation
@@ -272,13 +313,36 @@ report_format:
 
 ## Medium Issues
 ## Low Issues
+
+| Issue | Category | Location | Fix |
+|---|---|---|---|
+| title | cat | `path:N` | recommendation |
+
 ## Recurring Patterns
+
+| Pattern | Occurrences | Severity treatment |
+|---|---|---|
+| name | N | what happened to its members |
+
 ## Config Issues
+
+<findings in the shape above, or prose naming where the config findings already sit>
+
 ## Pre-existing Issues (scoped modes only)
 
 ## Architecture Opportunities
 
-<1 entry per candidate, in the shape the `report_format` block of references/architecture.md gives>
+<optional; 1 entry per candidate, in the shape the `report_format` block of references/architecture.md gives>
+
+## Verification
+
+| Check | Result |
+|---|---|
+| the command that ran | what it reported |
+
+## Generated artifacts
+
+- `<file under code-smells/>` — what it holds
 
 ---
 ````

package/ts-reviewer/references/architecture.md

@@ -23,8 +23,8 @@ confidence_scale:
 
 | Confidence | Criteria |
 |---|---|
-| strong | the pain repeats, the owning module is named, and the fix path is safe |
-| worth-exploring | the problem is confirmed, and the interface or the migration needs its own design |
+| strong | the pain repeats and the owner is named, or a quoted dependency rule maps 1:1 onto directories |
+| worth-exploring | the problem is confirmed but the interface, migration, inferred rule, or layer mapping needs its own design |
 | speculative | a signal with no call, history, or test evidence behind it |
 
 read_first:
@@ -35,23 +35,57 @@ read_first:
 - dependency direction matters more than layer count: the domain owns the logic, and transport and storage are injected or isolated at the edge
 - 1 adapter is a hypothetical seam and 2 adapters are a real seam: do not introduce a port until at least 2 adapters are justified, production and test at the minimum
 - an architecture finding rests on evidence: named files and symbols, an import or call direction, a repeated change path in `git log`, a duplicated rule, or a test no correct seam can reach
-- state the observation apart from the inference drawn from it, and mark a candidate with no evidence behind it as speculative rather than reporting it as a defect
+- state the observation apart from the inference, and list an evidence-free candidate as speculative in `discovery_summary` rather than reporting it as a defect
 - a defect no test can reach through a correct seam is an architecture finding, and not a reason to write a test past the interface
 - before proposing a module, a port, or a container, check in order: drop the need, an existing module in the repository, the standard library, a platform feature, an installed dependency
 - design a hard-to-reverse proposal twice: compare 2 different interfaces on caller knowledge, seam placement, and migration cost, then recommend 1
 - a cycle is unclear ownership and not a bad graph: move the type or the rule to its owner, and `import type` or a lazy import hides the direction rather than fixing it
 - a path alias shortens an import path and is not an architecture boundary: ownership and a controlled export list are
+- under `--arch`, Knip narrows the observed interface and confirms orphans, while dead-code findings remain owned by Dependency Hygiene
+- apply an exception stated with a dependency rule before reporting it, and cap a path the declaration marks legacy or deprecated at Low
 - pick the simplest form a deepened module can take: a pure function for a transformation, a reducer for events over 1 state, a state machine when a command is valid only in some states, a class only when it owns long-lived state
 
 workflow:
-1. trace 1 typical scenario end to end before naming a finding: entry point, orchestration, domain rule, storage or external call, response
-2. grep for feature-module imports inside the `shared`, `common`, `core`, and `utils` directories, which is the inverted direction
-3. list the importers of each module, and treat a module whose every export has exactly 1 importer as a pass-through candidate for the deletion test
-4. treat an interface or type re-exported unchanged through 3+ files as a pass-through chain
-5. check whether the exports of a utility file imported by most modules share 1 domain concept
-6. read `git log --name-only` and use it twice: a feature whose commits consistently touch 4+ directories is scattered logic, and the directories changing most often are where to start
-7. name the module owning the rule and the module owning the state for each candidate, and mark the candidate speculative when neither is identifiable
-8. run these checks rather than guessing from file names
+1. locate machine-readable dependency rules first, then prose in ADRs, `ARCHITECTURE.md`, README, and `CONTRIBUTING.md`, in that order
+2. resolve conflicting ADRs only through an explicit supersede, and ask when the conflict would produce a High finding
+3. list each extracted rule, its source line, and its directory mapping in `discovery_summary` before using it
+4. write prose-derived rules to `code-smells/suggested.dependency-cruiser.cjs`, and do not add them to the project during scan
+5. when no declaration exists, report observed structure and offer a declaration rather than inventing layers
+6. run the mechanical pre-pass with the commands below against 1 unchanged tree before the semantic pass
+7. classify Knip and dependency-cruiser by parseable output rather than exit code, since both tools use non-zero and zero exits for reportable candidates
+8. record a project with source files and `totalCruised == 0` as a skipped pre-pass, and do not report its mechanical zeros
+9. state Architecture coverage as successful projects over selected projects, and list each failed config with its bounded diagnostic
+10. give the semantic pass `code-smells/metrics.md` rather than a raw graph
+11. cross each co-change pair with the graph: an edge is weak evidence, while no edge across directories is an implicit-contract candidate
+12. read ESLint boundary rules from linter output without converting them, since the linter already executed those rules
+13. consolidate all violating edges for 1 declared rule into 1 candidate, after removing declared exceptions
+14. trace `min(declared entry points, 3)` scenarios, ranked by the number of modules each entry point reaches
+15. grep for feature-module imports inside the `shared`, `common`, `core`, and `utils` directories, which is the inverted direction
+16. apply the deletion test only to a module whose whole export set has 1 importer and that wraps or re-exports another module
+17. treat an interface or type re-exported unchanged through 3+ files as a pass-through chain
+18. inspect the top 20 modules and folders by fan-in for mixed concepts, and use folder instability only to rank layer checks
+19. name the module owning the rule and the module owning the state for each candidate, and mark the candidate speculative when neither is identifiable
+20. keep each collapsed project overview, then create 2..3 focused Mermaid diagrams tied to the top findings after triage
+21. generate SVG only after `dot -V` succeeds, and keep Mermaid when Graphviz is unavailable
+22. run these checks rather than reporting a cycle, hub, orphan, co-change pair, or Knip entry directly
+```bash
+# SKILL is the directory this file was loaded from; the main workflow approved missing tools before this pass.
+SKILL=<the directory this file was loaded from>
+KNIP=$([ -x node_modules/.bin/knip ] && echo node_modules/.bin/knip || echo "npx -y knip@6.31.0")
+
+mkdir -p code-smells
+
+node "$SKILL/tools/discover-projects.mjs" > code-smells/projects.json
+$KNIP --reporter json > code-smells/knip.json
+node "$SKILL/tools/co-change.mjs" --projects code-smells/projects.json --out code-smells/co-change.md
+node "$SKILL/tools/run-cruise.mjs" --projects code-smells/projects.json --out code-smells
+
+# In a scoped mode, BASE is the comparison ref computed by scope_commands.
+node "$SKILL/tools/run-cruise.mjs" --projects code-smells/projects.json --out code-smells --base "$BASE"
+
+# After triage, create one diagram for a top finding.
+node "$SKILL/tools/run-cruise.mjs" --projects code-smells/projects.json --out code-smells --focus '<module regex>' --name <finding>
+```
 
 checks:
 - shallow modules — understanding 1 concept requires bouncing across many tiny modules: Medium
@@ -76,6 +110,7 @@ checks:
 - under-engineering — event or string-keyed indirection between 2 modules that only ever talk to each other: Low, a direct typed call is checkable
 - dependency direction — a domain or computation module importing IO directly, `node:fs`, `node:http`, a DB client, or `fetch`, where the classification puts that IO behind a seam: Medium
 - dependency direction — a shared or leaf module, `utils/`, `types/`, or `core/`, importing from a feature module: High, the inverted direction is how import cycles start
+- dependency direction — an import edge contradicting a layer rule the project declares in an ADR or ARCHITECTURE.md: High, quote the rule with its source line and list the violating edges
 - dependency direction — a wire or DTO type from an external API imported deep into a domain module instead of mapped at the seam that owns the external contract: Medium
 - state ownership — 2+ modules mutating 1 entity, cache, or record with no single owning module: High, the write paths cannot be tested or reasoned about apart
 - state ownership — fix: a shared mutable entity, by naming 1 owning module and turning each write into a named command on it
@@ -88,6 +123,7 @@ non_findings:
 - a module with exactly 1 importer that hides an ordering, an invariant, or a decision: 1 importer starts the deletion test and is not a finding by itself
 - a layer count: the direction of the dependencies is the finding, and a layer holding a real rule is not
 - a port with 1 production adapter whose test double checks the same contract: the double is the second adapter
+- duplicated trees whose intent is documented, excluded by tool policy, or maintained in lockstep: report at most the synchronized-edit cost at Low, not the decision
 - formatting, import ordering, and file naming: `references/code-quality.md` owns them, and they are not architecture findings
 
 forbidden_behaviors:
@@ -102,7 +138,9 @@ forbidden_behaviors:
 - do not leave a new structure standing beside the old one: every proposal names the step deleting what it replaces
 - do not propose a change contradicting a decision under `docs/adr/` silently: name the ADR and the conflict, and leave the decision to the operator
 - do not report architecture candidates without naming 1 top recommendation and the reason it goes first
-- do not add an import-linting dependency for 1 rule: use `package.json#exports`, the linter the project already runs, or the workspace layout
+- do not claim the repository has no cycles, orphans, or coupling issues below 100% Architecture coverage: name the successful projects
+- do not add a dependency as the fix for 1 import rule: use `package.json#exports`, the project's linter, or the workspace layout
+- do not treat an approved `npx` graph tool used during review as a project dependency: it changes neither `package.json` nor the lockfile
 
 dependency_classification:
 
@@ -115,6 +153,9 @@ dependency_classification:
 
 severity_mapping:
 
+- map a project-declared severity to the finding: `error` to High, `warn` to Medium, and `info` to Low
+- copy the declared rule comment into Evidence, since it states the project's rationale and accepted debt
+
 | Severity | Architecture criteria |
 |---|---|
 | Highest | an architecture issue directly causing a security vulnerability, data loss, or a production correctness bug |
@@ -124,6 +165,10 @@ severity_mapping:
 
 fixability:
 
+- an `enforce` change is `report-only`, since scan does not write a project config
+- a `delete` change is `auto` only when no module imports the target
+- a deepening, merge, or ownership move is `needs-confirm`
+
 | Fixability | Meaning | Fix mode behaviour |
 |---|---|---|
 | `auto` | a local change: import path cleanup, a narrow circular-import break, a local module merge with co-located tests | applied in the normal fix loop |
@@ -134,17 +179,19 @@ report_format:
 ```md
 ### TITLE — Severity
 
-- **Confidence:** strong | worth-exploring | speculative
+- **Confidence:** strong | worth-exploring
 - **Files:** relative/path/a.ts, relative/path/b.ts
 - **Problem:** why this causes friction now (not just a pattern name)
 - **Evidence:** the imports, callers, `git log` path, or test the finding rests on
-- **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
+- **Change type:** deepening | ownership move | merge | delete | enforce
+- **Proposed change:** plain-English description of what would change
+- **Interface shape:** for deepening or merge only; rough sketch of the new interface and key invariants
+- **Dependency category:** for deepening only; in-process | local-substitutable | remote-owned | true-external
+- **Rule:** for enforce only; the exact rule text and the file where it would live
 - **Test strategy:** how tests would improve (what tests survive, what gets deleted, what's new)
-- **Migration:** prefactor | vertical slices | expand-contract, and the step deleting the replaced code
+- **Migration:** for deepening, merge, ownership move, or delete; prefactor | vertical slices | expand-contract, and the deletion step
 - **Benefits:** locality gained, leverage gained, test impact
 - **Trade-offs:** what gets harder, what is genuinely uncertain
-- **Fixability:** auto | needs-confirm | report-only
+- **Fixability:** auto | needs-confirm | report-only, and report-only for enforce, since a new rule fails the build before the edges it names are gone
 - **Top recommendation:** on exactly 1 entry in the report, the reason this candidate goes first
 ```