@pyreon/cli 0.16.0 → 0.18.0

package/lib/index.js

@@ -1,7 +1,11 @@
 #!/usr/bin/env node
 import * as fs from "node:fs";
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
 import * as path from "node:path";
-import { auditIslands, auditSsg, auditTestEnvironment, detectReactPatterns, formatIslandAudit, formatSsgAudit, formatTestAudit, generateContext as generateContext$1, hasReactPatterns, migrateReactCode } from "@pyreon/compiler";
+import { join, relative } from "node:path";
+import { auditIslands, auditSsg, auditTestEnvironment, detectPyreonPatterns, detectReactPatterns, generateContext as generateContext$1, hasPyreonPatterns, hasReactPatterns, migrateReactCode } from "@pyreon/compiler";
+import { execFileSync } from "node:child_process";
+import { allRules, lint } from "@pyreon/lint";
 
 //#region src/context.ts
 /**
@@ -33,70 +37,585 @@ function ensureGitignore(cwd) {
 }
 
 //#endregion
-//#region src/doctor.ts
+//#region src/doctor/gates/audit-types.ts
 /**
-* pyreon doctor — project-wide health check for AI-friendly development
+* audit-types gate — programmatic API.
 *
-* Runs a pipeline of checks:
-*  1. React pattern detection (imports, hooks, JSX attributes)
-*  2. Import source validation (@pyreon/* vs react/vue)
-*  3. Common Pyreon mistakes (signal without call, key vs by, etc.)
+* Catches typed-but-unimplemented public-interface fields. Walks every
+* exported interface in each high-risk package and counts non-type
+* references; fields with zero references are flagged HIGH. Catches the
+* 0.14.0-class bug (`mode: "ssg"` typed but never read by runtime).
 *
-* Output modes:
-*  - Human-readable (default): colored terminal output
-*  - JSON (--json): structured output for AI agent consumption
-*  - CI (--ci): exits with code 1 on any error
+* **Implementation note (subprocess adapter).** This gate invokes the
+* standalone `scripts/audit-types.ts` script via `--json --all` and
+* parses the output. The script is 476 lines of mature AST-walking
+* logic with its own test suite; rather than surgically extract it
+* mid-shape, the adapter shape keeps PR 1 tractable and lets PR 2's
+* aggregation layer consume the same `Finding[]` shape as the other
+* gates. Adapter cost is ~50ms subprocess overhead — noise within the
+* gate's 1-5s scan runtime. Full extraction is a deferred follow-up
+* (the doctor aggregator doesn't care HOW the gate runs).
+*/
+const mapSeverity = (s) => {
+	switch (s) {
+		case "HIGH": return "error";
+		case "MEDIUM": return "warning";
+		case "LOW": return "info";
+		case "OK": return null;
+	}
+};
+/**
+* Pure parse-and-map function — public so tests can exercise the JSON
+* → `Finding[]` translation without spawning a subprocess. Returns the
+* findings plus the count of packages scanned. Exported as `_internal`
+* (unstable API surface — may move when PR 2 lands the aggregator).
+*/
+const _parseAuditTypesOutput = (raw, cwd) => {
+	const results = JSON.parse(raw);
+	const findings = [];
+	for (const r of results) for (const f of r.findings) {
+		const severity = mapSeverity(f.severity);
+		if (severity === null) continue;
+		findings.push({
+			category: "architecture",
+			severity,
+			code: `audit-types/typed-but-unimplemented-${f.severity.toLowerCase()}`,
+			gate: "audit-types",
+			message: `${f.package}: \`${f.interface}.${f.field}\` is typed in the public API but has ${f.refCount} non-type reference(s) in the package — likely typed-but-unimplemented.`,
+			location: {
+				path: join(cwd, f.declaredIn),
+				relPath: f.declaredIn,
+				line: f.declaredLine
+			}
+		});
+	}
+	return {
+		findings,
+		scanned: results.length
+	};
+};
+const runAuditTypesGate = async (opts) => {
+	const start = Date.now();
+	const findings = [];
+	const args = [
+		"run",
+		join(opts.cwd, "scripts/audit-types.ts"),
+		"--json"
+	];
+	if (opts.packages && opts.packages.length > 0) args.push(...opts.packages);
+	else args.push("--all");
+	let scannedPackages = 0;
+	try {
+		const parsed = _parseAuditTypesOutput(execFileSync(opts.bun ?? "bun", args, {
+			cwd: opts.cwd,
+			encoding: "utf8",
+			stdio: [
+				"pipe",
+				"pipe",
+				"pipe"
+			],
+			maxBuffer: 16 * 1024 * 1024
+		}), opts.cwd);
+		findings.push(...parsed.findings);
+		scannedPackages = parsed.scanned;
+	} catch (err) {
+		findings.push({
+			category: "architecture",
+			severity: "error",
+			code: "audit-types/gate-failed",
+			gate: "audit-types",
+			message: `audit-types gate failed to run: ${err.message}`
+		});
+	}
+	return {
+		gate: "audit-types",
+		category: "architecture",
+		findings,
+		meta: {
+			scanned: scannedPackages,
+			elapsedMs: Date.now() - start
+		}
+	};
+};
+
+//#endregion
+//#region src/doctor/gates/bundle-budgets.ts
+/**
+* bundle-budgets gate — programmatic API.
+*
+* Locks the gzipped main-entry size of every published `@pyreon/*`
+* package against `scripts/bundle-budgets.json` (current + 25% headroom).
+* Three classes of finding land here:
 *
-* Fix mode (--fix): auto-applies safe transforms via migrateReactCode
+*   1. **violations** — package bundles past its budget (real regression).
+*      Severity: `error`. Code: `bundle-budgets/over-budget`.
+*   2. **missing** — package has no entry in `bundle-budgets.json` yet
+*      (new published package — author needs to commit a budget).
+*      Severity: `warning`. Code: `bundle-budgets/missing-budget`.
+*   3. **failures** — the bundler couldn't measure a package (unresolved
+*      transitive dep, build artifact issue). Severity: `error`. Code:
+*      `bundle-budgets/bundle-failed`. Surfaced as a finding rather than
+*      silently dropped — same lesson as PR #434.
+*
+* **Implementation note (subprocess adapter).** This gate invokes the
+* standalone `scripts/check-bundle-budgets.ts` script via `--json` and
+* parses the output. The script is 466 lines of bundler orchestration
+* + AST-walking dep collection logic; extracting it surgically into a
+* pure function carries too much risk for PR 1. The adapter shape lets
+* the doctor aggregator consume the same `Finding[]` shape as the other
+* gates; full extraction is a deferred follow-up (`pyreon doctor`
+* doesn't care HOW the gate runs — only that it returns `GateResult`).
+*
+* The full-bundle measurement is the slowest gate (~15-30s against
+* 50+ published packages). Doctor's default fast mode opts this gate
+* OUT; `--full` enables it.
 */
-async function doctor(options) {
-	const startTime = performance.now();
-	const result = runChecks(collectSourceFiles(options.cwd), options);
-	const elapsed = Math.round(performance.now() - startTime);
-	if (options.json) printJson(result);
-	else printHuman(result, elapsed);
-	if (options.auditTests) {
-		const auditResult = auditTestEnvironment(options.cwd);
-		if (options.json) {
-			console.log("");
-			console.log(JSON.stringify({ testAudit: auditResult }, null, 2));
-		} else {
-			console.log("");
-			console.log(formatTestAudit(auditResult, { minRisk: options.auditMinRisk ?? "medium" }));
-			console.log("");
+const formatKB = (bytes) => `${(bytes / 1024).toFixed(2)} KB`;
+/**
+* Pure parse-and-map function — public so tests can exercise the JSON
+* → `Finding[]` translation without spawning a subprocess. Returns the
+* findings plus the count of packages scanned (measured + failures).
+* Exported as `_internal` (unstable API surface — may move when PR 2
+* lands the aggregator).
+*/
+const _parseBundleBudgetsOutput = (raw, cwd) => {
+	const result = JSON.parse(raw);
+	const findings = [];
+	const budgetsRelPath = "scripts/bundle-budgets.json";
+	const budgetsPath = join(cwd, budgetsRelPath);
+	for (const v of result.violations) findings.push({
+		category: "performance",
+		severity: "error",
+		code: "bundle-budgets/over-budget",
+		gate: "bundle-budgets",
+		message: `${v.name}: ${formatKB(v.current)} > budget ${formatKB(v.budget)} (over by ${formatKB(v.overBy)}, +${v.overByPct.toFixed(1)}%). If growth is intentional, bump the value in scripts/bundle-budgets.json — the bump itself is the PR signal.`,
+		location: {
+			path: budgetsPath,
+			relPath: budgetsRelPath
+		},
+		fix: `Run \`bun run check-bundle-budgets --update\` to regenerate budgets after intentional growth.`
+	});
+	for (const m of result.missing) findings.push({
+		category: "performance",
+		severity: "warning",
+		code: "bundle-budgets/missing-budget",
+		gate: "bundle-budgets",
+		message: `${m.name}: ${formatKB(m.current)} (no budget entry). New published package?`,
+		location: {
+			path: budgetsPath,
+			relPath: budgetsRelPath
+		},
+		fix: `Run \`bun run check-bundle-budgets --update\` and review the diff.`
+	});
+	for (const f of result.failures) findings.push({
+		category: "performance",
+		severity: "error",
+		code: "bundle-budgets/bundle-failed",
+		gate: "bundle-budgets",
+		message: `${f.name}: bundle failed — ${f.error.split("\n")[0]}. Likely an unresolved third-party dep that the auto-external scan missed.`
+	});
+	return {
+		findings,
+		scanned: result.measured.length + result.failures.length
+	};
+};
+const runBundleBudgetsGate = async (opts) => {
+	const start = Date.now();
+	const findings = [];
+	const scriptPath = join(opts.cwd, "scripts/check-bundle-budgets.ts");
+	let scannedPackages = 0;
+	try {
+		let out;
+		try {
+			out = execFileSync(opts.bun ?? "bun", [
+				"run",
+				scriptPath,
+				"--json"
+			], {
+				cwd: opts.cwd,
+				encoding: "utf8",
+				stdio: [
+					"pipe",
+					"pipe",
+					"pipe"
+				],
+				maxBuffer: 16 * 1024 * 1024
+			});
+		} catch (err) {
+			const e = err;
+			if (e.stdout) out = typeof e.stdout === "string" ? e.stdout : e.stdout.toString("utf8");
+			else throw err;
 		}
+		const parsed = _parseBundleBudgetsOutput(out, opts.cwd);
+		findings.push(...parsed.findings);
+		scannedPackages = parsed.scanned;
+	} catch (err) {
+		findings.push({
+			category: "performance",
+			severity: "error",
+			code: "bundle-budgets/gate-failed",
+			gate: "bundle-budgets",
+			message: `bundle-budgets gate failed to run: ${err.message}`
+		});
 	}
-	if (options.checkIslands) {
-		const islandsResult = auditIslands(options.cwd);
-		if (options.json) {
-			console.log("");
-			console.log(JSON.stringify({ islandAudit: islandsResult }, null, 2));
-		} else {
-			console.log("");
-			console.log(formatIslandAudit(islandsResult));
-			console.log("");
+	return {
+		gate: "bundle-budgets",
+		category: "performance",
+		findings,
+		meta: {
+			scanned: scannedPackages,
+			elapsedMs: Date.now() - start
+		}
+	};
+};
+
+//#endregion
+//#region src/doctor/gates/distribution.ts
+/**
+* Distribution-hygiene gate — programmatic API.
+*
+* Two static invariants every published `@pyreon/*` package must hold:
+*   1. `sideEffects` field declared (bundler tree-shaking)
+*   2. `!lib/** /*.map` excluded from `files` array (no source-map ship)
+*
+* Plus a live `npm pack --dry-run` probe of `@pyreon/reactivity` to
+* verify the exclusion actually works at publish time (the `files`
+* field is technically right but npm's interpretation can diverge).
+*
+* Pure function — the standalone script `scripts/check-distribution.ts`
+* is a thin wrapper that calls this and formats the output.
+*
+* Mirrors the script logic 1:1 — no behavior change, just makes the
+* findings programmatically consumable by `pyreon doctor` aggregation
+* (PR 2).
+*/
+const findPackages = (repoRoot) => {
+	const result = [];
+	const packagesRoot = join(repoRoot, "packages");
+	if (!existsSync(packagesRoot)) return result;
+	for (const cat of readdirSync(packagesRoot)) {
+		const catDir = join(packagesRoot, cat);
+		let pkgs;
+		try {
+			pkgs = readdirSync(catDir);
+		} catch {
+			continue;
+		}
+		for (const pkg of pkgs) {
+			const pkgDir = join(catDir, pkg);
+			const pjPath = join(pkgDir, "package.json");
+			if (!existsSync(pjPath)) continue;
+			let pj;
+			try {
+				pj = JSON.parse(readFileSync(pjPath, "utf8"));
+			} catch {
+				continue;
+			}
+			if (pj.private) continue;
+			if (typeof pj.name !== "string") continue;
+			result.push({
+				name: pj.name,
+				dir: pkgDir,
+				pj
+			});
 		}
 	}
-	if (options.checkSsg) {
-		const ssgResult = auditSsg(options.cwd);
-		if (options.json) {
-			console.log("");
-			console.log(JSON.stringify({ ssgAudit: ssgResult }, null, 2));
-		} else {
-			console.log("");
-			console.log(formatSsgAudit(ssgResult));
-			console.log("");
+	return result;
+};
+/**
+* Pure parse-and-emit function for the `npm pack --dry-run` JSON
+* output. Exported as `_internal` so tests can exercise the .map-
+* detection + finding emission path without spawning the live npm
+* subprocess — under CI parallel load the real probe runs 100s+,
+* tripping the per-test timeout. Returns the finding (if any) for
+* the caller to push onto the gate's findings array.
+*/
+const _detectMapsInPackOutput = (raw, cwd, probe, probePackage) => {
+	const maps = (JSON.parse(raw)[0]?.files.map((f) => f.path) ?? []).filter((f) => f.endsWith(".map"));
+	if (maps.length === 0) return null;
+	return {
+		category: "architecture",
+		severity: "error",
+		code: "distribution/tarball-contains-map",
+		gate: "distribution",
+		message: `${probePackage}: npm pack --dry-run reported ${maps.length} .map file(s) in the would-be-published tarball: ${maps.slice(0, 3).join(", ")}${maps.length > 3 ? ", …" : ""}`,
+		location: {
+			path: join(probe.dir, "package.json"),
+			relPath: relative(cwd, join(probe.dir, "package.json"))
+		}
+	};
+};
+/**
+* Run the distribution-hygiene gate. Returns findings + metadata.
+*
+* @example
+* const result = await runDistributionGate({ cwd: process.cwd() })
+* if (result.findings.length > 0) process.exit(1)
+*/
+const runDistributionGate = async (opts) => {
+	const start = Date.now();
+	const probePackage = opts.probePackage ?? "@pyreon/reactivity";
+	const findings = [];
+	const packages = findPackages(opts.cwd);
+	for (const p of packages) {
+		if (p.pj.sideEffects === void 0) findings.push({
+			category: "architecture",
+			severity: "error",
+			code: "distribution/missing-sideEffects",
+			gate: "distribution",
+			message: `${p.name} package.json must declare \`sideEffects\` (use \`false\` for pure libraries, an array of paths for entry-point side effects) — required for bundler tree-shaking.`,
+			location: {
+				path: join(p.dir, "package.json"),
+				relPath: relative(opts.cwd, join(p.dir, "package.json"))
+			},
+			fix: "Add `\"sideEffects\": false` to package.json"
+		});
+		if (Array.isArray(p.pj.files) && p.pj.files.includes("lib")) {
+			if (!p.pj.files.includes("!lib/**/*.map")) findings.push({
+				category: "architecture",
+				severity: "error",
+				code: "distribution/missing-map-exclusion",
+				gate: "distribution",
+				message: `${p.name} package.json \`files\` must include \`"!lib/**/*.map"\` to exclude source maps from the published tarball.`,
+				location: {
+					path: join(p.dir, "package.json"),
+					relPath: relative(opts.cwd, join(p.dir, "package.json"))
+				},
+				fix: "Add `\"!lib/**/*.map\"` to the `files` array"
+			});
 		}
 	}
-	return result.summary.totalErrors;
-}
-const sourceExtensions = new Set([
+	if (!opts.skipPackProbe) {
+		const probe = packages.find((p) => p.name === probePackage);
+		if (probe) try {
+			const finding = _detectMapsInPackOutput(execFileSync("npm", [
+				"pack",
+				"--dry-run",
+				"--json"
+			], {
+				cwd: probe.dir,
+				encoding: "utf8",
+				stdio: [
+					"pipe",
+					"pipe",
+					"pipe"
+				]
+			}), opts.cwd, probe, probePackage);
+			if (finding) findings.push(finding);
+		} catch {}
+	}
+	return {
+		gate: "distribution",
+		category: "architecture",
+		findings,
+		meta: {
+			scanned: packages.length,
+			elapsedMs: Date.now() - start
+		}
+	};
+};
+
+//#endregion
+//#region src/doctor/gates/doc-claims.ts
+/**
+* Doc-claims gate — programmatic API.
+*
+* Catches numeric-drift between human-written docs and the underlying
+* source of truth. Recurring failure mode: a hand-quoted count
+* ("34 signal-based hooks…") appears in 3-5 places; one bumps when a
+* new hook lands, the others don't. Audit caught the README claiming
+* 16 vs actual 34 — drift that shipped to users for weeks.
+*
+* Pure function — `scripts/check-doc-claims.ts` wraps this for the
+* standalone CLI invocation.
+*/
+const countHookExports = (repoRoot) => {
+	const indexPath = join(repoRoot, "packages/fundamentals/hooks/src/index.ts");
+	if (!existsSync(indexPath)) return 0;
+	const matched = readFileSync(indexPath, "utf8").matchAll(/^export \{ (?:default as )?(use[A-Z][a-zA-Z]+) \}/gm);
+	const names = /* @__PURE__ */ new Set();
+	for (const [, name] of matched) if (name) names.add(name);
+	return names.size;
+};
+const countDocPages = (repoRoot) => {
+	const docsDir = join(repoRoot, "docs");
+	if (!existsSync(docsDir)) return 0;
+	let count = 0;
+	const walk = (dir) => {
+		let entries;
+		try {
+			entries = readdirSync(dir);
+		} catch {
+			return;
+		}
+		for (const name of entries) {
+			if (name === "node_modules" || name === "cache" || name === "dist" || name.startsWith(".")) continue;
+			const full = join(dir, name);
+			let isDir = false;
+			try {
+				isDir = statSync(full).isDirectory();
+			} catch {
+				continue;
+			}
+			if (isDir) walk(full);
+			else if (name.endsWith(".md")) count++;
+		}
+	};
+	walk(docsDir);
+	return count;
+};
+const checks = [{
+	name: "hook export count",
+	codeId: "hook-count",
+	actual: countHookExports,
+	claims: [
+		{
+			file: "packages/fundamentals/hooks/README.md",
+			pattern: /^(\d+) signal-based reactive utilities/m
+		},
+		{
+			file: "packages/fundamentals/hooks/src/manifest.ts",
+			pattern: /'(\d+) signal-based hooks:/
+		},
+		{
+			file: "packages/fundamentals/hooks/src/manifest.ts",
+			pattern: /Signal-based hooks for Pyreon — (\d+) reactive primitives/
+		},
+		{
+			file: "CLAUDE.md",
+			pattern: /\| `@pyreon\/hooks` *\| (\d+) signal-based hooks/,
+			rejectHedged: /\| `@pyreon\/hooks` *\| (\d+)\+ signal-based hooks/
+		},
+		{
+			file: "CLAUDE.md",
+			pattern: /^- (\d+) signal-based hooks across 6 categories/m
+		},
+		{
+			file: "docs/docs/index.md",
+			pattern: /\| (\d+) signal-based hooks for common UI patterns/
+		}
+	]
+}, {
+	name: "doc page count",
+	codeId: "doc-count",
+	actual: countDocPages,
+	claims: [{
+		file: "CLAUDE.md",
+		pattern: /(\d+) doc pages covering all packages/
+	}]
+}];
+const runDocClaimsGate = async (opts) => {
+	const start = Date.now();
+	const findings = [];
+	if (!checks.some((c) => c.claims.some((cl) => existsSync(join(opts.cwd, cl.file))))) return {
+		gate: "doc-claims",
+		category: "documentation",
+		findings: [],
+		meta: {
+			scanned: 0,
+			elapsedMs: Date.now() - start,
+			skipped: true,
+			skipReason: "no claim sites found in this project (gate targets Pyreon monorepo paths)"
+		}
+	};
+	for (const check of checks) {
+		const actual = check.actual(opts.cwd);
+		for (const claim of check.claims) {
+			const filePath = join(opts.cwd, claim.file);
+			const relPath = claim.file;
+			if (!existsSync(filePath)) {
+				findings.push({
+					category: "documentation",
+					severity: "error",
+					code: `doc-claims/${check.codeId}-file-missing`,
+					gate: "doc-claims",
+					message: `${check.name}: claim file ${claim.file} not found (claim may have been deleted or moved). Actual: ${actual}.`,
+					location: {
+						path: filePath,
+						relPath
+					}
+				});
+				continue;
+			}
+			const content = readFileSync(filePath, "utf8");
+			if (claim.rejectHedged) {
+				const hedged = content.match(claim.rejectHedged);
+				if (hedged?.[1]) {
+					findings.push({
+						category: "documentation",
+						severity: "error",
+						code: `doc-claims/${check.codeId}-hedged`,
+						gate: "doc-claims",
+						message: `${check.name}: rejected hedged claim "${hedged[1]}+" in ${claim.file} — write the exact count instead. Actual: ${actual}.`,
+						location: {
+							path: filePath,
+							relPath
+						},
+						fix: `Replace "${hedged[1]}+" with "${actual}"`
+					});
+					continue;
+				}
+			}
+			const claimedRaw = content.match(claim.pattern)?.[1];
+			if (!claimedRaw) {
+				findings.push({
+					category: "documentation",
+					severity: "warning",
+					code: `doc-claims/${check.codeId}-pattern-miss`,
+					gate: "doc-claims",
+					message: `${check.name}: pattern not found in ${claim.file} (claim was likely deleted or rephrased). Actual: ${actual}.`,
+					location: {
+						path: filePath,
+						relPath
+					}
+				});
+				continue;
+			}
+			const claimed = parseInt(claimedRaw, 10);
+			if (claimed !== actual) findings.push({
+				category: "documentation",
+				severity: "error",
+				code: `doc-claims/${check.codeId}-drift`,
+				gate: "doc-claims",
+				message: `${check.name}: ${claim.file} claims ${claimed}, actual ${actual}.`,
+				location: {
+					path: filePath,
+					relPath
+				},
+				fix: `Update the claim in ${claim.file} from ${claimed} to ${actual}`
+			});
+		}
+	}
+	return {
+		gate: "doc-claims",
+		category: "documentation",
+		findings,
+		meta: {
+			scanned: checks.reduce((n, c) => n + c.claims.length, 0),
+			elapsedMs: Date.now() - start
+		}
+	};
+};
+
+//#endregion
+//#region src/doctor/utils/walk.ts
+/**
+* Shared source-file walker for the per-file scanning gates
+* (react-patterns, pyreon-patterns).
+*
+* The walker skips the standard non-source dirs (`node_modules`,
+* `dist`, `lib`, `.git`, etc.) and matches `.ts` / `.tsx` / `.js` /
+* `.jsx`. It's a thin wrapper around the original `collectSourceFiles`
+* that lived in `doctor.ts` pre-PR-2; extracted here so any gate can
+* use it without import-cycling through the doctor module.
+*/
+const SOURCE_EXTENSIONS = new Set([
 	".tsx",
 	".jsx",
 	".ts",
 	".js"
 ]);
-const sourceIgnoreDirs = new Set([
+const IGNORE_DIRS = new Set([
 	"node_modules",
 	"dist",
 	"lib",
@@ -105,11 +624,11 @@ const sourceIgnoreDirs = new Set([
 	".next",
 	"build"
 ]);
-function shouldSkipDirEntry(entry) {
+const shouldSkipDirEntry = (entry) => {
 	if (!entry.isDirectory()) return false;
-	return entry.name.startsWith(".") || sourceIgnoreDirs.has(entry.name);
-}
-function walkSourceFiles(dir, results) {
+	return entry.name.startsWith(".") || IGNORE_DIRS.has(entry.name);
+};
+const walk = (dir, results) => {
 	let entries;
 	try {
 		entries = fs.readdirSync(dir, { withFileTypes: true });
@@ -119,125 +638,892 @@ function walkSourceFiles(dir, results) {
 	for (const entry of entries) {
 		if (shouldSkipDirEntry(entry)) continue;
 		const fullPath = path.join(dir, entry.name);
-		if (entry.isDirectory()) walkSourceFiles(fullPath, results);
-		else if (entry.isFile() && sourceExtensions.has(path.extname(entry.name))) results.push(fullPath);
+		if (entry.isDirectory()) walk(fullPath, results);
+		else if (entry.isFile() && SOURCE_EXTENSIONS.has(path.extname(entry.name))) results.push(fullPath);
 	}
-}
-function collectSourceFiles(cwd) {
+};
+const collectSourceFiles = (cwd) => {
 	const results = [];
-	walkSourceFiles(cwd, results);
+	walk(cwd, results);
 	return results;
-}
-function checkFileWithFix(file, relPath) {
-	let code;
-	try {
-		code = fs.readFileSync(file, "utf-8");
-	} catch {
-		return {
-			result: null,
-			fixCount: 0
-		};
+};
+
+//#endregion
+//#region src/doctor/gates/react-patterns.ts
+/**
+* react-patterns gate — wraps `@pyreon/compiler:detectReactPatterns`.
+*
+* Catches "coming from React" mistakes: `useState` / `useEffect`,
+* `className` / `htmlFor`, `onChange` on inputs, React-package
+* imports, etc. The detector is already used standalone by the
+* pre-PR-2 `pyreon doctor` legacy path; this adapter just emits its
+* findings in the unified `Finding[]` shape so the v2 aggregator can
+* fold them into the score.
+*
+* `--fix` mode delegates to `migrateReactCode` and reports BOTH the
+* applied changes (as `info` findings) AND any residual diagnostics
+* the migration didn't auto-resolve.
+*/
+const runReactPatternsGate = async (opts) => {
+	const start = Date.now();
+	const findings = [];
+	const files = collectSourceFiles(opts.cwd);
+	for (const file of files) {
+		let code;
+		try {
+			code = fs.readFileSync(file, "utf-8");
+		} catch {
+			continue;
+		}
+		if (!hasReactPatterns(code)) continue;
+		const relPath = path.relative(opts.cwd, file);
+		if (opts.fix) {
+			const migrated = migrateReactCode(code, relPath);
+			if (migrated.changes.length > 0) {
+				fs.writeFileSync(file, migrated.code, "utf-8");
+				for (const ch of migrated.changes) findings.push({
+					category: "correctness",
+					severity: "info",
+					code: `react-patterns/auto-fixed-${ch.type}`,
+					gate: "react-patterns",
+					message: `Auto-fixed: ${ch.description}`,
+					location: {
+						path: file,
+						relPath,
+						line: ch.line
+					}
+				});
+			}
+			const remaining = detectReactPatterns(migrated.code, relPath);
+			for (const diag of remaining) findings.push({
+				category: "correctness",
+				severity: diag.fixable ? "warning" : "error",
+				code: `react-patterns/${diag.code}`,
+				gate: "react-patterns",
+				message: diag.message,
+				location: {
+					path: file,
+					relPath,
+					line: diag.line,
+					column: diag.column
+				},
+				fix: diag.suggested,
+				fixable: diag.fixable
+			});
+		} else {
+			const diagnostics = detectReactPatterns(code, relPath);
+			for (const diag of diagnostics) findings.push({
+				category: "correctness",
+				severity: diag.fixable ? "warning" : "error",
+				code: `react-patterns/${diag.code}`,
+				gate: "react-patterns",
+				message: diag.message,
+				location: {
+					path: file,
+					relPath,
+					line: diag.line,
+					column: diag.column
+				},
+				fix: diag.suggested,
+				fixable: diag.fixable
+			});
+		}
 	}
-	if (!hasReactPatterns(code)) return {
-		result: null,
-		fixCount: 0
-	};
-	const migrated = migrateReactCode(code, relPath);
-	if (migrated.changes.length > 0) fs.writeFileSync(file, migrated.code, "utf-8");
-	const remaining = detectReactPatterns(migrated.code, relPath);
-	if (remaining.length > 0 || migrated.changes.length > 0) return {
-		result: {
-			file: relPath,
-			diagnostics: remaining,
-			fixed: migrated.changes.length > 0
-		},
-		fixCount: migrated.changes.length
+	return {
+		gate: "react-patterns",
+		category: "correctness",
+		findings,
+		meta: {
+			scanned: files.length,
+			elapsedMs: Date.now() - start
+		}
 	};
+};
+
+//#endregion
+//#region src/doctor/gates/pyreon-patterns.ts
+/**
+* pyreon-patterns gate — wraps `@pyreon/compiler:detectPyreonPatterns`.
+*
+* Catches "using Pyreon wrong" mistakes — 12 detector codes today
+* (for-missing-by, props-destructured, signal-write-as-call, etc.).
+* The detector matches the anti-patterns catalogue in
+* `.claude/rules/anti-patterns.md` (entries tagged `[detector: ...]`)
+* 1:1 — so the user reading the doctor output gets the same advice
+* as someone running `validate` via MCP.
+*/
+const runPyreonPatternsGate = async (opts) => {
+	const start = Date.now();
+	const findings = [];
+	const files = collectSourceFiles(opts.cwd);
+	for (const file of files) {
+		let code;
+		try {
+			code = fs.readFileSync(file, "utf-8");
+		} catch {
+			continue;
+		}
+		if (!hasPyreonPatterns(code)) continue;
+		const relPath = path.relative(opts.cwd, file);
+		const diagnostics = detectPyreonPatterns(code, relPath);
+		for (const diag of diagnostics) findings.push({
+			category: "correctness",
+			severity: "warning",
+			code: `pyreon-patterns/${diag.code}`,
+			gate: "pyreon-patterns",
+			message: diag.message,
+			location: {
+				path: file,
+				relPath,
+				line: diag.line,
+				column: diag.column
+			},
+			fix: diag.suggested
+		});
+	}
 	return {
-		result: null,
-		fixCount: 0
+		gate: "pyreon-patterns",
+		category: "correctness",
+		findings,
+		meta: {
+			scanned: files.length,
+			elapsedMs: Date.now() - start
+		}
 	};
-}
-function checkFileDetectOnly(file, relPath) {
-	let code;
-	try {
-		code = fs.readFileSync(file, "utf-8");
-	} catch {
-		return null;
+};
+
+//#endregion
+//#region src/doctor/gates/audit-tests.ts
+/**
+* audit-tests gate — wraps `@pyreon/compiler:auditTestEnvironment`.
+*
+* Catches mock-vnode test patterns (the PR #197 bug class — tests
+* that hand-construct `{ type, props, children }` literals or use a
+* `vnode()` helper instead of going through real `h()` from
+* `@pyreon/core`). Three risk tiers (HIGH / MEDIUM / LOW) from the
+* balance of mockVNodeLiteralCount + mockHelperCount +
+* mockHelperCallCount + realHCallCount + importsH. The adapter
+* maps tier → severity (high=error, medium=warning, low=info).
+*/
+const SEVERITY_BY_RISK = {
+	high: "error",
+	medium: "warning",
+	low: "info"
+};
+const RISK_RANK = {
+	high: 3,
+	medium: 2,
+	low: 1
+};
+const runAuditTestsGate = async (opts) => {
+	const start = Date.now();
+	const findings = [];
+	const minRank = RISK_RANK[opts.minRisk ?? "medium"] ?? 0;
+	const result = auditTestEnvironment(opts.cwd);
+	for (const entry of result.entries) {
+		if ((RISK_RANK[entry.risk] ?? 0) < minRank) continue;
+		const severity = SEVERITY_BY_RISK[entry.risk] ?? "warning";
+		findings.push({
+			category: "testing",
+			severity,
+			code: `audit-tests/mock-vnode-${entry.risk}`,
+			gate: "audit-tests",
+			message: `Mock-vnode test pattern (risk: ${entry.risk}). Literals: ${entry.mockVNodeLiteralCount}, helper defs: ${entry.mockHelperCount}, helper calls: ${entry.mockHelperCallCount}, real h() calls: ${entry.realHCallCount}. ${entry.realHCallCount === 0 ? "No real-h() coverage — every contract assertion is mock-only." : "Has real-h() coverage but mock-vnode patterns still dominate."}`,
+			location: {
+				path: entry.path,
+				relPath: entry.relPath
+			}
+		});
 	}
-	if (!hasReactPatterns(code)) return null;
-	const diagnostics = detectReactPatterns(code, relPath);
-	if (diagnostics.length > 0) return {
-		file: relPath,
-		diagnostics,
-		fixed: false
+	return {
+		gate: "audit-tests",
+		category: "testing",
+		findings,
+		meta: {
+			scanned: result.entries.length,
+			elapsedMs: Date.now() - start
+		}
+	};
+};
+
+//#endregion
+//#region src/doctor/gates/islands-audit.ts
+/**
+* islands-audit gate — wraps `@pyreon/compiler:auditIslands`.
+*
+* Project-wide cross-file detectors for the island architecture
+* (duplicate names, dead islands, registry drift, nested islands,
+* never-with-registry-entry). Per-finding severity is derived from
+* the finding code: `dead-island` is a warning (might be intentional
+* during refactor), everything else is an error (silent runtime
+* failure mode).
+*/
+const SEVERITY_BY_CODE$1 = {
+	"duplicate-name": "error",
+	"never-with-registry-entry": "error",
+	"registry-mismatch": "error",
+	"nested-island": "error",
+	"dead-island": "warning"
+};
+const runIslandsAuditGate = async (opts) => {
+	const start = Date.now();
+	const findings = [];
+	const result = auditIslands(opts.cwd);
+	for (const f of result.findings) findings.push({
+		category: "architecture",
+		severity: SEVERITY_BY_CODE$1[f.code] ?? "error",
+		code: `islands-audit/${f.code}`,
+		gate: "islands-audit",
+		message: f.message,
+		location: {
+			path: f.location.path,
+			relPath: f.location.relPath,
+			line: f.location.line,
+			column: f.location.column
+		},
+		relatedLocations: f.related?.map((r) => ({
+			path: r.path,
+			relPath: r.relPath,
+			line: r.line,
+			column: r.column
+		}))
+	});
+	return {
+		gate: "islands-audit",
+		category: "architecture",
+		findings,
+		meta: {
+			scanned: result.findings.length,
+			elapsedMs: Date.now() - start
+		}
 	};
+};
+
+//#endregion
+//#region src/doctor/gates/ssg-audit.ts
+/**
+* ssg-audit gate — wraps `@pyreon/compiler:auditSsg`.
+*
+* SSG / ISR convention checker (M3.4): `_404.tsx` placement, dynamic
+* routes missing `getStaticPaths`, non-literal revalidate exports.
+* Severities mirror the gate's intent: missing-getStaticPaths is a
+* warn (legit under `mode: 'ssr' | 'isr'`), the other two are errors
+* (silently broken under `mode: 'ssg'`).
+*/
+const SEVERITY_BY_CODE = {
+	"404-outside-layout-dir": "error",
+	"dynamic-route-missing-get-static-paths": "warning",
+	"non-literal-revalidate-export": "error"
+};
+const runSsgAuditGate = async (opts) => {
+	const start = Date.now();
+	const findings = [];
+	const result = auditSsg(opts.cwd);
+	for (const f of result.findings) findings.push({
+		category: "architecture",
+		severity: SEVERITY_BY_CODE[f.code] ?? "error",
+		code: `ssg-audit/${f.code}`,
+		gate: "ssg-audit",
+		message: f.message,
+		location: {
+			path: f.location.path,
+			relPath: f.location.relPath,
+			line: f.location.line,
+			column: f.location.column
+		}
+	});
+	return {
+		gate: "ssg-audit",
+		category: "architecture",
+		findings,
+		meta: {
+			scanned: result.findings.length,
+			elapsedMs: Date.now() - start
+		}
+	};
+};
+
+//#endregion
+//#region src/doctor/gates/lint.ts
+/**
+* lint gate — wraps `@pyreon/lint:lint`.
+*
+* Runs the project's configured Pyreon lint rules across the source
+* tree. Per-finding category is derived from the rule ID's prefix
+* (the lint rule categories: reactivity, jsx, lifecycle, performance,
+* ssr, architecture, store, form, styling, hooks, accessibility,
+* router, ssg) — `performance` rules emit `category: 'performance'`,
+* `architecture` rules emit `category: 'architecture'`, the rest fold
+* to `'correctness'` since they're all "your code is broken in some
+* way" findings from the doctor's perspective.
+*
+* Severity passes through as-is from lint's `Diagnostic.severity`
+* ('error' | 'warning' | 'info' all map 1:1 to the doctor severity
+* shape).
+*/
+const mapLintSeverity = (s) => {
+	if (s === "error") return "error";
+	if (s === "warn") return "warning";
+	if (s === "info") return "info";
 	return null;
+};
+const RULE_CATEGORY = (() => {
+	const map = /* @__PURE__ */ new Map();
+	for (const rule of allRules) {
+		const cat = mapLintCategory(rule.meta.category);
+		map.set(rule.meta.id, cat);
+	}
+	return map;
+})();
+function mapLintCategory(c) {
+	switch (c) {
+		case "performance": return "performance";
+		case "architecture":
+		case "ssr":
+		case "ssg":
+		case "router": return "architecture";
+		case "styling":
+		case "accessibility": return "architecture";
+		default: return "correctness";
+	}
 }
-function runChecks(files, options) {
-	const fileResults = [];
-	let totalFixed = 0;
-	for (const file of files) {
-		const relPath = path.relative(options.cwd, file);
-		if (options.fix) {
-			const { result, fixCount } = checkFileWithFix(file, relPath);
-			totalFixed += fixCount;
-			if (result) fileResults.push(result);
-		} else {
-			const result = checkFileDetectOnly(file, relPath);
-			if (result) fileResults.push(result);
-		}
+const runLintGate = async (opts) => {
+	const start = Date.now();
+	const findings = [];
+	const result = await lint({
+		paths: [opts.cwd],
+		fix: opts.fix ?? false
+	});
+	for (const fileResult of result.files) for (const diag of fileResult.diagnostics) {
+		const severity = mapLintSeverity(diag.severity);
+		if (severity === null) continue;
+		const category = RULE_CATEGORY.get(diag.ruleId) ?? "correctness";
+		findings.push({
+			category,
+			severity,
+			code: `lint/${diag.ruleId}`,
+			gate: "lint",
+			message: diag.message,
+			location: {
+				path: fileResult.filePath,
+				relPath: path.relative(opts.cwd, fileResult.filePath),
+				line: diag.loc.line,
+				column: diag.loc.column
+			},
+			fixable: diag.fix !== void 0
+		});
+	}
+	for (const cd of result.configDiagnostics) {
+		const severity = mapLintSeverity(cd.severity);
+		if (severity === null) continue;
+		findings.push({
+			category: "architecture",
+			severity,
+			code: `lint/config-${cd.ruleId}`,
+			gate: "lint",
+			message: cd.message
+		});
 	}
-	const totalErrors = fileResults.reduce((sum, f) => sum + f.diagnostics.length, 0);
-	const totalFixable = fileResults.reduce((sum, f) => sum + f.diagnostics.filter((d) => d.fixable).length, 0);
 	return {
-		passed: totalErrors === 0,
-		files: fileResults,
-		summary: {
-			filesScanned: files.length,
-			filesWithIssues: fileResults.length,
-			totalErrors,
-			totalFixable,
-			totalFixed
+		gate: "lint",
+		category: "correctness",
+		findings,
+		meta: {
+			scanned: result.files.length,
+			elapsedMs: Date.now() - start
 		}
 	};
-}
-function printJson(result) {
-	console.log(JSON.stringify(result, null, 2));
-}
-function printFileResult(fileResult) {
-	if (fileResult.diagnostics.length === 0) return;
-	console.log(`  ${fileResult.file}${fileResult.fixed ? " (partially fixed)" : ""}`);
-	for (const diag of fileResult.diagnostics) {
-		const fixTag = diag.fixable ? " [fixable]" : "";
-		console.log(`    ${diag.line}:${diag.column} — ${diag.message}${fixTag}`);
-		console.log(`      Current:   ${diag.current}`);
-		console.log(`      Suggested: ${diag.suggested}`);
-		console.log("");
+};
+
+//#endregion
+//#region src/doctor/score.ts
+const CATEGORIES = [
+	"correctness",
+	"performance",
+	"architecture",
+	"testing",
+	"documentation"
+];
+const SEVERITY_WEIGHTS = {
+	error: 10,
+	warning: 3,
+	info: 1
+};
+/** Pure scorer — no I/O, deterministic given findings. */
+const scoreCategory = (category, findings, included) => {
+	const inCat = findings.filter((f) => f.category === category);
+	const errors = inCat.filter((f) => f.severity === "error").length;
+	const warnings = inCat.filter((f) => f.severity === "warning").length;
+	const infos = inCat.filter((f) => f.severity === "info").length;
+	const penalty = errors * SEVERITY_WEIGHTS.error + warnings * SEVERITY_WEIGHTS.warning + infos * SEVERITY_WEIGHTS.info;
+	const score = Math.max(0, Math.min(100, 100 - penalty));
+	return {
+		category,
+		score,
+		errors,
+		warnings,
+		infos,
+		grade: gradeFor(score),
+		included
+	};
+};
+const gradeFor = (score) => {
+	if (score >= 90) return "A";
+	if (score >= 80) return "B";
+	if (score >= 70) return "C";
+	if (score >= 60) return "D";
+	return "F";
+};
+/**
+* Compute per-category subscores + overall score.
+*
+* `gates` is used to decide which categories are `included` — a
+* category is included if at least one non-skipped gate emits in it.
+* If no gate ran for `documentation`, the category is excluded from
+* the overall mean rather than counted as 100/100.
+*/
+const computeScore = (findings, gates) => {
+	const includedCats = /* @__PURE__ */ new Set();
+	for (const g of gates) if (!g.meta.skipped) includedCats.add(g.category);
+	for (const f of findings) includedCats.add(f.category);
+	const categories = CATEGORIES.map((c) => scoreCategory(c, findings, includedCats.has(c)));
+	const included = categories.filter((c) => c.included);
+	if (included.length === 0) return {
+		score: 100,
+		grade: "A",
+		categories
+	};
+	const sum = included.reduce((s, c) => s + c.score, 0);
+	const score = Math.round(sum / included.length);
+	return {
+		score,
+		grade: gradeFor(score),
+		categories
+	};
+};
+
+//#endregion
+//#region src/doctor/report.ts
+/**
+* `DoctorReport` aggregator — collects gate results, builds findings
+* list, computes the 0-100 score, returns the report the renderers
+* consume. Pure-function: takes gate results in, returns report out.
+*
+* The orchestration layer (which gates to run, in what order, with
+* what timeout) lives in the doctor command itself; this module is
+* just the "merge + score" step. Splitting them keeps the score
+* formula testable in isolation and makes it trivial to add a new
+* gate (drop into the orchestrator's list, no aggregator changes).
+*/
+const SEVERITY_RANK = {
+	error: 0,
+	warning: 1,
+	info: 2
+};
+/**
+* Sort findings: errors first, then warnings, then info. Within
+* each severity, group by category for predictable output.
+*/
+const sortFindings = (findings) => [...findings].sort((a, b) => {
+	const sevDelta = SEVERITY_RANK[a.severity] - SEVERITY_RANK[b.severity];
+	if (sevDelta !== 0) return sevDelta;
+	if (a.category !== b.category) return a.category.localeCompare(b.category);
+	return a.code.localeCompare(b.code);
+});
+const buildReport = (gates) => {
+	const findings = sortFindings(gates.flatMap((g) => g.findings));
+	const totals = {
+		errors: findings.filter((f) => f.severity === "error").length,
+		warnings: findings.filter((f) => f.severity === "warning").length,
+		infos: findings.filter((f) => f.severity === "info").length
+	};
+	const { score, grade, categories } = computeScore(findings, gates);
+	return {
+		score,
+		grade,
+		categories,
+		gates,
+		findings,
+		totals,
+		elapsedMs: gates.reduce((s, g) => s + g.meta.elapsedMs, 0),
+		timestamp: (/* @__PURE__ */ new Date()).toISOString()
+	};
+};
+
+//#endregion
+//#region src/doctor/orchestrator.ts
+/**
+* Doctor orchestrator — picks the gate list per mode, runs them in
+* parallel where safe, collects results, hands off to the aggregator.
+*
+* **Gate categorization by speed**:
+*   - FAST gates (default): react-patterns, pyreon-patterns, lint,
+*     distribution, doc-claims, islands-audit, ssg-audit, audit-tests.
+*     Total runtime ~2-5s on the real Pyreon repo.
+*   - SLOW gates (`--full` opt-in): audit-types (TS compiler-API walk
+*     across 6 packages, ~1-30s), bundle-budgets (Bun.build of every
+*     published package, ~15-30s).
+*
+* **Why parallel**: the gates are fully independent — no shared
+* state, no file-write contention (only `--fix` writes, and lint /
+* react-patterns target disjoint file patterns). Running them via
+* `Promise.all` cuts wall-clock from ~5s sequential to ~1-2s for the
+* fast set on a warm cache.
+*
+* **Skip filtering**: `--only` and `--skip` operate on gate names.
+* Skipped gates appear in the report with `meta.skipped: true` so
+* the renderer shows them in the footer ("Skipped: bundle-budgets").
+*/
+/** Gates that run by default (fast). */
+const FAST_GATES = [
+	"react-patterns",
+	"pyreon-patterns",
+	"lint",
+	"distribution",
+	"doc-claims",
+	"islands-audit",
+	"ssg-audit",
+	"audit-tests"
+];
+/** Gates that require `--full` to enable. */
+const SLOW_GATES = ["audit-types", "bundle-budgets"];
+const skippedGate = (gate, category, reason) => ({
+	gate,
+	category,
+	findings: [],
+	meta: {
+		elapsedMs: 0,
+		skipped: true,
+		skipReason: reason
 	}
-}
-function printSummary(summary) {
-	console.log(`  ${summary.totalErrors} issue${summary.totalErrors === 1 ? "" : "s"} in ${summary.filesWithIssues} file${summary.filesWithIssues === 1 ? "" : "s"}`);
-	if (summary.totalFixable > 0) console.log(`  ${summary.totalFixable} auto-fixable — run 'pyreon doctor --fix' to apply`);
-	console.log("");
-}
-function printHuman(result, elapsed) {
-	const { summary } = result;
-	console.log("");
-	console.log(`  Pyreon Doctor — scanned ${summary.filesScanned} files in ${elapsed}ms`);
-	console.log("");
-	if (result.passed && summary.totalFixed === 0) {
-		console.log("  ✓ No issues found. Your code is Pyreon-native!");
-		console.log("");
-		return;
+});
+const ALL_GATE_CATEGORIES = {
+	"react-patterns": "correctness",
+	"pyreon-patterns": "correctness",
+	lint: "correctness",
+	distribution: "architecture",
+	"doc-claims": "documentation",
+	"audit-tests": "testing",
+	"islands-audit": "architecture",
+	"ssg-audit": "architecture",
+	"audit-types": "architecture",
+	"bundle-budgets": "performance"
+};
+/**
+* Resolve which gates to run.
+*
+* Precedence: `--only` > `--skip` > (`--full` toggles slow gates) > default fast set.
+*/
+const resolveGates = (opts) => {
+	if (opts.only && opts.only.length > 0) {
+		const skip = new Set(opts.skip ?? []);
+		return opts.only.filter((g) => !skip.has(g));
 	}
-	if (summary.totalFixed > 0) {
-		console.log(`  ✓ Auto-fixed ${summary.totalFixed} issue${summary.totalFixed === 1 ? "" : "s"}`);
-		console.log("");
+	const base = opts.full ? [...FAST_GATES, ...SLOW_GATES] : [...FAST_GATES];
+	const skip = new Set(opts.skip ?? []);
+	return base.filter((g) => !skip.has(g));
+};
+/**
+* Run the gates and build the report. Wall-clock is measured here
+* (vs the aggregator's sum-of-elapsedMs which is total CPU time).
+*/
+const runDoctor = async (opts) => {
+	const start = Date.now();
+	const selected = new Set(resolveGates(opts));
+	const promises = [...FAST_GATES, ...SLOW_GATES].map(async (gate) => {
+		if (!selected.has(gate)) {
+			const reason = SLOW_GATES.includes(gate) && !opts.full ? "enable with --full" : "skipped";
+			return skippedGate(gate, ALL_GATE_CATEGORIES[gate], reason);
+		}
+		return runGate(gate, opts);
+	});
+	return {
+		...buildReport(await Promise.all(promises)),
+		elapsedMs: Date.now() - start
+	};
+};
+const runGate = async (gate, opts) => {
+	switch (gate) {
+		case "react-patterns": return runReactPatternsGate({
+			cwd: opts.cwd,
+			fix: opts.fix
+		});
+		case "pyreon-patterns": return runPyreonPatternsGate({ cwd: opts.cwd });
+		case "lint": return runLintGate({
+			cwd: opts.cwd,
+			fix: opts.fix
+		});
+		case "distribution": return runDistributionGate({
+			cwd: opts.cwd,
+			skipPackProbe: true
+		});
+		case "doc-claims": return runDocClaimsGate({ cwd: opts.cwd });
+		case "audit-tests": return runAuditTestsGate({
+			cwd: opts.cwd,
+			minRisk: opts.auditMinRisk ?? "medium"
+		});
+		case "islands-audit": return runIslandsAuditGate({ cwd: opts.cwd });
+		case "ssg-audit": return runSsgAuditGate({ cwd: opts.cwd });
+		case "audit-types": return runAuditTypesGate({ cwd: opts.cwd });
+		case "bundle-budgets": return runBundleBudgetsGate({ cwd: opts.cwd });
 	}
-	for (const fileResult of result.files) printFileResult(fileResult);
-	printSummary(summary);
-}
+};
+
+//#endregion
+//#region src/doctor/render/ansi.ts
+/**
+* Minimal ANSI helpers for `pyreon doctor` human output.
+*
+* We deliberately don't pull in `chalk` / `kleur` / etc. — the doctor
+* already lives in `@pyreon/cli` (the entrypoint package) and adding
+* a runtime ANSI library bumps the install footprint. The escapes
+* are tiny and stable.
+*
+* The `enabled` flag respects:
+*   - `NO_COLOR=1`            → disable (de-facto standard)
+*   - `FORCE_COLOR=1` / `0`   → force on / off
+*   - `process.stdout.isTTY`  → default if no override
+*   - CI tools like GitHub Actions set `CI=1` but their terminal DOES
+*     render ANSI — so CI alone doesn't disable color.
+*/
+const ESC = String.fromCharCode(27);
+const CSI = `${ESC}[`;
+const OSC = `${ESC}]`;
+const ST = `${ESC}\\`;
+const isColorEnabled = () => {
+	if (process.env.NO_COLOR) return false;
+	if (process.env.FORCE_COLOR === "0") return false;
+	if (process.env.FORCE_COLOR) return true;
+	return Boolean(process.stdout.isTTY);
+};
+const colorEnabled = isColorEnabled();
+const wrap = (open, close) => (s) => colorEnabled ? `${CSI}${open}m${s}${CSI}${close}m` : s;
+const bold = wrap("1", "22");
+const dim = wrap("2", "22");
+const red = wrap("31", "39");
+const green = wrap("32", "39");
+const yellow = wrap("33", "39");
+const blue = wrap("34", "39");
+const magenta = wrap("35", "39");
+const cyan = wrap("36", "39");
+const gray = wrap("90", "39");
+/**
+* OSC-8 hyperlink. iTerm2, WezTerm, kitty, modern VSCode terminals
+* render this as a clickable link; other terminals show the visible
+* text and ignore the escape. We use this for file paths so the user
+* can cmd-click a finding's location and jump to it.
+*
+* `url` should be a `file://` URL with optional line/column:
+*   `file:///path/to/file.ts#L42`
+*/
+const hyperlink = (text, url) => {
+	if (!colorEnabled) return text;
+	return `${OSC}8;;${url}${ST}${text}${OSC}8;;${ST}`;
+};
+/** Build a `file://` URL with optional line / column suffix. */
+const fileUrl = (absPath, line, _column) => {
+	let url = `file://${absPath}`;
+	if (line !== void 0) url += `#L${line}`;
+	return url;
+};
+
+//#endregion
+//#region src/doctor/render/text.ts
+const BAR_WIDTH = 12;
+const FILLED = "█";
+const EMPTY = "░";
+const SEV_ICON = {
+	error: "✖",
+	warning: "⚠",
+	info: "ℹ"
+};
+const colorForGrade = (g) => {
+	if (g === "A") return green;
+	if (g === "B" || g === "C") return yellow;
+	return red;
+};
+const colorForSeverity = (s) => {
+	if (s === "error") return red;
+	if (s === "warning") return yellow;
+	return cyan;
+};
+const renderBar = (score, color) => {
+	const filled = Math.round(score / 100 * BAR_WIDTH);
+	const empty = BAR_WIDTH - filled;
+	return color(FILLED.repeat(filled)) + gray(EMPTY.repeat(empty));
+};
+const padRight = (s, n) => s.length >= n ? s : s + " ".repeat(n - s.length);
+const renderCategory = (c) => {
+	if (!c.included) return `  ${dim(padRight(c.category, 14))} ${gray("skipped")}`;
+	const color = colorForGrade(c.grade);
+	const bar = renderBar(c.score, color);
+	const score = color(padRight(String(c.score), 3));
+	const breakdown = c.errors + c.warnings + c.infos === 0 ? gray("clean") : [
+		c.errors > 0 ? red(`${c.errors}E`) : "",
+		c.warnings > 0 ? yellow(`${c.warnings}W`) : "",
+		c.infos > 0 ? cyan(`${c.infos}i`) : ""
+	].filter(Boolean).join(" ");
+	return `  ${padRight(c.category, 14)} ${bar} ${score} ${dim("·")} ${breakdown}`;
+};
+const renderBanner = (report) => {
+	const gColor = colorForGrade(report.grade);
+	const score = gColor(bold(String(report.score)));
+	const grade = gColor(bold(report.grade));
+	return [
+		"",
+		`  ${bold("pyreon doctor")} ${dim("· project health audit")}`,
+		"",
+		`  Score:  ${score}/100   Grade: ${grade}`,
+		""
+	].join("\n");
+};
+const renderFinding = (f) => {
+	const icon = colorForSeverity(f.severity)(SEV_ICON[f.severity]);
+	const code = dim(f.code);
+	const lines = [`  ${icon} ${bold(f.message)}  ${code}`];
+	if (f.location) {
+		const linked = hyperlink(cyan(`${f.location.relPath || f.location.path}${f.location.line ? `:${f.location.line}${f.location.column !== void 0 ? `:${f.location.column}` : ""}` : ""}`), fileUrl(f.location.path, f.location.line, f.location.column));
+		lines.push(`     ${linked}`);
+	}
+	if (f.relatedLocations && f.relatedLocations.length > 0) for (const rl of f.relatedLocations) {
+		const relPath = rl.relPath || rl.path;
+		const lineCol = rl.line ? `:${rl.line}` : "";
+		const label = rl.label ? ` ${dim(`(${rl.label})`)}` : "";
+		lines.push(`     ${dim("↳")} ${cyan(relPath + lineCol)}${label}`);
+	}
+	if (f.fix) lines.push(`     ${dim("fix:")} ${f.fix}`);
+	return lines.join("\n");
+};
+const renderFindings = (report, topN) => {
+	if (report.findings.length === 0) return `  ${green("✓")} No findings. Your project is healthy.\n`;
+	const shown = report.findings.slice(0, topN);
+	const remaining = report.findings.length - shown.length;
+	const lines = [bold(`  Top findings (${shown.length} of ${report.findings.length}):`), ""];
+	for (const f of shown) {
+		lines.push(renderFinding(f));
+		lines.push("");
+	}
+	if (remaining > 0) {
+		lines.push(dim(`  …and ${remaining} more. Run with ${bold("--json")} for the full list.`));
+		lines.push("");
+	}
+	return lines.join("\n");
+};
+const renderSkipped = (report) => {
+	const skipped = report.gates.filter((g) => g.meta.skipped);
+	if (skipped.length === 0) return "";
+	const names = skipped.map((g) => `${g.gate}${g.meta.skipReason ? ` (${g.meta.skipReason})` : ""}`).join(", ");
+	return `  ${dim("Skipped:")} ${names}\n`;
+};
+const renderFooter = (report) => {
+	const { errors, warnings, infos } = report.totals;
+	const totalSummary = [
+		errors > 0 ? red(`${errors} error${errors === 1 ? "" : "s"}`) : "",
+		warnings > 0 ? yellow(`${warnings} warning${warnings === 1 ? "" : "s"}`) : "",
+		infos > 0 ? cyan(`${infos} info`) : ""
+	].filter(Boolean).join(`${dim(" · ")}`) || green("no findings");
+	const elapsed = `${(report.elapsedMs / 1e3).toFixed(1)}s`;
+	return `  ${totalSummary} ${dim(`· ${report.gates.filter((g) => !g.meta.skipped).length} gates · ${elapsed}`)}\n`;
+};
+const renderText = (report, opts = {}) => {
+	const topN = opts.topN ?? 10;
+	return [
+		renderBanner(report),
+		bold("  Per category:"),
+		"",
+		...report.categories.map(renderCategory),
+		"",
+		renderFindings(report, topN),
+		renderSkipped(report),
+		renderFooter(report)
+	].join("\n");
+};
+
+//#endregion
+//#region src/doctor/render/json.ts
+const renderJson = (report) => JSON.stringify(report, null, 2);
+
+//#endregion
+//#region src/doctor/render/gha.ts
+const GHA_LEVEL = {
+	error: "error",
+	warning: "warning",
+	info: "notice"
+};
+const escape = (s) => s.replace(/%/g, "%25").replace(/\r/g, "%0D").replace(/\n/g, "%0A");
+const renderGha = (report) => {
+	const lines = [];
+	lines.push(`::notice::pyreon doctor score: ${report.score}/100 (${report.grade}) — ${report.totals.errors} errors, ${report.totals.warnings} warnings, ${report.totals.infos} info`);
+	for (const f of report.findings) {
+		const level = GHA_LEVEL[f.severity];
+		const props = [];
+		props.push(`title=${escape(f.code)}`);
+		if (f.location?.relPath) props.push(`file=${escape(f.location.relPath)}`);
+		if (f.location?.line) props.push(`line=${f.location.line}`);
+		if (f.location?.column) props.push(`col=${f.location.column}`);
+		const msg = f.fix ? `${f.message} — ${f.fix}` : f.message;
+		lines.push(`::${level} ${props.join(",")}::${escape(msg)}`);
+	}
+	return lines.join("\n");
+};
+
+//#endregion
+//#region src/doctor.ts
+/**
+* `pyreon doctor` — project-wide health audit.
+*
+* PR 2 rewrites this entrypoint around the unified gate API
+* (`packages/tools/cli/src/doctor/`). The orchestrator runs every
+* gate in parallel, the aggregator builds a `DoctorReport` with a
+* 0-100 score, the renderer formats it for text / JSON / GHA.
+*
+* The legacy single-purpose flags (`--audit-tests`, `--check-islands`,
+* `--check-ssg`) are interpreted as `--only <gate>` shortcuts so any
+* existing CI script that relied on the old shape keeps working.
+* Without those flags, doctor runs the full fast-gate set + computes
+* a score — the new default behaviour.
+*
+* Output modes:
+*   - text (default): big-score banner + per-category bars + top-N findings
+*   - --json: full `DoctorReport` as JSON
+*   - --gha:  GitHub Actions annotation lines (one per finding)
+*
+* Modes:
+*   - --full: enable slow gates (audit-types, bundle-budgets)
+*   - --only <gates>: run ONLY the listed comma-separated gates
+*   - --skip <gates>: exclude these gates
+*   - --fix: auto-fix where possible (lint + react-patterns)
+*   - --ci: exit non-zero on any error finding
+*/
+const resolveFormat = (options) => {
+	if (options.format) return options.format;
+	if (options.json) return "json";
+	return "text";
+};
+const resolveOnly = (options) => {
+	if (options.only && options.only.length > 0) return options.only;
+	const legacyOnly = [];
+	if (options.auditTests) legacyOnly.push("audit-tests");
+	if (options.checkIslands) legacyOnly.push("islands-audit");
+	if (options.checkSsg) legacyOnly.push("ssg-audit");
+	return legacyOnly.length > 0 ? legacyOnly : void 0;
+};
+const doctor = async (options) => {
+	const report = await runDoctor({
+		cwd: options.cwd,
+		full: options.full,
+		only: resolveOnly(options),
+		skip: options.skip,
+		fix: options.fix,
+		auditMinRisk: options.auditMinRisk
+	});
+	const format = resolveFormat(options);
+	if (format === "json") console.log(renderJson(report));
+	else if (format === "gha") console.log(renderGha(report));
+	else console.log(renderText(report, { cwd: options.cwd }));
+	if (options.ci) return report.totals.errors;
+	return report.totals.errors + report.totals.warnings + report.totals.infos;
+};
 
 //#endregion
 //#region src/index.ts
@@ -245,9 +1531,21 @@ function printHuman(result, elapsed) {
 * @pyreon/cli — Developer tools for Pyreon
 *
 * Commands:
-*   pyreon doctor [--fix] [--json]  — Scan project for React patterns, bad imports, etc.
-*   pyreon context                  — Generate .pyreon/context.json for AI tools
+*   pyreon doctor   — project-wide health audit (score + per-category bars + findings)
+*   pyreon context  — generate .pyreon/context.json for AI tools
 */
+const VALID_GATES = [
+	"react-patterns",
+	"pyreon-patterns",
+	"lint",
+	"distribution",
+	"doc-claims",
+	"audit-tests",
+	"islands-audit",
+	"ssg-audit",
+	"audit-types",
+	"bundle-budgets"
+];
 const args = process.argv.slice(2);
 const command = args[0];
 function printUsage() {
@@ -255,23 +1553,62 @@ function printUsage() {
   pyreon <command> [options]
 
   Commands:
-    doctor [--fix] [--json] [--ci] [--audit-tests] [--audit-min-risk <level>] [--check-islands] [--check-ssg]
-                                     Scan for React patterns, bad imports, common mistakes.
-                                     --audit-tests appends mock-vnode test-audit (PR #197 class).
-                                     --audit-min-risk is high|medium|low (default medium).
-                                     --check-islands appends project-wide islands audit
-                                     (duplicate names, dead islands, registry drift, nested,
-                                     never-with-registry).
-                                     --check-ssg appends project-wide SSG / ISR audit
-                                     (_404.tsx placement, dynamic routes missing
-                                     getStaticPaths, non-literal revalidate exports).
+    doctor [options]                 Project-wide health audit with 0-100 score.
+                                     Runs 8 fast gates by default; --full enables 2 slow gates.
     context [--out <path>]           Generate .pyreon/context.json for AI tools
 
+  doctor options:
+    --fix                            Auto-fix what we can (lint + react-patterns).
+    --full                           Include slow gates (audit-types, bundle-budgets).
+    --only <gates>                   Run ONLY these gates (comma-separated).
+    --skip <gates>                   Skip these gates (comma-separated).
+    --format text|json|gha           Output format (default: text).
+    --json                           Shortcut for --format=json.
+    --gha                            Shortcut for --format=gha (GitHub Actions annotations).
+    --ci                             Exit non-zero on error findings only.
+    --audit-min-risk high|medium|low Minimum risk for test-env audit (default: medium).
+
+  doctor gates:
+    Fast: ${VALID_GATES.slice(0, 8).join(", ")}
+    Slow: ${VALID_GATES.slice(8).join(", ")} (require --full)
+
+  Legacy doctor flags (still work — map to --only shortcuts):
+    --audit-tests                    Equivalent to --only audit-tests
+    --check-islands                  Equivalent to --only islands-audit
+    --check-ssg                      Equivalent to --only ssg-audit
+
   Options:
     --help                           Show this help message
     --version                        Show version
 `);
 }
+const parseGateList = (raw) => {
+	if (!raw) return void 0;
+	const names = raw.split(",").map((s) => s.trim()).filter(Boolean);
+	const invalid = names.filter((n) => !VALID_GATES.includes(n));
+	if (invalid.length > 0) {
+		console.error(`Unknown gate(s): ${invalid.join(", ")}. Valid: ${VALID_GATES.join(", ")}`);
+		process.exit(1);
+	}
+	return names;
+};
+const getFlagValue = (flag) => {
+	const idx = args.indexOf(flag);
+	if (idx < 0) return void 0;
+	return args[idx + 1];
+};
+const parseFormat = (raw) => {
+	if (!raw) return void 0;
+	if (raw === "text" || raw === "json" || raw === "gha") return raw;
+	console.error(`--format must be text|json|gha, got '${raw}'`);
+	process.exit(1);
+};
+const parseMinRisk = (raw) => {
+	if (!raw) return void 0;
+	if (raw === "high" || raw === "medium" || raw === "low") return raw;
+	console.error(`--audit-min-risk must be high|medium|low, got '${raw}'`);
+	process.exit(1);
+};
 async function main() {
 	if (!command || command === "--help" || command === "-h") {
 		printUsage();
@@ -282,19 +1619,18 @@ async function main() {
 		return;
 	}
 	if (command === "doctor") {
-		const riskIdx = args.indexOf("--audit-min-risk");
-		const rawRisk = riskIdx >= 0 ? args[riskIdx + 1] : void 0;
-		if (rawRisk !== void 0 && rawRisk !== "high" && rawRisk !== "medium" && rawRisk !== "low") {
-			console.error(`--audit-min-risk must be high | medium | low, got '${rawRisk}'`);
-			process.exit(1);
-		}
+		const format = args.includes("--gha") ? "gha" : parseFormat(getFlagValue("--format"));
 		const options = {
 			fix: args.includes("--fix"),
 			json: args.includes("--json"),
 			ci: args.includes("--ci"),
 			cwd: process.cwd(),
+			format,
+			full: args.includes("--full"),
+			only: parseGateList(getFlagValue("--only")),
+			skip: parseGateList(getFlagValue("--skip")),
 			auditTests: args.includes("--audit-tests"),
-			auditMinRisk: rawRisk,
+			auditMinRisk: parseMinRisk(getFlagValue("--audit-min-risk")),
 			checkIslands: args.includes("--check-islands"),
 			checkSsg: args.includes("--check-ssg")
 		};