sqlew 3.8.1 → 3.9.0

package/dist/config/knex/enhancements/20251114000000_fix_v_tagged_decisions_numeric_support.js

@@ -0,0 +1,91 @@
+/**
+ * Migration: Fix v_tagged_decisions View to Support Numeric Decisions
+ *
+ * Problem:
+ * - v_tagged_decisions view only queries t_decisions, not t_decisions_numeric
+ * - This means numeric decisions don't appear in the view
+ * - get Decision() returns wrong values for numeric decisions (empty string instead of number)
+ *
+ * Solution:
+ * - Add LEFT JOIN to t_decisions_numeric
+ * - Use COALESCE(NULLIF(d.value, ''), dn.value) to prefer numeric value over empty string
+ *
+ * Satisfies Constraints:
+ * - Idempotent: Recreates view (DROP + CREATE)
+ * - Data Preservation: N/A (view has no data)
+ * - Cross-DB Compatible: Works with SQLite, MySQL, PostgreSQL
+ */
+export async function up(knex) {
+    console.log('🔄 Updating v_tagged_decisions view to support numeric decisions...');
+    // Get database client type
+    const client = knex.client.config.client;
+    const isSQLite = client === 'better-sqlite3' || client === 'sqlite3';
+    const isPostgres = client === 'pg' || client === 'postgres' || client === 'postgresql';
+    // Database-specific CAST syntax for numeric to string conversion
+    // - PostgreSQL: CAST(... AS TEXT)
+    // - MySQL/MariaDB: CAST(... AS CHAR)
+    // - SQLite: No CAST needed (accepts mixed types)
+    const castNumericToText = isPostgres ? 'CAST(dn.value AS TEXT)' :
+        isSQLite ? 'dn.value' :
+            'CAST(dn.value AS CHAR)'; // MySQL/MariaDB
+    // Drop existing view
+    await knex.raw('DROP VIEW IF EXISTS v_tagged_decisions');
+    // Recreate view with numeric support
+    await knex.raw(`
+    CREATE VIEW v_tagged_decisions AS
+    SELECT
+        k.key,
+        COALESCE(NULLIF(d.value, ''), ${castNumericToText}) as value,
+        d.version,
+        CASE d.status WHEN 1 THEN 'active' WHEN 2 THEN 'deprecated' ELSE 'draft' END as status,
+        d.project_id,
+        l.name as layer,
+        (SELECT ${isSQLite ? 'GROUP_CONCAT(t2.name, \',\')' : 'STRING_AGG(t2.name, \',\')'} FROM t_decision_tags dt2
+         JOIN m_tags t2 ON dt2.tag_id = t2.id
+         WHERE dt2.decision_key_id = d.key_id AND dt2.project_id = d.project_id) as tags,
+        (SELECT ${isSQLite ? 'GROUP_CONCAT(s2.name, \',\')' : 'STRING_AGG(s2.name, \',\')'} FROM t_decision_scopes ds2
+         JOIN m_scopes s2 ON ds2.scope_id = s2.id
+         WHERE ds2.decision_key_id = d.key_id AND ds2.project_id = d.project_id) as scopes,
+        a.name as decided_by,
+        ${isSQLite ? 'datetime(d.ts, \'unixepoch\')' : 'TO_TIMESTAMP(d.ts)'} as updated
+    FROM t_decisions d
+    JOIN m_context_keys k ON d.key_id = k.id
+    LEFT JOIN m_layers l ON d.layer_id = l.id
+    LEFT JOIN m_agents a ON d.agent_id = a.id
+    LEFT JOIN t_decisions_numeric dn ON dn.key_id = d.key_id AND dn.project_id = d.project_id
+  `);
+    console.log('✅ v_tagged_decisions view updated with numeric support');
+}
+export async function down(knex) {
+    console.log('🔄 Reverting v_tagged_decisions view to original...');
+    // Get database client type
+    const client = knex.client.config.client;
+    const isSQLite = client === 'better-sqlite3' || client === 'sqlite3';
+    // Drop existing view
+    await knex.raw('DROP VIEW IF EXISTS v_tagged_decisions');
+    // Recreate original view (without numeric support)
+    await knex.raw(`
+    CREATE VIEW v_tagged_decisions AS
+    SELECT
+        k.key,
+        d.value,
+        d.version,
+        CASE d.status WHEN 1 THEN 'active' WHEN 2 THEN 'deprecated' ELSE 'draft' END as status,
+        d.project_id,
+        l.name as layer,
+        (SELECT ${isSQLite ? 'GROUP_CONCAT(t2.name, \',\')' : 'STRING_AGG(t2.name, \',\')'} FROM t_decision_tags dt2
+         JOIN m_tags t2 ON dt2.tag_id = t2.id
+         WHERE dt2.decision_key_id = d.key_id AND dt2.project_id = d.project_id) as tags,
+        (SELECT ${isSQLite ? 'GROUP_CONCAT(s2.name, \',\')' : 'STRING_AGG(s2.name, \',\')'} FROM t_decision_scopes ds2
+         JOIN m_scopes s2 ON ds2.scope_id = s2.id
+         WHERE ds2.decision_key_id = d.key_id AND ds2.project_id = d.project_id) as scopes,
+        a.name as decided_by,
+        ${isSQLite ? 'datetime(d.ts, \'unixepoch\')' : 'TO_TIMESTAMP(d.ts)'} as updated
+    FROM t_decisions d
+    JOIN m_context_keys k ON d.key_id = k.id
+    LEFT JOIN m_layers l ON d.layer_id = l.id
+    LEFT JOIN m_agents a ON d.agent_id = a.id
+  `);
+    console.log('✅ v_tagged_decisions view reverted to original');
+}
+//# sourceMappingURL=20251114000000_fix_v_tagged_decisions_numeric_support.js.map

package/dist/config/knex/enhancements/20251114000000_fix_v_tagged_decisions_numeric_support.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"20251114000000_fix_v_tagged_decisions_numeric_support.js","sourceRoot":"","sources":["../../../../src/config/knex/enhancements/20251114000000_fix_v_tagged_decisions_numeric_support.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAIH,MAAM,CAAC,KAAK,UAAU,EAAE,CAAC,IAAU;IACjC,OAAO,CAAC,GAAG,CAAC,qEAAqE,CAAC,CAAC;IAEnF,2BAA2B;IAC3B,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC;IACzC,MAAM,QAAQ,GAAG,MAAM,KAAK,gBAAgB,IAAI,MAAM,KAAK,SAAS,CAAC;IACrE,MAAM,UAAU,GAAG,MAAM,KAAK,IAAI,IAAI,MAAM,KAAK,UAAU,IAAI,MAAM,KAAK,YAAY,CAAC;IAEvF,iEAAiE;IACjE,kCAAkC;IAClC,qCAAqC;IACrC,iDAAiD;IACjD,MAAM,iBAAiB,GAAG,UAAU,CAAC,CAAC,CAAC,wBAAwB,CAAC,CAAC;QACxC,QAAQ,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC;YACvB,wBAAwB,CAAC,CAAC,gBAAgB;IAEnE,qBAAqB;IACrB,MAAM,IAAI,CAAC,GAAG,CAAC,wCAAwC,CAAC,CAAC;IAEzD,qCAAqC;IACrC,MAAM,IAAI,CAAC,GAAG,CAAC;;;;wCAIuB,iBAAiB;;;;;kBAKvC,QAAQ,CAAC,CAAC,CAAC,8BAA8B,CAAC,CAAC,CAAC,4BAA4B;;;kBAGxE,QAAQ,CAAC,CAAC,CAAC,8BAA8B,CAAC,CAAC,CAAC,4BAA4B;;;;UAIhF,QAAQ,CAAC,CAAC,CAAC,+BAA+B,CAAC,CAAC,CAAC,oBAAoB;;;;;;GAMxE,CAAC,CAAC;IAEH,OAAO,CAAC,GAAG,CAAC,wDAAwD,CAAC,CAAC;AACxE,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,IAAI,CAAC,IAAU;IACnC,OAAO,CAAC,GAAG,CAAC,qDAAqD,CAAC,CAAC;IAEnE,2BAA2B;IAC3B,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC;IACzC,MAAM,QAAQ,GAAG,MAAM,KAAK,gBAAgB,IAAI,MAAM,KAAK,SAAS,CAAC;IAErE,qBAAqB;IACrB,MAAM,IAAI,CAAC,GAAG,CAAC,wCAAwC,CAAC,CAAC;IAEzD,mDAAmD;IACnD,MAAM,IAAI,CAAC,GAAG,CAAC;;;;;;;;;kBASC,QAAQ,CAAC,CAAC,CAAC,8BAA8B,CAAC,CAAC,CAAC,4BAA4B;;;kBAGxE,QAAQ,CAAC,CAAC,CAAC,8BAA8B,CAAC,CAAC,CAAC,4BAA4B;;;;UAIhF,QAAQ,CAAC,CAAC,CAAC,+BAA+B,CAAC,CAAC,CAAC,oBAAoB;;;;;GAKxE,CAAC,CAAC;IAEH,OAAO,CAAC,GAAG,CAAC,gDAAgD,CAAC,CAAC;AAChE,CAAC"}

package/dist/config/knex/enhancements/20251114120000_add_suggest_tool_to_help_system_v3_9_0.d.ts

@@ -0,0 +1,15 @@
+import type { Knex } from "knex";
+/**
+ * Migration: Add Suggest Tool to Help System (v3.9.0)
+ *
+ * Adds the new suggest tool and its actions to the help system database tables:
+ * - m_help_tools: suggest tool entry
+ * - m_help_actions: 4 actions (by_key, by_tags, by_context, check_duplicate)
+ * - t_help_action_params: Parameters for each action
+ * - t_help_action_examples: Code examples for each action
+ *
+ * Part of v3.9.0 Decision Intelligence System
+ */
+export declare function up(knex: Knex): Promise<void>;
+export declare function down(knex: Knex): Promise<void>;
+//# sourceMappingURL=20251114120000_add_suggest_tool_to_help_system_v3_9_0.d.ts.map

package/dist/config/knex/enhancements/20251114120000_add_suggest_tool_to_help_system_v3_9_0.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"20251114120000_add_suggest_tool_to_help_system_v3_9_0.d.ts","sourceRoot":"","sources":["../../../../src/config/knex/enhancements/20251114120000_add_suggest_tool_to_help_system_v3_9_0.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAEjC;;;;;;;;;;GAUG;AAEH,wBAAsB,EAAE,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAgRlD;AAED,wBAAsB,IAAI,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAOpD"}

package/dist/config/knex/enhancements/20251114120000_add_suggest_tool_to_help_system_v3_9_0.js

@@ -0,0 +1,270 @@
+/**
+ * Migration: Add Suggest Tool to Help System (v3.9.0)
+ *
+ * Adds the new suggest tool and its actions to the help system database tables:
+ * - m_help_tools: suggest tool entry
+ * - m_help_actions: 4 actions (by_key, by_tags, by_context, check_duplicate)
+ * - t_help_action_params: Parameters for each action
+ * - t_help_action_examples: Code examples for each action
+ *
+ * Part of v3.9.0 Decision Intelligence System
+ */
+export async function up(knex) {
+    // Check if suggest tool already exists
+    const existingSuggestTool = await knex('m_help_tools')
+        .where('tool_name', 'suggest')
+        .first();
+    if (existingSuggestTool) {
+        console.log('✓ Suggest tool already exists in help system, skipping');
+        return;
+    }
+    // =========================================================================
+    // 1. Add Suggest Tool to m_help_tools
+    // =========================================================================
+    await knex('m_help_tools').insert({
+        tool_name: 'suggest',
+        description: 'Intelligent Decision/Constraint Suggestion System - Find related decisions by key pattern, tags, or full context. Prevents duplicates and ensures consistency. Uses hybrid scoring with configurable relevance thresholds.'
+    });
+    // =========================================================================
+    // 2. Add Suggest Actions to m_help_actions
+    // =========================================================================
+    await knex('m_help_actions').insert([
+        {
+            tool_name: 'suggest',
+            action_name: 'by_key',
+            description: 'Find similar decisions by key pattern matching. Uses intelligent key similarity scoring based on path segments, common prefixes, and word overlap. Returns decisions ranked by relevance score (40 points for key match, 25 for layer, 20 for pattern, 10 for recency, 5 for priority).'
+        },
+        {
+            tool_name: 'suggest',
+            action_name: 'by_tags',
+            description: 'Find decisions by tag overlap (fast tag-based lookup). Uses inverted tag index for efficient queries. Returns decisions with matching tags ranked by overlap count. Ideal for discovering related decisions by topic or category.'
+        },
+        {
+            tool_name: 'suggest',
+            action_name: 'by_context',
+            description: 'Hybrid scoring combining key, tags, layer, and priority. Most comprehensive suggestion mode. Analyzes all context dimensions and returns top-ranked decisions. Use when you have rich context and want best matches across all factors.'
+        },
+        {
+            tool_name: 'suggest',
+            action_name: 'check_duplicate',
+            description: 'Check if decision key already exists or is very similar. Returns exact matches and high-similarity suggestions (score >= 70). Use before creating new decisions to prevent duplicates and discover existing related decisions.'
+        }
+    ]);
+    // =========================================================================
+    // 3. Get action IDs for parameter seeding
+    // =========================================================================
+    const byKeyAction = await knex('m_help_actions')
+        .where({ tool_name: 'suggest', action_name: 'by_key' })
+        .select('action_id')
+        .first();
+    const byTagsAction = await knex('m_help_actions')
+        .where({ tool_name: 'suggest', action_name: 'by_tags' })
+        .select('action_id')
+        .first();
+    const byContextAction = await knex('m_help_actions')
+        .where({ tool_name: 'suggest', action_name: 'by_context' })
+        .select('action_id')
+        .first();
+    const checkDuplicateAction = await knex('m_help_actions')
+        .where({ tool_name: 'suggest', action_name: 'check_duplicate' })
+        .select('action_id')
+        .first();
+    if (!byKeyAction || !byTagsAction || !byContextAction || !checkDuplicateAction) {
+        throw new Error('Failed to retrieve suggest action IDs');
+    }
+    // =========================================================================
+    // 4. Add Action Parameters to t_help_action_params
+    // =========================================================================
+    // by_key parameters
+    await knex('t_help_action_params').insert([
+        {
+            action_id: byKeyAction.action_id,
+            param_name: 'key',
+            param_type: 'string',
+            required: 1,
+            description: 'Decision key to find similar matches for. Uses path segment analysis and prefix matching.'
+        },
+        {
+            action_id: byKeyAction.action_id,
+            param_name: 'limit',
+            param_type: 'number',
+            required: 0,
+            description: 'Maximum number of suggestions to return',
+            default_value: '5'
+        },
+        {
+            action_id: byKeyAction.action_id,
+            param_name: 'min_score',
+            param_type: 'number',
+            required: 0,
+            description: 'Minimum relevance score (0-100) to include in results',
+            default_value: '30'
+        }
+    ]);
+    // by_tags parameters
+    await knex('t_help_action_params').insert([
+        {
+            action_id: byTagsAction.action_id,
+            param_name: 'tags',
+            param_type: 'array',
+            required: 1,
+            description: 'Array of tag names to match against. More tags = better filtering.'
+        },
+        {
+            action_id: byTagsAction.action_id,
+            param_name: 'layer',
+            param_type: 'string',
+            required: 0,
+            description: 'Filter results to specific architecture layer (presentation, business, data, infrastructure, cross-cutting, documentation, planning, coordination, review)',
+            default_value: 'null'
+        },
+        {
+            action_id: byTagsAction.action_id,
+            param_name: 'limit',
+            param_type: 'number',
+            required: 0,
+            description: 'Maximum number of suggestions to return',
+            default_value: '5'
+        },
+        {
+            action_id: byTagsAction.action_id,
+            param_name: 'min_score',
+            param_type: 'number',
+            required: 0,
+            description: 'Minimum relevance score (0-100) to include in results',
+            default_value: '30'
+        }
+    ]);
+    // by_context parameters
+    await knex('t_help_action_params').insert([
+        {
+            action_id: byContextAction.action_id,
+            param_name: 'key',
+            param_type: 'string',
+            required: 1,
+            description: 'Decision key for similarity matching'
+        },
+        {
+            action_id: byContextAction.action_id,
+            param_name: 'tags',
+            param_type: 'array',
+            required: 0,
+            description: 'Array of tags for topic matching',
+            default_value: '[]'
+        },
+        {
+            action_id: byContextAction.action_id,
+            param_name: 'layer',
+            param_type: 'string',
+            required: 0,
+            description: 'Architecture layer for layer-based scoring',
+            default_value: 'null'
+        },
+        {
+            action_id: byContextAction.action_id,
+            param_name: 'priority',
+            param_type: 'number',
+            required: 0,
+            description: 'Priority level (1=low, 2=medium, 3=high, 4=critical) for priority-based scoring',
+            default_value: 'null'
+        },
+        {
+            action_id: byContextAction.action_id,
+            param_name: 'limit',
+            param_type: 'number',
+            required: 0,
+            description: 'Maximum number of suggestions to return',
+            default_value: '5'
+        },
+        {
+            action_id: byContextAction.action_id,
+            param_name: 'min_score',
+            param_type: 'number',
+            required: 0,
+            description: 'Minimum relevance score (0-100) to include in results',
+            default_value: '30'
+        }
+    ]);
+    // check_duplicate parameters
+    await knex('t_help_action_params').insert([
+        {
+            action_id: checkDuplicateAction.action_id,
+            param_name: 'key',
+            param_type: 'string',
+            required: 1,
+            description: 'Decision key to check for duplicates. Returns exact match plus high-similarity suggestions (score >= 70).'
+        }
+    ]);
+    // =========================================================================
+    // 5. Add Code Examples to t_help_action_examples
+    // =========================================================================
+    // by_key examples
+    await knex('t_help_action_examples').insert([
+        {
+            action_id: byKeyAction.action_id,
+            example_title: 'Find similar authentication decisions',
+            example_code: '{"action":"by_key","key":"auth/jwt-strategy","limit":5,"min_score":40}',
+            explanation: 'Finds decisions with similar keys to "auth/jwt-strategy" such as "auth/session-strategy" or "auth/oauth-strategy". Returns top 5 with score >= 40.'
+        },
+        {
+            action_id: byKeyAction.action_id,
+            example_title: 'Discover related API decisions',
+            example_code: '{"action":"by_key","key":"api/rate-limiting","limit":3}',
+            explanation: 'Searches for API-related decisions similar to rate-limiting. Returns top 3 matches with default min_score of 30.'
+        }
+    ]);
+    // by_tags examples
+    await knex('t_help_action_examples').insert([
+        {
+            action_id: byTagsAction.action_id,
+            example_title: 'Find security and authentication decisions',
+            example_code: '{"action":"by_tags","tags":["security","authentication"],"layer":"business","limit":5}',
+            explanation: 'Finds business layer decisions tagged with both "security" and "authentication". Fast tag-based lookup.'
+        },
+        {
+            action_id: byTagsAction.action_id,
+            example_title: 'Discover performance optimization decisions',
+            example_code: '{"action":"by_tags","tags":["performance","caching"],"min_score":50}',
+            explanation: 'Searches for decisions tagged with performance and caching, returning only high-relevance matches (score >= 50).'
+        }
+    ]);
+    // by_context examples
+    await knex('t_help_action_examples').insert([
+        {
+            action_id: byContextAction.action_id,
+            example_title: 'Comprehensive context search for database decisions',
+            example_code: '{"action":"by_context","key":"db/connection-pool","tags":["database","performance"],"layer":"data","priority":3}',
+            explanation: 'Uses all context dimensions: key similarity, tag matching, layer filtering, and priority weighting. Returns best overall matches.'
+        },
+        {
+            action_id: byContextAction.action_id,
+            example_title: 'Find related infrastructure decisions',
+            example_code: '{"action":"by_context","key":"infra/deployment","tags":["docker","kubernetes"],"layer":"infrastructure"}',
+            explanation: 'Hybrid scoring across key, tags, and layer for infrastructure decisions. Ideal when you have rich context.'
+        }
+    ]);
+    // check_duplicate examples
+    await knex('t_help_action_examples').insert([
+        {
+            action_id: checkDuplicateAction.action_id,
+            example_title: 'Check for duplicate authentication decision',
+            example_code: '{"action":"check_duplicate","key":"auth/oauth2-provider"}',
+            explanation: 'Checks if "auth/oauth2-provider" already exists and finds very similar decisions (score >= 70). Prevents duplicate creation.'
+        },
+        {
+            action_id: checkDuplicateAction.action_id,
+            example_title: 'Verify unique decision before creation',
+            example_code: '{"action":"check_duplicate","key":"feature/dark-mode"}',
+            explanation: 'Verifies key uniqueness before creating new decision. Returns exact match or high-similarity warnings.'
+        }
+    ]);
+    console.log('✓ Suggest tool added to help system with 4 actions, 15 parameters, and 8 examples');
+}
+export async function down(knex) {
+    // Remove suggest tool entries (cascades to actions, parameters, and examples)
+    await knex('m_help_tools')
+        .where('tool_name', 'suggest')
+        .delete();
+    console.log('✓ Suggest tool removed from help system');
+}
+//# sourceMappingURL=20251114120000_add_suggest_tool_to_help_system_v3_9_0.js.map

package/dist/config/knex/enhancements/20251114120000_add_suggest_tool_to_help_system_v3_9_0.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"20251114120000_add_suggest_tool_to_help_system_v3_9_0.js","sourceRoot":"","sources":["../../../../src/config/knex/enhancements/20251114120000_add_suggest_tool_to_help_system_v3_9_0.ts"],"names":[],"mappings":"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"}

package/dist/config/knex/enhancements/20251114121000_add_suggest_tool_use_cases_v3_9_0.d.ts

@@ -0,0 +1,15 @@
+import type { Knex } from "knex";
+/**
+ * Migration: Add Suggest Tool Use Cases (v3.9.0)
+ *
+ * Adds comprehensive use cases for the suggest tool workflows:
+ * - Preventing duplicate decisions
+ * - Finding related decisions for consistency
+ * - Discovering decisions by topic (tags)
+ * - Context-aware decision discovery
+ *
+ * Part of v3.9.0 Decision Intelligence System
+ */
+export declare function up(knex: Knex): Promise<void>;
+export declare function down(knex: Knex): Promise<void>;
+//# sourceMappingURL=20251114121000_add_suggest_tool_use_cases_v3_9_0.d.ts.map

package/dist/config/knex/enhancements/20251114121000_add_suggest_tool_use_cases_v3_9_0.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"20251114121000_add_suggest_tool_use_cases_v3_9_0.d.ts","sourceRoot":"","sources":["../../../../src/config/knex/enhancements/20251114121000_add_suggest_tool_use_cases_v3_9_0.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAEjC;;;;;;;;;;GAUG;AAEH,wBAAsB,EAAE,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAiOlD;AAED,wBAAsB,IAAI,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAUpD"}

package/dist/config/knex/enhancements/20251114121000_add_suggest_tool_use_cases_v3_9_0.js

@@ -0,0 +1,241 @@
+/**
+ * Migration: Add Suggest Tool Use Cases (v3.9.0)
+ *
+ * Adds comprehensive use cases for the suggest tool workflows:
+ * - Preventing duplicate decisions
+ * - Finding related decisions for consistency
+ * - Discovering decisions by topic (tags)
+ * - Context-aware decision discovery
+ *
+ * Part of v3.9.0 Decision Intelligence System
+ */
+export async function up(knex) {
+    // Get category IDs
+    const decisionCategory = await knex('m_help_use_case_categories')
+        .where('category_name', 'decision_tracking')
+        .select('category_id')
+        .first();
+    const crossToolCategory = await knex('m_help_use_case_categories')
+        .where('category_name', 'cross_tool_workflow')
+        .select('category_id')
+        .first();
+    if (!decisionCategory || !crossToolCategory) {
+        throw new Error('Required use case categories not found. Run seed_help_categories_and_use_cases migration first.');
+    }
+    // Check if suggest use cases already exist
+    const existingUseCases = await knex('t_help_use_cases')
+        .where('title', 'like', '%suggest%')
+        .orWhere('full_example', 'like', '%suggest%');
+    if (existingUseCases.length > 0) {
+        console.log('✓ Suggest use cases already exist, skipping');
+        return;
+    }
+    // =========================================================================
+    // Add Suggest Tool Use Cases
+    // =========================================================================
+    await knex('t_help_use_cases').insert([
+        {
+            category_id: decisionCategory.category_id,
+            title: 'Prevent duplicate decisions before creation',
+            complexity: 'basic',
+            description: 'Use suggest.check_duplicate to verify a decision key is unique before creating it. Prevents duplicate decisions and discovers existing similar decisions that might be updated instead.',
+            full_example: JSON.stringify({
+                scenario: 'Before creating a new decision about API authentication, check if similar decisions exist',
+                steps: [
+                    {
+                        step: 1,
+                        action: 'suggest.check_duplicate',
+                        code: {
+                            action: 'check_duplicate',
+                            key: 'api/authentication-strategy'
+                        },
+                        explanation: 'Check if key exists or is very similar (score >= 70)'
+                    },
+                    {
+                        step: 2,
+                        decision: 'If no exact match found and similarity scores are low, create new decision',
+                        action: 'decision.set',
+                        code: {
+                            action: 'set',
+                            key: 'api/authentication-strategy',
+                            value: 'JWT with refresh tokens',
+                            layer: 'business',
+                            tags: ['api', 'security', 'authentication']
+                        }
+                    },
+                    {
+                        step: 3,
+                        alternative: 'If exact match or high similarity found, update existing decision instead',
+                        action: 'decision.set',
+                        code: {
+                            action: 'set',
+                            key: 'existing-key-from-suggestion',
+                            value: 'Updated value',
+                            version: '1.1.0'
+                        }
+                    }
+                ]
+            }),
+            action_sequence: 'suggest.check_duplicate → decision.set (new or update)'
+        },
+        {
+            category_id: decisionCategory.category_id,
+            title: 'Find related decisions for consistency',
+            complexity: 'intermediate',
+            description: 'Use suggest.by_key to find decisions with similar keys when making architectural choices. Ensures consistency across related decisions and helps discover existing patterns.',
+            full_example: JSON.stringify({
+                scenario: 'When implementing database caching strategy, find related database decisions',
+                steps: [
+                    {
+                        step: 1,
+                        action: 'suggest.by_key',
+                        code: {
+                            action: 'by_key',
+                            key: 'db/caching-strategy',
+                            limit: 5,
+                            min_score: 40
+                        },
+                        explanation: 'Find similar database decisions (db/connection-pool, db/query-optimization, etc.)'
+                    },
+                    {
+                        step: 2,
+                        action: 'decision.get',
+                        code: {
+                            action: 'get',
+                            key: 'db/connection-pool',
+                            include_context: true
+                        },
+                        explanation: 'Review similar decisions to understand existing patterns'
+                    },
+                    {
+                        step: 3,
+                        action: 'decision.set',
+                        code: {
+                            action: 'set',
+                            key: 'db/caching-strategy',
+                            value: 'Redis with write-through pattern',
+                            layer: 'data',
+                            tags: ['database', 'caching', 'performance']
+                        },
+                        explanation: 'Create new decision consistent with existing db/ pattern'
+                    }
+                ]
+            }),
+            action_sequence: 'suggest.by_key → decision.get → decision.set'
+        },
+        {
+            category_id: decisionCategory.category_id,
+            title: 'Discover decisions by topic using tags',
+            complexity: 'basic',
+            description: 'Use suggest.by_tags to find all decisions related to a specific topic or feature. Fast tag-based lookup for discovering related context.',
+            full_example: JSON.stringify({
+                scenario: 'Find all security-related decisions before implementing authentication',
+                steps: [
+                    {
+                        step: 1,
+                        action: 'suggest.by_tags',
+                        code: {
+                            action: 'by_tags',
+                            tags: ['security', 'authentication'],
+                            layer: 'business',
+                            limit: 10
+                        },
+                        explanation: 'Find security and authentication decisions in business layer'
+                    },
+                    {
+                        step: 2,
+                        action: 'decision.get',
+                        code: {
+                            action: 'get',
+                            key: 'returned-key-from-suggestion',
+                            include_context: true
+                        },
+                        explanation: 'Review each suggested decision for context and rationale'
+                    }
+                ],
+                expected_outcome: 'Comprehensive list of security decisions to guide implementation',
+                common_pitfalls: [
+                    'Using too many tags (reduces matches)',
+                    'Not specifying layer (gets results from all layers)',
+                    'Setting min_score too high (excludes valid results)'
+                ]
+            }),
+            action_sequence: 'suggest.by_tags → decision.get (for each result)'
+        },
+        {
+            category_id: crossToolCategory.category_id,
+            title: 'Context-aware decision discovery',
+            complexity: 'advanced',
+            description: 'Use suggest.by_context for comprehensive decision discovery using all context dimensions: key similarity, tag overlap, layer matching, and priority weighting. Ideal when you have rich context.',
+            full_example: JSON.stringify({
+                scenario: 'Find relevant decisions when implementing critical infrastructure change',
+                steps: [
+                    {
+                        step: 1,
+                        action: 'suggest.by_context',
+                        code: {
+                            action: 'by_context',
+                            key: 'infra/kubernetes-migration',
+                            tags: ['infrastructure', 'deployment', 'docker'],
+                            layer: 'infrastructure',
+                            priority: 4,
+                            limit: 5,
+                            min_score: 50
+                        },
+                        explanation: 'Hybrid scoring across key, tags, layer, and priority for best matches'
+                    },
+                    {
+                        step: 2,
+                        action: 'decision.get',
+                        code: {
+                            action: 'get',
+                            key: 'suggested-decision-key',
+                            include_context: true
+                        },
+                        explanation: 'Review suggested decision context and rationale'
+                    },
+                    {
+                        step: 3,
+                        action: 'decision.add_decision_context',
+                        code: {
+                            action: 'add_decision_context',
+                            key: 'infra/kubernetes-migration',
+                            rationale: 'Based on successful docker patterns from similar decisions',
+                            alternatives_considered: [
+                                {
+                                    option: 'Direct VM deployment',
+                                    rejected_because: 'Less flexible than container orchestration'
+                                }
+                            ],
+                            tradeoffs: {
+                                pros: ['Auto-scaling', 'High availability'],
+                                cons: ['Increased complexity', 'Learning curve']
+                            }
+                        },
+                        explanation: 'Document new decision with context referencing related decisions'
+                    }
+                ],
+                expected_outcome: 'Well-informed decision based on comprehensive context discovery',
+                common_pitfalls: [
+                    'Not providing enough context (tags, layer)',
+                    'Setting min_score too high for exploratory search',
+                    'Ignoring priority weighting for critical decisions'
+                ],
+                related_tools: ['decision', 'task']
+            }),
+            action_sequence: 'suggest.by_context → decision.get → decision.add_decision_context'
+        }
+    ]);
+    console.log('✓ Added 4 suggest tool use cases (1 basic, 1 intermediate, 1 advanced, 1 cross-tool)');
+}
+export async function down(knex) {
+    // Remove suggest use cases
+    await knex('t_help_use_cases')
+        .where('title', 'like', '%suggest%')
+        .orWhere('title', 'like', '%duplicate decision%')
+        .orWhere('title', 'like', '%related decisions%')
+        .orWhere('title', 'like', '%Context-aware decision%')
+        .delete();
+    console.log('✓ Removed suggest tool use cases');
+}
+//# sourceMappingURL=20251114121000_add_suggest_tool_use_cases_v3_9_0.js.map