sqlew 3.1.2 → 3.2.3

package/dist/tools/context.js

@@ -2,7 +2,7 @@
  * Context management tools for MCP Shared Context Server
  * Implements set_decision, get_context, and get_decision tools
  */
-import { getDatabase, getOrCreateAgent, getOrCreateContextKey, getOrCreateTag, getOrCreateScope, getLayerId, transaction } from '../database.js';
+import { getDatabase, getOrCreateAgent, getOrCreateContextKey, getOrCreateTag, getOrCreateScope, getLayerId, transaction, addDecisionContext as dbAddDecisionContext, getDecisionWithContext as dbGetDecisionWithContext, listDecisionContexts as dbListDecisionContexts } from '../database.js';
 import { STRING_TO_STATUS, DEFAULT_VERSION, DEFAULT_STATUS } from '../constants.js';
 import { processBatch } from '../utils/batch.js';
 import { validateRequired, validateStatus, validateLayer } from '../utils/validators.js';
@@ -44,31 +44,31 @@ function setDecisionInternal(params, db) {
     // Insert or update decision based on value type
     if (isNumeric) {
         // Numeric decision
-        const stmt = db.prepare(`
-      INSERT INTO t_decisions_numeric (key_id, value, agent_id, layer_id, version, status, ts)
-      VALUES (?, ?, ?, ?, ?, ?, ?)
-      ON CONFLICT(key_id) DO UPDATE SET
-        value = excluded.value,
-        agent_id = excluded.agent_id,
-        layer_id = excluded.layer_id,
-        version = excluded.version,
-        status = excluded.status,
-        ts = excluded.ts
+        const stmt = db.prepare(`
+      INSERT INTO t_decisions_numeric (key_id, value, agent_id, layer_id, version, status, ts)
+      VALUES (?, ?, ?, ?, ?, ?, ?)
+      ON CONFLICT(key_id) DO UPDATE SET
+        value = excluded.value,
+        agent_id = excluded.agent_id,
+        layer_id = excluded.layer_id,
+        version = excluded.version,
+        status = excluded.status,
+        ts = excluded.ts
     `);
         stmt.run(keyId, value, agentId, layerId, version, status, ts);
     }
     else {
         // String decision
-        const stmt = db.prepare(`
-      INSERT INTO t_decisions (key_id, value, agent_id, layer_id, version, status, ts)
-      VALUES (?, ?, ?, ?, ?, ?, ?)
-      ON CONFLICT(key_id) DO UPDATE SET
-        value = excluded.value,
-        agent_id = excluded.agent_id,
-        layer_id = excluded.layer_id,
-        version = excluded.version,
-        status = excluded.status,
-        ts = excluded.ts
+        const stmt = db.prepare(`
+      INSERT INTO t_decisions (key_id, value, agent_id, layer_id, version, status, ts)
+      VALUES (?, ?, ?, ?, ?, ?, ?)
+      ON CONFLICT(key_id) DO UPDATE SET
+        value = excluded.value,
+        agent_id = excluded.agent_id,
+        layer_id = excluded.layer_id,
+        version = excluded.version,
+        status = excluded.status,
+        ts = excluded.ts
     `);
         stmt.run(keyId, String(value), agentId, layerId, version, status, ts);
     }
@@ -193,8 +193,9 @@ export function getContext(params = {}) {
 /**
  * Get a specific decision by key
  * Returns full metadata including tags, layer, scopes, version
+ * Optionally includes decision context (v3.2.2)
  *
- * @param params - Decision key
+ * @param params - Decision key and optional include_context flag
  * @returns Decision details or not found
  */
 export function getDecision(params) {
@@ -204,7 +205,36 @@ export function getDecision(params) {
         throw new Error('Parameter "key" is required and cannot be empty');
     }
     try {
-        // Query v_tagged_decisions view
+        // If include_context is true, use the context-aware function
+        if (params.include_context) {
+            const result = dbGetDecisionWithContext(db, params.key);
+            if (!result) {
+                return {
+                    found: false
+                };
+            }
+            return {
+                found: true,
+                decision: {
+                    key: result.key,
+                    value: result.value,
+                    version: result.version,
+                    status: result.status,
+                    layer: result.layer,
+                    decided_by: result.decided_by,
+                    updated: result.updated,
+                    tags: null, // Not included in getDecisionWithContext
+                    scopes: null // Not included in getDecisionWithContext
+                },
+                context: result.context.map(ctx => ({
+                    ...ctx,
+                    // Parse JSON fields
+                    alternatives_considered: ctx.alternatives_considered ? JSON.parse(ctx.alternatives_considered) : null,
+                    tradeoffs: ctx.tradeoffs ? JSON.parse(ctx.tradeoffs) : null
+                }))
+            };
+        }
+        // Standard query without context (backward compatible)
         const stmt = db.prepare('SELECT * FROM v_tagged_decisions WHERE key = ?');
         const row = stmt.get(params.key);
         if (!row) {
@@ -317,16 +347,16 @@ export function getVersions(params) {
         }
         const keyId = keyResult.id;
         // Query t_decision_history with agent join
-        const stmt = db.prepare(`
-      SELECT
-        dh.version,
-        dh.value,
-        a.name as agent_name,
-        datetime(dh.ts, 'unixepoch') as timestamp
-      FROM t_decision_history dh
-      LEFT JOIN m_agents a ON dh.agent_id = a.id
-      WHERE dh.key_id = ?
-      ORDER BY dh.ts DESC
+        const stmt = db.prepare(`
+      SELECT
+        dh.version,
+        dh.value,
+        a.name as agent_name,
+        datetime(dh.ts, 'unixepoch') as timestamp
+      FROM t_decision_history dh
+      LEFT JOIN m_agents a ON dh.agent_id = a.id
+      WHERE dh.key_id = ?
+      ORDER BY dh.ts DESC
     `);
         const rows = stmt.all(keyId);
         // Transform to response format
@@ -377,58 +407,58 @@ export function searchByLayer(params) {
         const queryParams = [params.layer, statusValue];
         if (includeTagsValue) {
             // Use v_tagged_decisions view for full metadata
-            query = `
-        SELECT * FROM v_tagged_decisions
-        WHERE layer = ? AND status = ?
-        ORDER BY updated DESC
+            query = `
+        SELECT * FROM v_tagged_decisions
+        WHERE layer = ? AND status = ?
+        ORDER BY updated DESC
       `;
         }
         else {
             // Use base t_decisions table with minimal joins
-            query = `
-        SELECT
-          ck.key,
-          d.value,
-          d.version,
-          CASE d.status
-            WHEN 1 THEN 'active'
-            WHEN 2 THEN 'deprecated'
-            WHEN 3 THEN 'draft'
-          END as status,
-          l.name as layer,
-          NULL as tags,
-          NULL as scopes,
-          a.name as decided_by,
-          datetime(d.ts, 'unixepoch') as updated
-        FROM t_decisions d
-        INNER JOIN m_context_keys ck ON d.key_id = ck.id
-        LEFT JOIN m_layers l ON d.layer_id = l.id
-        LEFT JOIN m_agents a ON d.agent_id = a.id
-        WHERE l.name = ? AND d.status = ?
-
-        UNION ALL
-
-        SELECT
-          ck.key,
-          CAST(dn.value AS TEXT) as value,
-          dn.version,
-          CASE dn.status
-            WHEN 1 THEN 'active'
-            WHEN 2 THEN 'deprecated'
-            WHEN 3 THEN 'draft'
-          END as status,
-          l.name as layer,
-          NULL as tags,
-          NULL as scopes,
-          a.name as decided_by,
-          datetime(dn.ts, 'unixepoch') as updated
-        FROM t_decisions_numeric dn
-        INNER JOIN m_context_keys ck ON dn.key_id = ck.id
-        LEFT JOIN m_layers l ON dn.layer_id = l.id
-        LEFT JOIN m_agents a ON dn.agent_id = a.id
-        WHERE l.name = ? AND dn.status = ?
-
-        ORDER BY updated DESC
+            query = `
+        SELECT
+          ck.key,
+          d.value,
+          d.version,
+          CASE d.status
+            WHEN 1 THEN 'active'
+            WHEN 2 THEN 'deprecated'
+            WHEN 3 THEN 'draft'
+          END as status,
+          l.name as layer,
+          NULL as tags,
+          NULL as scopes,
+          a.name as decided_by,
+          datetime(d.ts, 'unixepoch') as updated
+        FROM t_decisions d
+        INNER JOIN m_context_keys ck ON d.key_id = ck.id
+        LEFT JOIN m_layers l ON d.layer_id = l.id
+        LEFT JOIN m_agents a ON d.agent_id = a.id
+        WHERE l.name = ? AND d.status = ?
+
+        UNION ALL
+
+        SELECT
+          ck.key,
+          CAST(dn.value AS TEXT) as value,
+          dn.version,
+          CASE dn.status
+            WHEN 1 THEN 'active'
+            WHEN 2 THEN 'deprecated'
+            WHEN 3 THEN 'draft'
+          END as status,
+          l.name as layer,
+          NULL as tags,
+          NULL as scopes,
+          a.name as decided_by,
+          datetime(dn.ts, 'unixepoch') as updated
+        FROM t_decisions_numeric dn
+        INNER JOIN m_context_keys ck ON dn.key_id = ck.id
+        LEFT JOIN m_layers l ON dn.layer_id = l.id
+        LEFT JOIN m_agents a ON dn.agent_id = a.id
+        WHERE l.name = ? AND dn.status = ?
+
+        ORDER BY updated DESC
       `;
             // Add params for the numeric table part of UNION
             queryParams.push(params.layer, statusValue);
@@ -785,12 +815,12 @@ export function hasUpdates(params) {
         }
         const sinceTs = Math.floor(sinceDate.getTime() / 1000);
         // Count decisions updated since timestamp (both string and numeric tables)
-        const decisionCountStmt = db.prepare(`
-      SELECT COUNT(*) as count FROM (
-        SELECT ts FROM t_decisions WHERE ts > ?
-        UNION ALL
-        SELECT ts FROM t_decisions_numeric WHERE ts > ?
-      )
+        const decisionCountStmt = db.prepare(`
+      SELECT COUNT(*) as count FROM (
+        SELECT ts FROM t_decisions WHERE ts > ?
+        UNION ALL
+        SELECT ts FROM t_decisions_numeric WHERE ts > ?
+      )
     `);
         const decisionResult = decisionCountStmt.get(sinceTs, sinceTs);
         const decisionsCount = decisionResult.count;
@@ -800,16 +830,16 @@ export function hasUpdates(params) {
         let messagesCount = 0;
         if (agentResult) {
             const agentId = agentResult.id;
-            const messageCountStmt = db.prepare(`
-        SELECT COUNT(*) as count FROM t_agent_messages
-        WHERE ts > ? AND (to_agent_id = ? OR to_agent_id IS NULL)
+            const messageCountStmt = db.prepare(`
+        SELECT COUNT(*) as count FROM t_agent_messages
+        WHERE ts > ? AND (to_agent_id = ? OR to_agent_id IS NULL)
       `);
             const messageResult = messageCountStmt.get(sinceTs, agentId);
             messagesCount = messageResult.count;
         }
         // Count file changes since timestamp
-        const fileCountStmt = db.prepare(`
-      SELECT COUNT(*) as count FROM t_file_changes WHERE ts > ?
+        const fileCountStmt = db.prepare(`
+      SELECT COUNT(*) as count FROM t_file_changes WHERE ts > ?
     `);
         const fileResult = fileCountStmt.get(sinceTs);
         const filesCount = fileResult.count;
@@ -944,9 +974,9 @@ export function createTemplate(params) {
             const defaultsJson = JSON.stringify(params.defaults);
             const requiredFieldsJson = params.required_fields ? JSON.stringify(params.required_fields) : null;
             // Insert template
-            const stmt = db.prepare(`
-        INSERT INTO t_decision_templates (name, defaults, required_fields, created_by)
-        VALUES (?, ?, ?, ?)
+            const stmt = db.prepare(`
+        INSERT INTO t_decision_templates (name, defaults, required_fields, created_by)
+        VALUES (?, ?, ?, ?)
       `);
             const info = stmt.run(params.name, defaultsJson, requiredFieldsJson, createdById);
             return {
@@ -972,17 +1002,17 @@ export function createTemplate(params) {
 export function listTemplates(params = {}) {
     const db = getDatabase();
     try {
-        const stmt = db.prepare(`
-      SELECT
-        t.id,
-        t.name,
-        t.defaults,
-        t.required_fields,
-        a.name as created_by,
-        datetime(t.ts, 'unixepoch') as created_at
-      FROM t_decision_templates t
-      LEFT JOIN m_agents a ON t.created_by = a.id
-      ORDER BY t.name ASC
+        const stmt = db.prepare(`
+      SELECT
+        t.id,
+        t.name,
+        t.defaults,
+        t.required_fields,
+        a.name as created_by,
+        datetime(t.ts, 'unixepoch') as created_at
+      FROM t_decision_templates t
+      LEFT JOIN m_agents a ON t.created_by = a.id
+      ORDER BY t.name ASC
     `);
         const rows = stmt.all();
         // Parse JSON fields
@@ -1069,4 +1099,310 @@ export function hardDeleteDecision(params) {
         throw new Error(`Failed to hard delete decision: ${message}`);
     }
 }
+// ============================================================================
+// Decision Context Actions (v3.2.2)
+// ============================================================================
+/**
+ * Add decision context action
+ * Adds rich context (rationale, alternatives, tradeoffs) to a decision
+ *
+ * @param params - Context parameters
+ * @returns Response with success status
+ */
+export function addDecisionContextAction(params) {
+    const db = getDatabase();
+    // Validate required parameters
+    if (!params.key || params.key.trim() === '') {
+        throw new Error('Parameter "key" is required and cannot be empty');
+    }
+    if (!params.rationale || params.rationale.trim() === '') {
+        throw new Error('Parameter "rationale" is required and cannot be empty');
+    }
+    try {
+        // Parse JSON if provided as strings
+        let alternatives = params.alternatives_considered || null;
+        let tradeoffs = params.tradeoffs || null;
+        // If already objects, stringify them
+        if (alternatives && typeof alternatives === 'object') {
+            alternatives = JSON.stringify(alternatives);
+        }
+        if (tradeoffs && typeof tradeoffs === 'object') {
+            tradeoffs = JSON.stringify(tradeoffs);
+        }
+        const contextId = dbAddDecisionContext(db, params.key, params.rationale, alternatives, tradeoffs, params.decided_by || null, params.related_task_id || null, params.related_constraint_id || null);
+        return {
+            success: true,
+            context_id: contextId,
+            decision_key: params.key,
+            message: `Decision context added successfully to "${params.key}"`
+        };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`Failed to add decision context: ${message}`);
+    }
+}
+/**
+ * List decision contexts action
+ * Query decision contexts with optional filters
+ *
+ * @param params - Filter parameters
+ * @returns Array of decision contexts
+ */
+export function listDecisionContextsAction(params) {
+    const db = getDatabase();
+    try {
+        const contexts = dbListDecisionContexts(db, {
+            decisionKey: params.decision_key,
+            relatedTaskId: params.related_task_id,
+            relatedConstraintId: params.related_constraint_id,
+            decidedBy: params.decided_by,
+            limit: params.limit || 50,
+            offset: params.offset || 0
+        });
+        return {
+            success: true,
+            contexts: contexts.map(ctx => ({
+                ...ctx,
+                // Parse JSON fields for display
+                alternatives_considered: ctx.alternatives_considered ? JSON.parse(ctx.alternatives_considered) : null,
+                tradeoffs: ctx.tradeoffs ? JSON.parse(ctx.tradeoffs) : null
+            })),
+            count: contexts.length
+        };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`Failed to list decision contexts: ${message}`);
+    }
+}
+/**
+ * Help action for decision tool
+ */
+export function decisionHelp() {
+    return {
+        tool: 'decision',
+        description: 'Manage decisions with metadata (tags, layers, versions, scopes)',
+        note: '💡 TIP: Use action: "example" to see comprehensive usage scenarios and real-world examples for all decision actions.',
+        purpose: {
+            title: '⚠️ CRITICAL: Store WHY and REASON, Not WHAT',
+            principle: 'Decisions table is for ARCHITECTURAL CONTEXT and REASONING, NOT implementation logs or task completion status',
+            what_to_store: {
+                correct: [
+                    'WHY a design choice was made (e.g., "Chose JWT over sessions because stateless auth scales better for our microservice architecture")',
+                    'REASONING behind architecture decisions (e.g., "Moved oscillator_type to MonophonicSynthConfig to separate synthesis methods - FM operators use different config")',
+                    'PROBLEM ANALYSIS and solution rationale (e.g., "Nested transaction bug: setDecision wraps in transaction, batch also wraps → solution: extract internal helper without transaction wrapper")',
+                    'DESIGN TRADE-OFFS and alternatives considered (e.g., "Query builder limited to simple filters, kept domain-specific logic inline for maintainability")',
+                    'CONSTRAINTS and requirements reasoning (e.g., "API response must be <100ms because mobile clients timeout at 200ms")',
+                    'BREAKING CHANGES with migration rationale (e.g., "Removed /v1/users endpoint - clients must use /v2/users with pagination for scalability")'
+                ],
+                incorrect: [
+                    '❌ Task completion logs (e.g., "Task 5 completed", "Refactoring done", "Tests passing") → Use tasks tool instead',
+                    '❌ Implementation status (e.g., "Added validators.ts", "Fixed bug in batch_create", "Updated README") → These are WHAT, not WHY',
+                    '❌ Test results (e.g., "All tests passing", "Integration tests complete", "v3.0.2 testing verified") → Temporary status, not architectural context',
+                    '❌ Git commit summaries (e.g., "Released v3.0.2", "Created git commit 2bf55a0") → Belongs in git history',
+                    '❌ Documentation updates (e.g., "README reorganized", "Help actions enhanced") → Implementation logs, not decisions',
+                    '❌ Build status (e.g., "Build succeeded", "TypeScript compiled with zero errors") → Temporary status'
+                ]
+            },
+            analogy: {
+                git_history: 'WHAT changed (files, lines, commits)',
+                code_comments: 'HOW it works (implementation details, algorithms)',
+                sqlew_decisions: 'WHY it was changed (reasoning, trade-offs, context)',
+                sqlew_tasks: 'WHAT needs to be done (work items, status, completion)'
+            },
+            examples: [
+                {
+                    key: 'api/auth/jwt-choice',
+                    value: 'Chose JWT over session-based auth because: (1) Stateless design scales horizontally, (2) Mobile clients can cache tokens, (3) Microservice architecture requires distributed auth. Trade-off: Revocation requires token blacklist, but acceptable for 15-min token lifetime.',
+                    explanation: 'Explains WHY JWT was chosen, considers trade-offs, provides architectural context'
+                },
+                {
+                    key: 'database/postgresql-choice',
+                    value: 'Selected PostgreSQL over MongoDB because: (1) Complex relational queries required for reporting, (2) ACID compliance critical for financial data, (3) Team has strong SQL expertise. Trade-off: Less flexible schema, but data integrity more important than schema flexibility for our use case.',
+                    explanation: 'Documents database choice with reasoning, alternatives considered, and trade-offs'
+                },
+                {
+                    key: 'security/encryption-at-rest',
+                    value: 'Implementing AES-256 encryption for all PII in database because: (1) GDPR compliance requires encryption at rest, (2) Recent security audit identified unencrypted sensitive data, (3) Performance impact <5ms per query acceptable. Alternative considered: Database-level encryption rejected due to backup/restore complexity.',
+                    explanation: 'Explains security decision with compliance reasoning and performance considerations'
+                }
+            ],
+            cleanup_rule: 'Delete decisions that start with "COMPLETED:", contain task status, test results, or implementation logs. Keep only architectural reasoning and design rationale.'
+        },
+        actions: {
+            set: 'Set/update a decision. Params: key (required), value (required), agent, layer, version, status, tags, scopes',
+            get: 'Get specific decision by key. Params: key (required), include_context (optional, boolean, default: false). When include_context=true, returns decision with attached context (rationale, alternatives, tradeoffs). Backward compatible - omitting flag returns standard decision format.',
+            list: 'List/filter decisions. Params: status, layer, tags, scope, tag_match',
+            search_tags: 'Search decisions by tags. Params: tags (required), match_mode, status, layer',
+            search_layer: 'Search decisions by layer. Params: layer (required), status, include_tags',
+            versions: 'Get version history for a decision. Params: key (required)',
+            quick_set: 'Quick set with smart defaults (FR-002). Params: key (required), value (required), agent, layer, version, status, tags, scopes. Auto-infers layer from key prefix (api/*→presentation, db/*→data, service/*→business, config/*→infrastructure), tags from key hierarchy, scope from parent path. Defaults: status=active, version=1.0.0. All inferred fields can be overridden.',
+            search_advanced: 'Advanced query with complex filtering (FR-004). Params: layers (OR), tags_all (AND), tags_any (OR), exclude_tags, scopes (wildcards), updated_after/before (ISO or relative like "7d"), decided_by, statuses, search_text, sort_by (updated/key/version), sort_order (asc/desc), limit (default:20, max:1000), offset (default:0). Returns decisions with total_count for pagination. All filters use parameterized queries (SQL injection protection).',
+            set_batch: 'Batch set decisions (FR-005). Params: decisions (required, array of SetDecisionParams, max: 50), atomic (optional, boolean, default: true). Returns: {success, inserted, failed, results}. ATOMIC MODE BEHAVIOR (atomic: true): All decisions succeed or all fail as a single transaction. If ANY decision fails, entire batch is rolled back and error is thrown. Use for critical operations requiring consistency. NON-ATOMIC MODE (atomic: false): Each decision is processed independently. If some fail, others still succeed. Returns partial results with per-item success/error status. Use for best-effort batch operations or when individual failures are acceptable. RECOMMENDATION FOR AI AGENTS: Use atomic:false by default to avoid transaction failures from validation errors or malformed data. Only use atomic:true when all-or-nothing guarantee is required. 52% token reduction vs individual calls.',
+            has_updates: 'Check for updates since timestamp (FR-003 Phase A - Lightweight Polling). Params: agent_name (required), since_timestamp (required, ISO 8601 format like "2025-10-14T08:00:00Z"). Returns: {has_updates: boolean, counts: {decisions: N, messages: N, files: N}}. Token cost: ~5-10 tokens per check. Uses COUNT queries on t_decisions, t_agent_messages, t_file_changes with timestamp filtering. Enables efficient polling without full data retrieval.',
+            set_from_template: 'Set decision using template (FR-006). Params: template (required, template name), key (required), value (required), agent, layer (override), version, status (override), tags (override), scopes, plus any template-required fields. Applies template defaults (layer, status, tags) while allowing overrides. Validates required fields if specified by template. Returns: {success, key, key_id, version, template_used, applied_defaults, message}. Built-in templates: breaking_change, security_vulnerability, performance_optimization, deprecation, architecture_decision.',
+            create_template: 'Create new decision template (FR-006). Params: name (required, unique), defaults (required, object with layer/status/tags/priority), required_fields (optional, array of field names), created_by (optional, agent name). Returns: {success, template_id, template_name, message}. Example defaults: {"layer":"business","status":"active","tags":["breaking"]}. Validates layer/status values.',
+            list_templates: 'List all decision templates (FR-006). No params required. Returns: {templates: [{id, name, defaults, required_fields, created_by, created_at}], count}. Shows both built-in and custom templates.',
+            hard_delete: 'Permanently delete a decision (hard delete). Params: key (required). WARNING: IRREVERSIBLE - removes all records including version history, tags, scopes. Use cases: manual cleanup after decision-to-task migration, remove test/debug decisions, purge sensitive data. Unlike soft delete (status=deprecated), this completely removes from database. Idempotent - safe to call even if already deleted. Returns: {success, key, message}.',
+            add_decision_context: 'Add rich context to a decision (v3.2.2). Params: key (required), rationale (required), alternatives_considered (optional, JSON array), tradeoffs (optional, JSON object with pros/cons), decided_by (optional), related_task_id (optional), related_constraint_id (optional). Use to document WHY decisions were made, what alternatives were considered, and trade-offs. Multiple contexts can be attached to the same decision over time. Returns: {success, context_id, decision_key, message}.',
+            list_decision_contexts: 'List decision contexts with filters (v3.2.2). Params: decision_key (optional), related_task_id (optional), related_constraint_id (optional), decided_by (optional), limit (default: 50), offset (default: 0). Returns: {success, contexts: [{id, decision_key, rationale, alternatives_considered, tradeoffs, decided_by, decision_date, related_task_id, related_constraint_id}], count}. JSON fields (alternatives, tradeoffs) are automatically parsed.'
+        },
+        examples: {
+            set: '{ action: "set", key: "auth_method", value: "jwt", tags: ["security"] }',
+            get: '{ action: "get", key: "auth_method" }',
+            list: '{ action: "list", status: "active", layer: "infrastructure" }',
+            search_tags: '{ action: "search_tags", tags: ["security", "api"] }',
+            quick_set: '{ action: "quick_set", key: "api/instruments/oscillator-refactor", value: "Moved oscillator_type to MonophonicSynthConfig" }',
+            search_advanced: '{ action: "search_advanced", layers: ["business", "data"], tags_all: ["breaking", "v0.3.3"], tags_any: ["api", "synthesis"], exclude_tags: ["deprecated"], scopes: ["api/instruments/*"], updated_after: "2025-10-01", statuses: ["active", "draft"], search_text: "oscillator", sort_by: "updated", sort_order: "desc", limit: 20, offset: 0 }',
+            set_batch: '{ action: "set_batch", decisions: [{"key": "feat-1", "value": "...", "layer": "business"}, {"key": "feat-2", "value": "...", "layer": "data"}], atomic: true }',
+            has_updates: '{ action: "has_updates", agent_name: "my-agent", since_timestamp: "2025-10-14T08:00:00Z" }',
+            set_from_template: '{ action: "set_from_template", template: "breaking_change", key: "oscillator-type-moved", value: "oscillator_type moved to MonophonicSynthConfig" }',
+            create_template: '{ action: "create_template", name: "bug_fix", defaults: {"layer":"business","tags":["bug","fix"],"status":"active"}, created_by: "my-agent" }',
+            list_templates: '{ action: "list_templates" }',
+            hard_delete: '{ action: "hard_delete", key: "task_old_authentication_refactor" }'
+        },
+        documentation: {
+            tool_selection: 'docs/TOOL_SELECTION.md - Decision tree, tool comparison, when to use each tool (236 lines, ~12k tokens)',
+            tool_reference: 'docs/TOOL_REFERENCE.md - Parameter requirements, batch operations, templates (471 lines, ~24k tokens)',
+            workflows: 'docs/WORKFLOWS.md - Multi-step workflow examples, multi-agent coordination (602 lines, ~30k tokens)',
+            best_practices: 'docs/BEST_PRACTICES.md - Common errors, best practices, troubleshooting (345 lines, ~17k tokens)',
+            shared_concepts: 'docs/SHARED_CONCEPTS.md - Layer definitions, enum values (status/layer/priority), atomic mode (339 lines, ~17k tokens)'
+        }
+    };
+}
+/**
+ * Example action for decision tool
+ */
+export function decisionExample() {
+    return {
+        tool: 'decision',
+        description: 'Comprehensive decision tool examples without needing WebFetch access',
+        scenarios: {
+            basic_usage: {
+                title: 'Basic Decision Management',
+                examples: [
+                    {
+                        scenario: 'Record API design decision',
+                        request: '{ action: "set", key: "api_auth_method", value: "JWT with refresh tokens", layer: "business", tags: ["api", "security", "authentication"] }',
+                        explanation: 'Documents the choice of authentication method for the API'
+                    },
+                    {
+                        scenario: 'Retrieve a decision',
+                        request: '{ action: "get", key: "api_auth_method" }',
+                        response_structure: '{ key, value, layer, status, version, tags, scopes, decided_by, updated_at }'
+                    },
+                    {
+                        scenario: 'List all active decisions',
+                        request: '{ action: "list", status: "active", limit: 20 }',
+                        explanation: 'Returns active decisions with metadata for browsing'
+                    }
+                ]
+            },
+            advanced_filtering: {
+                title: 'Advanced Search and Filtering',
+                examples: [
+                    {
+                        scenario: 'Find all security-related decisions in business layer',
+                        request: '{ action: "search_advanced", layers: ["business"], tags_any: ["security", "authentication"], status: ["active"], sort_by: "updated", sort_order: "desc" }',
+                        explanation: 'Combines layer filtering, tag matching, and sorting'
+                    },
+                    {
+                        scenario: 'Search within API scope with multiple tags',
+                        request: '{ action: "search_advanced", scopes: ["api/*"], tags_all: ["breaking", "v2.0"], updated_after: "2025-01-01" }',
+                        explanation: 'Uses scope wildcards and timestamp filtering for recent breaking changes'
+                    }
+                ]
+            },
+            versioning_workflow: {
+                title: 'Version Management',
+                steps: [
+                    {
+                        step: 1,
+                        action: 'Create initial decision',
+                        request: '{ action: "set", key: "database_choice", value: "PostgreSQL", layer: "data", version: "1.0.0", tags: ["database"] }'
+                    },
+                    {
+                        step: 2,
+                        action: 'Update decision (creates new version)',
+                        request: '{ action: "set", key: "database_choice", value: "PostgreSQL with read replicas", layer: "data", version: "1.1.0", tags: ["database", "scaling"] }'
+                    },
+                    {
+                        step: 3,
+                        action: 'View version history',
+                        request: '{ action: "versions", key: "database_choice" }',
+                        result: 'Returns all versions with timestamps and changes'
+                    }
+                ]
+            },
+            batch_operations: {
+                title: 'Batch Decision Management',
+                examples: [
+                    {
+                        scenario: 'Record multiple related decisions atomically',
+                        request: '{ action: "set_batch", decisions: [{"key": "cache_layer", "value": "Redis", "layer": "infrastructure"}, {"key": "cache_ttl", "value": "3600", "layer": "infrastructure"}], atomic: true }',
+                        explanation: 'All decisions succeed or all fail together (atomic mode)'
+                    },
+                    {
+                        scenario: 'Best-effort batch insert',
+                        request: '{ action: "set_batch", decisions: [{...}, {...}, {...}], atomic: false }',
+                        explanation: 'Each decision processed independently - partial success allowed'
+                    }
+                ]
+            },
+            templates: {
+                title: 'Using Decision Templates',
+                examples: [
+                    {
+                        scenario: 'Use built-in breaking_change template',
+                        request: '{ action: "set_from_template", template: "breaking_change", key: "api_remove_legacy_endpoint", value: "Removed /v1/users endpoint - migrate to /v2/users" }',
+                        explanation: 'Automatically applies layer=business, tags=["breaking"], status=active'
+                    },
+                    {
+                        scenario: 'Create custom template',
+                        request: '{ action: "create_template", name: "feature_flag", defaults: {"layer": "presentation", "tags": ["feature-flag"], "status": "draft"}, created_by: "backend-team" }',
+                        explanation: 'Define reusable templates for common decision patterns'
+                    }
+                ]
+            },
+            quick_set_inference: {
+                title: 'Quick Set with Smart Defaults',
+                examples: [
+                    {
+                        scenario: 'Auto-infer layer from key prefix',
+                        request: '{ action: "quick_set", key: "api/instruments/oscillator-refactor", value: "Moved oscillator_type to MonophonicSynthConfig" }',
+                        inferred: 'layer=presentation (from api/*), tags=["instruments", "oscillator-refactor"], scope=api/instruments'
+                    },
+                    {
+                        scenario: 'Database decision with auto-inference',
+                        request: '{ action: "quick_set", key: "db/users/add-email-index", value: "Added index on email column" }',
+                        inferred: 'layer=data (from db/*), tags=["users", "add-email-index"]'
+                    }
+                ]
+            }
+        },
+        best_practices: {
+            key_naming: [
+                'Use hierarchical keys: "api/users/authentication"',
+                'Prefix with layer hint: api/* → presentation, db/* → data, service/* → business',
+                'Use descriptive names that explain the decision context'
+            ],
+            tagging: [
+                'Tag with relevant categories: security, performance, breaking, etc.',
+                'Include version tags for release-specific decisions',
+                'Use consistent tag naming conventions across team'
+            ],
+            versioning: [
+                'Use semantic versioning: 1.0.0, 1.1.0, 2.0.0',
+                'Increment major version for breaking changes',
+                'Document rationale in decision value text'
+            ],
+            cleanup: [
+                'Mark deprecated decisions with status="deprecated"',
+                'Use hard_delete only for sensitive data or migration cleanup',
+                'Link related decisions using scopes'
+            ]
+        }
+    };
+}
 //# sourceMappingURL=context.js.map