@hienlh/ppm 0.9.81 → 0.9.83

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

@@ -1,244 +0,0 @@
-# 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/.opencode/skills/databases/transactional.md

@@ -1,176 +0,0 @@
-# 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/.opencode/skills/debugging/SKILL.md

@@ -1,87 +0,0 @@
----
-name: ckm:debugging
-description: Systematic debugging framework ensuring root cause investigation before fixes. Includes four-phase debugging process, backward call stack tracing, multi-layer validation, and verification protocols. Use when encountering bugs, test failures, unexpected behavior, performance issues, or before claiming work complete. Prevents random fixes, masks over symptoms, and false completion claims.
-argument-hint: "[error or issue description]"
-languages: all
-metadata:
-  author: claudekit
-  version: "3.0.0"
----
-
-# 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/.opencode/skills/debugging/references/defense-in-depth.md

@@ -1,124 +0,0 @@
-# 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.