@soulbatical/tetra-dev-toolkit 1.20.0 → 2.0.0

package/README.md

@@ -17,8 +17,8 @@ npx tetra-setup
 ```
 
 This creates:
-- `.husky/pre-commit` — quick security checks + migration lint before every commit
-- `.husky/pre-push` — full security audit + RLS security gate before every push
+- `.husky/pre-commit` — quick security checks before every commit
+- `.husky/pre-push` — hygiene + RLS security gate before every push
 - `.github/workflows/quality.yml` — full audit on PR/push to main
 - `.tetra-quality.json` — project config (override defaults)
 
@@ -30,131 +30,67 @@ npx tetra-setup ci       # GitHub Actions only
 npx tetra-setup config   # Config file only
 ```
 
----
+Re-running `tetra-setup hooks` on an existing project adds missing hooks without overwriting existing ones.
 
-## 8-Layer Security Architecture
+---
 
-Every Tetra project is protected by 8 layers. From the moment a developer writes code to the moment a database query executes — every layer enforces security independently. If one layer is bypassed, the next catches it.
+## 3-Layer Security Model
 
-See [SECURITY.md](./SECURITY.md) for the complete architecture reference.
+Every Tetra project is protected by three layers. All three must pass before code reaches production. No fallbacks. No soft warnings. Hard errors only.
 
 ```
-LAYER 1: CONFIG FILES         Feature configs define what SHOULD happen
-LAYER 2: PRE-COMMIT           Quick checks + migration lint on staged files
-LAYER 3: PRE-PUSH             Full security audit (12 checks) + live RLS gate
-LAYER 4: MIGRATION PUSH       tetra-db-push blocks unsafe SQL before Supabase
-LAYER 5: CI/CD                TypeScript compile + tests + build
-LAYER 6: RUNTIME              Express middleware (HTTPS, CORS, auth, rate limit, input sanitize)
-LAYER 7: DATABASE              RLS policies enforce org/user isolation on every query
-LAYER 8: DB HELPERS            adminDB/userDB/publicDB/systemDB enforce correct access pattern
-```
+LAYER 1: PRE-COMMIT (tetra-audit quick)
+  Blocks: hardcoded secrets, service key exposure, direct createClient imports
 
----
+LAYER 2: PRE-PUSH (tetra-check-rls + tetra-audit hygiene)
+  Blocks: RLS violations on live DB, repo clutter, missing FORCE RLS
 
-## CLI Tools
+LAYER 3: BUILD (Railway/deploy — tetra-check-rls --errors-only)
+  Blocks: anything that bypassed --no-verify. Last line of defense.
+```
 
-| Command | Description |
-|---------|-------------|
-| `tetra-audit` | Run quality/security/hygiene checks |
-| `tetra-audit quick` | Quick critical checks (pre-commit) |
-| `tetra-audit security` | Full security suite (12 checks) |
-| `tetra-audit stability` | Stability suite (16 checks) |
-| `tetra-audit codeQuality` | Code quality suite (4 checks) |
-| `tetra-audit supabase` | Supabase suite (3 checks) |
-| `tetra-audit hygiene` | Repo hygiene suite (2 checks) |
-| `tetra-audit --ci` | CI mode (GitHub Actions annotations) |
-| `tetra-audit --json` | JSON output |
-| `tetra-audit --verbose` | Detailed output with fix suggestions |
-| `tetra-migration-lint` | Offline SQL migration linter (8 rules) |
-| `tetra-migration-lint --staged` | Only git-staged .sql files (pre-commit hook) |
-| `tetra-migration-lint --fix-suggestions` | Show fix SQL per violation |
-| `tetra-db-push` | Safe wrapper: lint + `supabase db push` |
-| `tetra-check-rls` | RLS security gate against live Supabase |
-| `tetra-check-rls --fix` | Generate hardening migration SQL |
-| `tetra-setup` | Install hooks, CI, and config |
-| `tetra-init` | Initialize project config files |
-| `tetra-dev-token` | Generate development tokens |
+### Layer 1: Pre-commit
 
-Exit codes: `0` = passed, `1` = failed (CRITICAL/HIGH), `2` = error. No middle ground.
+Installed by `tetra-setup hooks`. Runs `tetra-audit quick` which executes critical security checks:
 
----
+| Check | What it catches |
+|-------|-----------------|
+| Hardcoded Secrets | API keys, tokens, JWTs in source code |
+| Service Key Exposure | Supabase service role keys in frontend code |
+| Direct Supabase Client | `createClient()` imports outside core db wrappers |
 
-## Check Suites
+If any check fails, the commit is **blocked**. No `--force`, no workaround.
 
-### Security (12 checks)
+### Layer 2: Pre-push (RLS Security Gate)
 
-| Check | Severity | What it catches |
-|-------|----------|-----------------|
-| `hardcoded-secrets` | critical | API keys, tokens, JWTs in source code |
-| `service-key-exposure` | critical | Supabase service role keys in frontend |
-| `deprecated-supabase-admin` | critical | Legacy `supabaseAdmin` patterns |
-| `direct-supabase-client` | critical | Direct `createClient` imports outside core wrappers |
-| `frontend-supabase-queries` | critical | `.from()` / `.rpc()` / `.storage` calls in frontend code |
-| `tetra-core-compliance` | critical | Missing configureAuth, authenticateToken, or db helpers |
-| `mixed-db-usage` | critical | Controller uses wrong DB helper or mixes types |
-| `config-rls-alignment` | critical | Feature config accessLevel does not match RLS policies |
-| `rpc-security-mode` | critical | SECURITY DEFINER on data RPCs (bypasses RLS) |
-| `route-config-alignment` | high | Route middleware does not match config accessLevel |
-| `systemdb-whitelist` | high | systemDB() in unauthorized contexts |
-| `gitignore-validation` | high | Missing .gitignore entries, tracked .env files |
-
-### Migration Lint (8 rules)
-
-| Rule | Severity | What it catches |
-|------|----------|-----------------|
-| `DEFINER_DATA_RPC` | critical | SECURITY DEFINER on data RPCs |
-| `CREATE_TABLE_NO_RLS` | critical | New table without ENABLE ROW LEVEL SECURITY |
-| `DISABLE_RLS` | critical | ALTER TABLE ... DISABLE RLS |
-| `USING_TRUE_WRITE` | critical | USING(true) on INSERT/UPDATE/DELETE/ALL policies |
-| `GRANT_PUBLIC_ANON` | critical | GRANT write permissions to public/anon |
-| `RAW_SERVICE_KEY` | critical | Hardcoded JWT in migration file |
-| `DROP_POLICY` | high | DROP POLICY without replacement in same migration |
-| `POLICY_NO_WITH_CHECK` | medium | INSERT/UPDATE policy without WITH CHECK clause |
+Installed by `tetra-setup hooks`. Runs before every `git push`. Two checks:
 
-### Supabase (3 checks, auto-detected)
+1. **Repo hygiene** — `tetra-audit hygiene` blocks clutter
+2. **RLS Security Gate** — `tetra-check-rls --errors-only` against the live Supabase database
 
-| Check | Severity | What it catches |
-|-------|----------|-----------------|
-| `rls-policy-audit` | critical | Tables without Row Level Security |
-| `rpc-param-mismatch` | critical | TypeScript `.rpc()` calls with wrong parameter names vs SQL |
-| `rpc-generator-origin` | high | RPC functions not generated by Tetra SQL Generator |
+The RLS gate auto-detects your Doppler project from `doppler.yaml` and runs 23 checks across 6 categories:
 
-### Stability (16 checks)
+| Category | Checks | What it catches |
+|----------|--------|-----------------|
+| Foundation | 3 | Tables without RLS, missing FORCE RLS, RLS without policies |
+| Policy Quality | 5 | Public role mutations, always-true policies, missing WITH CHECK |
+| Auth Functions | 4 | Missing auth functions, wrong SECURITY DEFINER, bad search_path |
+| Bypass Routes | 5 | SECURITY DEFINER data functions, anon grants, views bypassing RLS |
+| Data Exposure | 1 | Realtime enabled on sensitive tables |
+| Migration State | 4 | Non-Tetra auth patterns, missing org columns |
 
-| Check | Severity | What it catches |
-|-------|----------|-----------------|
-| `husky-hooks` | medium | Missing pre-commit/pre-push hooks |
-| `ci-pipeline` | medium | Missing or incomplete CI config |
-| `npm-audit` | high | Known vulnerabilities in dependencies |
-| `tests` | high | Missing test framework, test files, or test scripts |
-| `eslint-security` | high | Missing ESLint config, security plugin, or SonarJS plugin |
-| `typescript-strict` | medium | TypeScript strict mode not enabled |
-| `coverage-thresholds` | medium | No coverage thresholds configured |
-| `knip` | medium | Dead code: unused files, dependencies, exports |
-| `dependency-cruiser` | medium | Circular dependencies, architecture violations |
-| `dependency-automation` | medium | No Dependabot or Renovate configured |
-| `prettier` | low | No code formatter configured |
-| `conventional-commits` | low | No commit message convention enforced |
-| `bundle-size` | low | No bundle size monitoring |
-| `sast` | medium | No static application security testing |
-| `license-audit` | low | No license compliance checking |
-| `security-layers` | high | Missing security layers (auth, rate limiting, CORS, etc.) |
+If the RLS gate fails, the push is **blocked**. No `--no-verify` escape — Layer 3 catches that.
 
-### Code Quality (4 checks)
+### Layer 3: Build-time check
 
-| Check | Severity | What it catches |
-|-------|----------|-----------------|
-| `api-response-format` | medium | Non-standard response format |
-| `file-size` | medium | Files exceeding line limits |
-| `naming-conventions` | medium | Inconsistent file/dir naming |
-| `route-separation` | high | Business logic in route files |
+Add to your Railway/deploy build command:
 
-### Hygiene (2 checks)
+```bash
+# Railway build command
+doppler run -- npx tetra-check-rls --errors-only && npm run build
+```
 
-| Check | Severity | What it catches |
-|-------|----------|-----------------|
-| `file-organization` | high | Stray .md, .sh, clutter in code dirs |
-| `stella-compliance` | medium | Missing Stella integration |
+This catches developers who bypass git hooks with `--no-verify`. If RLS is broken, the build fails, the deploy never happens.
 
 ---
 
@@ -181,194 +117,255 @@ adminDB(req)                         →  Uses user's JWT. RLS enforces org boun
 
 A single `createClient` call with the service role key can leak data across all organizations. The db helpers enforce the security boundary at the application layer.
 
----
+### Allowed exceptions
 
-## Configuration
+These files MAY import `createClient` directly because they ARE the wrappers:
 
-Override defaults in `.tetra-quality.json`:
+- `core/systemDb.ts`, `core/publicDb.ts`, `core/adminDb.ts`, `core/userDb.ts`, `core/superadminDb.ts`
+- `core/Application.ts` (bootstrap)
+- `features/database/services/SupabaseUserClient.ts`
+- `auth/controllers/AuthController.ts` (needs `auth.admin` API)
+- `backend-mcp/src/supabase-client.ts`, `org-scoped-client.ts`, `api-key-service.ts`, `http-server.ts`
+- `scripts/` (not production code)
 
-```json
-{
-  "suites": {
-    "security": true,
-    "stability": true,
-    "codeQuality": true,
-    "supabase": "auto",
-    "hygiene": true
-  },
-  "supabase": {
-    "publicRpcFunctions": ["get_public_data"],
-    "publicTables": ["public_lookup"],
-    "backendOnlyTables": ["system_logs", "cron_state"],
-    "securityDefinerWhitelist": ["auth_org_id", "auth_uid"]
-  },
-  "ignore": ["**/legacy/**", "**/scripts/**"]
-}
-```
+Everything else gets a **hard error** at commit time.
 
 ---
 
-## New Project Checklist
+## Usage
 
 ```bash
-# 1. Install hooks (creates pre-commit + pre-push)
-npx tetra-setup hooks
-
-# 2. Run full audit
-npx tetra-audit
+npx tetra-audit              # Run all checks
+npx tetra-audit security     # Security checks only
+npx tetra-audit stability    # Stability checks only
+npx tetra-audit codeQuality  # Code quality checks only
+npx tetra-audit supabase     # Supabase checks only
+npx tetra-audit hygiene      # Repo hygiene checks only
+npx tetra-audit quick        # Quick critical checks (pre-commit)
+npx tetra-audit --ci         # CI mode (GitHub Actions annotations)
+npx tetra-audit --json       # JSON output
+npx tetra-audit --verbose    # Detailed output with fix suggestions
+```
 
-# 3. Run RLS gate manually
-doppler run -- npx tetra-check-rls
+Exit codes: `0` = passed, `1` = failed, `2` = error. No middle ground.
 
-# 4. Verify migration lint works
-npx tetra-migration-lint
+## RLS Security Gate (standalone)
 
-# 5. Add to Railway build command
-# doppler run -- npx tetra-check-rls --errors-only && npm run build
+```bash
+npx tetra-check-rls                              # Auto-detect from doppler.yaml
+npx tetra-check-rls --url <url> --key <key>      # Explicit credentials
+npx tetra-check-rls --errors-only                # CI/build mode
+npx tetra-check-rls --json                       # JSON output for automation
+npx tetra-check-rls --fix                        # Generate hardening migration SQL
+npx tetra-check-rls --check-exec-sql             # Verify exec_sql function is secure
 ```
 
-If any step fails, fix it before writing code. No exceptions.
+### Programmatic usage
+
+```typescript
+import { runRLSCheck } from '@soulbatical/tetra-core';
+
+const report = await runRLSCheck(supabaseServiceClient);
+if (!report.passed) {
+  throw new Error(report.summary); // Hard error. No soft fail.
+}
+```
 
 ---
 
-## Claude Code statusline
+## Check Suites
 
-A 3-line statusline for Claude Code that shows context usage, costs, project health, and session metadata.
+### Security (6 checks)
 
-### Setup
+| Check | Severity | What it catches |
+|-------|----------|-----------------|
+| Hardcoded Secrets | critical | API keys, tokens, JWTs in source code |
+| Service Key Exposure | critical | Supabase service role keys in frontend |
+| Deprecated Supabase Admin | high | Legacy `supabaseAdmin` patterns |
+| Direct Supabase Client | critical | Direct `createClient` imports outside core wrappers |
+| SystemDB Whitelist | critical | Unauthorized service role key usage in authenticated routes |
+| Gitignore Validation | high | Missing .gitignore entries, tracked .env files |
 
-```bash
-# Symlink the script
-ln -sf /path/to/tetra/packages/dev-toolkit/hooks/statusline.sh ~/.claude/hooks/statusline.sh
+### Stability (3 checks)
 
-# Add to ~/.claude/settings.json
-{
-  "statusLine": {
-    "type": "command",
-    "command": "~/.claude/hooks/statusline.sh"
-  }
-}
-```
+| Check | Severity | What it catches |
+|-------|----------|-----------------|
+| Husky Hooks | medium | Missing pre-commit/pre-push hooks |
+| CI Pipeline | medium | Missing or incomplete CI config |
+| NPM Audit | high | Known vulnerabilities in dependencies |
 
-### What it shows
+### Code Quality (4 checks)
 
-```
-repo: vibecodingacademy  tasks: 3 open / 12 done  started by: user  cmux: workspace:308 ⠂ Claude Code
-opus  ██████░░░░░░░░░ 44%  context: 89K / 200K  99% cached  this turn: +7K
-$3.76  5m20s  (api: 3m5s)  lines: +47 -12  turn #5  main*  v2.1.73
-```
+| Check | Severity | What it catches |
+|-------|----------|-----------------|
+| API Response Format | medium | Non-standard response format |
+| File Size | medium | Files exceeding line limits |
+| Naming Conventions | medium | Inconsistent file/dir naming |
+| Route Separation | high | Business logic in route files |
 
-**Line 1 — project dashboard**
+### Supabase (3 checks, auto-detected)
 
-| Field | Source | Description |
-|-------|--------|-------------|
-| `repo:` | `workspace.project_dir` | Current project directory name |
-| `tasks:` | `.ralph/@fix_plan.md` | Open/done task count from Ralph fix plan |
-| `started by:` | Process tree + cmux | `user`, `monica`, `ralph`, `cursor`, `vscode` |
-| `cmux:` | `cmux identify` + `cmux list-workspaces` | Workspace ref and name (only in cmux terminal) |
+| Check | Severity | What it catches |
+|-------|----------|-----------------|
+| RLS Policy Audit | critical | Tables without Row Level Security |
+| RPC Param Mismatch | critical | TypeScript `.rpc()` calls with wrong parameter names vs SQL |
+| RPC Generator Origin | high | RPC functions not generated by Tetra SQL Generator |
 
-**Line 2 — context window**
+### Hygiene (2 checks)
 
-| Field | Source | Description |
-|-------|--------|-------------|
-| Model | `model.id` | Short name: `opus`, `sonnet`, `haiku` |
-| Progress bar | `context_window.used_percentage` | 15-char bar, green <50%, yellow 50-80%, red >80% |
-| `context:` | input + cache tokens | Effective tokens in window vs max |
-| `cached` | `cache_read / context` | % of context served from prompt cache (saves cost) |
-| `this turn:` | Delta from previous turn | Token growth this turn (helps spot expensive hooks) |
+| Check | Severity | What it catches |
+|-------|----------|-----------------|
+| File Organization | high | Stray .md, .sh, clutter in code dirs |
+| Stella Compliance | medium | Missing Stella integration |
 
-**Line 3 — session stats**
+---
 
-| Field | Source | Description |
-|-------|--------|-------------|
-| Cost | `cost.total_cost_usd` | Session cost so far |
-| Duration | `cost.total_duration_ms` | Wall clock time |
-| API time | `cost.total_api_duration_ms` | Time spent waiting for API responses |
-| Lines | `cost.total_lines_added/removed` | Code changes this session |
-| Turn | Delta tracker | Number of assistant responses |
-| Branch | `git branch` | Current branch, `*` if dirty |
-| Version | `version` | Claude Code version |
+## Health Checks
+
+Scored assessment (0-N points) used by the Ralph Manager dashboard:
+
+| Check | Max | What it measures |
+|-------|-----|------------------|
+| File Organization | 6pt | Docs in /docs, scripts in /scripts, clean root & code dirs |
+| Git | 4pt | Clean working tree, branch hygiene, commit frequency |
+| Gitignore | 3pt | Critical entries present |
+| CLAUDE.md | 3pt | Project instructions for AI assistants |
+| Secrets | 3pt | No exposed secrets |
+| Tests | 4pt | Test framework, coverage, test files |
+| Naming Conventions | 5pt | File/dir naming consistency |
+| Infrastructure YML | 3pt | Railway/Docker config |
+| Doppler Compliance | 2pt | Secrets management via Doppler |
+| MCP Servers | 2pt | MCP configuration |
+| Stella Integration | 2pt | Stella package integration |
+| Quality Toolkit | 2pt | Tetra dev-toolkit installed |
+| Repo Visibility | 1pt | Private repo |
+| RLS Audit | 3pt | Row Level Security policies |
+| Plugins | 2pt | Claude Code plugin config |
+| VinciFox Widget | 1pt | Widget installation |
 
-### How "started by" detection works
+---
 
-1. If running in cmux: checks workspace name — `monica:*` → `monica`
-2. Fallback: walks the process tree looking for `ralph`, `cursor`, `code` (VS Code)
-3. Default: `user` (manual terminal session)
+## Auto-fix: Cleanup Script
 
-### Task colors
+For hygiene issues, an auto-fix script is included:
 
-| Color | Meaning |
-|-------|---------|
-| Green | 0 open tasks (all done) |
-| Yellow | 1-10 open tasks |
-| Red | 10+ open tasks |
+```bash
+# Dry run (shows what would change)
+bash node_modules/@soulbatical/tetra-dev-toolkit/bin/cleanup-repos.sh
 
-Projects without `.ralph/@fix_plan.md` don't show the tasks field.
+# Execute
+bash node_modules/@soulbatical/tetra-dev-toolkit/bin/cleanup-repos.sh --execute
+```
 
 ---
 
-## Changelog
+## Configuration
 
-### 1.16.0
+Override defaults in `.tetra-quality.json` or `"tetra-quality"` key in `package.json`:
 
-**New: Full Stability Suite (16 checks)**
-- Stability suite expanded from 3 → 16 checks via health check adapter
-- New checks: tests, eslint-security, typescript-strict, coverage-thresholds, knip, dependency-cruiser, dependency-automation, prettier, conventional-commits, bundle-size, sast, license-audit, security-layers
-- `tetra-audit stability` now catches missing test infrastructure, dead code, formatting, and security layer gaps
-- Health checks (score-based) automatically adapted to runner format (pass/fail)
-- RPC generator: SECURITY DEFINER → SECURITY INVOKER for all data RPCs
-- Migration lint: expanded whitelist for legitimate DEFINER functions
-- Mixed DB checker: fixed regex that matched `superadminDB` as `adminDB`
-- Route config checker: support `@tetra-audit-ignore` directive
+```json
+{
+  "suites": {
+    "security": true,
+    "stability": true,
+    "codeQuality": true,
+    "supabase": "auto",
+    "hygiene": true
+  },
+  "supabase": {
+    "publicRpcFunctions": ["get_public_data"],
+    "publicTables": ["public_lookup"]
+  },
+  "stability": {
+    "allowedVulnerabilities": {
+      "critical": 0,
+      "high": 0,
+      "moderate": 10
+    }
+  }
+}
+```
+
+---
+
+## CLI Tools
 
-### 1.15.0
+| Command | Description |
+|---------|-------------|
+| `tetra-audit` | Run quality/security/hygiene checks |
+| `tetra-setup` | Install hooks, CI, and config |
+| `tetra-check-rls` | RLS security gate against live Supabase |
+| `tetra-init` | Initialize project config files |
+| `tetra-dev-token` | Generate development tokens |
 
-**New: Migration Lint + DB Push Guard**
-- `tetra-migration-lint` — offline SQL migration linter (8 rules)
-- `tetra-db-push` — safe wrapper around `supabase db push` (lint first, push second)
-- Pre-commit hook now lints staged `.sql` files automatically
-- Rules: DEFINER on data RPCs, CREATE TABLE without RLS, DISABLE RLS, USING(true) writes, GRANT public/anon, DROP POLICY without replacement, missing WITH CHECK, hardcoded JWT
+---
 
-### 1.14.0
+## New Project Checklist
 
-**New: Config-RLS Alignment + Route-Config Alignment + RPC Security Mode**
-- `config-rls-alignment` — verifies feature config accessLevel matches RLS policies on the table
-- `route-config-alignment` — verifies route middleware matches config accessLevel (admin routes need auth middleware)
-- `rpc-security-mode` — scans ALL RPCs for SECURITY DEFINER (must be INVOKER unless whitelisted)
+After `npm install` in a new Tetra project:
 
-### 1.13.0
+```bash
+# 1. Install hooks (creates pre-commit + pre-push)
+npx tetra-setup hooks
 
-**New: Mixed DB Usage Detection**
-- `mixed-db-usage` — controllers must use exactly ONE DB helper type matching their naming convention
-- AdminController → adminDB only, UserController → userDB only, etc.
-- Detects systemDB misuse when authenticated user context is available
+# 2. Verify hooks are active
+cat .husky/pre-commit   # Should contain tetra-audit quick
+cat .husky/pre-push     # Should contain tetra-check-rls
 
-### 1.12.0
+# 3. Run full audit
+npx tetra-audit
 
-**New: Tetra Core Compliance**
-- `tetra-core-compliance` — if a project has @soulbatical/tetra-core, it MUST use configureAuth, authenticateToken, and db helpers
-- No more "skipped" checks — if tetra-core is a dependency, ALL security checks run
+# 4. Run RLS gate manually once
+doppler run -- npx tetra-check-rls
 
-### 1.11.0
+# 5. Add to Railway build command
+# doppler run -- npx tetra-check-rls --errors-only && npm run build
+```
 
-**New: Frontend Supabase Queries check**
-- `frontend-supabase-queries` — blocks `.from()`, `.rpc()`, `.storage` in frontend code
-- Frontend MUST use API client, never query Supabase directly
+If any step fails, fix it before writing code. No exceptions.
 
-### 1.10.0
+---
 
-**Improved: RLS Policy Audit**
-- Tables with RLS ON but 0 policies now flagged as CRITICAL (was HIGH)
-- New config: `supabase.backendOnlyTables` for tables that intentionally have no policies
+## Changelog
 
 ### 1.9.0
 
-**New: Direct Supabase Client check + 3-Layer Security Model**
+**New: Direct Supabase Client check (CRITICAL)**
+- Added `direct-supabase-client` check in security suite
+- Blocks any `createClient` import from `@supabase/supabase-js` outside core db wrappers
+- Hard error at commit time — no fallback, no override
+- Type-only imports (`import type { SupabaseClient }`) are allowed
+- Allowed files whitelist: core wrappers, auth controller, MCP server internals, scripts
+
+**New: 3-Layer Security Model documentation**
+- Layer 1: Pre-commit (tetra-audit quick)
+- Layer 2: Pre-push (tetra-check-rls + hygiene)
+- Layer 3: Build-time (tetra-check-rls --errors-only in Railway)
+- Complete Supabase Client Architecture docs with the 5 db helpers
+
+**Improved: prepublishOnly hooks**
+- tetra-core: `npm run build && npm run typecheck` before publish
+- tetra-dev-toolkit: `npm test` before publish
+
+### 1.3.0 (2025-02-21)
 
-### 1.3.0
+**New: Hygiene suite**
+- Added `tetra-audit hygiene` — detects stray docs, scripts, clutter in code dirs
+- Added `cleanup-repos.sh` auto-fix script in `bin/`
+- `tetra-setup hooks` now creates pre-push hook with hygiene gate
+- Re-running `tetra-setup hooks` on existing repos adds hygiene check without overwriting
 
-**New: Hygiene suite + RPC Param Mismatch check**
+**New: RPC Param Mismatch check**
+- Added `rpc-param-mismatch` check in supabase suite
+- Statically compares `.rpc()` calls in TypeScript with SQL function parameter names
+- Catches PGRST202 errors before they hit production
 
 ### 1.2.0
 
 - Initial public version
+- Security suite: hardcoded secrets, service key exposure, deprecated admin, systemdb whitelist, gitignore
+- Stability suite: husky hooks, CI pipeline, npm audit
+- Code quality suite: API response format
+- Supabase suite: RLS policy audit
+- Health checks: 16 checks, max 37pt
+- CLI: `tetra-audit`, `tetra-setup`, `tetra-dev-token`