@stella-studio/ck 1.0.0

package/.claude/skills/databases/stacks/sqlite.md

@@ -0,0 +1,244 @@
+# SQLite Rules
+
+Guidelines for designing schemas specific to SQLite.
+
+---
+
+## Data Types
+
+SQLite has **dynamic typing**, with only 5 storage classes:
+
+| Storage Class | Use case | Notes |
+|---------------|----------|-------|
+| `INTEGER` | PK, FK, counts, booleans | |
+| `REAL` | Floats, decimals | |
+| `TEXT` | Strings, dates, JSON, enums | |
+| `BLOB` | Binary data | |
+| `NULL` | Null values | |
+
+### Type affinity
+SQLite does not strictly enforce types. Type declaration is just a "hint":
+```sql
+-- All of these will be stored
+CREATE TABLE test (price REAL);
+INSERT INTO test VALUES (100);      -- Stored as INTEGER
+INSERT INTO test VALUES (99.99);    -- Stored as REAL
+INSERT INTO test VALUES ('free');   -- Stored as TEXT (!)
+```
+
+### Date/Time
+SQLite **does not have** DATE/TIME type. Store as TEXT with ISO format:
+```sql
+created_at TEXT DEFAULT (datetime('now'))
+-- Format: YYYY-MM-DD HH:MM:SS
+```
+
+---
+
+## Metadata Tables (REQUIRED)
+
+SQLite **does not support comments** on tables and columns. Need to create metadata tables:
+
+### Create metadata tables
+
+```sql
+CREATE TABLE IF NOT EXISTS metadata_tables (
+    table_name TEXT PRIMARY KEY,
+    description TEXT NOT NULL,
+    created_at TEXT DEFAULT (datetime('now')),
+    updated_at TEXT DEFAULT (datetime('now'))
+);
+
+CREATE TABLE IF NOT EXISTS metadata_columns (
+    table_name TEXT NOT NULL,
+    column_name TEXT NOT NULL,
+    description TEXT NOT NULL,
+    data_type TEXT,
+    is_nullable INTEGER DEFAULT 1,  -- 0=NOT NULL, 1=NULL
+    default_value TEXT,
+    created_at TEXT DEFAULT (datetime('now')),
+    PRIMARY KEY (table_name, column_name),
+    FOREIGN KEY (table_name) REFERENCES metadata_tables(table_name) ON DELETE CASCADE
+);
+
+CREATE INDEX idx_metadata_columns_table ON metadata_columns(table_name);
+```
+
+### Insert metadata after creating table
+
+```sql
+-- Table metadata
+INSERT INTO metadata_tables (table_name, description)
+VALUES ('orders', 'Table storing customer order information');
+
+-- Column metadata
+INSERT INTO metadata_columns (table_name, column_name, description, data_type, is_nullable)
+VALUES
+    ('orders', 'id', 'Primary key, auto increment', 'INTEGER', 0),
+    ('orders', 'order_number', 'Unique order code', 'TEXT', 0),
+    ('orders', 'user_id', 'FK to users.id', 'INTEGER', 0),
+    ('orders', 'status', 'pending|confirmed|shipped|cancelled', 'TEXT', 0),
+    ('orders', 'total_amount', 'Total value', 'REAL', 0);
+```
+
+### Query metadata
+
+```sql
+-- View schema with descriptions
+SELECT
+    t.table_name,
+    t.description AS table_description,
+    c.column_name,
+    c.description AS column_description,
+    c.data_type
+FROM metadata_tables t
+LEFT JOIN metadata_columns c ON t.table_name = c.table_name
+ORDER BY t.table_name, c.column_name;
+```
+
+---
+
+## Auto Increment
+
+```sql
+-- Option 1: INTEGER PRIMARY KEY (recommended)
+-- SQLite auto-increments INTEGER PRIMARY KEY automatically
+CREATE TABLE users (
+    id INTEGER PRIMARY KEY,
+    name TEXT
+);
+
+-- Option 2: AUTOINCREMENT keyword
+-- Ensures deleted IDs are not reused (slower)
+CREATE TABLE users (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    name TEXT
+);
+```
+
+---
+
+## Foreign Keys
+
+**IMPORTANT**: FK is disabled by default in SQLite!
+
+```sql
+-- Enable FK for each connection
+PRAGMA foreign_keys = ON;
+
+-- Create table with FK
+CREATE TABLE order_items (
+    id INTEGER PRIMARY KEY,
+    order_id INTEGER NOT NULL,
+    product_id INTEGER NOT NULL,
+    FOREIGN KEY (order_id) REFERENCES orders(id) ON DELETE CASCADE,
+    FOREIGN KEY (product_id) REFERENCES products(id) ON DELETE RESTRICT
+);
+
+-- Create index for FK
+CREATE INDEX idx_order_items_order ON order_items(order_id);
+CREATE INDEX idx_order_items_product ON order_items(product_id);
+```
+
+---
+
+## ENUM substitute
+
+SQLite does not have ENUM. Use CHECK constraint:
+
+```sql
+CREATE TABLE orders (
+    status TEXT NOT NULL DEFAULT 'pending'
+        CHECK (status IN ('pending', 'confirmed', 'shipped', 'cancelled'))
+);
+```
+
+---
+
+## Index Types
+
+SQLite only supports B-Tree indexes:
+
+```sql
+-- Standard index
+CREATE INDEX idx_orders_status ON orders(status);
+
+-- Composite index
+CREATE INDEX idx_orders_user_status ON orders(user_id, status);
+
+-- Unique index
+CREATE UNIQUE INDEX idx_orders_number ON orders(order_number);
+
+-- Partial index (SQLite 3.8.0+)
+CREATE INDEX idx_orders_active ON orders(user_id)
+    WHERE deleted_at IS NULL;
+```
+
+---
+
+## Limitations
+
+| Feature | Status | Workaround |
+|---------|--------|------------|
+| `ALTER COLUMN` | ❌ Not supported | Recreate table |
+| `DROP COLUMN` | ✅ SQLite 3.35+ | Recreate table (older) |
+| Comments | ❌ Not supported | Metadata tables |
+| ENUM | ❌ Not supported | CHECK constraint |
+| Stored procedures | ❌ Not supported | App logic |
+| Concurrent writes | ⚠️ Limited | Single writer |
+
+---
+
+## Example DDL
+
+```sql
+-- Enable foreign keys
+PRAGMA foreign_keys = ON;
+
+-- Create table
+CREATE TABLE orders (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    order_number TEXT NOT NULL,
+    user_id INTEGER NOT NULL,
+    status TEXT NOT NULL DEFAULT 'pending'
+        CHECK (status IN ('pending', 'confirmed', 'shipped', 'cancelled')),
+    subtotal REAL NOT NULL DEFAULT 0,
+    discount_amount REAL NOT NULL DEFAULT 0,
+    total_amount REAL NOT NULL DEFAULT 0,
+    created_at TEXT NOT NULL DEFAULT (datetime('now')),
+    updated_at TEXT NOT NULL DEFAULT (datetime('now')),
+    deleted_at TEXT,
+
+    FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE RESTRICT
+);
+
+-- Indexes
+CREATE UNIQUE INDEX idx_orders_number ON orders(order_number);
+CREATE INDEX idx_orders_user ON orders(user_id);
+CREATE INDEX idx_orders_status ON orders(status);
+CREATE INDEX idx_orders_updated ON orders(updated_at);
+
+-- Metadata
+INSERT INTO metadata_tables (table_name, description)
+VALUES ('orders', 'Table storing order information');
+
+INSERT INTO metadata_columns (table_name, column_name, description, data_type, is_nullable)
+VALUES
+    ('orders', 'id', 'Primary key', 'INTEGER', 0),
+    ('orders', 'order_number', 'Unique order code', 'TEXT', 0),
+    ('orders', 'user_id', 'FK to users.id', 'INTEGER', 0),
+    ('orders', 'status', 'pending|confirmed|shipped|cancelled', 'TEXT', 0),
+    ('orders', 'total_amount', 'Total payment', 'REAL', 0);
+```
+
+---
+
+## Checklist
+
+- [ ] `PRAGMA foreign_keys = ON` at start of each connection
+- [ ] Metadata tables created
+- [ ] INSERT metadata after each CREATE TABLE
+- [ ] Use `TEXT` for dates (ISO format: YYYY-MM-DD HH:MM:SS)
+- [ ] CHECK constraint instead of ENUM
+- [ ] Index for FK columns
+- [ ] Update metadata when ALTER/DROP table

package/.claude/skills/databases/transactional.md

@@ -0,0 +1,176 @@
+# Transactional (OLTP) Rules
+
+> **Note:** Core naming conventions, workflow, and checklist are in `SKILL.md` or `db-design.md` (always loaded).
+
+Guidelines for designing schemas for day-to-day business operations.
+
+---
+
+## Normalization Principles
+
+### Prefer 3NF (Third Normal Form)
+
+- Each table represents one clear entity/relationship
+- No repeating information that can be referenced (use FK)
+- Clear separation:
+  - `orders` (header) vs `order_items` (line items)
+  - `products` vs `product_variants`, `product_prices`
+
+### Foreign Key Constraints
+
+Use FK with appropriate ON DELETE / ON UPDATE:
+
+```sql
+-- Cascade: delete order → delete order_items
+FOREIGN KEY (order_id) REFERENCES orders(id) ON DELETE CASCADE
+
+-- Restrict: cannot delete user if orders exist
+FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE RESTRICT
+
+-- Set null: delete category → product.category_id = NULL
+FOREIGN KEY (category_id) REFERENCES categories(id) ON DELETE SET NULL
+```
+
+---
+
+## Indexing Rules
+
+### 1. Primary Key
+- Usually `BIGINT` auto-increment or UUID
+- Format: `PRIMARY KEY (id)`
+
+### 2. Foreign Key Indexes
+**IMPORTANT**: Create indexes for ALL foreign keys for efficient JOINs:
+```sql
+CREATE INDEX idx_orders_user_id ON orders(user_id);
+CREATE INDEX idx_order_items_order_id ON order_items(order_id);
+CREATE INDEX idx_order_items_product_id ON order_items(product_id);
+```
+
+### 3. Frequently Filtered Columns
+Index columns commonly used in WHERE:
+- `status`, `created_at`, `updated_at`
+- Code/reference columns: `order_number`, `sku`
+
+### 4. Composite Indexes
+Based on actual query patterns:
+```sql
+-- Query: WHERE user_id = ? AND status = ? ORDER BY created_at DESC
+CREATE INDEX idx_orders_user_status_created ON orders(user_id, status, created_at DESC);
+
+-- Query: WHERE store_id = ? AND created_at BETWEEN ...
+CREATE INDEX idx_orders_store_created ON orders(store_id, created_at);
+```
+
+**Composite index rules:**
+- Put columns with **high selectivity** (fewer duplicate values) first
+- Avoid duplicate/redundant indexes
+- Index should cover WHERE + ORDER BY of query
+
+### 5. Unique Constraints
+```sql
+UNIQUE (order_number)
+UNIQUE (sku)
+UNIQUE (user_id, email)  -- compound unique
+```
+
+---
+
+## Soft Delete Pattern
+
+When you need to keep deleted data instead of permanently deleting:
+
+```sql
+-- Add deleted_at column
+deleted_at TIMESTAMP NULL
+
+-- Partial index for non-deleted records (PostgreSQL)
+CREATE INDEX idx_orders_active ON orders(user_id, status)
+    WHERE deleted_at IS NULL;
+
+-- Query only active records
+SELECT * FROM orders WHERE deleted_at IS NULL;
+```
+
+---
+
+## Anti-patterns to Avoid
+
+### Missing FK Index
+```sql
+-- ❌ BAD: FK without index → slow JOINs
+FOREIGN KEY (user_id) REFERENCES users(id)
+-- Forgot CREATE INDEX
+```
+
+### Over-indexing
+```sql
+-- ❌ BAD: Indexing each column separately
+CREATE INDEX idx_a ON orders(user_id);
+CREATE INDEX idx_b ON orders(status);
+CREATE INDEX idx_c ON orders(created_at);
+
+-- ✅ GOOD: Composite index based on query pattern
+CREATE INDEX idx_orders_user_status_created ON orders(user_id, status, created_at DESC);
+```
+
+### Using TEXT instead of ENUM
+```sql
+-- ❌ BAD: Cannot validate values
+status TEXT
+
+-- ✅ GOOD: Use ENUM or CHECK
+status ENUM('pending', 'confirmed', 'shipped', 'cancelled')
+-- or
+status VARCHAR(32) CHECK (status IN ('pending', 'confirmed', 'shipped'))
+```
+
+### Missing Audit Columns
+```sql
+-- ❌ BAD
+CREATE TABLE products (id INT, name VARCHAR(255));
+
+-- ✅ GOOD
+CREATE TABLE products (
+    id INT,
+    name VARCHAR(255),
+    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP
+);
+```
+
+---
+
+## Example DDL
+
+```sql
+CREATE TABLE orders (
+    id BIGINT PRIMARY KEY AUTO_INCREMENT,
+    order_number VARCHAR(50) NOT NULL,
+    user_id BIGINT NOT NULL,
+    status VARCHAR(32) NOT NULL DEFAULT 'pending',
+    subtotal DECIMAL(18,2) NOT NULL DEFAULT 0,
+    discount_amount DECIMAL(18,2) NOT NULL DEFAULT 0,
+    total_amount DECIMAL(18,2) NOT NULL DEFAULT 0,
+    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
+
+    UNIQUE (order_number),
+    FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE RESTRICT
+);
+
+CREATE INDEX idx_orders_user_id ON orders(user_id);
+CREATE INDEX idx_orders_status ON orders(status);
+CREATE INDEX idx_orders_user_status_created ON orders(user_id, status, created_at DESC);
+```
+
+---
+
+## Checklist
+
+- [ ] Audit columns: `created_at`, `updated_at`
+- [ ] All FKs have indexes
+- [ ] Unique constraints for business keys (`order_number`, `sku`, `email`)
+- [ ] ENUM or CHECK for status/type columns
+- [ ] Composite index based on main query patterns
+- [ ] Soft delete if needed: `deleted_at` + partial index

package/.claude/skills/debug/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: debug
+description: Debug systematically with root cause analysis before fixes. Use for bugs, test failures, unexpected behavior, performance issues, call stack tracing, multi-layer validation.
+version: 3.1.0
+languages: all
+---
+
+# Debugging
+
+Comprehensive debugging framework combining systematic investigation, root cause tracing, defense-in-depth validation, and verification protocols.
+
+## Core Principle
+
+**NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST**
+
+Random fixes waste time and create new bugs. Find the root cause, fix at source, validate at every layer, verify before claiming success.
+
+## When to Use
+
+**Always use for:** Test failures, bugs, unexpected behavior, performance issues, build failures, integration problems, before claiming work complete
+
+**Especially when:** Under time pressure, "quick fix" seems obvious, tried multiple fixes, don't fully understand issue, about to claim success
+
+## The Four Techniques
+
+### 1. Systematic Debugging (`references/systematic-debugging.md`)
+
+Four-phase framework ensuring proper investigation:
+- Phase 1: Root Cause Investigation (read errors, reproduce, check changes, gather evidence)
+- Phase 2: Pattern Analysis (find working examples, compare, identify differences)
+- Phase 3: Hypothesis and Testing (form theory, test minimally, verify)
+- Phase 4: Implementation (create test, fix once, verify)
+
+**Key rule:** Complete each phase before proceeding. No fixes without Phase 1.
+
+**Load when:** Any bug/issue requiring investigation and fix
+
+### 2. Root Cause Tracing (`references/root-cause-tracing.md`)
+
+Trace bugs backward through call stack to find original trigger.
+
+**Technique:** When error appears deep in execution, trace backward level-by-level until finding source where invalid data originated. Fix at source, not at symptom.
+
+**Includes:** `scripts/find-polluter.sh` for bisecting test pollution
+
+**Load when:** Error deep in call stack, unclear where invalid data originated
+
+### 3. Defense-in-Depth (`references/defense-in-depth.md`)
+
+Validate at every layer data passes through. Make bugs impossible.
+
+**Four layers:** Entry validation → Business logic → Environment guards → Debug instrumentation
+
+**Load when:** After finding root cause, need to add comprehensive validation
+
+### 4. Verification (`references/verification.md`)
+
+Run verification commands and confirm output before claiming success.
+
+**Iron law:** NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE
+
+Run the command. Read the output. Then claim the result.
+
+**Load when:** About to claim work complete, fixed, or passing
+
+## Quick Reference
+
+```
+Bug → systematic-debugging.md (Phase 1-4)
+  Error deep in stack? → root-cause-tracing.md (trace backward)
+  Found root cause? → defense-in-depth.md (add layers)
+  About to claim success? → verification.md (verify first)
+```
+
+## Red Flags
+
+Stop and follow process if thinking:
+- "Quick fix for now, investigate later"
+- "Just try changing X and see if it works"
+- "It's probably X, let me fix that"
+- "Should work now" / "Seems fixed"
+- "Tests pass, we're done"
+
+**All mean:** Return to systematic process.

package/.claude/skills/debug/references/defense-in-depth.md

@@ -0,0 +1,124 @@
+# Defense-in-Depth Validation
+
+Validate at every layer data passes through to make bugs impossible.
+
+## Core Principle
+
+**Validate at EVERY layer data passes through. Make bug structurally impossible.**
+
+When fix bug caused by invalid data, adding validation at one place feels sufficient. But single check can be bypassed by different code paths, refactoring, or mocks.
+
+## Why Multiple Layers
+
+Single validation: "We fixed bug"
+Multiple layers: "We made bug impossible"
+
+Different layers catch different cases:
+- Entry validation catches most bugs
+- Business logic catches edge cases
+- Environment guards prevent context-specific dangers
+- Debug logging helps when other layers fail
+
+## The Four Layers
+
+### Layer 1: Entry Point Validation
+**Purpose:** Reject obviously invalid input at API boundary
+
+```typescript
+function createProject(name: string, workingDirectory: string) {
+  if (!workingDirectory || workingDirectory.trim() === '') {
+    throw new Error('workingDirectory cannot be empty');
+  }
+  if (!existsSync(workingDirectory)) {
+    throw new Error(`workingDirectory does not exist: ${workingDirectory}`);
+  }
+  if (!statSync(workingDirectory).isDirectory()) {
+    throw new Error(`workingDirectory is not a directory: ${workingDirectory}`);
+  }
+  // proceed
+}
+```
+
+### Layer 2: Business Logic Validation
+**Purpose:** Ensure data makes sense for this operation
+
+```typescript
+function initializeWorkspace(projectDir: string, sessionId: string) {
+  if (!projectDir) {
+    throw new Error('projectDir required for workspace initialization');
+  }
+  // proceed
+}
+```
+
+### Layer 3: Environment Guards
+**Purpose:** Prevent dangerous operations in specific contexts
+
+```typescript
+async function gitInit(directory: string) {
+  // In tests, refuse git init outside temp directories
+  if (process.env.NODE_ENV === 'test') {
+    const normalized = normalize(resolve(directory));
+    const tmpDir = normalize(resolve(tmpdir()));
+
+    if (!normalized.startsWith(tmpDir)) {
+      throw new Error(
+        `Refusing git init outside temp dir during tests: ${directory}`
+      );
+    }
+  }
+  // proceed
+}
+```
+
+### Layer 4: Debug Instrumentation
+**Purpose:** Capture context for forensics
+
+```typescript
+async function gitInit(directory: string) {
+  const stack = new Error().stack;
+  logger.debug('About to git init', {
+    directory,
+    cwd: process.cwd(),
+    stack,
+  });
+  // proceed
+}
+```
+
+## Applying the Pattern
+
+When find bug:
+
+1. **Trace data flow** - Where does bad value originate? Where used?
+2. **Map all checkpoints** - List every point data passes through
+3. **Add validation at each layer** - Entry, business, environment, debug
+4. **Test each layer** - Try to bypass layer 1, verify layer 2 catches it
+
+## Example from Real Session
+
+Bug: Empty `projectDir` caused `git init` in source code
+
+**Data flow:**
+1. Test setup → empty string
+2. `Project.create(name, '')`
+3. `WorkspaceManager.createWorkspace('')`
+4. `git init` runs in `process.cwd()`
+
+**Four layers added:**
+- Layer 1: `Project.create()` validates not empty/exists/writable
+- Layer 2: `WorkspaceManager` validates projectDir not empty
+- Layer 3: `WorktreeManager` refuses git init outside tmpdir in tests
+- Layer 4: Stack trace logging before git init
+
+**Result:** All 1847 tests passed, bug impossible to reproduce
+
+## Key Insight
+
+All four layers were necessary. During testing, each layer caught bugs others missed:
+- Different code paths bypassed entry validation
+- Mocks bypassed business logic checks
+- Edge cases on different platforms needed environment guards
+- Debug logging identified structural misuse
+
+**Don't stop at one validation point.** Add checks at every layer.