@a-company/paradigm 5.28.0 → 5.31.0

package/dist/university-content/courses/para-201.json

@@ -232,82 +232,54 @@
     {
       "id": "aspect-graph",
       "title": "The Aspect Graph",
-      "content": "## v3.5 Aspect Definition Fields\n\nParadigm v3.5 extends the aspect definition with structured fields that transform aspects from simple tagged rules into first-class graph nodes. Every aspect can now carry a `value`, a `category`, a `severity`, typed `edges` to other symbols, and `lore` references linking the aspect to project history.\n\nHere is a complete v3.5 aspect definition:\n\n```yaml\naspects:\n  ~token-expiry-24h:\n    description: JWT access tokens expire after 24 hours\n    value: \"24h\"\n    category: configuration\n    severity: high\n    anchors:\n      - src/auth/jwt.ts:18-22\n    applies-to: [\"#auth-middleware\", \"#token-refresh-handler\"]\n    edges:\n      - symbol: \"^authenticated\"\n        relation: enforced-by\n      - symbol: \"~refresh-token-7d\"\n        relation: related-to\n      - symbol: \"~session-timeout-30m\"\n        relation: supersedes\n    lore:\n      - L-2026-01-15-002\n      - L-2026-02-10-001\n    tags: [security, auth, configuration]\n```\n\nThe **value** field captures the aspect's concrete value — a number, duration, threshold, or configuration string. This makes aspects searchable by their actual content, not just their description.\n\nThe **category** field classifies the aspect into one of five types:\n- `rule` — A behavioral rule that code must follow (e.g., \"all API responses must include a request ID\")\n- `decision` — An architectural decision captured as an aspect (e.g., \"use RS256 for JWT signing\")\n- `constraint` — A hard limitation that cannot be violated (e.g., \"maximum 100 items per page\")\n- `configuration` — A configurable value that may change across environments (e.g., \"JWT expiry is 24 hours\")\n- `invariant` — A condition that must always hold true (e.g., \"user balance is never negative\")\n\nThe **severity** field indicates the impact of violating or changing the aspect: `low`, `medium`, `high`, or `critical`. This drives prioritization in drift detection and heatmap analysis.\n\nThe **edges** array defines explicit relationships to other symbols. Each edge has a `symbol` (the target) and a `relation` (the relationship type). Five relation types are supported:\n- `enforced-by` — The aspect is enforced by the target (e.g., a gate, a middleware)\n- `depends-on` — The aspect depends on the target existing or functioning\n- `contradicts` — The aspect conflicts with the target (useful for flagging tensions)\n- `supersedes` — The aspect replaces or overrides the target\n- `related-to` — A general association without directional semantics\n\nThe **lore** array references lore entry IDs that provide historical context for the aspect — when it was introduced, why it was changed, what incidents led to its creation.\n\n## The SQLite Graph Engine\n\nAspect definitions live in YAML `.purpose` files — that is the source of truth. But querying a graph across dozens of YAML files is slow and awkward. Paradigm v3.5 introduces a SQLite graph database at `.paradigm/aspect-graph.db` that materializes the aspect graph for fast querying.\n\nThis database is a **derived build artifact**. It is rebuilt from scratch every time you run `paradigm_reindex`. You should never edit it directly — any changes would be overwritten on the next reindex. The YAML files remain the authoritative source; the SQLite database is a read-optimized cache.\n\nThe materialization pipeline runs in order: `openAspectGraph` creates or opens the database, `materializeAspects` writes all aspect and anchor data, `materializeLoreLinks` connects aspects to lore entries, `inferLoreEdges` creates implicit edges from shared lore references, and `closeAspectGraph` finalizes the database.\n\n## Edge Origins\n\nNot all edges are created equal. The graph tracks three edge origins:\n\n- **explicit** — Edges declared in the YAML `edges` field. These are intentional, human-authored relationships with full confidence.\n- **inferred** — Edges derived from `applies-to` references. When an aspect applies to a component, the system creates an inferred edge with weight 0.5 and relation `related-to`. These have lower confidence because they are computed, not declared.\n- **learned** — Edges discovered from lore overlap. When two aspects share lore references, the system infers a relationship. Learned edges have the lowest initial weight but can strengthen through confirmation.\n\nWhen querying the graph, you can filter by origin to see only the relationships you trust most, or include all origins for a complete picture.\n\n## Three-Tier Search\n\nThe aspect search system uses a three-tier strategy that improves over time:\n\n**Tier 1: Learned Mappings.** Before doing any text search, the system checks `search_weights` — a table of query-to-aspect mappings built from previous confirmed searches. If you searched for \"jwt expiry\" last week and confirmed `~token-expiry-24h` as the result, that mapping is stored. The next time anyone searches \"jwt expiry,\" the learned mapping returns the result instantly with high confidence.\n\n**Tier 2: FTS5 Full-Text Search.** If no learned mapping matches (or the confidence is below threshold), the system falls back to SQLite FTS5 full-text search across aspect descriptions, values, categories, and tags. FTS5 provides ranked results with relevance scoring.\n\n**Tier 3: Levenshtein Fuzzy Matching.** If FTS5 returns no results, the system tries fuzzy matching using Levenshtein distance. This catches typos and approximate queries — searching for \"tockn expry\" will still find `~token-expiry-24h` if the edit distance is small enough.\n\nThe tiers are tried in order. The first tier to return results wins. This means the system gets faster and more accurate over time as learned mappings accumulate.\n\n## The Learning Loop\n\nThe search learning loop works as follows:\n\n1. **Search** — You call `paradigm_aspect_search({ query: 'jwt expiry' })` and receive ranked results from whichever tier matched.\n2. **Select** — You pick the result you want and use it (e.g., `paradigm_aspect_get({ aspectId: 'token-expiry-24h' })`).\n3. **Confirm** — You call `paradigm_aspect_confirm({ query: 'jwt expiry', aspectId: 'token-expiry-24h' })` to tell the system your selection was correct.\n4. **Weights Updated** — The confirmed aspect gets +1.0 weight for that query. All other results that were returned for the same query get a decay multiplier of *0.95 applied to their weights. This self-correcting mechanism ensures that the best result rises to the top while alternatives gradually fade.\n5. **Future Searches Improve** — The next search for \"jwt expiry\" hits Tier 1 immediately, returning the learned mapping without needing FTS5 or fuzzy matching.\n\nOver time, the search system learns the vocabulary of your project — which terms map to which aspects — making discovery faster for every team member and agent.\n\n## The Seven MCP Tools\n\nParadigm v3.5 adds seven MCP tools for aspect graph interaction:\n\n**`paradigm_aspect_search`** — Search aspects using the three-tier system. Returns ranked results with scores and the tier that matched. Always call `paradigm_aspect_confirm` after selecting a result to feed the learning loop.\n\n**`paradigm_aspect_get`** — Get full details for an aspect: description, category, severity, value, anchor snippets (the actual code at anchor locations), graph edges, and linked lore entries. This is the deep-dive tool after search narrows the field.\n\n**`paradigm_aspect_graph`** — Get the subgraph neighborhood of a symbol. Pass a symbol and a hop count, and it returns all aspects and edges within that radius. Useful for understanding how aspects cluster around components.\n\n**`paradigm_aspect_heatmap`** — Get the most-accessed aspects ranked by usage frequency. The heatmap tracks four access types: `search` (found via search), `ripple` (encountered during ripple analysis), `navigate` (found via navigation), and `direct` (accessed by ID). This reveals which aspects are central to the project and which might be under-utilized.\n\n**`paradigm_aspect_suggest_scan`** — Scan a source file for undocumented aspects. The scanner detects magic numbers, hardcoded strings, rate limits, time values, environment variable checks, feature flags, and regex patterns. Each suggestion includes the line number, the detected value, and a proposed aspect definition. This is the discovery tool for finding rules that exist in code but are not yet documented.\n\n**`paradigm_aspect_drift`** — Check aspect anchors for content drift. The system computes SHA-256 hashes of the code at each anchor's line range and compares them against the hashes stored at the last scan. If the code has changed, the anchor is flagged as drifted. This catches silent changes to enforcement code that could invalidate an aspect's guarantees.\n\n**`paradigm_aspect_confirm`** — Confirm a search result to improve future search quality. This is the feedback mechanism for the learning loop — it updates `search_weights` with +1.0 for the selected result and applies *0.95 decay to alternatives.\n\n## Drift Detection\n\nDrift detection uses SHA-256 content hashing. When `paradigm_reindex` runs, it reads the code at each anchor's line range and stores a hash. When you later call `paradigm_aspect_drift`, it re-reads the current code and compares hashes. A mismatch means the code changed since the last index — the aspect may no longer be accurately anchored.\n\nDrift is not always a problem. If someone added a comment to the enforcement code, the hash changes but the aspect is still valid. But if someone refactored the rate limiter from 100 requests/minute to 500 requests/minute, the `~rate-limit-100` aspect is now stale. Drift detection catches both cases and lets you decide which need action.\n\n## Auto-Suggest Scanning\n\nThe `paradigm_aspect_suggest_scan` tool analyzes source files for patterns that should be documented as aspects but are not. It detects:\n\n- **Magic numbers** — Numeric literals that represent thresholds, limits, or configuration values\n- **Hardcoded strings** — String literals that represent URLs, paths, keys, or identifiers\n- **Rate limits** — Patterns like `rateLimit(100)` or `maxRequests: 50`\n- **Time values** — Durations like `24 * 60 * 60 * 1000` or `'30m'` or `setTimeout(fn, 5000)`\n- **Environment checks** — `process.env.NODE_ENV`, `std::env::var()`, or similar patterns\n- **Feature flags** — Patterns like `isEnabled('feature-name')` or `if (features.newCheckout)`\n- **Regex patterns** — Regular expressions that encode business rules or validation logic\n\nEach suggestion includes the file path, line number, detected value, a proposed aspect ID, and a draft category. You review the suggestions, accept the ones worth documenting, and discard the rest. This is how teams discover the implicit rules hiding in their codebase.",
+      "content": "## What Is the Aspect Graph?\n\nIn earlier lessons you learned that aspects (`~`) represent cross-cutting rules, constraints, and configuration values anchored to specific lines of code. The **aspect graph** connects those aspects to each other and to the rest of your symbol system — components, gates, flows, and signals — creating a queryable relationship map.\n\nThink of it this way: a single aspect like `~token-expiry-24h` is useful on its own. But when you can see that it is *enforced by* `^authenticated`, *related to* `~refresh-token-7d`, and linked to a lore entry explaining why the team chose 24 hours — that is the graph at work.\n\n## v3.5 Aspect Fields\n\nParadigm v3.5 extended aspects with structured fields that make them graph-ready:\n\n```yaml\naspects:\n  ~rate-limit-100:\n    description: API rate limited to 100 requests per minute\n    value: 100/min\n    category: constraint\n    severity: high\n    anchors:\n      - src/middleware/rate-limiter.ts:12-18\n    applies-to: [#api-gateway]\n    edges:\n      - symbol: ^authenticated\n        relation: enforced-by\n    tags: [security, performance]\n```\n\nKey fields:\n- **value** — The concrete value (a number, duration, threshold) making aspects searchable by content\n- **category** — One of five types: `rule` (behavioral), `decision` (architectural choice), `constraint` (hard limit), `configuration` (environment-specific), `invariant` (always-true condition)\n- **severity** — Impact of violation: `low`, `medium`, `high`, `critical`\n- **edges** — Explicit relationships to other symbols with typed relations: `enforced-by`, `depends-on`, `contradicts`, `supersedes`, `related-to`\n- **lore** — References to lore entries providing historical context\n\n## Working with the Graph\n\nSeven MCP tools let you interact with the aspect graph:\n\n| Tool | Purpose |\n|------|---------|\n| `paradigm_aspect_search` | Find aspects by keyword — uses a three-tier search (learned mappings, full-text, fuzzy) |\n| `paradigm_aspect_get` | Deep-dive: full definition, code snippets at anchors, edges, linked lore |\n| `paradigm_aspect_graph` | Explore the neighborhood around a symbol (N hops out) |\n| `paradigm_aspect_heatmap` | See which aspects are accessed most (search, ripple, navigate, direct) |\n| `paradigm_aspect_suggest_scan` | Scan a source file for undocumented aspects (magic numbers, hardcoded strings, rate limits, etc.) |\n| `paradigm_aspect_drift` | Check if code at anchored lines changed since last scan (SHA-256 hash comparison) |\n| `paradigm_aspect_confirm` | Confirm a search result to improve future search accuracy (learning loop) |\n\nThe graph is stored as a SQLite database at `.paradigm/aspect-graph.db` — a derived artifact rebuilt by `paradigm_reindex`. The YAML `.purpose` files remain the source of truth.\n\n## When to Use the Aspect Graph\n\n- **Before modifying enforcement code** — call `paradigm_aspect_drift` to check for stale anchors\n- **Exploring unfamiliar rules** — call `paradigm_aspect_search` then `paradigm_aspect_get` for full context\n- **Understanding impact** — call `paradigm_aspect_graph` to see what a change affects\n- **Finding undocumented rules** — call `paradigm_aspect_suggest_scan` on source files\n\n> **Deep dive:** PARA 501 covers the SQLite schema, three-tier search internals, the learning loop, edge origins (explicit vs inferred vs learned), and the materialization pipeline in detail.",
       "keyConcepts": [
-        "v3.5 adds value, category, severity, edges, and lore fields to aspect definitions",
+        "Aspect graph connects aspects to components, gates, flows, and signals",
         "Five aspect categories: rule, decision, constraint, configuration, invariant",
-        "SQLite graph at .paradigm/aspect-graph.db is a derived artifact rebuilt by paradigm_reindex",
-        "Three edge origins: explicit (YAML), inferred (applies-to), learned (lore overlap)",
-        "Three-tier search: learned mappings, FTS5 full-text, Levenshtein fuzzy",
-        "Learning loop: search, select, confirm, weights update, future searches improve",
-        "Seven new MCP tools for search, detail, graph, heatmap, suggest, drift, and confirm",
-        "Drift detection uses SHA-256 hashing of code at anchor line ranges"
+        "Five edge relations: enforced-by, depends-on, contradicts, supersedes, related-to",
+        "Seven MCP tools for search, detail, graph, heatmap, suggest, drift, and confirm",
+        "SQLite graph at .paradigm/aspect-graph.db is a derived artifact — YAML is source of truth",
+        "Deep internals covered in PARA 501"
       ],
       "quiz": [
         {
           "id": "q1",
-          "question": "What is the correct order of tiers in aspect search?",
+          "question": "Your team's rate limiter was recently changed from 100 req/min to 500 req/min, but no one updated the aspect definition. Which tool would catch this?",
           "choices": {
-            "A": "FTS5 full-text search, then learned mappings, then Levenshtein fuzzy",
-            "B": "Levenshtein fuzzy, then FTS5 full-text search, then learned mappings",
-            "C": "Learned mappings, then FTS5 full-text search, then Levenshtein fuzzy",
-            "D": "Learned mappings, then Levenshtein fuzzy, then FTS5 full-text search",
-            "E": "All three tiers run in parallel and the highest-scoring result wins"
-          },
-          "correct": "C",
-          "explanation": "The three-tier search system tries tiers in order: Tier 1 (learned mappings from confirmed searches), Tier 2 (FTS5 full-text search across descriptions, values, categories, and tags), and Tier 3 (Levenshtein fuzzy matching for typo tolerance). The first tier to return results wins, which means learned mappings provide the fastest path when available."
-        },
-        {
-          "id": "q2",
-          "question": "A developer confirms a search result via paradigm_aspect_confirm. What happens to the search weights?",
-          "choices": {
-            "A": "All results for the query are removed and only the confirmed one remains",
-            "B": "The confirmed aspect gets +1.0 weight and all other results for the same query decay by *0.95",
-            "C": "The confirmed aspect gets +0.5 weight and nothing happens to other results",
-            "D": "All results for the query get +1.0 weight to reinforce the entire result set",
-            "E": "The confirmed aspect is pinned permanently and can never be overridden"
+            "A": "paradigm_aspect_search — it would find the stale value in search results",
+            "B": "paradigm_aspect_drift — it compares code hashes at anchor line ranges and detects the change",
+            "C": "paradigm_aspect_heatmap — it shows the aspect is no longer being accessed",
+            "D": "paradigm_aspect_graph — it reveals the broken edge to the rate limiter component",
+            "E": "paradigm_reindex — it automatically updates the aspect value during reindexing"
           },
           "correct": "B",
-          "explanation": "When a search result is confirmed, the selected aspect receives +1.0 weight for that query, reinforcing the mapping. All other results that were returned for the same query receive a *0.95 decay multiplier, gradually reducing their weight. This self-correcting mechanism ensures the best result rises to the top over time while alternatives fade without being immediately removed."
+          "explanation": "paradigm_aspect_drift compares SHA-256 hashes of code at anchored line ranges against the hashes from the last scan. When the rate limiter code changed, the hash changed, flagging the anchor as drifted. The other tools don't detect code changes — reindex rebuilds the graph from YAML, which still has the old value."
         },
         {
-          "id": "q3",
-          "question": "Which aspect category is appropriate for 'JWT expiry is 24 hours'?",
+          "id": "q2",
+          "question": "Which aspect category best fits \"JWT access tokens expire after 24 hours\"?",
           "choices": {
-            "A": "rule — it defines a behavioral rule that code must follow",
-            "B": "decision — it captures an architectural decision",
-            "C": "constraint — it is a hard limitation that cannot be violated",
-            "D": "configuration — it is a configurable value that may change across environments",
+            "A": "rule — it defines a behavioral pattern that code must follow",
+            "B": "decision — it captures an architectural choice",
+            "C": "constraint — it is a hard limit that cannot be violated",
+            "D": "configuration — it is a value that may differ across environments",
             "E": "invariant — it is a condition that must always hold true"
           },
           "correct": "D",
-          "explanation": "A JWT expiry duration is a configuration value — it defines a specific setting (24 hours) that could reasonably differ between environments (development might use shorter expiry, production longer). Constraints are hard limitations that cannot be changed without breaking things. Rules are behavioral patterns. Decisions capture why something was chosen. Configuration captures what value was set."
+          "explanation": "A JWT expiry duration is a configuration value — it could reasonably differ between environments (shorter in dev, longer in production). A constraint is a hard limitation (like \"maximum 100 items per page\"). A rule is a behavioral pattern. Configuration captures what specific value was set and where."
         },
         {
-          "id": "q4",
-          "question": "What does paradigm_aspect_drift detect?",
-          "choices": {
-            "A": "When aspect definitions in YAML have syntax errors",
-            "B": "When aspects are referenced by symbols that no longer exist",
-            "C": "When the code at anchored line ranges has changed since the last scan, detected via SHA-256 hash comparison",
-            "D": "When aspects have been moved to a different .purpose file",
-            "E": "When aspect edges reference symbols that have been renamed"
-          },
-          "correct": "C",
-          "explanation": "Drift detection works by comparing SHA-256 hashes of the code at each anchor's line range. During paradigm_reindex, the system hashes the code at every anchor location. When paradigm_aspect_drift runs later, it re-reads the current code and compares hashes. A mismatch means the enforcement code changed — the aspect may need updating to reflect the current implementation."
-        },
-        {
-          "id": "q5",
-          "question": "An aspect has edges: [{symbol: '^authenticated', relation: 'enforced-by'}]. What does this mean?",
+          "id": "q3",
+          "question": "An aspect has edges: [{symbol: \"^authenticated\", relation: \"enforced-by\"}]. What does this tell you?",
           "choices": {
             "A": "The aspect enforces the ^authenticated gate",
-            "B": "The ^authenticated gate depends on the aspect",
-            "C": "The aspect is enforced by the ^authenticated gate — the gate is the mechanism that ensures the aspect holds",
-            "D": "The aspect contradicts the ^authenticated gate",
-            "E": "The aspect and ^authenticated gate are the same thing expressed differently"
+            "B": "The ^authenticated gate depends on the aspect existing",
+            "C": "The ^authenticated gate is the mechanism that ensures the aspect holds true",
+            "D": "The aspect and the gate are in conflict",
+            "E": "The aspect will be removed if the gate is deleted"
           },
           "correct": "C",
-          "explanation": "The 'enforced-by' relation means the target symbol is the mechanism that enforces the aspect. In this case, the ^authenticated gate is what ensures the aspect's rule holds true. This is a common pattern — aspects define what must be true, and gates define the checkpoints that enforce those truths. The edge makes this relationship explicit and queryable in the graph."
+          "explanation": "The enforced-by relation means the target symbol is what ensures the aspect's rule holds. Here, the ^authenticated gate is the checkpoint that enforces whatever the aspect defines. Aspects declare what must be true; gates enforce those truths. The edge makes this relationship explicit and queryable."
         }
       ]
     },

package/dist/university-content/courses/para-301.json

@@ -30,16 +30,16 @@
         },
         {
           "id": "q2",
-          "question": "What are the three types of changes you can record in the history system?",
+          "question": "In one session you fixed a race condition in #checkout-flow, updated the $payment-flow to add retry logic, and added a new #refund-handler component. How would you record these three changes in the history system?",
           "choices": {
-            "A": "create, update, delete",
-            "B": "implement, refactor, rollback",
-            "C": "feature, fix, refactor",
-            "D": "add, modify, remove",
-            "E": "build, test, deploy"
+            "A": "One history_record call with all three changes combined",
+            "B": "Three separate history_record calls — a \"fix\" for the race condition, a \"change\" for the flow update, and an \"add\" for the new component",
+            "C": "Only record the new component — fixes and changes are tracked by git",
+            "D": "Use paradigm_lore_record instead — history is deprecated",
+            "E": "Record only the fix — it is the most important change"
           },
           "correct": "B",
-          "explanation": "The three change types are implement (new work), refactor (structural changes), and rollback (reverting a change). The options feature, fix, and refactor are intent values, not types."
+          "explanation": "The history system supports three change types: \"add\" (new symbols), \"change\" (modifications), and \"fix\" (bug fixes). Each change should be recorded separately so that future history queries can filter by type. Using the right type matters — when someone asks \"what broke recently?\" they want fixes, not additions."
         },
         {
           "id": "q3",
@@ -333,6 +333,112 @@
         }
       ]
     },
+    {
+      "id": "enforcement-levels",
+      "title": "Enforcement Levels",
+      "content": "## The Three Enforcement Levels\n\nParadigm enforcement is configurable. Not every project needs the same rigor — a weekend prototype has different needs than a healthcare platform. Enforcement levels control which compliance checks **block** (stop you), **warn** (notify but continue), or are **off** (silent).\n\n### Minimal — For Learning and Prototyping\n\nMinimal enforcement is the default for new projects created by `paradigm shift`. Only two checks are active, both as warnings:\n\n- `purpose-coverage` — warns if source directories lack `.purpose` files\n- `habits-blocking` — warns if defined habits are being violated\n\nEverything else is off. This means hooks never block you, so you can learn Paradigm without friction. You can always run checks manually with `paradigm doctor`.\n\n### Balanced — For Active Development\n\nWhen your team is comfortable with Paradigm, upgrade to balanced. This is where most teams operate:\n\n- **Blocks on:** `purpose-coverage` (must have purpose files), `habits-blocking` (must follow habits)\n- **Warns on:** `purpose-exists`, `portal-gates`, `aspect-anchors`, `purpose-freshness`, `lore-required`, `purpose-required-patterns`, `drift-detection`, `portal-compliance`, `orchestration-required`\n- **Off:** `aspect-advisory`, `graduation-tracking`\n\nBalanced catches problems early without being oppressive. The stop hook blocks on missing purpose files but lets you work freely otherwise.\n\n### Strict — For Regulated Domains\n\nHealthcare, finance, legal — domains where compliance is not optional. Strict blocks on nearly everything:\n\n- **Blocks on:** `purpose-coverage`, `purpose-exists`, `portal-gates`, `aspect-anchors`, `lore-required`, `habits-blocking`, `purpose-required-patterns`, `drift-detection`, `portal-compliance`, `orchestration-required`\n- **Warns on:** `purpose-freshness`, `aspect-advisory`, `graduation-tracking`\n\nWith strict enforcement, you cannot commit without purpose files, portal gates, lore records, and passing drift checks. This ensures every change is documented and traceable.\n\n## Configuration\n\nSet the level in `.paradigm/config.yaml`:\n\n```yaml\nenforcement:\n  level: balanced   # minimal | balanced | strict\n```\n\nOverride individual checks when a preset does not quite fit:\n\n```yaml\nenforcement:\n  level: balanced\n  checks:\n    orchestration-required: block   # Upgrade from warn to block\n    lore-required: off              # Downgrade — we don't need lore yet\n```\n\nPer-check overrides take precedence over the preset. This lets you start with a base level and tune specific checks to match your team's workflow.\n\n## The 13 Checks\n\n| Check | What It Validates |\n|-------|------------------|\n| `purpose-coverage` | Source directories have .purpose files |\n| `purpose-exists` | Referenced purpose files actually exist on disk |\n| `portal-gates` | Routes in portal.yaml have required gates defined |\n| `aspect-anchors` | Aspect anchors point to valid code locations |\n| `purpose-freshness` | Purpose files are not stale (content matches code) |\n| `aspect-advisory` | Components have at least one aspect (1:1 ratio) |\n| `lore-required` | Sessions modifying 3+ files record lore |\n| `habits-blocking` | Defined habits are being followed |\n| `purpose-required-patterns` | Required patterns (flows, gates) are present |\n| `drift-detection` | Aspect anchor code has not drifted |\n| `portal-compliance` | Portal.yaml matches actual route definitions |\n| `graduation-tracking` | Habits are graduating through automation tiers |\n| `orchestration-required` | Complex tasks use multi-agent orchestration |\n\n## Progression Strategy\n\nMost teams follow this path:\n\n1. **Start minimal** — learn Paradigm, build habits, no blocking\n2. **Move to balanced** after 1-2 weeks — catch issues early, still flexible\n3. **Upgrade to strict** for production-critical or regulated codebases\n\nYou can change levels at any time. The switch is immediate — no migration needed.",
+      "keyConcepts": [
+        "Three enforcement levels: minimal (learn), balanced (work), strict (regulated)",
+        "Minimal is the default for new projects — hooks warn but never block",
+        "13 checks control purpose, portal, aspect, lore, habits, drift, and orchestration compliance",
+        "Per-check overrides let you tune individual checks beyond the preset",
+        "Progression: minimal → balanced → strict as team comfort grows"
+      ],
+      "quiz": [
+        {
+          "id": "q1",
+          "question": "Your team is building a healthcare claims processing system that requires audit trails. A new developer joins and asks which enforcement level to use. What do you recommend?",
+          "choices": {
+            "A": "Minimal — let the new developer learn without friction first",
+            "B": "Balanced — it catches most issues without being too strict",
+            "C": "Strict — healthcare is a regulated domain where every change must be documented and traceable",
+            "D": "Minimal with lore-required overridden to block — just the audit trail matters",
+            "E": "No enforcement — the team should self-police"
+          },
+          "correct": "C",
+          "explanation": "Healthcare is a regulated domain where compliance is not optional. Strict enforcement ensures every change has purpose files, portal gates, lore records, and passing drift checks — exactly the traceability an audit requires. The new developer should work within these constraints from day one rather than building habits that strict mode would later break."
+        },
+        {
+          "id": "q2",
+          "question": "Your project uses balanced enforcement but your team never records lore entries, causing constant warnings. What is the best fix?",
+          "choices": {
+            "A": "Switch to minimal enforcement to silence all warnings",
+            "B": "Override lore-required to off in config.yaml — your team does not need lore yet",
+            "C": "Override lore-required to block — force the team to comply",
+            "D": "Delete the enforcement section from config.yaml entirely",
+            "E": "Ignore the warnings — they are just advisory"
+          },
+          "correct": "B",
+          "explanation": "Per-check overrides exist for exactly this situation. If your team is not ready for lore tracking, override lore-required to off rather than downgrading the entire enforcement level. This keeps all other balanced checks active while silencing the one that does not match your current workflow. You can re-enable it later when the team is ready."
+        },
+        {
+          "id": "q3",
+          "question": "A stop hook blocks your commit with \"missing .purpose file for src/payments/\". You are on balanced enforcement. What happened?",
+          "choices": {
+            "A": "purpose-exists check failed — the .purpose file has a syntax error",
+            "B": "purpose-coverage check blocked — you modified files in src/payments/ but that directory has no .purpose file",
+            "C": "portal-gates check failed — src/payments/ has unprotected routes",
+            "D": "purpose-freshness check failed — the .purpose file exists but is stale",
+            "E": "aspect-anchors check failed — aspects in src/payments/ have broken anchors"
+          },
+          "correct": "B",
+          "explanation": "On balanced enforcement, purpose-coverage is the only check set to block (besides habits-blocking). The error message says \"missing .purpose file\" which means the directory lacks one entirely — that is purpose-coverage, not purpose-exists (which checks that referenced files exist) or purpose-freshness (which checks staleness). Fix: create a .purpose file in src/payments/ describing its components."
+        }
+      ]
+    },
+    {
+      "id": "paradigm-shift",
+      "title": "The paradigm shift Command",
+      "content": "## One Command, Full Setup\n\n`paradigm shift` is the universal onboarding command. It transforms any project directory into a Paradigm-aware workspace in a single run. Whether you are starting a new project or adopting Paradigm in an existing codebase, this is where you begin.\n\n```bash\nparadigm shift\n```\n\n## What It Does (6 Steps)\n\nThe command runs six steps in sequence:\n\n### Step 1: Initialize\nCreates the `.paradigm/` directory with `config.yaml`, `tags.yaml`, and starter files. If the directory already exists, it updates configuration without overwriting your customizations.\n\n### Step 2: Auto-Migrate\nDetects if your project uses an older Paradigm version and applies breaking-change migrations automatically. This keeps projects up to date without manual migration effort.\n\n### Step 3: Scan & Index\nDiscovers all symbols in your codebase by reading `.purpose` files and `portal.yaml`. Builds the navigator index for fast symbol lookup. Skip this step with `--quick` for faster initialization.\n\n### Step 4: Sync IDEs\nGenerates instruction files for your AI tools:\n- `CLAUDE.md` — Claude Code instructions\n- `AGENTS.md` — Universal agent instructions\n- `.cursor/rules/` — Cursor IDE rules\n\nThese files are regenerated from your Paradigm configuration every time you run shift or sync.\n\n### Step 5: Install Hooks\nSets up Git hooks (pre-commit, post-commit) and Claude Code/Cursor hooks for automated enforcement. The hooks run compliance checks based on your enforcement level.\n\n### Step 6: Roster & Model Tiers\nSuggests an agent roster based on your detected project type (web, backend, mobile, etc.) and configures model tiers (tier-1/tier-2/tier-3) based on your environment.\n\n## Key Flags\n\n| Flag | Effect |\n|------|--------|\n| `--quick` | Skip symbol scanning (fast init) |\n| `--verify` | Run `paradigm doctor` health checks at the end |\n| `--workspace <name>` | Create or join a multi-project workspace |\n| `--force` | Reinitialize (overwrite existing config) |\n\n## When to Re-Run\n\nRun `paradigm shift` again when:\n- You upgrade Paradigm to a new version (auto-migrates)\n- You want to refresh IDE instruction files after config changes\n- You add the project to a workspace\n- After major restructuring that changes project type\n\nThe command is idempotent — running it multiple times is safe. It updates what changed and leaves the rest alone.\n\n## What Comes Out\n\nAfter `paradigm shift`, your project has:\n\n```\n.paradigm/\n  config.yaml       # Project configuration\n  tags.yaml         # Tag taxonomy\n  roster.yaml       # Agent team roster\n  agents.yaml       # Agent tier assignments\nCLAUDE.md            # Claude Code instructions\nAGENTS.md            # Universal agent instructions\n.purpose             # Root purpose file (if new project)\nportal.yaml          # Auth topology (if gates detected)\n```\n\nPlus Git hooks and IDE-specific instruction files, all derived from your Paradigm configuration.",
+      "keyConcepts": [
+        "paradigm shift is the universal onboarding command — one command, full setup",
+        "Six steps: init, migrate, scan, sync IDEs, install hooks, roster + model tiers",
+        "Non-interactive by default — auto-detects discipline, stack, and model tiers",
+        "Idempotent — safe to re-run after upgrades or config changes",
+        "--quick skips scanning, --verify adds health checks, --workspace enables multi-project"
+      ],
+      "quiz": [
+        {
+          "id": "q1",
+          "question": "You just cloned a teammate's Paradigm project and want to start working. The project already has .paradigm/ and .purpose files. What command should you run?",
+          "choices": {
+            "A": "paradigm init — to create a fresh .paradigm/ directory",
+            "B": "paradigm shift — it detects the existing setup, migrates if needed, and installs hooks for your environment",
+            "C": "paradigm scan — to rebuild the symbol index",
+            "D": "paradigm sync — to generate your IDE files",
+            "E": "No command needed — the project is already set up"
+          },
+          "correct": "B",
+          "explanation": "paradigm shift is the right choice even for existing projects. It detects that .paradigm/ exists, auto-migrates if the project uses an older version, installs Git and IDE hooks for YOUR environment, generates YOUR IDE instruction files, and suggests an agent roster. Just scan or sync alone would miss hooks and migration."
+        },
+        {
+          "id": "q2",
+          "question": "Your CI pipeline needs to initialize Paradigm quickly without scanning thousands of files. Which flag do you use?",
+          "choices": {
+            "A": "paradigm shift --force — it runs faster by overwriting existing config",
+            "B": "paradigm shift --quick — it skips symbol scanning for faster initialization",
+            "C": "paradigm shift --verify — it verifies instead of scanning",
+            "D": "paradigm init --minimal — it only creates the config file",
+            "E": "paradigm shift --no-hooks — it skips the slowest step"
+          },
+          "correct": "B",
+          "explanation": "The --quick flag skips Step 3 (scan & index), which is the most time-consuming step because it reads every .purpose file in the codebase. In CI, you typically just need config, hooks, and IDE files — the full index can be built separately if needed."
+        },
+        {
+          "id": "q3",
+          "question": "After upgrading Paradigm from v4.x to v5.x, your project's .purpose files use the old @feature syntax instead of #component. What should you do?",
+          "choices": {
+            "A": "Manually find-and-replace all @feature with #component across the codebase",
+            "B": "Run paradigm shift — Step 2 (auto-migrate) detects the version gap and applies breaking-change migrations",
+            "C": "Delete .paradigm/ and start over with paradigm init",
+            "D": "Run paradigm doctor to identify the issues, then fix them one by one",
+            "E": "Ignore it — old syntax still works in v5.x"
+          },
+          "correct": "B",
+          "explanation": "paradigm shift's Step 2 (auto-migrate) exists for exactly this scenario. It detects that your project uses older conventions and applies the necessary migrations automatically. Manual find-and-replace risks missing files or misformatting YAML. Deleting .paradigm/ loses custom configuration. The old syntax does NOT work in v5.x — the symbol system changed."
+        }
+      ]
+    },
     {
       "id": "navigation-system",
       "title": "Codebase Navigation",
@@ -721,4 +827,4 @@
       ]
     }
   ]
-}
+}

package/dist/university-content/courses/para-401.json

@@ -179,92 +179,67 @@
     {
       "id": "agent-roles",
       "title": "Agent Roles & Facets",
-      "content": "## Agent Roles & Facets\n\nEach agent role in Paradigm is not just a label -- it is a fully configured **facet** with its own model assignment, context scope, token budget, and communication protocol. These configurations live in `.paradigm/agents.yaml` and determine exactly how each agent behaves during orchestration.\n\n### Facet Configuration\n\nA facet defines four dimensions of an agent:\n\n**`defaultModel`** -- Which AI model to use. This matches task complexity to capability:\n- `opus` for architect and security (complex reasoning, design decisions, threat analysis)\n- `sonnet` for reviewer (balanced depth and speed for code critique)\n- `haiku` for builder and tester (fast, cost-effective for implementation and test writing)\n\n**`context.include / context.exclude`** -- Which files the agent should see. An architect might include `.purpose` files, `portal.yaml`, and architecture docs but exclude test files. A tester includes test directories and the implementation files but excludes deployment configs. This scoping keeps each agent focused and reduces token waste.\n\n```yaml\n# Example from agents.yaml\narchitect:\n  defaultModel: opus\n  context:\n    include:\n      - \"**/.purpose\"\n      - \"portal.yaml\"\n      - \".paradigm/specs/**\"\n    exclude:\n      - \"**/*.test.*\"\n      - \"node_modules/**\"\n  limits:\n    maxTokens: 30000\n  protocol:\n    relay: structured\n```\n\n**`limits.maxTokens`** -- The maximum token budget for a single agent invocation. Architects typically get higher budgets (30,000+) because design work requires more exploration. Builders and testers get tighter budgets because their work is more focused and mechanical.\n\n**`protocol.relay`** -- How the agent reports results back. Options include `structured` (returns a formatted JSON report), `markdown` (returns a narrative document), or `handoff` (writes to a handoff file for the next agent). The relay protocol is how agents communicate in a pipeline.\n\n### The Orchestrator's Role\n\nThe orchestrator is not an agent itself -- it is the coordinator that:\n1. **Decomposes** the task into stages based on trigger patterns\n2. **Assigns** each stage to the appropriate agent facet\n3. **Manages handoffs** between stages, passing context from one agent to the next\n4. **Identifies parallelism** -- stages that are independent can run simultaneously\n5. **Aggregates results** from all agents into a final output\n\nThe decomposition logic uses trigger patterns: tasks mentioning \"auth\" or \"security\" trigger the security agent. Tasks mentioning \"test\" or \"coverage\" trigger the tester. Tasks involving 3+ files or multiple symbols trigger the architect for upfront design. These patterns are configurable in the orchestration rules.\n\n### Handoff Context\n\nWhen agents run in sequence, each agent receives the output of the previous one via `handoffContext`. For example, the architect produces a design document, which is passed to the security agent for review, whose approved design is then passed to the builder for implementation. The `paradigm_agent_prompt` tool accepts `previousAgent` and `handoffContext` parameters to facilitate this chain.\n\n```\nparadigm_agent_prompt({\n  agent: \"builder\",\n  task: \"Implement the auth middleware as designed\",\n  previousAgent: \"architect\",\n  handoffContext: \"Design: JWT middleware at src/middleware/auth.ts, gates: ^authenticated, ^admin-only...\"\n})\n```\n\nThis chain of specialized agents, each scoped to its role with appropriate context and budget, produces higher quality output than a single generalist agent trying to do everything.\n\n### Reviewer Protocol\n\nThe reviewer agent follows a strict **two-stage review protocol**:\n\n**Stage 1 (Spec Compliance)** checks that the implementation matches Paradigm metadata: `.purpose` definitions are registered, `^gates` from `portal.yaml` are implemented, `$flow` steps execute in order, `!signals` are emitted, and `~aspects` are enforced. If Stage 1 fails, the reviewer **stops immediately** and hands back to the builder. There is no point reviewing code quality of spec-noncompliant code.\n\n**Stage 2 (Code Quality)** only runs if Stage 1 passes. It covers security (OWASP), conventions, test coverage, performance, and error handling.\n\nEvery review must produce a **minimum of 3 categorized findings**: `blocking` (must fix), `improvement` (should fix), or `note` (informational). Only blocking findings prevent approval. This ensures thorough examination -- a review with 3 notes and 0 blocking findings is still approved, but a rubber-stamp \"looks good\" with zero findings is never acceptable.",
+      "content": "## The Agent Roster: 8 Core, 54+ Total\n\nParadigm ships with over 54 agent definitions. You do not use all of them — `paradigm shift` auto-selects a project roster based on your detected project type. But understanding the hierarchy helps you work with the orchestrator effectively.\n\n### Three-Tier Hierarchy\n\n**Core agents (8)** are available in every project. These are the backbone of orchestration:\n\n| Nickname | Role | Model Tier | Purpose |\n|----------|------|-----------|---------|\n| — | **Architect** | Tier-1 (opus) | System design, multi-file planning |\n| — | **Builder** | Tier-3 (haiku) | Implementation, code generation |\n| — | **Reviewer** | Tier-2 (sonnet) | Two-stage code review (spec → quality) |\n| Sage | **Advocate** | Tier-2 (sonnet) | User perspective, UX implications |\n| Jinx | **Advocate** | Tier-2 (sonnet) | Stress-tests assumptions, finds edge cases |\n| Sentinel | **Security** | Tier-1 (opus) | Threat analysis, auth review, OWASP |\n| Doc | **Documentor** | Tier-2 (sonnet) | .purpose files, portal.yaml — Paradigm metadata only |\n| Rune | **Compliance** | Tier-2 (sonnet) | Symbol planning, 1:1 aspect enforcement |\n| Vigil | **Tester** | Tier-3 (haiku) | Test writing, coverage, edge cases |\n\n**Specialized agents (~20)** cover domains like mobile, database, DevOps, accessibility, and performance. They are rostered when your project type matches their expertise.\n\n**Ecosystem agents (~26+)** are language/platform-specific — Swift, TypeScript, Rust, Python ML, iOS, Android, etc. They accumulate per-ecosystem knowledge through notebooks that transfer across projects.\n\n> **Deep dive:** PARA 701 covers the full roster, agent profiles, notebooks, per-project customization, and the learning feedback loop.\n\n### Rune: The Compliance Specialist\n\nRune is the 8th core agent, added specifically to prevent a common failure mode: building features without proper symbol coverage.\n\n**Before implementation**, Rune creates a **Symbol Plan**:\n- Enumerates all `#components`, `$flows`, `!signals`, `~aspects` the task needs\n- Creates symbol stubs via MCP tools (`paradigm_purpose_add_component`, etc.)\n- Enforces a **1:1 component-to-aspect ratio** — every component must have at least one aspect\n\n**After implementation**, Rune produces a **Compliance Report**:\n- Validates that planned symbols were actually created\n- Checks that aspect anchors point to valid code\n- Verifies flows exist for logic spanning 3+ components\n- Reports findings as blocking (must fix) or passing\n\nRune never modifies source code — only Paradigm metadata files (.purpose, portal.yaml). Think of Rune as the \"symbol bookkeeper\" who ensures the spec matches the code.\n\n### Facet Configuration\n\nEach agent role is a **facet** with four dimensions defined in `.paradigm/agents.yaml`:\n\n- **`defaultModel`** — Which AI model to use (opus for complex reasoning, sonnet for balanced, haiku for fast execution)\n- **`context.include / context.exclude`** — Which files the agent sees (scoped to reduce token waste)\n- **`limits.maxTokens`** — Budget per invocation (architects get more, builders get less)\n- **`protocol.relay`** — How results are reported: `structured` (JSON), `markdown` (narrative), or `handoff` (file for next agent)\n\n```yaml\n# Example from agents.yaml\narchitect:\n  defaultModel: opus\n  context:\n    include: [\"**/.purpose\", \"portal.yaml\", \".paradigm/specs/**\"]\n    exclude: [\"**/*.test.*\", \"node_modules/**\"]\n  limits:\n    maxTokens: 30000\n  protocol:\n    relay: structured\n```\n\n### Handoff Context\n\nAgents run in sequence, each receiving the previous agent's output via `handoffContext`:\n\n```\nRune (symbol plan) → Architect (design) → Security (review) → Builder (implement) → Reviewer (check) → Rune (compliance report) → Doc (.purpose files)\n```\n\nThe `paradigm_agent_prompt` tool accepts `previousAgent` and `handoffContext` parameters to thread this chain.\n\n### Reviewer Protocol\n\nThe reviewer follows a strict **two-stage protocol**:\n\n**Stage 1 (Spec Compliance)** — checks .purpose registrations, portal.yaml gates, flow steps, signal emissions, aspect enforcement. If Stage 1 fails, the reviewer **stops immediately** and hands back to the builder.\n\n**Stage 2 (Code Quality)** — only runs if Stage 1 passes. Covers OWASP security, conventions, test coverage, performance, error handling.\n\nEvery review must produce a **minimum of 3 categorized findings**: blocking (must fix), improvement (should fix), or note (informational). A rubber-stamp \"looks good\" with zero findings is never acceptable.",
       "keyConcepts": [
-        "Four facet dimensions: model, context scope, token limits, relay protocol",
-        "agents.yaml configuration file",
-        "Orchestrator decomposition and stage assignment",
-        "Handoff context between sequential agents",
-        "Trigger patterns for agent selection"
+        "Three-tier hierarchy: 8 core agents, ~20 specialized, ~26+ ecosystem",
+        "Rune (compliance) handles pre-build symbol planning and post-build compliance reports",
+        "1:1 component-to-aspect ratio is enforced by Rune — every component needs at least one aspect",
+        "Facets define model, context scope, token budget, and relay protocol per agent",
+        "Reviewer uses two-stage protocol: spec compliance first, code quality only if spec passes",
+        "paradigm shift auto-selects a roster based on project type"
       ],
       "quiz": [
         {
           "id": "q1",
-          "question": "Why does the reviewer agent use the sonnet model instead of opus or haiku?",
+          "question": "You are about to add a payment refund feature that touches 5 files including auth middleware. The orchestrator composes a team. Which agents would you expect to see, and why?",
           "choices": {
-            "A": "Sonnet is the cheapest model",
-            "B": "Sonnet provides a balance of analytical depth and speed, suited for code critique",
-            "C": "Sonnet is the only model that can read code",
-            "D": "The reviewer does not need any AI model",
-            "E": "It is a random assignment with no rationale"
+            "A": "Only builder — it is an implementation task",
+            "B": "Architect (5 files = multi-file design), Sentinel (auth middleware = security), builder (implementation), Vigil (testing), Rune (symbol planning)",
+            "C": "Only architect and builder — the others are optional",
+            "D": "All 54+ agents are always activated for every task",
+            "E": "Only Sentinel — payment features are a security concern"
           },
           "correct": "B",
-          "explanation": "Code review requires analytical depth (catching subtle issues) but not the deep reasoning needed for architectural design. Sonnet balances depth and speed, making it ideal for critique. Opus would be more expensive than necessary; haiku might miss subtle issues."
+          "explanation": "The orchestrator uses trigger patterns: 5 files triggers the architect for upfront design, auth middleware triggers Sentinel for security review, implementation triggers builder, the complexity triggers Vigil for testing, and Rune always runs for symbol planning on orchestrated tasks. This is how the \"right team for the task\" is composed automatically."
         },
         {
           "id": "q2",
-          "question": "An architect agent's context.exclude contains '**/*.test.*'. Why?",
+          "question": "After building a new feature, Rune's compliance report shows: \"3 components created, 1 aspect defined. Blocking: 2 components missing aspects (1:1 ratio violated).\" What do you do?",
           "choices": {
-            "A": "Test files contain sensitive data",
-            "B": "To reduce token consumption by excluding files irrelevant to architectural design",
-            "C": "The architect is not allowed to see tests for compliance reasons",
-            "D": "Test files are always broken and would confuse the agent",
-            "E": "It is a default that cannot be changed"
+            "A": "Ignore the report — aspects are optional metadata",
+            "B": "Delete the 2 components to make the ratio work",
+            "C": "Add aspects to the 2 uncovered components — define what rules, constraints, or configuration each component enforces",
+            "D": "Reduce the aspect count to 0 so the ratio is consistently zero",
+            "E": "Ask the architect to redesign the feature with fewer components"
           },
-          "correct": "B",
-          "explanation": "Context scoping keeps agents focused and reduces token waste. An architect designing system structure does not need to read test files -- including them would consume tokens without adding value. Each role's context is scoped to the files relevant to its task."
+          "correct": "C",
+          "explanation": "Rune enforces a 1:1 component-to-aspect ratio because every component should have at least one documented rule, constraint, or configuration. Adding aspects is the correct fix — it forces you to think about what rules govern each component. If a component truly has no rules, it may be too small to be its own component."
         },
         {
           "id": "q3",
-          "question": "The orchestrator assigns a task to architect -> security -> builder -> tester. What mechanism passes context from the architect to the security agent?",
+          "question": "The reviewer runs Stage 1 (Spec Compliance) and finds that #checkout-form is not registered in any .purpose file. What happens?",
           "choices": {
-            "A": "They share the same conversation thread",
-            "B": "The handoffContext parameter in paradigm_agent_prompt, carrying the architect's output",
-            "C": "They both read the same files",
-            "D": "The orchestrator emails the context",
-            "E": "Context is not shared between agents"
+            "A": "The reviewer proceeds to Stage 2 and includes the missing registration as a note",
+            "B": "The reviewer stops immediately, reports a blocking finding, and hands back to the builder without Stage 2",
+            "C": "The reviewer auto-creates the .purpose entry and continues",
+            "D": "The reviewer skips both stages and approves with a warning",
+            "E": "The reviewer asks Rune to fix it"
           },
           "correct": "B",
-          "explanation": "When agents run in sequence, each receives the previous agent's output via the handoffContext parameter. paradigm_agent_prompt accepts previousAgent and handoffContext to include this chain context in the generated prompt."
+          "explanation": "The two-stage protocol is a hard gate: Stage 1 failure means immediate stop. There is no point reviewing code quality of spec-noncompliant code. The builder must fix the spec issue first, then resubmit. This ensures Paradigm metadata is always in sync with code before quality review begins."
         },
         {
           "id": "q4",
-          "question": "Which file contains the facet configuration for all agent roles?",
+          "question": "Your project is a React web app. After running paradigm shift, the roster includes architect, builder, reviewer, Sage, Jinx, Sentinel, Doc, Rune, Vigil, plus accessibility and performance specialists. A teammate's Python ML project has a different roster. Why?",
           "choices": {
-            "A": ".paradigm/config.yaml",
-            "B": ".paradigm/agents.yaml",
-            "C": "portal.yaml",
-            "D": ".purpose files in each directory",
-            "E": "navigator.yaml"
+            "A": "paradigm shift uses random selection",
+            "B": "Each project type gets a tailored roster — web apps get accessibility/performance specialists, ML projects get data pipeline/model evaluation specialists",
+            "C": "The Python project is missing agents and needs manual configuration",
+            "D": "All projects get the same roster but with different model assignments",
+            "E": "The difference is because of different Paradigm versions"
           },
           "correct": "B",
-          "explanation": "Agent facet configurations -- including model assignments, context scopes, token limits, and relay protocols -- are defined in .paradigm/agents.yaml. This is separate from config.yaml (project configuration) and portal.yaml (gate definitions)."
-        },
-        {
-          "id": "q5",
-          "question": "A task description mentions 'add rate limiting to the API with security audit'. Which trigger patterns activate?",
-          "choices": {
-            "A": "Only builder -- it is an implementation task",
-            "B": "Only security -- it mentions 'security audit'",
-            "C": "Security (triggered by 'security') and builder (triggered by implementation need), plus architect if 3+ files are affected",
-            "D": "All five agents are always triggered regardless of the task",
-            "E": "Only tester -- rate limiting needs testing"
-          },
-          "correct": "C",
-          "explanation": "Trigger patterns analyze the task description: 'security audit' triggers the security agent, the implementation need triggers the builder, and if the task affects 3+ files, the architect is triggered for upfront design. The orchestrator combines these signals to compose the right team."
-        },
-        {
-          "id": "q6",
-          "question": "The reviewer agent runs Stage 1 (Spec Compliance) and finds that #checkout-form is not registered in any .purpose file. What happens next?",
-          "choices": {
-            "A": "The reviewer proceeds to Stage 2 (Code Quality) and includes the missing registration as a note",
-            "B": "The reviewer stops immediately, reports a blocking finding, and hands back to the builder without running Stage 2",
-            "C": "The reviewer auto-creates the .purpose entry and continues",
-            "D": "The reviewer skips both stages and approves with a warning",
-            "E": "The reviewer runs both stages in parallel and combines results"
-          },
-          "correct": "B",
-          "explanation": "The two-stage protocol is a hard gate: if Stage 1 (Spec Compliance) fails, the reviewer stops immediately and reports blocking findings. There is no point reviewing code quality of spec-noncompliant code -- it is wasted effort. The builder must fix the spec compliance issues first, then resubmit for review."
+          "explanation": "paradigm shift auto-detects project type from markers (package.json = web/node, requirements.txt = Python, etc.) and selects specialized agents that match. The 8 core agents appear in every roster, but specialized and ecosystem agents vary. A web app gets accessibility and performance; an ML project gets data pipeline and model evaluation."
         }
       ]
     },
@@ -413,6 +388,59 @@
         }
       ]
     },
+    {
+      "id": "quick-check",
+      "title": "Quick-Check: Ask Before You Build",
+      "content": "## The Lightweight Pre-Check\n\nNot 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?*\n\nThat is what **quick-check mode** does. It runs a lightweight risk assessment (~3–4k tokens) and returns one of two verdicts:\n\n- **GREENLIGHT** — proceed to implementation. The task is well-scoped, low-risk, and does not need multi-agent planning.\n- **ESCALATE** — this needs full orchestration. The task has unaddressed risks, ambiguous requirements, or cross-cutting concerns.\n\n### How It Works\n\nQuick-check uses two agents:\n\n**Jinx (advocate)** stress-tests your assumptions:\n- \"What if the user loses their second factor?\"\n- \"What happens when the payment provider is down?\"\n- \"Did you consider rate limiting on this endpoint?\"\n\n**Reviewer** checks feasibility:\n- Does this touch auth, security, or shared state?\n- How many files will this change?\n- Are there dependencies that need updating?\n\nTheir combined assessment produces the verdict. If either agent raises concerns that cannot be resolved in a quick check, the verdict is ESCALATE.\n\n### Usage\n\n```\nparadigm_orchestrate_inline({\n  task: \"Add a 'last seen' timestamp to user profiles\",\n  mode: \"quick\"\n})\n```\n\nCompare with full orchestration:\n```\nparadigm_orchestrate_inline({\n  task: \"Add two-factor authentication to the login flow\",\n  mode: \"plan\"\n})\n```\n\n### When to Use Quick-Check vs Full Orchestration\n\n| Signal | Quick-Check | Full Orchestration |\n|--------|-------------|-------------------|\n| Single file change | Yes | Overkill |\n| UI-only change (styling, layout) | Yes | Overkill |\n| Touches auth or security | Depends on scope | Usually yes |\n| 3+ files affected | Depends on complexity | Yes |\n| New API endpoint | Depends on gates needed | Usually yes |\n| Infrastructure change | No | Yes |\n| Unknown scope (\"make it faster\") | No | Yes |\n\n**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.\n\n### Quick-Check and Enforcement\n\nQuick-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.\n\nHowever, 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.\n\n### Example Walkthrough\n\n**Task:** \"Add a 'forgot password' link to the login page\"\n\n**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?\"\n\n**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.\"\n\n**Verdict: ESCALATE** — the task looks simple but involves auth, a new endpoint, email, and rate limiting. Full orchestration with Sentinel (security) and architect (multi-file design) is recommended.\n\nCompare: \"Change the login button color from blue to green\" → **GREENLIGHT** (single CSS change, no logic, no auth).",
+      "keyConcepts": [
+        "Quick-check is a lightweight pre-implementation risk assessment (~3-4k tokens)",
+        "Two agents: Jinx stress-tests assumptions, reviewer checks feasibility",
+        "Two outcomes: GREENLIGHT (proceed) or ESCALATE (needs full orchestration)",
+        "Satisfies orchestration-required enforcement — a greenlight counts as orchestration",
+        "Rule of thumb: one-sentence change + ≤2 files = quick-check, otherwise full orchestration"
+      ],
+      "quiz": [
+        {
+          "id": "q1",
+          "question": "You need to rename a CSS class from .btn-primary to .btn-main across 2 files. Your project uses balanced enforcement with orchestration-required set to warn. What do you do?",
+          "choices": {
+            "A": "Run full orchestration — any change should go through the full pipeline",
+            "B": "Run quick-check — it is a scoped, low-risk change that will likely get GREENLIGHT",
+            "C": "Skip orchestration entirely — CSS changes do not count as \"complex tasks\"",
+            "D": "Ask the architect to plan the rename first",
+            "E": "Disable orchestration-required for this one task"
+          },
+          "correct": "B",
+          "explanation": "A CSS class rename across 2 files is exactly the kind of scoped, low-risk change quick-check is designed for. It will likely GREENLIGHT. Skipping orchestration entirely would trigger the enforcement warning. Running full orchestration would waste tokens on a trivial change. Quick-check gives you the compliance checkmark at minimal cost."
+        },
+        {
+          "id": "q2",
+          "question": "Quick-check returns ESCALATE for your task \"add user deletion endpoint.\" You are short on time and want to build it anyway. What are the consequences?",
+          "choices": {
+            "A": "Nothing — ESCALATE is just a suggestion",
+            "B": "The build will fail at compile time",
+            "C": "The stop hook will flag that you bypassed an ESCALATE recommendation, and the verdict is recorded for traceability",
+            "D": "Your code will be automatically reverted",
+            "E": "The orchestrator will refuse to run any further tasks"
+          },
+          "correct": "C",
+          "explanation": "ESCALATE is a recorded recommendation, not a hard block (unless orchestration-required is set to block in strict enforcement). However, the stop hook flags the bypass, and the verdict is traceable in the session history. A user deletion endpoint likely needs security review (Sentinel) and architectural planning — skipping that introduces real risk."
+        },
+        {
+          "id": "q3",
+          "question": "During quick-check, Jinx asks: \"What if the email service is down when sending password reset?\" and the reviewer notes \"touches auth, new endpoint, email infra — estimated 4+ files.\" The verdict is ESCALATE. Which agents would full orchestration likely include?",
+          "choices": {
+            "A": "Only builder — the task is clearly defined",
+            "B": "Architect (4+ files), Sentinel (auth + password reset), builder, Vigil (tester), Rune (symbols)",
+            "C": "Only Sentinel — it is a security task",
+            "D": "All 54 agents to be thorough",
+            "E": "Jinx and reviewer again, but with more tokens"
+          },
+          "correct": "B",
+          "explanation": "Full orchestration composes the team from trigger patterns: 4+ files triggers architect for multi-file design, auth/password triggers Sentinel for security review, implementation triggers builder, complexity triggers Vigil for testing, and Rune always runs for symbol planning. This is the value of ESCALATE — it routes you to the right team composition."
+        }
+      ]
+    },
     {
       "id": "pm-governance",
       "title": "PM Governance",
@@ -837,4 +865,4 @@
       ]
     }
   ]
-}
+}