@a-company/paradigm 5.38.0 → 6.0.2

package/dist/university-content/notes/N-para-401-orchestration-workflow.md

@@ -0,0 +1,101 @@
+---
+id: N-para-401-orchestration-workflow
+title: Orchestration Workflow
+type: note
+author: paradigm
+created: '2026-04-22'
+updated: '2026-04-22'
+tags:
+  - course
+  - para-401
+  - five-step-workflow-describe
+  - paradigmorchestrateinline-plan-then
+  - parallel-stage-launching
+symbols: []
+difficulty: beginner
+estimatedMinutes: 3
+prerequisites: []
+category: paradigm-core
+origin: imported
+source: courses/para-401.json
+---
+
+## Orchestration Workflow
+
+This lesson walks through the complete end-to-end orchestration workflow, from task description to final result. Understanding this workflow is essential for effectively coordinating multi-agent tasks in Paradigm.
+
+### Step 1: Describe the Task
+
+Start with a clear, specific task description. Good task descriptions include what you want to build, which areas are involved, and any constraints:
+
+- Good: "Add Apple Pay to the checkout flow with amount validation and ^authenticated gate"
+- Bad: "Fix payments"
+
+The quality of the task description directly affects the quality of the orchestration plan.
+
+### Step 2: Plan with paradigm_orchestrate_inline
+
+Call `paradigm_orchestrate_inline` with `mode="plan"` to get the orchestrator's analysis:
+
+```
+paradigm_orchestrate_inline({
+  task: "Add Apple Pay to the checkout flow with amount validation and ^authenticated gate",
+  mode: "plan"
+})
+```
+
+The plan returns: suggested agents, estimated token cost, and a stage breakdown with dependency information. Review this carefully. If you disagree with the agent selection, you can override it with the `agents` parameter.
+
+### Step 3: Execute to Get Prompts
+
+Once satisfied with the plan, call with `mode="execute"`:
+
+```
+paradigm_orchestrate_inline({
+  task: "Add Apple Pay to the checkout flow with amount validation and ^authenticated gate",
+  mode: "execute"
+})
+```
+
+This returns full prompts for each agent, complete with relevant file paths, symbol context, and stage-specific instructions.
+
+### Step 4: Launch Agents
+
+Launch agents according to the stage plan. Stages marked `canRunParallel: true` can be launched simultaneously:
+
+```
+// Stages 1 and 2 can run in parallel:
+Task: [architect prompt from execute output]
+Task: [security prompt from execute output]
+
+// Stage 3 depends on 1 and 2, must wait:
+Task: [builder prompt with handoff context from architect and security]
+
+// Stage 4 depends on 3:
+Task: [tester prompt with handoff context from builder]
+```
+
+### Step 5: Collect and Integrate Results
+
+Each agent returns results in its configured relay format. Review each output, verify it makes sense, and integrate the changes. The orchestrator does not auto-merge -- you are the final integrator.
+
+### CLI Alternative
+
+For command-line orchestration, the `paradigm team orchestrate` command handles the full workflow:
+
+```bash
+# Multi-agent (default)
+paradigm team orchestrate "Add Apple Pay to checkout"
+
+# Single agent mode -- one agent does everything
+paradigm team orchestrate "Add Apple Pay to checkout" --solo
+
+# A/B test -- compare solo vs multi-agent
+paradigm team orchestrate "Add Apple Pay to checkout" --compare
+```
+
+The `--solo` flag is useful when a task does not genuinely need multiple agents. The `--compare` flag runs both solo and faceted modes and lets you compare the results, which is valuable for learning when orchestration adds value versus overhead.
+
+### When NOT to Orchestrate
+
+Orchestration has overhead. For simple tasks (single file change, no security implications, clear implementation), a single builder agent is faster and cheaper. Use orchestration when the task involves 3+ files, has security implications, requires design decisions, or spans multiple feature areas.

package/dist/university-content/notes/N-para-401-pm-governance.md

@@ -0,0 +1,71 @@
+---
+id: N-para-401-pm-governance
+title: PM Governance
+type: note
+author: paradigm
+created: '2026-04-22'
+updated: '2026-04-22'
+tags:
+  - course
+  - para-401
+  - pre-flight-checks-symbols
+  - post-flight-checks-registration
+  - errorwarningsuggestion-severity-levels
+symbols: []
+difficulty: beginner
+estimatedMinutes: 3
+prerequisites: []
+category: paradigm-core
+origin: imported
+source: courses/para-401.json
+---
+
+## PM Governance
+
+The PM (Project Manager) layer is Paradigm's enforcement mechanism that ensures orchestrated tasks follow project discipline. Without governance, agents might implement features without updating `.purpose` files, add endpoints without portal.yaml gates, or ignore team wisdom. The PM layer adds automated pre-flight and post-flight checks that catch these oversights.
+
+### Pre-Flight Checks
+
+Before any implementation begins, the PM runs pre-flight checks to set up the task correctly:
+
+1. **Symbol identification** -- What symbols will this task create or modify? The PM uses `paradigm_search` and `paradigm_navigate` to identify all affected symbols.
+2. **Ripple analysis** -- For each affected symbol, run `paradigm_ripple` to map the blast radius. Flag any fragile dependents.
+3. **Portal requirements** -- If the task adds endpoints, run `paradigm_gates_for_route` to determine required gates. Flag if portal.yaml is missing or needs updates.
+4. **Wisdom check** -- Pull relevant wisdom with `paradigm_wisdom_context` to surface antipatterns and decisions that agents should know about.
+5. **Orchestration recommendation** -- Based on task complexity, recommend whether to use single-agent or multi-agent orchestration.
+
+```
+// Pre-flight output example:
+{
+  affectedSymbols: ["#payment-service", "$checkout-flow"],
+  rippleImpact: { direct: 3, indirect: 7, fragile: ["#notification-handler"] },
+  portalRequired: true,
+  requiredGates: ["^authenticated", "^payment-authorized"],
+  relevantWisdom: ["antipattern: api-001 (direct API calls from UI)"],
+  recommendation: "multi-agent: architect + security + builder"
+}
+```
+
+### Post-Flight Checks
+
+After implementation completes, the PM verifies compliance:
+
+1. **Purpose registration** -- Are all new components registered in `.purpose` files? Did renamed symbols get updated across all references?
+2. **Portal compliance** -- Are all new endpoints listed in portal.yaml with appropriate gates? Are there unprotected routes that should be protected?
+3. **Aspect anchors** -- If aspects were modified, do their anchors still point to valid code?
+4. **Wisdom capture** -- Were any decisions made during implementation that should be recorded? Did any antipatterns surface?
+5. **History recording** -- Was the implementation logged with `paradigm_history_record`?
+
+The PM reports issues in categories: **errors** (must fix before proceeding), **warnings** (should fix), and **suggestions** (good practice). A clean post-flight means full compliance.
+
+### Enabling PM Governance
+
+In the CLI, add the `--pm` flag to orchestrate commands:
+
+```bash
+paradigm team orchestrate "Add refund endpoint" --pm
+```
+
+This wraps the orchestration with pre-flight checks before the first agent runs and post-flight checks after the last agent completes. The PM does not modify code itself -- it reviews and reports, leaving fixes to you or the agents.
+
+PM governance is especially valuable for teams onboarding new developers or working with AI agents that do not yet have deep project familiarity. It is the safety net that ensures Paradigm metadata stays consistent with the code, regardless of who (or what) is writing that code.

package/dist/university-content/notes/N-para-401-provider-cascade.md

@@ -0,0 +1,75 @@
+---
+id: N-para-401-provider-cascade
+title: Provider Cascade
+type: note
+author: paradigm
+created: '2026-04-22'
+updated: '2026-04-22'
+tags:
+  - course
+  - para-401
+  - six-providers-claude
+  - cascade-tries-providers
+  - three-configuration-methods
+symbols: []
+difficulty: beginner
+estimatedMinutes: 3
+prerequisites: []
+category: paradigm-core
+origin: imported
+source: courses/para-401.json
+---
+
+## Provider Cascade
+
+Orchestrated agents need somewhere to run. Paradigm supports multiple **execution providers** -- the systems that actually run the agent prompts and return results. Since not every environment has the same providers available (some teams use the Anthropic API directly, others use Claude Code, others use Cursor), Paradigm implements a **cascade** that tries providers in priority order until one works.
+
+The default cascade order is:
+
+### Anthropic / Claude Ecosystem
+
+1. **`claude`** -- Direct Anthropic API. Requires `ANTHROPIC_API_KEY` environment variable. The most flexible option with full control over model selection and parameters.
+
+2. **`claude-code-teams`** -- Claude Code Agent Teams (experimental). Supports parallel agent execution natively. Only available with Claude Code Teams subscription.
+
+3. **`claude-code`** -- Claude Code Task tool. Uses the Task tool within a Claude Code session. Requires a Max subscription. Runs agents as sub-tasks within the current session.
+
+5. **`claude-cli`** -- Spawns separate `claude` CLI processes. Each agent runs as an independent CLI invocation. Available when the Claude CLI is installed.
+
+### Cursor Ecosystem
+
+4. **`cursor-cli`** -- Cursor's agent CLI. Auto-detected when running inside the Cursor IDE. Spawns agents through Cursor's built-in agent system.
+
+### Universal
+
+6. **`manual`** -- File-based handoffs. Always available as a fallback. Writes agent prompts to files that a human (or another tool) can execute. This is the universal fallback that works in every environment.
+
+### Configuration
+
+You can set the preferred provider in three ways (listed in priority order):
+
+```bash
+# Environment variable (highest priority)
+export PARADIGM_AGENT_PROVIDER=claude-code
+
+# Config file (.paradigm/config.yaml)
+agent-provider: claude-code
+
+# CLI command
+paradigm team providers --set claude-code
+```
+
+Setting a preferred provider does not disable the cascade -- it just changes the starting point. If your preferred provider is unavailable (e.g., API key expired), the cascade continues to the next available option.
+
+To see which providers are currently available in your environment, run:
+
+```bash
+paradigm team providers
+# Shows: claude (available), claude-code (available), cursor-cli (not detected), ...
+```
+
+### Model Discovery
+
+Different providers expose different models. `paradigm team models` shows the current model assignments per agent role and which provider serves them. If you add a new API key or install a new tool, run `paradigm team models --refresh` to re-discover available models.
+
+The cascade design means Paradigm orchestration works everywhere -- from a fully-equipped development machine with API keys and IDE integrations, down to a bare terminal where only manual file-based handoffs are possible. The fallback is always there.

package/dist/university-content/notes/N-para-401-quick-check.md

@@ -0,0 +1,95 @@
+---
+id: N-para-401-quick-check
+title: 'Quick-Check: Ask Before You Build'
+type: note
+author: paradigm
+created: '2026-04-22'
+updated: '2026-04-22'
+tags:
+  - course
+  - para-401
+  - quick-check-is-a
+  - two-agents-jinx
+  - two-outcomes-greenlight
+symbols: []
+difficulty: beginner
+estimatedMinutes: 3
+prerequisites: []
+category: paradigm-core
+origin: imported
+source: courses/para-401.json
+---
+
+## The Lightweight Pre-Check
+
+Not every task needs full orchestration with architect, security, builder, tester, and reviewer stages. Sometimes you just want to know: *is this task ready to build, or does it need more planning?*
+
+That is what **quick-check mode** does. It runs a lightweight risk assessment (~3–4k tokens) and returns one of two verdicts:
+
+- **GREENLIGHT** — proceed to implementation. The task is well-scoped, low-risk, and does not need multi-agent planning.
+- **ESCALATE** — this needs full orchestration. The task has unaddressed risks, ambiguous requirements, or cross-cutting concerns.
+
+### How It Works
+
+Quick-check uses two agents:
+
+**Jinx (advocate)** stress-tests your assumptions:
+- "What if the user loses their second factor?"
+- "What happens when the payment provider is down?"
+- "Did you consider rate limiting on this endpoint?"
+
+**Reviewer** checks feasibility:
+- Does this touch auth, security, or shared state?
+- How many files will this change?
+- Are there dependencies that need updating?
+
+Their combined assessment produces the verdict. If either agent raises concerns that cannot be resolved in a quick check, the verdict is ESCALATE.
+
+### Usage
+
+```
+paradigm_orchestrate_inline({
+  task: "Add a 'last seen' timestamp to user profiles",
+  mode: "quick"
+})
+```
+
+Compare with full orchestration:
+```
+paradigm_orchestrate_inline({
+  task: "Add two-factor authentication to the login flow",
+  mode: "plan"
+})
+```
+
+### When to Use Quick-Check vs Full Orchestration
+
+| Signal | Quick-Check | Full Orchestration |
+|--------|-------------|-------------------|
+| Single file change | Yes | Overkill |
+| UI-only change (styling, layout) | Yes | Overkill |
+| Touches auth or security | Depends on scope | Usually yes |
+| 3+ files affected | Depends on complexity | Yes |
+| New API endpoint | Depends on gates needed | Usually yes |
+| Infrastructure change | No | Yes |
+| Unknown scope ("make it faster") | No | Yes |
+
+**Rule of thumb:** If you can describe the complete change in one sentence and it touches ≤2 files, quick-check is appropriate. If you find yourself saying "and also..." or "but we need to consider...", go straight to full orchestration.
+
+### Quick-Check and Enforcement
+
+Quick-check satisfies the `orchestration-required` enforcement check. On balanced or strict enforcement, the stop hook requires that complex tasks go through orchestration before building. A GREENLIGHT from quick-check counts — you do not need to run full orchestration after a greenlight.
+
+However, if you get an ESCALATE verdict and proceed to build anyway, the stop hook will flag that you bypassed the recommendation. The verdict is recorded and traceable.
+
+### Example Walkthrough
+
+**Task:** "Add a 'forgot password' link to the login page"
+
+**Jinx:** "Where does the reset email get sent from? Is there rate limiting on reset requests? What happens if the email is not in the system — do you reveal that?"
+
+**Reviewer:** "This touches auth (password reset flow), requires a new API endpoint (/reset-password), involves email sending infrastructure, and needs rate limiting. Estimated: 4+ files."
+
+**Verdict: ESCALATE** — the task looks simple but involves auth, a new endpoint, email, and rate limiting. Full orchestration with security and architect (multi-file design) is recommended.
+
+Compare: "Change the login button color from blue to green" → **GREENLIGHT** (single CSS change, no logic, no auth).

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

@@ -0,0 +1,122 @@
+---
+id: N-para-501-advanced-workflows
+title: The Complete Workflow
+type: note
+author: paradigm
+created: '2026-04-22'
+updated: '2026-04-22'
+tags:
+  - course
+  - para-501
+  - five-phase-workflow-preflight
+  - session-recovery-provides
+  - post-write-hook-tracks
+symbols: []
+difficulty: beginner
+estimatedMinutes: 5
+prerequisites: []
+category: paradigm-core
+origin: imported
+source: courses/para-501.json
+---
+
+## Putting It All Together
+
+You have learned the five advanced systems individually. Now let's see how they work together in a complete development workflow. Every system has a role, and the handoffs between them create a feedback loop that gets smarter with every session.
+
+## The Full Cycle
+
+Here is the complete Paradigm workflow for a non-trivial task:
+
+### Phase 1: Preflight
+
+```
+1. paradigm_session_recover       → Load previous session context
+2. paradigm_pm_preflight           → Get compliance plan for the task
+3. paradigm_habits_check(preflight) → Verify discovery habits are followed
+4. paradigm_ripple                 → Check impact of planned changes
+5. paradigm_wisdom_context         → Get team knowledge for affected symbols
+6. paradigm_practice_context       → Get habit-aware warnings for symbols
+7. paradigm_session_checkpoint(planning) → Save plan before coding
+```
+
+Notice the layering: session recovery provides continuity, preflight ensures preparation, habits check enforces discovery discipline, ripple and wisdom provide context, practice context adds behavioral awareness, and the checkpoint enables crash recovery.
+
+### Phase 2: Implementation
+
+```
+8. Write code                      → Implement the feature
+   → Post-write hook fires         → Tracks edited files in .pending-review
+   → Post-write advisory           → Reminds about .purpose coverage
+9. Update .purpose files           → Document new/changed symbols
+10. Update portal.yaml             → Add routes and gates (if applicable)
+11. paradigm_session_checkpoint(implementing) → Save progress
+```
+
+The post-write hook acts as a running tally. Every source file edit is tracked, and periodic reminders keep documentation top of mind. Updating .purpose and portal.yaml during implementation (not after) prevents the stop hook from blocking at the end.
+
+### Phase 3: Validation
+
+```
+12. paradigm_flow_check          → Verify flows are complete
+13. paradigm_aspect_check           → Verify aspect anchors are valid
+14. paradigm_pm_postflight          → Run post-implementation governance
+15. paradigm_habits_check(postflight) → Verify documentation/testing habits
+16. paradigm_session_checkpoint(validating) → Save pre-test state
+```
+
+Validation catches issues before they become stop hook violations. Flow validation ensures multi-step processes are complete. Aspect checks confirm anchors point to real code. Postflight governance catches missing .purpose files and undefined gates.
+
+### Phase 4: Recording
+
+```
+17. paradigm_lore_record            → Record the session's work
+18. paradigm_history_record         → Log implementation to symbol history
+19. paradigm_reindex                → Rebuild the symbol index
+20. paradigm_session_checkpoint(complete) → Mark task complete
+```
+
+Recording preserves institutional knowledge. The lore entry captures what was done and why. History record logs implementation details to individual symbol timelines. Reindexing ensures the symbol index reflects all changes.
+
+### Phase 5: Commit
+
+```
+21. git commit                      → Commit changes
+    → Pre-commit hook fires         → Auto-rebuilds index, stages updated files
+    → Stop hook fires               → Validates all compliance checks
+22. If stop hook blocks             → Fix violations, re-attempt
+23. If stop hook passes             → Session complete
+```
+
+The commit phase is where enforcement happens. The pre-commit hook ensures the index is fresh. The stop hook validates everything: .purpose coverage, portal.yaml compliance, aspect anchors, lore recording, and pending review freshness.
+
+## How Systems Reinforce Each Other
+
+The power of the complete workflow is in the feedback loops:
+
+**Sentinel catches what Habits miss.** If an agent skips the `ripple-before-modify` habit and introduces a breaking change, Sentinel records the incident. The practice profile then shows that skipping ripple correlates with incidents — evidence to upgrade the habit severity.
+
+**Lore preserves what Sessions forget.** Session breadcrumbs and checkpoints are ephemeral — they expire after 7 days. Lore entries are permanent. The checkpoint gets you through a crash; the lore entry gets the team through the next 6 months.
+
+**Wisdom surfaces what Lore accumulates.** Lore entries record individual sessions. Wisdom distills patterns across sessions: "every time we modify #payment-service, check for null references on the refund object." Wisdom is lore, refined.
+
+**Hooks enforce what Habits recommend.** Habits at `advisory` severity are suggestions. The stop hook at `block` severity is enforcement. The workflow starts with advice (habits check) and ends with enforcement (stop hook). This graduated approach teaches good behavior before punishing bad behavior.
+
+## Capstone Scenario
+
+Imagine you are adding a refund endpoint to a payment system. Here is how the complete workflow plays out:
+
+1. **Session recover** reveals the previous session added the payment processor but did not add refunds
+2. **Preflight** shows you need to check `#payment-service`, `$checkout-flow`, and `^authenticated`
+3. **Habits check** confirms you called ripple and wisdom — discovery habits followed
+4. **Ripple** shows `#payment-service` has 4 downstream dependents
+5. **Wisdom** warns: "always null-check refund objects — see incident INC-042"
+6. You implement the refund endpoint with proper null checks
+7. **Post-write hook** tracks 5 edited files in `.pending-review`
+8. You update .purpose with `#refund-handler` and portal.yaml with `^refund-eligible` gate
+9. **Postflight** confirms all gates are declared and flows are valid
+10. **Lore record** captures the session with the decision to require `^refund-eligible`
+11. **Commit** triggers pre-commit (index rebuild) and stop hook (all checks pass)
+12. Three weeks later, a similar null reference hits — **Sentinel** matches pattern `payment-null-ref-001` and resolves it in 5 minutes using the recorded fix
+
+This is Paradigm at full power: every system contributing, every session building on the last, every incident making the next resolution faster.

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.