Review and Audits

Static analysis tools catch structural violations, but some rules require understanding business context. The /arch-review Claude Code skill performs qualitative assessment using the project's static tools as data sources, then layers AI analysis on top. Monthly scheduled audits automate this process.

The Arch-Review Checklist

docs/arch-review-checklist.md is the bridge between machine enforcement and AI-assisted review. It has 7 sections and 19 rules covering both machine-enforced rules (with "what bypassing looks like" guidance) and semantic rules that require understanding business intent.

Section	Severity	Rules
1. Tenant Isolation and RLS	Critical	1.1 No bare db in tenant-scoped code; 1.2 New tables have RLS
2. Authorization	Critical	2.1 authorizedProcedure enforcement; 2.2 CASL ability.can() before mutations
3. AI Layer	High	3.1 feature field on all AI calls; 3.2 ctx.ai in routers
4. Logging and Observability	High	4.1 No console.log; 4.2 ctx.logger in routers; 4.3 Structured logging format
5. Package Boundaries	High	5.1 SDK imports through wrappers; 5.2 Layer hierarchy
6. MCP Tools	Medium	6.1 Tool registration in server.ts; 6.2 Audit log writes; 6.3 withTenantContext()
7. Enforcement Integrity	Medium	7.1 No eslint-disable for architectural rules; 7.2 Allowlist justification; 7.3 @repo/db main entrypoint; 7.4 ESLint config integrity

Every machine-enforced rule is also on the checklist with "what bypassing looks like" guidance. This catches the second-order problem: an AI agent might not violate a rule directly but might weaken the enforcement mechanism itself (removing an ESLint rule, adding an unjustified allowlist entry, modifying restrictions.js).

For full tenant isolation enforcement details, see Identity & Access -- Tenant Isolation Enforcement. For the review rules specifically, see Identity & Access -- Review Rules.

The /arch-review Skill

/arch-review is a Claude Code skill (.claude/skills/arch-review/SKILL.md) that performs a 6-dimension architecture quality audit. It uses the project's existing tooling as data sources, then adds qualitative analysis.

Six Scoring Dimensions

Dimension	What It Measures	Data Sources
Boundary compliance	Package layer hierarchy, SDK wrapper enforcement, import direction	dependency-cruiser output, restrictions.js
Complexity	ESLint complexity scores, cognitive complexity, file sizes, nesting	ESLint JSON output
Coupling	Circular dependencies, shared mutable state, fan-in/fan-out ratios	dependency-cruiser graph
Consistency	Naming patterns, error handling, module structure	ESLint naming-convention, code inspection
Dead code and duplication	Unused exports/files/dependencies, duplicated logic	Knip output, jscpd output
Debt signals	Expired TODOs, hotspot files, stale allowlist entries	Hotspot script, TODO scan

Each dimension is scored 0--10. Findings include severity, specific file locations, and actionable remediation steps.

Auto-Promoted Findings

Certain findings are automatically promoted to HIGH severity regardless of score:

• RLS bypass -- bare db in tenant-scoped code
• Direct SDK imports -- bypassing wrapper packages
• Missing audit logs -- plan/step mutations without writeAuditLog()
• Missing CASL checks -- mutations without ctx.ability.can()
• Bare db usage -- in any context where withTenantContext should be used

The /dep-check Skill

/dep-check is a companion skill (.claude/skills/dep-check/SKILL.md) that evaluates dependency health. It replaces the periodic "are our library choices still right?" review.

Four Phases

1. Inventory -- parses all package.json files, builds a dependency map, checks for version conflicts and catalog gaps
2. Health check -- for each dependency: last publish date (flag if >6 months), open issues, maintainer count, download trends, TypeScript support, known CVEs
3. Alternative discovery -- for at-risk and major dependencies, searches for better alternatives
4. Upgrade status -- cross-references Renovate pending PRs, flags stalled major upgrades

Skip rules: @types/* follow their parent, @repo/* excluded, dev-only tooling is lower priority.

Scheduled Monthly Audits

Monthly automated audits run /arch-review, /dep-check, and hotspot analysis via Claude Code /schedule. Daily runs were initially configured but found to be redundant with CI -- the static analysis tools already run on every PR. Only qualitative monthly assessments add value beyond what CI catches.

Audit Workflow

1. Run /arch-review on the full codebase (collect scores and findings)
2. Run /dep-check on the full monorepo (collect at-risk dependencies)
3. Run bash scripts/hotspot-analysis.sh (collect hotspot report)
4. If any CRITICAL/HIGH findings, or overall rating is YELLOW/RED, or any HIGH-risk dependencies: create a Linear issue with audit-finding label
5. If a previous audit-finding issue is still open, update it instead of creating a duplicate
6. If everything is GREEN: complete silently
7. On the first run of each month, write the full report to docs/reports/arch-audit-YYYY-MM.md

Enforcement Config Protection

The enforcement system protects itself through three mechanisms:

1. CODEOWNERS -- GitHub CODEOWNERS requires founder review for changes to .dependency-cruiserrc.mjs, restrictions.js, ESLint base config, and architecture test files
2. Arch-review-checklist Section 7 -- specifically audits for weakened ESLint configs, expanded allowlists, and removed dependency-cruiser rules
3. Monthly audit -- the /arch-review skill checks enforcement integrity as one of its dimensions

Related Pages

• Identity & Access -- Tenant Isolation Enforcement -- tenant isolation enforcement details
• Identity & Access -- Review Rules -- review checklist rules for tenant isolation
• Hotspot Analysis -- the hotspot script that feeds monthly audits
• Fitness Tests -- the authorizedProcedure test whose allowlist is audited