@jmruthers/pace-core 0.6.6 → 0.6.7

package/docs/standards/0-standards-overview.md

@@ -0,0 +1,220 @@
+# Standards Overview
+
+**🤖 Cursor Rule**: See [00-standards-overview.mdc](../../cursor-rules/00-standards-overview.mdc) for AI-optimized directives that automatically enforce these standards.
+
+## Purpose
+
+This document provides an overview of the pace-core standards system, how it works, and how to use it. These standards are the **canonical development standards** for **pace-core** and **all consuming applications** in the pace-suite.
+
+These standards are **human-readable first**, but are deliberately structured so they can be **enforced by automation**, including Cursor rules, ESLint, and custom audit tooling.
+
+They are the **single source of truth**.  
+All other quality tools must align *to these standards*, not reinterpret them.
+
+---
+
+## How to Use These Standards
+
+### pace-core
+
+- Treat these standards as **hard constraints**
+- pace-core sets the bar and defines the contracts
+- Any deviation must be explicitly documented here
+
+### Consuming Applications
+
+- Inherit these standards by default
+- Only diverge where a documented exception exists
+- Consuming apps should never weaken standards silently
+
+### AI Agents (Cursor, Codex, etc.)
+
+- Follow these standards **strictly**
+- Do **not** silence rules to "make things pass"
+- If compliance is unclear, stop and report rather than guessing
+
+---
+
+## The Four Layers of Quality Enforcement
+
+The pace-suite uses **four complementary quality layers**, each with a distinct responsibility.  
+They are intentionally overlapping in *coverage*, but **not duplicative in purpose**.
+
+Think of this as *defence in depth*, not redundancy.
+
+### 1. Standards Documents (Source of Truth)
+
+**What they are**
+- Human-readable `.md` documents
+- Describe *intent*, *principles*, and *expectations*
+- Technology-agnostic where possible
+
+**What they are used for**
+- Defining *what "good" looks like*
+- Onboarding humans and AI agents
+- Resolving ambiguity when tools disagree
+- Designing new rules, lint checks, and audits
+
+**What they are NOT**
+- They are not executable
+- They do not enforce anything by themselves
+- They should not contain implementation hacks
+
+➡️ **If there is a conflict, the standards win.**
+
+### 2. Cursor Rules (Real-time Guidance)
+
+**What they are**
+- AI-optimised interpretations of the standards
+- Applied while code is being written or modified
+- Prevent mistakes *before* they land
+
+**What they are used for**
+- Steering AI agents toward correct patterns
+- Enforcing architectural intent during development
+- Reducing rework later in linting or audits
+
+**What they are NOT**
+- They are not a replacement for lint or audits
+- They should not invent new standards
+- They should not silence problems "to move on"
+
+➡️ Cursor rules **translate standards into behaviour**, but do not redefine them.
+
+### 3. ESLint (Fast, Local Static Analysis)
+
+**What it is**
+- Deterministic, file-level static analysis
+- Runs locally and in CI
+- Focused on correctness, safety, and consistency
+
+**What it is used for**
+- Catching obvious issues early (types, hooks, imports, patterns)
+- Enforcing mechanically checkable rules
+- Preventing regressions during refactors
+
+**What it is NOT**
+- ESLint should not encode complex business rules
+- It should not contain subjective or architectural debates
+- It should not be silenced to "get green builds"
+
+➡️ ESLint enforces *how code is written*, not *whether the system is correct*.
+
+### 4. Audit Tool (Deep, System-Level Analysis)
+
+**What it is**
+- A custom static analysis tool
+- Operates across files, folders, and systems
+- Understands pace-core contracts and invariants
+- Organized by the 10-file standards structure
+
+**What it is used for**
+- Validating architectural compliance (RBAC, data access, boundaries)
+- Catching issues ESLint cannot see (cross-file analysis, configuration validation)
+- Providing actionable remediation plans
+- System-level checks (provider nesting, RLS policies in SQL, project structure)
+
+**What it is NOT**
+- It is not a linter replacement
+- It should not report stylistic issues (handled by ESLint)
+- It should not duplicate ESLint checks (file-level AST analysis)
+- It should not contradict the standards
+
+➡️ The audit tool answers: *"Is this system actually compliant?"*
+
+**Usage**: Run `npm run audit:pace-core` in your consuming app to generate a comprehensive audit report organized by standard.
+
+---
+
+## How the Layers Work Together
+
+| Layer        | Strength                         | Timing          |
+|--------------|----------------------------------|-----------------|
+| Standards    | Intent & clarity                 | Design time     |
+| Cursor rules | Preventive guidance              | Write time      |
+| ESLint       | Fast mechanical enforcement      | Dev / CI        |
+| Audit tool   | Deep architectural verification  | Review / CI     |
+
+No single layer is sufficient on its own.  
+Together, they create a **repeatable, scalable quality system** for both humans and AI.
+
+---
+
+## Precedence Order
+
+When standards conflict, apply this precedence order:
+
+1. **Security** - Security and RBAC standards take highest priority
+2. **API/RPC** - API contracts and RPC standards
+3. **Components & Markup** - Component usage and markup quality
+4. **Code Quality/Style** - TypeScript, naming, code style
+5. **Testing & Documentation** - Testing and documentation requirements
+6. **Consuming App Structure** - Project structure and organization
+
+**Example:** If a component pattern conflicts with a security requirement, security wins.
+
+---
+
+## Standards File Mapping
+
+The standards are organized into 10 files, each covering a specific domain:
+
+| File | Standard | Cursor Rule | Purpose |
+|------|----------|------------|---------|
+| `0-standards-overview.md` | Overview | `00-standards-overview.mdc` | This file - entry point and system overview |
+| `1-pace-core-compliance-standards.md` | pace-core Compliance | `01-pace-core-compliance.mdc` | Enforce pace-core usage patterns |
+| `2-project-structure-standards.md` | Project Structure | `02-project-structure.mdc` | Define standard folder structure |
+| `3-architecture-standards.md` | Architecture | `03-architecture.mdc` | Enforce SOLID architecture principles |
+| `4-code-quality-standards.md` | Code Quality | `04-code-quality.mdc` | Enforce code quality standards |
+| `5-styling-standards.md` | Styling | `05-styling.mdc` | Enforce clean markup and styling standards |
+| `6-security-rbac-standards.md` | Security & RBAC | `06-security-rbac.mdc` | Enforce RBAC contract and security |
+| `7-api-tech-stack-standards.md` | API & Tech Stack | `07-api-tech-stack.mdc` | Enforce tech stack versions and API standards |
+| `8-testing-documentation-standards.md` | Testing & Documentation | `08-testing-documentation.mdc` | Enforce testing and documentation standards |
+| `9-operations-standards.md` | Operations | `09-operations.mdc` | Enforce error handling, performance, and CI/CD |
+
+---
+
+## Quick Reference Guide
+
+**New to pace-core?** Start here:
+1. Read [Standards Overview](./0-standards-overview.md) (this file) - Understand the system
+2. Read [Styling Standards](./5-styling-standards.md) - **CRITICAL:** Required CSS setup
+3. Read [pace-core Compliance](./1-pace-core-compliance-standards.md) - How to use pace-core
+4. Read [Project Structure](./2-project-structure-standards.md) - Organize your code
+
+**Common Tasks:**
+- **Setting up a new app?** → [Project Structure](./2-project-structure-standards.md) + [Styling Standards](./5-styling-standards.md)
+- **Writing components?** → [Architecture](./3-architecture-standards.md) + [Code Quality](./4-code-quality-standards.md)
+- **Working with RBAC?** → [Security & RBAC](./6-security-rbac-standards.md)
+- **Creating APIs/RPCs?** → [API & Tech Stack](./7-api-tech-stack-standards.md)
+- **Handling errors?** → [Operations](./9-operations-standards.md)
+- **Writing tests?** → [Testing & Documentation](./8-testing-documentation-standards.md)
+
+---
+
+## Key Principles
+
+- **Do not silence tools** — fix the underlying issue
+- **Do not duplicate rules** — each layer has a purpose
+- **Do not diverge silently** — document exceptions explicitly
+- **Standards always win** — tools must align to them
+
+---
+
+## Related Documentation
+
+- [pace-core Compliance](./1-pace-core-compliance-standards.md) - pace-core usage patterns
+- [Project Structure](./2-project-structure-standards.md) - Project structure and organization
+- [Architecture](./3-architecture-standards.md) - SOLID architecture principles
+- [Code Quality](./4-code-quality-standards.md) - Code quality and TypeScript standards
+- [Styling](./5-styling-standards.md) - Markup and styling standards
+- [Security & RBAC](./6-security-rbac-standards.md) - RBAC and RLS standards
+- [API & Tech Stack](./7-api-tech-stack-standards.md) - Tech stack and API/RPC standards
+- [Testing & Documentation](./8-testing-documentation-standards.md) - Testing and documentation standards
+- [Operations](./9-operations-standards.md) - Error handling, performance, and CI/CD
+
+---
+
+**Last Updated:** 2025-01-28  
+**Version:** 2.0.0  
+**Applies to:** All pace-core and consuming apps