learning-agent 0.2.2 → 0.2.3

package/CHANGELOG.md

@@ -7,6 +7,50 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.2.3] - 2026-02-01
+
+### Added
+
+- **SQLite Graceful Degradation** (2f0)
+  - Works as dev dependency without native bindings failing
+  - JSONL-only mode when SQLite unavailable
+  - Keyword search falls back gracefully
+  - Warning displayed in degraded mode
+
+- **Claude Code Integration** (ctv, 8lp, 6nw, 501, 2jp, lfy)
+  - Claude Plugin structure (`.claude-plugin/`) with manifest and commands
+  - `/learn` slash command for quick lesson capture
+  - `/check-plan` slash command for plan-time retrieval
+  - Auto-invoke triggers for lesson capture patterns
+  - Detection triggers wired to Claude Code workflow
+  - AGENTS.md includes reference to CLAUDE.md
+
+- **Context Recovery** (gpv)
+  - `lna prime` command for context recovery after compaction/clear
+  - Outputs workflow rules, commands, and quality gates
+
+- **Diagnostics** (qi0)
+  - `setup claude --status` shows integration health
+  - Displays settings file, hook status, slash command availability
+  - JSON output with `--json` flag
+
+### Changed
+
+- **Architecture Refactoring** (e73, zpl)
+  - Split sqlite.ts (644 lines) into focused modules (<200 lines each)
+  - Module imports now use barrel exports (Parnas principles)
+  - Cleaner internal boundaries and improved maintainability
+
+- **CLI Improvements** (79k, e2r)
+  - CLI releases database resources on SIGINT/SIGTERM signals
+  - `setup claude --uninstall` removes AGENTS.md section and CLAUDE.md reference
+  - Clean uninstall preserves other content
+
+### Fixed
+
+- Claude now uses CLI commands instead of editing JSONL directly (0p5)
+- Plan-time lessons now appear via check-plan hook integration (6nw)
+
 ## [0.2.2] - 2026-02-01
 
 ### Added
@@ -186,7 +230,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   - Vitest test suite
   - tsup build configuration
 
-[Unreleased]: https://github.com/Nathandela/learning_agent/compare/v0.2.2...HEAD
+[Unreleased]: https://github.com/Nathandela/learning_agent/compare/v0.2.3...HEAD
+[0.2.3]: https://github.com/Nathandela/learning_agent/compare/v0.2.2...v0.2.3
 [0.2.2]: https://github.com/Nathandela/learning_agent/compare/v0.2.1...v0.2.2
 [0.2.1]: https://github.com/Nathandela/learning_agent/compare/v0.2.0...v0.2.1
 [0.2.0]: https://github.com/Nathandela/learning_agent/compare/v0.1.0...v0.2.0

package/README.md

@@ -49,6 +49,27 @@ pnpm test
 pnpm download-model
 ```
 
+## Development
+
+### Test Scripts
+
+| Script | Duration | Tests | Use Case |
+|--------|----------|-------|----------|
+| `pnpm test:fast` | ~6s | 385 | **Rapid feedback during development** |
+| `pnpm test` | ~60s | 653 | Full suite before committing |
+| `pnpm test:changed` | varies | varies | Only tests affected by recent changes |
+| `pnpm test:watch` | - | - | Watch mode for TDD workflow |
+| `pnpm test:all` | ~60s | 653 | Full suite with model download |
+
+**Recommended workflow:**
+1. Use `pnpm test:fast` while coding for rapid feedback
+2. Run `pnpm test` before committing
+3. CI runs the full suite
+
+### Why test:fast is fast
+
+The CLI integration tests spawn Node.js processes (~400ms overhead each) and account for 95% of test time. `test:fast` skips these, running only unit tests that verify all business logic.
+
 ## Architecture
 
 ```
@@ -194,6 +215,62 @@ import {
 
 See [examples/](examples/) for usage examples.
 
+## Lesson Schema
+
+Lessons are stored as JSONL records with the following schema:
+
+### Required Fields
+
+All lessons must have these fields:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `id` | string | Unique identifier (e.g., "L12345678") |
+| `type` | "quick" \| "full" | Lesson complexity level |
+| `trigger` | string | What caused the lesson (context/situation) |
+| `insight` | string | What was learned (the takeaway) |
+| `tags` | string[] | Categorization tags |
+| `source` | string | How it was captured (user_correction, self_correction, test_failure, manual) |
+| `context` | object | Tool/intent context |
+| `created` | ISO string | Creation timestamp |
+| `confirmed` | boolean | Whether user confirmed the lesson |
+
+### Optional Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `evidence` | string | Supporting evidence (full lessons only) |
+| `severity` | "high" \| "medium" \| "low" | Importance level (separate from type) |
+| `citation` | object | File/line reference (file, line, commit) |
+
+**Note**: The `severity` field is separate from `type`. A quick lesson can have high severity, and a full lesson can have low severity.
+
+### Session-Start Loading
+
+At session start, lessons are loaded based on:
+- **High severity** lessons are always loaded
+- **Confirmed** lessons are prioritized
+- Only non-invalidated lessons are included
+
+### Complete JSON Example
+
+```json
+{
+  "id": "L12345678",
+  "type": "full",
+  "trigger": "API returned 401 despite valid JWT token",
+  "insight": "Auth API requires X-Request-ID header in all requests",
+  "evidence": "Traced in network tab, discovered missing header requirement",
+  "severity": "high",
+  "tags": ["api", "auth", "headers"],
+  "source": "test_failure",
+  "context": { "tool": "fetch", "intent": "API authentication" },
+  "created": "2024-01-15T10:30:00.000Z",
+  "confirmed": true,
+  "citation": { "file": "src/api/client.ts", "line": 42 }
+}
+```
+
 ## Lesson Types
 
 ### Quick Lesson (fast capture)
@@ -260,6 +337,32 @@ Version 0.2.2 - Hardening release with quality gates based on [LANDSCAPE.md](doc
 | [doc/PLAN.md](doc/PLAN.md) | Implementation plan |
 | [AGENTS.md](AGENTS.md) | Agent instructions overview |
 | [.claude/CLAUDE.md](.claude/CLAUDE.md) | Claude Code project instructions |
+| [doc/test-optimization-baseline.md](doc/test-optimization-baseline.md) | Test performance metrics |
+
+## Testing
+
+### Test Organization
+
+Tests are organized for parallelization:
+
+```
+src/
+├── *.test.ts           # Unit tests (fast)
+├── cli/                # CLI integration tests (split by command)
+│   ├── cli-test-utils.ts    # Shared utilities
+│   ├── learn.test.ts
+│   ├── search.test.ts
+│   └── ...
+├── storage/            # Storage layer tests
+├── embeddings/         # Embedding model tests (skipped if model unavailable)
+└── ...
+```
+
+### Known Limitations
+
+**Embedding concurrency**: The `node-llama-cpp` native addon may crash under heavy parallel load. This is a known limitation of the underlying C++ library. Tests pass reliably under normal conditions.
+
+**Timing-based tests**: Some tests verify performance thresholds. These use generous limits (5000ms) to avoid flakiness on slow CI machines.
 
 ## License