jdi-cli 0.1.0

package/runtimes/claude/skills/frontend-validator/SKILL.md

@@ -0,0 +1,553 @@
+---
+name: frontend-validator
+description: Validates live UI via Playwright + axe-core. Detects Playwright; installs if missing (with user consent). Spawns dev server, navigates critical routes on mobile+desktop, captures console errors, network failures, a11y violations, screenshots, layout shifts. Structured JSON output for the reviewer to parse.
+---
+
+# Skill: jdi-frontend-validator
+
+Runs UI validation in a real browser. Without Playwright installed, installs with consent. Output always JSON in `.jdi/cache/ui-findings.json` for the parent reviewer to consume.
+
+## When to apply
+
+Reviewer calls at gate 7. Preconditions in PROJECT.md:
+
+```yaml
+frontend:
+  has_frontend: true
+  frontend_url: http://localhost:5173
+  dev_command: pnpm dev
+  critical_paths:
+    - /
+    - /login
+    - /dashboard
+```
+
+Missing any key -> abort with descriptive error.
+
+## Procedure
+
+### Step 1: Pre-flight
+
+```bash
+# bash
+test -d .jdi/ || { echo "No .jdi/. Run /jdi-new"; exit 1; }
+test -f .jdi/PROJECT.md || { echo "PROJECT.md missing"; exit 1; }
+
+# Read frontend.has_frontend, frontend_url, dev_command, critical_paths
+# (simple YAML parse - assume well-defined format)
+
+# Create cache
+mkdir -p .jdi/cache/screenshots
+
+# .gitignore guarantee
+grep -q '^\.jdi/cache/' .gitignore 2>/dev/null || echo '.jdi/cache/' >> .gitignore
+```
+
+```powershell
+# PowerShell
+if (-not (Test-Path .jdi)) { Write-Error "No .jdi/. Run /jdi-new"; exit 1 }
+if (-not (Test-Path .jdi/PROJECT.md)) { Write-Error "PROJECT.md missing"; exit 1 }
+
+New-Item -ItemType Directory -Force -Path .jdi/cache/screenshots | Out-Null
+
+if (-not (Test-Path .gitignore) -or -not (Select-String -Path .gitignore -Pattern '^\.jdi/cache/' -Quiet)) {
+  Add-Content .gitignore '.jdi/cache/'
+}
+```
+
+### Step 2: Detect package manager
+
+Lockfile detection (more reliable than `which`):
+
+```bash
+# bash
+if [ -f pnpm-lock.yaml ]; then PKG_MGR=pnpm
+elif [ -f yarn.lock ]; then PKG_MGR=yarn
+elif [ -f bun.lockb ] || [ -f bun.lock ]; then PKG_MGR=bun
+elif [ -f package-lock.json ]; then PKG_MGR=npm
+else PKG_MGR=npm  # fallback
+fi
+```
+
+```powershell
+# PowerShell
+if (Test-Path pnpm-lock.yaml) { $PKG_MGR = "pnpm" }
+elseif (Test-Path yarn.lock) { $PKG_MGR = "yarn" }
+elseif ((Test-Path bun.lockb) -or (Test-Path bun.lock)) { $PKG_MGR = "bun" }
+elseif (Test-Path package-lock.json) { $PKG_MGR = "npm" }
+else { $PKG_MGR = "npm" }
+```
+
+Corresponding install command:
+
+| Pkg mgr | Install dev dep | Run binary |
+|---|---|---|
+| npm | `npm install --save-dev <pkg>` | `npx <bin>` |
+| pnpm | `pnpm add -D <pkg>` | `pnpm exec <bin>` or `pnpm dlx <bin>` |
+| yarn | `yarn add -D <pkg>` | `yarn <bin>` |
+| bun | `bun add -d <pkg>` | `bunx <bin>` |
+
+### Step 3: Detect Playwright
+
+```bash
+# bash
+PW_BIN="npx --no-install playwright"
+[ "$PKG_MGR" = "pnpm" ] && PW_BIN="pnpm exec playwright"
+[ "$PKG_MGR" = "yarn" ] && PW_BIN="yarn playwright"
+[ "$PKG_MGR" = "bun" ] && PW_BIN="bunx playwright"
+
+if ! $PW_BIN --version >/dev/null 2>&1; then
+  PLAYWRIGHT_MISSING=1
+fi
+
+# Check axe-core/playwright separately
+if [ -f package.json ] && ! grep -q '@axe-core/playwright' package.json; then
+  AXE_MISSING=1
+fi
+```
+
+```powershell
+# PowerShell - simplified
+$pwExists = $false
+try {
+  $null = & npx --no-install playwright --version 2>$null
+  if ($LASTEXITCODE -eq 0) { $pwExists = $true }
+} catch {}
+if (-not $pwExists) { $env:PLAYWRIGHT_MISSING = "1" }
+
+$axeExists = $false
+if (Test-Path package.json) {
+  if (Select-String -Path package.json -Pattern '@axe-core/playwright' -Quiet) { $axeExists = $true }
+}
+if (-not $axeExists) { $env:AXE_MISSING = "1" }
+```
+
+### Step 4: If missing, ask consent + install
+
+Use AskUserQuestion (or prompt fallback if runtime doesn't support it):
+
+```
+Playwright not installed in this project.
+
+Install now?
+- [Yes, install with Chromium] (~150MB, 2-5min, recommended)
+- [Yes, install with all browsers] (~500MB, 5-10min)
+- [No, skip gate 7 this time] (gate returns SKIPPED)
+- [Cancel entire review]
+```
+
+Choice mapping:
+
+**Yes, Chromium:**
+```bash
+$INSTALL_CMD @playwright/test @axe-core/playwright
+$PLAYWRIGHT_INSTALL chromium
+```
+
+Where:
+- `$INSTALL_CMD` = `pnpm add -D` / `npm install --save-dev` / etc based on PKG_MGR
+- `$PLAYWRIGHT_INSTALL` = `$PW_BIN install`
+
+**Yes, all browsers:**
+```bash
+$INSTALL_CMD @playwright/test @axe-core/playwright
+$PLAYWRIGHT_INSTALL
+```
+
+**No, skip:**
+Returns `{ "status": "SKIPPED", "reason": "user declined Playwright install" }` - reviewer marks gate 7 as SKIPPED (not BLOCK).
+
+**Cancel review:**
+Returns error code, reviewer aborts.
+
+### Step 5: Generate temporary Playwright spec
+
+Creates `.jdi/cache/playwright-check.spec.js` (gitignored). Content:
+
+```javascript
+// Auto-generated by jdi-frontend-validator. DO NOT edit manually.
+// @ts-check
+const { test, expect } = require('@playwright/test');
+const AxeBuilder = require('@axe-core/playwright').default;
+const fs = require('fs');
+const path = require('path');
+
+const URL = process.env.JDI_FRONTEND_URL;
+const ROUTES = (process.env.JDI_ROUTES || '/').split(',').map(r => r.trim()).filter(Boolean);
+const OUT = process.env.JDI_OUT || '.jdi/cache/ui-findings.json';
+const SCREENSHOT_DIR = process.env.JDI_SCREENSHOT_DIR || '.jdi/cache/screenshots';
+
+const VIEWPORTS = [
+  { name: 'mobile', width: 375, height: 667 },
+  { name: 'desktop', width: 1280, height: 720 }
+];
+
+const findings = {
+  metadata: { url: URL, routes: ROUTES, timestamp: new Date().toISOString() },
+  console: [],
+  network: [],
+  a11y: [],
+  layout: [],
+  screenshots: [],
+  navigationFailures: []
+};
+
+for (const route of ROUTES) {
+  for (const viewport of VIEWPORTS) {
+    test(`${route} @ ${viewport.name}`, async ({ page }) => {
+      await page.setViewportSize({ width: viewport.width, height: viewport.height });
+
+      page.on('console', msg => {
+        if (msg.type() === 'error') {
+          findings.console.push({
+            route,
+            viewport: viewport.name,
+            text: msg.text(),
+            location: msg.location()
+          });
+        }
+      });
+
+      page.on('requestfailed', req => {
+        findings.network.push({
+          route,
+          viewport: viewport.name,
+          url: req.url(),
+          method: req.method(),
+          failure: req.failure()?.errorText,
+          severity: 'requestfailed'
+        });
+      });
+
+      page.on('response', res => {
+        if (res.status() >= 500) {
+          findings.network.push({
+            route,
+            viewport: viewport.name,
+            url: res.url(),
+            status: res.status(),
+            severity: '5xx'
+          });
+        } else if (res.status() >= 400 && res.status() !== 404) {
+          findings.network.push({
+            route,
+            viewport: viewport.name,
+            url: res.url(),
+            status: res.status(),
+            severity: '4xx'
+          });
+        }
+      });
+
+      const targetUrl = `${URL}${route}`;
+      let response;
+      try {
+        response = await page.goto(targetUrl, { waitUntil: 'networkidle', timeout: 30000 });
+      } catch (err) {
+        findings.navigationFailures.push({
+          route,
+          viewport: viewport.name,
+          error: err.message
+        });
+        return;
+      }
+
+      if (!response || !response.ok()) {
+        findings.navigationFailures.push({
+          route,
+          viewport: viewport.name,
+          status: response?.status() ?? 'no-response',
+          url: targetUrl
+        });
+        return;
+      }
+
+      // Detect horizontal scroll
+      const hasHScroll = await page.evaluate(() => {
+        return document.documentElement.scrollWidth > document.documentElement.clientWidth + 1;
+      });
+      if (hasHScroll) {
+        findings.layout.push({
+          route,
+          viewport: viewport.name,
+          issue: 'horizontal_scroll'
+        });
+      }
+
+      // axe-core a11y scan
+      try {
+        const axeResults = await new AxeBuilder({ page })
+          .withTags(['wcag2a', 'wcag2aa', 'wcag22aa', 'best-practice'])
+          .analyze();
+
+        for (const v of axeResults.violations) {
+          findings.a11y.push({
+            route,
+            viewport: viewport.name,
+            id: v.id,
+            impact: v.impact,
+            help: v.help,
+            helpUrl: v.helpUrl,
+            nodes: v.nodes.length,
+            sample: v.nodes.slice(0, 3).map(n => ({
+              target: n.target,
+              html: n.html.slice(0, 200)
+            }))
+          });
+        }
+      } catch (err) {
+        // axe-core failure doesn't block run
+        findings.a11y.push({
+          route,
+          viewport: viewport.name,
+          error: `axe-core failed: ${err.message}`
+        });
+      }
+
+      // Screenshot
+      const safeName = (route === '/' ? 'root' : route.replace(/^\//, '').replace(/\//g, '_'));
+      const screenshotPath = path.join(SCREENSHOT_DIR, `${safeName}_${viewport.name}.png`);
+      await page.screenshot({ path: screenshotPath, fullPage: true });
+      findings.screenshots.push({ route, viewport: viewport.name, path: screenshotPath });
+    });
+  }
+}
+
+test.afterAll(() => {
+  fs.writeFileSync(OUT, JSON.stringify(findings, null, 2));
+});
+```
+
+And inline config `.jdi/cache/playwright.config.js`:
+
+```javascript
+module.exports = {
+  testDir: '.jdi/cache',
+  testMatch: 'playwright-check.spec.js',
+  timeout: 60000,
+  retries: 0,
+  workers: 1,
+  reporter: [['line']],
+  use: {
+    headless: true,
+    ignoreHTTPSErrors: true
+  }
+};
+```
+
+### Step 6: Spawn dev server
+
+```bash
+# bash
+DEV_LOG=.jdi/cache/dev-server.log
+DEV_PID_FILE=.jdi/cache/dev-server.pid
+
+# Spawn in background, redirecting log
+nohup $DEV_COMMAND > $DEV_LOG 2>&1 &
+echo $! > $DEV_PID_FILE
+
+# Wait ready (poll URL, timeout 60s)
+READY=0
+for i in $(seq 1 60); do
+  if curl -sSf -o /dev/null --max-time 2 "$FRONTEND_URL"; then
+    READY=1
+    break
+  fi
+  sleep 1
+done
+
+if [ $READY -eq 0 ]; then
+  # Cleanup
+  kill $(cat $DEV_PID_FILE) 2>/dev/null
+  echo '{"status":"INCONCLUSIVE","reason":"dev server failed to start in 60s","logs":"'$DEV_LOG'"}' > .jdi/cache/ui-findings.json
+  exit 0  # doesn't fail the reviewer - INCONCLUSIVE is WARN
+fi
+```
+
+```powershell
+# PowerShell
+$DEV_LOG = ".jdi/cache/dev-server.log"
+$DEV_PID_FILE = ".jdi/cache/dev-server.pid"
+
+$proc = Start-Process -FilePath pwsh -ArgumentList "-NoProfile", "-Command", $DEV_COMMAND `
+  -RedirectStandardOutput $DEV_LOG -RedirectStandardError $DEV_LOG `
+  -PassThru -WindowStyle Hidden
+$proc.Id | Out-File -FilePath $DEV_PID_FILE
+
+$ready = $false
+for ($i = 0; $i -lt 60; $i++) {
+  try {
+    $r = Invoke-WebRequest -Uri $FRONTEND_URL -UseBasicParsing -TimeoutSec 2 -ErrorAction Stop
+    if ($r.StatusCode -eq 200) { $ready = $true; break }
+  } catch {}
+  Start-Sleep -Seconds 1
+}
+
+if (-not $ready) {
+  Stop-Process -Id $proc.Id -Force -ErrorAction SilentlyContinue
+  $err = @{ status="INCONCLUSIVE"; reason="dev server failed to start in 60s"; logs=$DEV_LOG } | ConvertTo-Json
+  $err | Out-File .jdi/cache/ui-findings.json
+  exit 0
+}
+```
+
+### Step 7: Run Playwright
+
+```bash
+# bash
+JDI_FRONTEND_URL="$FRONTEND_URL" \
+JDI_ROUTES="$(echo $CRITICAL_PATHS | tr '\n' ',')" \
+JDI_OUT=".jdi/cache/ui-findings.json" \
+JDI_SCREENSHOT_DIR=".jdi/cache/screenshots" \
+  $PW_BIN test --config=.jdi/cache/playwright.config.js 2>&1 | tee .jdi/cache/playwright.log
+
+# Playwright exit code doesn't matter - findings already written by afterAll
+```
+
+```powershell
+# PowerShell
+$env:JDI_FRONTEND_URL = $FRONTEND_URL
+$env:JDI_ROUTES = ($CRITICAL_PATHS -join ',')
+$env:JDI_OUT = ".jdi/cache/ui-findings.json"
+$env:JDI_SCREENSHOT_DIR = ".jdi/cache/screenshots"
+
+& npx playwright test --config=.jdi/cache/playwright.config.js 2>&1 | Tee-Object -FilePath .jdi/cache/playwright.log
+```
+
+### Step 8: Kill dev server (always, even on failure)
+
+```bash
+# bash
+if [ -f $DEV_PID_FILE ]; then
+  PID=$(cat $DEV_PID_FILE)
+  # Kill process + children (dev server usually has children: node, esbuild, vite, etc)
+  pkill -P $PID 2>/dev/null
+  kill $PID 2>/dev/null
+  # Safeguard on common ports (in case wrong PID)
+  # Vite: 5173, Next: 3000, etc - skip aggressive cleanup
+  rm $DEV_PID_FILE
+fi
+```
+
+```powershell
+# PowerShell
+if (Test-Path $DEV_PID_FILE) {
+  $pid = Get-Content $DEV_PID_FILE
+  # Kill children first
+  Get-CimInstance Win32_Process -Filter "ParentProcessId=$pid" -ErrorAction SilentlyContinue |
+    ForEach-Object { Stop-Process -Id $_.ProcessId -Force -ErrorAction SilentlyContinue }
+  # Kill the parent
+  Stop-Process -Id $pid -Force -ErrorAction SilentlyContinue
+  Remove-Item $DEV_PID_FILE
+}
+```
+
+### Step 9: Return to parent reviewer
+
+Skill doesn't write REVIEW.md. Only writes `.jdi/cache/ui-findings.json` + screenshots.
+
+Reviewer reads the JSON, classifies severities, and writes "UI Validation" section in REVIEW.md.
+
+## Finding classification (reference for the reviewer)
+
+| Finding | Severity |
+|---|---|
+| `console.error` on any route | BLOCK |
+| `network.5xx` on critical_path | BLOCK |
+| `network.4xx` on critical_path | WARN |
+| `network.requestfailed` (CORS/abort/etc) | WARN |
+| `navigationFailures` (404/timeout/etc on critical_path) | BLOCK |
+| `a11y.impact=critical` | BLOCK |
+| `a11y.impact=serious` | BLOCK |
+| `a11y.impact=moderate` | WARN |
+| `a11y.impact=minor` | INFO |
+| `layout.horizontal_scroll` on mobile | BLOCK |
+| `layout.horizontal_scroll` on desktop | INFO |
+| `axe-core failed` (technical error) | WARN |
+| `INCONCLUSIVE` (dev server timeout) | WARN |
+| `SKIPPED` (user declined install) | WARN |
+
+## Expected inputs
+
+From PROJECT.md (passed as environment variables by the reviewer):
+- `frontend.frontend_url` -> `FRONTEND_URL`
+- `frontend.dev_command` -> `DEV_COMMAND`
+- `frontend.critical_paths` -> `CRITICAL_PATHS` (list)
+
+## Outputs
+
+Files created in `.jdi/cache/` (gitignored):
+- `ui-findings.json` - structured findings
+- `screenshots/*.png` - 1 per route x viewport
+- `dev-server.log` - dev server log
+- `playwright.log` - Playwright run log
+- `playwright-check.spec.js` - generated spec
+- `playwright.config.js` - generated config
+
+NEVER commit `.jdi/cache/`.
+
+## Anti-patterns
+
+- Running against prod URL - dev local only. Prod is out of scope for this gate
+- Testing flows that require login - MVP doesn't support auth setup. Critical paths must be public OR pre-authenticated manually (cookie/session passed via PROJECT.md in follow-up)
+- Blocking review if Playwright install fails - degrade to SKIPPED
+- Leaving dev server alive after gate - always kill, even on error
+- Committing screenshots - .gitignore guaranteed in pre-flight
+- Running parallel (workers > 1) - local dev server doesn't scale, and race conditions confuse findings
+- Using `--headed` in CI - always headless
+- Trusting Playwright exit code - findings come from afterAll, even with test failure
+
+## References
+
+- `references/playwright-setup.md` - Detailed install per package manager + troubleshoot
+- `references/dev-server-detection.md` - Heuristics for detecting ready (curl, wait-on, polling)
+- `references/axe-rules.md` - Mapping of axe rule IDs -> WCAG -> severity
+- `references/auth-flows.md` - Roadmap for authenticated flows (future)
+
+## Examples
+
+### Example 1: Vite + React, Playwright missing, user accepts install
+
+```
+1. Reviewer triggers gate 7
+2. Skill detects `npx playwright --version` -> exit 1
+3. Lockfile = pnpm-lock.yaml -> PKG_MGR=pnpm
+4. AskUserQuestion -> user picks "Yes, Chromium"
+5. pnpm add -D @playwright/test @axe-core/playwright
+6. pnpm exec playwright install chromium
+7. Spawns `pnpm dev` in bg, PID 12345
+8. Waits http://localhost:5173 -> ready in 4s
+9. Runs Playwright on /, /login, /dashboard x mobile + desktop = 6 navigations
+10. Findings:
+    - 1 console error (uncaught promise) on /dashboard mobile + desktop
+    - 0 network errors
+    - 2 a11y serious on /login (missing label + contrast)
+    - 1 horizontal scroll on /dashboard mobile
+11. Kill PID 12345 + children
+12. Writes .jdi/cache/ui-findings.json
+13. Reviewer reads JSON, marks gate 7 = BLOCK (3 issues), writes REVIEW.md
+```
+
+### Example 2: API-only, has_frontend=false
+
+Skill is not even loaded. Reviewer skips gate 7 with SKIPPED.
+
+### Example 3: Dev server fails to start
+
+```
+1. Spawns `pnpm dev` -> process dies after 2s (port 5173 occupied)
+2. Poll of 60s expires without 200 OK
+3. Cleanup of PID
+4. Writes {"status":"INCONCLUSIVE","reason":"dev server failed to start in 60s"}
+5. Reviewer marks gate 7 = WARN with link to dev-server.log
+6. Review not blocked, but user alerted
+```
+
+### Example 4: User declines to install Playwright
+
+```
+1. AskUserQuestion -> "No, skip gate 7"
+2. Writes {"status":"SKIPPED","reason":"user declined Playwright install"}
+3. Reviewer marks gate 7 = SKIPPED (warn not block)
+4. REVIEW.md notes "UI Validation: SKIPPED - run /jdi-verify again when you accept installing"
+```

package/runtimes/claude/skills/kiss/SKILL.md

@@ -0,0 +1,164 @@
+---
+name: kiss
+description: KISS (Keep It Simple, Stupid). The simplest solution that solves the problem wins. Complexity only justified by real measured pain. Each layer/abstraction must pay its own cost. Applies in any language.
+---
+
+# Skill: KISS
+
+> Simplicity is the best design. Every complexity must pay its own cost.
+
+KISS is not "dumb code". It's **rejecting unjustified complexity**. Every interface, every layer, every abstraction has maintenance cost — only worth it if it solves real pain.
+
+## Rules
+
+### 1. Default is the simplest
+
+Ask before adding:
+- **Function** vs class vs framework?
+- **Variable** vs config vs feature flag?
+- **If/else** vs strategy pattern vs plugin system?
+- **Sync** vs async vs queue vs event bus?
+- **Inline** vs helper vs lib?
+
+Start with the leftmost. Only step up if there is a real requirement.
+
+### 2. Complexity must justify pain
+
+**Allowed:**
+- New pattern if it has 3+ real cases using it
+- Abstraction layer if it has 2+ implementations that exist today
+- Cache if measurement shows hot path
+- Async if there's unacceptable latency synchronous
+- Plugin system if there are confirmed external extenders
+
+**Forbidden:**
+- "Will scale later" without current requirement
+- "Other people might need it" without other people
+- "To make it generic" without 2nd use case
+- "Will look cleaner" trading 5 clear lines for 50 elegant ones
+- Enterprise pattern in small codebase (Repository + UoW + Mediator + CQRS for 10-controller app)
+
+### 3. Cognitive load is a real metric
+
+Code you read 10x and write 1x. Optimize for reading:
+- **Named variables** > composite expression
+- **Early return** > nested if/else
+- **Linear function** > jumps between callbacks
+- **Explicit types** > magical inference in large codebase
+- **Simple procedural code** > fancy OOP for 50 lines
+
+Rule: code that needs a comment explaining "why so complex" is too complex.
+
+### 4. Indicators of over-engineering
+
+Signs the code went over the line:
+
+- Interface with 1 implementation
+- Factory/Builder for something instantiated 1x
+- Generic <T> only used with 1 type
+- Config with a key that never changed
+- Abstraction layer that only encapsulates a call to another layer (pass-through)
+- Inheritance hierarchy > 2 levels
+- File with more setup than logic
+- Test that needs 30 lines of mock to run 5 lines of logic
+
+### 5. Refactor is the opposite direction
+
+Natural tendency: code grows in complexity. Refactoring = REMOVE complexity that no longer pays.
+
+Ask:
+- Does this layer still exist to solve a problem, or did it become tradition?
+- Does this abstraction have 2+ implementations today?
+- If I delete this, what breaks?
+- Can I solve it with 5 lines instead of 50?
+
+## Anti-patterns
+
+| Anti-pattern | Symptom |
+|---|---|
+| Interface + 1 implementation | `IUserService` + `UserService` (only 1) — delete the interface, use the class |
+| Generic `<T>` used with 1 type | `Repository<User>` but never `Repository<Order>` — concretize |
+| Factory for new() | `UserFactory.create()` that only does `return new User()` |
+| Config string that never changed | `MAX_RETRIES: 3` in config + nobody ever changed it — hardcode |
+| Inheritance > 2 levels | `BaseEntity -> AuditableEntity -> SoftDeletableEntity -> User` — flatten via composition |
+| Pass-through layer | `Controller -> Service -> Repository -> DbContext` where Service only calls Repository without logic — delete Service |
+| Enterprise pattern without demand | Mediator/CQRS in small app — replace with direct call |
+| Comment explaining "why so complex" | Code lost the war — refactor |
+| Mock setup > logic test | Test gets fragile; code under test is over-coupled |
+| Unused future-proof params | `(opts?: { future?: boolean })` without caller passing — remove |
+
+## Procedure
+
+### Doer (before writing)
+
+1. Ask: "What is the **simplest** version that meets the current requirement?"
+2. Write that version.
+3. Only step up complexity if you hit real pain.
+4. After writing, ask: "Can I delete any layer/parameter/abstraction without losing functionality?"
+
+### Reviewer (gate 5)
+
+Over-engineering heuristics:
+
+```bash
+# Interfaces with 1 implementation
+grep -RnE '^(public |export )?interface I?[A-Z]\w+' src/ | while read iface; do
+  name=$(echo "$iface" | grep -oE '[A-Z]\w+\b' | head -1)
+  count=$(grep -RnE "class \w+\s*:\s*$name|implements $name" src/ | wc -l)
+  [[ $count -eq 1 ]] && echo "WARN: $iface has only 1 implementation"
+done
+
+# Deep inheritance (> 2 levels)
+# (depends on stack — specific heuristic)
+
+# Very large or nested functions
+grep -cE '^\s{20,}\S' src/**/*  # lines with 20+ spaces = deep nesting
+```
+
+Match -> WARN with suggestion to simplify.
+
+## Inputs
+
+- Diff/content of the file
+- Context: codebase size (over-engineering is relative)
+
+## Outputs
+
+Does NOT produce a file. Modifies judgement.
+
+## Examples
+
+### Example 1: Interface with 1 impl
+
+Wrong:
+```typescript
+interface ILogger { log(msg: string): void }
+class ConsoleLogger implements ILogger { log(msg) { console.log(msg) } }
+const logger: ILogger = new ConsoleLogger()
+```
+
+Right (KISS):
+```typescript
+function log(msg: string) { console.log(msg) }
+// or
+class Logger { static log(msg: string) { console.log(msg) } }
+```
+
+Add interface when 2nd impl arrives, not before.
+
+### Example 2: Pass-through service
+
+Wrong:
+```csharp
+public class UserService {
+  public User GetById(int id) => _repo.GetById(id);  // only calls repo
+}
+```
+
+Right: use `_repo` directly in the controller. Add Service when there is real logic (validation, multi-step, transaction, event).
+
+### Example 3: Hardcodable config
+
+Wrong: `appsettings.json -> "MaxItemsPerPage": 50` that nobody ever changed in 2 years.
+
+Right: `const MAX_ITEMS_PER_PAGE = 50` in the code. Move back to config if some client actually needs to customize.