sqlew 3.7.4 → 3.8.0

package/dist/tools/context/actions/set-from-template.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"set-from-template.js","sourceRoot":"","sources":["../../../../src/tools/context/actions/set-from-template.ts"],"names":[],"mappings":"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"}

package/dist/tools/context/actions/set.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Set or update a decision in the context
+ * Auto-detects numeric vs string values and routes to appropriate table
+ * Supports tags, layers, scopes, and version tracking
+ */
+import { DatabaseAdapter } from '../../../adapters/index.js';
+import type { SetDecisionParams, SetDecisionResponse } from '../types.js';
+/**
+ * Set or update a decision in the context
+ *
+ * @param params - Decision parameters
+ * @param adapter - Optional database adapter (for testing)
+ * @returns Response with success status and metadata
+ */
+export declare function setDecision(params: SetDecisionParams, adapter?: DatabaseAdapter): Promise<SetDecisionResponse>;
+//# sourceMappingURL=set.d.ts.map

package/dist/tools/context/actions/set.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"set.d.ts","sourceRoot":"","sources":["../../../../src/tools/context/actions/set.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAY7D,OAAO,KAAK,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAE1E;;;;;;GAMG;AACH,wBAAsB,WAAW,CAC/B,MAAM,EAAE,iBAAiB,EACzB,OAAO,CAAC,EAAE,eAAe,GACxB,OAAO,CAAC,mBAAmB,CAAC,CAwC9B"}

package/dist/tools/context/actions/set.js

@@ -0,0 +1,56 @@
+/**
+ * Set or update a decision in the context
+ * Auto-detects numeric vs string values and routes to appropriate table
+ * Supports tags, layers, scopes, and version tracking
+ */
+import { getAdapter } from '../../../database.js';
+import { getProjectContext } from '../../../utils/project-context.js';
+import connectionManager from '../../../utils/connection-manager.js';
+import { debugLogFunctionEntry, debugLogFunctionExit, debugLogTransaction, debugLogCriticalError } from '../../../utils/debug-logger.js';
+import { validateActionParams } from '../internal/validation.js';
+import { setDecisionInternal } from '../internal/queries.js';
+/**
+ * Set or update a decision in the context
+ *
+ * @param params - Decision parameters
+ * @param adapter - Optional database adapter (for testing)
+ * @returns Response with success status and metadata
+ */
+export async function setDecision(params, adapter) {
+    debugLogFunctionEntry('setDecision', params);
+    // Validate parameters
+    try {
+        validateActionParams('decision', 'set', params);
+    }
+    catch (error) {
+        throw error;
+    }
+    const actualAdapter = adapter ?? getAdapter();
+    try {
+        debugLogTransaction('START', 'setDecision');
+        // Validate project context (Constraint #29 - fail-fast before mutations)
+        const projectId = getProjectContext().getProjectId();
+        // Use transaction for atomicity with connection retry
+        const result = await connectionManager.executeWithRetry(async () => {
+            return await actualAdapter.transaction(async (trx) => {
+                debugLogTransaction('COMMIT', 'setDecision-transaction-begin');
+                const internalResult = await setDecisionInternal(params, actualAdapter, projectId, trx);
+                debugLogTransaction('COMMIT', 'setDecision-transaction-end');
+                return internalResult;
+            });
+        });
+        debugLogFunctionExit('setDecision', true, result);
+        return result;
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        debugLogCriticalError('setDecision', error, {
+            function: 'setDecision',
+            params
+        });
+        debugLogTransaction('ROLLBACK', 'setDecision');
+        debugLogFunctionExit('setDecision', false, undefined, error);
+        throw new Error(`Failed to set decision: ${message}`);
+    }
+}
+//# sourceMappingURL=set.js.map

package/dist/tools/context/actions/set.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"set.js","sourceRoot":"","sources":["../../../../src/tools/context/actions/set.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAClD,OAAO,EAAE,iBAAiB,EAAE,MAAM,mCAAmC,CAAC;AACtE,OAAO,iBAAiB,MAAM,sCAAsC,CAAC;AACrE,OAAO,EACL,qBAAqB,EACrB,oBAAoB,EACpB,mBAAmB,EACnB,qBAAqB,EACtB,MAAM,gCAAgC,CAAC;AACxC,OAAO,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAC;AACjE,OAAO,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAG7D;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAC/B,MAAyB,EACzB,OAAyB;IAEzB,qBAAqB,CAAC,aAAa,EAAE,MAAM,CAAC,CAAC;IAE7C,sBAAsB;IACtB,IAAI,CAAC;QACH,oBAAoB,CAAC,UAAU,EAAE,KAAK,EAAE,MAAM,CAAC,CAAC;IAClD,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,KAAK,CAAC;IACd,CAAC;IAED,MAAM,aAAa,GAAG,OAAO,IAAI,UAAU,EAAE,CAAC;IAE9C,IAAI,CAAC;QACH,mBAAmB,CAAC,OAAO,EAAE,aAAa,CAAC,CAAC;QAE5C,yEAAyE;QACzE,MAAM,SAAS,GAAG,iBAAiB,EAAE,CAAC,YAAY,EAAE,CAAC;QAErD,sDAAsD;QACtD,MAAM,MAAM,GAAG,MAAM,iBAAiB,CAAC,gBAAgB,CAAC,KAAK,IAAI,EAAE;YACjE,OAAO,MAAM,aAAa,CAAC,WAAW,CAAC,KAAK,EAAE,GAAG,EAAE,EAAE;gBACnD,mBAAmB,CAAC,QAAQ,EAAE,+BAA+B,CAAC,CAAC;gBAC/D,MAAM,cAAc,GAAG,MAAM,mBAAmB,CAAC,MAAM,EAAE,aAAa,EAAE,SAAS,EAAE,GAAG,CAAC,CAAC;gBACxF,mBAAmB,CAAC,QAAQ,EAAE,6BAA6B,CAAC,CAAC;gBAC7D,OAAO,cAAc,CAAC;YACxB,CAAC,CAAC,CAAC;QACL,CAAC,CAAC,CAAC;QAEH,oBAAoB,CAAC,aAAa,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC;QAClD,OAAO,MAAM,CAAC;IAChB,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,OAAO,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QACvE,qBAAqB,CAAC,aAAa,EAAE,KAAK,EAAE;YAC1C,QAAQ,EAAE,aAAa;YACvB,MAAM;SACP,CAAC,CAAC;QACH,mBAAmB,CAAC,UAAU,EAAE,aAAa,CAAC,CAAC;QAC/C,oBAAoB,CAAC,aAAa,EAAE,KAAK,EAAE,SAAS,EAAE,KAAK,CAAC,CAAC;QAC7D,MAAM,IAAI,KAAK,CAAC,2BAA2B,OAAO,EAAE,CAAC,CAAC;IACxD,CAAC;AACH,CAAC"}

package/dist/tools/context/actions/versions.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Get version history for a specific decision key
+ * Returns all historical versions ordered by timestamp (newest first)
+ */
+import { DatabaseAdapter } from '../../../adapters/index.js';
+import type { GetVersionsParams, GetVersionsResponse } from '../types.js';
+/**
+ * Get version history for a decision
+ *
+ * @param params - Decision key to get history for
+ * @param adapter - Optional database adapter (for testing)
+ * @returns Array of historical versions with metadata
+ */
+export declare function getVersions(params: GetVersionsParams, adapter?: DatabaseAdapter): Promise<GetVersionsResponse>;
+//# sourceMappingURL=versions.d.ts.map

package/dist/tools/context/actions/versions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"versions.d.ts","sourceRoot":"","sources":["../../../../src/tools/context/actions/versions.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAI7D,OAAO,KAAK,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAE1E;;;;;;GAMG;AACH,wBAAsB,WAAW,CAC/B,MAAM,EAAE,iBAAiB,EACzB,OAAO,CAAC,EAAE,eAAe,GACxB,OAAO,CAAC,mBAAmB,CAAC,CAsE9B"}

package/dist/tools/context/actions/versions.js

@@ -0,0 +1,69 @@
+/**
+ * Get version history for a specific decision key
+ * Returns all historical versions ordered by timestamp (newest first)
+ */
+import { getAdapter } from '../../../database.js';
+import { getProjectContext } from '../../../utils/project-context.js';
+import { validateActionParams } from '../internal/validation.js';
+/**
+ * Get version history for a decision
+ *
+ * @param params - Decision key to get history for
+ * @param adapter - Optional database adapter (for testing)
+ * @returns Array of historical versions with metadata
+ */
+export async function getVersions(params, adapter) {
+    // Validate parameters
+    try {
+        validateActionParams('decision', 'versions', params);
+    }
+    catch (error) {
+        throw error;
+    }
+    const actualAdapter = adapter ?? getAdapter();
+    const knex = actualAdapter.getKnex();
+    // Validate project context
+    const projectId = getProjectContext().getProjectId();
+    // Validate required parameter
+    if (!params.key || params.key.trim() === '') {
+        throw new Error('Parameter "key" is required and cannot be empty');
+    }
+    try {
+        // Get key_id for the decision
+        const keyResult = await knex('m_context_keys')
+            .where({ key: params.key })
+            .first('id');
+        if (!keyResult) {
+            // Key doesn't exist, return empty history
+            return {
+                key: params.key,
+                history: [],
+                count: 0
+            };
+        }
+        const keyId = keyResult.id;
+        // Query t_decision_history with agent join
+        const rows = await knex('t_decision_history as dh')
+            .leftJoin('m_agents as a', 'dh.agent_id', 'a.id')
+            .where({ 'dh.key_id': keyId, 'dh.project_id': projectId })
+            .select('dh.version', 'dh.value', 'a.name as agent_name', knex.raw(`datetime(dh.ts, 'unixepoch') as timestamp`))
+            .orderBy('dh.ts', 'desc');
+        // Transform to response format
+        const history = rows.map(row => ({
+            version: row.version,
+            value: row.value,
+            agent: row.agent_name,
+            timestamp: row.timestamp
+        }));
+        return {
+            key: params.key,
+            history: history,
+            count: history.length
+        };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`Failed to get versions: ${message}`);
+    }
+}
+//# sourceMappingURL=versions.js.map

package/dist/tools/context/actions/versions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"versions.js","sourceRoot":"","sources":["../../../../src/tools/context/actions/versions.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAClD,OAAO,EAAE,iBAAiB,EAAE,MAAM,mCAAmC,CAAC;AACtE,OAAO,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAC;AAGjE;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAC/B,MAAyB,EACzB,OAAyB;IAEzB,sBAAsB;IACtB,IAAI,CAAC;QACH,oBAAoB,CAAC,UAAU,EAAE,UAAU,EAAE,MAAM,CAAC,CAAC;IACvD,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,KAAK,CAAC;IACd,CAAC;IAED,MAAM,aAAa,GAAG,OAAO,IAAI,UAAU,EAAE,CAAC;IAC9C,MAAM,IAAI,GAAG,aAAa,CAAC,OAAO,EAAE,CAAC;IAErC,2BAA2B;IAC3B,MAAM,SAAS,GAAG,iBAAiB,EAAE,CAAC,YAAY,EAAE,CAAC;IAErD,8BAA8B;IAC9B,IAAI,CAAC,MAAM,CAAC,GAAG,IAAI,MAAM,CAAC,GAAG,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC;QAC5C,MAAM,IAAI,KAAK,CAAC,iDAAiD,CAAC,CAAC;IACrE,CAAC;IAED,IAAI,CAAC;QACH,8BAA8B;QAC9B,MAAM,SAAS,GAAG,MAAM,IAAI,CAAC,gBAAgB,CAAC;aAC3C,KAAK,CAAC,EAAE,GAAG,EAAE,MAAM,CAAC,GAAG,EAAE,CAAC;aAC1B,KAAK,CAAC,IAAI,CAA+B,CAAC;QAE7C,IAAI,CAAC,SAAS,EAAE,CAAC;YACf,0CAA0C;YAC1C,OAAO;gBACL,GAAG,EAAE,MAAM,CAAC,GAAG;gBACf,OAAO,EAAE,EAAE;gBACX,KAAK,EAAE,CAAC;aACT,CAAC;QACJ,CAAC;QAED,MAAM,KAAK,GAAG,SAAS,CAAC,EAAE,CAAC;QAE3B,2CAA2C;QAC3C,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,0BAA0B,CAAC;aAChD,QAAQ,CAAC,eAAe,EAAE,aAAa,EAAE,MAAM,CAAC;aAChD,KAAK,CAAC,EAAE,WAAW,EAAE,KAAK,EAAE,eAAe,EAAE,SAAS,EAAE,CAAC;aACzD,MAAM,CACL,YAAY,EACZ,UAAU,EACV,sBAAsB,EACtB,IAAI,CAAC,GAAG,CAAC,2CAA2C,CAAC,CACtD;aACA,OAAO,CAAC,OAAO,EAAE,MAAM,CAKtB,CAAC;QAEL,+BAA+B;QAC/B,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;YAC/B,OAAO,EAAE,GAAG,CAAC,OAAO;YACpB,KAAK,EAAE,GAAG,CAAC,KAAK;YAChB,KAAK,EAAE,GAAG,CAAC,UAAU;YACrB,SAAS,EAAE,GAAG,CAAC,SAAS;SACzB,CAAC,CAAC,CAAC;QAEJ,OAAO;YACL,GAAG,EAAE,MAAM,CAAC,GAAG;YACf,OAAO,EAAE,OAAO;YAChB,KAAK,EAAE,OAAO,CAAC,MAAM;SACtB,CAAC;IACJ,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,OAAO,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QACvE,MAAM,IAAI,KAAK,CAAC,2BAA2B,OAAO,EAAE,CAAC,CAAC;IACxD,CAAC;AACH,CAAC"}

package/dist/tools/context/help/example.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Example action for decision tool
+ */
+export declare function decisionExample(): any;
+//# sourceMappingURL=example.d.ts.map

package/dist/tools/context/help/example.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"example.d.ts","sourceRoot":"","sources":["../../../../src/tools/context/help/example.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,wBAAgB,eAAe,IAAI,GAAG,CA2FrC"}

package/dist/tools/context/help/example.js

@@ -0,0 +1,96 @@
+/**
+ * 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 }'
+                    }
+                ]
+            },
+            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" }'
+                    }
+                ]
+            },
+            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: 'View version history',
+                        request: '{ action: "versions", key: "database_choice" }'
+                    }
+                ]
+            },
+            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 }'
+                    }
+                ]
+            },
+            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" }'
+                    }
+                ]
+            },
+            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"]'
+                    }
+                ]
+            }
+        },
+        best_practices: {
+            key_naming: [
+                'Use hierarchical keys: "api/users/authentication"',
+                'Prefix with layer hint: api/* → presentation, db/* → data',
+                'Use descriptive names that explain the decision context'
+            ],
+            tagging: [
+                'Tag with relevant categories: security, performance, breaking',
+                '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'
+            ]
+        }
+    };
+}
+//# sourceMappingURL=example.js.map

package/dist/tools/context/help/example.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"example.js","sourceRoot":"","sources":["../../../../src/tools/context/help/example.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,MAAM,UAAU,eAAe;IAC7B,OAAO;QACL,IAAI,EAAE,UAAU;QAChB,WAAW,EAAE,sEAAsE;QACnF,SAAS,EAAE;YACT,WAAW,EAAE;gBACX,KAAK,EAAE,2BAA2B;gBAClC,QAAQ,EAAE;oBACR;wBACE,QAAQ,EAAE,4BAA4B;wBACtC,OAAO,EAAE,6IAA6I;wBACtJ,WAAW,EAAE,2DAA2D;qBACzE;oBACD;wBACE,QAAQ,EAAE,qBAAqB;wBAC/B,OAAO,EAAE,2CAA2C;wBACpD,kBAAkB,EAAE,8EAA8E;qBACnG;iBACF;aACF;YACD,kBAAkB,EAAE;gBAClB,KAAK,EAAE,+BAA+B;gBACtC,QAAQ,EAAE;oBACR;wBACE,QAAQ,EAAE,uDAAuD;wBACjE,OAAO,EAAE,2JAA2J;qBACrK;iBACF;aACF;YACD,mBAAmB,EAAE;gBACnB,KAAK,EAAE,oBAAoB;gBAC3B,KAAK,EAAE;oBACL;wBACE,IAAI,EAAE,CAAC;wBACP,MAAM,EAAE,yBAAyB;wBACjC,OAAO,EAAE,qHAAqH;qBAC/H;oBACD;wBACE,IAAI,EAAE,CAAC;wBACP,MAAM,EAAE,sBAAsB;wBAC9B,OAAO,EAAE,gDAAgD;qBAC1D;iBACF;aACF;YACD,gBAAgB,EAAE;gBAChB,KAAK,EAAE,2BAA2B;gBAClC,QAAQ,EAAE;oBACR;wBACE,QAAQ,EAAE,8CAA8C;wBACxD,OAAO,EAAE,2LAA2L;qBACrM;iBACF;aACF;YACD,SAAS,EAAE;gBACT,KAAK,EAAE,0BAA0B;gBACjC,QAAQ,EAAE;oBACR;wBACE,QAAQ,EAAE,uCAAuC;wBACjD,OAAO,EAAE,sIAAsI;qBAChJ;iBACF;aACF;YACD,mBAAmB,EAAE;gBACnB,KAAK,EAAE,+BAA+B;gBACtC,QAAQ,EAAE;oBACR;wBACE,QAAQ,EAAE,kCAAkC;wBAC5C,OAAO,EAAE,8HAA8H;wBACvI,QAAQ,EAAE,8EAA8E;qBACzF;iBACF;aACF;SACF;QACD,cAAc,EAAE;YACd,UAAU,EAAE;gBACV,mDAAmD;gBACnD,2DAA2D;gBAC3D,yDAAyD;aAC1D;YACD,OAAO,EAAE;gBACP,+DAA+D;gBAC/D,qDAAqD;gBACrD,mDAAmD;aACpD;YACD,UAAU,EAAE;gBACV,8CAA8C;gBAC9C,8CAA8C;gBAC9C,2CAA2C;aAC5C;SACF;KACF,CAAC;AACJ,CAAC"}

package/dist/tools/context/help/help.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Help action for decision tool
+ */
+export declare function decisionHelp(): any;
+//# sourceMappingURL=help.d.ts.map

package/dist/tools/context/help/help.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"help.d.ts","sourceRoot":"","sources":["../../../../src/tools/context/help/help.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,wBAAgB,YAAY,IAAI,GAAG,CA4DlC"}

package/dist/tools/context/help/help.js

@@ -0,0 +1,65 @@
+/**
+ * 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 create_batch", "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)'
+            },
+            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)',
+            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). Auto-infers layer, tags, scope from key',
+            search_advanced: 'Advanced query with complex filtering (FR-004). Supports layers, tags, scopes, temporal filters',
+            set_batch: 'Batch set decisions (FR-005). Max 50 items. Atomic or non-atomic modes',
+            has_updates: 'Check for updates since timestamp (FR-003 Phase A). Lightweight polling mechanism',
+            set_from_template: 'Set decision using template (FR-006). Applies defaults and validates required fields',
+            create_template: 'Create new decision template (FR-006). Define reusable defaults',
+            list_templates: 'List all decision templates (FR-006)',
+            hard_delete: 'Permanently delete a decision. WARNING: IRREVERSIBLE',
+            add_decision_context: 'Add rich context to a decision (v3.2.2). Rationale, alternatives, tradeoffs',
+            list_decision_contexts: 'List decision contexts with filters (v3.2.2)'
+        },
+        documentation: {
+            tool_selection: 'docs/TOOL_SELECTION.md - Decision tree, tool comparison',
+            tool_reference: 'docs/TOOL_REFERENCE.md - Parameter requirements, batch operations',
+            workflows: 'docs/WORKFLOWS.md - Multi-step workflow examples',
+            best_practices: 'docs/BEST_PRACTICES.md - Common errors, best practices',
+            shared_concepts: 'docs/SHARED_CONCEPTS.md - Layer definitions, enum values'
+        }
+    };
+}
+//# sourceMappingURL=help.js.map

package/dist/tools/context/help/help.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"help.js","sourceRoot":"","sources":["../../../../src/tools/context/help/help.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,MAAM,UAAU,YAAY;IAC1B,OAAO;QACL,IAAI,EAAE,UAAU;QAChB,WAAW,EAAE,iEAAiE;QAC9E,IAAI,EAAE,sHAAsH;QAC5H,OAAO,EAAE;YACP,KAAK,EAAE,6CAA6C;YACpD,SAAS,EAAE,+GAA+G;YAC1H,aAAa,EAAE;gBACb,OAAO,EAAE;oBACP,uIAAuI;oBACvI,oKAAoK;oBACpK,8LAA8L;oBAC9L,wJAAwJ;oBACxJ,sHAAsH;oBACtH,6IAA6I;iBAC9I;gBACD,SAAS,EAAE;oBACT,iHAAiH;oBACjH,gIAAgI;oBAChI,mJAAmJ;oBACnJ,yGAAyG;oBACzG,oHAAoH;oBACpH,qGAAqG;iBACtG;aACF;YACD,OAAO,EAAE;gBACP,WAAW,EAAE,sCAAsC;gBACnD,aAAa,EAAE,mDAAmD;gBAClE,eAAe,EAAE,qDAAqD;gBACtE,WAAW,EAAE,wDAAwD;aACtE;YACD,YAAY,EAAE,mKAAmK;SAClL;QACD,OAAO,EAAE;YACP,GAAG,EAAE,8GAA8G;YACnH,GAAG,EAAE,2GAA2G;YAChH,IAAI,EAAE,sEAAsE;YAC5E,WAAW,EAAE,8EAA8E;YAC3F,YAAY,EAAE,2EAA2E;YACzF,QAAQ,EAAE,4DAA4D;YACtE,SAAS,EAAE,iFAAiF;YAC5F,eAAe,EAAE,iGAAiG;YAClH,SAAS,EAAE,wEAAwE;YACnF,WAAW,EAAE,mFAAmF;YAChG,iBAAiB,EAAE,sFAAsF;YACzG,eAAe,EAAE,iEAAiE;YAClF,cAAc,EAAE,sCAAsC;YACtD,WAAW,EAAE,sDAAsD;YACnE,oBAAoB,EAAE,6EAA6E;YACnG,sBAAsB,EAAE,8CAA8C;SACvE;QACD,aAAa,EAAE;YACb,cAAc,EAAE,yDAAyD;YACzE,cAAc,EAAE,mEAAmE;YACnF,SAAS,EAAE,kDAAkD;YAC7D,cAAc,EAAE,wDAAwD;YACxE,eAAe,EAAE,0DAA0D;SAC5E;KACF,CAAC;AACJ,CAAC"}

package/dist/tools/context/index.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Context/Decision tool - Barrel export
+ *
+ * Exports all decision-related actions from modular structure
+ */
+export { setDecision } from './actions/set.js';
+export { getDecision } from './actions/get.js';
+export { getContext } from './actions/list.js';
+export { searchByTags } from './actions/search-tags.js';
+export { searchByLayer } from './actions/search-layer.js';
+export { searchAdvanced } from './actions/search-advanced.js';
+export { getVersions } from './actions/versions.js';
+export { quickSetDecision } from './actions/quick-set.js';
+export { setDecisionBatch } from './actions/batch-set.js';
+export { hasUpdates } from './actions/has-updates.js';
+export { setFromTemplate } from './actions/set-from-template.js';
+export { createTemplate } from './actions/create-template.js';
+export { listTemplates } from './actions/list-templates.js';
+export { hardDeleteDecision } from './actions/hard-delete.js';
+export { addDecisionContextAction } from './actions/add-context.js';
+export { listDecisionContextsAction } from './actions/list-contexts.js';
+export { decisionHelp } from './help/help.js';
+export { decisionExample } from './help/example.js';
+export type { SetDecisionParams, GetContextParams, GetDecisionParams, SetDecisionResponse, GetContextResponse, GetDecisionResponse, TaggedDecision, Status, SearchByTagsParams, SearchByTagsResponse, GetVersionsParams, GetVersionsResponse, SearchByLayerParams, SearchByLayerResponse, QuickSetDecisionParams, QuickSetDecisionResponse, SearchAdvancedParams, SearchAdvancedResponse, SetDecisionBatchParams, SetDecisionBatchResponse, SetFromTemplateParams, SetFromTemplateResponse, CreateTemplateParams, CreateTemplateResponse, ListTemplatesParams, ListTemplatesResponse, HasUpdatesParams, HasUpdatesResponse, HardDeleteDecisionParams, HardDeleteDecisionResponse, DecisionAction } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/tools/context/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/tools/context/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC/C,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC/C,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAC/C,OAAO,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AACxD,OAAO,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAC1D,OAAO,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAC9D,OAAO,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AACpD,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AACtD,OAAO,EAAE,eAAe,EAAE,MAAM,gCAAgC,CAAC;AACjE,OAAO,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAC9D,OAAO,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AAC5D,OAAO,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAC9D,OAAO,EAAE,wBAAwB,EAAE,MAAM,0BAA0B,CAAC;AACpE,OAAO,EAAE,0BAA0B,EAAE,MAAM,4BAA4B,CAAC;AAGxE,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAGpD,YAAY,EACV,iBAAiB,EACjB,gBAAgB,EAChB,iBAAiB,EACjB,mBAAmB,EACnB,kBAAkB,EAClB,mBAAmB,EACnB,cAAc,EACd,MAAM,EACN,kBAAkB,EAClB,oBAAoB,EACpB,iBAAiB,EACjB,mBAAmB,EACnB,mBAAmB,EACnB,qBAAqB,EACrB,sBAAsB,EACtB,wBAAwB,EACxB,oBAAoB,EACpB,sBAAsB,EACtB,sBAAsB,EACtB,wBAAwB,EACxB,qBAAqB,EACrB,uBAAuB,EACvB,oBAAoB,EACpB,sBAAsB,EACtB,mBAAmB,EACnB,qBAAqB,EACrB,gBAAgB,EAChB,kBAAkB,EAClB,wBAAwB,EACxB,0BAA0B,EAC1B,cAAc,EACf,MAAM,YAAY,CAAC"}

package/dist/tools/context/index.js

@@ -0,0 +1,26 @@
+/**
+ * Context/Decision tool - Barrel export
+ *
+ * Exports all decision-related actions from modular structure
+ */
+// Action exports
+export { setDecision } from './actions/set.js';
+export { getDecision } from './actions/get.js';
+export { getContext } from './actions/list.js';
+export { searchByTags } from './actions/search-tags.js';
+export { searchByLayer } from './actions/search-layer.js';
+export { searchAdvanced } from './actions/search-advanced.js';
+export { getVersions } from './actions/versions.js';
+export { quickSetDecision } from './actions/quick-set.js';
+export { setDecisionBatch } from './actions/batch-set.js';
+export { hasUpdates } from './actions/has-updates.js';
+export { setFromTemplate } from './actions/set-from-template.js';
+export { createTemplate } from './actions/create-template.js';
+export { listTemplates } from './actions/list-templates.js';
+export { hardDeleteDecision } from './actions/hard-delete.js';
+export { addDecisionContextAction } from './actions/add-context.js';
+export { listDecisionContextsAction } from './actions/list-contexts.js';
+// Help exports
+export { decisionHelp } from './help/help.js';
+export { decisionExample } from './help/example.js';
+//# sourceMappingURL=index.js.map

package/dist/tools/context/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/tools/context/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,iBAAiB;AACjB,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC/C,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC/C,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAC/C,OAAO,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AACxD,OAAO,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAC1D,OAAO,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAC9D,OAAO,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AACpD,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AACtD,OAAO,EAAE,eAAe,EAAE,MAAM,gCAAgC,CAAC;AACjE,OAAO,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAC9D,OAAO,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AAC5D,OAAO,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAC9D,OAAO,EAAE,wBAAwB,EAAE,MAAM,0BAA0B,CAAC;AACpE,OAAO,EAAE,0BAA0B,EAAE,MAAM,4BAA4B,CAAC;AAExE,eAAe;AACf,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/tools/context/internal/queries.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Shared database queries for context/decision operations
+ */
+import { DatabaseAdapter } from '../../../adapters/index.js';
+import { Knex } from 'knex';
+import type { SetDecisionParams, SetDecisionResponse } from '../types.js';
+/**
+ * Internal helper: Set decision without wrapping in transaction
+ * Used by setDecision (with transaction) and setDecisionBatch (manages its own transaction)
+ *
+ * @param params - Decision parameters
+ * @param adapter - Database adapter instance
+ * @param projectId - Project ID
+ * @param trx - Optional transaction
+ * @returns Response with success status and metadata
+ */
+export declare function setDecisionInternal(params: SetDecisionParams, adapter: DatabaseAdapter, projectId: number, trx?: Knex.Transaction): Promise<SetDecisionResponse>;
+//# sourceMappingURL=queries.d.ts.map

package/dist/tools/context/internal/queries.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"queries.d.ts","sourceRoot":"","sources":["../../../../src/tools/context/internal/queries.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAC7D,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAW5B,OAAO,KAAK,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAE1E;;;;;;;;;GASG;AACH,wBAAsB,mBAAmB,CACvC,MAAM,EAAE,iBAAiB,EACzB,OAAO,EAAE,eAAe,EACxB,SAAS,EAAE,MAAM,EACjB,GAAG,CAAC,EAAE,IAAI,CAAC,WAAW,GACrB,OAAO,CAAC,mBAAmB,CAAC,CAmK9B"}

package/dist/tools/context/internal/queries.js

@@ -0,0 +1,160 @@
+/**
+ * Shared database queries for context/decision operations
+ */
+import { getOrCreateAgent, getOrCreateContextKey, getOrCreateTag, getOrCreateScope, getLayerId } from '../../../database.js';
+import { STRING_TO_STATUS, DEFAULT_VERSION, DEFAULT_STATUS } from '../../../constants.js';
+import { logDecisionSet, logDecisionUpdate, recordDecisionHistory } from '../../../utils/activity-logging.js';
+import { parseStringArray } from '../../../utils/param-parser.js';
+/**
+ * Internal helper: Set decision without wrapping in transaction
+ * Used by setDecision (with transaction) and setDecisionBatch (manages its own transaction)
+ *
+ * @param params - Decision parameters
+ * @param adapter - Database adapter instance
+ * @param projectId - Project ID
+ * @param trx - Optional transaction
+ * @returns Response with success status and metadata
+ */
+export async function setDecisionInternal(params, adapter, projectId, trx) {
+    const knex = trx || adapter.getKnex();
+    // Validate required parameters
+    if (!params.key || params.key.trim() === '') {
+        throw new Error('Parameter "key" is required and cannot be empty');
+    }
+    if (params.value === undefined || params.value === null) {
+        throw new Error('Parameter "value" is required');
+    }
+    // Determine if value is numeric
+    const isNumeric = typeof params.value === 'number';
+    const value = params.value;
+    // Set defaults
+    const version = params.version || DEFAULT_VERSION;
+    const status = params.status ? STRING_TO_STATUS[params.status] : DEFAULT_STATUS;
+    const agentName = params.agent || 'system';
+    // Validate layer if provided
+    let layerId = null;
+    if (params.layer) {
+        const validLayers = ['presentation', 'business', 'data', 'infrastructure', 'cross-cutting', 'documentation'];
+        if (!validLayers.includes(params.layer)) {
+            throw new Error(`Invalid layer. Must be one of: ${validLayers.join(', ')}`);
+        }
+        layerId = await getLayerId(adapter, params.layer, trx);
+        if (layerId === null) {
+            throw new Error(`Layer not found in database: ${params.layer}`);
+        }
+    }
+    // Scope validation warning (v3.8.0)
+    if (!params.scopes || params.scopes.length === 0) {
+        console.warn(`⚠️  Decision "${params.key}" has no scope specified. Defaulting to GLOBAL scope.`);
+        console.warn(`   💡 Consider using scopes for better organization:`);
+        console.warn(`      - "FEATURE:<name>" for feature-specific decisions`);
+        console.warn(`      - "COMPONENT:<name>" for component-level decisions`);
+        console.warn(`      - "MODULE:<name>" for module-scoped decisions`);
+        console.warn(`      - "GLOBAL" for project-wide decisions (current default)`);
+    }
+    // Get or create master records
+    const agentId = await getOrCreateAgent(adapter, agentName, trx);
+    const keyId = await getOrCreateContextKey(adapter, params.key, trx);
+    // Current timestamp
+    const ts = Math.floor(Date.now() / 1000);
+    // Check if decision already exists for activity logging
+    const existingDecision = await knex(isNumeric ? 't_decisions_numeric' : 't_decisions')
+        .where({ key_id: keyId, project_id: projectId })
+        .first();
+    // Insert or update decision based on value type
+    const tableName = isNumeric ? 't_decisions_numeric' : 't_decisions';
+    const decisionData = {
+        key_id: keyId,
+        project_id: projectId,
+        value: isNumeric ? value : String(value),
+        agent_id: agentId,
+        layer_id: layerId,
+        version: version,
+        status: status,
+        ts: ts
+    };
+    // Use transaction-aware upsert
+    const conflictColumns = ['key_id', 'project_id'];
+    const updateColumns = Object.keys(decisionData).filter(key => !conflictColumns.includes(key));
+    const updateData = updateColumns.reduce((acc, col) => {
+        acc[col] = decisionData[col];
+        return acc;
+    }, {});
+    await knex(tableName)
+        .insert(decisionData)
+        .onConflict(conflictColumns)
+        .merge(updateData);
+    // Activity logging (replaces triggers)
+    if (existingDecision) {
+        // Update case - log update and record history
+        await logDecisionUpdate(knex, {
+            key: params.key,
+            old_value: String(existingDecision.value),
+            new_value: String(value),
+            old_version: existingDecision.version,
+            new_version: version,
+            agent_id: agentId,
+            layer_id: layerId || undefined
+        });
+        await recordDecisionHistory(knex, {
+            key_id: keyId,
+            version: existingDecision.version,
+            value: String(existingDecision.value),
+            agent_id: existingDecision.agent_id,
+            ts: existingDecision.ts
+        });
+    }
+    else {
+        // New decision case - log set
+        await logDecisionSet(knex, {
+            key: params.key,
+            value: String(value),
+            version: version,
+            status: status,
+            agent_id: agentId,
+            layer_id: layerId || undefined
+        });
+    }
+    // Handle m_tags (many-to-many)
+    if (params.tags && params.tags.length > 0) {
+        const tags = parseStringArray(params.tags);
+        // Clear existing tags for this project
+        await knex('t_decision_tags')
+            .where({ decision_key_id: keyId, project_id: projectId })
+            .delete();
+        // Insert new tags
+        for (const tagName of tags) {
+            const tagId = await getOrCreateTag(adapter, projectId, tagName, trx);
+            await knex('t_decision_tags').insert({
+                decision_key_id: keyId,
+                tag_id: tagId,
+                project_id: projectId
+            });
+        }
+    }
+    // Handle m_scopes (many-to-many)
+    if (params.scopes && params.scopes.length > 0) {
+        const scopes = parseStringArray(params.scopes);
+        // Clear existing scopes for this project
+        await knex('t_decision_scopes')
+            .where({ decision_key_id: keyId, project_id: projectId })
+            .delete();
+        // Insert new scopes
+        for (const scopeName of scopes) {
+            const scopeId = await getOrCreateScope(adapter, projectId, scopeName, trx);
+            await knex('t_decision_scopes').insert({
+                decision_key_id: keyId,
+                scope_id: scopeId,
+                project_id: projectId
+            });
+        }
+    }
+    return {
+        success: true,
+        key: params.key,
+        key_id: keyId,
+        version: version,
+        message: `Decision "${params.key}" set successfully`
+    };
+}
+//# sourceMappingURL=queries.js.map