pi-lens 2.0.29 → 2.0.35

package/clients/architect-client.js

@@ -0,0 +1,216 @@
+/**
+ * Architect Client for pi-lens
+ *
+ * Loads path-based architectural rules from .pi-lens/architect.yaml
+ * and checks file paths against them.
+ *
+ * Provides:
+ * - Pre-write hints: what rules apply before the agent edits
+ * - Post-write validation: check for violations after edits
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { minimatch } from "minimatch";
+// --- Client ---
+export class ArchitectClient {
+    constructor(verbose = false) {
+        this.config = null;
+        this.configPath = null;
+        this.log = verbose
+            ? (msg) => console.error(`[architect] ${msg}`)
+            : () => { };
+    }
+    /**
+     * Load architect config from project root
+     */
+    loadConfig(projectRoot) {
+        // Try common locations
+        const candidates = [
+            path.join(projectRoot, ".pi-lens", "architect.yaml"),
+            path.join(projectRoot, "architect.yaml"),
+            path.join(projectRoot, ".pi-lens", "architect.yml"),
+        ];
+        for (const configPath of candidates) {
+            try {
+                const content = fs.readFileSync(configPath, "utf-8");
+                this.config = this.parseYaml(content);
+                this.configPath = configPath;
+                this.log(`Loaded architect config from ${configPath}`);
+                return true;
+            }
+            catch (error) {
+                this.log(`Could not read ${configPath}: ${error}`);
+                continue;
+            }
+        }
+        this.log("No architect.yaml found");
+        return false;
+    }
+    /**
+     * Check if config is loaded
+     */
+    hasConfig() {
+        return this.config !== null;
+    }
+    /**
+     * Get rules that apply to a file path
+     */
+    getRulesForFile(filePath) {
+        if (!this.config)
+            return [];
+        const matched = [];
+        for (const rule of this.config.rules) {
+            if (minimatch(filePath, rule.pattern, { matchBase: true })) {
+                matched.push(rule);
+            }
+        }
+        return matched;
+    }
+    /**
+     * Check code content against rules for a file path
+     * Returns violations found
+     */
+    checkFile(filePath, content) {
+        const rules = this.getRulesForFile(filePath);
+        const violations = [];
+        for (const rule of rules) {
+            if (!rule.must_not)
+                continue;
+            for (const check of rule.must_not) {
+                const regex = new RegExp(check.pattern, "i");
+                if (regex.test(content)) {
+                    violations.push({
+                        pattern: rule.pattern,
+                        message: check.message,
+                    });
+                }
+            }
+        }
+        return violations;
+    }
+    /**
+     * Check file size against max_lines rule
+     * Returns violation if file exceeds the limit
+     */
+    checkFileSize(filePath, lineCount) {
+        const rules = this.getRulesForFile(filePath);
+        for (const rule of rules) {
+            if (rule.max_lines && lineCount > rule.max_lines) {
+                return {
+                    pattern: rule.pattern,
+                    message: `File is ${lineCount} lines — exceeds ${rule.max_lines} line limit. Split into smaller modules.`,
+                };
+            }
+        }
+        return null;
+    }
+    /**
+     * Get pre-write hints for a file path
+     * Returns rules that will apply to the file being written
+     */
+    getHints(filePath) {
+        const rules = this.getRulesForFile(filePath);
+        const hints = [];
+        for (const rule of rules) {
+            if (rule.must_not) {
+                for (const check of rule.must_not) {
+                    hints.push(check.message);
+                }
+            }
+            if (rule.must) {
+                for (const req of rule.must) {
+                    hints.push(`Must: ${req}`);
+                }
+            }
+        }
+        return hints;
+    }
+    /**
+     * Simple YAML parser for architect.yaml format
+     * Handles the specific structure we need
+     */
+    parseYaml(content) {
+        const config = { rules: [] };
+        // Split into top-level rule blocks (4-space indent "- pattern:")
+        const ruleBlocks = content.split(/(?=^  - pattern:)/m);
+        for (const block of ruleBlocks) {
+            const lines = block.split("\n");
+            let rule = null;
+            let section = null;
+            let violation = null;
+            for (const line of lines) {
+                const trimmed = line.trim();
+                if (trimmed.startsWith("#") || !trimmed)
+                    continue;
+                // Version (top-level)
+                if (trimmed.startsWith("version:") && !rule) {
+                    config.version = trimmed.split(":")[1]?.trim().replace(/['"]/g, "");
+                    continue;
+                }
+                // Rule pattern
+                const ruleMatch = trimmed.match(/^-?\s*pattern:\s*["'](.+?)["']/);
+                if (ruleMatch && trimmed.startsWith("-") && !section) {
+                    rule = { pattern: ruleMatch[1], must_not: [], must: [] };
+                    continue;
+                }
+                // Nested pattern inside must_not (may start with "- ")
+                if ((trimmed.startsWith("pattern:") || trimmed.startsWith("- pattern:")) && section === "must_not") {
+                    // Extract everything after "pattern:" and unquote
+                    const raw = trimmed.replace(/^-?\s*pattern:\s*/, "").trim();
+                    const unquoted = raw.replace(/^["']|["']$/g, "");
+                    if (unquoted) {
+                        violation = { pattern: unquoted, message: "" };
+                    }
+                    continue;
+                }
+                // Section headers
+                if (trimmed === "must_not:" || trimmed.startsWith("must_not:")) {
+                    section = "must_not";
+                    continue;
+                }
+                if (trimmed === "must:") {
+                    section = "must";
+                    continue;
+                }
+                // Message for current violation
+                if (trimmed.startsWith("message:") && violation) {
+                    const match = trimmed.match(/message:\s*["'](.+?)["']/);
+                    if (match) {
+                        violation.message = match[1];
+                        if (rule) {
+                            rule.must_not = rule.must_not ?? [];
+                            rule.must_not.push(violation);
+                        }
+                        violation = null;
+                    }
+                    continue;
+                }
+                // Must items (simple strings)
+                if (section === "must" && trimmed.startsWith("- ") && rule) {
+                    const item = trimmed.slice(2).replace(/^["']|["']$/g, "");
+                    rule.must = rule.must ?? [];
+                    rule.must.push(item);
+                }
+                // max_lines setting
+                if (trimmed.startsWith("max_lines:") && rule) {
+                    const num = parseInt(trimmed.split(":")[1]?.trim(), 10);
+                    if (!Number.isNaN(num)) {
+                        rule.max_lines = num;
+                    }
+                }
+            }
+            if (rule) {
+                config.rules.push(rule);
+            }
+        }
+        return config;
+    }
+}
+// --- Singleton ---
+let instance = null;
+export function getArchitectClient(verbose = false) {
+    if (!instance) {
+        instance = new ArchitectClient(verbose);
+    }
+    return instance;
+}

package/clients/architect-client.ts

@@ -0,0 +1,273 @@
+/**
+ * Architect Client for pi-lens
+ *
+ * Loads path-based architectural rules from .pi-lens/architect.yaml
+ * and checks file paths against them.
+ *
+ * Provides:
+ * - Pre-write hints: what rules apply before the agent edits
+ * - Post-write validation: check for violations after edits
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { minimatch } from "minimatch";
+
+// --- Types ---
+
+export interface ArchitectViolation {
+	pattern: string;
+	message: string;
+}
+
+export interface ArchitectRule {
+	pattern: string;
+	must_not?: Array<{ pattern: string; message: string }>;
+	must?: string[];
+	max_lines?: number;
+}
+
+export interface ArchitectConfig {
+	version?: string;
+	inherits?: string[];
+	rules: ArchitectRule[];
+}
+
+export interface FileArchitectResult {
+	filePath: string;
+	matchedRules: ArchitectRule[];
+	violations: ArchitectViolation[];
+}
+
+// --- Client ---
+
+export class ArchitectClient {
+	private config: ArchitectConfig | null = null;
+	private configPath: string | null = null;
+	private log: (msg: string) => void;
+
+	constructor(verbose = false) {
+		this.log = verbose
+			? (msg: string) => console.error(`[architect] ${msg}`)
+			: () => {};
+	}
+
+	/**
+	 * Load architect config from project root
+	 */
+	loadConfig(projectRoot: string): boolean {
+		// Try common locations
+		const candidates = [
+			path.join(projectRoot, ".pi-lens", "architect.yaml"),
+			path.join(projectRoot, "architect.yaml"),
+			path.join(projectRoot, ".pi-lens", "architect.yml"),
+		];
+
+		for (const configPath of candidates) {
+			try {
+				const content = fs.readFileSync(configPath, "utf-8");
+				this.config = this.parseYaml(content);
+				this.configPath = configPath;
+				this.log(`Loaded architect config from ${configPath}`);
+				return true;
+			} catch (error) {
+				this.log(`Could not read ${configPath}: ${error}`);
+				continue;
+			}
+		}
+
+		this.log("No architect.yaml found");
+		return false;
+	}
+
+	/**
+	 * Check if config is loaded
+	 */
+	hasConfig(): boolean {
+		return this.config !== null;
+	}
+
+	/**
+	 * Get rules that apply to a file path
+	 */
+	getRulesForFile(filePath: string): ArchitectRule[] {
+		if (!this.config) return [];
+
+		const matched: ArchitectRule[] = [];
+		for (const rule of this.config.rules) {
+			if (minimatch(filePath, rule.pattern, { matchBase: true })) {
+				matched.push(rule);
+			}
+		}
+		return matched;
+	}
+
+	/**
+	 * Check code content against rules for a file path
+	 * Returns violations found
+	 */
+	checkFile(filePath: string, content: string): ArchitectViolation[] {
+		const rules = this.getRulesForFile(filePath);
+		const violations: ArchitectViolation[] = [];
+
+		for (const rule of rules) {
+			if (!rule.must_not) continue;
+
+			for (const check of rule.must_not) {
+				const regex = new RegExp(check.pattern, "i");
+				if (regex.test(content)) {
+					violations.push({
+						pattern: rule.pattern,
+						message: check.message,
+					});
+				}
+			}
+		}
+
+		return violations;
+	}
+
+	/**
+	 * Check file size against max_lines rule
+	 * Returns violation if file exceeds the limit
+	 */
+	checkFileSize(filePath: string, lineCount: number): ArchitectViolation | null {
+		const rules = this.getRulesForFile(filePath);
+
+		for (const rule of rules) {
+			if (rule.max_lines && lineCount > rule.max_lines) {
+				return {
+					pattern: rule.pattern,
+					message: `File is ${lineCount} lines — exceeds ${rule.max_lines} line limit. Split into smaller modules.`,
+				};
+			}
+		}
+		return null;
+	}
+
+	/**
+	 * Get pre-write hints for a file path
+	 * Returns rules that will apply to the file being written
+	 */
+	getHints(filePath: string): string[] {
+		const rules = this.getRulesForFile(filePath);
+		const hints: string[] = [];
+
+		for (const rule of rules) {
+			if (rule.must_not) {
+				for (const check of rule.must_not) {
+					hints.push(check.message);
+				}
+			}
+			if (rule.must) {
+				for (const req of rule.must) {
+					hints.push(`Must: ${req}`);
+				}
+			}
+		}
+
+		return hints;
+	}
+
+	/**
+	 * Simple YAML parser for architect.yaml format
+	 * Handles the specific structure we need
+	 */
+	private parseYaml(content: string): ArchitectConfig {
+		const config: ArchitectConfig = { rules: [] };
+
+		// Split into top-level rule blocks (4-space indent "- pattern:")
+		const ruleBlocks = content.split(/(?=^  - pattern:)/m);
+
+		for (const block of ruleBlocks) {
+			const lines = block.split("\n");
+			let rule: ArchitectRule | null = null;
+			let section: "must_not" | "must" | null = null;
+			let violation: { pattern: string; message: string } | null = null;
+
+			for (const line of lines) {
+				const trimmed = line.trim();
+				if (trimmed.startsWith("#") || !trimmed) continue;
+
+				// Version (top-level)
+				if (trimmed.startsWith("version:") && !rule) {
+					config.version = trimmed.split(":")[1]?.trim().replace(/['"]/g, "");
+					continue;
+				}
+
+				// Rule pattern
+				const ruleMatch = trimmed.match(/^-?\s*pattern:\s*["'](.+?)["']/);
+				if (ruleMatch && trimmed.startsWith("-") && !section) {
+					rule = { pattern: ruleMatch[1], must_not: [], must: [] };
+					continue;
+				}
+				// Nested pattern inside must_not (may start with "- ")
+				if ((trimmed.startsWith("pattern:") || trimmed.startsWith("- pattern:")) && section === "must_not") {
+					// Extract everything after "pattern:" and unquote
+					const raw = trimmed.replace(/^-?\s*pattern:\s*/, "").trim();
+					const unquoted = raw.replace(/^["']|["']$/g, "");
+					if (unquoted) {
+						violation = { pattern: unquoted, message: "" };
+					}
+					continue;
+				}
+
+				// Section headers
+				if (trimmed === "must_not:" || trimmed.startsWith("must_not:")) {
+					section = "must_not";
+					continue;
+				}
+				if (trimmed === "must:") {
+					section = "must";
+					continue;
+				}
+
+				// Message for current violation
+				if (trimmed.startsWith("message:") && violation) {
+					const match = trimmed.match(/message:\s*["'](.+?)["']/);
+					if (match) {
+						violation.message = match[1];
+						if (rule) {
+							rule.must_not = rule.must_not ?? [];
+							rule.must_not.push(violation);
+						}
+						violation = null;
+					}
+					continue;
+				}
+
+				// Must items (simple strings)
+				if (section === "must" && trimmed.startsWith("- ") && rule) {
+					const item = trimmed.slice(2).replace(/^["']|["']$/g, "");
+					rule.must = rule.must ?? [];
+					rule.must.push(item);
+				}
+
+				// max_lines setting
+				if (trimmed.startsWith("max_lines:") && rule) {
+					const num = parseInt(trimmed.split(":")[1]?.trim(), 10);
+					if (!Number.isNaN(num)) {
+						rule.max_lines = num;
+					}
+				}
+			}
+
+			if (rule) {
+				config.rules.push(rule);
+			}
+		}
+
+		return config;
+	}
+}
+
+// --- Singleton ---
+
+let instance: ArchitectClient | null = null;
+
+export function getArchitectClient(verbose = false): ArchitectClient {
+	if (!instance) {
+		instance = new ArchitectClient(verbose);
+	}
+	return instance;
+}

package/clients/jscpd-client.js

@@ -57,7 +57,7 @@ export class JscpdClient {
                 "--output",
                 outDir,
                 "--ignore",
-                "**/node_modules/**,**/dist/**,**/build/**,**/.git/**,**/.pi-lens/**,**/*.md,**/*.txt,**/*.json,**/*.yaml,**/*.yml,**/*.toml,**/*.lock",
+                "**/node_modules/**,**/dist/**,**/build/**,**/.git/**,**/.pi-lens/**,**/*.md,**/*.txt,**/*.json,**/*.yaml,**/*.yml,**/*.toml,**/*.lock,**/*.test.*,**/*.spec.*",
             ], {
                 encoding: "utf-8",
                 timeout: 30000,

package/clients/jscpd-client.ts

@@ -86,7 +86,7 @@ export class JscpdClient {
 					"--output",
 					outDir,
 					"--ignore",
-					"**/node_modules/**,**/dist/**,**/build/**,**/.git/**,**/.pi-lens/**,**/*.md,**/*.txt,**/*.json,**/*.yaml,**/*.yml,**/*.toml,**/*.lock",
+					"**/node_modules/**,**/dist/**,**/build/**,**/.git/**,**/.pi-lens/**,**/*.md,**/*.txt,**/*.json,**/*.yaml,**/*.yml,**/*.toml,**/*.lock,**/*.test.*,**/*.spec.*",
 				],
 				{
 					encoding: "utf-8",

package/clients/scan-architectural-debt.js

@@ -1,6 +1,6 @@
 /**
  * Shared architectural debt scanning — used by booboo-fix and booboo-refactor.
- * Scans ast-grep skip rules + complexity metrics, scores files by combined signal.
+ * Scans ast-grep skip rules + complexity metrics + architect.yaml rules.
  */
 import * as fs from "node:fs";
 import * as path from "node:path";
@@ -73,11 +73,56 @@ export function scanComplexityMetrics(complexityClient, targetPath, isTsProject)
     scanDir(targetPath);
     return metricsByFile;
 }
+/**
+ * Scan for architectural rule violations grouped by absolute file path.
+ * Returns map of absolute file path → list of violation messages.
+ */
+export function scanArchitectViolations(architectClient, targetPath) {
+    const violationsByFile = new Map();
+    if (!architectClient.hasConfig())
+        return violationsByFile;
+    const scanDir = (dir) => {
+        if (!fs.existsSync(dir))
+            return;
+        for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+            const full = path.join(dir, entry.name);
+            if (entry.isDirectory()) {
+                if (["node_modules", ".git", "dist", "build", ".next", ".pi-lens"].includes(entry.name))
+                    continue;
+                scanDir(full);
+            }
+            else if (/\.(ts|tsx|js|jsx|py|go|rs)$/.test(entry.name)) {
+                const relPath = path.relative(targetPath, full).replace(/\\/g, "/");
+                const content = fs.readFileSync(full, "utf-8");
+                const lineCount = content.split("\n").length;
+                const msgs = [];
+                // Check pattern violations
+                for (const v of architectClient.checkFile(relPath, content)) {
+                    msgs.push(v.message);
+                }
+                // Check file size
+                const sizeV = architectClient.checkFileSize(relPath, lineCount);
+                if (sizeV) {
+                    msgs.push(sizeV.message);
+                }
+                if (msgs.length > 0) {
+                    violationsByFile.set(full, msgs);
+                }
+            }
+        }
+    };
+    scanDir(targetPath);
+    return violationsByFile;
+}
 /**
  * Score each file by combined debt signal. Higher = worse.
  */
-export function scoreFiles(skipByFile, metricsByFile) {
-    const allFiles = new Set([...skipByFile.keys(), ...metricsByFile.keys()]);
+export function scoreFiles(skipByFile, metricsByFile, architectViolations) {
+    const allFiles = new Set([
+        ...skipByFile.keys(),
+        ...metricsByFile.keys(),
+        ...(architectViolations?.keys() ?? []),
+    ]);
     return [...allFiles]
         .map((file) => {
         let score = 0;
@@ -108,6 +153,11 @@ export function scoreFiles(skipByFile, metricsByFile) {
             else
                 score += 1;
         }
+        // Architect violations are high-priority signals
+        const archMsgs = architectViolations?.get(file);
+        if (archMsgs && archMsgs.length > 0) {
+            score += archMsgs.length * 3; // Each violation = 3 points
+        }
         return { file, score };
     })
         .filter((f) => f.score > 0)

package/clients/scan-architectural-debt.ts

@@ -1,11 +1,12 @@
 /**
  * Shared architectural debt scanning — used by booboo-fix and booboo-refactor.
- * Scans ast-grep skip rules + complexity metrics, scores files by combined signal.
+ * Scans ast-grep skip rules + complexity metrics + architect.yaml rules.
  */
 import * as fs from "node:fs";
 import * as path from "node:path";
 import type { AstGrepClient } from "./ast-grep-client.js";
 import type { ComplexityClient } from "./complexity-client.js";
+import type { ArchitectClient } from "./architect-client.js";
 
 export type SkipIssue = { rule: string; line: number; note: string };
 export type FileMetrics = { mi: number; cognitive: number; nesting: number };
@@ -86,14 +87,64 @@ export function scanComplexityMetrics(
 	return metricsByFile;
 }
 
+/**
+ * Scan for architectural rule violations grouped by absolute file path.
+ * Returns map of absolute file path → list of violation messages.
+ */
+export function scanArchitectViolations(
+	architectClient: ArchitectClient,
+	targetPath: string,
+): Map<string, string[]> {
+	const violationsByFile = new Map<string, string[]>();
+	if (!architectClient.hasConfig()) return violationsByFile;
+
+	const scanDir = (dir: string) => {
+		if (!fs.existsSync(dir)) return;
+		for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+			const full = path.join(dir, entry.name);
+			if (entry.isDirectory()) {
+				if (["node_modules", ".git", "dist", "build", ".next", ".pi-lens"].includes(entry.name)) continue;
+				scanDir(full);
+			} else if (/\.(ts|tsx|js|jsx|py|go|rs)$/.test(entry.name)) {
+				const relPath = path.relative(targetPath, full).replace(/\\/g, "/");
+				const content = fs.readFileSync(full, "utf-8");
+				const lineCount = content.split("\n").length;
+				const msgs: string[] = [];
+
+				// Check pattern violations
+				for (const v of architectClient.checkFile(relPath, content)) {
+					msgs.push(v.message);
+				}
+
+				// Check file size
+				const sizeV = architectClient.checkFileSize(relPath, lineCount);
+				if (sizeV) {
+					msgs.push(sizeV.message);
+				}
+
+				if (msgs.length > 0) {
+					violationsByFile.set(full, msgs);
+				}
+			}
+		}
+	};
+	scanDir(targetPath);
+	return violationsByFile;
+}
+
 /**
  * Score each file by combined debt signal. Higher = worse.
  */
 export function scoreFiles(
 	skipByFile: Map<string, SkipIssue[]>,
 	metricsByFile: Map<string, FileMetrics>,
+	architectViolations?: Map<string, string[]>,
 ): { file: string; score: number }[] {
-	const allFiles = new Set([...skipByFile.keys(), ...metricsByFile.keys()]);
+	const allFiles = new Set([
+		...skipByFile.keys(),
+		...metricsByFile.keys(),
+		...(architectViolations?.keys() ?? []),
+	]);
 	return [...allFiles]
 		.map((file) => {
 			let score = 0;
@@ -108,6 +159,11 @@ export function scoreFiles(
 				else if (issue.rule === "no-as-any") score += 2;
 				else score += 1;
 			}
+			// Architect violations are high-priority signals
+			const archMsgs = architectViolations?.get(file);
+			if (archMsgs && archMsgs.length > 0) {
+				score += archMsgs.length * 3; // Each violation = 3 points
+			}
 			return { file, score };
 		})
 		.filter((f) => f.score > 0)

package/index.ts

@@ -35,6 +35,7 @@ import {
 	TypeSafetyClient,
 	getTypeSafetyClient,
 } from "./clients/type-safety-client.js";
+import { ArchitectClient } from "./clients/architect-client.js";
 import { DependencyChecker } from "./clients/dependency-checker.js";
 import { GoClient } from "./clients/go-client.js";
 import { JscpdClient } from "./clients/jscpd-client.js";
@@ -47,7 +48,7 @@ import { TodoScanner } from "./clients/todo-scanner.js";
 import { TypeCoverageClient } from "./clients/type-coverage-client.js";
 import { TypeScriptClient } from "./clients/typescript-client.js";
 import { buildInterviewer, type InterviewOption } from "./clients/interviewer.js";
-import { scanSkipViolations, scanComplexityMetrics, scoreFiles, extractCodeSnippet, type SkipIssue, type FileMetrics } from "./clients/scan-architectural-debt.js";
+import { scanSkipViolations, scanComplexityMetrics, scanArchitectViolations, scoreFiles, extractCodeSnippet, type SkipIssue, type FileMetrics } from "./clients/scan-architectural-debt.js";
 
 const DEBUG_LOG = path.join(os.homedir(), "pi-lens-debug.log");
 function dbg(msg: string) {
@@ -62,6 +63,7 @@ function dbg(msg: string) {
 // --- State ---
 
 let _verbose = false;
+let projectRoot = process.cwd();
 
 function log(msg: string) {
 	if (_verbose) console.error(`[pi-lens] ${msg}`);
@@ -83,6 +85,7 @@ export default function (pi: ExtensionAPI) {
 	const metricsClient = new MetricsClient();
 	const complexityClient = new ComplexityClient();
 	const typeSafetyClient = new TypeSafetyClient();
+	const architectClient = new ArchitectClient();
 	const goClient = new GoClient();
 	const rustClient = new RustClient();
 
@@ -578,6 +581,55 @@ export default function (pi: ExtensionAPI) {
 				}
 			}
 
+			// Part 9: Architectural Rules
+			if (architectClient.hasConfig()) {
+				const archViolations: Array<{ file: string; message: string }> = [];
+				const archScanDir = (dir: string) => {
+					for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+						const full = path.join(dir, entry.name);
+						if (entry.isDirectory()) {
+							if (
+								["node_modules", ".git", "dist", "build", ".next", ".pi-lens"].includes(
+									entry.name,
+								)
+							)
+								continue;
+							archScanDir(full);
+						} else if (/\.(ts|tsx|js|jsx|py|go|rs)$/.test(entry.name)) {
+							const relPath = path.relative(targetPath, full).replace(/\\/g, "/");
+							const content = fs.readFileSync(full, "utf-8");
+							const lineCount = content.split("\n").length;
+
+							// Check pattern violations
+							const violations = architectClient.checkFile(relPath, content);
+							for (const v of violations) {
+								archViolations.push({ file: relPath, message: v.message });
+							}
+
+							// Check file size
+							const sizeV = architectClient.checkFileSize(relPath, lineCount);
+							if (sizeV) {
+								archViolations.push({ file: relPath, message: sizeV.message });
+							}
+						}
+					}
+				};
+				archScanDir(targetPath);
+
+				if (archViolations.length > 0) {
+					parts.push(
+						`🔴 ${archViolations.length} architectural violation(s) — fix before adding new code`,
+					);
+					let fullSection = `## Architectural Rules\n\n`;
+					fullSection += `**${archViolations.length} violation(s) found**\n\n`;
+					for (const v of archViolations) {
+						fullSection += `- **${v.file}**: ${v.message}\n`;
+					}
+					fullSection += "\n";
+					fullReport.push(fullSection);
+				}
+			}
+
 			// Build and save full markdown report
 			const fs = require("node:fs");
 			fs.mkdirSync(reviewDir, { recursive: true });
@@ -1190,7 +1242,10 @@ export default function (pi: ExtensionAPI) {
 
 			const skipByFile = scanSkipViolations(astGrepClient, configPath, targetPath, isTsProject, SKIP_RULES, RULE_ACTIONS);
 			const metricsByFile = scanComplexityMetrics(complexityClient, targetPath, isTsProject);
-			const scored = scoreFiles(skipByFile, metricsByFile);
+			const architectViolations = architectClient.hasConfig()
+				? scanArchitectViolations(architectClient, targetPath)
+				: new Map<string, string[]>();
+			const scored = scoreFiles(skipByFile, metricsByFile, architectViolations);
 
 			if (scored.length === 0) {
 				ctx.ui.notify("✅ No architectural debt found — codebase is clean.", "info");
@@ -1201,6 +1256,7 @@ export default function (pi: ExtensionAPI) {
 			const relFile = path.relative(targetPath, worstFile).replace(/\\/g, "/");
 			const issues = skipByFile.get(worstFile) ?? [];
 			const metrics = metricsByFile.get(worstFile);
+			const archIssues = architectViolations.get(worstFile) ?? [];
 
 			const snippetResult = issues.length > 0 ? extractCodeSnippet(worstFile, issues[0].line) : null;
 			const snippet = snippetResult?.snippet ?? "";
@@ -1218,6 +1274,9 @@ export default function (pi: ExtensionAPI) {
 						`- \`${r}\` (×${n})${RULE_ACTIONS[r] ? ` — ${RULE_ACTIONS[r].note}` : ""}`,
 				)
 				.join("\n");
+			const archSummary = archIssues.length > 0
+				? archIssues.map((m) => `- ${m}`).join("\n")
+				: "None";
 			const metricsSummary = metrics
 				? `MI: ${metrics.mi.toFixed(1)}, Cognitive: ${metrics.cognitive}, Nesting: ${metrics.nesting}`
 				: "";
@@ -1230,6 +1289,7 @@ export default function (pi: ExtensionAPI) {
 				metrics ? `**Complexity**: ${metricsSummary}` : "",
 				"",
 				issues.length > 0 ? `**Violations**:\n${issuesSummary}` : "",
+				archIssues.length > 0 ? `**Architectural rules violated**:\n${archSummary}` : "",
 				"",
 				`**Code** (\`${relFile}\` lines ${snippetStart}–${snippetEnd}):`,
 				"```typescript",
@@ -1773,8 +1833,13 @@ export default function (pi: ExtensionAPI) {
 		dbg(`session_start tools: ${tools.join(", ")}`);
 
 		const cwd = ctx.cwd ?? process.cwd();
+		projectRoot = cwd; // Module-level for architect client
 		dbg(`session_start cwd: ${cwd}`);
 
+		// Load architect rules if present
+		const hasArchitectRules = architectClient.loadConfig(cwd);
+		if (hasArchitectRules) tools.push("Architect rules");
+
 		// Log test runner if detected
 		const detectedRunner = testRunnerClient.detectRunner(cwd);
 		if (detectedRunner) {
@@ -1907,6 +1972,18 @@ export default function (pi: ExtensionAPI) {
 			);
 		}
 
+		// Architectural rules pre-write hints
+		if (architectClient.hasConfig()) {
+			const relPath = path.relative(projectRoot, filePath).replace(/\\/g, "/");
+			const archHints = architectClient.getHints(relPath);
+			if (archHints.length > 0) {
+				hints.push(`📐 Architectural rules for ${relPath}:`);
+				for (const h of archHints) {
+					hints.push(`  → ${h}`);
+				}
+			}
+		}
+
 		dbg(`  pre-write hints: ${hints.length} — ${hints.join(" | ") || "none"}`);
 		if (hints.length > 0) {
 			preWriteHints.set(filePath, hints.join("\n"));
@@ -2052,6 +2129,29 @@ export default function (pi: ExtensionAPI) {
 			}
 		}
 
+		// Architectural rule validation (post-write)
+		if (architectClient.hasConfig() && fs.existsSync(filePath)) {
+			const relPath = path.relative(projectRoot, filePath).replace(/\\/g, "/");
+			const content = fs.readFileSync(filePath, "utf-8");
+			const lineCount = content.split("\n").length;
+
+			// Check for violations
+			const violations = architectClient.checkFile(relPath, content);
+			if (violations.length > 0) {
+				lspOutput += `\n\n🔴 Architectural violation(s) in ${relPath}:\n`;
+				for (const v of violations) {
+					lspOutput += `  → ${v.message}\n`;
+				}
+			}
+
+			// Check file size limit — hard stop, file is too large to reason about
+			const sizeViolation = architectClient.checkFileSize(relPath, lineCount);
+			if (sizeViolation) {
+				lspOutput += `\n\n🔴 STOP — ${sizeViolation.message}\n`;
+				lspOutput += `    → Split into smaller, focused modules before adding more code.\n`;
+			}
+		}
+
 		// ast-grep structural analysis — delta mode (only show new violations)
 		if (!pi.getFlag("no-ast-grep") && astGrepClient.isAvailable()) {
 			const after = astGrepClient.scanFile(filePath);

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-lens",
-	"version": "2.0.29",
+	"version": "2.0.35",
 	"description": "Real-time code quality feedback for pi — TypeScript LSP, Biome, ast-grep, Ruff, complexity metrics, duplicate detection. Includes automated fix loop (/lens-booboo-fix) and interactive architectural refactoring (/lens-booboo-refactor) with browser-based interviews.",
 	"repository": {
 		"type": "git",