agent-enderun 0.6.5 → 0.6.6

package/.enderun/blueprints/README.md

@@ -0,0 +1,82 @@
+# Blueprints
+
+This directory stores **Gold Standard** reusable patterns and architectural capabilities for Agent Enderun.
+
+## Purpose
+
+Blueprints allow agents to store and reuse high-quality, repeatable architectural patterns, error systems, UI components, or business logic structures.
+
+Goals:
+- Standardize recurring high-quality solutions
+- Enable agents to work from proven patterns instead of starting from scratch
+- Raise quality at the framework level, not just per-project
+
+## How It Works
+
+Agents use the following tools to work with blueprints:
+
+- `list_blueprints` → Lists all available blueprints
+- `instantiate_blueprint` → Copies a blueprint into the user's project
+- `save_as_blueprint` → Saves a new high-quality solution as a blueprint
+
+## Recommended Folder Structure
+
+For a clean and maintainable structure, the following format is recommended:
+
+```
+blueprints/
+├── backend/
+│   ├── errors/
+│   │   ├── config/
+│   │   │   └── meta.json          # Blueprint metadata
+│   │   └── domain-error.ts        # Source code
+│   └── ...
+├── frontend/
+│   └── ...
+├── general/
+│   └── ...
+└── README.md
+```
+
+**Mandatory Discipline Rule:**  
+Categories without actual content **must not** create folders on disk. Empty folders are only listed as plans in this README. When a new blueprint is added, the relevant folder + `config/meta.json` + source code are added together.
+
+Each blueprint folder contains:
+- `config/meta.json` → Blueprint metadata (description, category, version, recommendedPath, etc.)
+- Relevant source code files (at least 1 file)
+
+## Maintenance and Discipline Rules (When Content Is Low)
+
+This folder must **always** be kept clean and professional. Even with low content, clutter or empty folders are not allowed.
+
+- Only blueprints that have actually been added and are working exist as folders on disk.
+- Planned categories (middleware, repositories, frontend/components, etc.) are **only listed as plans in this README**; no folders are created on disk.
+- Every time a new blueprint is added, this README and related knowledge documents are updated.
+- Empty folders are cleaned up or never created (structure governance rule).
+
+## Current Blueprints
+
+Currently there is only 1 mature example:
+
+- `backend/errors/` → DomainError-based error system (Gold Standard)
+  - `config/meta.json`
+  - `domain-error.ts`
+
+Other categories (middleware, repositories, frontend, general) do not yet have content, so no folders exist on disk.
+
+## Rules for Adding New Blueprints
+
+1. Only truly high-quality and repeatable solutions should be saved as blueprints.
+2. Every blueprint must have a short description inside `config/meta.json`.
+3. Blueprints should be as framework-agnostic as possible (easy to adapt when copied).
+4. Before adding a new blueprint, check with `list_blueprints` whether something similar already exists.
+5. **When adding a new blueprint, the folder + config/meta.json + at least one source code file must be added together.** Empty folders are not created.
+
+## Related Documents
+
+- `.enderun/knowledge/blueprint_driven_construction.md` (Blueprint usage philosophy)
+- `framework-mcp/src/tools/scaffold.ts` (Technical implementation)
+
+---
+
+**Note:** This folder must be dynamically grown by the agents. Even with low content, it must be kept **organized, documented, and disciplined** at all times (structure governance rule 2026-05-24 item 2).

package/.enderun/docs/README.md

@@ -0,0 +1,50 @@
+# .enderun/docs/ — Framework Governance Documentation
+
+**Owner:** @manager  
+**Created:** 24 May 2026  
+**Purpose:** Clear separation of governance, audit, and internal framework documentation belonging to the `.enderun/` layer.
+
+---
+
+## What This Folder Contains
+
+This folder contains **only** Agent Enderun's own internal rules, policies, and governance documents.
+
+### Content Summary
+
+- `api/` → MCP tool contracts, auth, errors (synchronized with `{{FRAMEWORK_DIR}}/docs/api/`)
+- `error-handling.md`, `security.md`, `privacy.md`, `troubleshooting.md` → Mandatory framework-level standards
+- `structure-audit-2026-05-24.md` → Structure, naming, and folder discipline audit reports
+- `phase1-reference-app-execution-plan.md` → Phase 1 execution plan for the framework team
+- `project-docs.md` → Project documentation policies (governance-focused)
+- `tech-stack.md` → Framework technology stack decisions
+
+---
+
+## Clear Distinction Between root `docs/` and `.enderun/docs/`
+
+| Folder              | Type                          | Content Type                                      | Ownership Rule                          | Example Files                          |
+|---------------------|-------------------------------|---------------------------------------------------|-----------------------------------------|----------------------------------------|
+| `docs/` (root)      | **Project / Product Documentation** | User-facing guides, roadmaps, and action plans provided by Agent Enderun | The project's own `docs/` structure (Documentation Ownership Rule) | getting-started.md, roadmap.md, action-plan-2026.md, README.md |
+| `.enderun/docs/`    | **Framework Governance**     | Only the framework's internal rules, audits, API contracts, and security policies | Same layer as `.enderun/knowledge/`    | api/, structure-audit-*.md, security.md, phase1-*.md |
+
+### Fundamental Rule (Mandatory)
+
+- If it is a **framework rule or governance decision** → `.enderun/docs/` or `.enderun/knowledge/`
+- If it is **user-project-specific implementation detail, pattern, or decision** → **User project's own `docs/` folder** (root `docs/` in this repository)
+
+This distinction is **fully compliant** with the rule in `.enderun/knowledge/documentation_ownership.md`.
+
+**Never** write user-project-specific items such as toaster implementations, approval flow details, component patterns, or technical debt findings here or into `.enderun/knowledge/`.
+
+---
+
+## Related Rules
+
+- See `.enderun/knowledge/documentation_ownership.md` (mandatory reading for all agents)
+- See `structure-audit-2026-05-24.md` (items 6.5 and 7)
+- See ENDERUN.md → Core Principles (Framework vs User Project Boundary)
+
+---
+
+**This file clarifies the purpose of the `.enderun/docs/` folder and prevents structural confusion.**

package/.enderun/docs/phase1-reference-app-execution-plan.md

@@ -0,0 +1,177 @@
+# Phase 1 Reference Application — Granular Execution Plan (v0.6.5)
+
+**Owner:** @manager  
+**Status:** APPROVED & ACTIVE (23 May 2026)  
+**Goal:** Produce the first production-grade reference application inside `apps/` that proves the entire governance system (Kurumsal CRUD, managerApproval, Hermes, Contract-First, Audit) works in practice.
+
+**Critical Rules (Non-Negotiable)**
+- All code lives **only** inside `apps/backend/` and `apps/web/`
+- Never touch `framework-mcp/`, `.enderun/agents/`, root config files
+- Contract-First + Branded Types mandatory
+- Every high-risk action requires explicit `managerApproval`
+- Zero mock data (except 3rd party like Stripe)
+- Full audit logging + Trace ID on every change
+
+---
+
+## Phase 1 Execution Steps (18 Concrete Steps)
+
+### Preparation (Steps 1-2)
+
+**Step 1: Activate Execution Plan in Memory**
+- Read current `PROJECT_MEMORY.md`
+- Add new section: "Phase 1 Reference App Execution — Started 2026-05-23"
+- Record Trace ID for this plan (generate via `enderun:trace` or manual ULID)
+- Update Strategic Roadmap to mark Phase 1 as IN_PROGRESS
+- Log this action with `log_agent_action`
+
+**Step 2: Workspace Validation**
+- Confirm `apps/` directory does not exist or is empty
+- Verify workspaces in root `package.json` already declare `"apps/*"`
+- Check that `framework-mcp` is buildable (`npm run enderun:build`)
+- Confirm no existing user project code that would conflict
+
+---
+
+### Backend Foundation (Steps 3-8)
+
+**Step 3: Create Backend Monorepo Skeleton**
+- `mkdir -p apps/backend/src/{types,db, routes, plugins, utils}`
+- `cd apps/backend && npm init -y`
+- Add required dependencies:
+  - fastify, @fastify/cors, @fastify/jwt, kysely, kysely-postgres, zod, @types/node
+- Create `tsconfig.json` (strict, ESM, paths for @/types)
+- Add scripts: `dev`, `build`, `typecheck`, `lint`
+
+**Step 4: Define Core Branded Types & Error Hierarchy**
+- Create `apps/backend/src/types/branded.ts` (UserID, RoleID, TraceID, etc.)
+- Create `apps/backend/src/types/domain.ts` (User, Role, Permission)
+- Create `apps/backend/src/types/errors.ts` (DomainError base + specific errors)
+- Update `contract.version.json` (initial version 1.0.0, empty hash)
+
+**Step 5: Database Layer (Kysely)**
+- Create `apps/backend/src/db/connection.ts`
+- Create migration folder + first migration (users table with id, email, role, created_at)
+- Create `UserRepository` with findById, findAll, updateRole (with audit fields)
+
+**Step 6: Normal CRUD Endpoints (Standard Business Logic)**
+- `POST /users` — create user (standard)
+- `GET /users` — list with pagination + search
+- `GET /users/:id` — detail
+- `PATCH /users/:id` — profile update (non-admin fields)
+- All routes protected by JWT + standard auth plugin
+- Every mutation logs to `apps/backend/logs/` with TraceID
+
+**Step 7: High-Risk Admin Operation — Role Upgrade**
+- `PATCH /admin/users/:id/role` 
+- Payload must contain: `isHighRiskAdminAction: true`, `newRole: 'SuperAdmin'`
+- Backend **must refuse** unless valid `managerApproval` object is present in headers/body
+- `managerApproval` = { traceId, approvedBy: '@manager', timestamp, signature (simple hash for v1), reason }
+- Create `plugins/managerApproval.ts` validator
+- On success: update role + write full before/after audit record to `logs/admin-actions.jsonl`
+
+**Step 8: Contract Versioning & Verification**
+- After any type change, run contract hash update
+- Store `contract.version.json` with hash of all exported types
+- Add endpoint `GET /contract` that returns current version + hash
+
+---
+
+### Frontend Foundation (Steps 9-13)
+
+**Step 9: Create Frontend Monorepo Skeleton**
+- `mkdir -p apps/web/src/{components/ui, pages, hooks, types, lib}`
+- `cd apps/web && npm create vite@latest . -- --template react-ts`
+- Install: @vitejs/plugin-react, panda-css, zustand (if needed), lucide-react (icons only)
+- Configure Panda CSS (use root `panda.config.ts` or local copy)
+- Set up `styled-system/` generation
+
+**Step 10: UI Component System (Zero Library + Composition)**
+- Create inside `apps/web/src/components/ui/`:
+  - `Button.tsx` (compound: Button + Button.Icon + Button.Loading)
+  - `Modal.tsx` (with slot for header/body/footer)
+  - `Table.tsx` (with Row, Cell composition)
+  - `FormField.tsx`
+- All components use Panda CSS + strict accessibility props
+- Enforce 44x44px touch targets, focus rings, ARIA
+
+**Step 11: Type Contract Sync (Frontend Side)**
+- Copy or generate branded types from backend into `apps/web/src/types/`
+- Create script that fails build if `contract.version.json` hash mismatches
+- Use same branded types on client (UserID etc.)
+
+**Step 12: Normal User Pages**
+- `/users` — list (Table component + pagination)
+- `/users/:id` — detail + edit form (profile only)
+- Use hooks: `useListPage`, `useDetailPage` (blueprint pattern)
+- All data fetching goes through typed API client
+
+**Step 13: High-Risk Role Change UI**
+- On user detail page, show "Upgrade to SuperAdmin" button (only for authorized)
+- Button opens `SecurityApprovalModal`
+- Modal shows:
+  - Risk warning
+  - Reason input
+  - "Request Manager Approval" button → triggers Hermes message to @manager
+- After approval token received → submits the high-risk PATCH with `managerApproval` payload
+- On success: shows audit trail + success banner
+
+---
+
+### Integration & Governance Proof (Steps 14-18)
+
+**Step 14: Hermes Integration**
+- Implement `send_agent_message` usage from frontend (via backend proxy or direct if MCP available)
+- Scenario: Frontend requests briefing for role change → @manager responds with signed approval
+- Log all Hermes messages under `.enderun/messages/`
+
+**Step 15: Full Audit & Logging System**
+- Backend writes structured JSONL logs for every mutation
+- High-risk actions additionally write to dedicated `admin-audit.log`
+- Trace ID propagated from @manager briefing all the way to DB and UI
+
+**Step 16: Contract Integrity Gate**
+- Add Vitest test that compares backend `contract.version.json` hash vs frontend copied types
+- Fail CI if drift detected
+
+**Step 17: Professionalization Checkpoints (Frontend)**
+- All components pass manual WCAG 2.2 AA checklist (documented)
+- Performance budgets verified (LCP < 2.5s, bundle < 250KB)
+- Minimum 70% component test coverage
+
+**Step 18: Final Governance Validation**
+- @manager performs full walkthrough:
+  1. Normal CRUD works without special approval
+  2. High-risk role upgrade is **blocked** until managerApproval present
+  3. Hermes message was sent and processed
+  4. Full audit trail exists in logs
+  5. Contract version is consistent
+- Update `PROJECT_MEMORY.md` — mark Phase 1 COMPLETE
+- Record maturity increase for @backend and @frontend
+- Update Risk Dashboard: "No Production-Grade Reference Application" → CLOSED
+
+---
+
+## Success Criteria (Definition of Done for Phase 1)
+
+- A developer can run `npm run dev --workspace=backend` and `npm run dev --workspace=web`
+- Can create user via UI, then attempt role upgrade
+- Role upgrade fails without @manager approval
+- After simulated approval, role changes and audit log is written
+- Hermes message appears in `.enderun/messages/`
+- `contract.version.json` is maintained and verified
+- Zero lint errors, all TypeScript strict
+- All high-risk rules from `manager.md` followed
+
+---
+
+## Risk Mitigation During Execution
+
+- If any step takes > 2 sessions → split further and update memory
+- If frontend composition patterns feel weak → pause and reinforce @frontend agent first
+- Every major decision must be recorded in CRITICAL DECISIONS section of PROJECT_MEMORY.md
+
+**Next Action After This Plan:** Execute Step 1 immediately.
+
+---
+*This document is the single source of truth for Phase 1 execution. Every step must be checked off in PROJECT_MEMORY.md before moving to the next.*

package/.enderun/docs/structure-audit-2026-05-24.md

@@ -0,0 +1,72 @@
+# Structure & Naming Audit Report
+
+**Project:** Agent Enderun  
+**Date:** 24 May 2026  
+**Auditor:** @manager (AI-assisted)  
+**Scope:** File/folder naming + overall structural quality (excluding apps/, only governance and MCP layer)
+
+---
+
+## 1. Executive Summary
+
+**Overall Score:** 7.2 / 10
+
+The project is moving toward an **enterprise-scale manageable structure**, especially with the improvements made in May 2026. However, there are still significant gaps in **naming consistency**, **discoverability**, and **folder discipline**.
+
+**Strongest Areas:**
+- Clear separation between `.enderun/` and `framework-mcp/` layers
+- Knowledge files mostly follow consistent `kebab-case`
+- Newly created `live-tests/` structure is clean and scalable
+
+**Most Critical Weaknesses:**
+- Core "brain" files (`PROJECT_MEMORY.md`, `BRAIN_DASHBOARD.md`) use mixed UPPERCASE + snake_case
+- Many important folders lack README / INDEX files
+- `.enderun/messages/` contains a mix of old and new test messages
+- Content clutter in the `blueprints/` folder
+
+---
+
+## 2. Naming Consistency
+
+### Good Practices
+- Agent files: `manager.md`, `backend.md`, `git.md` → **consistent lowercase**
+- Knowledge files: `hermes_protocol.md`, `enterprise_project_adaptation.md` → **nearly perfect kebab-case**
+- MCP tool files: `contract.ts`, `memory.ts`, `hermes_live_test_guidelines.md` → good
+
+### Issues Found
+
+| File / Folder                          | Problem                                      | Recommendation                          | Priority |
+|----------------------------------------|----------------------------------------------|-----------------------------------------|----------|
+| `PROJECT_MEMORY.md`                    | UPPERCASE + underscore                       | `project-memory.md`                     | High     |
+| `BRAIN_DASHBOARD.md`                   | UPPERCASE + underscore                       | `brain-dashboard.md`                    | High     |
+| `2026-05-23-manager-to-backend-....json` | Dated flat message files                   | `messages/archive/2026-05-23/...`       | High     |
+| `blueprints/backend/errors/domain-error.ts` + `blueprint.json` | Both TS and JSON in same folder | `blueprints/backend/errors/` + `config/` | Medium   |
+
+**Conclusion:** Naming is ~80% consistent. The biggest problem is special treatment given to "core brain files".
+
+---
+
+## 3. Folder Structure Evaluation
+
+### Strong Points
+- `.enderun/` → Governance layer (agents, knowledge, memory, rules)
+- `framework-mcp/src/tools/` → MCP tools are modular and domain-separated (excellent)
+- `.enderun/messages/live-tests/` → New structure is very clean and scalable
+
+### Weaknesses and Risks
+1. **Missing README / Discoverability**
+2. Mixed old and new test messages in `.enderun/messages/`
+3. Content disorder in `blueprints/`
+
+---
+
+## 4. Recommendations (Priority Order)
+
+1. Rename core brain files to lowercase kebab-case.
+2. Add README.md to every important folder.
+3. Archive old test messages under `messages/archive/`.
+4. Enforce strict blueprint discipline (no empty folders).
+
+**Overall:** The governance layer is structurally sound but needs naming and documentation hygiene improvements to reach true enterprise maturity.
+
+**Last Updated:** 24 May 2026

package/.enderun/knowledge/README.md

@@ -0,0 +1,22 @@
+# Knowledge Base
+
+This directory is the **permanent enterprise knowledge** repository for Agent Enderun agents.
+
+## Content Rules
+- File names **must** be in kebab-case (`hermes-protocol.md`, `enterprise-project-adaptation.md`).
+- Every file must contain a clear title and "Version / Owner / Last Updated" metadata.
+- Knowledge should be as **practical and actionable** as possible (not just theory).
+
+## Important Files
+- `enterprise_project_adaptation.md` → Enterprise project entry protocol (EPDP)
+- `enterprise_frontend_adaptation.md` → Enterprise adaptation rules for frontend
+- `hermes_protocol.md` → Inter-agent communication standard
+- `manager_authority_audit_enforcement.md` → @manager authority audit rules
+- `hermes_live_test_guidelines.md` → Hermes test program
+
+## Usage
+Agents must search this directory first when conducting research or making decisions (using the `search_knowledge_base` tool).
+
+Newly discovered important patterns or rules must be written here.
+
+**Last Updated:** 24 May 2026

package/.enderun/knowledge/database_governance_guidelines.md

@@ -0,0 +1,118 @@
+# Enterprise Database Governance and Performance Guidelines (DBA SOP)
+
+**Version:** v0.6.5 | **Ownership:** @backend & @dba Security Framework
+
+This document is the constitutional database ruleset establishing **Zero-Downtime DDL (schema migrations)**, **maximum query performance (Index Tuning)**, and **deadlock prevention strategies (Lock Management)** in applications running under the PostgreSQL + Kysely architecture. `@backend` executes these rules with 0 error tolerance when writing code, and `@analyst` actively audits them during code review.
+
+---
+
+## ⚡ 1. INDEX OPTIMIZATION LAWS (INDEX TUNING)
+
+To ensure that queries do not exhaust the database and can respond to thousands of requests per second, index design cannot be left to chance.
+
+### 1.1 Foreign Key Index Obligation
+*   **Rule:** For every Foreign Key (FK) column defined, **it is mandatory to create a corresponding index**.
+*   **Rationale:** Prevents sequential scans on the target table during `JOIN` operations and when deleting data from the parent table (`ON DELETE CASCADE`).
+*   **Kysely/SQL Pattern:**
+    ```typescript
+    // Inside the migration file
+    await db.schema.createIndex('idx_orders_user_id')
+      .on('orders')
+      .column('user_id')
+      .execute();
+    ```
+
+### 1.2 Concurrent Indexing
+*   **Rule:** All indexes created on production databases **must be created using the `CONCURRENTLY` keyword**.
+*   **Rationale:** Standard index creation locks the target table completely for write operations (`ShareLock`). `CONCURRENTLY` builds the index in the background without locking the table.
+*   **Migration Rule:** When creating indexes concurrently, the migration process must run outside of a database transaction. In Kysely, this operation must be run `transaction-free`.
+
+### 1.3 Partial & Composite Indexes
+*   **Rule:** **Partial Indexes** must be used on tables using soft deletes (`deleted_at IS NOT NULL`) or when queries filter by a specific status.
+*   **Kysely Pattern:**
+    ```typescript
+    // An extremely fast and small index that scans only active records
+    await db.schema.createIndex('idx_active_users_email')
+      .on('users')
+      .column('email')
+      .where(sql`deleted_at IS NULL`)
+      .execute();
+    ```
+*   **Rule 2:** When creating composite indexes for multi-column searches like `WHERE a = x AND b = y`, the **column with the highest selectivity (high cardinality) must be placed on the far left**.
+
+---
+
+## 🔒 2. DATABASE LOCK MANAGEMENT (LOCK MANAGEMENT)
+
+Incorrect lock management leads to connection pool exhaustion within seconds, causing a complete system crash (cascading failure).
+
+### 2.1 Transaction Boundaries and Golden Rules
+1.  **Zero Network Inside TX:** While a database transaction (`db.transaction()`) is active, **external API calls, sending emails, or file read/write operations are strictly forbidden**. A 1-second network latency causes locks in the database to be held for that second, clogging the entire system.
+2.  **Keep it Short Principle:** Transactions must only contain database write operations and must be `committed` as quickly as possible.
+
+### 2.2 Deadlock Prevention and Smart Query Design
+*   **Rule:** The use of `SELECT ... FOR UPDATE` (Row Lock) is forbidden except in high-urgency scenarios. When its use is mandatory, the query must be restricted with **`NOWAIT`** or **`SKIP LOCKED`** parameters to avoid entering the queue and causing deadlocks.
+*   **Kysely Pattern:**
+    ```typescript
+    // Instead of waiting in a queue and locking the system, throw an error or skip if locked
+    const job = await db.selectFrom('jobs')
+      .selectAll()
+      .where('status', '=', 'PENDING')
+      .limit(1)
+      .forUpdate()
+      .skipLocked() // OR .noWait()
+      .executeTakeFirst();
+    ```
+
+### 2.3 Timeout Safety
+Lock timeout parameters must be set before every session or heavy migration. This ensures that if a lock accumulation occurs in the background, the transaction cancels itself instead of locking up the system.
+```sql
+SET statement_timeout = '15s';
+SET lock_timeout = '5s';
+```
+
+---
+
+## 🛡️ 3. SAFE SCHEMA TRANSITION LAWS (SAFE MIGRATIONS - DDL)
+
+To ensure zero-downtime during schema migrations on production environments, the following templates must be applied:
+
+### 3.1 NOT NULL Column Addition Procedure
+Adding a column containing a `NOT NULL` constraint directly to a production table causes PostgreSQL to lock the entire table. The safe procedure is:
+1.  Add the column as **nullable**.
+2.  Update the data in the background with default values (in batches).
+3.  Add the `NOT NULL` constraint to the column (this operation no longer creates a lock).
+
+### 3.2 Breaking Column/Table Changes - "Expand & Contract"
+Renaming a column or changing its data type directly on a live system is strictly forbidden. Instead, follow these 5 steps:
+```
+[Deployment 1 - EXPAND]
+Add the new column. Start dual-writing in the codebase (write to both old and new columns).
+
+[Deployment 2 - BACKFILL]
+Migrate legacy data from the old column to the new column in the background (Batch Update).
+
+[Deployment 3 - READ SWITCH]
+Redirect all read requests in the codebase to the new column.
+
+[Deployment 4 - STOP DUAL-WRITE]
+Completely stop writing to the old column.
+
+[Deployment 5 - CONTRACT]
+Delete the old column from the database (Drop Column).
+```
+
+### 3.3 Adding Constraints Safely
+To prevent table locks when adding `CHECK` or `FOREIGN KEY` constraints to large tables:
+1.  Add the constraint as `NOT VALID` (bypasses scanning legacy data, returns immediately).
+2.  Then, validate the constraint in the background by running the `VALIDATE CONSTRAINT` command concurrently.
+
+---
+
+## 🕵️ 4. AUTOMATED QA GATE CHECKLIST
+
+`@analyst` scans the database schema and queries automatically during code review against these rules:
+*   [ ] For every new `table.foreign()` definition, is a corresponding `createIndex()` defined?
+*   [ ] Is `.forUpdate()` used in any `selectFrom` query without `.skipLocked()` or `.noWait()` written next to it?
+*   [ ] Is there any `alterTable().renameColumn()` or direct destructive `dropColumn()` in migration files? (Expand/Contract audit).
+*   [ ] Is `CONCURRENTLY` used in index additions on large tables?

package/.enderun/knowledge/deployment_checklist.md

@@ -1,7 +1,133 @@
-# Deployment Checklist
+# Enterprise Deployment Standard Operating Procedure (DevOps SOP)
 
-- [ ] Environment variables set (`.env.production`).
-- [ ] Database migrations executed.
-- [ ] Build artifacts verified.
-- [ ] SSL certificates active.
-- [ ] Monitoring hooks connected.
+**Version:** v0.6.6 | **Ownership:** Human Devs & @manager Oversight
+
+This document is the **Standard Operating Procedure (SOP)** designed to ensure that deliverables produced by AI agents are deployed to production securely, with zero-downtime, and zero-errors by human engineers. Agents generate deliverables based on this guide, and humans execute these steps manually and sequentially.
+
+---
+
+## 📋 DEPLOYMENT MATRIX AND APPROVAL CHAIN
+
+| Deployment Phase | Owner | Auditor | Criticality Level | Mandatory Approval |
+| :--- | :--- | :--- | :--- | :--- |
+| **Staging (Test)** | Human Developer | `@analyst` | Low | `@analyst` (AST & Contract MATCH) |
+| **Production (Live)** | Human Engineer (DevOps) | `@manager` | Critical | `@manager` (Trace Approval) + Human CTO |
+
+---
+
+## 🔍 PHASE 1: PRE-DEPLOYMENT VALIDATION
+
+Before deciding to deploy to production, verify the following steps in your local environment or CI/CD interface.
+
+### 1.1 Contract and Type Integrity Testing
+Trigger the MCP tools to verify that there is no drift in the backend and frontend types generated by the agents:
+*   [ ] **Contract Integrity Scan:** Run the `verify_api_contract` tool and verify that the output is `MATCH`.
+*   [ ] **Frontend Compatibility Scan:** Run the `validate_frontend_api_contract` tool to ensure frontend hooks align perfectly with backend API contracts.
+
+### 1.2 Quality and Test Gate Control
+Run the following commands to audit test coverage:
+```bash
+# Run backend tests and verify coverage
+npm run test --workspace=backend -- --coverage
+# Run frontend tests and verify coverage
+npm run test --workspace=web -- --coverage
+```
+*   [ ] **Unit & Integration Coverage:** Verify that coverage for critical paths (Auth, Payments, RBAC) is **%85+** and overall codebase coverage is **%75+**.
+*   [ ] **Linter & Biome/ESLint:** Confirm there are zero build or styling errors: `npm run lint`.
+
+### 1.3 Static Security Scanning (SecOps)
+Run static security rules locally or in the remote repository:
+*   [ ] **Secret Scan:** Confirm that there are no hardcoded API keys, private keys, or passwords outside of `.env.production`.
+*   [ ] **AST Security Check:** Run the `security_audit_scan` or `analyze_constitution_compliance` tool to report any occurrences of the `any` type or unsafe `innerHTML` usage.
+
+---
+
+## 🗄️ PHASE 2: DATABASE MIGRATION MANAGEMENT
+
+Schema changes (DDL/DML) on production databases are the highest-risk infrastructure operations. Apply the **Expand and Contract** strategy to prevent downtime.
+
+### 2.1 Backward Compatibility and Schema Transition Steps
+*   [ ] **Breaking Change Check:** Never perform destructive operations like dropping columns or changing data types in a single deployment. First, add the new column (Expand), mark the old column as deprecated, migrate the data, and drop the old column in a subsequent deployment (Contract).
+*   [ ] **Dry Run:** Test migration files on a local test database or an isolated staging DB:
+    ```bash
+    npm run db:migrate -- --dry-run
+    ```
+*   [ ] **Backup (Cold/Hot Backup):** Take an instantaneous snapshot of the live database right before running the migration.
+
+---
+
+## 📦 PHASE 3: BUILD & BUNDLE BUDGET
+
+Build and audit the production package to verify that the application does not exceed performance budgets.
+
+### 3.1 Frontend Package Analysis
+```bash
+npm run build --workspace=web
+```
+*   [ ] **Bundle Budget Audit:** Verify that the initial load bundle size (Gzipped) is **< 250KB** and no single chunk size exceeds **50KB**.
+*   [ ] **CLS & A11y Protection:** Check that image and dynamic component dimensions are reserved with CSS to prevent Cumulative Layout Shift (CLS) during page load.
+
+---
+
+## 🚀 PHASE 4: DEPLOYMENT EXECUTION
+
+Zero-Downtime deployment steps to be followed during the manual deployment by human engineers.
+
+```mermaid
+sequenceDiagram
+  autonumber
+  actor Human as Human DevOps (Yusuf)
+  participant DB as PostgreSQL (Production)
+  participant Old as Live Server (V1)
+  participant New as New Server (V2)
+  participant LB as Load Balancer / Nginx
+
+  Human->>DB: 1. db:migrate (Backward Compatible)
+  Human->>New: 2. Boot V2 Code (Invisible)
+  Note over New: Waiting for Health Check (/health)
+  New->>New: 3. Warm-Up & Connection Tests
+  Human->>LB: 4. Switch Traffic to V2 (Rolling Update)
+  LB->>Old: 5. Disconnect V1 Connections (Graceful Shutdown)
+  Human->>Old: 6. Terminate / Archive Old Server
+```
+
+### 4.1 Step-by-Step Live Deployment Guide
+1.  **Environment Variables:** Confirm that the `.env.production` file is up-to-date and encrypted (stored in Secret Manager) on the target server.
+2.  **Database Migration:** Execute migrations before servers receive traffic:
+    ```bash
+    npm run db:migrate
+    ```
+3.  **Trigger Rolling Update:** Boot the new version (V2) but do not route traffic to it yet.
+4.  **Warm-Up & Health Check:** Route requests to the `/health` endpoint of the new servers to confirm a successful `200 OK` response and verify database pool health.
+5.  **Traffic Routing (Nginx/LB Switch):** Gradually route traffic to V2 servers via the Load Balancer.
+6.  **Graceful Shutdown:** Wait **30 seconds** for old servers (V1) to complete active requests (Graceful Shutdown), then shut down V1 servers.
+
+---
+
+## 📊 PHASE 5: POST-DEPLOYMENT MONITORING
+
+Keep monitoring dashboards open for the first **15 minutes** after going live.
+
+*   [ ] **Log Stream (Pino JSON):** Confirm there is no accumulation of `fatal` or `error` level logs on the server logs.
+*   [ ] **SSL & DNS Health:** Verify the validity period of the `https://` protocol and the SSL certificate (confirming at least 30 days remaining) via the browser.
+*   [ ] **Error Rate:** Observe that the `5xx` error rate remains below **%0.1** of total incoming requests.
+
+---
+
+## 🚨 PHASE 6: EMERGENCY ROLLBACK PROCEDURE
+
+If a critical error (Memory leak, >1% 5xx errors, DB deadlock) is detected post-deployment, apply the following **60-Second Emergency Rollback** steps without panic.
+
+### 6.1 Emergency Rollback Steps (Max 60 Seconds)
+1.  **Switch Traffic:** Instantly redirect traffic back to the previous stable release (V1 servers) via the Load Balancer / Nginx.
+2.  **Migration Rollback:** If there is a critical, backward-incompatible database error, rollback the migration:
+    ```bash
+    npm run db:rollback
+    ```
+    *(Note: Since schemas are designed to be backward-compatible, in most cases rolling back the code version is sufficient without needing a DB rollback.)*
+3.  **Audit and Trace Logging:** Boot the faulty version on an isolated debug port and inspect logs. Prepare a post-mortem report linked with the `Trace ID` to report the issue to `@manager`.
+
+---
+
+### Procedure Verification Declaration
+> ⚠️ **Engineering Note:** Any downtime caused by skipping steps in this guide will be considered an internal process violation. A history entry (HISTORY) must be added to `PROJECT_MEMORY.md` after every successful deployment, including the `@manager` approval.