sqlew 4.0.5 → 4.1.0

package/docs/AI_AGENT_GUIDE.md

@@ -1,299 +0,0 @@
-# AI Agent Guide for sqlew ADR System
-
-**Quick Reference for Claude Code and other AI agents using sqlew (v4.0.0+)**
-
-## What is sqlew?
-
-sqlew is an **ADR (Architecture Decision Record) system designed for AI agents**. It enables you to create, query, and maintain structured architectural decisions in a SQL database, providing persistent context across sessions.
-
-### Core Concept: ADR for AI
-
-Traditional ADR uses Markdown files. sqlew brings ADR to AI agents through **RDBMS + MCP**:
-
-**RDBMS (Relational Database)** enables efficient operations:
-- **Indexed queries** – Find decisions by tags/layers in milliseconds
-- **JOIN operations** – Query related decisions, constraints, and tasks together
-- **Transaction safety** – ACID guarantees prevent data corruption
-- **Scalability** – Handle thousands of ADRs without slowdown
-
-**MCP (Model Context Protocol)** provides AI-native access:
-- **Native tool calls** – AI agents use ADR as built-in functions
-- **Structured parameters** – Type-safe, validated inputs prevent errors
-- **Token efficiency** – Retrieve only required data (60-75% reduction)
-- **Session persistence** – ADRs survive beyond individual conversations
-
-**Result**: AI agents query ADRs like database operations, not file reads.
-
----
-
-## Most Important Rule
-
-**ALWAYS include the `action` parameter in EVERY tool call.** This is the #1 cause of errors.
-
-```javascript
-// WRONG - Missing action
-{
-  key: "auth_method",
-  value: "jwt"
-}
-
-// CORRECT - action parameter present
-{
-  action: "set",
-  key: "auth_method",
-  value: "jwt"
-}
-```
-
----
-
-## Quick Start: Creating Your First ADR
-
-### Basic ADR Workflow
-
-```javascript
-// 1. Record an architectural decision
-{
-  action: "set",
-  key: "auth_method",
-  value: "We chose JWT authentication over session-based auth. JWT enables stateless API design and better horizontal scaling. Session-based auth was rejected due to scaling concerns with shared session stores.",
-  layer: "business",
-  tags: ["security", "authentication", "api"]
-}
-
-// 2. Retrieve the decision
-{
-  action: "get",
-  key: "auth_method"
-}
-
-// 3. Search for related decisions
-{
-  action: "list",
-  tags: ["authentication"],
-  status: "active"
-}
-
-// 4. Add architectural constraint
-{
-  action: "add",
-  category: "security",
-  constraint_text: "All authentication must use JWT with RS256 signing algorithm",
-  layer: "business"
-}
-```
-
----
-
-## When to Use Each Tool
-
-### Core ADR Tools
-
-| Tool | ADR Purpose | Key Feature |
-|------|-------------|-------------|
-| **decision** | Record architectural decisions | Full version history, alternatives tracking |
-| **constraint** | Define architectural principles | Category-based rules, validation support |
-| **task** | Track decision implementation | Links to decisions, status tracking |
-| **file** | Document impacted code | Shows which files implement decisions |
-| **suggest** | Find similar decisions | Prevent duplicate ADRs, detect conflicts |
-
-### Utility Tools
-
-| Tool | Purpose | When to Use |
-|------|---------|-------------|
-| **help** | Query action parameters | Need to check available parameters for an action |
-| **example** | Browse code examples | Want to see working code snippets |
-| **use_case** | Learn complete workflows | Need end-to-end multi-step scenarios |
-
-> **Note**: Utility tools provide documentation and examples without affecting your ADR data.
-
-### Understanding the ADR Data Model
-
-| Concept | ADR Equivalent | Example |
-|---------|----------------|---------|
-| **Decision** | Architecture Decision Record | "We chose PostgreSQL over MongoDB for ACID compliance" |
-| **Constraint** | Architectural Principle/Rule | "All database queries must use prepared statements" |
-| **Task** | Implementation Action | "Migrate user authentication to JWT" |
-| **File** | Impacted Component | "Modified auth.ts to implement JWT" |
-
-### Complete ADR Workflow Example
-
-```javascript
-// 1. Record decision with full context
-{
-  action: "set",
-  key: "database_choice",
-  value: "PostgreSQL selected for production database. Alternatives considered: MongoDB (rejected: no ACID), MySQL (rejected: weaker JSON support). PostgreSQL chosen for ACID compliance, mature ecosystem, and superior JSON handling.",
-  layer: "data",
-  tags: ["database", "postgresql", "architecture"]
-}
-
-// 2. Define constraints based on decision
-{
-  action: "add",
-  category: "database",
-  constraint_text: "All database operations must use connection pooling with max 20 connections",
-  layer: "data"
-}
-
-// 3. Create implementation task
-{
-  action: "create",
-  title: "Set up PostgreSQL connection pool",
-  description: "Implement connection pooling as per database_choice ADR",
-  layer: "data",
-  tags: ["database", "postgresql"]
-}
-
-// 4. Track file changes
-{
-  action: "set",
-  path: "src/db/connection.ts",
-  description: "PostgreSQL connection pool implementation",
-  layer: "data"
-}
-```
-
----
-
-## Common Errors & Solutions
-
-### Error: "Unknown action: undefined"
-
-**Cause**: Missing `action` parameter
-
-```javascript
-// WRONG
-{ key: "some_key", value: "some value" }
-
-// CORRECT
-{ action: "set", key: "some_key", value: "some value" }
-```
-
-### Error: "Invalid layer"
-
-**Valid layers** (9 total):
-- `presentation`, `business`, `data`, `infrastructure`, `cross-cutting`
-- `documentation`, `planning`, `coordination`, `review`
-
-### Error: "Invalid status"
-
-**Valid decision statuses**: `active`, `deprecated`, `draft`
-
-**Valid task statuses**: `pending`, `in_progress`, `blocked`, `on_hold`, `completed`
-
-### Error: "Batch operations are limited to 50 items maximum"
-
-**Solution**: Split into multiple batches of ≤50 items each
-
----
-
-## Key Parameters Quick Reference
-
-### decision tool
-
-| Action | Required | Optional |
-|--------|----------|----------|
-| **set** | action, key, value, layer | version, status, tags, scopes |
-| **get** | action, key | version |
-| **list** | action | status, layer, tags, limit |
-
-### task tool
-
-| Action | Required | Optional |
-|--------|----------|----------|
-| **create** | action, title | description, priority, layer, tags, status |
-| **move** | action, task_id, status | - |
-| **list** | action | status, layer, tags, limit |
-
-### constraint tool
-
-| Action | Required | Optional |
-|--------|----------|----------|
-| **add** | action, category, constraint_text | priority, layer, tags |
-| **get** | action | category, layer, active_only |
-
-> **Full parameter reference**: See [TOOL_REFERENCE.md](TOOL_REFERENCE.md)
-
----
-
-## ADR Best Practices for AI Agents
-
-### Writing Good ADRs
-
-1. **Include rationale** - Explain WHY, not just WHAT
-   ```javascript
-   // BAD: "Use PostgreSQL"
-   // GOOD: "Use PostgreSQL for ACID compliance (rejected MongoDB for lack of transactions)"
-   ```
-
-2. **Document alternatives** - Show what was considered and rejected
-   ```javascript
-   value: "JWT chosen. Alternatives: session-based (rejected: scaling), OAuth (overkill for internal API)"
-   ```
-
-3. **Use descriptive keys** - Make decisions discoverable
-   ```javascript
-   // BAD: key: "db"
-   // GOOD: key: "database_postgresql_production"
-   ```
-
-4. **Tag comprehensively** - Enable efficient searching
-   ```javascript
-   tags: ["database", "postgresql", "production", "acid", "scalability"]
-   ```
-
-5. **Link related entities** - Connect decisions to implementation
-   ```javascript
-   // Record decision → Create constraint → Make task → Track files
-   ```
-
-### Technical Best Practices
-
-1. **Always include `action` parameter** - #1 error source
-2. **Always specify `layer`** - Required for architectural organization
-3. **Use `atomic: false` for batch operations** - Avoid all-or-nothing failures
-4. **Check for duplicates first** - Use `suggest` tool before creating decisions
-5. **Version important changes** - Increment version for significant updates
-
-> **Detailed best practices**: See [BEST_PRACTICES.md](BEST_PRACTICES.md)
-
----
-
-## Built-In Documentation
-
-All tools provide built-in help with zero token cost:
-
-```javascript
-// Get detailed help for any tool
-{ action: "help" }
-
-// Get comprehensive examples
-{ action: "example" }
-```
-
----
-
-## Related Documentation
-
-| Document | Content |
-|----------|---------|
-| [TOOL_REFERENCE.md](TOOL_REFERENCE.md) | Complete parameter reference |
-| [WORKFLOWS.md](WORKFLOWS.md) | Multi-step workflow examples |
-| [BEST_PRACTICES.md](BEST_PRACTICES.md) | Detailed best practices |
-| [DECISION_INTELLIGENCE.md](DECISION_INTELLIGENCE.md) | Decision duplicate detection |
-| [CONSTRAINT_INTELLIGENCE.md](CONSTRAINT_INTELLIGENCE.md) | Constraint duplicate detection |
-| [BATCH_VALIDATION.md](BATCH_VALIDATION.md) | Batch operations guide |
-| [ARCHITECTURE.md](ARCHITECTURE.md) | System architecture |
-
----
-
-## Most Common Mistakes
-
-1. **Missing `action` parameter** ← #1 error!
-2. Invalid layer/status values
-3. Forgetting to specify `layer` when setting decisions
-4. Using `atomic: true` by default in batch operations
-5. Using `new_status` instead of `status` for task.move
-
-**When in doubt**: Call `{action: "help"}` or `{action: "example"}`!

package/docs/ARCHITECTURE.md

@@ -1,167 +0,0 @@
-# sqlew Architecture Documentation
-
-## Overview
-
-sqlew (SQL Efficient Workflow) is an MCP server designed to achieve **72% token reduction** in context sharing between Claude Code agents through intelligent database design and metadata-driven architecture. **Version 4.0.0** introduces a major schema refactoring with unified v4_ table prefix and action-based MCP tool architecture.
-
-## Core Design Principles
-
-### 1. Token Efficiency Strategy
-
-The 72% token reduction is achieved through five key strategies:
-
-| Strategy | Description | Savings |
-|----------|-------------|---------|
-| **ID-Based Normalization** | Store strings once in master tables, reference by integer IDs | ~50% |
-| **Integer Enums** | Replace string values with integers (status, priority, etc.) | 70-75% |
-| **Pre-Aggregated Views** | Eliminate need for multiple joins in client code | ~85% |
-| **Type-Based Separation** | Separate tables for numeric vs string values | ~50% |
-| **Automatic Cleanup** | Prevent database bloat via triggers | N/A |
-
-### 2. Metadata-Driven Classification
-
-sqlew organizes data through five metadata dimensions:
-
-| Dimension | Purpose | Example |
-|-----------|---------|---------|
-| **Tags** | Flexible cross-cutting categorization | authentication, security, api |
-| **Layers** | Architecture layer organization (9 layers) | business, data, infrastructure |
-| **Scopes** | Module/component-level organization | user-service, api-gateway |
-| **Versions** | Automatic version history tracking | 1.0.0, 1.1.0 |
-| **Priority** | Importance levels (1-4) | low, medium, high, critical |
-
-### 3. Layer System (v4.0)
-
-9 layers organized by file requirement:
-
-**FILE_REQUIRED (6 layers):**
-- presentation, business, data, infrastructure, cross-cutting, documentation
-
-**FILE_OPTIONAL (3 layers):**
-- planning, coordination, review
-
-### 4. Data Integrity
-
-- **Foreign Key Constraints**: All relationships enforced via SQLite
-- **Transaction Guarantees**: ACID properties, WAL mode for concurrency
-- **Auto-Registration Pattern**: Master records auto-created on first use
-
-## Database Schema (v4.0)
-
-All tables use unified `v4_` prefix. For detailed schema, see `src/database/migrations/v4/`.
-
-### Master Tables (Normalization)
-
-| Table | Purpose |
-|-------|---------|
-| `v4_files` | Normalize file paths |
-| `v4_context_keys` | Normalize decision keys |
-| `v4_layers` | Architecture layers (9 seeded) |
-| `v4_tags` | Categorization tags (10 seeded, auto-expandable) |
-| `v4_scopes` | Module/component scopes |
-| `v4_constraint_categories` | Constraint types (performance, architecture, security) |
-| `v4_task_statuses` | Task status types (pending, in_progress, completed, blocked, on_hold) |
-| `v4_config` | Configuration storage |
-
-### Transaction Tables (Core Data)
-
-| Table | Purpose |
-|-------|---------|
-| `v4_decisions` | Store decisions with layer, status, version |
-| `v4_decision_history` | Version history for all decision changes |
-| `v4_decision_context` | Decision context (rationale, alternatives, tradeoffs) |
-| `v4_file_changes` | Track file modifications with layer |
-| `v4_constraints` | Project constraints with priority |
-| `v4_tasks` | Task management with kanban-style status |
-
-### Relationship Tables
-
-| Table | Purpose |
-|-------|---------|
-| `v4_decision_tags` | Decision ↔ Tags (many-to-many) |
-| `v4_decision_scopes` | Decision ↔ Scopes (many-to-many) |
-| `v4_task_file_links` | Task ↔ Files with action types |
-| `v4_task_dependencies` | Task dependencies with circular detection |
-
-### Pre-Aggregated Views
-
-| View | Purpose |
-|------|---------|
-| `v4_tagged_decisions` | Decisions with all metadata (tags, layers, scopes) |
-| `v4_layer_summary` | Per-layer aggregated statistics |
-| `v4_recent_file_changes` | Recent file changes with metadata |
-| `v4_tagged_constraints` | Constraints with category and layer |
-| `v4_task_board` | Kanban-style task view with dependencies |
-
-## MCP Tool Architecture
-
-### Action-Based Tool System (v4.0)
-
-6 consolidated action-based MCP tools:
-
-| Tool | Purpose | Key Actions |
-|------|---------|-------------|
-| **decision** | Decision context management | set, get, list, search, versions |
-| **file** | File change tracking | record, get, check_lock |
-| **constraint** | Constraint management | add, get, deactivate |
-| **task** | Task management with dependencies | create, update, move, link, list |
-| **help** | Documentation queries | query_action, query_tool, workflow_hints |
-| **suggest** | Decision intelligence | by_key, by_tags, check_duplicate |
-
-All tools support `action: "help"` for in-tool documentation.
-
-## Performance Characteristics
-
-### Query Performance
-
-| Operation | Avg Time |
-|-----------|----------|
-| decision.set | 2-5 ms |
-| decision.get | 5-15 ms |
-| file.record | 2-4 ms |
-| task.create | 3-7 ms |
-
-### Database Size
-
-- **Empty:** ~28 KB (schema + seed data)
-- **Growth Rate:** ~140 bytes/decision (linear)
-
-### Concurrent Access
-
-- **WAL Mode:** Enabled for read/write concurrency
-- **Busy Timeout:** 5000ms
-
-## File Structure
-
-| Component | Location |
-|-----------|----------|
-| MCP Server | `src/index.ts` |
-| Database Init | `src/database/initialization/` |
-| Migrations | `src/database/migrations/v4/` |
-| Tool Implementations | `src/tools/` |
-| Types | `src/types.ts` |
-| Constants | `src/constants.ts` |
-
-## Known Limitations
-
-1. **No Semantic Search:** Delegated to specialized tools like Serena
-2. **Single Project Scope:** Not multi-tenant
-3. **No Authentication:** Trust-based (local MCP server)
-4. **No Network Access:** Offline-only operation
-
-## Version History
-
-| Version | Key Changes |
-|---------|-------------|
-| **v4.0.0** | Unified v4_ prefix, agent system removed, 6 action-based tools, 9 layers |
-| v3.9.0 | Decision Intelligence System, suggestion policies |
-| v3.8.0 | Layer expansion (5→9), file_actions parameter |
-| v3.0.0 | Kanban task system, 7-tool consolidation |
-| v2.0 | Action-based API, 96% token reduction |
-
-## Related Documentation
-
-- [SHARED_CONCEPTS.md](SHARED_CONCEPTS.md) - Common concepts across tools
-- [TOOL_REFERENCE.md](TOOL_REFERENCE.md) - Complete tool parameter reference
-- [CONFIGURATION.md](CONFIGURATION.md) - Configuration options
-- [TASK_OVERVIEW.md](TASK_OVERVIEW.md) - Task management overview