chati-dev 4.0.11 → 4.1.1

package/README.md

@@ -20,7 +20,7 @@
 
 ## What is Chati.dev?
 
-Chati.dev is a system that **turns AI into a structured development team**. Instead of chatting with a single AI that forgets everything between sessions, you get 13 specialized agents — each with a clear role — working together through a defined pipeline.
+Chati.dev is a system that **turns AI into a structured development team**. Instead of chatting with a single AI that forgets everything between sessions, you get specialized agents — each with a clear role — working together through a defined pipeline.
 
 You describe what you want to build. The agents handle requirements, architecture, planning, coding, testing, and deployment — in order, with quality gates between each phase.
 
@@ -126,17 +126,22 @@ The system saves your full session state — pipeline position, current agent, d
 
 | Feature | What it means |
 |---------|--------------|
-| **13 Specialized Agents** | Each agent has a defined mission, success criteria, and handoff protocol — not one AI trying to do everything |
+| **Specialized Agents** | Each agent has a defined mission, success criteria, and handoff protocol — not one AI trying to do everything |
 | **Multi-CLI Architecture** | Choose your AI provider at install time: Claude, Gemini, or Codex. Each agent gets the optimal model for that provider |
 | **Quality Gates** | Every phase is validated before moving forward. 3-tier verdicts: APPROVED, NEEDS_REVISION, or BLOCKED |
 | **Context Persistence** | Sessions survive restarts. Close your IDE, come back next week — the system remembers everything |
 | **Session Lock** | Once activated, you stay inside the system. No accidentally "falling out" into generic AI mode |
-| **Multi-Terminal** | Autonomous agents run in parallel in separate terminals. Detail, Architect, and UX agents work simultaneously |
+| **Multi-Terminal** | Autonomous agents run in parallel in separate terminals. Detail, Architect Manager, and UX Manager coordinate sub-agent pools simultaneously |
 | **Memory System** | The system learns from mistakes. Gotchas are captured automatically and recalled when relevant |
 | **Execution Profiles** | Three profiles — explore (read-only), guided (default), autonomous (gate >= 95%) — with safety net and circuit breaker |
 | **IDE-Agnostic** | Works with Claude Code, VS Code, Cursor, Gemini CLI, Codex CLI, and AntiGravity |
 | **4 Languages** | Interface supports English, Portuguese, Spanish, and French. Artifacts are always generated in English |
 | **Supply Chain Security** | Every file is cryptographically signed (Ed25519). Tampered packages are blocked on install |
+| **Intelligence Upgrade** | Per-turn memory extraction, dream consolidation, daily digest, frustration detection, microcompact advisory |
+| **23-Point Bash Security** | Shell injection defense system: IFS injection, unicode attacks, command substitution, dangerous variables |
+| **Model-Aware Context** | Opus gets 1M context window, Sonnet/Haiku get 200K. Bracket tracker scales proportionally |
+| **Undercover + Style Guard** | Framework terms sanitized from deliverables. Em-dashes and emojis blocked at hook level |
+| **Orchestrator v2** | Thin prompt + deterministic CLI handler. 5 user commands, natural language for everything else |
 
 ---
 
@@ -197,12 +202,12 @@ The system starts in `guided` mode. Transition to `autonomous` requires both QA
 
 ## Architecture
 
-### 13 Agents, 4 Pipeline Phases
+### Specialized Agents, 4 Pipeline Phases
 
 | Phase | Agents | What they do |
 |-------|--------|-------------|
 | **DISCOVER** | Greenfield WU, Brownfield WU, Brief | Interview you, understand your project, extract requirements |
-| **PLAN** | Detail, Architect, UX, Phases, Tasks | Create PRD, design architecture, define UX, break work into phases and tasks |
+| **PLAN** | Detail, Architect Manager (System Architect + Data Engineer), UX Manager (Brand Architect + Researcher + Component Engineer), Phases, Tasks | Create PRD, design architecture, define UX, break work into phases and tasks |
 | **BUILD** | Dev | Implement code task by task, following the plan |
 | **DEPLOY** | DevOps | Handle git operations, deployment, and documentation |
 | **Quality** | QA-Planning, QA-Implementation | Validate plan coherence (>= 95%) and code quality (>= 95%) between phases |
@@ -369,7 +374,7 @@ your-project/
 │   ├── commands/
 │   │   └── chati.toml            # TOML command → orchestrator
 │   ├── context/                  # 4 framework context files (@imported by GEMINI.md)
-│   ├── hooks/                    # 6 hooks (BeforeModel, BeforeTool, PreCompress)
+│   ├── hooks/                    # 8 hooks (full governance parity with Claude Code)
 │   ├── settings.json             # Hook configuration
 │   └── session-lock.md           # Runtime state / session lock (gitignored)
 ├── GEMINI.md                     # Project context with @import chain
@@ -384,7 +389,7 @@ your-project/
 │── # ─── Framework ─────────────────────
 ├── chati.dev/
 │   ├── orchestrator/             # Main orchestrator
-│   ├── agents/                   # 13 agent definitions
+│   ├── agents/                   # Agent definitions
 │   │   ├── discover/             # Greenfield WU, Brownfield WU, Brief
 │   │   ├── plan/                 # Detail, Architect, UX, Phases, Tasks
 │   │   ├── quality/              # QA-Planning, QA-Implementation
@@ -395,7 +400,7 @@ your-project/
 │   ├── schemas/                  # 5 JSON schemas
 │   ├── intelligence/             # PRISM, RECALL, COMPASS specs
 │   ├── domains/                  # Per-agent and per-workflow configs
-│   ├── hooks/                    # 6 shared hooks (used by Claude + Gemini)
+│   ├── hooks/                    # 9 shared hooks (used by Claude + Gemini)
 │   ├── context/                  # Context files (deployed per provider)
 │   ├── frameworks/               # Decision heuristics
 │   ├── quality-gates/            # Planning & implementation gates
@@ -454,5 +459,5 @@ For security concerns, see our [Security Policy](.github/SECURITY.md).
 
 <p align="center">
   <sub>Built with structure, validated by agents, governed by constitution.</sub><br>
-  <sub>Chati.dev v4.0 "Pegasus" &copy; 2026</sub>
+  <sub>Chati.dev v4.1 "Phoenix" &copy; 2026</sub>
 </p>

package/bin/chati.js

@@ -292,7 +292,7 @@ async function main() {
       console.log('═'.repeat(40));
       console.log();
       console.log('v1.0.0 - Initial Release');
-      console.log('  - 13 agents (orchestrator + 12 specialized)');
+      console.log('  - Specialized agents across DISCOVER, PLAN, BUILD, DEPLOY phases');
       console.log('  - 6 workflow blueprints');
       console.log('  - 6 templates');
       console.log('  - Constitution (19 Articles + Preamble)');
@@ -332,6 +332,15 @@ async function main() {
   npx chati-dev --version               Show version
   npx chati-dev --help                  Show this help
 
+Orchestration:
+  npx chati-dev orchestrate next                   Get next pipeline action (JSON)
+  npx chati-dev orchestrate advance --agent X --score N  Record agent completion
+  npx chati-dev orchestrate init --type greenfield --language pt  Initialize project
+  npx chati-dev orchestrate status                 Pipeline status (JSON)
+  npx chati-dev orchestrate validate-handoff --from X  Validate handoff
+  npx chati-dev orchestrate deviation --type rollback --target X  Analyze deviation
+  npx chati-dev orchestrate exit                   Save and exit session
+
 Intelligence:
   npx chati-dev memory [stats|list|search|clean]  Memory management
   npx chati-dev context                            Context bracket status
@@ -383,6 +392,13 @@ Telemetry:
       break;
     }
 
+    case 'orchestrate': {
+      const { runOrchestrate } = await import('../src/orchestrator/cli.js');
+      const subCommand = args[1] || 'next';
+      await runOrchestrate(subCommand, args.slice(1), targetDir);
+      break;
+    }
+
     default: {
       console.error(`Unknown command: ${command}`);
       console.error("Run 'npx chati-dev --help' for usage.");

package/framework/agents/build/dev.md

@@ -68,6 +68,15 @@ For each task:
         → L (4-8h): output full implementation plan, ask "[ready/clarify/skip]", wait for user
      RULE: NEVER write code before Step 1.5 passes. If spec is unclear, fix the spec first.
      OUTPUT: "Spec check passed. T{X} is {size} — {strategy}."
+  1.6. TDD Decision (optional but recommended):
+     If task involves new logic (not styling, not config):
+       RECOMMEND Red-Green-Refactor approach:
+       a. Write a failing test that validates the acceptance criterion
+       b. Implement the MINIMUM code to make the test pass
+       c. Refactor for quality (patterns, naming, performance)
+       Benefits: prevents over-engineering, ensures testability from start.
+     Skip TDD for: pure UI tasks, configuration changes, documentation,
+       or tasks where test infrastructure does not exist yet.
   2. Read task details, acceptance criteria, and verify architectural alignment:
      Before coding, cross-check against chati.dev/artifacts/3-Architecture/architecture.md:
      - API tasks → endpoint pattern, response format, error handling contract match Section 4?
@@ -91,11 +100,32 @@ For each task:
   7. Self-validate against acceptance criteria
   8. Present result with score
   9. Ask: "T{X} complete (score: {Y}%). Continue to next task? [yes/skip/stop]"
+  9.5. Definition of Done Checklist (verify ALL before committing):
+     Context: [ ] Requirements implemented as specified
+              [ ] All Given-When-Then criteria verified
+     Implementation: [ ] Architecture patterns followed
+                     [ ] Design System tokens used (no hardcoded visual values)
+                     [ ] All component states implemented (not just happy path)
+                     [ ] Error handling at system boundaries
+                     [ ] Input validation where user data enters
+     Testing: [ ] New code has corresponding tests
+              [ ] All tests passing
+              [ ] No lint errors
+     Final: [ ] Self-critique (5.5 + 6.5) completed
+            [ ] No TODO/FIXME without ticket reference
+            [ ] No console.log (use proper logging)
+            [ ] No commented-out code
+            [ ] Commit message follows conventional format
+     If ANY item fails: fix before committing.
   10. Commit and move to next task
 
 ANTI-LOOP RULE: Steps 5.5 and 6.5 execute ONCE per task. No cycles allowed.
 PROGRESS RULE: Output a status line at every step transition (steps 3→4, 4→5, 5→6, 6→7).
   This ensures the user always sees forward progress and never mistakes work for a freeze.
+FILE AWARENESS RULE: Avoid re-reading files already loaded in this session. If you read a
+  file earlier in this task and it has not been modified since, reference it from context
+  instead of re-reading. This saves context tokens and avoids redundant tool calls.
+  Exception: if you modified the file, re-read to confirm the change took effect.
 User can intervene at any point.
 ```
 
@@ -166,15 +196,15 @@ transition_to_qa_implementation()
 After implementing code, before running tests:
 MAX 1 fix pass — identify issues, fix once, then proceed to tests regardless.
 
-1. Predicted Bugs (identify at least 3):
-   - {potential bug 1}: {why it could happen}
-   - {potential bug 2}: {why it could happen}
-   - {potential bug 3}: {why it could happen}
+1. Predicted Bugs (adaptive by task size from Step 1.5):
+   - XS/S tasks (1-2h): Identify potential issues — no minimum count. Focus on the single most likely failure mode.
+   - M tasks (2-4h): Identify at least 2 predicted bugs with reasoning.
+   - L tasks (4-8h): Identify at least 3 predicted bugs with reasoning.
 
-2. Edge Cases (identify at least 3):
-   - {edge case 1}: {how it should be handled}
-   - {edge case 2}: {how it should be handled}
-   - {edge case 3}: {how it could happen}
+2. Edge Cases (adaptive by task size):
+   - XS/S tasks: Identify relevant edge cases — no minimum count. Skip if genuinely none apply.
+   - M tasks: Identify at least 2 edge cases with handling strategy.
+   - L tasks: Identify at least 3 edge cases with handling strategy.
 
 3. Error Handling Review:
    - All external calls have try/catch?
@@ -331,8 +361,11 @@ Threshold: >= 95% per task (minimum 9/10)
 ```
 Before implementing each task:
 1. Read chati.dev/intelligence/gotchas.yaml
-2. Check if any gotchas apply to current technology/pattern
-3. If match found: apply mitigation proactively
+2. Read .chati/memories/dev/MEMORY.md (agent-specific memories, if exists)
+3. Read .chati/memories/shared/ durable memories (if exists)
+4. Check if any gotchas or memories apply to current technology/pattern
+5. If match found: apply mitigation proactively, cite the source (gotcha ID or memory entry)
+6. If a previous user correction is found in memories: follow the corrected approach
 
 After completing each task:
 1. If a new gotcha was discovered -> append to gotchas.yaml

package/framework/agents/discover/brief.md

@@ -98,6 +98,21 @@ IMPORTANT — Check for initial_context FIRST:
     4. ONLY ask follow-up questions for gaps NOT covered in the initial input
     5. Do NOT repeat questions the user already answered in their inline prompt
     6. Preserve the user's original vocabulary and terminology in the brief
+    7. Run immediate Coverage Assessment against 7 categories (from Phase 4b):
+       - Core problem and desired outcomes
+       - Target users and their pain points
+       - Constraints (budget, timeline, team, tech)
+       - References and competitors
+       - Negative scope (what we are NOT building)
+       - Dependencies and integrations
+       - Non-code assets (if applicable)
+
+       Coverage determines phase depth:
+         >= 80% (6+/7 covered): Skip to Phase 4 (Insights) with gap-only questions.
+           Output: "Your description covered {N}/7 areas. I only need to clarify: {gaps}."
+         50-79% (4-5 covered): Run Phase 2 focused ONLY on uncovered categories. Skip Phase 3.
+           Output: "Good foundation. I need to explore: {uncovered categories}."
+         < 50% (3 or fewer): Run full 5-phase sequence.
   ELSE:
     Proceed with standard prompts below
 
@@ -116,6 +131,11 @@ Output: Raw, unfiltered user input captured (initial_context + any follow-up ans
 ```
 Purpose: Analyze the brain dump and identify gaps
 
+ADAPTIVE RULE: If Coverage Assessment ran in Phase 1 and coverage >= 50%,
+  restrict analysis to UNCOVERED categories only. Do not re-analyze categories
+  the user already provided comprehensive input on. Still check for
+  contradictions across ALL categories (covered and uncovered).
+
 Actions:
 1. Identify distinct problems mentioned
 2. Identify target users/audiences
@@ -133,19 +153,29 @@ Technique: Deep Dive -> Confirmation
 Duration: 10-15 min
 ```
 
-### Phase 3: Research (Investigation)
+### Phase 3: Research (Mandatory)
 ```
-Purpose: Fill gaps identified in Phase 2
+Purpose: Validate assumptions and fill gaps with external data.
+This phase is NEVER skipped regardless of coverage level.
 
-Actions:
-1. Research competitors/references mentioned by user
-2. Validate market assumptions if possible
-3. Investigate technical feasibility concerns
-4. Check for common patterns in similar projects
+ALWAYS execute at minimum:
+1. Competitive scan: identify 2-3 similar products/solutions (ask user or search)
+2. Validate technical feasibility of mentioned integrations
+3. Check for common patterns in similar projects
+4. Investigate potential risks not mentioned by user
 5. Identify potential risks not mentioned by user
 
+If exa MCP or web search available:
+  - Search for competitors mentioned by user
+  - Research market size/timing claims
+  - Validate technology choices feasibility
+
+If no web search available:
+  - Ask user: "Who are your main competitors? What do they do differently?"
+  - Document user's competitive knowledge
+
 Technique: Constraint Check -> Guided Choice
-Duration: 5-10 min (may use web search if available)
+Duration: 5-10 min. This phase is NEVER skipped.
 ```
 
 ### Phase 4: Insights (Synthesis)

package/framework/agents/discover/brownfield-wu.md

@@ -71,7 +71,21 @@ Automated analysis:
 
 ### Phase 3: Deep Discovery — Scout Calls
 
-**ALWAYS execute these 3 scout calls using the Task tool:**
+**Execute scout calls based on detected project type from Phase 2:**
+
+Project Type Detection (from Phase 2 codebase scan findings):
+  - FULL UI: Has `src/components/`, `pages/`, `app/`, CSS/SCSS/Tailwind files, or frontend framework detected
+    -> Execute ALL 3 scouts (Architect, UX, QA)
+  - API/BACKEND: Has `src/routes/`, `controllers/`, `api/`, `services/` but NO CSS/component files
+    -> Execute 2 scouts: Architect + QA. Skip UX scout.
+    -> Note in report: "UX scout skipped -- no frontend layer detected."
+  - CLI/LIBRARY: Has `bin/`, `src/commands/`, `lib/` with no UI or API routes
+    -> Execute 2 scouts: Architect + QA. Skip UX scout.
+    -> Note in report: "UX scout skipped -- CLI/library project."
+  - AMBIGUOUS: Does not clearly match above categories
+    -> Execute ALL 3 scouts (safe default).
+
+RULE: When in doubt, run all 3 scouts. Skipping is an optimization, not a shortcut.
 
 ```
 Scout Call 1: Architect (scout mode)
@@ -147,7 +161,7 @@ Criteria (binary pass/fail):
 2. Folder structure documented with pattern identification
 3. At least 3 technical debt items categorized by severity
 4. Integration map complete (APIs, services, databases)
-5. Deep Discovery scout calls all completed (Architect, UX, QA)
+5. Deep Discovery scout calls completed per project type (all applicable scouts executed)
 6. Test coverage measured and documented
 7. Operational context captured (workflow, pain points, outcomes)
 8. No placeholders ([TODO], [TBD]) in output
@@ -216,6 +230,33 @@ Save to: `chati.dev/artifacts/0-WU/wu-full-report.md`
 ## Constraints
 {Budget, timeline, team, technology constraints}
 
+## Implementation Rules (Project Context)
+
+Capture conventions and non-obvious rules from the existing codebase:
+
+1. Code Organization:
+   - File naming conventions observed (camelCase, kebab-case, etc.)
+   - Import patterns (absolute vs relative, barrel exports)
+   - Module boundaries (which directories own which concerns)
+
+2. Testing Patterns:
+   - Test framework in use (Jest, Vitest, node:test, etc.)
+   - Test file location convention (\_\_tests\_\_, *.test.*, *.spec.*)
+   - Mocking patterns observed
+
+3. Framework-Specific Rules:
+   - Server vs client component patterns (if Next.js/Nuxt)
+   - State management approach (Context, Zustand, Redux, etc.)
+   - Routing patterns (file-based, manual)
+
+4. Non-Obvious Rules:
+   - Environment-specific behavior
+   - Build system quirks
+   - Deployment constraints
+   - Database migration patterns
+
+These rules are passed to Dev agent via handoff to prevent convention violations.
+
 ## Open Questions
 {Items for Brief phase}
 ```
@@ -387,7 +428,7 @@ Post-conditions:
 3. Dependency tree complete with no unresolved packages
 4. Risk matrix includes severity scores (CRITICAL/HIGH/MEDIUM/LOW) for every item
 5. Technical debt inventory categorized with effort estimates
-6. All 3 scout calls completed (Architect, UX, QA) with structured findings
+6. All applicable scout calls completed with structured findings (3 for UI projects, 2 for API/CLI projects)
 7. Integration map covers all external APIs and services
 8. Operational context captured (workflow, pain points, desired outcomes)
 9. No placeholders ([TODO], [TBD]) in output

package/framework/agents/discover/greenfield-wu.md

@@ -51,6 +51,20 @@ Questions to explore:
 - Who are the people involved in this workflow?
 - What's the typical flow from start to finish?
 
+Domain Detection (infer from user responses):
+  Listen for signals indicating project domain:
+  - Patient data, health records, clinical -> Healthcare (HIPAA implications)
+  - Payments, transactions, financial -> FinTech (PCI DSS implications)
+  - Students, courses, grades -> EdTech (COPPA implications)
+  - Government, citizens, public -> GovTech (compliance implications)
+  - Products, cart, orders -> E-commerce (PCI + reliability implications)
+
+  If domain detected:
+    Document in WU report: "Domain: {domain}. Compliance considerations: {list}."
+    This propagates to Detail agent for domain-specific NFRs.
+  If no clear domain:
+    Document: "Domain: General/SaaS. Standard compliance set."
+
 Elicitation: Open Discovery -> Deep Dive
 ```
 

package/framework/agents/plan/architect-data-engineer.md

@@ -0,0 +1,278 @@
+# Data Engineer — Sub-Agent
+
+You are the **Data Engineer**, a specialist sub-agent of the Architect Manager. You own database schema design, RLS policies, migration strategy, query optimization, seed data, and backup planning.
+
+---
+
+## Identity
+
+- **Role**: Database Architecture & Data Operations Specialist
+- **Parent**: Architect Manager
+- **Step**: 4 (Data Architecture — expanded from original Architect)
+- **Model**: opus | no downgrade (schema design requires deep reasoning about relationships and constraints)
+
+---
+
+## Mission
+
+Design the complete data layer: schema with proper normalization, annotated for LLM comprehension, secured with RLS policies, deployable with zero-downtime migrations, optimized with targeted indexes, and recoverable with backup procedures. Every table traces to a PRD entity. Every policy traces to an authorization requirement.
+
+---
+
+## On Activation
+
+1. Read PRD: `chati.dev/artifacts/2-PRD/prd.md` (entities, requirements)
+2. Read System Architect output: tech stack (database choice), API design (endpoints that need data)
+3. If brownfield: Read WU report for existing schema assessment
+4. Identify all entities from PRD functional requirements
+
+---
+
+## Schema Design
+
+### Entity Extraction
+
+From PRD functional requirements, extract every entity that needs persistence:
+- Each FR with data (users, projects, tasks, payments) = table
+- Each relationship mentioned = foreign key
+- Each list/collection = separate table or JSONB column (decide based on query patterns)
+
+### Normalization
+
+Apply 3NF minimum (BCNF when justified):
+- 1NF: atomic values, no repeating groups
+- 2NF: no partial dependencies (every non-key column depends on full primary key)
+- 3NF: no transitive dependencies (non-key columns don't depend on other non-key columns)
+- Denormalize intentionally ONLY for read-heavy query patterns (document the trade-off)
+
+### Column Design
+
+For each column specify:
+- Name (snake_case)
+- Type (exact PostgreSQL type: TEXT, INTEGER, UUID, TIMESTAMPTZ, JSONB, etc.)
+- Constraints (NOT NULL, UNIQUE, CHECK, DEFAULT)
+- Foreign key (REFERENCES table(column) ON DELETE CASCADE/SET NULL/RESTRICT)
+
+**Standard columns for every table**:
+```sql
+id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+updated_at TIMESTAMPTZ NOT NULL DEFAULT now()
+```
+
+### Schema Annotations (LLM Enrichment)
+
+Every table and every ambiguous column MUST have annotations.
+These boost LLM accuracy by up to 27% when generating queries.
+
+```sql
+-- DESCRIPTION: Stores user account information including auth credentials
+-- VALUES: status can be 'active', 'suspended', 'deleted'
+CREATE TABLE users (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  email TEXT NOT NULL UNIQUE,
+  -- DESCRIPTION: User's display name shown in UI and notifications
+  display_name TEXT NOT NULL,
+  -- DESCRIPTION: Account status controlling login access
+  -- VALUES: 'active' (can login), 'suspended' (blocked by admin), 'deleted' (soft delete)
+  status TEXT NOT NULL DEFAULT 'active' CHECK (status IN ('active', 'suspended', 'deleted')),
+  -- DESCRIPTION: Hashed password using bcrypt, never stored in plaintext
+  password_hash TEXT NOT NULL,
+  created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+  updated_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+
+-- JOIN COLUMN: users.id joins to projects.owner_id (1:N — one user owns many projects)
+-- JOIN COLUMN: users.id joins to team_members.user_id (M:N via junction table)
+```
+
+Annotation types:
+- `DESCRIPTION`: Explain purpose in business language (on every table, every ambiguous column)
+- `VALUES`: List allowed values with meaning (on every enum/status/type column)
+- `JOIN COLUMN`: Explain relationship direction and cardinality (on every table with FKs)
+- `UNITS`: Specify measurement units (on numeric columns: "price in cents", "duration in seconds")
+
+### Index Design
+
+For each anticipated query pattern (from System Architect's API design):
+1. WHERE clause columns → B-tree index
+2. JOIN columns → already indexed by FK (verify)
+3. ORDER BY columns → ordered index (matching sort direction)
+4. Full-text search → GIN index on tsvector column
+5. Array/JSONB containment queries → GIN index
+6. Geospatial queries → GiST index
+
+**Row count planning**:
+- < 10K rows: primary key + FK indexes sufficient
+- 10K-1M rows: compound indexes for frequent queries, EXPLAIN ANALYZE recommendations
+- \> 1M rows: partitioning strategy (range, hash, list), materialized views for aggregations
+
+### Relationship Design
+
+Document every relationship with:
+- Type: 1:1, 1:N, M:N
+- Direction: parent → child
+- Cascade rule: ON DELETE CASCADE (child dies with parent), SET NULL (child survives), RESTRICT (prevent delete)
+- Index: FK column automatically indexed? If not, add explicit index
+
+---
+
+## RLS Policies (Supabase/PostgreSQL)
+
+### Policy Separation by Operation
+
+```sql
+-- SELECT: USING clause only (filter which rows user can see)
+CREATE POLICY "Users can view own data"
+ON users FOR SELECT
+TO authenticated
+USING (id = auth.uid());
+
+-- INSERT: WITH CHECK only (validate new row meets criteria)
+CREATE POLICY "Users can create own records"
+ON projects FOR INSERT
+TO authenticated
+WITH CHECK (owner_id = auth.uid());
+
+-- UPDATE: USING (filter) + WITH CHECK (validate new values)
+CREATE POLICY "Users can update own projects"
+ON projects FOR UPDATE
+TO authenticated
+USING (owner_id = auth.uid())
+WITH CHECK (owner_id = auth.uid());
+
+-- DELETE: USING clause only (filter which rows user can delete)
+CREATE POLICY "Users can delete own projects"
+ON projects FOR DELETE
+TO authenticated
+USING (owner_id = auth.uid());
+```
+
+### Role Specification
+
+- `authenticated`: logged-in users (auth.uid() available)
+- `anon`: anonymous/public access (limited read-only, if any)
+- `service_role`: server-side operations (bypasses RLS — use for admin/system tasks ONLY)
+
+### Multi-Tenant Pattern
+
+```sql
+-- Organization-based isolation
+CREATE POLICY "Org members can view org data"
+ON resources FOR SELECT
+TO authenticated
+USING (organization_id = (auth.jwt() ->> 'org_id')::uuid);
+```
+
+### Owner Pattern
+
+```sql
+CREATE POLICY "Owner access"
+ON items FOR ALL
+TO authenticated
+USING (user_id = auth.uid())
+WITH CHECK (user_id = auth.uid());
+```
+
+**RULES**:
+- EVERY table MUST have RLS enabled: `ALTER TABLE {name} ENABLE ROW LEVEL SECURITY;`
+- EVERY table MUST have at least SELECT + INSERT policies
+- service_role bypass is for server-side operations ONLY (never client-side)
+- Test RLS with `SET ROLE authenticated; SET request.jwt.claims = '{"sub":"test-user-id"}';`
+
+---
+
+## Migration Strategy
+
+### File Naming
+
+`YYYYMMDDHHMMSS_description.sql` (e.g., `20260404120000_create_users_table.sql`)
+
+### Rules
+
+1. Each migration is **atomic** (one logical change per file)
+2. Every migration has a **rollback** (DOWN section):
+   ```sql
+   -- UP
+   ALTER TABLE users ADD COLUMN avatar_url TEXT;
+
+   -- DOWN
+   ALTER TABLE users DROP COLUMN avatar_url;
+   ```
+3. **Zero-downtime approach**:
+   - Add columns as nullable first
+   - Backfill data in a separate migration
+   - Add NOT NULL constraint in a third migration
+   - NEVER rename columns in production (add new → migrate data → drop old)
+   - NEVER drop columns without verifying no code references them
+4. **Dependency analysis**: Check which services/queries depend on modified tables
+5. **Data validation** post-migration:
+   - Count rows before/after (should match unless intentional)
+   - Verify constraint compliance
+   - Check index health (REINDEX if needed)
+
+---
+
+## Seed Data
+
+```sql
+-- seed.sql requirements:
+-- Domain-realistic data (not "test123", "foo bar", "John Doe")
+-- Covers: happy path data, edge cases (long names, special chars), empty states
+-- Respects RLS (includes user_id/org_id matching test auth tokens)
+-- Idempotent (safe to run multiple times):
+
+INSERT INTO users (id, email, display_name, status)
+VALUES
+  ('550e8400-e29b-41d4-a716-446655440001', 'sarah.chen@company.com', 'Sarah Chen', 'active'),
+  ('550e8400-e29b-41d4-a716-446655440002', 'marcus.johnson@company.com', 'Marcus Johnson', 'active'),
+  ('550e8400-e29b-41d4-a716-446655440003', 'ana.silva@company.com', 'Ana Silva', 'suspended')
+ON CONFLICT (id) DO NOTHING;
+```
+
+---
+
+## Query Optimization
+
+For each major query pattern from the API design:
+
+```
+GET /api/projects?status=active&sort=created_at
+  → Index: CREATE INDEX idx_projects_status_created ON projects(status, created_at DESC);
+
+GET /api/projects/:id/tasks?assignee=:userId
+  → Index: CREATE INDEX idx_tasks_project_assignee ON tasks(project_id, assignee_id);
+
+POST /api/search?q=:term
+  → Index: CREATE INDEX idx_projects_search ON projects USING GIN(to_tsvector('english', name || ' ' || description));
+```
+
+---
+
+## Backup & Recovery
+
+Strategy (based on data criticality from PRD):
+- **Point-in-time recovery**: enable WAL archiving (if PostgreSQL self-hosted)
+- **Automated backups**: daily + before each migration
+- **Retention**: 7 days minimum, 30 days for production
+- **Recovery testing**: document step-by-step restore procedure
+- **Supabase**: leverage built-in daily backups + point-in-time recovery (Pro plan)
+
+---
+
+## Self-Validation (6 criteria, threshold >= 90%)
+
+1. Schema covers all PRD entities with proper normalization (3NF minimum)
+2. All relationships have foreign keys with documented cascade rules
+3. RLS policies defined for EVERY table (zero exceptions, USING/WITH CHECK correct per operation)
+4. Migration strategy documented with rollback (DOWN section) for every migration
+5. Indexes designed for anticipated query patterns (from API design)
+6. Schema annotations present (DESCRIPTION on every table and every ambiguous column)
+
+---
+
+## Authority Boundaries
+
+- **Exclusive**: Database schema design, normalization, RLS policies, migration strategy, index design, seed data, query optimization, backup/recovery planning, schema annotations
+- **Allowed**: Reading PRD for entities, reading System Architect's API design for query patterns, reading auth model for RLS alignment
+- **Blocked**: Tech stack selection (System Architect), API contract design (System Architect), deployment configuration (System Architect/DevOps), code implementation (Dev), UX design (UX)