sqlew 3.2.2 → 3.2.3

package/CHANGELOG.md

@@ -5,6 +5,41 @@ All notable changes to sqlew will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [3.2.3] - 2025-10-20
+
+### Changed
+- **Code Organization - Major Refactoring**
+  - Reduced `src/index.ts` from 1,534 lines to 525 lines (66% reduction)
+  - Extracted 1,009 lines of help/example documentation to respective tool files
+  - Moved help/example functions to 7 tool files: `context.ts`, `messaging.ts`, `files.ts`, `constraints.ts`, `utils.ts`, `config.ts`, `tasks.ts`
+  - Improved maintainability: Help/example documentation now co-located with tool implementations
+  - Zero API changes: All 14 help/example actions remain fully backward compatible
+
+- **File Watcher Documentation Updates**
+  - Corrected token savings claims: Changed "97% token reduction" to "save 300 tokens per file compared to registering watchers manually"
+  - Updated claims in 5 locations across `taskHelp()` and `taskExample()` functions
+  - Added best practice recommendation: "Except in exceptional cases, it is recommended to set up file watchers for all tasks that involve code changes"
+  - Clarified automatic file watching benefits with accurate token efficiency metrics
+
+- **Package Description Update**
+  - Updated description from "97% token reduction" to "96% token efficiency through API consolidation"
+  - More accurately reflects the token savings from v2.0 action-based API consolidation
+
+### Technical Details
+- **Files Modified:**
+  - `src/index.ts`: Simplified to pure routing logic (525 lines)
+  - `src/tools/context.ts`: Added `decisionHelp()`, `decisionExample()` (+217 lines)
+  - `src/tools/messaging.ts`: Added `messageHelp()`, `messageExample()` (+136 lines)
+  - `src/tools/files.ts`: Added `fileHelp()`, `fileExample()` (+127 lines)
+  - `src/tools/constraints.ts`: Added `constraintHelp()`, `constraintExample()` (+169 lines)
+  - `src/tools/utils.ts`: Added `statsHelp()`, `statsExample()` (+137 lines)
+  - `src/tools/config.ts`: Added `configHelp()`, `configExample()` (+107 lines)
+  - `src/tools/tasks.ts`: Added `taskExample()` (+200 lines, `taskHelp()` already existed)
+
+- **Pattern Applied:** Extract inline switch case blocks to exported functions in tool files
+- **Backward Compatibility:** 100% maintained - all existing MCP tool calls work identically
+- **Build:** TypeScript compilation successful with zero errors
+
 ## [3.2.2] - 2025-10-18
 
 ### Added

package/README.md

@@ -209,6 +209,9 @@ Each tool supports `action: "help"` for full documentation and `action: "example
 - 🔗 **[Task Linking](docs/TASK_LINKING.md)** - Link tasks to decisions/constraints/files/tasks (900+ lines, ~23k tokens)
 - 🔄 **[Task Migration](docs/TASK_MIGRATION.md)** - Migrate from decision-based tracking (701 lines, ~18k tokens)
 
+**Decision Context (v3.2.2):**
+- 📝 **[Decision Context](docs/DECISION_CONTEXT.md)** - Rich decision documentation with rationale, alternatives, and tradeoffs (500+ lines, ~15k tokens) **NEW v3.2.2**
+
 **Auto File Tracking (v3.0.2):**
 - 🤖 **[Auto File Tracking](docs/AUTO_FILE_TRACKING.md)** - Zero-token task management, setup, troubleshooting
 - ✅ **[Acceptance Criteria](docs/ACCEPTANCE_CRITERIA.md)** - All check types (tests_pass, code_removed, code_contains, file_exists)
@@ -267,6 +270,48 @@ Each tool supports `action: "help"` for full documentation and `action: "example
 }
 ```
 
+### Decision Context (v3.2.2)
+
+```javascript
+// Record a decision with rich context
+{
+  action: "set",
+  key: "database_choice",
+  value: "PostgreSQL over MongoDB",
+  layer: "data",
+  tags: ["architecture", "database"]
+}
+
+// Add rationale and tradeoffs
+{
+  action: "add_decision_context",
+  key: "database_choice",
+  rationale: "Selected PostgreSQL because: (1) Complex relational queries required for reporting, (2) ACID compliance critical for financial data, (3) Team has strong SQL expertise",
+  alternatives_considered: [
+    {
+      option: "MongoDB",
+      reason: "Rejected due to weak consistency guarantees for financial data"
+    },
+    {
+      option: "MySQL",
+      reason: "Rejected due to limited JSON support needed for metadata"
+    }
+  ],
+  tradeoffs: {
+    pros: ["Strong consistency", "Complex queries", "Team expertise"],
+    cons: ["Less flexible schema", "Vertical scaling limitations"]
+  }
+}
+
+// Retrieve decision with full context
+{
+  action: "get",
+  key: "database_choice",
+  include_context: true
+}
+// → Returns decision + rationale + alternatives + tradeoffs
+```
+
 ### Session Continuity
 
 ```javascript
@@ -310,7 +355,7 @@ on [GitHub Sponsors](https://github.com/sponsors/sin5ddd)
 
 ## Version
 
-Current version: **3.0.0**
+Current version: **3.2.2**
 See [CHANGELOG.md](CHANGELOG.md) for release history.
 
 ## License