ts-reviewer 3.0.0 → 3.1.0

package/README.md

@@ -84,6 +84,8 @@ Audit the codebase for security and type safety problems
 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.
 
+The analysis passes run in waves. `--agents N` sets how many run at once (default 3; `--agents 1` runs them one at a time in the main agent). Each pass writes its own findings file under `code-smells/passes/`, and the queue in `code-smells/passes/queue.md` tracks which passes are done, so an interrupted scan does not lose finished work.
+
 #### Domain flags
 
 By default, only the nine core domains run. Use flags to control which domains are active:
@@ -197,6 +199,12 @@ cnlp/                                 # the CNL-P format the skill files are wri
 
 ts-reviewer/
 ├── SKILL.md                          # Main skill file — mode routing, workflow orchestration
+├── tools/                            # Mechanical pre-pass and report validator — plain Node, no dependencies
+│   ├── discover-projects.mjs         # Finds the TypeScript projects and their source roots
+│   ├── co-change.mjs                 # Git co-change pairs across directory boundaries
+│   ├── run-cruise.mjs                # dependency-cruiser graphs, metrics, and Mermaid diagrams per project
+│   ├── classify-run.mjs              # Reads a tool run by its output, not its exit code
+│   └── validate-report.mjs           # Checks code-smells/report.md against the report contract
 └── references/
     ├── type-safety.md                # Checklist: any, unknown, casts, !, exhaustiveness, branded types
     ├── security.md                   # Checklist: trust boundaries, injection, SSRF, pollution, ReDoS
@@ -228,7 +236,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.
@@ -240,26 +248,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, 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/`.
-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.
+2. **Diagnostics** — runs `tsc --noEmit`, linter, and LSP diagnostics (if available); 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 judge the candidates against the active checklists, 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.
+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
 
 - **Add `code-smells/` to `.gitignore`** — it contains review artifacts, not source code.
 
+- **Resume an interrupted scan** — run the same scan again. When `code-smells/passes/queue.md` exists, the skill asks whether to resume (finished passes are skipped, cached `tsc` and linter output is reused on the same commit) or restart from scratch.
+
+- **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.
+
 - **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/report.md` as its work plan, you can delete issues you don't want fixed, change severities, or add notes before running fix.

package/package.json

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

package/ts-reviewer/SKILL.md

@@ -23,7 +23,7 @@ target_stack:
 - a pattern below this stack is a finding, and a feature above it is never recommended
 
 inputs:
-- the request, which carries the run mode, the domain set, and the scope mode
+- the request, which carries the run mode, the domain set, the scope mode, and the wave size
 - the project `tsconfig.json`, `package.json`, and linter config
 - the reference checklists under `references/`
 
@@ -61,9 +61,13 @@ 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
+- do not start a wave before every pass of the previous wave is marked `done`, `pending`, or `failed` in the queue
+- do not read a finding from an agent reply: the `.jsonl` file under `code-smells/passes/` is the record, and a reply holds 1 line
 
 outputs:
 - `code-smells/report.md` in the project root: the scan report, and the work plan fix reads
+- `code-smells/passes/`: the pass queue, the cached diagnostics, and 1 JSONL file per pass
 - `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
@@ -119,50 +123,65 @@ workflow:
 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. map the project tree in full, whatever the scope mode
-7. read `tsconfig.json` and `references/tsconfig.md`, then audit the config flags
-8. detect monorepo workspaces in `package.json` and `pnpm-workspace.yaml`, and every further tsconfig
-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 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 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. 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
+6. ask once whether to resume or restart when `code-smells/passes/queue.md` exists, and delete `code-smells/passes/` on restart
+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 `references/tsconfig.md`, then audit the config flags
+10. detect monorepo workspaces in `package.json` and `pnpm-workspace.yaml`, and every further tsconfig
+11. audit the config that governs the files in scope, and name that config in the summary
+12. read the linter config: `eslint.config.*`, `.eslintrc.*`, `biome.json`, `deno.json`
+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. when Architecture is active, inspect local Knip and dependency-cruiser binaries and ask once before running either missing tool through pinned-major `npx -y`
+16. collect the context files named in `scope:` when the scope mode is scoped
+17. identify feature slices and public entry points when Architecture is active, leaving graph discovery to its mechanical pre-pass
+18. collect machine-readable dependency rules and prose from ADR directories, `ARCHITECTURE.md`, README, and `CONTRIBUTING.md`
+19. run `npx tsc --noEmit 2>&1 | head -200` over the full project into `code-smells/passes/tsc.log`, and report only the errors in the scoped files
+20. run the linter into `code-smells/passes/lint.json`: `npx eslint [files] --format json` or `npx biome check [files] --reporter json`
+21. reuse `tsc.log` and `lint.json` on a resume when the queue `HEAD` matches and the tree is clean, and rerun both otherwise
+22. query the TypeScript LSP over MCP when it is reachable, then merge and deduplicate against the compiler output
+23. triage every compiler and linter diagnostic through `severity_mapping`
+24. read the reference file named in `domains` before each analysis pass
+25. run the mechanical pre-pass in `references/architecture.md` when Architecture is active, passing the approved tool decision and scoped base
+26. report the discovery summary in the shape of `discovery_summary`, including skipped and clean mechanical results
+27. build the pass list: 1 pass per active domain, split by directory when scoped files > 20, with the shared types visible to every pass
+28. write `code-smells/passes/queue.md` in the shape of `pass_queue`, in its domain order, and skip a pass marked `done` on a resume
+29. run the pending passes in waves of the wave size, as sub-agents shaped by `subagent_template`, or in the main agent when the wave size is 1
+30. wait for every agent of a wave, then mark each pass `done` when the last line of its file is the `done` line, and `pending` otherwise
+31. mark a pass `failed` after 2 attempts without a `done` line, name it in the discovery summary, and report its domain as not run
+32. read the findings of every `done` pass from its `.jsonl` file before the re-read below
+33. re-read the exact lines in the current file state before a finding enters the report
+34. 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
+35. downgrade a flagged non-High pattern that appears 5+ times across the codebase by 1 level, and report it once as a Recurring Pattern
+36. boost a finding carrying `in_diff: true` by 1 level in a scoped mode, and mark it `High [boosted, was Medium — new code]`
+37. deduplicate the findings on the same file, line, and issue, keeping 1
+38. merge the findings 2 domains raise on the same file and line into 1 entry attributing both categories, at the higher severity
+39. consolidate 3+ identical issues into 1 Recurring Pattern entry
+40. 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
+41. write `code-smells/report.md` in the shape of `report_format`
+42. 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
+```
+43. correct every named error and retry with report validation iterations <= 2
+44. 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
+45. sort by severity group, then category, then file path, and place `in_diff: true` before pre-existing in a scoped mode
+46. show the top 10 and summarize the rest in a table when Medium and Low together hold more than 15 issues
+47. recommend that the operator adds `code-smells/` to `.gitignore`: it holds review artifacts
+48. read `references/fix-workflow.md` before fix mode executes: it holds the complete protocol
+49. detect the test runner and run the baseline tests
+50. fix the issues file by file, and run `tsc --noEmit` after each file
+51. run the linter and fix the lint errors it reports
+52. run the full test suite, compare it against the baseline, and fix the regressions
+53. repeat the compiler, linter, and test verification with verification iterations <= 5
+54. rerun the Architecture mechanical pre-pass on the fixed tree when Architecture is active
+55. update `code-smells/report.md`: remove what is fixed, mark what failed
+56. show the scan summary in auto mode, and ask the operator whether to proceed with the fix
+57. re-scan after the fix in auto mode with full scan-fix cycles <= 2, and stop when issues persist after the second
+58. delete `code-smells/report.md` and report success when every issue is fixed
+59. retain the remaining `code-smells/` artifacts, state what they contain, and remove them only after the operator confirms
 
 scope_commands:
 ```bash
@@ -223,8 +242,11 @@ 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)
+Agents per wave: <N>
+Resumed: <done>/<total> passes from code-smells/passes/queue.md, or no
 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>
@@ -242,6 +264,9 @@ Read the reference checklist: [REFERENCE_PATH]
 Review these files: [FILE_LIST]
 Context files (read-only, do NOT report issues): [CONTEXT_FILE_LIST]
 Scope mode: [full|uncommitted|branch|commits:N]
+Write every finding as 1 JSONL line to: [OUTPUT_PATH]
+Append 1 last line when every file is reviewed: {"done": true, "findings": N, "files": M}
+Reply with 1 line: the pass id, the findings count, the files count. The file is the result; the reply is not.
 
 Output JSONL, one object per line:
 {
@@ -259,7 +284,31 @@ Output JSONL, one object per line:
 }
 ```
 
+pass_queue:
+- `--agents N` in the request sets the wave size, and the default is 3
+- `--agents 1` runs 1 pass at a time in the main agent, with no sub-agent
+- the pass id is the domain slug, or `<domain slug>.<directory slug>` for a split pass
+- the domain order: Security, Type Safety, Async Patterns, Error Handling, Boundary Validation, Config, Dependency Hygiene, Modernization, Code Quality, Architecture
+- a status is `pending`, `done`, or `failed`, and `Attempts` counts the waves the pass ran in
+```markdown
+# Pass queue
+
+HEAD: <sha>
+Scope: <mode>
+Agents per wave: <N>
+
+| Pass | Domain | Files | Status | Attempts | Findings |
+|---|---|---|---|---|---|
+| security | Security | 42 | done | 1 | 7 |
+| type-safety.src-auth | Type Safety | 12 | pending | 1 | |
+```
+
 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 +317,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 +325,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 +336,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 +347,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).`);
+}