@a-company/paradigm 5.38.0 → 6.0.4

package/dist/university-content/notes/N-para-501-assessment-loops.md

@@ -0,0 +1,116 @@
+---
+id: N-para-501-assessment-loops
+title: Lore as Unified Project Memory
+type: note
+author: paradigm
+created: '2026-04-22'
+updated: '2026-04-22'
+tags:
+  - course
+  - para-501
+  - lore-is-the
+  - eight-entry-types
+  - arc-tags-arc
+symbols: []
+difficulty: beginner
+estimatedMinutes: 4
+prerequisites: []
+category: paradigm-core
+origin: imported
+source: courses/para-501.json
+---
+
+## Lore: The Single Source of Project Memory
+
+Paradigm uses lore as its unified project memory system. Every piece of project knowledge — session records, retrospectives, insights, decisions, milestones — lives in lore entries, differentiated by `type` and classified by tags.
+
+The model is simple: **one system, tags drive classification.**
+
+| Entry Type | When to Use |
+|---|---|
+| `agent-session` | Automated record of an AI-assisted work session |
+| `human-note` | Manual note from a human developer |
+| `decision` | Strategic or architectural decision with rationale |
+| `review` | Quality review of a previous entry |
+| `incident` | Production issue or bug report |
+| `milestone` | Significant project achievement |
+| `retro` | Retrospective — looking back at completed work |
+| `insight` | A realization or pattern discovered across sessions |
+
+Lore entries are stored as YAML files in `.paradigm/lore/entries/{date}/` with the `.lore` extension. Each entry has a unique ID: `L-{date}-{author}-{HHMMSS}-{NNN}`.
+
+## Tags Drive Classification
+
+Tags are the primary classification mechanism in lore. Any string can be a tag, but certain prefixes carry special meaning:
+
+| Tag Prefix | Meaning | Example |
+|---|---|---|
+| `arc:` | Groups entries into a thematic arc | `arc:auth-hardening`, `arc:v2-migration` |
+| `assessment:` | Marks the reflection type | `assessment:retro`, `assessment:insight` |
+| `arc-closed` | Arc is no longer active | Added when an arc is complete |
+| `arc-status:` | Arc status metadata | `arc-status:complete`, `arc-status:archived` |
+
+Arcs are simply tag prefixes — no separate storage or management needed. To create an arc, just start tagging lore entries with `arc:my-arc-name`. To close an arc, add `arc-closed` and `arc-status:complete` tags to its entries.
+
+## The Body Field
+
+For entries that need more than a 2-3 sentence summary, lore entries support a `body` field for long-form content. This is where retrospective narratives, detailed decision rationale, and multi-paragraph reflections live:
+
+```yaml
+id: L-2026-03-02-ascend-164500-001
+type: retro
+title: "JWT refresh token rotation — what we learned"
+summary: Completed refresh token rotation with httpOnly cookie storage.
+body: |
+  After three sessions implementing refresh token rotation,
+  the key insight is that storing refresh tokens in httpOnly
+  cookies eliminates an entire class of XSS vulnerabilities.
+symbols_touched: ["#refresh-token-handler", "^authenticated"]
+linked_lore: [L-2026-02-10-003, L-2026-02-12-001]
+linked_commits: [a1b2c3d, e4f5g6h]
+tags: [arc:auth-hardening, assessment:retro, security, auth, jwt]
+```
+
+## Cross-Referencing
+
+Lore entries can link to other project artifacts:
+
+- **`linked_lore`** — References to other lore entry IDs, creating a web of related records
+- **`linked_tasks`** — References to paradigm task IDs
+- **`linked_commits`** — Git commit SHAs related to this entry
+
+These links create traceability. A retrospective entry can point to the three session records that produced it and the five commits that implemented it.
+
+## Working with Lore
+
+**Recording:** Use `paradigm_lore_record` with `type`, `title`, `summary`, and `symbols_touched`. Add `body` for long-form content, `tags` with `arc:*` prefixes for arc grouping, and `linked_lore`/`linked_commits` for cross-references.
+
+**Searching:** Use `paradigm_lore_search` with filters:
+- `tag: "arc:auth-hardening"` — Find all entries in an arc
+- `type: "retro"` — Find all retrospectives
+- `hasBody: true` — Find entries with detailed content
+- `symbol: "#payment-service"` — Find entries touching a symbol
+
+## The Reflection Loop
+
+Lore supports a natural reflection cycle:
+
+1. **Session records** — Automatically captured during work sessions (type: `agent-session`)
+2. **Reflection entries** — Manually recorded at natural pause points (type: `retro`, `insight`, `decision`, `milestone`)
+3. **Arc grouping** — Related reflections tagged with `arc:*` for thematic organization
+4. **Cross-referencing** — Reflection entries link back to the sessions that produced them
+
+When a task is marked complete via `paradigm_task_done`, the system suggests recording a lore entry as a natural reflection point.
+
+## When to Record Reflective Entries
+
+- **After completing a multi-session feature** — What did we learn? (`retro` with `arc:feature-name`)
+- **When a pattern emerges** — "Every time we touch auth, we find token edge cases" (`insight`)
+- **When making a strategic choice** — "Switching from REST to GraphQL" (`decision`)
+- **When reaching a milestone** — "v2.0 shipped to production" (`milestone`)
+
+The general rule: if the knowledge would be valuable in 3 months, record it as a reflective lore entry with appropriate tags.
+
+## Migration from Assessments
+
+Projects that used the older separate assessment system can migrate with `paradigm lore migrate-assessments`. This converts assessment entries to lore entries with `arc:{arc_id}` and `assessment:{type}` tags, preserving all data.

package/dist/university-content/notes/N-para-501-conductor-workspace.md

@@ -0,0 +1,77 @@
+---
+id: N-para-501-conductor-workspace
+title: 'Conductor: Visual Mission Control'
+type: note
+author: paradigm
+created: '2026-04-22'
+updated: '2026-04-22'
+tags:
+  - course
+  - para-501
+  - conductor-is-a
+  - workspace-mode-provides
+  - symphony-integration-shows
+symbols: []
+difficulty: beginner
+estimatedMinutes: 3
+prerequisites: []
+category: paradigm-core
+origin: imported
+source: courses/para-501.json
+---
+
+## What Is Conductor?
+
+Conductor is a native macOS application that serves as the visual mission control for Paradigm. While the CLI and MCP tools handle the automation, Conductor gives you a real-time view of what your agent team is doing — and lets you interact with them visually.
+
+Think of it as the difference between managing a team over email versus walking into a mission control room. Both work, but the room gives you instant awareness.
+
+### Core Capabilities
+
+**Workspace Mode** — A full-screen tiling window manager for Claude Code sessions. Launch multiple terminals side by side, split horizontally or vertically, drag dividers to resize. Six layout presets (single, split-h, split-v, quad, triple, grid) let you quickly arrange your workspace.
+
+**Symphony Integration** — Conductor connects to Symphony, the inter-agent messaging system. When agents communicate during orchestration (handing off context, requesting approval, debating approaches), those messages appear in Conductor's thread view in real time. You can read the full conversation without switching to the CLI.
+
+**Task Protocol** — A structured protocol for human-agent coordination with 7 intents:
+- `task` — assign work to an agent
+- `task-ack` — agent acknowledges receipt
+- `progress` — agent reports progress
+- `approval-request` — agent asks for human approval
+- `approval-response` — human approves or rejects
+- `task-complete` — agent reports success
+- `task-failed` — agent reports failure
+
+This protocol makes agent work visible and controllable. You see when agents are working, what they are asking, and whether they succeeded.
+
+**Agent Health Dashboard** — Per-agent metrics: success rates, average time-per-task, acceptance rates for contributions. Sparklines show trends over time. When an agent's performance drops, you see it immediately.
+
+**Live Sentinel** — Real-time event viewer with symbol filtering. When Sentinel detects an incident or pattern, it appears in Conductor's event feed with full detail and suggested resolution.
+
+### Architecture
+
+Conductor is built with Swift and SwiftUI — a native macOS application, not an Electron wrapper. Key design decisions:
+
+- **Single-owner pattern** — AppDelegate owns the orchestrator, workspace, project store, and agent process manager. No shared mutable state.
+- **Local-only ML** — Gaze tracking, gesture recognition, and voice commands all run locally via CoreML. Zero cloud, zero cost, zero latency.
+- **SwiftTerm embedding** — Terminal sessions use SwiftTerm, a native Swift terminal emulator. Each session is a real PTY with full ANSI support.
+- **7 platform protocols** — Abstraction layer for future portability (the same protocol set would power a Windows or Linux version).
+
+### Getting Started
+
+Build and install Conductor:
+
+```bash
+cd packages/conductor
+./build-conductor.sh --install
+```
+
+This produces `Conductor.app` in `/Applications`. Launch it, and it connects to your Paradigm project automatically.
+
+### When to Use Conductor
+
+- **During orchestration** — watch agents work in real time, approve contributions, read debates
+- **Multi-session development** — tile 2-4 Claude Code sessions side by side, each working on different parts of the codebase
+- **Monitoring** — keep Conductor visible on a secondary display to catch Sentinel events and agent health changes
+- **Team collaboration** — when multiple developers use Symphony, Conductor shows cross-session threads and file approval requests
+
+Conductor is optional — everything it shows is also available via CLI and MCP tools. But for teams that want visual awareness of their agent team, it is the command center.

package/dist/university-content/notes/N-para-501-habits-practice.md

@@ -0,0 +1,164 @@
+---
+id: N-para-501-habits-practice
+title: Habits & Practice
+type: note
+author: paradigm
+created: '2026-04-22'
+updated: '2026-04-22'
+tags:
+  - course
+  - para-501
+  - six-categories-discovery
+  - four-triggers-preflight
+  - three-severity-levels
+symbols: []
+difficulty: beginner
+estimatedMinutes: 6
+prerequisites: []
+category: paradigm-core
+origin: imported
+source: courses/para-501.json
+---
+
+## Instinct vs Habit
+
+When you first learn to drive, you consciously think about every action — check mirrors, signal, check blind spot, change lanes. After thousands of miles, these become habits: automatic behaviors you execute without conscious effort. The Habits system brings this concept to AI-assisted development.
+
+Without habits, an agent must be told every time: "check ripple before modifying," "validate flows after changing gates," "record lore for significant sessions." With habits, these checks become automatic behavioral triggers — the system evaluates them at defined points and reports compliance. Over time, agents internalize the patterns, and the habit checks become confirmation rather than correction.
+
+## Habit Definitions
+
+Each habit is a structured rule with six fields:
+
+```yaml
+id: ripple-before-modify
+name: Check Ripple Before Modifying
+description: Always call paradigm_ripple before modifying any symbol
+category: discovery
+trigger: preflight
+severity: advisory
+check:
+  type: tool-called
+  params:
+    tools: [paradigm_ripple]
+enabled: true
+```
+
+**Categories** classify what kind of discipline the habit enforces. There are six:
+- `discovery` — Exploring before acting (ripple, navigate, search)
+- `verification` — Validating after implementing (postflight, reindex)
+- `testing` — Ensuring test coverage for new code
+- `documentation` — Keeping .purpose files and lore entries current
+- `collaboration` — Checking team wisdom and expert knowledge
+- `security` — Validating gates and portal.yaml compliance
+
+**Triggers** define when the habit is evaluated. There are four:
+- `preflight` — Before starting implementation
+- `postflight` — After completing implementation
+- `on-commit` — Before committing changes
+- `on-stop` — Before the session ends (stop hook)
+
+**Severity** determines what happens when a habit is violated:
+- `advisory` — Log a note, don't block anything
+- `warn` — Show a warning to the agent/user
+- `block` — Prevent session completion until resolved (enforced by stop hook)
+
+## Check Types
+
+Habits verify compliance through twelve check types:
+
+| Check Type | What It Verifies |
+|---|---|
+| `tool-called` | Specified MCP tools were invoked during the session |
+| `file-exists` | Files matching glob patterns exist (e.g., test files) |
+| `file-modified` | Files matching patterns were modified during session |
+| `lore-recorded` | A lore entry was created (for 3+ file sessions) |
+| `symbols-registered` | New code is registered in .purpose files |
+| `gates-declared` | Routes have corresponding gates in portal.yaml |
+| `tests-exist` | Test files exist for modified components |
+| `git-clean` | Git working tree is clean — all changes committed |
+| `commit-message-format` | Commit messages match regex patterns (default: conventional commit prefix + Symbols: trailer) |
+| `flow-coverage` | Changes spanning 3+ components have a documented $flow |
+| `context-checked` | Session context/recovery tools (paradigm_session_health, paradigm_session_recover) were called |
+| `aspect-anchored` | Touched aspects (~) have valid code anchors verified via paradigm_aspect_check |
+
+## The 14 Seed Habits
+
+Paradigm ships with 14 built-in habits that establish baseline discipline:
+
+1. **explore-before-implement** (preflight/advisory/discovery) — Called paradigm_ripple, paradigm_navigate, paradigm_search, or paradigm_related before coding
+2. **ripple-before-modify** (preflight/advisory/discovery) — Called paradigm_ripple specifically before modifying symbols
+3. **check-fragility** (preflight/advisory/discovery) — Called paradigm_history_fragility before touching symbols
+4. **wisdom-before-implement** (preflight/advisory/collaboration) — Checked paradigm_wisdom_context or paradigm_wisdom_expert
+5. **verify-before-done** (on-stop/warn/verification) — Called paradigm_pm_postflight before finishing
+6. **postflight-compliance** (on-stop/advisory/verification) — Ran postflight and reindex
+7. **test-new-components** (postflight/advisory/testing) — Test files exist for new components
+8. **purpose-coverage** (postflight/warn/documentation) — .purpose files cover modified directories
+9. **record-lore-for-significant** (on-stop/warn/documentation) — Lore recorded for 3+ file sessions
+10. **gates-for-routes** (postflight/warn/security) — Routes have portal.yaml gate coverage
+11. **commit-message-symbols** (on-commit/advisory/documentation) — Commit messages follow type(#symbol): format with Symbols: trailer
+12. **flow-coverage-for-multi-component** (postflight/advisory/documentation) — Changes spanning 3+ components have a documented $flow
+13. **context-session-awareness** (preflight/advisory/discovery) — Session recovery or context check tools were called for continuity
+14. **aspect-anchors-valid** (postflight/advisory/verification) — Aspects touched during the session have valid code anchors
+
+## Habit Loading and Overrides
+
+Habits load from three sources, merged in order (later wins):
+
+1. **Seed habits** — The 10 built-in habits (always present)
+2. **Global habits** — `~/.paradigm/habits.yaml` (optional, applies to all projects)
+3. **Project habits** — `.paradigm/habits.yaml` (optional, project-specific)
+
+Overrides let you adjust severity or disable habits without redefining them:
+
+```yaml
+# .paradigm/habits.yaml
+overrides:
+  ripple-before-modify:
+    severity: block    # Upgrade from advisory to blocking
+  test-new-components:
+    enabled: false     # Disable for this project
+custom:
+  - id: check-migrations
+    name: Verify DB Migrations
+    category: verification
+    trigger: on-commit
+    severity: warn
+    check:
+      type: file-exists
+      params:
+        patterns: ["migrations/*.sql"]
+```
+
+## Practice Profiles
+
+Every habit evaluation is recorded as a practice event with a result: `followed`, `skipped`, or `partial`. These events accumulate into practice profiles that show compliance rates over time.
+
+`paradigm_habits_status` returns a practice profile with: overall compliance rate, strongest and weakest categories, per-category breakdowns, trend analysis (improving/declining/stable), and incident correlations — habits whose skipped evaluations correlate with higher incident rates.
+
+The incident correlation is powerful: if skipping `ripple-before-modify` correlates with a 3x higher incident rate for the modified symbols, that is concrete evidence for upgrading the habit's severity.
+
+## MCP Tools
+
+**`paradigm_habits_check`** — Evaluate habits for a trigger point. Pass the trigger (`preflight`, `postflight`, `on-stop`), optionally with `filesModified` and `symbolsTouched` for context. Returns evaluations with follow/skip/partial results and whether any blocking violations exist.
+
+**`paradigm_habits_status`** — Get the practice profile for an engineer over a time period (7d, 30d, 90d, or all). Shows compliance rates, category breakdowns, trends, and incident correlations.
+
+**`paradigm_practice_context`** — Before modifying symbols, get habit-aware warnings. Pass the symbols you are about to touch, and it returns relevant habits, recent compliance rates, and suggestions based on your weak areas.
+
+## CLI Commands
+
+The CLI provides full habit management:
+
+- `paradigm habits list` — List all habits with trigger, severity, and enabled status
+- `paradigm habits add` — Add a custom habit with check type, patterns, and tools
+- `paradigm habits edit <id>` — Edit habit fields (for seed habits: severity and enabled only)
+- `paradigm habits remove <id>` — Remove a custom habit
+- `paradigm habits enable/disable <id>` — Toggle a habit on or off
+- `paradigm habits check --trigger <trigger>` — Evaluate compliance for a specific trigger
+- `paradigm habits status` — Practice profile with compliance rates and trends
+- `paradigm habits init` — Initialize a habits.yaml file for the project
+
+## Platform Targeting
+
+Habits support a `platforms` field to restrict evaluation to specific platforms. For example, a habit with `platforms: ['claude', 'cursor']` will only be evaluated when running in those environments. A habit with `platforms: ['cli']` will only fire during CLI-driven workflows. When `platforms` is omitted, the habit applies everywhere.

package/dist/university-content/notes/N-para-501-hook-enforcement.md

@@ -0,0 +1,100 @@
+---
+id: N-para-501-hook-enforcement
+title: Hook Enforcement & Automation
+type: note
+author: paradigm
+created: '2026-04-22'
+updated: '2026-04-22'
+tags:
+  - course
+  - para-501
+  - stop-hook-blocks
+  - post-write-hook-tracks
+  - pre-commit-hook-auto-rebuilds
+symbols: []
+difficulty: beginner
+estimatedMinutes: 4
+prerequisites: []
+category: paradigm-core
+origin: imported
+source: courses/para-501.json
+---
+
+## The Compliance Gap
+
+Paradigm's value depends on discipline. Purpose files must be updated when code changes. Portal.yaml must reflect route additions. Lore must be recorded for significant sessions. Aspect anchors must point to real code. Without enforcement, these requirements become suggestions that erode over time.
+
+Hooks close this gap. They are automated checks that run at specific points in the development workflow, catching violations before they become technical debt. Paradigm uses three hooks, each with a distinct role and severity.
+
+## The Stop Hook
+
+The stop hook is the primary enforcer. It runs before an agent session completes and can **block** the session from finishing if compliance checks fail.
+
+**Trigger**: Before agent session end (Claude Code: Stop hook, Cursor: pre-finish)
+
+**Seven checks, in order:**
+
+1. **Source files modified without .purpose updates** — If 2+ source files were modified but zero paradigm metadata files (.purpose, portal.yaml, etc.) were updated, the hook blocks. This catches the "implement and forget" pattern.
+
+2. **Modified directories missing .purpose coverage** — The hook walks up the directory tree from each modified source file looking for a covering .purpose file. If no .purpose exists anywhere in the ancestor chain (including the project root), it blocks.
+
+3. **Route patterns without portal.yaml** — The hook scans modified files for route declaration patterns (Express `.get()`, `.post()`, decorators like `@Get()`, Rust macros like `#[actix_web::get]`). If routes are detected and portal.yaml was neither present nor modified, it blocks.
+
+4. **Stale aspect anchors** — The hook parses .purpose files for `anchors:` sections and validates that each referenced file still exists. If an anchor points to a deleted file, it blocks.
+
+5. **Pending .purpose freshness** — The post-write hook tracks files edited without .purpose updates in `.paradigm/.pending-review`. The stop hook checks this list: if source files are pending and their covering .purpose was not also modified during the session, it blocks.
+
+6. **Aspect coverage advisory** — If the project uses `~aspects`, the hook advises (non-blocking) to verify that anchor line numbers are still accurate after code changes.
+
+7. **Lore entry for significant sessions** — If 3+ source files were modified and no lore entry was recorded in `.paradigm/lore/entries/`, the hook blocks.
+
+**When blocked**, the hook outputs a clear list of violations with remediation steps. Fix the violations, then complete the session.
+
+## The Post-Write Hook
+
+The post-write hook runs after every file edit (Edit or Write tool calls). It is **advisory only** — it never blocks.
+
+**Trigger**: After Edit or Write tool completes
+
+**Actions:**
+1. Extracts the edited file path
+2. Skips non-source files (.purpose, portal.yaml, .md, .lock, .json, .yaml, .gitignore, .env files) and paradigm directories (.paradigm/, .claude/, .cursor/)
+3. Appends source file paths to `.paradigm/.pending-review` (deduplicated)
+4. Checks if a .purpose file covers the edited directory
+5. If no .purpose exists: reminds "No .purpose file covers {dir}/ — Create one"
+6. Every 3 source files edited: general reminder to update .purpose files
+
+The `.pending-review` file is the bridge between the post-write hook and the stop hook. Post-write accumulates the list; stop hook validates against it.
+
+## The Pre-Commit Hook
+
+The pre-commit hook runs before `git commit` and handles index maintenance. It **never blocks**.
+
+**Trigger**: Before Bash commands containing `git commit`
+
+**Actions:**
+1. Runs `paradigm index --quiet` to rebuild scan-index.json, navigator.yaml, and flow-index.json
+2. Stages the rebuilt files so they are included in the commit
+3. Exits 0 (always succeeds)
+
+This ensures that every commit has a fresh symbol index. Without this hook, the index would drift from the actual codebase between manual `paradigm scan` runs.
+
+## Hook Installation
+
+Hooks are installed automatically by `paradigm shift` (full setup) or manually with `paradigm hooks install`. The installer detects the IDE (Claude Code or Cursor) and writes the appropriate hook format.
+
+For Claude Code, hooks are configured in `.claude/settings.json` using the hooks API — stop hooks, PreToolUse matchers (for Bash commands matching `git commit`), and PostToolUse matchers (for Edit/Write tool calls).
+
+## Remediation Workflow
+
+When the stop hook blocks you:
+
+1. **Read the violation list** — Each violation names the specific check that failed
+2. **Update .purpose files** — For modified directories without coverage, create or update the nearest .purpose file
+3. **Update portal.yaml** — If routes were added, add the route and gate definitions
+4. **Fix stale anchors** — If aspect anchors point to deleted/moved files, update the anchor paths
+5. **Record lore** — If 3+ files were modified, call `paradigm_lore_record` with the session summary
+6. **Run `paradigm_reindex`** — Rebuild the index to reflect your updates
+7. **Complete the session** — The stop hook runs again and should pass
+
+The key insight is that the stop hook is not punitive — it is protective. Every check it enforces prevents a real problem: stale documentation, unprotected routes, orphaned anchors, or lost institutional knowledge.

package/dist/university-content/notes/N-para-501-lore-system.md

@@ -0,0 +1,155 @@
+---
+id: N-para-501-lore-system
+title: The Lore System
+type: note
+author: paradigm
+created: '2026-04-22'
+updated: '2026-04-18'
+tags:
+  - course
+  - para-501
+  - lore-entries-record
+  - seven-entry-types
+  - date-partitioned-yaml-storage
+symbols: []
+difficulty: beginner
+estimatedMinutes: 5
+prerequisites: []
+category: paradigm-core
+origin: imported
+source: courses/para-501.json
+---
+
+## Why Projects Forget
+
+Every software project accumulates institutional knowledge — why a migration was attempted then rolled back, which approach was chosen for caching and why, what the team learned when the billing system went down at 2 AM. Without a system for capturing this knowledge, it lives only in the heads of the people who were there. When they leave, context-switch, or simply forget, the project loses its memory.
+
+Paradigm's Lore system is a structured project timeline. It records sessions, milestones, incidents, retros, reviews, and insights as date-partitioned YAML entries that both humans and AI agents can search, filter, and learn from.
+
+> **v6.0 change:** the `decision` lore type was removed. Architectural decisions now have their own dedicated store — see "Decisions Have Their Own Store" below.
+
+## Anatomy of a Lore Entry
+
+Every lore entry follows a consistent structure:
+
+```yaml
+id: L-2026-02-21-ascend-143025-001
+type: agent-session
+timestamp: "2026-02-21T14:30:25Z"
+duration_minutes: 45
+author: ascend
+agent:
+  provider: anthropic
+  model: claude-opus-4-6
+title: "Add JWT authentication to user routes"
+summary: "Implemented RS256 JWT auth middleware, added ^authenticated and ^project-admin gates to portal.yaml, created refresh token rotation."
+symbols_touched: ["#auth-middleware", "^authenticated", "^project-admin"]
+symbols_created: ["#refresh-token-handler"]
+files_modified: ["src/middleware/auth.ts", "portal.yaml"]
+files_created: ["src/handlers/refresh-token.ts"]
+lines_added: 247
+lines_removed: 12
+commit: "a1b2c3d"
+decisions:
+  - id: jwt-signing
+    decision: "Use RS256 over HS256"
+    rationale: "Allows public key verification without sharing the signing secret"
+learnings:
+  - "Express v5 requires explicit async error wrapping for middleware"
+verification:
+  status: pass
+  details: { "unit-tests": pass, "integration": pass }
+tags: [security, auth]
+```
+
+The `id` field is auto-generated as `L-{date}-{author}-{hhmmss}-{seq}` — date partitions the storage, author and timestamp disambiguate within a day, and the sequence handles burst writes. Note that `author` is the human user (a string), and AI assistance is recorded separately in the optional `agent` object. The `decisions` field on an agent-session entry remains valid — it captures decisions made *during* a work session. Standalone architectural decisions go through `paradigm_decision_record` (see below).
+
+## Entry Types
+
+Lore recognizes seven entry types, each capturing a different kind of project event:
+
+| Type | When to Use |
+|---|---|
+| `agent-session` | An AI agent completed a work session (most common) |
+| `human-note` | A human records context, rationale, or tribal knowledge |
+| `review` | A code review, PR review, or post-mortem |
+| `incident` | A production incident or significant failure |
+| `milestone` | A release, launch, migration completion, or major achievement |
+| `retro` | A retrospective on a sprint, project, or incident response |
+| `insight` | A learned pattern or observation worth preserving |
+
+The type drives how the entry appears in timeline views and which filters surface it.
+
+## Decisions Have Their Own Store
+
+In v6.0 the `decision` lore type was removed. Decisions are first-class enough to deserve their own store, separate from the time-partitioned narrative of lore. Decisions live in `.paradigm/decisions/` as `TD-*` entries, recorded via `paradigm_decision_record`. When you record a decision, Paradigm auto-writes a companion lore `insight` entry pointing at it (with `references.decision_id`) — so the timeline still surfaces the moment the decision was made, while the canonical decision record stays addressable by topic rather than by date.
+
+If you have a v1/v2 project with old `type: decision` lore entries, the storage layer migrates them to type `insight` on read and tags them `v6-migrated:from-decision` for forensic recovery. New entries with `type: 'decision'` are rejected at the storage layer with an error pointing you at the decision-record path. The rejection envelope (`code: 'lore_type_decision_removed'`, `successor_tool: 'paradigm_decision_record'`) is structured so calling agents can auto-retry without human intervention.
+
+Search hierarchy:
+- Use `paradigm_lore_search` for narrative ("what happened on 2026-02-21?").
+- Use `paradigm_decision_search` for canonical choices ("what did we decide about caching?").
+
+## Storage: Date-Partitioned YAML
+
+Lore entries live in `.paradigm/lore/entries/` organized by date. Filenames mirror the entry id (`L-{date}-{author}-{hhmmss}-{seq}.yaml`), so you can identify the author and burst order from the filename alone:
+
+```
+.paradigm/lore/
+  timeline.yaml          # Index metadata
+  entries/
+    2026-02-19/
+      L-2026-02-19-ascend-091203-001.yaml
+      L-2026-02-19-matt-143812-001.yaml
+    2026-02-20/
+      L-2026-02-20-ascend-101545-001.yaml
+    2026-02-21/
+      L-2026-02-21-ascend-143025-001.yaml
+```
+
+The `timeline.yaml` index tracks total entry count, last updated timestamp, and known authors. Date partitioning keeps directories small and makes time-range queries efficient — to find entries from last week, you only read 7 directories.
+
+## CLI Tools
+
+The CLI provides full lore management:
+
+- `paradigm lore list` — List entries with filters (author, type, symbol, date range, tags)
+- `paradigm lore show <id>` — Full detail view of a single entry
+- `paradigm lore record` — Record a new entry with expanded fields (files-modified, files-created, commit, learnings, duration)
+- `paradigm lore edit <id>` — Edit entry fields (title, summary, type, symbols, tags, learnings)
+- `paradigm lore delete <id>` — Delete an entry (with --yes to skip confirmation)
+- `paradigm lore timeline` — Timeline view grouped by date with hot symbols
+- `paradigm lore review <id>` — Add review scores to an entry
+- `paradigm lore` — Launch the web timeline UI
+
+## MCP Tools
+
+The Lore system exposes the following MCP tools:
+
+**`paradigm_lore_record`** — Create a new entry. Requires `type`, `title`, `summary`, and `symbols_touched`. Optional fields include files, decisions, learnings, and verification status. The entry is written to the correct date directory with an auto-incremented ID. When `validateSymbols: true` is passed, the tool checks each symbol in `symbols_touched` against registered symbols in `.purpose` files, `flows.yaml`, and `portal.yaml`. Unregistered symbols produce advisory warnings (the entry is always recorded regardless). Calling with `type: 'decision'` returns a structured rejection envelope pointing at `paradigm_decision_record`.
+
+**`paradigm_lore_search`** — Query entries with filters: by symbol, author, type, date range, tags, review status, and minimum completeness score. Returns matching entries sorted by recency.
+
+**`paradigm_lore_timeline`** — Get a high-level view: recent entries, active authors, hot symbols (most-referenced in recent entries), and timeline metadata. Use this for orientation — it tells you what has been happening in the project.
+
+**`paradigm_lore_get`** — Fetch a single entry by ID. Returns the full entry with all fields, including decisions, learnings, and review data.
+
+**`paradigm_lore_update`** — Update an existing entry. Pass the entry ID and the fields to change (title, summary, type, symbols, tags, learnings). Only specified fields are modified.
+
+**`paradigm_lore_delete`** — Delete an entry by ID. Requires `confirm: true` to prevent accidental deletion.
+
+**`paradigm_lore_assess`** — Score an entry's quality and completeness (1-5 each), with optional notes. The assessment is stored alongside the entry and feeds the calibration and review filters.
+
+**`paradigm_lore_calibration`** — Surface calibration drift: entries where the recorded confidence diverges from later-observed reality. Use this to find sessions where an agent over- or under-estimated its certainty.
+
+## Lore Reviews
+
+Entries can be reviewed by humans after the fact. A review adds a `completeness` score (1-5), a `quality` score (1-5), and optional notes. This creates a feedback loop: agents learn which sessions produced high-quality entries and can adjust their recording behavior. You can filter entries by `hasReview` and `minCompleteness` to surface only verified project history.
+
+## When to Record
+
+The general rule: **record lore when a session modifies 3 or more source files**. This threshold captures significant work sessions while ignoring trivial edits. The stop hook enforces this — if you modified 3+ files without recording a lore entry, it will block your session from completing.
+
+Beyond the threshold, always record lore for: production incidents, milestone completions, retros, and any session where you learned something the next developer should know. For standalone architectural decisions, use `paradigm_decision_record` instead — the decision store handles them, and a companion lore `insight` is auto-written for timeline coverage.
+
+> **Going deeper:** PARA 601 covers knowledge streams (work-log, journal, decisions) and how `paradigm_decision_record` writes to the decisions stream while emitting a companion lore `insight` for timeline coverage. PARA 301 covers the new dedicated decision store in detail (`N-para-301-decisions`).