ts-reviewer 3.0.0 → 3.0.1

package/README.md

@@ -228,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.
@@ -241,20 +241,23 @@ The test catches a check line that lost its severity, a block the profile does n
 
 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. **Architecture pre-pass** — when active, writes bounded Knip, graph, metric, co-change, rule, and Mermaid artifacts under `code-smells/`.
+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`. Architecture findings appear in a separate `## Architecture Opportunities` section at the end.
+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/report.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, keeps the remaining `code-smells/` artifacts, and asks before removing them
+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
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ts-reviewer",
-  "version": "3.0.0",
+  "version": "3.0.1",
   "description": "Install the TypeScript Code Reviewer skill for Claude Code, Codex, or Antigravity",
   "license": "MIT",
   "type": "module",

package/ts-reviewer/SKILL.md

@@ -61,6 +61,7 @@ forbidden_behaviors:
 - 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/report.md` in the project root: the scan report, and the work plan fix reads
@@ -148,21 +149,29 @@ workflow:
 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. sort by severity group, then category, then file path, and place `in_diff: true` before pre-existing in a scoped mode
-36. show the top 10 and summarize the rest in a table when Medium and Low together hold more than 15 issues
-37. recommend that the operator adds `code-smells/` to `.gitignore`: it holds review artifacts
-38. read `references/fix-workflow.md` before fix mode executes: it holds the complete protocol
-39. detect the test runner and run the baseline tests
-40. fix the issues file by file, and run `tsc --noEmit` after each file
-41. run the linter and fix the lint errors it reports
-42. run the full test suite, compare it against the baseline, and fix the regressions
-43. repeat the compiler, linter, and test verification with verification iterations <= 5
-44. rerun the Architecture mechanical pre-pass on the fixed tree when Architecture is active
-45. update `code-smells/report.md`: remove what is fixed, mark what failed
-46. show the scan summary in auto mode, and ask the operator whether to proceed with the fix
-47. re-scan after the fix in auto mode with full scan-fix cycles <= 2, and stop when issues persist after the second
-48. delete `code-smells/report.md` and report success when every issue is fixed
-49. retain the remaining `code-smells/` artifacts, state what they contain, and remove them only after the operator confirms
+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
@@ -225,6 +234,7 @@ 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>
@@ -260,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
 
@@ -268,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)
 
@@ -275,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]
@@ -282,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
@@ -293,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

@@ -54,19 +54,20 @@ workflow:
 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. give the semantic pass `code-smells/metrics.md` rather than a raw graph
-10. cross each co-change pair with the graph: an edge is weak evidence, while no edge across directories is an implicit-contract candidate
-11. read ESLint boundary rules from linter output without converting them, since the linter already executed those rules
-12. consolidate all violating edges for 1 declared rule into 1 candidate, after removing declared exceptions
-13. trace `min(declared entry points, 3)` scenarios, ranked by the number of modules each entry point reaches
-14. grep for feature-module imports inside the `shared`, `common`, `core`, and `utils` directories, which is the inverted direction
-15. apply the deletion test only to a module whose whole export set has 1 importer and that wraps or re-exports another module
-16. treat an interface or type re-exported unchanged through 3+ files as a pass-through chain
-17. inspect the top 20 modules and folders by fan-in for mixed concepts, and use folder instability only to rank layer checks
-18. name the module owning the rule and the module owning the state for each candidate, and mark the candidate speculative when neither is identifiable
-19. after triage, create 2..3 focused Mermaid diagrams tied to the top findings, and do not create a whole-project diagram
-20. generate SVG only after `dot -V` succeeds, and keep Mermaid when Graphviz is unavailable
-21. run these checks rather than reporting a cycle, hub, orphan, co-change pair, or Knip entry directly
+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>
@@ -137,6 +138,7 @@ 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 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
 
@@ -190,6 +192,6 @@ report_format:
 - **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
 ```

package/ts-reviewer/references/fix-workflow.md

@@ -10,12 +10,18 @@ read_first:
 - `code-smells/report.md` exists in the project root, and a missing report stops the run with the error "No scan report found at code-smells/report.md. Run scan first; the report path changed in v3."
 - the project is inside a git repository, so a change can be reverted
 - recommend that the operator commits or stashes uncommitted work before the fix runs, which leaves `git diff` and `git checkout -- .` usable to review and revert
-- the baseline taken in step 3 decides what counts as a regression: a test failing before the fixes is pre-existing and stays out of the work
+- the baseline taken in step 9 decides what counts as a regression: a test failing before the fixes is pre-existing and stays out of the work
 
 workflow:
-1. read `code-smells/report.md` and extract every issue into a work list
-2. group the issues by file path, and sort them by line number descending inside each file, so a fix lower in the file does not shift the lines above it
-3. build the work plan
+1. validate the report and stop without changing code when it reports an error, since a `warning:` line names a pre-pass outcome rather than a defect of the report
+```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
+```
+2. read `code-smells/report.md` and extract every issue into a work list
+3. group the issues by file path, and sort them by line number descending inside each file, so a fix lower in the file does not shift the lines above it
+4. build the work plan
 ```
 File: src/auth/token.ts
   - Line 142: [High] Unsafe `as` cast — type-safety
@@ -26,21 +32,21 @@ File: src/api/handler.ts
   - Line 201: [Highest] eval() with user input — security
   - Line 55:  [Medium] Missing exhaustive check — type-safety
 ```
-4. detect the test runner through the signals in `test_runners`, in the order listed there
-5. detect the test file convention: `*.test.ts` against `*.spec.ts`, a `__tests__/` directory against co-location, and the framework imports, `describe` and `it` against `test`
-6. warn the operator with "No test runner detected. Fixes will be applied without test verification." when no test infrastructure is found, skip every test step, and still run the compiler and the linter
-7. run the full test suite before any change, and write the log to the OS temp directory, or to the project root when temp is unavailable
+5. detect the test runner through the signals in `test_runners`, in the order listed there
+6. detect the test file convention: `*.test.ts` against `*.spec.ts`, a `__tests__/` directory against co-location, and the framework imports, `describe` and `it` against `test`
+7. warn the operator with "No test runner detected. Fixes will be applied without test verification." when no test infrastructure is found, skip every test step, and still run the compiler and the linter
+8. run the full test suite before any change, and write the log to the OS temp directory, or to the project root when temp is unavailable
 ```bash
 <test_command> 2>&1 | tee "$TMPDIR/ts-reviewer-baseline.log"
 ```
-8. record the baseline: total tests, passing, failing with the list, and the command used
-9. process 1 file at a time, reading its current state before each fix, since an earlier fix in the same file has shifted the lines
-10. apply the fix the report describes
-11. update every reference to a renamed or replaced symbol across the codebase, its imports and its usages, when the fix replaces a pattern such as `enum` with `as const`
-12. write a regression test for each testable fix: an incorrect cast, an injection sink, a floating promise, or a missing null check
-13. skip the regression test for an untestable fix: a naming or formatting change, a config flag, a modernization that keeps the behaviour, or a complexity split
-14. name the regression test file `<original-file>.reviewer-fixes.test.ts`, following the naming, the placement, and the framework the project already uses
-15. label each test with the issue title, and keep it to the specific fix rather than the whole function
+9. record the baseline: total tests, passing, failing with the list, and the command used
+10. process 1 file at a time, reading its current state before each fix, since an earlier fix in the same file has shifted the lines
+11. apply the fix the report describes
+12. update every reference to a renamed or replaced symbol across the codebase, its imports and its usages, when the fix replaces a pattern such as `enum` with `as const`
+13. write a regression test for each testable fix: an incorrect cast, an injection sink, a floating promise, or a missing null check
+14. skip the regression test for an untestable fix: a naming or formatting change, a config flag, a modernization that keeps the behaviour, or a complexity split
+15. name the regression test file `<original-file>.reviewer-fixes.test.ts`, following the naming, the placement, and the framework the project already uses
+16. label each test with the issue title, and keep it to the specific fix rather than the whole function
 ```typescript
 describe('ts-reviewer fixes: src/auth/token.ts', () => {
   it('should not use unsafe cast for token payload (type-safety)', () => {
@@ -48,40 +54,40 @@ describe('ts-reviewer fixes: src/auth/token.ts', () => {
   });
 });
 ```
-16. tell the operator that the `.reviewer-fixes` files are candidates to rename and merge into the existing suites: the naming is a handoff convention and not a permanent home
-17. run `npx tsc --noEmit 2>&1` after each file, and use `--incremental` or check every 3..5 files instead where the work plan > 30 files and a full typecheck is slow
-18. fix a new compiler error in the file just changed or in a file the change affects, then run the compiler again to confirm
-19. revert the last fix in the file and mark the issue `[FIX FAILED: caused type errors]` when the same error survives 2 attempts
-20. repeat steps 9..19 for each file in the work plan
-21. run the linter over the changed files once every file is fixed
+17. tell the operator that the `.reviewer-fixes` files are candidates to rename and merge into the existing suites: the naming is a handoff convention and not a permanent home
+18. run `npx tsc --noEmit 2>&1` after each file, and use `--incremental` or check every 3..5 files instead where the work plan > 30 files and a full typecheck is slow
+19. fix a new compiler error in the file just changed or in a file the change affects, then run the compiler again to confirm
+20. revert the last fix in the file and mark the issue `[FIX FAILED: caused type errors]` when the same error survives 2 attempts
+21. repeat steps 10..20 for each file in the work plan
+22. run the linter over the changed files once every file is fixed
 ```bash
 # ESLint
 npx eslint [changed_files] --format json 2>/dev/null
 # or Biome
 npx biome check [changed_files] --reporter json 2>/dev/null
 ```
-22. apply `npx eslint --fix [files]` or `npx biome check --fix [files]`, fix the rest by hand, and run the linter again to confirm it is clean
-23. run the full test suite and compare it against the baseline through `baseline_verdicts`
+23. apply `npx eslint --fix [files]` or `npx biome check --fix [files]`, fix the rest by hand, and run the linter again to confirm it is clean
+24. run the full test suite and compare it against the baseline through `baseline_verdicts`
 ```bash
 <test_command> 2>&1 | tee "$TMPDIR/ts-reviewer-postfix.log"
 ```
-24. read the failure and the stack trace of each regression, and identify the fix that caused it from the diff of that file
-25. fix the regression, or revert the fix that caused it and mark it `[FIX REVERTED: caused test regression in <test>]`
-26. repeat the compiler, the linter, and the full suite until they are clean, with iterations <= 5
+25. read the failure and the stack trace of each regression, and identify the fix that caused it from the diff of that file
+26. fix the regression, or revert the fix that caused it and mark it `[FIX REVERTED: caused test regression in <test>]`
+27. repeat the compiler, the linter, and the full suite until they are clean, with iterations <= 5
 ```
 Iteration 1: Fixed 12/15 issues. 2 test regressions found.
 Iteration 2: Fixed 2 regressions. 1 new tsc error.
 Iteration 3: Fixed tsc error. All tests pass. Clean.
 -> Done at iteration 3.
 ```
-27. stop fixing once the fifth iteration ends with the compiler, the linter, or the suite still not clean, leave the code as it stands, and add a Stabilization section to the report listing the unresolved regressions for the operator
-28. show the operator what a `needs-confirm` architecture finding would change, and describe the reorganization or the interface change
-29. apply an approved `needs-confirm` finding through the same file-by-file compiler loop, and mark a rejected one `[SKIPPED: user rejected]`
-30. rerun Knip, dependency-cruiser, and co-change through the Architecture workflow when the report contains architecture findings
-31. delete `code-smells/report.md` when every issue is fixed, and tell the operator "All N issues fixed. Report deleted. Run scan again to verify."
-32. keep `code-smells/` after deleting the report, state what it contains, and ask before removing the directory
-33. rewrite `code-smells/report.md` in the shape of `report_format` when any issue remains, carrying both what was fixed and what was not
-34. leave every change in the working tree, unstaged and uncommitted, including the new regression test files
+28. stop fixing once the fifth iteration ends with the compiler, the linter, or the suite still not clean, leave the code as it stands, and add a Stabilization section to the report listing the unresolved regressions for the operator
+29. show the operator what a `needs-confirm` architecture finding would change, and describe the reorganization or the interface change
+30. apply an approved `needs-confirm` finding through the same file-by-file compiler loop, and mark a rejected one `[SKIPPED: user rejected]`
+31. rerun Knip, dependency-cruiser, and co-change through the Architecture workflow when the report contains architecture findings
+32. delete `code-smells/report.md` when every issue is fixed, and tell the operator "All N issues fixed. Report deleted. Run scan again to verify."
+33. keep `code-smells/` after deleting the report, state what it contains, and ask before removing the directory
+34. rewrite `code-smells/report.md` in the shape of `report_format` when any issue remains, carrying both what was fixed and what was not
+35. leave every change in the working tree, unstaged and uncommitted, including the new regression test files
 
 forbidden_behaviors:
 - do not commit and do not stage: the operator reviews and decides

package/ts-reviewer/tools/run-cruise.mjs

@@ -84,8 +84,13 @@ const nodePath = existsSync(path.join(projectModules, "typescript"))
   : process.env.NODE_PATH || projectModules;
 const localCruise = path.join(projectModules, ".bin", process.platform === "win32" ? "depcruise.cmd" : "depcruise");
 
+// `--ts-config` is absolute on purpose, and a relative path here is not equivalent even though the
+// cwd is the repository: TypeScript resolves the config's own `include` globs against the cwd when
+// the path is relative, so a nested `templates/x/tsconfig.json` with `include: ["src"]` looks for
+// `<repo>/src` and exits TS18003, no inputs found. Every nested project on the first real run failed
+// this way, and every project that passed sat at the repository root.
 function cruise(label, extraArgs, project) {
-  const toolArgs = ["--config", ruleset, "--ts-config", project.config, ...extraArgs, ...project.sourceRoots];
+  const toolArgs = ["--config", ruleset, "--ts-config", path.resolve(repo, project.config), ...extraArgs, ...project.sourceRoots];
   const args = existsSync(localCruise) ? toolArgs : ["-y", TOOL, ...toolArgs];
   const shell = process.platform === "win32";
   const started = Date.now();
@@ -149,9 +154,14 @@ const orphans = new Set();
 const crossDirectory = new Set();
 const violations = new Set();
 const projectRows = [];
+// A project counts as covered when it produced a graph, and nothing else: the graph is what the
+// semantic pass reads, while a failed mermaid or affected step costs a diagram and not an analysis.
+// One predicate, so metrics.md, cruise-summary.md, and the report's coverage cannot disagree.
 for (const { project, graph } of results) {
+  const modules = graph?.modules ?? [];
+  projectRows.push([project.config, graph ? "ok" : "failed", modules.length,
+    graph?.summary?.totalDependenciesCruised ?? 0, modules.filter((m) => m.orphan).length]);
   if (!graph) continue;
-  const modules = graph.modules ?? [];
   const roots = [...project.sourceRoots].sort((a, b) => b.length - a.length);
   const area = (source) => {
     const root = roots.find((candidate) => source === candidate || source.startsWith(`${candidate}/`));
@@ -178,13 +188,12 @@ for (const { project, graph } of results) {
   for (const violation of graph.summary?.violations ?? []) {
     violations.add(`${violation.rule?.name ?? "unnamed"} | ${violation.from ?? ""} | ${violation.to ?? ""}`);
   }
-  projectRows.push([project.config, modules.length, graph.summary?.totalDependenciesCruised ?? 0, modules.filter((m) => m.orphan).length]);
 }
 const topModules = [...moduleRows.values()].sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0])).slice(0, 20);
 const topFolders = [...folderRows.values()].sort((a, b) => b[2] - a[2] || a[0].localeCompare(b[0])).slice(0, 20);
 const metricsLines = [
   "# Architecture metrics", "",
-  "## Projects", "", ...table(["Project", "Modules", "Edges", "Orphans"], projectRows), "",
+  "## Projects", "", ...table(["Project", "Status", "Modules", "Edges", "Orphans"], projectRows), "",
   "## Top modules by fan-in", "", ...table(["Module", "Fan-in", "Fan-out", "Instability"], topModules), "",
   "## Top folders by fan-in", "", ...table(["Folder", "Modules", "Afferent", "Efferent", "Instability"], topFolders), "",
   "## Cycles", "", ...(cycles.size ? [...cycles].slice(0, 20).map((edge) => `- ${edge}`) : ["- none"]), "",
@@ -195,18 +204,22 @@ const metricsLines = [
 writeFileSync(path.join(outDir, "metrics.md"), metricsLines.join("\n"), "utf8");
 
 // ── summary ─────────────────────────────────────────────────────────────────
-const lines = [`# Cruise summary`, ``, `Ruleset: ${rulesFrom}`, ``,
-  `| Project | Source roots | Step | Exit | Reading |`, `|---|---|---|---|---|`];
-let failures = 0;
-for (const { project, runs } of results) {
-  for (const run of runs) {
-    if (run.reading.startsWith("failed")) failures++;
-    lines.push(`| ${project.config} | ${project.sourceRoots.join(", ")} | ${run.label.split(" ")[1]} | ${run.exitCode} | ${run.reading} |`);
-  }
+const summaryRows = [];
+let successful = 0;
+for (const { project, graph, runs } of results) {
+  if (graph) successful++;
+  const failed = runs.filter((run) => run.reading.startsWith("failed"));
+  const diagnostics = [...new Set(failed.flatMap((run) => `${run.stderr}\n${run.stdout}`.split(/\r?\n/))
+    .map((line) => line.trim()).filter(Boolean))].slice(0, 3).join(" / ").slice(0, 500);
+  summaryRows.push([project.config, project.sourceRoots.join(", "), graph ? "ok" : "failed",
+    failed.map((run) => run.label.split(" ")[1]).join(", ") || "none", diagnostics || "none"]);
 }
-lines.push(``, failures
-  ? `**${failures} step(s) failed.** A cruise of zero modules is a failed pre-pass, not a clean result: record it as skipped and do not read the empty graph as an absence of coupling.`
-  : `All steps produced a graph. Zero findings from these runs are reportable as mechanical zeros.`);
+const failures = results.length - successful;
+const lines = [`# Cruise summary`, ``, `Ruleset: ${rulesFrom}`, ``,
+  `Coverage: ${successful}/${results.length} projects`, ``,
+  ...table(["Project", "Source roots", "Status", "Failed steps", "Diagnostics"], summaryRows), ``, failures
+    ? `**${failures} project(s) failed.** Record them as skipped and do not read their empty graphs as an absence of coupling.`
+    : `All projects produced graphs. Zero findings from these runs are reportable as mechanical zeros.`];
 
 writeFileSync(path.join(outDir, "cruise-summary.md"), lines.join("\n") + "\n", "utf8");
 console.log(lines.join("\n"));

package/ts-reviewer/tools/validate-report.mjs

@@ -0,0 +1,324 @@
+#!/usr/bin/env node
+// Checks code-smells/report.md against the `report_format` block of SKILL.md, and nothing beyond it:
+// the spec is the contract, this script is only the reader that enforces it.
+//
+//   node validate-report.mjs --repo . --report code-smells/report.md
+//
+// An error is a defect of the report text, which rewriting the report can correct. A warning names
+// an outcome of the mechanical pre-pass, which it cannot — a missing diagram is not a bad report,
+// and failing the run over one would burn the two validation attempts the workflow allows.
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import path from "node:path";
+
+const DOMAINS = new Set([
+  "Type Safety", "Security", "Async Patterns", "Modernization", "Code Quality", "Config",
+  "Boundary Validation", "Error Handling", "Dependency Hygiene", "Architecture",
+]);
+const SEVERITIES = ["Highest", "High", "Medium", "Low"];
+// The whole section set, in the order report_format gives it. Anything else is a renamed section.
+const SECTIONS = [
+  { name: "Summary", required: true },
+  { name: "Discovery", required: false },
+  { name: "Highest + High Issues", required: true },
+  { name: "Medium Issues", required: true },
+  { name: "Low Issues", required: true },
+  { name: "Recurring Patterns", required: true },
+  { name: "Config Issues", required: true },
+  { name: "Pre-existing Issues (scoped modes only)", required: false },
+  { name: "Architecture Opportunities", required: false },
+  { name: "Verification", required: false },
+  { name: "Generated artifacts", required: false },
+];
+const ISSUE_SECTIONS = [
+  "Highest + High Issues", "Medium Issues", "Low Issues", "Recurring Patterns", "Config Issues",
+  "Pre-existing Issues (scoped modes only)",
+];
+const SECTION_SEVERITY = { "Medium Issues": "Medium", "Low Issues": "Low" };
+const COMMON_ARCH_FIELDS = [
+  "Confidence", "Files", "Problem", "Evidence", "Change type", "Proposed change",
+  "Test strategy", "Benefits", "Trade-offs", "Fixability",
+];
+const CONDITIONAL_ARCH_FIELDS = {
+  deepening: ["Interface shape", "Dependency category", "Migration"],
+  merge: ["Interface shape", "Migration"],
+  "ownership move": ["Migration"],
+  delete: ["Migration"],
+  enforce: ["Rule"],
+};
+
+const value = (name, fallback) => {
+  const at = process.argv.indexOf(`--${name}`);
+  return at >= 0 && process.argv[at + 1] ? process.argv[at + 1] : fallback;
+};
+const repo = path.resolve(value("repo", "."));
+const reportArg = value("report", "code-smells/report.md");
+const report = path.isAbsolute(reportArg) ? reportArg : path.resolve(repo, reportArg);
+if (!existsSync(report)) {
+  console.error(`${path.relative(repo, report) || report}:1: report does not exist`);
+  process.exit(1);
+}
+
+const lines = readFileSync(report, "utf8").split(/\r?\n/);
+const errors = [];
+const warnings = [];
+const fail = (line, message) => errors.push({ line: Math.max(1, line), message });
+const warn = (line, message) => warnings.push({ line: Math.max(1, line), message });
+const insideRepo = (target) => {
+  const relative = path.relative(repo, target);
+  return relative !== "" && !relative.startsWith("..") && !path.isAbsolute(relative);
+};
+const checkRepoPath = (raw, line) => {
+  if (path.isAbsolute(raw)) {
+    fail(line, `path must be relative: ${raw}`);
+    return null;
+  }
+  const target = path.resolve(repo, raw);
+  if (!insideRepo(target)) { fail(line, `path leaves the repository: ${raw}`); return null; }
+  if (!existsSync(target)) { fail(line, `path does not exist: ${raw}`); return null; }
+  return target;
+};
+
+const firstContent = lines.findIndex((line) => line.trim());
+if (lines[firstContent] !== "# TypeScript Code Review Report") fail(firstContent + 1, "expected exact report title");
+
+// ── sections ────────────────────────────────────────────────────────────────
+const h2s = lines.flatMap((line, index) => {
+  const match = line.match(/^## (.+)$/);
+  return match ? [{ name: match[1], index }] : [];
+});
+const actualSections = h2s.map(({ name }) => name);
+const known = new Set(SECTIONS.map((section) => section.name));
+const firstHeading = (h2s[0]?.index ?? 0) + 1;
+for (const { name, index } of h2s) if (!known.has(name)) fail(index + 1, `unknown section: ${name}`);
+for (const { name, required } of SECTIONS) {
+  if (required && !actualSections.includes(name)) fail(firstHeading, `missing section: ${name}`);
+}
+const present = actualSections.filter((name) => known.has(name));
+const expected = SECTIONS.map(({ name }) => name).filter((name) => actualSections.includes(name));
+if (present.join("\n") !== expected.join("\n")) {
+  fail(firstHeading, `sections are out of order or repeated; expected: ${expected.join(" > ")}`);
+}
+const sections = new Map(h2s.map((heading, index) => [heading.name, {
+  start: heading.index + 1,
+  end: h2s[index + 1]?.index ?? lines.length,
+  line: heading.index + 1,
+}]));
+
+const metadata = ["Project", "Reviewed", "Stack", "Scope", "Files analyzed", "Total issues"];
+for (const name of metadata) {
+  const matches = lines.flatMap((line, index) => line.startsWith(`**${name}:**`) ? [index] : []);
+  if (matches.length !== 1) fail(matches[0] + 1 || 1, `metadata ${name} must appear exactly once`);
+}
+const totalLine = lines.findIndex((line) => line.startsWith("**Total issues:**"));
+const totalMatch = lines[totalLine]?.match(/^\*\*Total issues:\*\* (\d+) \((\d+) highest, (\d+) high, (\d+) medium, (\d+) low\)$/);
+if (!totalMatch) fail(totalLine + 1, "Total issues has an invalid shape");
+
+// ── findings ────────────────────────────────────────────────────────────────
+// A table in an issue section is read by its header: the summary table of workflow step 39 carries
+// issues, and the Recurring Patterns table carries patterns whose members are counted where they sit.
+const cells = (line) => line.split("|").slice(1, -1).map((cell) => cell.trim());
+const isSummaryTable = (header) => header.includes("Category") && header.includes("Location");
+const isPatternTable = (header) => header.includes("Pattern") && header.includes("Occurrences");
+
+const counts = new Map(SEVERITIES.map((severity) => [severity, 0]));
+let issueCount = 0;
+const duplicates = new Map();
+const headingPattern = /^### .+ — (Highest|High|Medium|Low)(?: \[.+\])?$/;
+
+for (const sectionName of ISSUE_SECTIONS) {
+  const section = sections.get(sectionName);
+  if (!section) continue;
+  const headings = [];
+  for (let index = section.start; index < section.end; index++) {
+    if (lines[index].startsWith("### ")) headings.push(index);
+  }
+  for (let at = 0; at < headings.length; at++) {
+    const index = headings[at];
+    const end = headings[at + 1] ?? section.end;
+    const heading = lines[index].match(headingPattern);
+    if (!heading) {
+      fail(index + 1, "finding heading must end with an exact severity");
+      continue;
+    }
+    const severity = heading[1];
+    if (sectionName === "Highest + High Issues" && !["Highest", "High"].includes(severity)) fail(index + 1, "severity does not match its section");
+    if (sectionName === "Medium Issues" && severity !== "Medium") fail(index + 1, "severity does not match its section");
+    if (sectionName === "Low Issues" && severity !== "Low") fail(index + 1, "severity does not match its section");
+    counts.set(severity, counts.get(severity) + 1);
+    issueCount++;
+
+    const block = lines.slice(index + 1, end);
+    const metaAt = block.findIndex((line) => line.startsWith("**Category:**"));
+    const meta = block[metaAt]?.match(/^\*\*Category:\*\* (.+?) \| \*\*File:\*\* `([^`]+)` \| \*\*Line:\*\* (\d+) \| \*\*Auto-fixable:\*\* (Yes|No) \| \*\*New code:\*\* (Yes|No)$/);
+    if (!meta) {
+      fail(index + 1, "finding metadata is missing or has the wrong field names");
+      continue;
+    }
+    const categories = meta[1].split(/\s*(?:,|&)\s*/);
+    for (const category of categories) {
+      if (!DOMAINS.has(category)) fail(index + metaAt + 2, `unknown category: ${category}`);
+    }
+    const source = checkRepoPath(meta[2], index + metaAt + 2);
+    const sourceLine = Number(meta[3]);
+    // Workflow step 31 merges what two domains raise on one file and line into one entry naming
+    // both categories, so a second entry on that line is the merge that did not happen.
+    const key = `${meta[2]}:${sourceLine}`.toLowerCase();
+    if (duplicates.has(key)) fail(index + 1, `duplicate finding; first entry is at line ${duplicates.get(key)}`);
+    else duplicates.set(key, index + 1);
+    if (!block.some((line) => line.startsWith("**Problem:** "))) fail(index + 1, "finding has no Problem field");
+    if (!block.some((line) => line.startsWith("**Fix:** "))) fail(index + 1, "finding has no Fix field");
+
+    const fence = block.findIndex((line) => /^```[^`]*$/.test(line));
+    const fenceEnd = fence >= 0 ? block.findIndex((line, at) => at > fence && line === "```") : -1;
+    if (fence < 0 || fenceEnd < 0) {
+      fail(index + 1, "finding has no fenced snippet");
+    } else if (source && statSync(source).isFile()) {
+      const sourceLines = readFileSync(source, "utf8").split(/\r?\n/);
+      if (sourceLine < 1 || sourceLine > sourceLines.length) fail(index + metaAt + 2, `line is outside the file: ${sourceLine}`);
+      else {
+        // A snippet runs 3-7 lines and the stated line sits anywhere inside it, so the window is the
+        // snippet's own length on either side, and any one of its lines anchors it to the file.
+        const snippet = block.slice(fence + 1, fenceEnd).map((line) => line.trim()).filter(Boolean);
+        const reach = snippet.length;
+        const window = new Set(sourceLines.slice(Math.max(0, sourceLine - 1 - reach), sourceLine + reach).map((line) => line.trim()));
+        if (reach && !snippet.some((line) => window.has(line))) {
+          fail(index + fence + 2, `snippet matches no line within ${reach} line(s) of line ${sourceLine}`);
+        }
+      }
+    }
+  }
+
+  let counting = false;
+  let fenced = false;
+  for (let index = section.start; index < section.end; index++) {
+    if (lines[index].startsWith("```")) { fenced = !fenced; continue; }
+    if (fenced) continue;
+    if (/^\|[-:| ]+\|$/.test(lines[index])) {
+      const header = cells(lines[index - 1] ?? "");
+      counting = isSummaryTable(header);
+      if (!counting && !isPatternTable(header)) {
+        fail(index, "table header must carry Category and Location, or Pattern and Occurrences");
+      } else if (counting && !SECTION_SEVERITY[sectionName]) {
+        fail(index, "a summary table belongs in Medium Issues or Low Issues");
+        counting = false;
+      }
+      continue;
+    }
+    if (lines[index].startsWith("|") && lines[index].endsWith("|")) {
+      if (!counting) continue;
+      const severity = SECTION_SEVERITY[sectionName];
+      counts.set(severity, counts.get(severity) + 1);
+      issueCount++;
+    } else if (lines[index].trim()) counting = false;
+  }
+}
+
+// ── architecture opportunities ──────────────────────────────────────────────
+const architecture = sections.get("Architecture Opportunities");
+let architectureEntries = 0;
+let topRecommendations = 0;
+if (architecture) {
+  const headings = [];
+  for (let index = architecture.start; index < architecture.end; index++) if (lines[index].startsWith("### ")) headings.push(index);
+  if (!headings.length) fail(architecture.line, "Architecture Opportunities has no entries");
+  for (let at = 0; at < headings.length; at++) {
+    const index = headings[at];
+    const end = headings[at + 1] ?? architecture.end;
+    const heading = lines[index].match(headingPattern);
+    if (!heading) { fail(index + 1, "architecture heading must end with an exact severity"); continue; }
+    counts.set(heading[1], counts.get(heading[1]) + 1);
+    issueCount++;
+    architectureEntries++;
+    const fields = new Map();
+    for (let line = index + 1; line < end; line++) {
+      const match = lines[line].match(/^- \*\*([^*]+):\*\* (.+)$/);
+      if (!match) continue;
+      if (fields.has(match[1])) fail(line + 1, `duplicate architecture field: ${match[1]}`);
+      fields.set(match[1], { value: match[2], line: line + 1 });
+    }
+    for (const field of COMMON_ARCH_FIELDS) if (!fields.has(field)) fail(index + 1, `missing architecture field: ${field}`);
+    const confidence = fields.get("Confidence");
+    if (confidence && !["strong", "worth-exploring"].includes(confidence.value)) fail(confidence.line, `invalid Confidence: ${confidence.value}`);
+    const change = fields.get("Change type");
+    const conditional = change ? CONDITIONAL_ARCH_FIELDS[change.value] : null;
+    if (change && !conditional) fail(change.line, `invalid Change type: ${change.value}`);
+    for (const field of conditional ?? []) if (!fields.has(field)) fail(index + 1, `missing architecture field: ${field}`);
+    const allowed = new Set([...COMMON_ARCH_FIELDS, ...(conditional ?? []), "Top recommendation"]);
+    for (const [field, data] of fields) if (!allowed.has(field)) fail(data.line, `field does not apply to ${change?.value ?? "this change"}: ${field}`);
+    const fixability = fields.get("Fixability");
+    if (fixability && !["auto", "needs-confirm", "report-only"].includes(fixability.value)) fail(fixability.line, `invalid Fixability: ${fixability.value}`);
+    if (change?.value === "enforce" && fixability?.value !== "report-only") fail(fixability?.line ?? index + 1, "enforce changes must be report-only");
+    if (fields.has("Top recommendation")) topRecommendations++;
+    const files = fields.get("Files");
+    if (files) for (const file of files.value.split(",").map((item) => item.trim().replaceAll("`", ""))) checkRepoPath(file, files.line);
+  }
+  if (architectureEntries && topRecommendations !== 1) fail(architecture.line, "architecture findings require exactly one Top recommendation");
+}
+
+if (totalMatch) {
+  const stated = totalMatch.slice(2).map(Number);
+  if (Number(totalMatch[1]) !== issueCount) fail(totalLine + 1, `Total issues says ${totalMatch[1]}, found ${issueCount}`);
+  SEVERITIES.forEach((severity, index) => {
+    if (stated[index] !== counts.get(severity)) fail(totalLine + 1, `${severity} count says ${stated[index]}, found ${counts.get(severity)}`);
+  });
+}
+
+// ── linked artifacts ────────────────────────────────────────────────────────
+const reportDir = path.dirname(report);
+for (let index = 0; index < lines.length; index++) {
+  for (const match of lines[index].matchAll(/\[[^\]]*\]\(([^)]+)\)/g)) {
+    let link;
+    try { link = decodeURI(match[1].replace(/^<|>$/g, "")).split("#")[0]; }
+    catch { fail(index + 1, `artifact link has invalid escaping: ${match[1]}`); continue; }
+    if (/^(?:https?:|mailto:|#)/.test(link)) continue;
+    if (!/\.(?:json|mmd|md|svg)$/i.test(link)) continue;
+    const targets = [path.resolve(reportDir, link), path.resolve(repo, link)];
+    const target = targets.find((candidate) => insideRepo(candidate) && existsSync(candidate));
+    if (!target) fail(index + 1, `linked artifact does not exist: ${link}`);
+    else if (path.extname(target) === ".json") {
+      try { JSON.parse(readFileSync(target, "utf8")); } catch { fail(index + 1, `linked JSON is invalid: ${link}`); }
+    }
+  }
+}
+
+// ── architecture coverage ───────────────────────────────────────────────────
+// The claim the report makes about how much of the tree was analysed is the one number a reader
+// trusts when it says there are no cycles, so an overclaim is an error and everything else is not.
+const coverageLine = lines.findIndex((line) => line.startsWith("**Architecture coverage:**"));
+const coverage = lines[coverageLine]?.match(/^\*\*Architecture coverage:\*\* (\d+)\/(\d+)$/);
+const architectureActive = coverageLine >= 0 || Boolean(architecture);
+if (architectureActive) {
+  if (!coverage) fail(coverageLine + 1 || 1, "Architecture coverage must have the shape successful/selected");
+  const at = coverageLine + 1 || 1;
+  const core = ["projects.json", "co-change.md", "cruise-summary.md", "metrics.md"];
+  for (const artifact of core) if (!existsSync(path.join(reportDir, artifact))) warn(at, `missing architecture artifact: ${artifact}`);
+  const graphDir = path.join(reportDir, "graphs");
+  const graphFiles = existsSync(graphDir) && statSync(graphDir).isDirectory()
+    ? readdirSync(graphDir).filter((file) => file.endsWith(".json")) : [];
+  for (const file of graphFiles) {
+    try { JSON.parse(readFileSync(path.join(graphDir, file), "utf8")); } catch { warn(at, `invalid graph JSON: graphs/${file}`); }
+    const diagram = path.join(reportDir, "diagrams", `${path.basename(file, ".json")}.mmd`);
+    if (!existsSync(diagram)) warn(at, `successful graph has no overview diagram: ${path.basename(diagram)}`);
+  }
+  const projectsPath = path.join(reportDir, "projects.json");
+  if (coverage && existsSync(projectsPath)) {
+    try {
+      const discovery = JSON.parse(readFileSync(projectsPath, "utf8"));
+      const projects = Array.isArray(discovery) ? discovery : discovery.projects;
+      const [successful, selected] = coverage.slice(1).map(Number);
+      if (!Array.isArray(projects)) fail(at, "projects.json must contain a projects array");
+      else if (selected !== projects.length) fail(at, `Architecture coverage selects ${selected} of the ${projects.length} discovered projects`);
+      if (successful > graphFiles.length) fail(at, `Architecture coverage claims ${successful} analysed project(s) over ${graphFiles.length} graph(s)`);
+      else if (successful < graphFiles.length) warn(at, `Architecture coverage claims ${successful} analysed project(s) under ${graphFiles.length} graph(s)`);
+    } catch { fail(at, "projects.json is invalid JSON"); }
+  }
+}
+
+const display = path.relative(repo, report) || path.basename(report);
+for (const warning of warnings) console.error(`${display}:${warning.line}: warning: ${warning.message}`);
+if (errors.length) {
+  for (const error of errors) console.error(`${display}:${error.line}: ${error.message}`);
+  process.exitCode = 1;
+} else {
+  console.log(`Validated ${display}: ${issueCount} issue(s), ${warnings.length} warning(s).`);
+}