pi-lens 2.2.9 → 3.0.0

package/README.md

@@ -1,519 +1,709 @@
-# pi-lens
-
-Real-time code quality feedback for [pi](https://github.com/mariozechner/pi-coding-agent). Every write and edit is automatically analysed — diagnostics are injected directly into the tool result so the agent sees them without any extra steps.
-
-## Install
-
-```bash
-pi install npm:pi-lens
-```
-
-Or directly from git:
-
-```bash
-pi install git:github.com/apmantza/pi-lens
-```
-
----
-
-## Features
-
-### On every write / edit
-
-Every file write is automatically checked. Blocking issues appear inline:
-
-```
-🔴 STOP — 1 issue(s) must be fixed:
-  L23: var total = sum(items); — use 'let' or 'const'
-```
-
-**Runners:** TypeScript type-checking, Python type-checking (pyright), linting (ruff, biome), secrets scan, architectural rules.
-
-### Code quality scoring
-
-```
-/lens-rate
-```
-
-```
-📊 CODE QUALITY SCORE: 85/100 (B)
-┌─────────────────────────────────────────────────────────┐
-│  🔷 Type Safety  🟩🟩🟩🟩🟩🟩🟩🟩⬜⬜  85 │
-│  🧩 Complexity   🟩🟩🟩🟩🟩🟩🟩🟩⬜⬜  82 │
-│  🔒 Security     🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩 100 │
-│  🏗️ Architecture  🟩🟩🟩🟩🟩🟩🟩🟩⬜⬜  80 │
-│  🗑️ Dead Code    🟩🟩🟩🟩🟩🟩🟩🟩🟩⬜  90 │
-│  ✅ Tests        🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩 100 │
-└─────────────────────────────────────────────────────────┘
-```
-
-### On-demand commands
-
-| Command | What it does |
-|---------|--------------|
-| `/lens-booboo` | Full codebase review (design smells, complexity, dead code, duplicates, type coverage) |
-| `/lens-booboo-fix` | Automated mechanical fixes for lint issues |
-| `/lens-booboo-refactor` | Interactive architectural refactoring |
-| `/lens-rate` | Code quality score with visual breakdown |
-| `/lens-metrics` | Complexity metrics for all files |
-| `/lens-format` | Apply Biome formatting |
-
-### Context-aware rules
-
-Rules are automatically skipped for test files — no more `no-console-log` warnings in `*.test.ts`.
-
-### Project rules integration
-
-Scans for `.claude/rules/`, `.agents/rules/`, `CLAUDE.md`, `AGENTS.md` at session start. Project-specific rules are surfaced in the system prompt.
-
-### Secret scanning
-
-Catches secrets in ANY file type on write/edit — `.env`, `.yaml`, `.json`, not just TypeScript:
-
-```
-🔴 STOP — 1 potential secret(s) in src/config.ts:
-  L12: Possible Stripe or OpenAI API key (sk-*)
-  → Remove before continuing. Use env vars instead.
-```
-
-### Delta-mode feedback
-
-First edit: full feedback. Subsequent edits: only NEW issues. Pre-existing issues are tracked and excluded from inline output.
-
----
-
-## Dependent Tools
-
-pi-lens works out of the box for TypeScript/JavaScript. For full language support, install these tools — **all are optional and gracefully skip if not installed**:
-
-### JavaScript / TypeScript
-
-| Tool | Install | What it does |
-|------|---------|--------------|
-| `@biomejs/biome` | `npm i -D @biomejs/biome` | Linting + formatting |
-| `knip` | `npm i -D knip` | Dead code / unused exports |
-| `jscpd` | `npm i -D jscpd` | Copy-paste detection |
-| `type-coverage` | `npm i -D type-coverage` | TypeScript `any` coverage % |
-
-### Python
-
-| Tool | Install | What it does |
-|------|---------|--------------|
-| `ruff` | `pip install ruff` | Linting + formatting |
-| `pyright` | `pip install pyright` | Type-checking (catches type errors) |
-
-### Go
-
-| Tool | Install | What it does |
-|------|---------|--------------|
-| `go` | [golang.org](https://golang.org) | Built-in `go vet` for static analysis |
-
-### Rust
-
-| Tool | Install | What it does |
-|------|---------|--------------|
-| `rust` + `clippy` | [rustup.rs](https://rustup.rs) | Linting via `cargo clippy` |
-
-### All Languages
-
-| Tool | Install | What it does |
-|------|---------|--------------|
-| `@ast-grep/cli` | `npm i -D @ast-grep/cli` | Structural pattern matching (80+ rules) |
-
----
-
-## Flags
-
-| Flag | Description |
-|------|-------------|
-| `--lens-verbose` | Enable console logging |
-| `--autofix-biome` | Auto-fix lint issues with Biome |
-
----
-
-## Rules
-
-pi-lens includes 80+ ast-grep rules for:
-
-## ast-grep rules
-
-Rules live in `rules/ast-grep-rules/rules/`. All rules are YAML files you can edit or extend.
-
-Each rule includes a `message` and `note` that are shown in diagnostics, so the agent understands why something violated a rule and how to fix it.
-
-**Security**
-`no-eval`, `no-implied-eval`, `no-hardcoded-secrets`, `no-insecure-randomness`, `no-open-redirect`, `no-sql-in-code`, `no-inner-html`, `no-dangerously-set-inner-html`, `no-javascript-url`
-
-**TypeScript**
-`no-any-type`, `no-as-any`, `no-non-null-assertion`
-
-**Style** (Biome handles `no-var`, `prefer-const`, `prefer-template`, `no-useless-concat` natively)
-`prefer-nullish-coalescing`, `prefer-optional-chain`, `nested-ternary`, `no-lonely-if`
-
-**Correctness**
-`no-debugger`, `no-throw-string`, `no-return-await`, `no-await-in-loop`, `no-await-in-promise-all`, `require-await`, `empty-catch`, `strict-equality`, `strict-inequality`
-
-**Patterns**
-`no-console-log`, `no-alert`, `no-delete-operator`, `no-shadow`, `no-star-imports`, `switch-needs-default`, `switch-without-default`
-
-**Type Safety** (type-aware checks via `type-safety-client.ts`)
-`switch-exhaustiveness` — detects missing cases in union type switches (inline blocker)
-
-**Design Smells**
-`long-method`, `long-parameter-list`, `large-class`
-
-**AI Slop Detection**
-`no-param-reassign`, `no-single-char-var`, `no-process-env`, `no-architecture-violation`
-
----
-
-## TypeScript LSP — tsconfig detection
-
-The LSP walks up from the edited file's directory until it finds a `tsconfig.json`. If found, it uses that project's exact `compilerOptions` (paths, strict settings, lib, etc.). If not found, it falls back to sensible defaults:
-
-- `target: ES2020`
-- `lib: ["es2020", "dom", "dom.iterable"]`
-- `moduleResolution: bundler`
-- `strict: true`
-
-The compiler options are refreshed automatically when you switch between projects within a session.
-
----
-
-
----
-
-## Changelog
-
-
-## [2.1.1] - 2026-03-29
-
-### Added
-- **Content-level secret scanning**: Catches secrets in ANY file type on write/edit (`.env`, `.yaml`, `.json`, not just TypeScript). Blocks before save with patterns for `sk-*`, `ghp_*`, `AKIA*`, private keys, hardcoded passwords.
-- **Project rules integration**: Scans for `.claude/rules/`, `.agents/rules/`, `CLAUDE.md`, `AGENTS.md` at session start and surfaces in system prompt.
-- **Grep-ability rules**: New ast-grep rules for `no-default-export` and `no-relative-cross-package-import` to improve agent searchability.
-
-### Changed
-- **Inline feedback stripped to blocking only**: Warnings no longer shown inline (noise). Only blocking violations and test failures interrupt the agent.
-- **booboo-fix output compacted**: Summary in terminal, full plan in `.pi-lens/reports/fix-plan.tsv`.
-- **booboo-refactor output compacted**: Top 5 worst offenders in terminal, full ranked list in `.pi-lens/reports/refactor-ranked.tsv`.
-- **`ast_grep_search` new params**: Added `selector` (extract specific AST node) and `context` (show surrounding lines).
-- **`ast_grep_replace` mode indicator**: Shows `[DRY-RUN]` or `[APPLIED]` prefix.
-- **no-hardcoded-secrets**: Fixed to only flag actual hardcoded strings (not `process.env` assignments).
-- **no-process-env**: Now only flags secret-related env vars (not PORT, NODE_ENV, etc.).
-- **Removed Factory AI article reference** from architect.yaml.
-
-## [2.0.40] - 2026-03-27
-
-### Changed
-- **Passive capture on every file edit**: `captureSnapshot()` now called from `tool_call` hook with 5s debounce. Zero latency — reuses complexity metrics already computed for real-time feedback.
-- **Skip duplicate snapshots**: Same commit + same MI = no write (reduces noise).
-
-## [2.0.39] - 2026-03-27
-
-### Added
-- **Historical metrics tracking**: New `clients/metrics-history.ts` module captures complexity snapshots per commit. Tracks MI, cognitive complexity, and nesting depth across sessions.
-- **Trend analysis in `/lens-metrics`**: New "Trend" column shows 📈/📉/➡️ with MI delta. "Trend Summary" section aggregates improving/stable/regressing counts with worst regressions.
-- **Passive capture**: Snapshots captured on every file edit (tool_call hook) + `/lens-metrics` run. Max 20 snapshots per file (sliding window).
-
-## [2.0.38] - 2026-03-27
-
-### Changed
-- **Refactored 4 client files** via `/lens-booboo-refactor` loop:
-  - `biome-client.ts`: Extracted `withValidatedPath()` guard pattern (4 methods consolidated)
-  - `complexity-client.ts`: Extracted `analyzeFile()` pipeline into `readAndParse()`, `computeMetrics()`, `aggregateFunctionStats()`
-  - `dependency-checker.ts`: Simplified `importsChanged()` — replaced 3 for-loops with `setsEqual()` helper
-  - `ast-grep-client.ts`: Simplified `groupSimilarFunctions()` with `filter().map()` pattern + `extractFunctionName()` helper
-
-## [2.0.29] - 2026-03-26
-
-### Added
-- **`clients/ts-service.ts`**: Shared TypeScript service that creates one `ts.Program` per session. Both `complexity-client` and `type-safety-client` now share the same program instead of creating a new one per file. Significant performance improvement on large codebases.
-
-### Removed
-- **3 redundant ast-grep rules** that overlap with Biome: `no-var`, `prefer-template`, `no-useless-concat`. Biome handles these natively with auto-fix. ast-grep no longer duplicates this coverage.
-- **`prefer-const` from RULE_ACTIONS** — no longer needed (Biome handles directly).
-
-### Changed
-- **Consolidated rule overlap**: Biome is now the single source of truth for style/format rules. ast-grep focuses on structural patterns Biome doesn't cover (security, design smells, AI slop).
-
-## [2.0.27] - 2026-03-26
-
-### Added
-- **`switch-exhaustiveness` check**: New type safety rule detects missing cases in union type switches. Uses TypeScript compiler API for type-aware analysis. Reports as inline blocker: `🔴 STOP — Switch on 'X' is not exhaustive. Missing cases: 'Y'`.
-- **`clients/type-safety-client.ts`**: New client for type safety checks. Extensible for future checks (null safety, exhaustive type guards).
-
-### Changed
-- **Type safety violations added to inline feedback**: Missing switch cases now block the agent mid-task, same as TypeScript errors.
-- **Type safety violations in `/lens-booboo-fix`**: Marked as agent-fixable (add missing case or default clause).
-
-## [2.0.26] - 2026-03-26
-
-### Added
-- **5 new ast-grep rules** for AI slop detection:
-  - `no-process-env`: Block direct `process.env` access (use DI or config module) — error level
-  - `no-param-reassign`: Detect function parameter reassignment — warning level
-  - `no-single-char-var`: Flag single-character variable names — info level
-  - `switch-without-default`: Ensure switch statements have default case — warning level
-  - `no-architecture-violation`: Block cross-layer imports (models/db) — error level
-
-### Changed
-- **RULE_ACTIONS updated** for new rules:
-  - `agent` type (inline + booboo-fix): `no-param-reassign`, `switch-without-default`, `switch-exhaustiveness`
-  - `skip` type (booboo-refactor only): `no-process-env`, `no-single-char-var`, `no-architecture-violation`
-
-## [2.0.24] - 2026-03-26
-
-### Changed
-- **Simplified `/lens-booboo-refactor` confirmation flow**: Post-change report instead of pre-change gate. Agent implements first, then shows what was changed (git diff + metrics delta). User reviews and can request refinements via chat. No more temp files or dry-run diffs.
-- **Confirmation screen**: "✅ Looks good — move to next offender" / "💬 Request changes" (chat textarea). Diff display is optional.
-
-## [2.0.23] - 2026-03-26
-
-### Changed
-- **Extracted interviewer and scan modules from `index.ts`**: `index.ts` reduced by 460 lines.
-  - `clients/interviewer.ts` — all browser interview infrastructure (HTML generation, HTTP server, browser launch, option selection, diff confirmation screen)
-  - `clients/scan-architectural-debt.ts` — shared scanning utilities (`scanSkipViolations`, `scanComplexityMetrics`, `scoreFiles`, `extractCodeSnippet`)
-- **`/lens-booboo-refactor`** now uses imported scan functions instead of duplicated inline code.
-
-## [2.0.22] - 2026-03-26
-
-### Added
-- **Impact metrics in interview options**: Each option now supports an `impact` object (`linesReduced`, `miProjection`, `cognitiveProjection`) rendered as colored badges in the browser form. Agent estimates impact when presenting refactoring options.
-- **Iterative confirmation loop**: Confirmation screen now includes "🔄 Describe a different approach" option with free-text textarea. Agent regenerates plan+diff based on feedback, re-opens confirmation. Repeat until user confirms or cancels.
-- **Auto-close on confirm**: Browser tab closes automatically after user submits.
-
-## [2.0.21] - 2026-03-26
-
-### Added
-- **Two-step confirmation for `/lens-booboo-refactor`**: Agent implements changes, then calls `interviewer` with `confirmationMode=true` to show plan (markdown) + unified diff (green/red line coloring) + line counts at the top. User can Confirm, Cancel, or describe a different approach.
-- **Plan + diff confirmation screen**: Plan rendered as styled markdown, diff rendered with syntax-colored `+`/`-` lines. Line counts (`+N / −N`) shown in diff header.
-
-## [2.0.20] - 2026-03-26
-
-### Added
-- **Impact metrics in interview options**: Structured `impact` field per option with `linesReduced`, `miProjection`, `cognitiveProjection`. Rendered as colored badges (green for lines reduced, blue for metric projections) inside each option card.
-
-## [2.0.19] - 2026-03-26
-
-### Changed
-- **`/lens-booboo-fix` jscpd filter**: Only within-file duplicates shown in actionable section. Cross-file duplicates are architectural — shown in skip section only.
-- **AI slop filter tightened**: Require 2+ signals per file (was 1+). Single-issue flags on small files are noise — skip them.
-
-## [2.0.18] - 2026-03-26
-
-### Fixed
-- **`/lens-booboo-fix` max iterations**: Session file auto-deletes when hitting max iterations. Previously blocked with a manual "delete .pi-lens/fix-session.json" message.
-
-## [2.0.17] - 2026-03-26
-
-### Changed
-- **Agent-driven option generation**: `/lens-booboo-refactor` no longer hardcodes refactoring options per violation type. The command scans and presents the problem + code to the agent; the agent analyzes the actual code and generates 3-5 contextual options with rationale and impact estimates. Calls the `interviewer` tool to present them.
-- **`interviewer` tool**: Generic, reusable browser-based interview mechanism. Accepts `question`, `options` (with `value`, `label`, `context`, `recommended`, `impact`), and `confirmationMode`. Zero dependencies — Node's built-in `http` module + platform CLI `open`/`start`/`xdg-open`.
-
-## [2.0.16] - 2026-03-26
-
-### Added
-- **`/lens-booboo-refactor`**: Interactive architectural refactor session. Scans for worst offender by combined debt score (ast-grep skip violations + complexity metrics). Opens a browser interview with the problem, code context, and AI-generated options. Steers the agent to propose a plan and wait for user confirmation before making changes.
-
-### Changed
-- **Inline tool_result suppresses skip-category rules**: `long-method`, `large-class`, `long-parameter-list`, `no-shadow`, `no-as-any`, `no-non-null-assertion`, `no-star-imports` no longer show as hard stops in real-time feedback. They are architectural — handled by `/lens-booboo-refactor` instead.
-
-## [2.0.15] - 2026-03-26
-
-### Removed
-- **Complexity metrics from real-time feedback**: MI, cognitive complexity, nesting depth, try/catch counts, and entropy scores removed from tool_result output. These were always noise — the agent never acted on "MI dropped to 5.6" mid-task. Metrics still available via `/lens-metrics` and `/lens-booboo`.
-- **Session summary injection**: The `[Session Start]` block (TODOs, dead code, jscpd, type-coverage) is no longer injected into the first tool result. Scans still run for caching purposes (exports, clones, baselines). Data surfaced on-demand via explicit commands.
-- **`/lens-todos`**: Removed (covered by `/lens-booboo`).
-- **`/lens-dead-code`**: Removed (covered by `/lens-booboo`).
-- **`/lens-deps`**: Removed — circular dep scan added to `/lens-booboo` as Part 8.
-
-### Changed
-- **Hardened stop signals**: New violations (ast-grep, Biome, jscpd, duplicate exports) now all use `🔴 STOP` framing. The agent is instructed to fix these before continuing.
-- **`/lens-booboo` now includes circular dependencies**: Added as Part 8 (after type coverage) using `depChecker.scanProject`.
-
-## [2.0.14] - 2026-03-26
-
-### Fixed
-- **`/lens-booboo-fix` excludes `.js` compiled output**: Detects `tsconfig.json` and excludes `*.js` from jscpd, ast-grep, and complexity scans. Prevents double-counting of the same code in `.ts` and `.js` forms.
-- **`raw-strings` rule added to skip list**: 230 false positives in CLI/tooling codebases.
-- **`typescript-client.ts` duplication**: Extracted `resolvePosition()`, `resolveTree()`, and `toLocations()` helpers, deduplicating 6+ LSP methods.
-- **All clients**: `console.log` → `console.error` in verbose loggers (stderr for debug, stdout for data).
-
-## [2.0.13] - 2026-03-26
-
-### Removed
-- **`raw-strings` ast-grep rule**: Not an AI-specific pattern. Humans write magic strings too. Biome handles style. Generated 230 false positives on first real run.
-
-## [2.0.12] - 2026-03-26
-
-### Fixed
-- **`/lens-booboo-fix` sequential scan order**: Reordered to Biome/Ruff → jscpd (duplicates) → knip (dead code) → ast-grep → AI slop → remaining Biome. Duplicates should be fixed before violations (fixing one fixes both). Dead code should be deleted before fixing violations in it.
-
-### Changed
-- **Remaining Biome section rephrased**: "These couldn't be auto-fixed even with `--unsafe` — fix each manually."
-
-## [2.0.11] - 2026-03-26
-
-### Added
-- **Circular dependency scan to `/lens-booboo`**: Added as Part 8, using `depChecker.scanProject()` to detect circular chains across the codebase.
-
-### Removed
-- **`/lens-todos`**, **`/lens-dead-code`**, **`/lens-deps`**: Removed standalone commands — all covered by `/lens-booboo`.
-
-## [2.0.10] - 2026-03-26
-
-### Changed
-- **Session summary injection removed**: The `[Session Start]` block is no longer injected into the first tool result. Scans still run silently for caching (exports for duplicate detection, clones for jscpd, complexity baselines for deltas).
-
-## [2.0.1] - 2026-03-25
-
-### Fixed
-- **ast-grep in `/lens-booboo` was silently dropping all results** — newer ast-grep versions exit `0` with `--json` even when issues are found; fixed the exit code check.
-- **Renamed "Design Smells" to "ast-grep"** in booboo report — the scan runs all 65 rules (security, correctness, style, design), not just design smells.
-
-### Changed
-- **Stronger real-time feedback messages** — all messages now use severity emoji and imperative language:
-  - `🔴 Fix N TypeScript error(s) — these must be resolved`
-  - `🧹 Remove N unused import(s) — they are dead code`
-  - `🔴 You introduced N new structural violation(s) — fix before moving on`
-  - `🟠 You introduced N new Biome violation(s) — fix before moving on`
-  - `🟡 Complexity issues — refactor when you get a chance`
-  - `🟠 This file has N duplicate block(s) — extract to shared utilities`
-  - `🔴 Do not redefine — N function(s) already exist elsewhere`
-- **Biome fix command is now a real bash command** — `npx @biomejs/biome check --write <file>` instead of `/lens-format` (which is a pi UI command, not runnable from agent tools).
-- **Complexity warnings skip test files in real-time** — same exclusion as lens-booboo.
-
-## [2.0.0] - 2026-03-25
-
-### Added
-- **`/lens-metrics` command**: Measure complexity metrics for all files. Exports a full `report.md` with A-F grades, summary stats, AI slop aggregate table, and top 10 worst files with actionable warnings.
-- **`/lens-booboo` saves full report**: Results saved to `.pi-lens/reviews/booboo-<timestamp>.md` — no truncation, all issues, agent-readable.
-- **AI slop indicators**: Four new real-time and report-based detectors:
-  - `AI-style comments` — emoji and boilerplate comment phrases
-  - `Many try/catch blocks` — lazy error handling pattern
-  - `Over-abstraction` — single-use helper functions
-  - `Long parameter list` — functions with > 6 params
-- **`SubprocessClient` base class**: Shared foundation for CLI tool clients (availability check, logging, command execution).
-- **Shared test utilities**: `createTempFile` and `setupTestEnvironment` extracted to `clients/test-utils.ts`, eliminating copy-paste across 13 test files.
-
-### Changed
-- **Delta mode for real-time feedback**: ast-grep and Biome now only show *new* violations introduced by the current edit — not all pre-existing ones. Fixed violations shown as `✓ Fixed: rule-name (-N)`. No change = silent.
-- **Removed redundant pre-write hints**: ast-grep and Biome pre-write counts removed (delta mode makes them obsolete). TypeScript pre-write warning kept (blocking errors).
-- **Test files excluded from AI slop warnings**: MI/complexity thresholds are inherently low in test files — warnings suppressed for `*.test.ts` / `*.spec.ts`.
-- **Test files excluded from TODO scanner**: Test fixture annotations (`FIXME`, `BUG`, etc.) no longer appear in TODO reports.
-- **ast-grep excludes test files and `.pi-lens/`**: Design smell scan in `/lens-booboo` skips test files (no magic-numbers noise) and internal review reports.
-- **jscpd excludes non-code files**: `.md`, `.json`, `.yaml`, `.yml`, `.toml`, `.lock`, and `.pi-lens/` excluded from duplicate detection — no more false positives from report files.
-- **Removed unused dependencies**: `vscode-languageserver-protocol` and `vscode-languageserver-types` removed; `@sinclair/typebox` added (was unlisted).
-
-### Fixed
-- Removed 3 unconditional `console.log` calls leaking `[scan_exports]` to terminal.
-- Duplicate Biome scan in `tool_call` hook eliminated (was scanning twice for pre-write hint + baseline).
-
-## [1.3.14] - 2026-03-25
-
-### Added
-- **Actionable feedback messages**: All real-time warnings now include specific guidance on what to do.
-- **Code entropy metric**: Shannon entropy in bits (threshold: >3.5 indicates risky AI-induced complexity).
-- **Advanced pattern matching**: `/lens-booboo` now finds structurally similar functions (e.g., `formatDate` and `formatTimestamp`).
-- **Duplicate export detection**: Warns when redefining a function that already exists in the codebase.
-- **Biome formatting noise removed**: Only lint issues shown in real-time; use `/lens-format` for formatting.
-
-## [1.3.10] - 2026-03-25
-
-### Added
-- **Actionable complexity warnings**: Real-time feedback when metrics break limits with specific fix guidance.
-
-## [1.3.9] - 2026-03-25
-
-### Fixed
-- **Entropy calculation**: Corrected to use bits with 3.5-bit threshold for AI-induced complexity.
-
-## [1.3.8] - 2026-03-25
-
-### Added
-- **Code entropy metric**: Shannon entropy to detect repetitive or unpredictable code patterns.
-
-## [1.3.7] - 2026-03-25
-
-### Added
-- **Advanced pattern matching in `/lens-booboo`**: Finds structurally similar functions across the codebase.
-
-## [1.3.6] - 2026-03-25
-
-### Added
-- **Duplicate export detection on write**: Warns when defining a function that already exists elsewhere.
-
-## [1.3.5] - 2026-03-25
-
-### Changed
-- **Consistent command prefix**: All commands now start with `lens-`.
-  - `/find-todos` → `/lens-todos`
-  - `/dead-code` → `/lens-dead-code`
-  - `/check-deps` → `/lens-deps`
-  - `/format` → `/lens-format`
-  - `/design-review` + `/lens-metrics` → `/lens-booboo`
-
-## [1.5.0] - 2026-03-23
-
-### Added
-- **Real-time jscpd duplicate detection**: Code duplication is now detected on every write. Duplicates involving the edited file are shown to the agent in real-time.
-- **`/lens-review` command**: Combined code review: design smells + complexity metrics in one command.
-
-### Changed
-- **Consistent command prefix**: All commands now start with `lens-`.
-  - `/find-todos` → `/lens-todos`
-  - `/dead-code` → `/lens-dead-code`
-  - `/check-deps` → `/lens-deps`
-  - `/format` → `/lens-format`
-  - `/design-review` + `/lens-metrics` → `/lens-review`
-
-## [1.4.0] - 2026-03-23
-
-### Added
-- **Test runner feedback**: Runs corresponding test file on every write (vitest, jest, pytest). Silent if no test file exists. Disable with `--no-tests`.
-- **Complexity metrics**: AST-based analysis: Maintainability Index, Cyclomatic/Cognitive Complexity, Halstead Volume, nesting depth, function length.
-- **`/lens-metrics` command**: Full project complexity scan.
-- **Design smell rules**: New `long-method`, `long-parameter-list`, and `large-class` rules for structural quality checks.
-- **`/design-review` command**: Analyze files for design smells. Usage: `/design-review [path]`
-- **Go language support**: New Go client for Go projects.
-- **Rust language support**: New Rust client for Rust projects.
-
-### Changed
-- **Improved ast-grep tool descriptions**: Better pattern guidance to prevent overly broad searches.
-
-## [2.2.1] - 2026-03-29
-
-### Fixed
-- **No auto-install**: Runners (biome, pyright) now use direct CLI commands instead of `npx`. If not installed, gracefully skip instead of attempting to download.
-
-## [2.2.0] - 2026-03-29
-
-### Added
-- **`/lens-rate` command**: Visual code quality scoring across 6 dimensions (Type Safety, Complexity, Security, Architecture, Dead Code, Tests). Shows grade A-F and colored progress bars.
-- **Pyright runner**: Real Python type-checking via pyright. Catches type errors like `result: str = add(1, 2)` that ruff misses. Runs alongside ruff (pyright for types, ruff for linting).
-- **Vitest config**: Increased test timeout to 15s for CLI spawn tests. Fixes flaky test failures when npx downloads packages.
-
-### Fixed
-- **Test flakiness**: Availability tests (biome, knip, jscpd) no longer timeout when npx is downloading packages.
-
-## [1.3.0] - 2026-03-23
-
-### Changed
-- **Biome auto-fix disabled by default**: Biome still provides linting feedback, but no longer auto-fixes on write. Use `/format` to apply fixes or enable with `--autofix-biome`.
-
-### Added
-- **ast-grep search/replace tools**: New `ast_grep_search` and `ast_grep_replace` tools for AST-aware code pattern matching. Supports meta-variables and 24 languages.
-- **Rule descriptions in diagnostics**: ast-grep violations now include the rule's message and note, making feedback more actionable for the agent.
-
-### Changed
-- **Reduced console noise**: Extension no longer prints to console by default. Enable with `--lens-verbose`.
-
-## [1.2.0] - 2026-03-23
-
-### Added
-- GitHub repository link in npm package
-
-## [1.1.2] - Previous
-
-- See git history for earlier releases
+# pi-lens
+
+Real-time code feedback for [pi](https://github.com/mariozechner/pi-coding-agent) — LSP, linters, formatters, type-checking, structural analysis (ast-grep), TODO scanner, dead code detection, duplicate detection, type coverage, complexity metrics, and AI slop detection.
+
+## What pi-lens Does
+
+**For every file you edit:**
+1. **Auto-formats** — Detects and runs formatters (Biome, Prettier, Ruff, gofmt, rustfmt, etc.)
+2. **Type-checks** TypeScript, Python, Go, Rust (and 27 more languages with `--lens-lsp`)
+3. **Scans for secrets** — blocks on hardcoded API keys, tokens, passwords
+4. **Runs linters** — Biome (TS/JS), Ruff (Python), plus structural analysis
+5. **Detects code smells** — empty catch blocks, debuggers, nested ternaries, etc.
+6. **Only shows NEW issues** — delta-mode tracks baselines and filters pre-existing problems (reduces noise)
+
+**Blocking issues** (type errors, secrets) appear inline and stop the agent until fixed. **Warnings** are tracked but hidden inline — run `/lens-booboo` to see them all.
+
+## Quick Start
+
+```bash
+# Install
+pi install npm:pi-lens
+
+# Standard mode (auto-formatting, type-checking, linting enabled by default)
+pi
+
+# Disable auto-formatting if needed
+pi --no-autoformat
+
+# Full LSP mode (31 language servers)
+pi --lens-lsp
+
+# Fastest mode (LSP + concurrent execution) (Experimental)
+pi --lens-lsp --lens-effect
+```
+
+## Install
+
+```bash
+pi install npm:pi-lens
+```
+
+Or directly from git:
+
+```bash
+pi install git:github.com/apmantza/pi-lens
+```
+
+---
+
+## Features
+
+### Auto-Formatting (Default Enabled)
+
+pi-lens **automatically formats** every file you write or edit. Formatters are auto-detected based on your project configuration.
+
+**Priority:** **Biome** is the default. **Prettier** runs only if Biome is not configured. This prevents race conditions and ensures consistent formatting.
+
+| Formatter | Languages | Detection | Installation | Role |
+|-----------|-----------|-----------|--------------|------|
+| **Biome** ⭐ | TS/JS/JSON/CSS | `biome.json` or `@biomejs/biome` in devDependencies | ✅ Automatic | **Default** |
+| **Prettier** | TS/JS/JSON/CSS/Markdown | `.prettierrc` or `prettier` in devDependencies | Manual (`npm install -g prettier`) | Fallback |
+| **Ruff** ⭐ | Python | `[tool.ruff]` in `pyproject.toml` | ✅ Automatic | **Default** |
+| **Black** | Python | `[tool.black]` in `pyproject.toml` | Manual (`pip install black`) | Fallback |
+| **gofmt** | Go | `go` binary available | Manual (included with Go SDK) | Default |
+| **rustfmt** | Rust | `rustfmt` binary available | Manual (included with Rust toolchain) | Default |
+| **zig fmt** | Zig | `zig` binary available | Manual (included with Zig SDK) | Default |
+| **dart format** | Dart | `dart` binary available | Manual (included with Dart SDK) | Default |
+| **shfmt** | Shell | `shfmt` binary available | Manual (download binary) | Default |
+| **mix format** | Elixir | `mix` binary available | Manual (included with Elixir) | Default |
+
+⭐ = Auto-installed (no manual setup required)
+
+**How it works:**
+1. Agent writes a file
+2. pi-lens detects formatters based on config files/dependencies
+3. Biome takes priority; Prettier runs only if Biome is not configured
+4. FileTime tracking ensures safety (agents re-read if file changes externally)
+
+**Safety:** If a formatter changes the file, the agent is notified and must re-read before next edit — preventing stale content overwrites.
+
+**Disable:**
+```bash
+pi --no-autoformat    # Skip automatic formatting
+```
+
+---
+
+### Auto-Linting (Default Enabled)
+
+pi-lens **automatically lints** every file you write or edit. Linters are auto-detected based on your project configuration.
+
+| Linter | Languages | Installation | Role | Priority |
+|--------|-----------|--------------|------|----------|
+| **Biome** ⭐ | TS/JS/JSON/CSS | ✅ Automatic | **Default** | 10 |
+| **Ruff** ⭐ | Python | ✅ Automatic | **Default** | 10 |
+| **oxlint** | TS/JS | Manual (`npm i -g oxlint`) | Fast alternative | 12 |
+| **ESLint** | JS/Vue/Svelte | `npx` via `--lens-lsp` | LSP only | - |
+| **shellcheck** | Bash/sh/zsh/fish | Manual (`apt install shellcheck`) | Shell scripts | 20 |
+
+⭐ = Auto-installed (no manual setup required)
+
+**Priority:** Lower numbers = run earlier. Biome/Ruff run first, followed by specialized linters.
+
+**How it works:**
+1. Agent writes a file
+2. pi-lens detects linters based on config files and file type
+3. Biome takes priority for TS/JS; Ruff takes priority for Python
+4. Multiple linters can run on the same file (e.g., Biome + oxlint)
+5. Issues are delta-tracked (only new issues shown after first write)
+
+**Notes:**
+- Biome and Ruff are **dual-purpose** (lint + format)
+- oxlint is a faster Rust-based alternative to ESLint
+- ESLint only runs when `--lens-lsp` is enabled
+- shellcheck requires manual installation on most systems
+
+---
+
+### LSP Support (NEW) — 31 Language Servers
+
+Enable full Language Server Protocol support with `--lens-lsp`:
+
+| Category | Languages |
+|----------|-----------|
+| **Core** | TypeScript, Python, Go, Rust, Ruby, PHP, C#, F#, Java, Kotlin |
+| **Native** | C/C++, Zig, Swift, Haskell, OCaml, Lua, Dart |
+| **Functional** | Elixir, Gleam, Clojure, Haskell |
+| **DevOps** | Terraform, Nix, Docker, Bash |
+| **Config** | YAML, JSON, Prisma |
+| **Web** | Vue, Svelte, CSS/SCSS/Sass/Less |
+
+**Auto-installation (4 core tools):** TypeScript, Python, and formatting tools auto-install on first use to `.pi-lens/tools/`. Other LSP servers are launched via `npx` when available or require manual installation.
+
+**Usage:**
+```bash
+pi --lens-lsp                    # Enable LSP
+pi --lens-lsp --lens-effect      # LSP + concurrent execution
+```
+
+### `pi` vs `pi --lens-lsp`
+
+| Feature | `pi` (Default) | `pi --lens-lsp` |
+|---------|----------------|-----------------|
+| **Type Checking** | Built-in TypeScriptClient | Full LSP (31 language servers) |
+| **Auto-format** | ✅ Biome, Prettier, Ruff, etc. | ✅ Same |
+| **Auto-fix** | ✅ Enabled by default | ✅ Same |
+| **Secrets scan** | ✅ Blocks on hardcoded secrets | ✅ Same |
+| **Languages** | TypeScript, Python (built-in) | 31 languages via LSP |
+| **Python** | Ruff/pyright (built-in) | Pyright LSP |
+| **Go, Rust, etc.** | Basic linting | Full LSP support |
+
+**Recommendation:** Use `pi` for TypeScript/Python projects. Use `pi --lens-lsp` for multi-language projects or when you need full language server features.
+
+See [docs/LSP_CONFIG.md](docs/LSP_CONFIG.md) for configuration options.
+
+---
+
+### Execution Modes
+
+| Mode | Flag | Description |
+|------|------|-------------|
+| **Sequential** | (default) | Runners execute one at a time |
+| **Concurrent** | `--lens-effect` | All runners in parallel via Effect-TS (Experimental) |
+
+---
+
+### On every write / edit
+
+Every file write/edit triggers multiple analysis phases:
+
+**Execution flow:**
+1. **Secrets scan** (pre-flight) — Hardcoded secrets block immediately (non-runner check)
+2. **LSP integration** (Phase 3, with `--lens-lsp`) — Real-time type errors from language servers
+3. **Dispatch system** — Routes file to appropriate runners by `FileKind`
+4. **Runners execute** by priority (lower = earlier). See [Runners](#runners) section for full list.
+5. **Test runner detection** (post-write) — Detects Jest/Vitest/Pytest and runs relevant tests
+
+**With `--lens-effect`:** Dispatch runners execute concurrently via Effect-TS. Test runner remains sequential (step 5).
+
+**Delta mode behavior:**
+- **First write:** All issues tracked and stored in baseline
+- **Subsequent edits:** Only **NEW** issues shown (pre-existing issues filtered out)
+- **Goal:** Don't spam agent with issues they didn't cause
+
+**Output shown inline:**
+```
+🔴 STOP — 1 issue(s) must be fixed:
+  L23: var total = sum(items); — use 'let' or 'const'
+```
+
+> **Note:** Only **blocking** issues (`ts-lsp`, `pyright` errors, `type-safety` switch errors, secrets) appear inline. Warnings are tracked but not shown inline (noise reduction) — run `/lens-booboo` to see all warnings.
+
+---
+
+### Runners
+
+pi-lens uses a **dispatcher-runner architecture** for extensible multi-language support. Runners are executed by priority (lower = earlier).
+
+| Runner | Language | Priority | Output | Description |
+|--------|----------|----------|--------|-------------|
+| **ts-lsp** | TypeScript | 5 | Blocking | TypeScript errors (hard stops) |
+| **pyright** | Python | 5 | Blocking | Python type errors (hard stops) |
+| **biome** | TS/JS | 10 | Warning | Linting issues (delta-tracked) |
+| **ruff** | Python | 10 | Warning | Python linting (delta-tracked) |
+| **oxlint** | TS/JS | 12 | Warning | Fast Rust-based JS/TS linter |
+| **tree-sitter** | TS/JS, Python | 14 | Mixed | AST-based structural analysis (17 patterns) |
+| **ast-grep-napi** | TS/JS | 15 | Warning | **100x faster** structural analysis |
+| **type-safety** | TS | 20 | Mixed | Switch exhaustiveness (blocking), other (warning) |
+| **shellcheck** | Shell | 20 | Warning | Bash/sh/zsh/fish linting |
+| **python-slop** | Python | 25 | Warning | AI slop detection (~40 patterns) |
+| **spellcheck** | Markdown | 30 | Warning | Typo detection in docs |
+| **ast-grep** | Go, Rust, Python, etc. | 30 | Warning | Structural analysis via CLI (fallback for non-TS/JS) |
+| **similarity** | TS | 35 | Silent | Semantic duplicate detection (metrics only) |
+| **architect** | All | 40 | Warning | Architectural rule violations |
+| **go-vet** | Go | 50 | Warning | Go static analysis |
+| **rust-clippy** | Rust | 50 | Warning | Rust linting |
+
+**Priority legend:**
+- **5** — Type checkers (blocking errors)
+- **10-15** — Linters and structural analysis
+- **20-30** — Specialized checks (safety, slop, spellcheck)
+- **35** — Metrics only (silent)
+- **40-50** — Language-specific and architectural
+
+**Output semantics:**
+- **Blocking** — Hard stop, must fix (type errors, secrets)
+- **Warning** — Shown in `/lens-booboo`, not inline (noise reduction)
+- **Silent** — Tracked in metrics only, never shown
+
+**Disabled runners:** `ts-slop` (merged into `ast-grep-napi`)
+
+**Tree-sitter runner patterns** (priority 14, AST-based structural analysis):
+
+TypeScript/JavaScript (12 patterns):
+- 🔴 **Error**: empty-catch, hardcoded-secrets, eval
+- 🟡 **Warning**: debugger, await-in-loop, console-statement, long-parameter-list, nested-ternary, deep-promise-chain, mixed-async-styles, deep-nesting
+
+Python (6 patterns):
+- 🔴 **Error**: bare-except, mutable-default-arg, eval-exec, unreachable-except  
+- 🟡 **Warning**: wildcard-import, is-vs-equals
+
+**Custom tree-sitter queries:** Add `.yml` files to `.pi-lens/rules/tree-sitter-queries/{typescript,python}/`
+
+**AI Slop Detection:** The `python-slop` runner (priority 25) detects low-quality patterns in Python code (~40 patterns). TypeScript/JavaScript slop detection is integrated into `ast-grep-napi` runner.
+
+---
+
+### Additional Safeguards
+
+Safeguards that run **before** the dispatch system:
+
+#### Secrets Scanning (Pre-flight)
+
+Runs on every file write/edit **before** any other checks. Scans for:
+- Stripe/OpenAI keys (`sk-*`)
+- GitHub tokens (`ghp_*`, `github_pat_*`)
+- AWS keys (`AKIA*`)
+- Slack tokens (`xoxb-*`, `xoxp-*`)
+- Private keys (`BEGIN PRIVATE KEY`)
+- Hardcoded passwords and API keys
+
+**Behavior:** Always blocking, always runs on all file types. Cannot be disabled — security takes precedence.
+
+#### Agent Behavior Warnings
+
+Inline heuristics to catch anti-patterns in real-time:
+
+**Blind Write Detection**
+- **Triggers:** Agent edits a file without reading it in the last 5 tool calls
+- **Warning:** `⚠ BLIND WRITE — editing 'file.ts' without reading in the last 5 tool calls.`
+- **Why:** Prevents edits based on stale assumptions
+
+**Thrashing Detection**
+- **Triggers:** 3+ consecutive identical tool calls within 30 seconds
+- **Warning:** `🔴 THRASHING — 3 consecutive 'edit' calls with no other action.`
+- **Why:** Catches stuck loops where the agent repeats failed actions
+
+**Behavior:** Warnings appear inline but do **not** block execution.
+
+#### Custom ast-grep Rules
+
+Create your own structural rules in `.pi-lens/rules/`:
+
+```yaml
+# .pi-lens/rules/no-console-prod.yml
+id: no-console-prod
+language: javascript
+rule:
+  pattern: console.$METHOD($$$ARGS)
+message: "Remove console statements before production"
+severity: warning
+```
+
+See [docs/ast-grep-rules.md](docs/ast-grep-rules.md) for full guide.
+
+---
+
+### At Session Start
+
+When pi starts a new session, pi-lens performs initialization scans to establish baselines and surface existing technical debt:
+
+**Initialization sequence:**
+1. **Reset session state** — Clear metrics and complexity baselines
+2. **Initialize LSP** (with `--lens-lsp`) — Detect and auto-install language servers
+3. **Pre-install TypeScript LSP** (with `--lens-lsp`) — Warm up cache for instant response
+4. **Detect available tools** — Biome, ast-grep, Ruff, Knip, jscpd, Madge, type-coverage, Go, Rust
+5. **Load architect rules** — If `architect.yml` or `.architect.yml` present
+6. **Detect test runner** — Jest, Vitest, Pytest, etc.
+
+**Cached scans** (with 5-min TTL):
+| Scan | Tool | Cached | Purpose |
+|------|------|--------|---------|
+| **TODOs** | Internal | No | Tech debt markers |
+| **Dead code** | Knip | Yes | Unused exports/files/deps |
+| **Duplicates** | jscpd | Yes | Copy-paste detection |
+| **Exports** | ast-grep | No | Function index for similarity |
+
+**Error debt tracking** (with `--error-debt` flag):
+- If tests passed at end of previous session but fail now → **regression detected**
+- Blocks agent until tests pass again
+
+**Output:** Scan results appear in session startup notification
+
+---
+
+### Code Review
+
+```
+/lens-booboo [path]
+```
+
+Full codebase analysis with **10 tracked runners** producing a comprehensive report:
+
+| # | Runner | What it finds |
+|---|--------|---------------|
+| 1 | **ast-grep (design smells)** | Structural issues (empty catch, no-debugger, etc.) |
+| 2 | **ast-grep (similar functions)** | Duplicate function patterns across files |
+| 3 | **semantic similarity (Amain)** | 57×72 matrix semantic clones (>75% similarity) |
+| 4 | **complexity metrics** | Low MI, high cognitive complexity, AI slop indicators |
+| 5 | **TODO scanner** | TODO/FIXME annotations and tech debt markers |
+| 6 | **dead code (Knip)** | Unused exports, files, dependencies |
+| 7 | **duplicate code (jscpd)** | Copy-paste blocks with line/token counts |
+| 8 | **type coverage** | Percentage typed vs `any`, low-coverage files |
+| 9 | **circular deps (Madge)** | Import cycles and dependency chains |
+| 10 | **architectural rules** | Layer violations, file size limits, path rules |
+
+**Output:**
+- **Terminal:** Progress `[1/10] runner...` with timing, summary with findings per runner
+- **JSON:** `.pi-lens/reviews/booboo-{timestamp}.json` (structured data for AI processing)
+- **Markdown:** `.pi-lens/reviews/booboo-{timestamp}.md` (human-readable report)
+
+**Usage:**
+```bash
+/lens-booboo              # Scan current directory
+/lens-booboo ./src        # Scan specific path
+```
+
+---
+
+### Test Runner
+
+**Auto-detected test runners:**
+| Runner | Config Files | Languages |
+|--------|--------------|-----------|
+| **Vitest** | `vitest.config.ts`, `vitest.config.js` | TypeScript, JavaScript |
+| **Jest** | `jest.config.js`, `jest.config.ts`, `package.json` (jest field) | TypeScript, JavaScript |
+| **Pytest** | `pytest.ini`, `setup.cfg`, `pyproject.toml` | Python |
+
+**Behavior:**
+- **On file write:** Detects corresponding test file and runs it
+- **Pattern matching:** `file.ts` → `file.test.ts` or `__tests__/file.test.ts`
+- **Output:** Inline pass/fail with failure details (shown with lint results)
+- **Flag:** Use `--no-tests` to disable automatic test running
+
+**Execution flow:**
+1. Agent writes `src/utils.ts`
+2. pi-lens finds `src/utils.test.ts` (or `__tests__/utils.test.ts`)
+3. Runs only that test file (not full suite)
+4. Results appear inline:
+```
+[tests] 3 passed, 1 failed (42ms)
+  ✓ should calculate total
+  ✗ should handle empty array (expected 0, got undefined)
+```
+
+**Why only corresponding tests?**
+Running the full suite on every edit would be too slow. Targeted testing gives immediate feedback for the code being edited.
+
+---
+
+### Complexity Metrics
+
+pi-lens calculates comprehensive code quality metrics for every source file:
+
+| Metric | Range | Description | Thresholds |
+|--------|-------|-------------|------------|
+| **Maintainability Index (MI)** | 0-100 | Composite score combining complexity, size, and structure | <20: 🔴 Unmaintainable, 20-40: 🟡 Poor, >60: ✅ Good |
+| **Cognitive Complexity** | 0+ | Human mental effort to understand code (nesting penalties) | >20: 🟡 Hard to understand, >50: 🔴 Very complex |
+| **Cyclomatic Complexity** | 1+ | Independent code paths (branch points + 1) | >10: 🟡 Complex function, >20: 🔴 Highly complex |
+| **Max Cyclomatic** | 1+ | Worst function in file | >10 flagged |
+| **Nesting Depth** | 0+ | Maximum block nesting level | >4: 🟡 Deep nesting, >6: 🔴 Excessive |
+| **Code Entropy** | 0-8+ bits | Shannon entropy — unpredictability of code patterns | >3.5: 🟡 Risky AI-induced complexity |
+| **Halstead Volume** | 0+ | Vocabulary × length — unique ops/operands | High = many different operations |
+
+**AI Slop Indicators:**
+- Low MI + high cognitive complexity + high entropy = potential AI-generated spaghetti code
+- Excessive comments (>40%) + low MI = hand-holding anti-patterns
+- Single-use helpers with high entropy = over-abstraction
+
+**Usage:**
+- `/lens-booboo` — Shows complexity table for all files
+- `tool_result` — Complexity tracked per file, AI slop warnings inline
+
+---
+
+## Dependent Tools
+
+pi-lens works out of the box for TypeScript/JavaScript. For full language support, install these tools — **all are optional and gracefully skip if not installed**:
+
+### JavaScript / TypeScript
+
+| Tool | Install | What it does |
+|------|---------|--------------|
+| `@biomejs/biome` | `npm i -D @biomejs/biome` | Linting + formatting |
+| `oxlint` | `npm i -D oxlint` | Fast Rust-based JS/TS linting |
+| `knip` | `npm i -D knip` | Dead code / unused exports |
+| `jscpd` | `npm i -D jscpd` | Copy-paste detection |
+| `type-coverage` | `npm i -D type-coverage` | TypeScript `any` coverage % |
+| `@ast-grep/napi` | `npm i -D @ast-grep/napi` | Fast structural analysis (TS/JS) |
+| `@ast-grep/cli` | `npm i -D @ast-grep/cli` | Structural pattern matching (all languages) |
+| `typos-cli` | `cargo install typos-cli` | Spellcheck for Markdown |
+
+### Python
+
+| Tool | Install | What it does |
+|------|---------|--------------|
+| `ruff` | `pip install ruff` | Linting + formatting |
+| `pyright` | `pip install pyright` | Type-checking (catches type errors) |
+
+### Go
+
+| Tool | Install | What it does |
+|------|---------|--------------|
+| `go` | [golang.org](https://golang.org) | Built-in `go vet` for static analysis |
+
+### Rust
+
+| Tool | Install | What it does |
+|------|---------|--------------|
+| `rust` + `clippy` | [rustup.rs](https://rustup.rs) | Linting via `cargo clippy` |
+
+### Shell
+
+| Tool | Install | What it does |
+|------|---------|--------------|
+| `shellcheck` | `apt install shellcheck` / `brew install shellcheck` | Shell script linting (bash/sh/zsh/fish) |
+
+---
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `/lens-booboo` | Full codebase review (10 analysis runners) |
+| `/lens-format` | Apply Biome formatting |
+| `/lens-tdi` | Technical Debt Index and trends |
+
+---
+
+## Execution Modes
+
+| Mode | Command | What happens |
+|------|---------|--------------|
+| **Standard** (default) | `pi` | Auto-formatting, TS/Python type-checking, sequential execution |
+| **Full LSP** | `pi --lens-lsp` | Real LSP servers (31 languages), sequential execution |
+| **Fastest** | `pi --lens-lsp --lens-effect` | Real LSP + concurrent execution (all runners in parallel) |
+
+
+### Flag Reference
+
+| Flag | Description |
+|------|-------------|
+| `--lens-lsp` | Use real Language Server Protocol servers instead of built-in type-checking |
+| `--lens-effect` | Run all runners **concurrently** (faster) instead of sequentially (Experimental) |
+| `--lens-verbose` | Enable detailed console logging |
+| `--no-autoformat` | Disable automatic formatting (formatting is **enabled by default**) |
+| `--no-autofix` | Disable all auto-fixing (Biome + Ruff autofix is **enabled by default**) |
+| `--no-autofix-biome` | Disable Biome auto-fix only |
+| `--no-autofix-ruff` | Disable Ruff auto-fix only |
+| `--no-oxlint` | Skip Oxlint linting |
+| `--no-shellcheck` | Skip shellcheck for shell scripts |
+| `--no-tests` | Disable automatic test running on file write |
+| `--no-madge` | Skip circular dependency checks |
+| `--no-ast-grep` | Skip ast-grep structural analysis |
+| `--no-biome` | Skip Biome linting |
+| `--no-lsp` | Skip TypeScript/Python type checking |
+| `--error-debt` | Track test regressions across sessions |
+
+**Recommended combinations:**
+```bash
+pi                               # Default: auto-format, auto-fix, built-in type-checking
+pi --lens-lsp                    # LSP type-checking (31 languages)
+pi --lens-lsp --lens-effect      # LSP + concurrent execution (fastest)
+```
+
+---
+
+## TypeScript LSP — tsconfig detection
+
+The LSP walks up from the edited file's directory until it finds a `tsconfig.json`. If found, it uses that project's exact `compilerOptions` (paths, strict settings, lib, etc.). If not found, it falls back to sensible defaults:
+
+- `target: ES2020`
+- `lib: ["es2020", "dom", "dom.iterable"]`
+- `moduleResolution: bundler`
+- `strict: true`
+
+The compiler options are refreshed automatically when you switch between projects within a session.
+
+---
+
+## Exclusion Criteria
+
+pi-lens automatically excludes certain files from analysis to reduce noise and focus on production code.
+
+### Test Files
+
+All runners respect test file exclusions — both in the dispatch system (`skipTestFiles: true`) and the `/lens-booboo` command.
+
+**Excluded patterns:**
+```
+**/*.test.ts      **/*.test.tsx      **/*.test.js      **/*.test.jsx
+**/*.spec.ts      **/*.spec.tsx      **/*.spec.js      **/*.spec.jsx
+**/*.poc.test.ts  **/*.poc.test.tsx
+**/test-utils.ts  **/test-*.ts
+**/__tests__/**  **/tests/**  **/test/**
+```
+
+**Why:** Test files intentionally duplicate patterns (test fixtures, mock setups) and have different complexity standards. Including them creates false positives.
+
+### Build Artifacts (TypeScript Projects)
+
+In TypeScript projects (detected by `tsconfig.json` presence), compiled `.js` files are excluded:
+
+```
+**/*.js   **/*.jsx   (when corresponding .ts/.tsx exists)
+```
+
+**Why:** In TS projects, `.js` files are build artifacts. Analyzing them duplicates every issue (once in source `.ts`, once in compiled `.js`).
+
+**Note:** In pure JavaScript projects (no `tsconfig.json`), `.js` files are **included** as they are the source files.
+
+### Excluded Directories
+
+| Directory | Reason |
+|-----------|--------|
+| `node_modules/` | Third-party dependencies |
+| `.git/` | Version control metadata |
+| `dist/`, `build/` | Build outputs |
+| `.pi-lens/`, `.pi/` | pi agent internal files |
+| `.next/`, `.ruff_cache/` | Framework/build caches |
+| `coverage/` | Test coverage reports |
+
+### Per-Runner Exclusion Summary
+
+| Runner | Test Files | Build Artifacts | Directories |
+|--------|-----------|-----------------|-------------|
+| **dispatch runners** | ✅ `skipTestFiles` | ✅ `.js` excluded in TS | ✅ `EXCLUDED_DIRS` |
+| **booboo /lens-booboo** | ✅ `shouldIncludeFile()` | ✅ `isTsProject` check | ✅ `EXCLUDED_DIRS` |
+| **Secrets scan** | ❌ No exclusion (security) | ❌ No exclusion | ✅ Dirs excluded |
+
+---
+
+## Caching Architecture
+
+pi-lens uses a multi-layer caching strategy to avoid redundant work:
+
+### 1. Tool Availability Cache
+
+**Location:** `clients/tool-availability.ts`
+
+```
+┌─────────────────────────────────────────┐
+│         TOOL AVAILABILITY CACHE          │
+│  Map<toolName, {available, version}>     │
+│  • Persisted for session lifetime         │
+│  • Refreshed on extension restart        │
+└─────────────────────────────────────────┘
+```
+
+Avoids repeated `which`/`where` calls to check if `biome`, `ruff`, `pyright`, etc. are installed.
+
+### 2. Dispatch Baselines (Delta Mode)
+
+**Location:** `clients/dispatch/dispatcher.ts`
+
+```
+┌─────────────────────────────────────────┐
+│         DISPATCH BASELINES              │
+│  Map<filePath, Diagnostic[]>            │
+│  • Cleared at turn start                 │
+│  • Updated after each runner execution   │
+│  • Filters: only NEW issues shown        │
+└─────────────────────────────────────────┘
+```
+
+Delta mode tracking: first edit shows all issues, subsequent edits only show issues that weren't there before.
+
+### 3. Client-Level Caches
+
+| Client | Cache | TTL | Purpose |
+|--------|-------|-----|---------|
+| **Knip** | `clients/cache-manager.ts` | 5 min | Dead code analysis (slow) |
+| **jscpd** | `clients/cache-manager.ts` | 5 min | Duplicate detection (slow) |
+| **Type Coverage** | In-memory | Session | `any` type percentage |
+| **Complexity** | In-memory | File-level | MI, cognitive complexity per file |
+
+### 4. Session Turn State
+
+**Location:** `clients/cache-manager.ts`
+
+```
+┌─────────────────────────────────────────┐
+│         TURN STATE TRACKING               │
+│  • Modified files this turn              │
+│  • Modified line ranges per file         │
+│  • Import changes detected               │
+│  • Turn cycle counter (max 10)           │
+└─────────────────────────────────────────┘
+```
+
+Tracks which files were edited in the current agent turn for:
+- jscpd: Only re-scan modified files
+- Madge: Only check deps if imports changed
+- Cycle detection: Prevents infinite fix loops
+
+### 5. Runner Internal Caches
+
+| Runner | Cache | Notes |
+|--------|-------|-------|
+| `ast-grep-napi` | Rule descriptions | Loaded once per session |
+| `biome` | Tool availability | Checked once, cached |
+| `pyright` | Command path | Venv lookup cached |
+| `ruff` | Command path | Venv lookup cached |
+
+---
+
+## Project Structure
+
+```
+pi-lens/
+├── clients/              # Lint tool wrappers and utilities
+│   ├── bus/              # Event bus system (Phase 1)
+│   │   ├── bus.ts
+│   │   ├── events.ts
+│   │   └── integration.ts
+│   ├── dispatch/         # Dispatcher and runners
+│   │   ├── dispatcher.ts
+│   │   └── runners/      # Individual runners
+│   │       ├── ast-grep-napi.ts      # Fast TS/JS runner
+│   │       ├── python-slop.ts        # Python slop detection
+│   │       ├── ts-lsp.ts             # TS type checking
+│   │       ├── biome.ts
+│   │       ├── ruff.ts
+│   │       ├── pyright.ts
+│   │       ├── go-vet.ts
+│   │       └── rust-clippy.ts
+│   ├── lsp/              # LSP client system (Phase 3)
+│   │   ├── client.ts
+│   │   ├── server.ts     # 31 LSP server definitions
+│   │   ├── language.ts
+│   │   ├── launch.ts
+│   │   └── config.ts     # Custom LSP configuration
+│   ├── installer/          # Auto-installation (Phase 4)
+│   │   └── index.ts
+│   ├── services/           # Effect-TS services (Phase 2)
+│   │   ├── runner-service.ts
+│   │   └── effect-integration.ts
+│   ├── complexity-client.ts
+│   ├── type-safety-client.ts
+│   └── secrets-scanner.ts
+├── commands/             # pi commands
+│   ├── booboo.ts
+│   └── fix-simplified.ts
+├── docs/                 # Documentation
+│   └── LSP_CONFIG.md     # LSP configuration guide
+├── rules/                # AST-grep rules
+│   └── ast-grep-rules/   # General structural rules
+├── index.ts              # Main entry point
+└── package.json
+```
+
+---
+
+## Changelog
+
+See [CHANGELOG.md](CHANGELOG.md) for full history.
+
+### Latest Highlights
+
+- **LSP Support:** 31 Language Server Protocol clients (4 core auto-installed, others via npx or manual)
+- **Concurrent Execution:** Effect-TS-based parallel runner execution with `--lens-effect`
+- **NAPI Runner:** 100x faster TypeScript/JavaScript structural analysis (~9ms vs ~1200ms)
+- **Slop Detection:** 30+ TypeScript and 40+ Python patterns for AI-generated code quality issues
+
+---
+
+## License
+
+MIT