@kensaurus/skills 0.0.0-stage → 2.1.0

package/skills/audit-responsive/SKILL.md

@@ -0,0 +1,221 @@
+---
+name: audit-responsive
+description: >
+  Audit and fix layouts at every breakpoint — desktop is not a wide phone. Use
+  when "responsive audit", desktop looks stacked or stretched, there is no
+  max-width, or 1440 looks like a phone. Touch-first build →
+  design-mobile-first.
+license: MIT
+effort: high
+---
+
+# audit-responsive — Layout & breakpoint IA
+
+**Degree of freedom: MIXED** — Phases 0–3 `[HIGH freedom]`; viewport
+screenshot loop `[LOW freedom — run exactly]`; Phase 4 implement only after
+the report (wait if scope is large).
+
+> **Audit-and-fix exception.** Report first; then implement. Not present-then-stop.
+
+**Desktop is not a wide phone.** Responsive means groups reflow, controls size to
+function, and reading columns cap. A 1440px screenshot that looks like a stretched
+phone fails this skill.
+
+**Before ANY browser interaction, read `protocol-browser-anti-stall`.**
+
+> **Report-first.** Findings + token sheet + ASCII wireframes first. If the scope
+> is large, wait for approval before Phase 4. Then implement in reviewable chunks.
+> Optional path scope: `$ARGUMENTS` or a path the user named
+> (e.g. `src/pages/dashboard`).
+
+## This skill vs neighbors
+
+| Skill | Owns |
+|---|---|
+| **audit-responsive** (this) | Layout reflow + page-level IA at 375 / 768 / 1440 |
+| `design-mobile-first` | Touch, safe areas, gestures — mobile-up, not "unstack desktop" |
+| `audit-ux-journeys` | Cross-page stories, nav findability |
+| `audit-ux` | Per-page heuristics and microcopy |
+| `audit-uiux-design-system` | Tokens, components, visual drift |
+| `plan-uiux-unification` | Full DS unification plan — no code |
+| `enhance-web-ui` / `enhance-web-ux` | Polish after the layout contract exists |
+
+## How to reason
+
+1. **Observe** — quote the container/grid and the 375 / 768 / 1440 screenshots
+2. **Interpret** — did groups reflow, or is 1440 a stretched phone?
+3. **Classify** — anti-pattern # (1–10) / present-and-correct
+4. **Severity** — stretched-phone 1440 = blocker for that page
+
+## Worked example
+
+> **Observe:** Dashboard at 1440: single column, full-width buttons, no
+> `max-w-*`. Screenshot matches the 375 stack scaled up.
+> **Interpret:** desktop is a wide phone — groups that compare (stats, list+detail)
+> never sit side-by-side.
+> **Classify:** anti-patterns 1, 2, 3 — blocker.
+> **Finding:** `app/dashboard/page.tsx` | #1+#2+#3 | blocker | add page
+> max-width; 12-col stats + list+detail at ≥1024
+
+---
+
+## Phase 0 — Detect the stack (do not assume)  [HIGH freedom]
+
+Inspect the scoped UI and record:
+
+- **Framework:** React / Next / Vue / Nuxt / Svelte / Angular / HTML / server templates
+- **Styling:** Tailwind / CSS Modules / styled-components / SCSS / vanilla / UI library
+- **Tokens already in repo:** breakpoints, spacing, type, colors, container widths, icon set
+- **Underused system:** a design system or component library installed but ignored
+
+All fixes use the repo's conventions. Never add a styling system unless none exists —
+then propose the lightest fit and ask before adding a dependency.
+
+```bash
+# Framework + styling signals
+rg -l '"next"|"react"|"vue"|"svelte"|"@angular"' package.json
+rg -l 'tailwindcss|styled-components|@emotion|@mui/material|@chakra-ui|@radix-ui' package.json
+# Tokens / containers / breakpoints
+rg -n "screens|breakpoints|max-w-|container|@theme|--spacing" -g '*.{css,ts,js,mjs}' -g '!node_modules' | head -40
+# Icon set already in use
+rg -n "from 'lucide-react'|from '@heroicons'|from 'react-icons'|phosphor" -g '*.{tsx,jsx,vue,svelte}' | head -20
+```
+
+---
+
+## Phase 1 — Audit the 10 anti-patterns  [HIGH freedom; screenshot loop = LOW]
+
+Scan scoped pages, views, screens, and major layout components. Full signals and
+pass/fail cues: [references/checklist.md](references/checklist.md).
+
+| # | Anti-pattern | Fail when |
+|---|---|---|
+| 1 | **No max-width container** | Content or text edge-to-edge at desktop. Cap layouts ~1140–1280px; reading ~640–720px / 65–75ch |
+| 2 | **Single-column everything** | Vertical stack at ≥1024px when groups belong side-by-side (form+summary, list+detail, comparable stats, media+text) |
+| 3 | **Stretched interactive elements** | Full-width buttons, inputs, or cards at desktop. Full-width is a mobile pattern |
+| 4 | **No visual hierarchy** | Headings, body, labels, captions near-identical size/weight; everything left-aligned by default, not by decision |
+| 5 | **No spacing system** | Arbitrary 13/22/37px gaps instead of the repo's 4/8 scale |
+| 6 | **No grouping / IA** | Related data unclustered; unrelated data merged; flat lists where table/grid/master-detail fits |
+| 7 | **Missing or mixed icons** | Text-only nav/status/actions, or mixed icon libraries/styles |
+| 8 | **Breakpoint gaps** | Styles for one width only; abandoned at 768 (tablet) or 1440 (desktop) |
+| 9 | **Typography defaults** | Browser font stack/size, no type scale, line length >~80ch, cramped body line-height |
+| 10 | **Table/data misuse** | Tabular data as stacked cards on desktop, or wide tables with no mobile strategy |
+
+Each finding: `file:line` · anti-pattern # · one-line description · severity
+(`blocker` / `major` / `minor`).
+
+Live evidence — resize **before** `goto` (viewport persists across navigation):
+
+```bash
+PW="npx --yes @playwright/cli@latest"; S="-s=responsive-audit"
+$PW $S open --headed "<app-url>"
+for wh in "375 812" "768 1024" "1440 900"; do
+  $PW $S resize $wh
+  $PW $S goto "<route>"
+  sleep 2 && $PW $S snapshot
+  $PW $S screenshot --filename ".playwright-mcp/responsive-<route>-${wh// /x}.png"
+done
+```
+
+If the 1440 screenshot is a stretched phone, that is a **blocker** for the page.
+
+---
+
+## Phase 2 — Extract or propose the token sheet  [HIGH freedom]
+
+Before fixing, produce a sheet. If the repo already has tokens, **use them
+verbatim** and flag violations — do not invent a second scale.
+
+| Token | Default if the repo has none (mark as *proposed*) |
+|---|---|
+| Breakpoints | mobile <640 · tablet 640–1023 · desktop ≥1024 |
+| Containers | page max-width · content max-width · reading max-width |
+| Grid | 12-column mental model; how each group maps at each breakpoint |
+| Spacing | 4 / 8 / 12 / 16 / 24 / 32 / 48 / 64 |
+| Type | 12 / 14 / 16 / 20 / 24 / 32 + weight + use (caption / label / body / h3 / h2 / h1) |
+| Icons | one library; 16 inline · 20 controls · 24 nav |
+
+---
+
+## Phase 3 — Information architecture before pixels  [HIGH freedom]
+
+For each flagged page/screen:
+
+1. List content blocks. Classify each: **primary** (why the page exists),
+   **secondary** (supporting), **metadata** (timestamps, IDs, status).
+2. Group related blocks; name each group.
+3. Sketch ASCII wireframes at **375 / 768 / 1440** showing how groups reflow
+   (sidebar → tabs; 3-up stats → 1-col; master-detail → list → push).
+   Templates: [references/checklist.md](references/checklist.md#wireframes).
+4. Only then write code. The wireframe is the contract; CSS implements it.
+
+Use **real content** from the codebase — never invented examples.
+
+---
+
+## Phase 4 — Implement  [LOW freedom — after the report; repo tokens only]
+
+- Native responsive primitives: CSS grid/flex + media or container queries;
+  Tailwind prefixes; framework grid components.
+- Prefer **container queries** when a component is reused across contexts and
+  the stack supports them.
+- Mobile-first CSS: base = mobile, enhance upward.
+- Preserve semantics and a11y: heading levels match visual hierarchy, visible
+  focus, touch targets ≥44px on mobile, `prefers-reduced-motion` respected.
+- Diff scope: layout / hierarchy / spacing / type only. Do not restyle brand
+  colors or rewrite copy unless copy blocks hierarchy.
+
+Chunk by severity into reviewable PRs. After each chunk, re-run the 375 / 768 /
+1440 screenshot loop on touched routes.
+
+Hand off leftover polish (motion, microcopy, token drift) — do not absorb it.
+
+---
+
+## Definition of Done — verify at 375 / 768 / 1440
+
+- [ ] 1440: no content or control spans the full viewport; page has a max-width container
+- [ ] Related information is grouped; groups sit side-by-side where comparison or context helps
+- [ ] **5-second glance:** primary content, page purpose, and next action are obvious without reading
+- [ ] Spacing values come from the scale; font sizes come from the type scale
+- [ ] Icons from one set, used to aid scanning (status, nav, actions)
+- [ ] Body line length ≤ ~75ch; paragraph line-height ≥ 1.5
+- [ ] No horizontal overflow at 375; touch targets ≥44px; tables have a defined mobile strategy
+- [ ] Layout **meaningfully differs** between 375 and 1440 — a stretched-phone 1440 fails
+
+## Self-critique before reporting  [LOW freedom — do not skip]
+
+1. **Three viewports** — no "done" from code inspection alone
+2. **Repo tokens first** — do not invent a second scale
+3. **Wireframe before CSS** — Phase 3 is the contract
+4. **Right owner** — touch/gestures → `design-mobile-first`; empty states → `audit-ui-states`
+
+---
+
+## Output format
+
+1. **Findings table** — `file:line` | anti-pattern | severity | one-line fix
+2. **Token sheet** — extracted or proposed (mark which)
+3. **Per-screen wireframes** — 375 / 768 / 1440, ASCII
+4. **Fix plan** — severity order, PR-sized chunks
+5. Then implement chunk by chunk (or wait if the user is reviewing 1–4)
+
+**Forbidden:** inventing a new design system when one exists; stacking a
+desktop skin on a single-column DOM; claiming done from code inspection
+without the three viewport screenshots; routing a linearized-desktop complaint
+to `design-mobile-first`.
+
+---
+
+## Related
+
+- `design-mobile-first` — touch / safe-area / gesture; the mobile-up counterpart
+- `plan-uiux-unification` — whole-repo DS + IA plan when the system itself is the problem
+- `audit-uiux-design-system` — token/component compliance after layout is fixed
+- `audit-ux` / `audit-ux-journeys` — heuristics and cross-page IA (not breakpoint layout)
+- `enhance-web-ui` / `enhance-web-ux` — polish once the wireframe is implemented
+- `housekeep-design` — competing token/component SSOTs
+- `audit-accessibility` — WCAG after reflow (focus order, target size)
+- `audit-ui-states` — empty/error/offline matrix (not breakpoint layout)
+- `test-visual-regression` — lock the 375 / 768 / 1440 baselines
+- `test-playwright` — regression coverage for the new layouts

package/skills/audit-responsive/references/checklist.md

@@ -0,0 +1,166 @@
+# audit-responsive — anti-pattern signals & wireframe templates
+
+Loaded from `audit-responsive` Phase 1 and Phase 3. Do not invent a second
+scale — if the repo already defines tokens, substitute those numbers below.
+
+---
+
+## Anti-pattern signals
+
+Search the scoped UI. Cite `file:line`. Severity: **blocker** (1440 is a
+stretched phone, or primary task unusable) · **major** (hierarchy/IA broken at
+one breakpoint) · **minor** (inconsistent scale, mixed icons).
+
+### 1. No max-width container
+
+```bash
+rg -n "w-full|w-screen|max-w-none|width:\s*100%" -g '*.{tsx,jsx,vue,svelte,css}'
+rg -n "max-w-(sm|md|lg|xl|2xl|3xl|4xl|5xl|6xl|7xl|prose)|max-w-\[" -g '*.{tsx,jsx,vue,svelte}'
+```
+
+**Fail:** a page root or reading column has no `max-width` / `max-w-*` and
+stretches with the viewport past ~1280px. **Pass:** layout shell caps
+~1140–1280px (or the repo token); body copy caps ~65–75ch.
+
+### 2. Single-column everything
+
+```bash
+rg -n "flex-col|grid-cols-1|space-y-|stack" -g '*.{tsx,jsx,vue,svelte}'
+rg -n "md:grid-cols|lg:grid-cols|md:flex-row|lg:flex-row|sm:grid-cols" -g '*.{tsx,jsx,vue,svelte}'
+```
+
+**Fail:** at ≥1024px the page is still one column when it contains groups that
+invite comparison or context (form + summary, list + detail, 3+ stat cards,
+media + text). **Pass:** those groups sit side-by-side at desktop; they stack
+only below the tablet breakpoint.
+
+### 3. Stretched interactive elements
+
+```bash
+rg -n "w-full.*(Button|button|input|Input)|className=.*w-full" -g '*.{tsx,jsx,vue,svelte}'
+```
+
+**Fail:** primary buttons, text inputs, or cards are `w-full` with no
+`sm:`/`md:` constraint, so they span the desktop column. **Pass:** mobile may
+be full-bleed; desktop controls size to content or a defined field width
+(often `max-w-sm` / `max-w-md` for inputs).
+
+### 4. No visual hierarchy
+
+Look at the 1440 screenshot for 5 seconds. If you cannot name the page purpose
+and the next action, this fails.
+
+```bash
+rg -n "text-(xs|sm|base|lg|xl|2xl|3xl)|font-(normal|medium|semibold|bold)" -g '*.{tsx,jsx,vue,svelte}' | head -40
+```
+
+**Fail:** heading / body / label / caption rendered at near-identical size and
+weight; everything left-aligned because that was the default, not a decision.
+**Pass:** a readable primary → secondary → metadata scale; alignment is chosen
+(start / center / end / grid) per group.
+
+### 5. No spacing system
+
+```bash
+rg -n "\\b(p|m|gap|space-[xy])-\\[" -g '*.{tsx,jsx,vue,svelte,css}'
+rg -n "padding:\\s*[0-9]+px|margin:\\s*[0-9]+px" -g '*.{tsx,jsx,vue,svelte,css}'
+```
+
+**Fail:** one-off values (13px, 22px, 37px, `p-[13px]`) next to equivalent
+elements that use a different gap. **Pass:** all spacing from the repo scale
+(or the Phase 2 proposed 4/8 scale).
+
+### 6. No grouping / information architecture
+
+Walk the page's DOM sections and the 1440 screenshot. Name each visual group.
+If you cannot, or if unrelated fields share a card while related ones sit
+pages apart, this fails.
+
+**Fail:** long flat lists where a table, 2–3 column grid, or master-detail
+fits; no fieldsets/sections; status + title + timestamp not clustered.
+**Pass:** named groups; related data shares a region; layout matches the
+Phase 3 wireframe.
+
+### 7. Missing or mixed iconography
+
+```bash
+rg -n "from 'lucide-react'|from '@heroicons'|from 'react-icons'|from '@phosphor-icons'|material-symbols" -g '*.{tsx,jsx,vue,svelte}'
+```
+
+**Fail:** two or more icon libraries; or nav/status/actions are text-only
+where a consistent set would aid scanning. **Pass:** one library, one size
+grammar (16 inline / 20 controls / 24 nav, or the repo's).
+
+### 8. Breakpoint gaps
+
+```bash
+rg -n "sm:|md:|lg:|xl:|2xl:|@media|@container" -g '*.{tsx,jsx,vue,svelte,css}' | head -40
+```
+
+**Fail:** only a mobile base, or only a desktop layout, with no tablet
+treatment; 768px screenshot looks abandoned (overflow, crushed columns, or
+still a phone stack). **Pass:** 375, 768, and 1440 each have an intentional
+layout — not leftover.
+
+### 9. Typography defaults
+
+```bash
+rg -n "font-sans|font-serif|font-mono|--font-|fontFamily|line-height|leading-" -g '*.{tsx,jsx,vue,svelte,css}' | head -30
+```
+
+**Fail:** no type scale (browser defaults), body measure >~80ch, paragraph
+`line-height` < 1.5. **Pass:** sizes from the sheet; reading column ≤75ch;
+body leading ≥ 1.5.
+
+### 10. Table / data misuse
+
+```bash
+rg -n "<table|role=\"table\"|overflow-x-auto|md:hidden|hidden md:table" -g '*.{tsx,jsx,vue,svelte}'
+```
+
+**Fail:** tabular data rendered only as stacked cards at 1440; or a wide
+`<table>` with no mobile strategy (horizontal scroll, column priority, or
+card collapse). **Pass:** desktop uses a table or dense grid; 375 has an
+explicit strategy.
+
+---
+
+## Wireframes
+
+For each flagged screen, copy this block and fill it with **real** groups from
+the page (names from Phase 3). Do not invent content.
+
+```
+PAGE: <route> — primary: <why this page exists>
+
+375
+┌─────────────────────┐
+│ [nav / title]       │
+│ ┌─────────────────┐ │
+│ │ PRIMARY         │ │
+│ └─────────────────┘ │
+│ ┌─────────────────┐ │
+│ │ SECONDARY       │ │
+│ └─────────────────┘ │
+│ [metadata]          │
+└─────────────────────┘
+
+768
+┌──────────────┬──────────────┐
+│ PRIMARY      │ SECONDARY    │
+│              │ metadata     │
+└──────────────┴──────────────┘
+
+1440
+┌──────┬────────────────┬──────────┐
+│ nav  │ PRIMARY        │ SECONDARY│
+│      │                │ metadata │
+└──────┴────────────────┴──────────┘
+```
+
+Reflow examples (pick what the content actually needs):
+
+- Sidebar → top tabs at 375
+- 3-up stat cards → 1-col stack at 375, 2-col at 768, 3-col at 1440
+- Master-detail → list, then push view at 375; split pane at 1440
+- Form + summary → stacked at 375; 2/3 + 1/3 at 1440

package/skills/audit-security/SKILL.md

@@ -0,0 +1,289 @@
+---
+name: audit-security
+description: >
+  Audit and fix app code against OWASP (injection, headers, dependencies). Use
+  when "review security" or "check vulnerabilities". Auth gates →
+  audit-auth-flows. Plan-only → plan-security-audit. RLS → plan-rls-audit. LLM
+  → audit-llm-security.
+license: MIT
+effort: high
+---
+
+# Security Audit Skill
+
+**Degree of freedom: MIXED** — Steps 0–4 judgment `[HIGH freedom]`;
+dependency and secret scans `[LOW freedom — run exactly]`. Never write
+exploit PoCs.
+
+> **Audit-and-fix exception.** May fix inline. Plan-only burndown → `plan-security-audit`.
+> When fixing inline: patch the evidenced sink only, in place; unrelated weaknesses you notice go in the report as findings, not fixes. Add a test only where the repo already keeps security tests or the task asks. Auth behavior, RLS, secrets rotation, payments, and migrations stay STOP-and-confirm.
+
+OWASP static review (injection, headers, deps). Session / route×gate /
+`getSession()` → `audit-auth-flows`. Next.js 16: grep `middleware.ts` **and**
+`proxy.ts` — a route gate can live in either file, and the proxy layer has its own bypass class.
+
+## How to reason
+
+1. **Observe** — quote the sink or missing check (`file:line`)
+2. **Interpret** — can untrusted input reach a query, HTML, or object-id?
+3. **Classify** — injection / IDOR / secret / header / dep-CVE / hand-off
+4. **Severity** — exploitable data access or hardcoded secret = Critical
+
+## Worked example
+
+> **Observe:** `GET /documents/:id` loads by id only (`api/docs/route.ts:18`).
+> **Interpret:** any caller who can hit the route reads another user's doc.
+> **Classify:** IDOR.
+> **Severity:** Critical.
+> **Finding:** IDOR | `/documents/:id` | add `userId` predicate.
+> Matcher / `getSession()` on that route → `audit-auth-flows`, not this checklist.
+
+## Step 0: Understand the Project  [HIGH freedom]
+
+Before auditing, discover the tech stack and attack surface:
+
+1. Read `package.json` / `requirements.txt` / `go.mod` to identify:
+ - Auth library (next-auth, passport, supabase-auth, django-auth, etc.)
+ - Database ORM (Prisma, Sequelize, SQLAlchemy, etc.)
+ - HTTP framework (Express, Fastify, Django, Flask, etc.)
+ - Any security-specific packages (helmet, cors, csurf, rate-limit, etc.)
+
+2. Identify the auth pattern:
+ - Session-based vs JWT vs OAuth
+ - Where tokens are stored (cookies, localStorage, headers)
+ - How permissions/roles are enforced
+
+3. Identify the data flow:
+ - Where user input enters the system
+ - How data is validated and sanitized
+ - How data reaches the database
+
+---
+
+## Step 1: Research Current Threats  [HIGH freedom]
+
+Fetch current OWASP and security best practices for the detected stack:
+
+```json
+firecrawl:firecrawl_search
+{
+ "query": "<framework> security best practices OWASP <current year>",
+ "limit": 5,
+ "sources": [{ "type": "web" }]
+}
+```
+
+Scrape the OWASP Top 10 for the relevant platform:
+
+```json
+firecrawl:firecrawl_scrape
+{
+ "url": "https://owasp.org/Top10/",
+ "formats": ["markdown"],
+ "onlyMainContent": true
+}
+```
+
+Also check for known CVEs in dependencies:
+
+```json
+firecrawl:firecrawl_search
+{
+ "query": "<package-name> CVE vulnerability <current year>",
+ "limit": 5,
+ "sources": [{ "type": "web" }]
+}
+```
+
+---
+
+## Step 2: Check Production Security Errors (Sentry)  [HIGH freedom]
+
+If Sentry is configured, check for security-related production errors:
+
+```json
+sentry:search_issues
+{
+ "organizationSlug": "<ORG_SLUG>",
+ "query": "401 unauthorized OR 403 forbidden OR CORS OR CSP violation in last 30 days",
+ "projectSlugOrId": "<PROJECT_SLUG>",
+ "regionUrl": "<REGION_URL>",
+ "limit": 20
+}
+```
+
+Patterns that indicate security findings:
+- Frequent 401/403 errors → possible auth bypass attempts
+- CORS errors from unexpected origins → misconfigured CORS
+- CSP violations → potential XSS vectors
+- Rate limit errors → possible brute force
+
+---
+
+## Step 3: Automated Code Scan  [HIGH freedom]
+
+### Authentication Audit
+
+- [ ] Passwords hashed with bcrypt/argon2/scrypt (not MD5/SHA1/SHA256 for passwords)
+- [ ] Session tokens are cryptographically random
+- [ ] Sessions expire appropriately (idle timeout + absolute timeout)
+- [ ] Password reset tokens are single-use and expire quickly
+- [ ] MFA available for sensitive accounts
+- [ ] Login rate limiting implemented
+- [ ] Account lockout after repeated failed attempts
+- [ ] OAuth state parameter validated (CSRF protection for OAuth flows)
+- [ ] JWT secret is strong and stored in env vars (not hardcoded)
+- [ ] JWT expiry is reasonable (access: 15min, refresh: 7d)
+
+### Authorization Audit
+
+- [ ] Every API endpoint checks permissions (not just authentication)
+- [ ] No direct object references without ownership/permission check (IDOR)
+- [ ] Role-based access properly enforced at the API layer (not just UI)
+- [ ] Principle of least privilege followed
+- [ ] Admin functions require elevated auth
+- [ ] Row-Level Security (RLS) enabled for multi-tenant databases
+- [ ] API keys scoped to minimum required permissions
+
+### Input Validation Audit
+
+- [ ] All user input validated server-side (client validation is UX only)
+- [ ] Input sanitized before use in queries, HTML, commands
+- [ ] File uploads validated: type (MIME + magic bytes), size, filename
+- [ ] JSON/XML parsing has depth/size limits
+- [ ] URL parameters decoded and validated
+- [ ] No raw SQL concatenation (parameterized queries only)
+- [ ] No `eval()`, `Function()`, `innerHTML` with user input
+- [ ] No `dangerouslySetInnerHTML` without DOMPurify
+
+### Data Protection Audit
+
+- [ ] Sensitive data encrypted at rest
+- [ ] TLS/HTTPS enforced (no HTTP fallback)
+- [ ] Secrets not in code, git history, or logs
+- [ ] PII handled according to applicable regulations (GDPR, CCPA)
+- [ ] Database connections encrypted (SSL)
+- [ ] API responses don't leak internal data (stack traces, SQL errors, file paths)
+- [ ] Password fields use `type="password"` and `autocomplete="new-password"`
+
+### Security Headers Audit
+
+- [ ] `Strict-Transport-Security` (HSTS) with long max-age
+- [ ] `Content-Security-Policy` (CSP) configured (not just `default-src *`)
+- [ ] `X-Content-Type-Options: nosniff`
+- [ ] `X-Frame-Options: DENY` or `SAMEORIGIN`
+- [ ] `Referrer-Policy: strict-origin-when-cross-origin` or stricter
+- [ ] `Permissions-Policy` restricting unnecessary browser features
+- [ ] CORS `Access-Control-Allow-Origin` is NOT `*` for authenticated endpoints
+- [ ] Cookies: `HttpOnly`, `Secure`, `SameSite=Strict` (or `Lax`)
+
+### Dependency Audit  [LOW freedom — run exactly]
+
+```bash
+npm audit # Node.js
+pip-audit # Python
+cargo audit # Rust
+govulncheck ./... # Go
+bundle audit # Ruby
+```
+
+- [ ] No known high/critical CVEs
+- [ ] Dependencies reasonably up to date
+- [ ] Lock file committed (`package-lock.json`, `yarn.lock`, `pnpm-lock.yaml`)
+- [ ] No unnecessary dependencies (smaller surface area)
+
+---
+
+## Step 4: Common Vulnerability Patterns  [HIGH freedom]
+
+Grep for the sinks, then read each hit in context:
+
+- **SQL injection** — string interpolation into a query (`` `SELECT … ${ ``, `+ userId +`); parameterized or ORM calls pass
+- **XSS** — `dangerouslySetInnerHTML` / `innerHTML` fed user input without `DOMPurify.sanitize`
+- **IDOR** — a load by `req.params.id` with no owner predicate (`userId: req.user.id`) on the query
+- **Sensitive data exposure** — `res.json(user)`-style whole-record responses instead of an explicit field pick
+
+---
+
+## Step 5: Environment and Secrets  [LOW freedom — names/prefixes only]
+
+### Scan for Hardcoded Secrets
+
+Search the codebase for potential leaked secrets. Patterns to look for:
+
+- Generic secret names: `api_key`, `apiKey`, `secret`, `password`, `token`, `credentials`, `private_key`
+- Key prefixes: `sk-`, `pk-`, `ghp_`, `gho_`, `xox[bpsa]-`, `AKIA`
+- Private key headers: `-----BEGIN (RSA|EC|OPENSSH) PRIVATE KEY-----`
+
+### Verify .gitignore
+
+```
+.env, .env.local, .env.production
+*.pem, *.key, *.p12
+credentials.json, service-account.json
+.sentryclirc (if it contains auth tokens)
+```
+
+### Validate Environment Variables
+
+```typescript
+import { z } from 'zod';
+
+const envSchema = z.object({
+ DATABASE_URL: z.string().url(),
+ API_KEY: z.string().min(1),
+ JWT_SECRET: z.string().min(32),
+ SENTRY_DSN: z.string().url().optional(),
+});
+
+const env = envSchema.parse(process.env);
+```
+
+---
+
+## Self-critique before applying fixes  [LOW freedom — do not skip]
+
+1. **Evidenced** — `file:line` or audit output, not "this might be injectable"
+2. **Reproducible** — same sink still present; no exploit PoC written
+3. **Severity justified** — Critical = demonstrated data access or leaked secret
+4. **Right owner** — session/route×gate/`getSession` → `audit-auth-flows`; RLS → `plan-rls-audit`; LLM → `audit-llm-security`
+5. **No-false-safety** — headers or middleware alone ≠ authorization
+
+## Output: Security Audit Report
+
+```markdown
+## Security Audit: [Project Name]
+
+### Tech Stack
+- Framework: [name + version]
+- Auth: [library + pattern]
+- Database: [ORM + provider]
+- Security packages: [list]
+
+### Critical Issues (must fix)
+| # | Category | Finding | File | Recommendation |
+|---|----------|---------|------|----------------|
+| 1 | Auth | JWT secret hardcoded | config.ts:12 | Move to env var |
+
+### High Risk (should fix soon)
+| # | Category | Finding | File | Recommendation |
+|---|----------|---------|------|----------------|
+
+### Medium Risk (improve when possible)
+| # | Category | Finding | File | Recommendation |
+|---|----------|---------|------|----------------|
+
+### Passed Checks
+- [list of security areas that are properly implemented]
+
+### Dependencies
+- Critical CVEs: [count] — [details]
+- High CVEs: [count]
+- Outdated packages: [count]
+
+### Research Sources
+- [URL] — [what it confirmed or revealed]
+```
+
+Session / route×gate / `getSession()` findings belong on `audit-auth-flows`,
+not in this OWASP checklist.