@a-company/paradigm 5.38.0 → 6.0.4

package/dist/university-content/notes/N-para-451-tiers.md

@@ -0,0 +1,81 @@
+---
+id: N-para-451-tiers
+title: Model Tiers — Which Claude Each Agent Runs On
+type: note
+author: paradigm
+created: '2026-04-26'
+updated: '2026-04-26'
+tags:
+  - course
+  - para-451
+  - tier-1
+  - tier-2
+  - tier-3
+  - model-tier
+  - taxonomy
+symbols: []
+difficulty: beginner
+estimatedMinutes: 4
+prerequisites:
+  - N-para-451-welcome
+category: paradigm-core
+origin: authored
+source: agents-course-phase-a-design.md
+---
+
+## Tier = which model the agent runs on
+
+In Paradigm, an agent's **tier** answers a single question: *which Claude model does this agent invoke by default?* That is it. Tier is a routing decision, not a status ranking, not a capability label, and — importantly — not the same thing as the v6.1 notebook tier (that one is covered separately; see the callout at the end).
+
+The three tiers map to the three Claude model classes:
+
+| Tier | Default model | Cost / latency profile | Typical role fit |
+|------|---------------|------------------------|------------------|
+| **Tier 1** | opus | Most capable, highest cost, slowest | Design, threat analysis, simulation, learning-loop reasoning — work where one extra IQ point pays for itself many times over. |
+| **Tier 2** | sonnet | Balanced capability and cost | Review, documentation, devil's-advocacy, ecosystem specialists — work that needs depth but not the maximum. |
+| **Tier 3** | haiku | Fast, low cost | Implementation, test writing, mechanical execution — well-defined work where speed and volume matter. |
+
+## The match is to the work, not the agent
+
+A Tier-3 agent (Builder, Tester) is **not** a junior agent. It is an agent doing work that is well-specified enough that a fast model handles it efficiently. Throwing opus at "implement this function the architect already designed" wastes tokens for no gain. Throwing haiku at "design a multi-file refactor across the codebase" wastes everyone's time on a thinner reasoning surface than the task demands. Tier is the framework's way of matching cost and capability to the actual cognitive shape of the work.
+
+## Examples from the canonical roster
+
+- **Architect** (id: `architect`) — Tier 1 (opus). Designs systems. Most expensive thinking the team does.
+- **Security** (id: `security`) — Tier 1 (opus). Threat modelling and OWASP review. Mistakes are expensive; tier is conservative.
+- **Cid** (id: `cid`) — Tier 1 (opus). Captain. Pre-task brief, post-task debrief. Reasoning over the whole session.
+- **Reviewer** (id: `reviewer`) — Tier 2 (sonnet). Two-stage review. Needs depth but does not need to design from scratch.
+- **Documentor** (id: `documentor`) — Tier 2 (sonnet). Writes `.purpose` files and updates `portal.yaml`.
+- **Compliance** (id: `compliance`) — Tier 2 (sonnet). Symbol planner and coverage owner.
+- **Builder** (id: `builder`) — Tier 3 (haiku). Implementation. Fast loop, narrow scope.
+- **Tester** (id: `tester`) — Tier 3 (haiku). Test writing.
+
+You will see the full tier breakdown in **N-para-451-roster-reference** — every active agent, one row each, with its tier called out.
+
+## How to override
+
+Tier is a *default*, not a contract. You can override the model for any agent on a per-project basis in `.paradigm/config.yaml` under the `model-resolution` section:
+
+```yaml
+model-resolution:
+  builder: claude-opus-4         # override builder up to opus for a research project
+  documentor: claude-haiku-4     # override documentor down to haiku to save cost
+```
+
+Override sparingly. The defaults exist because they reflect a deliberate cost / capability trade-off across the team. If you find yourself overriding the same agent in every project, that is a signal worth bringing to the design — Loid (the intelligence officer) tracks override patterns precisely because they often surface a tier-default that should change.
+
+## What tier does **not** mean
+
+Tier does not say:
+
+- How much an agent is "trusted" — every agent's authority is governed by its profile and (at v6.1) its authority claims, not its tier.
+- How often an agent is invoked — Builder (Tier 3) runs more often than Architect (Tier 1) on most projects.
+- Which agents are "core" versus "specialty" — that is a separate axis (see the roster reference).
+
+Tier is exactly one thing: the default model the agent calls. Keep it that simple and the rest of the framework gets easier.
+
+> **Coming in v6.1:** Paradigm introduces a separate concept also named "tier" for **notebooks** — tier-1 (transferable across projects, owned by the agent) versus tier-2 (project-local, owned by the project). The two "tier" concepts are orthogonal: an agent's *model tier* (this entry) is about cost and capability; a *notebook tier* (v6.1) is about scope and ownership of learned patterns. The naming collision is unfortunate; we keep them strictly separate in PARA 451 and 551 to avoid conflation. See `agent-owned-enforcement-plan.md`.
+
+## Up next
+
+The next entry — **N-para-451-roster-reference** — is where everything you have learned so far comes together: the canonical roster, with each agent's id, nickname, archetype, *and* tier all in a single scannable table.

package/dist/university-content/notes/N-para-451-welcome.md

@@ -0,0 +1,55 @@
+---
+id: N-para-451-welcome
+title: Welcome to PARA 451 — Agents Foundations
+type: note
+author: paradigm
+created: '2026-04-26'
+updated: '2026-04-26'
+tags:
+  - course
+  - para-451
+  - agents
+  - welcome
+symbols: []
+difficulty: beginner
+estimatedMinutes: 4
+prerequisites:
+  - LP-para-101
+category: paradigm-core
+origin: authored
+source: agents-course-phase-a-design.md
+---
+
+## Why this course exists
+
+Paradigm's most differentiated feature is its **agent team**. Other AI tooling gives you one model and a chat box. Paradigm gives you a roster of named, persistent identities — each with its own role, its own notebook of learned patterns, and its own moment to step in. Architect designs. Builder implements. Reviewer reviews. Cid runs the briefing. Loid runs the learning loop. Scholar and Sheila pair on research. The team is the product.
+
+Until now, the only place to learn about agents in University was a handful of entries inside PARA 401: Orchestration — an advanced course beginners rarely reach. Worse, those entries pre-date the v6.0.3 partners primitive and the three-layer identity model, so they describe an older version of the team. PARA 451 is the canonical, beginner-accessible introduction; the older PARA 401 agent entries are flagged as v6.1 retirement candidates and will be retired once 451 is broadly adopted.
+
+## What you will learn
+
+By the end of this course you will be able to answer:
+
+- **What is an agent in Paradigm, and how is it different from "the model"?** An agent is a persistent identity with a profile, a notebook, and a role — not a single prompt or a single Claude call.
+- **What is an archetype, and how is it different from a nickname or an id?** The three-layer identity model (id / nickname / archetype) is what makes the same agent recognisable across every project, while still letting you call it whatever you want on yours.
+- **Who is on the team, and when do you call each one?** A single roster reference page covers all twenty-one currently-active agents — what each one is for, when it gets invoked, and which agents it pairs with.
+- **What does it mean for two agents to be "partners"?** The partners primitive (shipped at v6.0.3) is how the framework expresses that some agents work meaningfully better as a unit. Scholar + Sheila is the canonical example.
+- **How does orchestration actually run?** Faceted orchestration in Claude Code (true multi-agent, isolated Task contexts) versus sequential roleplay in Cursor and IDEs without Task tool support.
+
+## Prerequisite
+
+You should have completed **PARA 101: Foundations** — the five symbols, `.purpose` files, the basic shape of the `.paradigm/` directory. You do **not** need PARA 201, 301, or 401. The agent system is conceptually approachable, and learning the team early pays off in every project from then on.
+
+## Course shape
+
+PARA 451 is a single ordered learning path: notes interleaved with quizzes, ending in a mastery review. The full course is ~18 entries (about 35 minutes if you skim, 75-90 minutes if you take the quizzes seriously). This first batch of entries covers the foundation: identity, model tiers, and the roster. Subsequent batches add roster management, orchestration modes, the partners primitive deep-dive, and auto-rostering.
+
+## What this course does **not** cover
+
+Phase A — the entries in this course — is intentionally stable. We do not teach Rune's authority modes, the soft-block primitive, the notebook tier-1/tier-2 split, or the cross-project compounding runtime. Those topics are evolving as the v6.1 enforcement model lands, and they live in **PARA 551: Agents in Practice** (the follow-up course). The mastery review at the end of 451 will point you there when you are ready.
+
+> **Coming in v6.1:** PARA 551 launches alongside the v6.1 enforcement-model release. It treats PARA 451 as a hard prerequisite. See `agent-owned-enforcement-plan.md`.
+
+## Where to go from here
+
+Continue to **N-para-451-what-is-an-agent** to start with the conceptual foundation, then move on to **N-para-451-identity-layers**. If you only have ten minutes and you want the team-at-a-glance, jump to **N-para-451-roster-reference** — it is the most-referenced page in the course, and you will come back to it often.

package/dist/university-content/notes/N-para-451-what-is-an-agent.md

@@ -0,0 +1,73 @@
+---
+id: N-para-451-what-is-an-agent
+title: What Is an Agent in Paradigm?
+type: note
+author: paradigm
+created: '2026-04-26'
+updated: '2026-04-26'
+tags:
+  - course
+  - para-451
+  - agents
+  - identity
+  - profile
+symbols: []
+difficulty: beginner
+estimatedMinutes: 5
+prerequisites:
+  - N-para-451-welcome
+category: paradigm-core
+origin: authored
+source: agents-course-phase-a-design.md
+---
+
+## An agent is not a model invocation
+
+The single most common confusion newcomers bring to Paradigm is the assumption that "an agent" is just "a Claude API call with a system prompt". It is not. A model invocation is **transient** — it begins, returns a response, and forgets everything. An **agent** is **persistent**: it has a name, a profile on disk, a notebook of patterns it has learned, and a role it fills across every session and (often) across every project on your machine.
+
+Concretely, an agent in Paradigm is the union of four things:
+
+| Part | What it is | Where it lives |
+|------|------------|----------------|
+| **Profile** | The agent's identity, role, voice, expertise, and partner declarations. | `~/.paradigm/agents/<id>.agent` |
+| **Notebook** | What the agent has learned — patterns, gotchas, expertise entries promoted from journal observations. | `.paradigm/notebooks/<id>/` (project) or global notebook stores |
+| **Roster entry** | Whether this agent is active on a given project, and at what tier. | `.paradigm/roster.yaml` |
+| **Runtime invocation** | The Claude model call that happens when the agent is asked to do something — driven by the profile, fed the notebook, scoped by the roster. | At runtime, via `paradigm_orchestrate_inline` or the Claude Code Task tool |
+
+Strip any one of these away and you do not have an agent any more — you have something less. A profile with no notebook is a fresh hire. A notebook with no profile is orphaned data. A roster entry pointing at a missing profile is a dangling reference. The agent is the *whole* construct.
+
+## Why the framework has many of them
+
+Paradigm could have given you one big general-purpose Claude with a long system prompt and called it a day. It deliberately does not. Two reasons:
+
+1. **Specialised attention beats generalist attention.** When Architect is invoked, its profile narrows the model's attention to system design — multi-file planning, spec coherence, blast-radius reasoning. When Builder is invoked, its profile narrows attention to "follow the spec exactly, push back if unclear, ship the code". The same Claude model in both invocations produces measurably different output because the framing is different. A multi-agent team is a way of giving the model **multiple framings** in the same project, each at the right time.
+
+2. **Persistent expertise compounds per role.** Architect's notebook accrues *design* patterns. Reviewer's notebook accrues *review* heuristics. Loid's notebook accrues *learning-loop* observations. If everything were one agent, the patterns would muddle. Splitting roles means each agent's notebook stays sharp in its lane, and the cross-project learning that Paradigm bets on (Swift patterns compounding everywhere Swift is detected, for example) actually makes sense.
+
+The team metaphor is not decoration. It is the simplest accurate description of what is happening: a small group of specialised, persistent identities, each running on Claude, coordinating through the framework.
+
+## Two scopes: globally installed, project-rostered
+
+Every agent has two scopes you should keep straight from day one:
+
+- **Globally installed** — the profile sits at `~/.paradigm/agents/<id>.agent` and exists once on your machine. You can install agents from GitHub or (in future) the nevr.land registry; the profile travels with you.
+- **Project-rostered** — each project decides which agents from your global pool are active, via `.paradigm/roster.yaml`. Benching an agent on Project A leaves it untouched on Project B. The same global Architect can be active on six projects simultaneously and benched on a seventh.
+
+This split is intentional. You curate your team once, globally. You shape your team per project, locally. The roster-management entry later in the course (**N-para-451-roster-management**) walks through the CLI and the `/paradigm:agents` skill that drive both halves.
+
+## How agents are invoked at runtime
+
+When the framework needs an agent to do something, two paths are common:
+
+1. **Via the Task tool (Claude Code).** Each agent runs in an isolated Task subagent context, with the `paradigm:` prefix on its name (e.g. `paradigm:architect`, `paradigm:builder`). Each agent has its own conversation, its own memory, its own tool access — true multi-agent execution. This is **faceted orchestration**, the default in Claude Code.
+2. **Via sequential roleplay.** In Cursor and other IDEs without Task tool support, the framework runs each agent as an inline persona switch in the same context — you see the agent's voice and reasoning, but they share memory rather than each holding their own. This is **sequential mode**, covered in **N-para-451-orchestration-modes**.
+
+Either way, the agent's profile is loaded, its notebook is consulted, and its output is attributed back to its identity (so you can see in the orchestration log "Architect designed", "Builder implemented", "Reviewer flagged"). The mode shapes *how* the work runs; the identity is the same either way.
+
+## Try this
+
+Run `paradigm agent list`. The output is your project's roster — every agent currently active, with its id and nickname. Pick one (Architect is a good first target) and run `paradigm agent get architect`. You will see the profile fields: id, nickname, role, tier, partners, and a description of what the agent does. That on-disk record — not a conversation, not a single prompt — is the agent.
+
+## Up next
+
+Now that the agent concept is clear, **N-para-451-identity-layers** zooms into the three layers every agent has (id, nickname, archetype) and why each layer earns its keep. After that, **N-para-451-tiers** covers the orthogonal question of which Claude model an agent runs on by default.

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.

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.