@a-company/paradigm 5.37.11 → 6.0.2

package/dist/university-content/notes/N-para-501-aspect-graph-advanced.md

@@ -0,0 +1,195 @@
+---
+id: N-para-501-aspect-graph-advanced
+title: The Aspect Graph at Scale
+type: note
+author: paradigm
+created: '2026-04-22'
+updated: '2026-04-22'
+tags:
+  - course
+  - para-501
+  - 8-built-in-detectors
+  - custom-detectors-defined
+  - bfs-traversal-with
+symbols: []
+difficulty: beginner
+estimatedMinutes: 8
+prerequisites: []
+category: paradigm-core
+origin: imported
+source: courses/para-501.json
+---
+
+## Beyond the Basics
+
+PARA 201 introduced the Aspect Graph's internals — the SQLite schema, materialization pipeline, and recursive ripple. This lesson takes you deeper: building custom detectors, advanced graph queries, drift detection in CI/CD, search learning optimization, and governing aspects at enterprise scale.
+
+## Building Custom Aspect Detection Patterns
+
+Paradigm ships with 8 built-in detectors that `paradigm_aspect_suggest_scan` uses to find undocumented aspects in source code:
+
+1. **Magic numbers** — Numeric literals that aren't 0 or 1 (e.g., `timeout: 30000`, `maxRetries: 3`)
+2. **Hardcoded strings** — String literals used in conditionals or assignments that smell like configuration (e.g., `'production'`, `'us-east-1'`)
+3. **Rate limits** — Patterns like `rateLimit(100)`, `throttle(1000)`, or variable names containing `limit`, `throttle`, `quota`
+4. **Time values** — Durations, timeouts, TTLs, and expiry values (e.g., `86400`, `24 * 60 * 60`)
+5. **Environment checks** — `process.env`, `std::env`, `os.environ` patterns that branch on environment variables
+6. **Feature flags** — Conditional logic gated on feature names (e.g., `isEnabled('new-checkout')`, `featureFlags.get()`)
+7. **Regex patterns** — Regular expressions used for validation (e.g., email patterns, URL matchers)
+8. **Assertion guards** — Invariant checks using `assert`, `invariant()`, `expect()` that enforce guarantees
+
+To extend the detection system, you define custom detectors in `.paradigm/aspect-detectors.yaml`:
+
+```yaml
+detectors:
+  - id: compliance-annotation
+    name: Compliance Annotations
+    description: Detects SOC2/GDPR compliance annotations in code
+    patterns:
+      - regex: "@(SOC2|GDPR|PCI|HIPAA)"
+        languages: [typescript, javascript, java]
+      - regex: "#\[compliance\("
+        languages: [rust]
+    suggestedCategory: rule
+    suggestedSeverity: critical
+    suggestedTags: [compliance, security]
+
+  - id: retry-policy
+    name: Retry Policies
+    description: Detects retry/backoff configurations
+    patterns:
+      - regex: "(retryPolicy|backoff|maxAttempts|retryCount)"
+        languages: [typescript, javascript, python]
+    suggestedCategory: configuration
+    suggestedSeverity: medium
+```
+
+Custom detectors are loaded alongside the built-in 8 during `paradigm_aspect_suggest_scan`. They follow the same interface: match source code patterns, suggest a category and severity, and let the user decide whether to formalize the finding as a `~aspect`.
+
+## Graph Querying Strategies
+
+The aspect graph supports three primary querying patterns, each suited to different use cases:
+
+### BFS Traversal (Neighborhood Analysis)
+
+`paradigm_aspect_graph` uses breadth-first search to explore the neighborhood of a symbol. The `hops` parameter controls how far to traverse:
+
+- **1 hop** — Direct connections only. Use this when you need to know what a single aspect directly relates to. Fast, focused, minimal noise.
+- **2 hops** — Friends-of-friends. Reveals indirect relationships: "this aspect relates to that aspect, which relates to that component." The sweet spot for most queries.
+- **3+ hops** — Extended neighborhood. Useful for understanding how distant parts of the codebase connect through aspects. Gets noisy in dense graphs.
+
+The multiplicative weight decay means that each hop reduces confidence. An explicit edge (weight 1.0) followed by an inferred edge (weight 0.5) produces a path weight of 0.5. Two inferred edges produce 0.25. The `minWeight` threshold (default 0.1) prunes low-confidence paths automatically.
+
+### Heatmap-Driven Exploration
+
+`paradigm_aspect_heatmap` ranks aspects by access frequency. This is not about what aspects ARE important — it is about what aspects are USED most. The distinction matters:
+
+- An aspect accessed 50 times via search but never via ripple might have a discoverability problem — people search for it because it is hard to find through the graph.
+- An aspect accessed primarily via ripple has good graph connectivity — it naturally surfaces during impact analysis.
+- An aspect with zero access across all types may be stale, poorly named, or irrelevant.
+
+Heatmap data is the starting point for governance reviews. Aspects that nobody accesses should be evaluated for removal or renaming.
+
+### Edge-Filtered Queries
+
+When calling `paradigm_aspect_graph`, you can filter by edge relation to narrow results:
+
+- `enforced-by` — Find all aspects that enforce a given component. Useful when changing a component to know what rules apply.
+- `depends-on` — Find dependency chains. If `~token-expiry-24h` depends-on `~jwt-signing-rs256`, changing JWT signing affects token expiry.
+- `contradicts` — Find conflicting aspects. Two aspects that contradict each other signal an architectural tension that needs resolution.
+- `supersedes` — Find deprecated-but-still-referenced aspects. The superseding aspect should be the authoritative one.
+- `related-to` — The weakest relation. Useful for discovery but not for impact analysis.
+
+## Drift Detection in CI/CD
+
+Aspect drift occurs when the code at an anchor location changes without updating the aspect definition. The `paradigm_aspect_drift` tool detects this using SHA-256 content hashes.
+
+During materialization, the pipeline computes a SHA-256 hash of the code at each anchor's line range and stores it in the `anchors.content_hash` column. When `paradigm_aspect_drift` runs later, it re-reads the code at those line ranges, computes a new hash, and compares. A mismatch means the code changed — the anchor is drifted.
+
+For CI/CD integration, add drift detection as a pipeline step:
+
+```yaml
+# .github/workflows/paradigm.yml
+steps:
+  - name: Check aspect drift
+    run: |
+      paradigm scan --quiet
+      paradigm doctor --strict --json | jq '.aspects.drifted'
+      if [ $(paradigm doctor --json | jq '.aspects.drifted | length') -gt 0 ]; then
+        echo "::error::Aspect anchors have drifted"
+        exit 1
+      fi
+```
+
+The `--strict` flag treats drifted anchors as errors rather than warnings. In a mature project, you want drift detection to block merges — it ensures that aspect documentation stays synchronized with code changes.
+
+Drift detection is also available per-aspect via the MCP tool:
+
+```
+paradigm_aspect_drift({ aspectId: 'token-expiry-24h' })
+```
+
+This returns: the aspect ID, each anchor with its stored hash vs current hash, whether each anchor has drifted, and the specific lines that changed. Use this during code review to verify that refactors updated their aspect anchors.
+
+## Search Learning Loop Optimization
+
+The three-tier search system improves over time through the confirm-and-decay mechanism. Here is how to optimize it:
+
+### Tier Priority
+
+1. **Tier 1: Learned mappings** — Query-to-aspect weights in the `search_weights` table. If a query matches a stored mapping with weight >= 1.0, the result is returned immediately. This is instant because it is a simple key-value lookup.
+2. **Tier 2: FTS5 full-text search** — SQLite's FTS5 engine searches aspect descriptions, values, and categories. Returns results ranked by BM25 relevance. Accurate but slower than Tier 1.
+3. **Tier 3: Fuzzy matching** — Levenshtein distance-based matching with a configurable threshold. Catches typos and partial matches. Slowest but most forgiving.
+
+### Warming the Learning System
+
+A new project's search starts cold — no learned mappings exist. Every search falls through to Tier 2 or 3. To warm the system:
+
+1. Run common queries for your project's domain (e.g., search for 'expiry', 'rate limit', 'auth')
+2. Confirm the best result with `paradigm_aspect_confirm` for each query
+3. After 3-5 confirmations per query, the learned weight exceeds the Tier 1 threshold
+
+The decay mechanism (confirmed +1.0, others *0.95) means that a single confirmation is enough to create a Tier 1 entry. But multiple confirmations build a stronger mapping that resists displacement.
+
+### Diagnosing Search Issues
+
+When search returns unexpected results:
+
+- Check `search_weights` table entries for the query — are stale mappings dominating?
+- Verify aspect descriptions contain the keywords you are searching for (FTS5 searches descriptions)
+- Check for typos in the query that might prevent Tier 2 matches but trigger Tier 3 fuzzy results
+- Use `paradigm_aspect_heatmap` to see if the expected aspect is ever accessed — a zero-access aspect might have a discovery problem
+
+## Aspect Governance at Scale
+
+When a project exceeds 100 aspects, governance becomes critical. Without it, aspects accumulate as stale documentation, anchor drift goes undetected, and the graph becomes noisy rather than useful.
+
+### The Governance Review Cycle
+
+Run quarterly aspect reviews using this process:
+
+1. **Heatmap analysis** — `paradigm_aspect_heatmap({ limit: 0 })` returns ALL aspects ranked by access. The bottom 20% are candidates for removal or consolidation.
+2. **Drift audit** — `paradigm doctor --strict` catches all drifted anchors. Drifted aspects either need anchor updates or should be marked stale.
+3. **Category distribution** — Check that aspect categories are balanced. A project with 80 rules and 2 decisions might be over-documenting constraints while missing strategic choices.
+4. **Edge health** — Check for orphaned aspects (no edges to any other symbol). An aspect with zero edges is either standalone (legitimate but rare) or poorly connected.
+5. **Search weight review** — Check the `search_weights` table for queries with multiple high-weight mappings, which indicate ambiguous terminology.
+
+### Naming Conventions at Scale
+
+With 100+ aspects, naming collisions and ambiguity become real problems. Establish conventions:
+
+- **Category prefix** — Prefix aspects with their category: `~rule-no-console-log`, `~decision-use-redis`, `~constraint-max-upload-10mb`
+- **Domain grouping** — Group related aspects by domain: `~auth-token-expiry`, `~auth-session-timeout`, `~auth-refresh-rotation`
+- **Version suffix** — When aspects evolve: `~rate-limit-v2` supersedes `~rate-limit-v1` with an explicit `supersedes` edge
+
+### Delegation and Ownership
+
+For large teams, assign aspect ownership:
+
+```yaml
+~payment-idempotency:
+  description: Payment operations must be idempotent
+  owner: payments-team
+  reviewers: [platform-team, security-team]
+```
+
+The `owner` field indicates who maintains the aspect, and `reviewers` lists teams that should be consulted when the aspect changes. This is purely metadata — Paradigm does not enforce it — but it guides humans and AI agents when modifications are needed.

package/dist/university-content/notes/N-para-501-aspect-graph-internals.md

@@ -0,0 +1,97 @@
+---
+id: N-para-501-aspect-graph-internals
+title: Aspect Graph Internals
+type: note
+author: paradigm
+created: '2026-04-22'
+updated: '2026-04-22'
+tags:
+  - course
+  - para-501
+  - six-sqlite-tables
+  - recursive-ripple-uses
+  - default-maxdepth-is
+symbols: []
+difficulty: beginner
+estimatedMinutes: 6
+prerequisites: []
+category: paradigm-core
+origin: imported
+source: courses/para-501.json
+---
+
+## SQLite Schema
+
+The aspect graph database at `.paradigm/aspect-graph.db` uses six core tables that model the full aspect ecosystem:
+
+**`aspects`** — The primary table storing aspect metadata. Columns include `id` (the aspect symbol, e.g., `token-expiry-24h`), `description`, `value`, `category` (rule/decision/constraint/configuration/invariant), `severity` (low/medium/high/critical), and `content_hash` (SHA-256 of the combined anchor code for drift detection). Each row represents one aspect from a `.purpose` file.
+
+**`anchors`** — Stores code anchor locations. Columns: `aspect_id` (foreign key to aspects), `file_path`, `start_line`, `end_line`, and `content_hash` (SHA-256 of the code at those lines). An aspect can have multiple anchors across different files.
+
+**`edges`** — The graph edges connecting aspects to other symbols. Columns: `source` (the aspect), `target` (any symbol), `relation` (enforced-by, depends-on, contradicts, supersedes, related-to), `weight` (numeric confidence, default 1.0 for explicit edges), and `origin` (explicit, inferred, or learned). This table is what makes the aspect system a graph rather than a flat list.
+
+**`lore_links`** — Connects aspects to lore entries. Columns: `aspect_id` and `lore_id`. These links are materialized from the `lore` field in aspect YAML definitions, and additional links are inferred when two aspects share lore references.
+
+**`search_weights`** — The learning system's memory. Columns: `query` (the search string), `aspect_id` (the result), and `weight` (accumulated confidence). This table powers Tier 1 of the three-tier search — when a query matches a stored mapping with sufficient weight, the result is returned immediately without FTS5 or fuzzy matching.
+
+**`heatmap`** — Tracks aspect access patterns. Columns: `aspect_id`, `access_type` (search, ripple, navigate, direct), `count`, and `last_accessed`. This data drives the `paradigm_aspect_heatmap` tool, revealing which aspects are most frequently referenced and how they are typically discovered.
+
+## Recursive Ripple
+
+The aspect graph enables recursive ripple analysis — when you call `paradigm_ripple` on a symbol that has aspect edges, the ripple follows those edges to discover indirect impacts. The algorithm uses weighted breadth-first search (BFS) with three configurable parameters:
+
+- **maxDepth** — How many hops to traverse. Default is 5, maximum is 10. Each hop follows one edge in the graph. At depth 1, you see direct connections. At depth 5, you see connections five edges away.
+- **minWeight** — The minimum cumulative weight to continue traversal. Default is 0.1. As the BFS traverses edges, it multiplies the current weight by each edge's weight (multiplicative decay). When the cumulative weight drops below minWeight, that branch is pruned.
+- **Queue limit** — Maximum BFS queue size: 1000 nodes. This prevents runaway traversals in densely connected graphs. If the queue exceeds 1000 entries, the oldest entries are dropped.
+
+The multiplicative decay is the key mechanism. An explicit edge with weight 1.0 passes full confidence to the next hop. An inferred edge with weight 0.5 halves the confidence. After two inferred edges, the weight is 0.25 — and after four, it drops to 0.0625, below the default minWeight threshold. This naturally limits traversal depth through low-confidence paths while allowing full traversal through high-confidence ones.
+
+## Heatmap Tracking
+
+Every time an aspect is accessed through any MCP tool, the heatmap table records the access. Four access types are tracked:
+
+- **search** — The aspect was found via `paradigm_aspect_search`
+- **ripple** — The aspect was encountered during `paradigm_ripple` traversal
+- **navigate** — The aspect was discovered via `paradigm_navigate`
+- **direct** — The aspect was accessed by ID via `paradigm_aspect_get`
+
+The heatmap serves two purposes. First, it powers the `paradigm_aspect_heatmap` tool, which ranks aspects by access frequency and reveals usage patterns. Second, it provides data for project health analysis — aspects that are never accessed may be stale or poorly named, while aspects accessed frequently across multiple types are clearly central to the project.
+
+## Materialization Pipeline
+
+The aspect graph is rebuilt during `paradigm_reindex` through a five-step pipeline:
+
+1. **openAspectGraph** — Opens (or creates) the SQLite database at `.paradigm/aspect-graph.db`. If the database exists, all tables are cleared for a fresh rebuild. This ensures the graph always reflects the current state of YAML files.
+
+2. **materializeAspects** — Reads all `.purpose` files, extracts aspect definitions, and writes them to the `aspects`, `anchors`, and `edges` tables. For each anchor, the pipeline reads the actual source code at the specified line range and computes a SHA-256 content hash. Explicit edges from the YAML `edges` field are written with origin `explicit` and weight 1.0. Inferred edges from `applies-to` references are written with origin `inferred` and weight 0.5.
+
+3. **materializeLoreLinks** — Reads the `lore` field from each aspect and creates entries in the `lore_links` table connecting aspects to their referenced lore entries.
+
+4. **inferLoreEdges** — Scans the `lore_links` table for aspects that share lore references. When two aspects both reference the same lore entry, a learned edge is created between them with origin `learned` and a weight proportional to the number of shared references. This discovers implicit relationships that were not explicitly declared.
+
+5. **closeAspectGraph** — Commits all changes, runs ANALYZE for query optimization, and closes the database connection.
+
+Because the entire graph is rebuilt from YAML on every reindex, there is no migration or versioning concern. If the schema changes in a future Paradigm version, the next reindex simply creates the new schema.
+
+## Category Inference
+
+When an aspect definition omits the `category` field, the materialization pipeline attempts to infer it from the description using keyword matching:
+
+- Descriptions containing "must", "always", "never", "required" suggest `rule`
+- Descriptions containing "decided", "chosen", "selected", "opted" suggest `decision`
+- Descriptions containing "limit", "maximum", "minimum", "cannot exceed" suggest `constraint`
+- Descriptions containing "configured", "set to", "defaults to", "environment" suggest `configuration`
+- Descriptions containing "always true", "never negative", "invariant", "guarantee" suggest `invariant`
+
+Similarly, severity can be inferred from tags: aspects tagged `[critical]` or `[security]` default to `high` severity, aspects tagged `[compliance]` default to `critical`, and untagged aspects default to `medium`.
+
+Inference is a fallback — explicit `category` and `severity` fields in YAML always take precedence.
+
+## Weight Decay in Search Learning
+
+The search learning system uses a reinforcement model. When `paradigm_aspect_confirm` is called with a query and aspect ID:
+
+1. The selected result's weight for that query gets **+1.0** added to its current weight in the `search_weights` table. If no entry exists, one is created with weight 1.0.
+2. All other aspects that were previously returned for the same query get their weights multiplied by **0.95** (a 5% decay). This applies only to aspects that have existing `search_weights` entries for this query — it does not penalize aspects that were never returned for this query.
+
+This mechanism is self-correcting. If result A is consistently confirmed for a query, its weight grows (1.0, 2.0, 3.0, ...) while alternatives decay (1.0, 0.95, 0.9025, ...). After enough confirmations, the learned mapping becomes dominant and Tier 1 returns it instantly. But if the user later confirms a different result B for the same query, B starts climbing while A begins decaying — the system adapts to changing preferences without requiring manual intervention.

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.