learning-agent 0.2.1 → 0.2.3

package/CHANGELOG.md

@@ -7,6 +7,95 @@ 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
+
+- **Age-based Temporal Validity** (LANDSCAPE.md: eik)
+  - `CompactionLevelSchema` for lesson lifecycle (0=active, 1=flagged, 2=archived)
+  - Age distribution display in `stats` command (<30d, 30-90d, >90d)
+  - Age warnings in `load-session` for lessons older than 90 days
+  - New schema fields: `compactionLevel`, `compactedAt`, `lastRetrieved`
+
+- **Manual Invalidation** (LANDSCAPE.md: mov)
+  - `learning-agent wrong <id>` - Mark a lesson as invalid/wrong
+  - `learning-agent validate <id>` - Re-enable a previously invalidated lesson
+  - `list --invalidated` flag to show only invalidated lessons
+  - New schema fields: `invalidatedAt`, `invalidationReason`
+
+- **Optional Citation Field** (LANDSCAPE.md: tn3)
+  - `CitationSchema` for lesson provenance tracking
+  - Store file path, line number, and git commit with lessons
+  - `learn --citation <file:line>` and `--citation-commit <hash>` flags
+
+- **Count Warning** (LANDSCAPE.md: qp9)
+  - Warning in `stats` when lesson count exceeds 20 (context pollution prevention)
+  - Note in `load-session` when total lessons may degrade retrieval quality
+
+### Changed
+
+- Lesson schema now includes optional fields for citation, age-tracking, and invalidation
+- `list` command shows `[INVALID]` marker for invalidated lessons
+- `load-session` JSON output includes `totalCount` field
+- CLI refactored into command modules (`src/commands/`) for maintainability
+- Age calculation logic centralized in `src/utils.ts`
+
+### Fixed
+
+- **SQLite schema now stores v0.2.2 fields** (x9y)
+  - Added columns: `invalidated_at`, `invalidation_reason`, `citation_*`, `compaction_level`, `compacted_at`
+  - `rebuildIndex` preserves all v0.2.2 fields during cache rebuild
+  - `rowToLesson` correctly maps all fields back to Lesson objects
+
+- **Retrieval paths filter out invalidated lessons** (z8k)
+  - `searchKeyword` excludes lessons with `invalidated_at` set
+  - `searchVector` skips invalidated lessons during scoring
+  - `loadSessionLessons` filters out invalidated high-severity lessons
+
 ## [0.2.1] - 2026-02-01
 
 ### Added
@@ -141,7 +230,9 @@ 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.1...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
 [0.1.0]: https://github.com/Nathandela/learning_agent/releases/tag/v0.1.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
 
 ```
@@ -93,18 +114,30 @@ pnpm download-model
 # Capture a lesson manually
 pnpm learn "Use Polars for large files, not pandas"
 
+# Capture with citation (file:line provenance)
+learning-agent learn "API requires auth header" --citation src/api.ts:42
+
 # Search lessons
 learning-agent search "data processing"
 
-# Rebuild index from JSONL
-learning-agent rebuild
-
 # List all lessons
 learning-agent list
 
-# Show database stats
+# List only invalidated lessons
+learning-agent list --invalidated
+
+# Mark a lesson as wrong/invalid
+learning-agent wrong L12345678 --reason "This advice was incorrect"
+
+# Re-enable an invalidated lesson
+learning-agent validate L12345678
+
+# Show database stats (includes age distribution)
 learning-agent stats
 
+# Rebuild index from JSONL
+learning-agent rebuild
+
 # Compact and archive old lessons
 learning-agent compact
 ```
@@ -184,118 +217,87 @@ See [examples/](examples/) for usage examples.
 
 ## Lesson Schema
 
-Lessons are stored in JSONL format with Zod validation. Understanding the schema is critical for correct usage.
+Lessons are stored as JSONL records with the following schema:
 
 ### Required Fields
 
-Every lesson **must** have these fields:
+All lessons must have these fields:
 
 | Field | Type | Description |
 |-------|------|-------------|
-| `id` | string | Unique identifier (e.g., "L1a2b3c4d") |
-| `type` | "quick" \| "full" | Lesson quality tier (see below) |
-| `trigger` | string | What caused this lesson to be learned |
-| `insight` | string | The actual lesson content |
-| `tags` | string[] | Categorization tags (can be empty) |
-| `source` | enum | How it was captured: "user_correction", "self_correction", "test_failure", "manual" |
-| `context` | object | `{ tool: string, intent: string }` - what was happening |
-| `created` | string | ISO8601 timestamp |
-| `confirmed` | boolean | Whether user confirmed this lesson |
-| `supersedes` | string[] | IDs of lessons this replaces (can be empty) |
-| `related` | string[] | IDs of related lessons (can be empty) |
+| `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 (typically for "full" type) |
-| `severity` | "high" \| "medium" \| "low" | Importance level |
-| `pattern` | object | `{ bad: string, good: string }` - code pattern |
-| `deleted` | boolean | Tombstone marker for deletions |
-| `retrievalCount` | number | Times this lesson was retrieved |
-
-### Type vs Severity (Important!)
-
-**`type`** and **`severity`** are **separate** fields:
+| `evidence` | string | Supporting evidence (full lessons only) |
+| `severity` | "high" \| "medium" \| "low" | Importance level (separate from type) |
+| `citation` | object | File/line reference (file, line, commit) |
 
-- **`type`**: Quality tier of the lesson
-  - `"quick"` - Minimal capture, fast to create
-  - `"full"` - Detailed lesson with evidence/patterns
-
-- **`severity`**: Importance level (optional field)
-  - `"high"` - Critical, loaded at every session start
-  - `"medium"` - Important, retrieved when relevant
-  - `"low"` - Minor, lower retrieval priority
-
-**Common mistake**: Using `type: "high"` instead of `type: "full"` with `severity: "high"`.
+**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
 
-High-severity lessons are automatically loaded at session start. For a lesson to load:
+At session start, lessons are loaded based on:
+- **High severity** lessons are always loaded
+- **Confirmed** lessons are prioritized
+- Only non-invalidated lessons are included
 
-1. `type` must be `"full"`
-2. `severity` must be `"high"`
-3. `confirmed` must be `true`
+### Complete JSON Example
 
-### Complete Examples
+```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 }
+}
+```
 
-#### Quick Lesson (minimal)
+## Lesson Types
 
+### Quick Lesson (fast capture)
 ```json
 {
-  "id": "L1a2b3c4d",
+  "id": "L001",
   "type": "quick",
   "trigger": "Used pandas for 500MB file",
-  "insight": "Polars is 10x faster for large files",
+  "insight": "Polars 10x faster",
   "tags": ["performance", "polars"],
-  "source": "user_correction",
-  "context": { "tool": "edit", "intent": "optimize CSV processing" },
-  "created": "2025-01-30T14:00:00Z",
-  "confirmed": true,
-  "supersedes": [],
-  "related": []
+  "source": "user_correction"
 }
 ```
 
-#### Full Lesson with High Severity (loads at session start)
-
+### Full Lesson (detailed, high-severity)
 ```json
 {
-  "id": "L5e6f7g8h",
+  "id": "L002",
   "type": "full",
   "trigger": "Auth API returned 401 despite valid token",
   "insight": "API requires X-Request-ID header",
-  "evidence": "Traced in network tab, header was missing",
-  "tags": ["api", "auth"],
+  "evidence": "Traced in network tab, header missing",
   "severity": "high",
-  "source": "test_failure",
-  "context": { "tool": "bash", "intent": "run auth integration tests" },
-  "created": "2025-01-30T15:30:00Z",
-  "confirmed": true,
-  "supersedes": [],
-  "related": ["L1a2b3c4d"],
-  "pattern": {
-    "bad": "requests.get(url, headers={'Authorization': token})",
-    "good": "requests.get(url, headers={'Authorization': token, 'X-Request-ID': uuid4()})"
-  }
+  "source": "test_failure"
 }
 ```
 
-### Creating Lessons via CLI
-
-Always use the CLI to create lessons (never edit JSONL directly):
-
-```bash
-# Quick lesson
-npx lna learn "Use Polars for large files"
-
-# Full lesson with high severity (loads at session start)
-npx lna learn "API requires X-Request-ID header" --severity high
-
-# With trigger context
-npx lna learn "Use uv not pip" --trigger "pip was slow" --severity medium
-```
-
 ## Technology Stack
 
 | Component | Technology |
@@ -324,7 +326,7 @@ pnpm lint
 
 ## Project Status
 
-Version 0.2.1 - Bug fixes and documentation improvements. See [doc/SPEC.md](doc/SPEC.md) for the full specification and [CHANGELOG.md](CHANGELOG.md) for recent changes.
+Version 0.2.2 - Hardening release with quality gates based on [LANDSCAPE.md](doc/LANDSCAPE.md) reviewer feedback. Adds age-based validity warnings, manual invalidation commands, optional citation tracking, and context pollution warnings. See [CHANGELOG.md](CHANGELOG.md) for details.
 
 ## Documentation
 
@@ -335,6 +337,32 @@ Version 0.2.1 - Bug fixes and documentation improvements. See [doc/SPEC.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