sqlew 4.0.5 → 4.1.0

package/docs/BEST_PRACTICES.md

@@ -1,168 +0,0 @@
-# Best Practices & Troubleshooting
-
-## Critical Rules
-
-### 1. Always Include `action` Parameter
-**#1 cause of errors**
-
-```javascript
-❌ { key: "some_key", value: "some value" }
-✅ { action: "set", key: "some_key", value: "some value" }
-```
-
-### 2. Store WHY in Decisions, Not WHAT
-
-**Organizational memory gap:**
-- Git history → WHAT changed
-- Code comments → HOW it works
-- **Decisions** → WHY it was changed (reasoning, trade-offs)
-- **Tasks** → WHAT needs to be done (work status)
-
-### Good vs Bad Examples
-
-**✅ GOOD - Store WHY:**
-- "Chose JWT because: stateless scales, mobile caching, distributed auth. Trade-off: needs blacklist."
-- "Nested transaction bug: setDecision wraps, batch wraps → extract internal helper."
-- "Duration must NOT be in Loom - breaks architectural separation."
-
-**❌ BAD - Don't store WHAT:**
-- "v3.0.2 testing complete. All tools verified working." → Use tasks
-- "Refactoring complete. Query builder created." → Use git commits
-- "PASS - All tests passing." → Use CI/CD logs
-- "Doc restructure complete." → Use git commits
-
----
-
-## Parameter Validation Patterns
-
-**NEW in dev branch**: sqlew provides comprehensive parameter validation with helpful error messages.
-
-### How Validation Helps
-
-1. **Catch Typos Early** - Get instant feedback on misspelled parameter names
-2. **Learn by Example** - Every error includes a working example
-3. **Clear Requirements** - Know exactly which parameters are required vs optional
-4. **Visual Markers** - Help responses show 🔴 REQUIRED and ⚪ OPTIONAL
-
-### Common Validation Errors and Fixes
-
-**Missing Required Parameter:**
-```javascript
-// ❌ ERROR: Missing required parameter 'value'
-{ action: "set", key: "auth_method" }
-
-// ✅ FIX: Add required parameter
-{ action: "set", key: "auth_method", value: "JWT authentication chosen" }
-```
-
-**Typo in Parameter Name:**
-```javascript
-// ❌ ERROR: Unknown parameter 'tgas' (did you mean 'tags'?)
-{ action: "set", key: "api/v2", value: "New API", tgas: ["api"] }
-
-// ✅ FIX: Correct the typo
-{ action: "set", key: "api/v2", value: "New API", tags: ["api"] }
-```
-
-**Wrong Action Name:**
-```javascript
-// ❌ ERROR: Unknown action 'create_task' (did you mean 'create'?)
-{ action: "create_task", title: "Implement auth" }
-
-// ✅ FIX: Use correct action name
-{ action: "create", title: "Implement auth" }
-```
-
-**Parameters from Wrong Action:**
-```javascript
-// ❌ ERROR: Unknown parameter 'task_id' for action 'create'
-{ action: "create", task_id: 5, title: "New task" }
-
-// ✅ FIX: Use 'update' action instead
-{ action: "update", task_id: 5, title: "Updated task" }
-```
-
-### Reading Validation Error Messages
-
-Error messages provide structured guidance:
-
-```json
-{
-  "error": "Missing required parameter for action 'set': value",
-  "missing_params": ["value"],              // What you're missing
-  "required_params": ["key", "value"],      // All required fields
-  "optional_params": ["agent", "layer"],    // All optional fields
-  "you_provided": ["key", "layer"],         // What you actually sent
-  "example": { ... },                       // Working example
-  "hint": "Use 'quick_set' for simpler..."  // Helpful tip
-}
-```
-
----
-
-## Common Errors
-
-| Error | Cause | Solution |
-|-------|-------|----------|
-| "Unknown action: undefined" | Missing `action` | Always include `action` parameter |
-| "Missing required parameter" | Omitted required field | Check `required_params` in error message |
-| "Unknown parameter" | Typo or wrong action | Check `did_you_mean` suggestions |
-| "Parameter 'value' is required" | Using `defaults` with templates | Pass parameters directly, not in `defaults` |
-| "Invalid layer" | Wrong layer name | Use: presentation, business, data, infrastructure, cross-cutting |
-| "Invalid status" | Wrong status | Use: active, deprecated, draft |
-| "Batch limit exceeded" | >50 items | Split into batches of ≤50 |
-
----
-
-## Best Practices
-
-1. **Always use `action` parameter** - Required in ALL calls
-2. **Use `atomic: false` for batches** - Avoid transaction failures
-3. **Choose right search action** - `list` (simple), `search_tags` (tag-focused), `search_advanced` (complex)
-4. **Use templates** - For repeated decision patterns
-5. **Meaningful tags** - Descriptive, consistent naming
-6. **Always specify `layer`** - Organizes architectural concerns
-7. **Use `has_updates`** - Check before fetching (95% token savings)
-8. **Handle errors** - Check for `error` field in responses
-9. **Constraints for requirements** - Use `constraint` for rules, `decision` for choices
-10. **Clean up regularly** - Use `clear` action or auto-cleanup config
-
-### Decision Intelligence Best Practices (v3.9.0)
-
-11. **Use `check_duplicate` before `set`** - Prevent redundant decisions
-12. **Enable policy auto-triggering** - Set `suggest_similar: 1` for consistent checks
-13. **Handle three-tier responses** - Review gentle nudges, resolve hard blocks, trust auto-updates
-14. **Provide `ignore_reason`** - Always document why bypassing duplicate detection
-15. **Use consistent tag taxonomy** - Better similarity scoring with consistent tags
-16. **Use descriptive keys** - Pattern-based keys (`api/users/auth`) enable better matching
-
----
-
-## Performance Tips
-
-**Token Efficiency:**
-- `has_updates` before fetching (95% savings)
-- Metadata-only task queries (70% smaller)
-- Batch operations (52% reduction)
-
-**Database Health:**
-- Monitor with `db_stats`
-- Enable auto-cleanup
-- Archive completed tasks
-
-**Multi-Agent:**
-- Priority levels for messages
-- Link tasks to decisions
-- Update status promptly
-
----
-
-## Related Documentation
-
-- [TOOL_SELECTION.md](TOOL_SELECTION.md) - Tool selection guide
-- [TOOL_REFERENCE.md](TOOL_REFERENCE.md) - Parameter reference
-- [WORKFLOWS.md](WORKFLOWS.md) - Multi-step workflows
-- [SHARED_CONCEPTS.md](SHARED_CONCEPTS.md) - Layers, enums, concepts
-- [DECISION_INTELLIGENCE.md](DECISION_INTELLIGENCE.md) - Three-tier duplicate detection (v3.9.0)
-
-**Tip**: Use `{action: "help"}` for any tool's detailed documentation.

package/docs/CONSTRAINT_INTELLIGENCE.md

@@ -1,339 +0,0 @@
-# Constraint Intelligence System (v4.0.0)
-
-**Status:** Production Ready
-**Release Date:** 2025-11-27
-
----
-
-## Overview
-
-The Constraint Intelligence System provides duplicate detection and similarity-based suggestions for architectural constraints. It complements the [Decision Intelligence System](DECISION_INTELLIGENCE.md) with constraint-specific scoring and workflows.
-
-### Key Features
-
-- **Duplicate Detection**: Two-phase check (exact match, then similarity)
-- **Hybrid Scoring**: Combines text, tags, layer, recency, and priority
-- **Constraint-Specific Scoring**: Optimized for rule-based content
-- **Pre-Creation Validation**: Check before adding new constraints
-
----
-
-## Accessing Constraint Suggestions
-
-Use `target: "constraint"` with the suggest tool:
-
-```javascript
-// Default is target: "decision"
-suggest({
-  action: "by_tags",
-  target: "constraint",  // Required for constraint suggestions
-  tags: ["api", "performance"]
-})
-```
-
----
-
-## Scoring Algorithm
-
-### Components (100 points max)
-
-| Component | Max Points | Description |
-|-----------|-----------|-------------|
-| Tag overlap | 40 | 10 per matching tag (max 4 tags) |
-| Layer match | 25 | Exact layer match |
-| Text similarity | 20 | Levenshtein distance calculation |
-| Recency | 10 | Recently updated constraints score higher |
-| Priority | 5 | Higher priority constraints score higher |
-
-### Recency Tiers
-
-| Age | Points |
-|-----|--------|
-| < 30 days | 10 |
-| 30-90 days | 5 |
-| 90-180 days | 2 |
-| > 180 days | 0 |
-
-### Priority Scores
-
-| Priority | Level | Points |
-|----------|-------|--------|
-| 4 | Critical | 5 |
-| 3 | High | 4 |
-| 2 | Medium | 3 |
-| 1 | Low | 2 |
-
-### Thresholds
-
-| Threshold | Value | Description |
-|-----------|-------|-------------|
-| Default min_score | 30 | Minimum score for suggestions |
-| Duplicate threshold | 70 | Score triggering duplicate warning |
-
----
-
-## Actions
-
-### by_key - Text Pattern Search
-
-Find similar constraints by text pattern (alias for by_context with text only).
-
-```javascript
-suggest({
-  action: "by_key",
-  target: "constraint",
-  text: "API response time",      // Required: text to match
-  layer: "business",              // Optional: filter by layer
-  limit: 5,                       // Optional: max results (default: 5)
-  min_score: 30                   // Optional: minimum score (default: 30)
-})
-```
-
-### by_tags - Tag-Based Discovery
-
-Find constraints by tag overlap (fast).
-
-```javascript
-suggest({
-  action: "by_tags",
-  target: "constraint",
-  tags: ["api", "performance"],   // Required: tags to match
-  layer: "business",              // Optional: filter by layer
-  limit: 5,                       // Optional
-  min_score: 30                   // Optional
-})
-```
-
-### by_context - Hybrid Search
-
-Comprehensive search combining text, tags, layer, and priority.
-
-```javascript
-suggest({
-  action: "by_context",
-  target: "constraint",
-  text: "database query",         // Optional
-  tags: ["sql"],                  // Optional
-  layer: "data",                  // Optional (also used for scoring)
-  priority: 3,                    // Optional (for scoring)
-  limit: 5,                       // Optional
-  min_score: 30                   // Optional
-})
-
-// Note: At least one of text, tags, or layer required
-```
-
-### check_duplicate - Pre-Creation Check
-
-Two-phase duplicate detection before creating constraints.
-
-```javascript
-suggest({
-  action: "check_duplicate",
-  target: "constraint",
-  text: "API response time must be under 100ms",  // Required
-  category: "performance"                          // Optional: filter by category
-})
-
-// Response:
-{
-  is_duplicate: false,
-  match_type: "similar",        // "exact" | "similar" | "none"
-  existing: null,               // Existing constraint (if exact)
-  similar_constraints: [...],   // Array of similar constraints
-  score: 65,                    // Similarity score of top match
-  recommendation: "Similar constraint found..."
-}
-```
-
----
-
-## Workflows
-
-### Before Creating a Constraint
-
-```javascript
-// Step 1: Check for duplicates
-const result = await suggest({
-  action: "check_duplicate",
-  target: "constraint",
-  text: "API response time must be under 100ms"
-});
-
-// Step 2: Handle result
-if (result.is_duplicate) {
-  // Exact match exists - update instead
-  console.log("Constraint exists:", result.existing);
-} else if (result.match_type === "similar") {
-  // Review similar constraints
-  console.log("Similar constraints:", result.similar_constraints);
-  // Decide: create new or update existing
-} else {
-  // Safe to create new constraint
-  constraint({ action: "add", ... });
-}
-```
-
-### Finding Related Constraints
-
-```javascript
-// Fast: Tag-based discovery
-const byTags = await suggest({
-  action: "by_tags",
-  target: "constraint",
-  tags: ["security", "authentication"]
-});
-
-// Comprehensive: Hybrid search
-const byContext = await suggest({
-  action: "by_context",
-  target: "constraint",
-  text: "password policy",
-  tags: ["security"],
-  layer: "business"
-});
-
-// Review score_breakdown to understand relevance
-byContext.suggestions.forEach(s => {
-  console.log(s.constraint_text, s.score_breakdown);
-});
-```
-
----
-
-## Response Structure
-
-### Suggestion Object
-
-```typescript
-{
-  id: number,                    // Constraint ID
-  constraint_text: string,       // Full constraint text
-  category: string,              // Constraint category
-  score: number,                 // Total relevance score (0-100)
-  reason: string,                // Human-readable explanation
-  score_breakdown: {
-    tag_overlap: number,
-    layer_match: number,
-    text_similarity: number,
-    recency: number,
-    priority: number
-  },
-  layer?: string,                // Assigned layer
-  tags?: string[],               // Associated tags
-  ts?: number                    // Last updated timestamp
-}
-```
-
----
-
-## Comparison: Decision vs Constraint Intelligence
-
-| Feature | Decision Intelligence | Constraint Intelligence |
-|---------|----------------------|------------------------|
-| Target | `"decision"` (default) | `"constraint"` |
-| Scoring max | 100 points | 100 points |
-| Key/Text weight | 40 points | 20 points |
-| Tag weight | 30 points | 40 points |
-| Layer weight | 15 points | 25 points |
-| Recency | - | 10 points |
-| Priority | - | 5 points |
-| Auto-update tier | Yes (60+) | No |
-| Hard block tier | Yes (45-59) | No |
-| Duplicate threshold | 60+ auto-update | 70 warning |
-
-### Why Different Scoring?
-
-**Decisions** focus on key patterns and value similarity (choices already made).
-
-**Constraints** focus on tag overlap and layer match (rules that must be enforced).
-
----
-
-## Best Practices
-
-### 1. Use Consistent Tags
-
-```javascript
-// Good: Consistent taxonomy
-tags: ["api", "performance", "latency"]
-
-// Avoid: Inconsistent naming
-tags: ["API", "perf", "response-time"]
-```
-
-### 2. Check Before Creating
-
-```javascript
-// Always check for duplicates
-suggest({
-  action: "check_duplicate",
-  target: "constraint",
-  text: "Your constraint text"
-})
-```
-
-### 3. Use by_tags for Discovery
-
-```javascript
-// Fast discovery of related constraints
-suggest({
-  action: "by_tags",
-  target: "constraint",
-  tags: ["security"]
-})
-```
-
-### 4. Review score_breakdown
-
-```javascript
-// Understand why a constraint was suggested
-suggestions.forEach(s => {
-  if (s.score_breakdown.tag_overlap > 30) {
-    // High tag overlap - likely related
-  }
-  if (s.score_breakdown.layer_match === 25) {
-    // Same layer - consider consolidation
-  }
-});
-```
-
----
-
-## Configuration
-
-**File:** `src/constants.ts`
-
-```typescript
-// Constraint suggestion defaults
-export const CONSTRAINT_SUGGEST_DEFAULTS = {
-  MIN_SCORE: 30,
-  LIMIT: 5,
-  DUPLICATE_THRESHOLD: 70,
-} as const;
-
-// Score weights
-export const CONSTRAINT_SCORE_WEIGHTS = {
-  TAG_OVERLAP: 10,      // Per matching tag (max 40)
-  LAYER_MATCH: 25,      // Exact match
-  TEXT_SIMILARITY: 20,  // Max based on Levenshtein
-  RECENCY_MAX: 10,      // Based on age tiers
-  PRIORITY_MAX: 5,      // Based on priority level
-} as const;
-```
-
----
-
-## Related Documentation
-
-| Document | Content |
-|----------|---------|
-| [DECISION_INTELLIGENCE.md](DECISION_INTELLIGENCE.md) | Decision duplicate detection |
-| [TOOL_REFERENCE.md](TOOL_REFERENCE.md) | Complete parameter reference |
-| [SHARED_CONCEPTS.md](SHARED_CONCEPTS.md) | Layers, priorities, tags |
-| [TOOL_SELECTION.md](TOOL_SELECTION.md) | Constraint vs Decision selection |
-
----
-
-**Version:** 4.0.0
-**Last Updated:** 2025-11-27