sqlew 3.8.1 → 3.9.1

package/docs/TOOL_REFERENCE.md

@@ -108,30 +108,28 @@
 }
 ```
 
-### Basic Messaging Workflow
+### Basic Suggestion Workflow (v3.9.0)
 
 ```javascript
-// 1. Send a message
+// 1. Check for duplicates before creating
 {
-  action: "send",
-  from_agent: "bot1",
-  msg_type: "info",
-  message: "Task completed successfully",
-  priority: "high"
+  action: "check_duplicate",
+  key: "api-rate-limiting",
+  tags: ["api", "performance"]
 }
 
-// 2. Get messages
+// 2. Find related decisions by tags
 {
-  action: "get",
-  agent_name: "bot1",
-  unread_only: true
+  action: "by_tags",
+  tags: ["api", "security"],
+  limit: 5
 }
 
-// 3. Mark as read
+// 3. Search by key pattern
 {
-  action: "mark_read",
-  agent_name: "bot1",
-  message_ids: [1, 2, 3]
+  action: "by_key",
+  key: "api/*",
+  limit: 10
 }
 ```
 
@@ -276,14 +274,16 @@ sqlew uses Levenshtein distance (≤2 edits) to detect common typos:
 | **add_decision_context** | action, key, rationale | alternatives_considered, tradeoffs, decided_by, related_task_id, related_constraint_id |
 | **list_decision_contexts** | action | decision_key, related_task_id, related_constraint_id, decided_by, limit, offset |
 
-### `message` Tool
+### `message` Tool ⚠️ DEPRECATED (v3.6.5)
 
-| Action | Required | Optional |
-|--------|----------|----------|
-| **send** | action, from_agent, msg_type, message | to_agent, priority, payload |
-| **get** | action, agent_name | unread_only, priority_filter, msg_type_filter, limit |
-| **mark_read** | action, agent_name, message_ids | - |
-| **send_batch** | action, messages | atomic |
+> **Note:** The messaging system was removed in v3.6.5. The `t_agent_messages` table has been dropped.
+
+~~| Action | Required | Optional |~~
+~~|--------|----------|----------|~~
+~~| **send** | action, from_agent, msg_type, message | to_agent, priority, payload |~~
+~~| **get** | action, agent_name | unread_only, priority_filter, msg_type_filter, limit |~~
+~~| **mark_read** | action, agent_name, message_ids | - |~~
+~~| **send_batch** | action, messages | atomic |~~
 
 ### `file` Tool
 
@@ -341,6 +341,16 @@ sqlew uses Levenshtein distance (≤2 edits) to detect common typos:
 | **watch_files** (v3.4.1) | action, task_id, action (watch/unwatch/list) | file_paths |
 | **watcher** | action | subaction (status/list_files/list_tasks/help) |
 
+### `suggest` Tool (v3.9.0)
+
+| Action | Required | Optional |
+|--------|----------|----------|
+| **by_key** | action, key | limit, min_score, layer |
+| **by_tags** | action, tags | limit, min_score, layer |
+| **by_context** | action | key, tags, layer, limit, min_score, priority |
+| **check_duplicate** | action, key | tags, layer, min_score |
+| **help** | action | - |
+
 ---
 
 ## Search Actions Decision Tree
@@ -883,6 +893,137 @@ This returns:
 
 ---
 
+## Decision Intelligence System (v3.9.0)
+
+### Overview
+
+The Decision Intelligence System provides automatic duplicate detection and smart suggestions when creating decisions. It uses a three-tier approach to handle different similarity levels.
+
+### Three-Tier Detection
+
+| Tier | Score Range | Behavior | Use Case |
+|------|-------------|----------|----------|
+| **Gentle Nudge** | 35-44 | Non-blocking warning in `duplicate_risk` | May be related, user decides |
+| **Hard Block** | 45-59 | Blocking error, requires resolution | Likely duplicate, needs review |
+| **Auto-Update** | 60+ | Transparent update of existing decision | Clearly same decision |
+
+### Similarity Scoring
+
+**Total Score: 0-100 points**
+
+| Factor | Max Points | Calculation |
+|--------|------------|-------------|
+| Tag overlap | 40 | 10 per matching tag (max 4) |
+| Layer match | 25 | Same layer = 25, different = 0 |
+| Key similarity | 20 | Pattern + Levenshtein distance |
+| Recency | 10 | <30 days = 10, decay over time |
+| Priority | 5 | Critical = 5, High = 4, etc. |
+
+### Using the suggest Tool
+
+```javascript
+// Find by key pattern
+{
+  action: "by_key",
+  key: "api/*/latency",
+  limit: 5,
+  min_score: 30
+}
+
+// Find by tag similarity
+{
+  action: "by_tags",
+  tags: ["performance", "api"],
+  limit: 5
+}
+
+// Combined search
+{
+  action: "by_context",
+  key: "api/*",
+  tags: ["performance"],
+  layer: "infrastructure",
+  limit: 5
+}
+
+// Pre-creation duplicate check
+{
+  action: "check_duplicate",
+  key: "new-decision",
+  tags: ["tag1", "tag2"]
+}
+```
+
+### Auto-Trigger with Policies
+
+Enable automatic duplicate detection in policies:
+
+```javascript
+{
+  action: "create_policy",
+  name: "security-decisions",
+  defaults: {
+    layer: "cross-cutting",
+    tags: ["security"]
+  },
+  suggest_similar: 1,  // Enable auto-trigger
+  validation_rules: {
+    patterns: { key: "^security/" }
+  }
+}
+```
+
+When a decision matches this policy, suggestions are automatically triggered.
+
+### Bypass Mechanism
+
+Override duplicate detection when needed:
+
+```javascript
+{
+  action: "set",
+  key: "intentionally-similar",
+  value: "Different use case",
+  tags: ["same", "tags"],
+  ignore_suggest: true,  // Skip duplicate detection
+  ignore_reason: "Different use case - async tasks vs event bus"
+}
+```
+
+### Enhanced Response Fields (v3.9.0)
+
+**Tier 1 (Gentle Nudge):**
+```json
+{
+  "success": true,
+  "key": "new-decision",
+  "duplicate_risk": {
+    "severity": "MODERATE",
+    "max_score": 42,
+    "suggestions": [...]
+  }
+}
+```
+
+**Tier 3 (Auto-Update):**
+```json
+{
+  "success": true,
+  "auto_updated": true,
+  "requested_key": "similar-key",
+  "actual_key": "existing-key",
+  "similarity_score": 85,
+  "version": "1.0.1"
+}
+```
+
+### See Also
+
+- **[DECISION_INTELLIGENCE.md](DECISION_INTELLIGENCE.md)** - Comprehensive three-tier system guide
+- **[MIGRATION_GUIDE_V3.9.0.md](MIGRATION_GUIDE_V3.9.0.md)** - Migration instructions
+
+---
+
 ## Related Documentation
 
 - **[TOOL_SELECTION.md](TOOL_SELECTION.md)** - Choosing the right tool for your task
@@ -890,3 +1031,4 @@ This returns:
 - **[BEST_PRACTICES.md](BEST_PRACTICES.md)** - Common errors and best practices
 - **[ARCHITECTURE.md](ARCHITECTURE.md)** - Layer definitions and system architecture
 - **[AI_AGENT_GUIDE.md](AI_AGENT_GUIDE.md)** - Complete guide (original comprehensive version)
+- **[DECISION_INTELLIGENCE.md](DECISION_INTELLIGENCE.md)** - Decision Intelligence System (v3.9.0)

package/docs/TOOL_SELECTION.md

@@ -7,12 +7,12 @@
 | Tool | Use For | Don't Use For | Key Feature |
 |------|---------|---------------|-------------|
 | **decision** | Recording choices made | Future work, requirements | Version history tracking |
-| **message** | Agent communication | Permanent records, decisions | Priority-based delivery |
+| **suggest** (v3.9.0) | Finding similar decisions | Creating decisions | Three-tier duplicate detection |
 | **constraint** | Requirements & rules | Decisions, tasks | Category-based organization |
 | **task** | Work tracking (TODO) | Decisions, history | Auto-stale detection |
 | **file** | File change tracking | Code search, content | Layer-based organization |
 | **stats** | Metrics & cleanup | Data storage | Aggregated views |
-| **config** | Retention settings | Business logic | Auto-deletion control |
+| ~~**message**~~ | ~~Agent communication~~ | ~~Permanent records~~ | ⚠️ DEPRECATED v3.6.5 |
 
 ## Decision vs Constraint vs Task
 
@@ -62,6 +62,19 @@
 | **search_advanced** | Complex multi-filter, pagination, full-text |
 | **versions** | Version history of specific decision |
 
+## Suggest Tool Actions (v3.9.0)
+
+| Action | Use For |
+|--------|---------|
+| **by_key** | Pattern-based key search (e.g., `api/*/latency`) |
+| **by_tags** | Tag similarity scoring (Jaccard index) |
+| **by_context** | Multi-factor search (key + tags + layer) |
+| **check_duplicate** | Pre-creation validation to prevent duplicates |
+
+**When to use suggest vs search:**
+- Use **suggest** to find *similar* decisions before creating new ones
+- Use **search** actions to query *existing* decisions for information
+
 ---
 
 ## Related Documentation
@@ -70,3 +83,4 @@
 - [WORKFLOWS.md](WORKFLOWS.md) - Multi-step workflows
 - [BEST_PRACTICES.md](BEST_PRACTICES.md) - Common errors
 - [SHARED_CONCEPTS.md](SHARED_CONCEPTS.md) - Layers, enums, concepts
+- [DECISION_INTELLIGENCE.md](DECISION_INTELLIGENCE.md) - Three-tier duplicate detection (v3.9.0)

package/docs/WORKFLOWS.md

@@ -616,9 +616,172 @@ if (stats.total_messages > 1000) {
 
 ---
 
+## Workflow 5: Decision Intelligence & Duplicate Prevention (v3.9.0)
+
+**Scenario**: Agent maintains decision consistency using the three-tier duplicate detection system.
+
+### Step 1: Check for Existing Decisions Before Creating
+
+```javascript
+// 1. Search for related decisions by key pattern
+{
+  action: "by_key",
+  key: "api/*/authentication",
+  limit: 5,
+  min_score: 30
+}
+
+// 2. Check for duplicates by tags
+{
+  action: "by_tags",
+  tags: ["api", "security", "authentication"],
+  limit: 5
+}
+
+// 3. Pre-creation duplicate check
+{
+  action: "check_duplicate",
+  key: "api-authentication-jwt",
+  tags: ["api", "security", "jwt"]
+}
+```
+
+### Step 2: Handle Three-Tier Responses
+
+```javascript
+// Tier 1: Gentle Nudge (35-44 score)
+// Decision is created but with warnings
+{
+  action: "set",
+  key: "api-rate-limiting-v2",
+  value: "100 requests/minute for free tier",
+  layer: "infrastructure",
+  tags: ["api", "rate-limiting", "performance"]
+}
+
+// Response includes duplicate_risk:
+// {
+//   "success": true,
+//   "key": "api-rate-limiting-v2",
+//   "duplicate_risk": {
+//     "severity": "MODERATE",
+//     "max_score": 42,
+//     "suggestions": [{
+//       "key": "api-rate-limiting",
+//       "score": 42,
+//       "reasoning": "2 matching tags, same layer"
+//     }]
+//   }
+// }
+
+// Tier 2: Hard Block (45-59 score)
+// Must update existing or bypass
+{
+  action: "set",
+  key: "api-throttling",
+  value: "100 requests/minute for free tier",  // Nearly identical
+  layer: "infrastructure",
+  tags: ["api", "rate-limiting", "performance"],
+  // Option A: Update existing decision
+  // Option B: Bypass with reason
+  ignore_suggest: true,
+  ignore_reason: "Different use case - async queue vs real-time API"
+}
+
+// Tier 3: Auto-Update (60+ score)
+// Transparently updates existing decision
+{
+  action: "set",
+  key: "api-rate-limit-config",
+  value: "Updated: 150 requests/minute for free tier",
+  layer: "infrastructure",
+  tags: ["api", "rate-limiting", "performance"]
+}
+
+// Response shows auto-update:
+// {
+//   "success": true,
+//   "auto_updated": true,
+//   "requested_key": "api-rate-limit-config",
+//   "actual_key": "api-rate-limiting",
+//   "similarity_score": 85,
+//   "version": "1.0.1"
+// }
+```
+
+### Step 3: Policy-Based Auto-Triggering
+
+```javascript
+// 1. Create policy with suggestion enabled
+{
+  action: "create_policy",
+  name: "security-decisions",
+  defaults: {
+    layer: "cross-cutting",
+    tags: ["security"]
+  },
+  suggest_similar: 1,  // Enable auto-trigger
+  validation_rules: {
+    patterns: { key: "^security/" }
+  }
+}
+
+// 2. All security/* decisions now auto-check for duplicates
+{
+  action: "set",
+  key: "security/jwt-expiration",
+  value: "15 minute token expiration",
+  tags: ["security", "jwt", "authentication"]
+  // Auto-triggers duplicate detection!
+}
+
+// Response includes suggestions:
+// {
+//   "success": true,
+//   "key": "security/jwt-expiration",
+//   "suggestions": {
+//     "triggered_by": "security-decisions",
+//     "reason": "Policy has suggest_similar enabled",
+//     "suggestions": [...]
+//   }
+// }
+```
+
+### Step 4: Context-Aware Search
+
+```javascript
+// Hybrid search combining multiple factors
+{
+  action: "by_context",
+  key: "api/*",
+  tags: ["security", "performance"],
+  layer: "infrastructure",
+  priority: 3,
+  limit: 5
+}
+
+// Returns decisions matching:
+// - Key pattern: api/*
+// - Tags: security, performance
+// - Layer: infrastructure
+// - Priority: high (3)
+```
+
+### Token Efficiency
+
+**Suggest Tool Savings:**
+- Pattern search: ~50-100 tokens vs manual scanning
+- Duplicate detection: ~100 tokens vs creating duplicates
+- Auto-update: Eliminates error handling overhead
+
+**Best Practice**: Always use `check_duplicate` before `set` for high-value decisions.
+
+---
+
 ## Related Documentation
 
 - **[TOOL_SELECTION.md](TOOL_SELECTION.md)** - Choosing the right tool for your task
 - **[TOOL_REFERENCE.md](TOOL_REFERENCE.md)** - Complete parameter reference
 - **[BEST_PRACTICES.md](BEST_PRACTICES.md)** - Common errors and best practices
+- **[DECISION_INTELLIGENCE.md](DECISION_INTELLIGENCE.md)** - Three-tier system details (v3.9.0)
 - **[AI_AGENT_GUIDE.md](AI_AGENT_GUIDE.md)** - Complete guide (original comprehensive version)