sqlew 4.1.2 → 4.3.1

package/assets/claude-md-snippets/plan-mode-integration.md

@@ -1,24 +1,50 @@
 ## Plan Mode Integration
 
+### REQUIRED: Decision & Constraint Recording
+
+**When writing plans, you MUST include the following sections:**
+
+1. **📌 Decisions** - Technology choices, architecture patterns, implementation approaches
+2. **🚫 Constraints** - Rules, restrictions, limitations, prohibited patterns from user requirements
+
+**IMPORTANT**: If the user mentions any restrictions, prohibitions, or "don't use X", these MUST be recorded as 🚫 Constraints.
+
+---
+
+**Decision format (REQUIRED for any technical choice):**
+
+```markdown
+### 📌 Decision: [key/path]
+- **Value**: Description of the decision
+- **Layer**: presentation | business | data | infrastructure | cross-cutting
+- **Tags**: tag1, tag2 (optional)
+```
+
+**Constraint format (REQUIRED when user specifies restrictions):**
+
+```markdown
+### 🚫 Constraint: [category]
+- **Rule**: Description of the constraint
+- **Priority**: critical | high | medium | low
+- **Tags**: tag1, tag2 (optional)
+```
+
+Category options: `architecture` | `security` | `code-style` | `performance`
+
+---
+
 ### With Claude Code Hooks (Recommended)
 
-If you've run `sqlew init --hooks`, sqlew integration is **fully automatic**:
+If you've run `sqlew --hooks`, sqlew integration is **fully automatic**:
+
+- 📌/🚫 patterns are auto-detected and registered as draft on ExitPlanMode
 - Related decisions are auto-suggested before Task execution
-- Plan files are auto-tracked with unique IDs
 - Decisions are auto-saved when code is edited
-- Status updates to `in_review` when all tasks complete
-- Status updates to `implemented` after git merge/rebase
 
 ### Manual Usage (Without Hooks)
 
-When `<system-reminder>Plan mode is active</system-reminder>` appears:
-
 **Research Phase:**
 - `/sqlew search for <topic>` - find related decisions
-- `/sqlew show remaining tasks` - check active tasks
 
 **Final Plan Phase:**
 - `/sqlew record <decision>` - record key architectural decisions
-- `/sqlew create task <description>` - create implementation tasks
-
-**Quick Reference**: `.claude/skills/sqw-plan-guidance/SKILL.md`

package/assets/config.example.toml

@@ -1,282 +1,120 @@
-# sqlew Configuration File
-# Copy this file to .sqlew/config.toml and customize as needed
-#
-# Priority: CLI arguments > config.toml > database m_config > defaults
-# Documentation: docs/CONFIGURATION.md
-
-# ============================================================================
-# Database Settings
-# ============================================================================
-[database]
-# SQLite Configuration (default, local development)
-# Database file path (relative to project root or absolute)
-# Default: ".sqlew/sqlew.db"
-# path = ".sqlew/custom.db"
-# path = "/absolute/path/to/database.db"
-
-# PostgreSQL/MySQL/MariaDB Configuration (multi-agent production)
-# Uncomment and configure for remote database access
-# type = "postgres"  # or "mysql" (also works with MariaDB 10.5+)
-
-# Connection settings (required for postgres/mysql/mariadb)
-# IMPORTANT: Database must already exist! User does NOT need CREATE DATABASE privilege.
-# [database.connection]
-# host = "localhost"
-# port = 5432  # PostgreSQL: 5432, MySQL/MariaDB: 3306
-# database = "sqlew"  # Must be created beforehand!
-
-# Authentication settings (required for postgres/mysql/mariadb)
-# Required user privileges: SELECT, INSERT, UPDATE, DELETE, CREATE, ALTER, INDEX, DROP, REFERENCES
-# [database.auth]
-# type = "direct"  # Options: "direct", "ssh", "aws-iam", "gcp-iam"
-# user = "postgres"  # or mysql_user, etc.
-# password = "your-password"
-
-# SSL/TLS Configuration (optional, for encrypted connections)
-# [database.auth.ssl]
-# ca = "/path/to/ca-cert.pem"  # or inline certificate content
-# cert = "/path/to/client-cert.pem"  # for mutual TLS
-# key = "/path/to/client-key.pem"  # for mutual TLS
-# rejectUnauthorized = true  # set to false for self-signed certs (not recommended for production)
-
-# SSH Tunnel Configuration (when type = "ssh")
-# Used for bastion host / jump server access
-# [database.auth.ssh]
-# host = "bastion.example.com"
-# port = 22
-# username = "deploy"
-# privateKeyPath = "/home/user/.ssh/id_rsa"  # or use password
-# password = "ssh-password"  # alternative to privateKeyPath
-# passphrase = "key-passphrase"  # if private key is encrypted
-# timeout = 30000  # SSH connection timeout in ms
-# keepalive = true
-# keepaliveInterval = 10000
-# localPort = 50000  # auto-allocated from 50000-60000 if not specified
-
-# ============================================================================
-# Auto-Deletion Settings
-# ============================================================================
-[autodelete]
-# Skip weekends when calculating retention periods
-# When true: 24 hours on Monday = previous Friday (skips Sat/Sun)
-# When false: 24 hours = exactly 24 hours ago
-# Default: false
-ignore_weekend = false
-
-# Message retention period in hours (1-720)
-# Messages older than this are automatically deleted
-# Default: 24 (1 day)
-message_hours = 24
-
-# File change history retention in days (1-365)
-# File changes older than this are automatically deleted
-# Default: 7 (1 week)
-file_history_days = 7
-
-# ============================================================================
-# Debug Logging Settings (v3.5.4)
-# ============================================================================
-[debug]
-# Debug log file path (optional)
-# When set, enables detailed debug logging for troubleshooting
-# Environment variable SQLEW_DEBUG takes precedence over this setting
-# Default: not set (logging disabled)
-# log_path = "/home/user/.sqlew/debug.log"
-# log_path = ".sqlew/debug.log"
-
-# Log level for debug output (case-insensitive)
-# Levels: "error", "warn", "info", "debug"
-# error: Only errors
-# warn: Errors and warnings
-# info: Errors, warnings, and informational messages
-# debug: All messages including debug details
-# Default: "info"
-# log_level = "info"
-
-# ============================================================================
-# Task Management Settings
-# ============================================================================
-[tasks]
-# Auto-archive done tasks after N days (1-365)
-# Tasks in 'done' status older than this are moved to 'archived'
-# Keeps task list clean while preserving history
-# Default: 2 (48 hours)
-auto_archive_done_days = 2
-
-# Stale detection threshold for 'in_progress' tasks (hours, 1-168)
-# Tasks stuck in 'in_progress' longer than this → move to 'waiting_review'
-# Helps recover from interrupted AI sessions
-# Default: 2 (2 hours)
-stale_hours_in_progress = 2
-
-# Stale detection threshold for 'waiting_review' tasks (hours, 1-720)
-# Tasks stuck in 'waiting_review' longer than this → move back to 'todo'
-# Prevents abandoned reviews from blocking workflow
-# Default: 24 (1 day)
-stale_hours_waiting_review = 24
-
-# Enable automatic stale detection
-# When true: Runs stale detection on startup and before task operations
-# When false: Stale detection disabled (manual only)
-# Default: true
-auto_stale_enabled = true
-
-# ============================================================================
-# VCS-Aware Auto-Complete Settings (v3.5.2)
-# ============================================================================
-[vcs]
-# Auto-complete tasks when files are staged (git add)
-# When true: waiting_review → done when files are staged
-# When false: Manual task completion required
-# Default: true
-git_auto_complete_on_stage = true
-
-# Auto-archive tasks when files are committed (git commit)
-# When true: done → archived when files are committed
-# When false: Manual task archiving required
-# Default: true
-git_auto_archive_on_commit = true
-
-# Require ALL watched files to be staged for auto-completion
-# When true: All files must be staged to trigger waiting_review → done
-# When false: At least one file staged is sufficient
-# Default: true
-require_all_files_staged = true
-
-# Require ALL watched files to be committed for auto-archiving
-# When true: All files must be committed to trigger done → archived
-# When false: At least one file committed is sufficient
-# Default: true
-require_all_files_committed_for_archive = true
-
-# ============================================================================
-# Specialized Agents Settings
-# ============================================================================
-[agents]
-# Which specialized agents to enable for your project
-# Set to false to skip agents you don't need (reduces token consumption)
-# Install by manually copying files from assets/sample-agents/ to ~/.claude/agents/
-# Note: Agents are only loaded into Claude Code conversations, not the MCP server
-
-# Scrum Master: Multi-agent coordination, task management, sprint planning
-# Token cost: ~12KB per conversation when loaded in Claude Code
-# Use when: Coordinating complex features, managing dependencies, tracking progress
-# Default: true
-scrum_master = true
-
-# Researcher: Query decisions, analyze patterns, investigate context
-# Token cost: ~14KB per conversation when loaded in Claude Code
-# Use when: Understanding past decisions, onboarding new members, sprint retrospectives
-# Default: true
-researcher = true
-
-# Architect: Document decisions, enforce constraints, maintain standards
-# Token cost: ~20KB per conversation when loaded in Claude Code
-# Use when: Making architectural choices, establishing rules, validating compliance
-# Default: true
-architect = true
-
-# Example: Minimal installation (only Scrum Master for task management)
-# [agents]
-# scrum_master = true
-# researcher = false
-# architect = false
-
-# Token Impact Examples:
-# - All 3 agents: ~46KB loaded per conversation (scrum 12KB + researcher 14KB + architect 20KB)
-# - Scrum + Architect: ~32KB (30% reduction)
-# - Scrum only: ~12KB (74% reduction)
-
-
-# ============================================================================
-# Slash Commands Settings
-# ============================================================================
-[commands]
-# Which slash commands to install on server startup
-# Set to false to skip commands you don't need
-
-# /sqlew: Unified natural language interface for decisions and tasks
-# Usage: /sqlew <what you want to do>
-# Examples:
-#   /sqlew show remaining tasks
-#   /sqlew search for auth decisions
-#   /sqlew record that we use PostgreSQL 15
-# Default: true
-sqlew = true
-
-# ============================================================================
-# Example Configurations
-# ============================================================================
-
-# Example 1: PostgreSQL with Direct Authentication + SSL
-# [database]
-# type = "postgres"
-# [database.connection]
-# host = "db.example.com"
-# port = 5432
-# database = "sqlew_production"
-# [database.auth]
-# type = "direct"
-# user = "postgres"
-# password = "secure-password"
-# [database.auth.ssl]
-# ca = "/path/to/ca-cert.pem"
-# rejectUnauthorized = true
-
-# Example 2: PostgreSQL through SSH Tunnel
-# [database]
-# type = "postgres"
-# [database.connection]
-# host = "db.internal.example.com"
-# port = 5432
-# database = "sqlew_production"
-# [database.auth]
-# type = "ssh"
-# user = "postgres"
-# password = "db-password"
-# [database.auth.ssh]
-# host = "bastion.example.com"
-# username = "deploy"
-# privateKeyPath = "/home/user/.ssh/id_rsa"
-
-# Example 3: MySQL with SSL and SSH
-# [database]
-# type = "mysql"
-# [database.connection]
-# host = "mysql.internal.example.com"
-# port = 3306
-# database = "sqlew_db"
-# [database.auth]
-# type = "ssh"
-# user = "mysql_user"
-# password = "db-password"
-# [database.auth.ssl]
-# ca = "-----BEGIN CERTIFICATE-----\nMIIE...\n-----END CERTIFICATE-----"
-# rejectUnauthorized = true
-# [database.auth.ssh]
-# host = "jump.example.com"
-# port = 22
-# username = "deploy"
-# privateKeyPath = "/home/user/.ssh/deploy_key"
-# passphrase = "key-passphrase"
-# localPort = 53306
-
-# Aggressive cleanup (development)
-# [autodelete]
-# message_hours = 1
-# file_history_days = 1
-# [tasks]
-# auto_archive_done_days = 1
-
-# Conservative cleanup (production)
-# [autodelete]
-# message_hours = 168  # 7 days
-# file_history_days = 30
-# [tasks]
-# auto_archive_done_days = 7
-
-# Weekend-aware workflow (for developers)
-# [autodelete]
-# ignore_weekend = true
-# message_hours = 48
-# file_history_days = 14
+# sqlew Configuration File
+# Copy this file to .sqlew/config.toml and customize as needed
+#
+# Priority: CLI arguments > config.toml > database m_config > defaults
+# Documentation: docs/CONFIGURATION.md
+
+# ============================================================================
+# Database Settings
+# ============================================================================
+[database]
+# SQLite Configuration (default, local development)
+# Database file path (relative to project root or absolute)
+# Default: ".sqlew/sqlew.db"
+# path = ".sqlew/custom.db"
+# path = "/absolute/path/to/database.db"
+
+# PostgreSQL/MySQL/MariaDB Configuration (multi-agent production)
+# Uncomment and configure for remote database access
+# type = "postgres"  # or "mysql" (also works with MariaDB 10.5+)
+
+# Connection settings (required for postgres/mysql/mariadb)
+# IMPORTANT: Database must already exist! User does NOT need CREATE DATABASE privilege.
+# [database.connection]
+# host = "localhost"
+# port = 5432  # PostgreSQL: 5432, MySQL/MariaDB: 3306
+# database = "sqlew"  # Must be created beforehand!
+
+# Authentication settings (required for postgres/mysql/mariadb)
+# Required user privileges: SELECT, INSERT, UPDATE, DELETE, CREATE, ALTER, INDEX, DROP, REFERENCES
+# [database.auth]
+# user = "postgres"  # or mysql_user, etc.
+# password = "your-password"
+
+
+# ============================================================================
+# Debug Logging Settings (v3.5.4)
+# ============================================================================
+[debug]
+# Debug log file path (optional)
+# When set, enables detailed debug logging for troubleshooting
+# Environment variable SQLEW_DEBUG takes precedence over this setting
+# Default: not set (logging disabled)
+# log_path = "/home/user/.sqlew/debug.log"
+# log_path = ".sqlew/debug.log"
+
+# Log level for debug output (case-insensitive)
+# Levels: "error", "warn", "info", "debug"
+# error: Only errors
+# warn: Errors and warnings
+# info: Errors, warnings, and informational messages
+# debug: All messages including debug details
+# Default: "info"
+# log_level = "info"
+
+
+# ============================================================================
+# Specialized Agents Settings (DEPRECATED)
+# ============================================================================
+[agents]
+# DEPRECATED: With Claude Opus 4.5's improved capabilities, specialized agents
+# are no longer necessary. The base model now handles coordination, research,
+# and architectural decisions effectively without additional agent overhead.
+#
+# These settings are preserved for backward compatibility but all agents are
+# disabled by default. Will be removed in v5.0.
+
+# Scrum Master: Multi-agent coordination (DEPRECATED)
+# Default: false
+scrum_master = false
+
+# Researcher: Query decisions, analyze patterns (DEPRECATED)
+# Default: false
+researcher = false
+
+# Architect: Document decisions, enforce constraints (DEPRECATED)
+# Default: false
+architect = false
+
+
+# ============================================================================
+# Slash Commands Settings
+# ============================================================================
+[commands]
+# Which slash commands to install on server startup
+# Set to false to skip commands you don't need
+
+# /sqlew: Unified natural language interface for decisions and tasks
+# Usage: /sqlew <what you want to do>
+# Examples:
+#   /sqlew show remaining tasks
+#   /sqlew search for auth decisions
+#   /sqlew record that we use PostgreSQL 15
+# Default: true
+sqlew = true
+
+# ============================================================================
+# Example Configurations
+# ============================================================================
+
+# Example 1: PostgreSQL with SSL
+# [database]
+# type = "postgres"
+# [database.connection]
+# host = "db.example.com"
+# port = 5432
+# database = "sqlew_production"
+# [database.auth]
+# user = "postgres"
+# password = "secure-password"
+
+# Example 2: MySQL/MariaDB
+# [database]
+# type = "mysql"
+# [database.connection]
+# host = "mysql.example.com"
+# port = 3306
+# database = "sqlew_db"
+# [database.auth]
+# user = "mysql_user"
+# password = "db-password"

package/assets/sample-skills/sqlew-decision-format/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: sqlew-decision-format
+description: |
+  Format guide for recording decisions and constraints in plan mode.
+  Auto-injected during plan creation to encourage structured documentation.
+  Auto-detected and registered as draft on ExitPlanMode.
+---
+
+## Plan Mode: Decision & Constraint Recording
+
+When including decisions or constraints in your plan, use the following format.
+They will be auto-detected on ExitPlanMode and registered as draft in sqlew.
+
+---
+
+### 📌 Decision: [hierarchical/key]
+
+Record decisions using this format:
+
+```markdown
+### 📌 Decision: [key/path]
+- **Value**: Description of the decision
+- **Layer**: presentation | business | data | infrastructure | cross-cutting
+- **Tags**: tag1, tag2 (optional)
+```
+
+**Examples:**
+
+### 📌 Decision: frontend/framework
+- **Value**: Use React 18
+- **Layer**: presentation
+- **Tags**: react, frontend
+
+### 📌 Decision: database/orm
+- **Value**: Adopt Prisma
+- **Layer**: data
+- **Tags**: prisma, orm, typescript
+
+---
+
+### 🚫 Constraint: [category]
+
+Record constraints using this format:
+
+```markdown
+### 🚫 Constraint: [category]
+- **Rule**: Description of the constraint
+- **Priority**: critical | high | medium | low
+- **Tags**: tag1, tag2 (optional)
+```
+
+**Category options:** `architecture` | `security` | `code-style` | `performance`
+
+**Examples:**
+
+### 🚫 Constraint: code-style
+- **Rule**: No inline styles, use CSS Modules
+- **Priority**: medium
+- **Tags**: css, styling
+
+### 🚫 Constraint: security
+- **Rule**: No hardcoded API keys, use environment variables
+- **Priority**: critical
+- **Tags**: security, env
+
+---
+
+## Automatic Processing Flow
+
+1. **During Planning**: Write Decision/Constraint in the format above
+2. **On ExitPlanMode**: Auto-detected → registered as draft/inactive
+3. **On Implementation File Edit**: Auto-promoted to active
+4. **Check command**: `mcp__sqlew__decision({ action: "list", status: "draft" })`

package/dist/cli/hooks/check-completion.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"check-completion.d.ts","sourceRoot":"","sources":["../../../src/cli/hooks/check-completion.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAyBH;;;;;GAKG;AACH,wBAAsB,sBAAsB,IAAI,OAAO,CAAC,IAAI,CAAC,CA4E5D"}
+{"version":3,"file":"check-completion.d.ts","sourceRoot":"","sources":["../../../src/cli/hooks/check-completion.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAmHH;;;;;GAKG;AACH,wBAAsB,sBAAsB,IAAI,OAAO,CAAC,IAAI,CAAC,CA4F5D"}

package/dist/cli/hooks/check-completion.js

@@ -10,9 +10,10 @@
  * @since v4.1.0
  */
 import { readStdinJson, sendContinue, areAllTodosCompleted, getProjectPath } from './stdin-parser.js';
-import { loadCurrentPlan } from '../../config/global-config.js';
+import { loadCurrentPlan, loadPlanTomlCache, savePlanTomlCache, } from '../../config/global-config.js';
 import { initializeDatabase } from '../../database.js';
 import { setDecision } from '../../tools/context/actions/set.js';
+import { enqueueDecisionCreate } from '../../utils/hook-queue.js';
 import { join } from 'path';
 // ============================================================================
 // Constants
@@ -24,6 +25,77 @@ const IN_REVIEW_STATUS = 'active';
 /** Workflow tag for in-review state */
 const WORKFLOW_TAG_IN_REVIEW = 'workflow:in_review';
 // ============================================================================
+// TOML Decision/Constraint Processing (v4.2.0+)
+// ============================================================================
+/**
+ * Format constraint candidates as a registration prompt
+ *
+ * @param cache - Plan TOML cache with constraint candidates
+ * @returns Formatted prompt string with MCP command examples
+ */
+function formatConstraintPrompt(cache) {
+    if (cache.constraints.length === 0) {
+        return '';
+    }
+    const lines = [
+        '',
+        '🎯 **Constraint Candidates Ready for Registration**',
+        '',
+        `Found ${cache.constraints.length} constraint candidate(s) from plan TOML:`,
+        '',
+    ];
+    cache.constraints.forEach((c, i) => {
+        const priority = c.priority || 'medium';
+        lines.push(`${i + 1}. [${c.category}/${priority}] ${c.text}`);
+        if (c.rationale) {
+            lines.push(`   Rationale: ${c.rationale}`);
+        }
+    });
+    lines.push('');
+    lines.push('To register, use mcp__sqlew__constraint with action="add":');
+    lines.push('```');
+    // Show example for first constraint
+    const first = cache.constraints[0];
+    lines.push(`mcp__sqlew__constraint action="add" constraint_text="${first.text}" category="${first.category}" priority="${first.priority || 'medium'}"`);
+    lines.push('```');
+    lines.push('');
+    return lines.join('\n');
+}
+/**
+ * Process TOML decisions and constraints from plan cache
+ *
+ * @param projectPath - Project root path
+ * @param cache - Plan TOML cache
+ * @returns Context message with results
+ */
+function processPlanTomlCache(projectPath, cache) {
+    const messages = [];
+    // Auto-register decisions (queued for MCP server processing)
+    if (!cache.decisions_registered && cache.decisions.length > 0) {
+        for (const d of cache.decisions) {
+            enqueueDecisionCreate(projectPath, {
+                key: d.key,
+                value: d.value,
+                status: d.status || 'active',
+                layer: d.layer || 'cross-cutting',
+                tags: d.tags || [],
+            });
+        }
+        cache.decisions_registered = true;
+        messages.push(`✅ Registered ${cache.decisions.length} decision(s) to queue`);
+    }
+    // Prompt for constraints (user decision required)
+    if (!cache.constraints_prompted && cache.constraints.length > 0) {
+        messages.push(formatConstraintPrompt(cache));
+        cache.constraints_prompted = true;
+    }
+    // Save updated cache
+    if (cache.decisions_registered || cache.constraints_prompted) {
+        savePlanTomlCache(projectPath, cache);
+    }
+    return messages.join('\n');
+}
+// ============================================================================
 // Main Entry Point
 // ============================================================================
 /**
@@ -85,12 +157,28 @@ export async function checkCompletionCommand() {
                 layer: 'cross-cutting',
                 tags: ['plan', 'implementation', WORKFLOW_TAG_IN_REVIEW, planInfo.plan_id.slice(0, 8)],
             });
-            sendContinue(`[sqlew] All tasks completed! Decision updated to status: ${IN_REVIEW_STATUS}`);
+            // Process TOML decisions and constraints (v4.2.0+)
+            let tomlContext = '';
+            const tomlCache = loadPlanTomlCache(projectPath);
+            if (tomlCache && tomlCache.plan_id === planInfo.plan_id) {
+                tomlContext = processPlanTomlCache(projectPath, tomlCache);
+            }
+            const baseMessage = `[sqlew] All tasks completed! Decision updated to status: ${IN_REVIEW_STATUS}`;
+            sendContinue(tomlContext ? `${baseMessage}\n${tomlContext}` : baseMessage);
         }
         catch (error) {
             // Log error but continue
             const message = error instanceof Error ? error.message : String(error);
             console.error(`[sqlew check-completion] Error updating decision: ${message}`);
+            // Still process TOML even if decision update failed
+            const tomlCache = loadPlanTomlCache(projectPath);
+            if (tomlCache && tomlCache.plan_id === planInfo.plan_id) {
+                const tomlContext = processPlanTomlCache(projectPath, tomlCache);
+                if (tomlContext) {
+                    sendContinue(tomlContext);
+                    return;
+                }
+            }
             sendContinue();
         }
     }