sqlew 5.1.0 → 5.2.1

package/dist/watcher/base-watcher.js.map

@@ -1 +1 @@
-{"version":3,"file":"base-watcher.js","sourceRoot":"","sources":["../../src/watcher/base-watcher.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"base-watcher.js","sourceRoot":"","sources":["../../src/watcher/base-watcher.ts"],"names":[],"mappings":"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"}

package/docs/ADR_CONCEPTS.md

@@ -1,152 +1,152 @@
-# Decisions & Constraints for AI Development
-
-Persistent design context — decisions and constraints recorded as structured data — gives AI agents architectural memory across sessions. sqlew makes this zero-effort: plan normally, and hooks capture your decisions automatically.
-
-## Why Persistent Design Context Matters
-
-Research shows that recording design intent dramatically improves LLM code generation:
-
-- **22.4% reduction** in overall development time
-- **80% of tasks** completed faster with design intent available
-- **50%+ improvement** in feature-addition and architectural-change tasks
-- **137% increase** in design decision references by final tasks — AI learns to leverage past context more over time
-
-> Kitayama, S. (2026). *Rediscovering Architectural Decision Records: How Persistent Design Context Improves LLM Code Generation*. [DOI](https://doi.org/10.36227/techrxiv.177205025.54351571/v1)
->
-> Blog post: [Recording Design Intent for AI Efficiency](https://blog.sqlew.io/recording-design-intent-for-ai-efficiency)
-
-## Key Benefits for AI-Driven Development
-
-### Persistent Architectural Memory
-- **Zero context loss** – AI agents remember every architectural decision across sessions
-- **Rationale preservation** – Never forget WHY a decision was made, not just WHAT
-- **Alternative tracking** – Document rejected options to prevent circular debates
-- **Evolution history** – See how decisions changed over time with full version history
-
-### Prevent Architectural Drift
-- **Constraint enforcement** – Define architectural rules once, AI follows them forever
-- **Pattern consistency** – AI generates code matching established patterns automatically
-- **Anti-pattern prevention** – Document "what NOT to do" as enforceable constraints
-- **Regression prevention** – AI won't reintroduce previously rejected approaches
-
-### Intelligent Decision Discovery
-- **Three-tier duplicate detection** – Gentle nudge (35-44), hard block (45-59), or auto-update (60+) based on similarity score
-- **Similarity detection** – AI identifies duplicate or related decisions before creating new ones
-- **Context-aware search** – Query by layer, tags, or relationships to find relevant decisions
-- **Conflict detection** – Find decisions that contradict or supersede each other
-
-### Extreme Efficiency
-- **60-75% token reduction** – Query only relevant decisions instead of reading full files
-- **Millisecond queries** – 2-50ms response times even with thousands of decisions
-- **Scalable architecture** – Perform well with large decision histories
-
-## How sqlew Works
-
-```mermaid
-flowchart LR
-    subgraph Claude Code
-        A[Plan Mode] -->|Create Plan| B[User Approval]
-        B -->|ExitPlanMode| C[Hook Triggered]
-    end
-
-    subgraph sqlew
-        C -->|Enqueue| D[Queue File]
-        D -->|QueueWatcher| E[(SQL Database)]
-    end
-
-    subgraph Next Session
-        F[AI Agent] -->|Query| E
-        E -->|Past Decisions| F
-    end
-```
-
-**Zero-effort knowledge accumulation:**
-1. You plan your work normally in Claude Code
-2. Hooks automatically capture decisions
-3. Next session, AI queries past decisions via SQL
-
-## Core Concepts
-
-**Decisions** capture architectural choices with full context:
-- **What** was decided (the decision itself)
-- **Why** it was chosen (rationale, trade-offs)
-- **What else** was considered (alternatives rejected)
-- **Impact** on the system (consequences, affected components)
-
-**Constraints** define architectural principles and rules:
-- **Performance requirements** (response time limits, throughput goals)
-- **Technology choices** ("must use PostgreSQL", "avoid microservices")
-- **Coding standards** ("async/await only", "no any types")
-- **Security policies** (authentication patterns, data handling rules)
-
-**Lifecycle tracking:**
-- **Status evolution** tracks decision lifecycle (draft → active → deprecated)
-- **Auto-capture via Hooks** records decisions automatically from Plan Mode
-
-```mermaid
-erDiagram
-    DECISION ||--o{ TAG : has
-    DECISION {
-        string key
-        string value
-        string layer
-        string status
-        timestamp updated
-    }
-    CONSTRAINT ||--o{ TAG : has
-    CONSTRAINT {
-        string text
-        string category
-        int priority
-    }
-    TAG {
-        string name
-    }
-```
-
-## SQL vs Markdown
-
-| Traditional approach (Markdown) | sqlew approach (SQL) |
-|--------------------------------|---------------------|
-| Read entire files | Query specific decisions |
-| Manual duplicate checking | Automatic similarity detection |
-| Text parsing required | Structured, typed data |
-| Linear token scaling | Constant-time lookups |
-| File-based organization | Relational queries with JOINs |
-
-### Why SQL?
-
-Traditional text-based records force AI to:
-- Read complete files even for simple queries
-- Parse unstructured text to find relationships
-- Manually detect duplicate or conflicting decisions
-
-sqlew's **SQL-backed decision repository** enables AI to:
-- Query by layer, tags, status in milliseconds (2-50ms)
-- Join decisions with constraints
-- Leverage similarity algorithms to prevent duplicates
-- Scale to thousands of decisions without context explosion
-
-**Token efficiency**: 60-75% reduction compared to reading Markdown files
-
-### Why RDBMS + MCP?
-
-**RDBMS (Relational Database)** provides efficient structured queries:
-- **Indexed searches** – Find decisions by tags/layers in milliseconds, not seconds
-- **JOIN operations** – Query related decisions and constraints in a single operation
-- **Transaction support** – ACID guarantees ensure data integrity across concurrent AI agents
-- **Scalability** – Handle thousands of decisions without performance degradation
-
-**MCP (Model Context Protocol)** enables seamless AI integration:
-- **Seamless DB connection** – AI agents access the database through a standardized protocol without direct DB setup
-- **Self-documenting tools** – Tool descriptions teach AI how to use each operation, no manual onboarding needed
-- **Type safety** – Structured parameters prevent errors and guide correct usage
-- **Cross-session persistence** – Decisions survive beyond individual chat sessions
-
-**Together**: AI agents gain SQL-powered decision capabilities without managing databases directly.
-
-## References
-
-- Kitayama, S. (2026). *Rediscovering Architectural Decision Records: How Persistent Design Context Improves LLM Code Generation*. [DOI](https://doi.org/10.36227/techrxiv.177205025.54351571/v1)
-- Blog: [Recording Design Intent for AI Efficiency](https://blog.sqlew.io/recording-design-intent-for-ai-efficiency)
-- The concept of Architecture Decision Records was originally proposed by Michael Nygard in 2011.
+# Decisions & Constraints for AI Development
+
+Persistent design context — decisions and constraints recorded as structured data — gives AI agents architectural memory across sessions. sqlew makes this zero-effort: plan normally, and hooks capture your decisions automatically.
+
+## Why Persistent Design Context Matters
+
+Research shows that recording design intent dramatically improves LLM code generation:
+
+- **22.4% reduction** in overall development time
+- **80% of tasks** completed faster with design intent available
+- **50%+ improvement** in feature-addition and architectural-change tasks
+- **137% increase** in design decision references by final tasks — AI learns to leverage past context more over time
+
+> Kitayama, S. (2026). *Rediscovering Architectural Decision Records: How Persistent Design Context Improves LLM Code Generation*. [DOI](https://doi.org/10.36227/techrxiv.177205025.54351571/v1)
+>
+> Blog post: [Recording Design Intent for AI Efficiency](https://blog.sqlew.io/recording-design-intent-for-ai-efficiency)
+
+## Key Benefits for AI-Driven Development
+
+### Persistent Architectural Memory
+- **Zero context loss** – AI agents remember every architectural decision across sessions
+- **Rationale preservation** – Never forget WHY a decision was made, not just WHAT
+- **Alternative tracking** – Document rejected options to prevent circular debates
+- **Evolution history** – See how decisions changed over time with full version history
+
+### Prevent Architectural Drift
+- **Constraint enforcement** – Define architectural rules once, AI follows them forever
+- **Pattern consistency** – AI generates code matching established patterns automatically
+- **Anti-pattern prevention** – Document "what NOT to do" as enforceable constraints
+- **Regression prevention** – AI won't reintroduce previously rejected approaches
+
+### Intelligent Decision Discovery
+- **Three-tier duplicate detection** – Gentle nudge (35-44), hard block (45-59), or auto-update (60+) based on similarity score
+- **Similarity detection** – AI identifies duplicate or related decisions before creating new ones
+- **Context-aware search** – Query by layer, tags, or relationships to find relevant decisions
+- **Conflict detection** – Find decisions that contradict or supersede each other
+
+### Extreme Efficiency
+- **60-75% token reduction** – Query only relevant decisions instead of reading full files
+- **Millisecond queries** – 2-50ms response times even with thousands of decisions
+- **Scalable architecture** – Perform well with large decision histories
+
+## How sqlew Works
+
+```mermaid
+flowchart LR
+    subgraph Claude Code
+        A[Plan Mode] -->|Create Plan| B[User Approval]
+        B -->|ExitPlanMode| C[Hook Triggered]
+    end
+
+    subgraph sqlew
+        C -->|Enqueue| D[Queue File]
+        D -->|QueueWatcher| E[(SQL Database)]
+    end
+
+    subgraph Next Session
+        F[AI Agent] -->|Query| E
+        E -->|Past Decisions| F
+    end
+```
+
+**Zero-effort knowledge accumulation:**
+1. You plan your work normally in Claude Code
+2. Hooks automatically capture decisions
+3. Next session, AI queries past decisions via SQL
+
+## Core Concepts
+
+**Decisions** capture architectural choices with full context:
+- **What** was decided (the decision itself)
+- **Why** it was chosen (rationale, trade-offs)
+- **What else** was considered (alternatives rejected)
+- **Impact** on the system (consequences, affected components)
+
+**Constraints** define architectural principles and rules:
+- **Performance requirements** (response time limits, throughput goals)
+- **Technology choices** ("must use PostgreSQL", "avoid microservices")
+- **Coding standards** ("async/await only", "no any types")
+- **Security policies** (authentication patterns, data handling rules)
+
+**Lifecycle tracking:**
+- **Status evolution** tracks decision lifecycle (draft → active → deprecated)
+- **Auto-capture via Hooks** records decisions automatically from Plan Mode
+
+```mermaid
+erDiagram
+    DECISION ||--o{ TAG : has
+    DECISION {
+        string key
+        string value
+        string layer
+        string status
+        timestamp updated
+    }
+    CONSTRAINT ||--o{ TAG : has
+    CONSTRAINT {
+        string text
+        string category
+        int priority
+    }
+    TAG {
+        string name
+    }
+```
+
+## SQL vs Markdown
+
+| Traditional approach (Markdown) | sqlew approach (SQL) |
+|--------------------------------|---------------------|
+| Read entire files | Query specific decisions |
+| Manual duplicate checking | Automatic similarity detection |
+| Text parsing required | Structured, typed data |
+| Linear token scaling | Constant-time lookups |
+| File-based organization | Relational queries with JOINs |
+
+### Why SQL?
+
+Traditional text-based records force AI to:
+- Read complete files even for simple queries
+- Parse unstructured text to find relationships
+- Manually detect duplicate or conflicting decisions
+
+sqlew's **SQL-backed decision repository** enables AI to:
+- Query by layer, tags, status in milliseconds (2-50ms)
+- Join decisions with constraints
+- Leverage similarity algorithms to prevent duplicates
+- Scale to thousands of decisions without context explosion
+
+**Token efficiency**: 60-75% reduction compared to reading Markdown files
+
+### Why RDBMS + MCP?
+
+**RDBMS (Relational Database)** provides efficient structured queries:
+- **Indexed searches** – Find decisions by tags/layers in milliseconds, not seconds
+- **JOIN operations** – Query related decisions and constraints in a single operation
+- **Transaction support** – ACID guarantees ensure data integrity across concurrent AI agents
+- **Scalability** – Handle thousands of decisions without performance degradation
+
+**MCP (Model Context Protocol)** enables seamless AI integration:
+- **Seamless DB connection** – AI agents access the database through a standardized protocol without direct DB setup
+- **Self-documenting tools** – Tool descriptions teach AI how to use each operation, no manual onboarding needed
+- **Type safety** – Structured parameters prevent errors and guide correct usage
+- **Cross-session persistence** – Decisions survive beyond individual chat sessions
+
+**Together**: AI agents gain SQL-powered decision capabilities without managing databases directly.
+
+## References
+
+- Kitayama, S. (2026). *Rediscovering Architectural Decision Records: How Persistent Design Context Improves LLM Code Generation*. [DOI](https://doi.org/10.36227/techrxiv.177205025.54351571/v1)
+- Blog: [Recording Design Intent for AI Efficiency](https://blog.sqlew.io/recording-design-intent-for-ai-efficiency)
+- The concept of Architecture Decision Records was originally proposed by Michael Nygard in 2011.