learning-agent 0.2.1 → 0.2.2

package/CHANGELOG.md

@@ -7,6 +7,51 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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 +186,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.1...HEAD
+[Unreleased]: https://github.com/Nathandela/learning_agent/compare/v0.2.2...HEAD
+[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

@@ -93,18 +93,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
 ```
@@ -182,120 +194,33 @@ import {
 
 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.
-
-### Required Fields
-
-Every lesson **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) |
-
-### 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:
-
-- **`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"`.
-
-### Session-Start Loading
-
-High-severity lessons are automatically loaded at session start. For a lesson to load:
-
-1. `type` must be `"full"`
-2. `severity` must be `"high"`
-3. `confirmed` must be `true`
-
-### Complete Examples
-
-#### 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 +249,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