@a-company/paradigm 5.37.11 → 6.0.2

package/dist/university-content/quizzes/Q-plsat-v2.yaml

@@ -0,0 +1,904 @@
+id: Q-plsat-v2
+title: The PLSAT — Paradigm Licensure Standardized Assessment Test
+description: 50 questions. 45 minutes. 90% to pass. Good luck, scholar.
+author: paradigm
+created: '2026-04-22'
+updated: '2026-04-22'
+tags:
+  - plsat
+  - certification
+symbols: []
+difficulty: advanced
+passThreshold: 0.9
+timeLimit: 2700
+exam:
+  kind: proctored
+category: paradigm-core
+origin: imported
+source: plsat/v2.0.json
+questions:
+  - id: plsat-001
+    scenario: You've just joined a team that uses Paradigm. You open the project and see directories like `.paradigm/`, several `.purpose` files, and a `portal.yaml` at the root. A colleague asks you to document a new utility function they wrote in `src/lib/format-currency.ts`.
+    question: Which symbol prefix should you use to document this utility?
+    choices:
+      A: '`$format-currency` — because it describes a process (formatting)'
+      B: '`!format-currency` — because it signals a transformation event'
+      C: '`#format-currency` — because it is a documented code unit'
+      D: '`~format-currency` — because it applies a rule (formatting rules)'
+      E: '`^format-currency` — because it gates what format is allowed'
+    correct: C
+    explanation: In Paradigm, every documented code unit uses the `#` (Component) symbol. There are only 5 operational symbols, and `#` is the universal prefix for any code unit — utilities, services, handlers, components, hooks, you name it. `$` is for multi-step flows, `!` for signals/events, `~` for aspects with code anchors, and `^` for condition gates. A simple utility function is a component.
+    section: para-101
+  - id: plsat-002
+    scenario: A component manages user authentication state — tracking the current user, login status, and session tokens. You need to document it in a `.purpose` file.
+    question: How should this component be documented in Paradigm?
+    choices:
+      A: '`#auth-state` with no tags — the component name is descriptive enough'
+      B: '`#auth-state` with `tags: [state]` — the `[state]` tag classifies its role'
+      C: '`!auth-state` — authentication state changes should be modeled as signals'
+      D: '`$auth-state` — state management is a multi-step flow'
+      E: '`~auth-state` — authentication state is a cross-cutting concern requiring an aspect'
+    correct: B
+    explanation: State management components use the `#` (Component) symbol with a `[state]` tag from the tag bank. Paradigm uses only 5 operational symbols for structure, and a tag bank for classification. The `[state]` tag tells humans and AI agents that this component's primary role is managing state, while `#` identifies it as a documented code unit. Signals (`!`) are for events, flows (`$`) are for multi-step processes, and aspects (`~`) are for enforced rules with code anchors.
+    section: para-101
+  - id: plsat-003
+    scenario: Your team is debating logging practices. One developer argues that using `console.log` everywhere is fine because logs are just for debugging. Another insists on using structured, symbol-aware logging with Paradigm's logger (e.g., `log.component('#checkout-service').info('Processing payment', { amount })`).
+    question: What is the STRONGEST argument for using Paradigm's structured logger over raw `console.log`?
+    choices:
+      A: Structured logging is faster at runtime than `console.log`
+      B: Paradigm's logger automatically fixes bugs when it detects errors in the logs
+      C: Symbol-aware logging connects runtime behavior to the documented architecture, making it possible to trace issues back to specific components, flows, and gates
+      D: Using `console.log` will cause Paradigm's CI checks to fail
+      E: Structured logging is required by law for production applications
+    correct: C
+    explanation: 'The core value of Paradigm''s structured logger is traceability: every log line is tagged with a symbol (`#component`, `^gate`, `!signal`, etc.), which means you can correlate runtime behavior with the architectural documentation. When something goes wrong, you can trace from the log back to the component in the `.purpose` file, understand its flows, check its gates, and review its history. Raw `console.log` loses this connection. Performance (A) is not the primary benefit. Paradigm doesn''t auto-fix bugs (B) or enforce logging by law (E). CI checks (D) depend on team configuration, not a universal rule.'
+    section: para-101
+  - id: plsat-004
+    scenario: You're setting up a brand new project with Paradigm. You run `paradigm shift` and it creates the `.paradigm/` directory structure. Your project will have a REST API with several endpoints that require condition checks — such as authentication, feature flags, and rate limiting.
+    question: Which file MUST you create at the project root?
+    choices:
+      A: '`auth.yaml` — Paradigm''s dedicated authentication config'
+      B: '`gates.yaml` — where all `^gate` definitions live'
+      C: '`portal.yaml` — where gates and protected routes are defined'
+      D: '`.paradigm/security.yaml` — security config goes in the paradigm directory'
+      E: No file needed — gates are defined inline in `.purpose` files only
+    correct: C
+    explanation: '`portal.yaml` is REQUIRED at the project root whenever your project has protected routes. It defines gates (`^` symbols) with their check expressions, and maps routes to the gates that protect them. Gates can represent any condition checkpoint — authentication, authorization, feature flags, rate limits, or custom business rules. Gates can also appear in `.purpose` files for documentation, but `portal.yaml` is the authoritative source for route protection.'
+    section: para-101
+  - id: plsat-005
+    scenario: |-
+      You find the following `.purpose` file in `src/payments/`:
+
+      ```yaml
+      name: Payments Module
+      description: Handles all payment processing
+      components:
+        #stripe-service:
+          description: Stripe API integration
+          file: stripe.ts
+          tags: [integration, stripe]
+        #payment-processor:
+          description: Core payment logic
+          file: processor.ts
+          signals: ["!payment-completed", "!payment-failed"]
+      ```
+    question: What is the correct way to reference `#stripe-service` from another `.purpose` file in a different directory?
+    choices:
+      A: '`payments/#stripe-service` — use the directory path as a namespace'
+      B: '`#stripe-service` — symbol IDs are globally unique across the project'
+      C: '`&stripe-service` — integrations use the `&` prefix when cross-referenced'
+      D: '`#payments.stripe-service` — use dot notation for cross-module references'
+      E: '`import: #stripe-service from payments` — use import syntax'
+    correct: B
+    explanation: Symbol IDs are globally unique across the entire Paradigm project. You reference `#stripe-service` the same way everywhere — no namespacing, no path prefixes, no import syntax. Paradigm's index (built by `paradigm scan`) tracks where each symbol is defined. If you have naming conflicts, use more specific names (e.g., `#payments-stripe-service`). The convention is kebab-case for all symbol IDs.
+    section: para-101
+  - id: plsat-006
+    scenario: |-
+      Your team uses the following directory structure:
+
+      ```
+      src/
+        middleware/auth.ts
+        events/payment-events.ts
+        services/billing.ts
+        flows/onboarding.ts
+        aspects/rate-limiter.ts
+      ```
+
+      A new developer asks which Paradigm logger method to use in each file. Your team follows the conventional directory-to-symbol mapping as a guideline.
+    question: Which file-to-logger mapping is INCORRECT?
+    choices:
+      A: '`middleware/auth.ts` → `log.gate(''^auth-check'')`'
+      B: '`events/payment-events.ts` → `log.signal(''!payment-received'')`'
+      C: '`services/billing.ts` → `log.component(''#billing-service'')`'
+      D: '`flows/onboarding.ts` → `log.signal(''!onboarding-started'')`'
+      E: '`aspects/rate-limiter.ts` → `log.aspect(''~rate-limited'')`'
+    correct: D
+    explanation: 'Files in the `flows/` directory conventionally correspond to `$` (Flow) symbols and should use `log.flow()`, not `log.signal()`. The correct call would be `log.flow(''$onboarding'').info(...)`. The conventional directory-to-symbol mapping is: middleware/auth/guards → `^` (gate), events/handlers/listeners → `!` (signal), services/lib/components → `#` (component), flows/sagas/workflows → `$` (flow), aspects/rules → `~` (aspect). While teams may adapt these conventions to their needs, this mapping provides a consistent default that helps developers and AI agents reason about the codebase.'
+    section: para-101
+  - id: plsat-007
+    scenario: Your team is prototyping a new feature — an experimental search widget that may or may not ship. You've built the component and want to document it in a `.purpose` file. You also want to make it clear to other developers and AI agents that this is an idea in progress, not a committed part of the product.
+    question: How should you classify this component to indicate it is experimental?
+    choices:
+      A: Use a special `?experimental-widget` symbol prefix reserved for ideas
+      B: 'Add `status: experimental` to the component definition'
+      C: 'Add the `[idea]` tag to the component: `tags: [idea]`'
+      D: Create an aspect `~experimental` and apply it to the component
+      E: Comment it out in the `.purpose` file with `# EXPERIMENTAL`
+    correct: C
+    explanation: 'Paradigm''s tag bank includes the `[idea]` tag for exactly this purpose. You''d define the component as `#experimental-widget` with `tags: [idea]`. Tags are the classification layer in Paradigm: the 5 operational symbols (`#`, `$`, `^`, `!`, `~`) provide structure, while tags from the tag bank provide classification metadata like `[idea]`, `[feature]`, `[state]`, `[integration]`, `[critical]`, etc. Choice B (status field) is plausible but `status` is typically for lifecycle states like `active` or `deprecated`, not for ideation. There is no `?` symbol prefix in Paradigm (A). Commenting it out (E) removes it from the symbol graph entirely.'
+    section: para-101
+  - id: plsat-008
+    scenario: 'A `.paradigm/tags.yaml` file has three sections: `core`, `project`, and `suggested`. The `core` section contains tags like `[feature]`, `[integration]`, `[state]`, `[critical]`, and `[security]`.'
+    question: What is the `suggested` section for?
+    choices:
+      A: Tags that Paradigm automatically generates based on code analysis
+      B: Tags proposed by AI agents awaiting human approval before use
+      C: Tags from the Paradigm community marketplace that can be installed
+      D: Tags that are deprecated and will be removed in the next version
+      E: Tags that the framework suggests but are optional to implement
+    correct: B
+    explanation: 'The `suggested` section in `tags.yaml` holds tags proposed by AI agents (via `paradigm_tags_suggest`) that haven''t been approved by a human yet. This is part of Paradigm''s governance model: AI can propose new classifications, but a human must promote them to `project` or `core` before they become official. This prevents tag sprawl and keeps the taxonomy intentional. The `core` tags ship with Paradigm, `project` tags are team-defined, and `suggested` are AI proposals awaiting review.'
+    section: para-101
+  - id: plsat-009
+    scenario: |-
+      You're reading a project's `.paradigm/config.yaml` and see:
+
+      ```yaml
+      discipline: fullstack
+      conventions:
+        naming: kebab-case
+        components: PascalCase
+      ```
+    question: Based on these conventions, which symbol ID is correctly formatted?
+    choices:
+      A: '`#paymentService` — camelCase for services'
+      B: '`#payment-service` — kebab-case for IDs, PascalCase for class-like references'
+      C: '`#Payment_Service` — PascalCase with underscores'
+      D: '`#PAYMENT_SERVICE` — SCREAMING_SNAKE for services'
+      E: '`#payment.service` — dot notation for namespaced components'
+    correct: B
+    explanation: 'Paradigm conventions specify kebab-case for all symbol IDs. The `components: PascalCase` convention means that when referring to class-like components in prose or code, you use PascalCase (e.g., `#PaymentService`), but the canonical ID in `.purpose` files is kebab-case (`#payment-service`). This dual convention is documented in the CLAUDE.md: ''Use kebab-case for all symbol IDs'' and ''Use PascalCase for class-like components''.'
+    section: para-101
+  - id: plsat-010
+    scenario: |-
+      A team member creates a new `.purpose` file for their notification system:
+
+      ```yaml
+      name: Notifications
+      components:
+        #email-sender:
+          description: Sends transactional emails
+          file: email.ts
+        #push-notifier:
+          description: Sends push notifications
+          file: push.ts
+      signals:
+        !notification-sent:
+          description: Fires after any notification is delivered
+          emitters: ["#email-sender", "#push-notifier"]
+      ```
+    question: This `.purpose` file is missing a critical top-level field. What is it?
+    choices:
+      A: '`version` — every purpose file must specify a schema version'
+      B: '`description` — every purpose file should describe what the module does'
+      C: '`tags` — top-level tags are required for indexing'
+      D: '`gates` — every module must define its authorization requirements'
+      E: '`flows` — signals require at least one flow to be meaningful'
+    correct: B
+    explanation: Every `.purpose` file should have a `description` field explaining what the module/directory does. While `name` identifies it, `description` provides the context that AI agents and developers need to understand the module's role. The `paradigm_purpose_init` tool requires both `name` and `description` conceptually, and `paradigm doctor` will flag purpose files missing descriptions. Tags, gates, and flows are optional depending on the module's nature. Version is handled at the framework level, not per-file.
+    section: para-101
+  - id: plsat-011
+    scenario: 'You''re designing an e-commerce checkout process that involves: (1) validating the cart, (2) checking inventory, (3) processing payment via Stripe, (4) creating the order record, and (5) sending a confirmation email. This spans 5 different components across 3 directories.'
+    question: How should this be documented in Paradigm?
+    choices:
+      A: As a single `#checkout` component with sub-steps in its description
+      B: As a `$checkout-flow` with ordered steps referencing each component
+      C: As five separate `!` signals chained together
+      D: As a `~checkout-required` aspect applied to all five components
+      E: As five `^` gates that must be passed sequentially
+    correct: B
+    explanation: 'A multi-step process spanning 3+ components is the textbook definition of a Flow (`$`). You''d define `$checkout-flow` with ordered steps, each referencing the responsible component and action: `#cart-validator` validates, `#inventory-checker` checks stock, `#stripe-service` processes payment, `#order-service` creates the record, `#email-sender` confirms. Flows document the sequence and make it visible to `paradigm_flows_affected` for impact analysis. Signals (`!`) may be emitted during the flow, but they don''t define the sequence.'
+    section: para-201
+  - id: plsat-012
+    scenario: |-
+      Your `portal.yaml` defines these gates:
+
+      ```yaml
+      gates:
+        ^authenticated:
+          description: User must be logged in
+          check: req.user != null
+        ^project-admin:
+          description: User must be admin of the project
+          check: project.admins.includes(req.user.id)
+          requires: ["^authenticated"]
+      ```
+
+      A new endpoint `DELETE /api/projects/:id` needs to be added. Only project admins should be able to delete projects.
+    question: What is the correct route entry in `portal.yaml`?
+    choices:
+      A: '`"DELETE /api/projects/:id": [^authenticated, ^project-admin]`'
+      B: '`"DELETE /api/projects/:id": [^project-admin]`'
+      C: '`"DELETE /api/projects/:id": [^authenticated]`'
+      D: '`"DELETE /api/projects/:id": [^project-admin, ^authenticated]`'
+      E: '`"DELETE /api/projects/:id": [^admin]`'
+    correct: B
+    explanation: 'Since `^project-admin` already has `requires: ["^authenticated"]`, listing `^authenticated` in the route is redundant. The gate dependency chain means `^project-admin` will automatically enforce `^authenticated` first. The route only needs to specify `[^project-admin]`. Choice A technically works (it''s not wrong per se), but it''s redundant and violates the DRY principle. Choice D reverses the order, which could cause confusion about evaluation sequence. Choice E references a gate that doesn''t exist in the portal.'
+    section: para-201
+  - id: plsat-013
+    scenario: |-
+      A developer defines the following aspect:
+
+      ```yaml
+      aspects:
+        ~audit-required:
+          description: All financial operations must be logged
+          tags: [compliance, security]
+          applies-to: ["#*Service"]
+      ```
+
+      They run `paradigm doctor` and get a validation error.
+    question: What is missing from this aspect definition?
+    choices:
+      A: The `enforcement` field specifying how the aspect is enforced
+      B: The `anchors` field pointing to the actual enforcement code
+      C: The `severity` field indicating how critical the aspect is
+      D: The `gates` field linking the aspect to authorization checks
+      E: The `signals` field for emitting audit events
+    correct: B
+    explanation: 'Aspects (`~`) MUST have code anchors. This is a hard rule in Paradigm: no unanchored aspects allowed. Anchors point to the actual lines of code where the aspect is enforced (e.g., `src/middleware/audit.ts:15-35`). Without anchors, the aspect is just documentation with no verifiable link to implementation. `paradigm doctor` and `paradigm_aspect_check` will both flag unanchored aspects. The anchor format supports single lines (`file.ts:15`), ranges (`file.ts:15-20`), and multiple lines (`file.ts:15,25,30`).'
+    section: para-201
+  - id: plsat-014
+    scenario: 'You''re implementing a webhook handler that receives events from a third-party payment provider. When a payment succeeds, your system needs to: update the order status, send a receipt email, and notify the analytics service. These are independent side effects that don''t need to happen in order.'
+    question: What is the MOST appropriate Paradigm modeling for these independent side effects?
+    choices:
+      A: A `$payment-webhook-flow` with three sequential steps
+      B: A `!payment-succeeded` signal with three subscriber components
+      C: Three separate `^` gates that the webhook must pass
+      D: A `~payment-side-effects` aspect applied to the webhook handler
+      E: Three `#` components with no formal connection between them
+    correct: B
+    explanation: When side effects are independent and don't require ordering, a Signal (`!`) is the right model. You define `!payment-succeeded` and document three subscriber components (`#order-service`, `#email-sender`, `#analytics-tracker`) that react to it. Signals are for events that trigger side effects. A Flow (`$`) would be appropriate if the steps needed to happen in a specific order or if one step depended on the output of another. Gates (`^`) are for condition checks, not business logic.
+    section: para-201
+  - id: plsat-015
+    scenario: 'Your project''s discipline is `fullstack`. You''re adding a new feature: team invitations. The feature involves a UI component for the invite form, an API endpoint, a service for generating invite tokens, and an email sender. You create a new directory `src/features/team-invites/`.'
+    question: What should the `.purpose` file in this directory contain at minimum?
+    choices:
+      A: Just a `name` field — Paradigm will auto-discover the rest
+      B: A `name`, `description`, and at least one `#component` entry
+      C: A full `$flow` definition with all steps documented
+      D: Gate definitions (`^`) for all protected endpoints in this feature
+      E: Signal definitions (`!`) for all events this feature emits
+    correct: B
+    explanation: At minimum, a `.purpose` file needs a `name` and `description` (to orient agents and developers) and at least one `#component` documenting a code unit. Gates go in `portal.yaml` (the authoritative source for route protection), not in purpose files. Flows and signals are important but not required for every feature — they should be added when the feature has multi-step processes or emits events. Paradigm does not auto-discover components; they must be explicitly documented.
+    section: para-201
+  - id: plsat-016
+    scenario: |-
+      You're looking at a `portal.yaml` with this route mapping:
+
+      ```yaml
+      routes:
+        "GET /api/projects": [^authenticated]
+        "POST /api/projects": [^authenticated]
+        "GET /api/projects/:id": [^authenticated, ^project-member]
+        "PUT /api/projects/:id": [^authenticated, ^project-admin]
+        "DELETE /api/projects/:id": [^authenticated, ^project-admin]
+        "POST /api/projects/:id/comments": [^authenticated, ^project-member]
+      ```
+
+      A colleague adds a new endpoint: `DELETE /api/projects/:id/comments/:commentId`. Only the comment author should be able to delete their own comment.
+    question: Which gate configuration follows Paradigm best practices?
+    choices:
+      A: Add `[^authenticated, ^project-admin]` — admins can delete anything
+      B: Add `[^authenticated, ^project-member, ^comment-author]` — must be a member AND the author
+      C: Add `[^comment-author]` — authorship implies authentication and membership
+      D: Add `[^authenticated, ^comment-author]` — logged in and owns the comment
+      E: Don't add it to portal.yaml — handle it in the route handler code only
+    correct: B
+    explanation: 'The correct approach is `[^authenticated, ^project-member, ^comment-author]`. Being the comment author doesn''t automatically mean you''re authenticated or a project member (the comment could be from before you were removed). Each gate has one responsibility: `^authenticated` checks login, `^project-member` checks project access, `^comment-author` checks ownership. If `^comment-author` had `requires: [^authenticated, ^project-member]`, then just `[^comment-author]` would suffice. But without explicit requires, list all gates. Choice E violates the cardinal rule: all protected routes MUST be in portal.yaml.'
+    section: para-201
+  - id: plsat-017
+    scenario: |-
+      Your team defines the following flow:
+
+      ```yaml
+      flows:
+        $user-onboarding:
+          description: New user setup after registration
+          steps:
+            - component: "#email-verifier"
+              action: send-verification-email
+            - component: "#profile-wizard"
+              action: collect-profile-data
+            - component: "#team-assigner"
+              action: assign-default-team
+            - component: "#welcome-emailer"
+              action: send-welcome-email
+          signals: ["!user-onboarded"]
+      ```
+
+      You need to modify `#email-verifier` to use a new email provider.
+    question: Before making the code change, what should you do FIRST?
+    choices:
+      A: Run `paradigm_search` to find all references to `#email-verifier`
+      B: Read the `#email-verifier` source file to understand the current implementation
+      C: Call `paradigm_ripple` on `#email-verifier` to understand the impact
+      D: Call `paradigm_orchestrate_inline` to plan the migration
+      E: Update the `.purpose` file first to reflect the new provider
+    correct: C
+    explanation: Before modifying ANY symbol, the first step is always `paradigm_ripple`. This shows you what depends on `#email-verifier` directly and indirectly — in this case, you'd discover it's part of `$user-onboarding` and any other flows or components that reference it. This prevents you from making changes that break downstream dependencies. After ripple analysis, you'd read the source (B), check wisdom/history, and then implement. Orchestration (D) is for complex multi-file tasks, not single-component changes.
+    section: para-201
+  - id: plsat-018
+    scenario: You're defining a gate for a multi-tenant SaaS application. Users can belong to multiple organizations, and each organization has its own resources. You need a gate that checks whether the requesting user is a member of the organization that owns the requested resource.
+    question: Which gate definition follows the Paradigm portal pattern?
+    choices:
+      A: |-
+        ```yaml
+        ^org-member:
+          description: User is a member of the organization AND has read permission
+          check: org.members.includes(req.user.id) && req.user.permissions.read
+        ```
+      B: |-
+        ```yaml
+        ^org-member:
+          description: User is a member of the resource's organization
+          check: org.members.includes(req.user.id)
+        ```
+      C: |-
+        ```yaml
+        ^org-access:
+          description: User can access organization resources with full CRUD
+          check: org.members.includes(req.user.id) && req.user.role !== 'viewer'
+        ```
+      D: |-
+        ```yaml
+        ^resource-check:
+          description: Validates resource exists and user has access
+          check: resource != null && org.members.includes(req.user.id)
+        ```
+      E: |-
+        ```yaml
+        ^member-or-admin:
+          description: User is either a member or an admin of the organization
+          check: org.members.includes(req.user.id) || org.admins.includes(req.user.id)
+        ```
+    correct: B
+    explanation: 'Paradigm''s gate philosophy is ''one responsibility per gate.'' Choice B does exactly one thing: checks organization membership. Choice A bundles membership with permissions (two responsibilities). Choice C adds a role check. Choice D validates resource existence (that''s a different concern). Choice E conflates membership and admin roles. If you need permission checks, create `^org-reader`, `^org-writer` as separate gates with `requires: ["^org-member"]`. Keep gates minimal and composable.'
+    section: para-201
+  - id: plsat-019
+    scenario: |-
+      A developer has documented the following in `aspects/`:
+
+      ```yaml
+      aspects:
+        ~rate-limited:
+          description: API endpoints are rate-limited per user
+          tags: [security, performance]
+          anchors:
+            - src/middleware/rate-limiter.ts:12-45
+          applies-to: ["#*-handler"]
+          enforcement: middleware
+      ```
+
+      The `applies-to` pattern `#*-handler` uses a glob. The developer asks if the aspect will automatically apply rate limiting to all matching components.
+    question: What is the correct understanding of `applies-to` in an aspect?
+    choices:
+      A: It automatically applies the middleware to all matching components at runtime
+      B: It generates rate-limiting code for each matching component during build
+      C: It is a documentation hint — tells humans/AI which components SHOULD have this aspect, but doesn't enforce it
+      D: It creates a compile-time check that all matching components import the rate limiter
+      E: It registers the components with the rate-limiter middleware automatically on server startup
+    correct: C
+    explanation: Paradigm is a documentation and intelligence framework, not a runtime. `applies-to` is a declarative hint that tells humans and AI agents which components should have the `~rate-limited` aspect applied. It doesn't auto-generate code, inject middleware, or create compile-time checks. The anchors point to WHERE the rate limiting is implemented, and `applies-to` says WHERE it SHOULD be applied. `paradigm doctor` and `paradigm_aspect_check` can validate that the anchors exist, but enforcement in the actual code is the developer's responsibility.
+    section: para-201
+  - id: plsat-020
+    scenario: 'You open `.paradigm/config.yaml` and see `discipline: fullstack`. You''re curious what this means and whether it affects how symbols are mapped.'
+    question: What does the `discipline` field control in Paradigm?
+    choices:
+      A: It determines which programming language the project uses
+      B: It configures the symbol-to-directory mapping and recommended patterns for the project type
+      C: It restricts which symbols are allowed — e.g., some disciplines don't use flows
+      D: It's purely cosmetic — shown in the dashboard but has no functional effect
+      E: It determines the deployment pipeline configuration
+    correct: B
+    explanation: The `discipline` field tells Paradigm what kind of project this is, which influences symbol mappings (e.g., where components vs. gates typically live), suggested patterns, and how AI agents reason about the codebase. A `fullstack` discipline suggests `middleware/` maps to gates, `services/` to components, etc. Different disciplines (e.g., `cli`, `library`, `embedded`) would have different default mappings. Since v2, Paradigm auto-detects the discipline from project structure at init time. It doesn't restrict symbols — all 5 are always available.
+    section: para-201
+  - id: plsat-021
+    scenario: |-
+      While reviewing a PR, you notice a developer added a new webhook endpoint:
+
+      ```typescript
+      // src/api/webhooks/stripe.ts
+      app.post('/api/webhooks/stripe', async (req, res) => {
+        const event = verifyStripeSignature(req);
+        if (event.type === 'payment_intent.succeeded') {
+          await updateOrderStatus(event.data);
+          await sendReceipt(event.data);
+        }
+        res.json({ received: true });
+      });
+      ```
+
+      The developer did not update any Paradigm files.
+    question: Which Paradigm files should be updated? Select the MOST complete answer.
+    choices:
+      A: Only `portal.yaml` — add the webhook route with appropriate gates
+      B: Only the nearest `.purpose` file — add `#stripe-webhook-handler` as a component
+      C: Both `portal.yaml` and the nearest `.purpose` file
+      D: The `.purpose` file, `portal.yaml`, and add a `!payment-succeeded` signal definition
+      E: No updates needed — webhooks are external and don't need Paradigm documentation
+    correct: D
+    explanation: 'The most complete answer includes: (1) The `.purpose` file needs a `#stripe-webhook-handler` component with `tags: [integration, stripe]`. (2) `portal.yaml` needs the route — even webhook endpoints may need gates (e.g., signature verification as `^stripe-signature-valid`). (3) The payment success event should be documented as `!payment-succeeded` since it triggers side effects (order update, receipt). This is the Paradigm principle: if it exists in code, it should exist in the symbol graph.'
+    section: para-201
+  - id: plsat-022
+    scenario: |-
+      A developer writes this commit message:
+
+      ```
+      added apple pay button and updated checkout
+      ```
+    question: What is wrong with this commit message according to Paradigm conventions?
+    choices:
+      A: It should use past tense ('added' is correct, actually)
+      B: It's missing the conventional commit type, primary symbol in parentheses, and the `Symbols:` trailer
+      C: It should be in ALL CAPS for visibility
+      D: It should reference the Jira ticket number instead of symbols
+      E: Nothing is wrong — commit messages are personal preference
+    correct: B
+    explanation: |-
+      Paradigm commit messages follow a strict format: `type(#primary-symbol): description` in the subject, symbol references in the body, and a `Symbols:` trailer for machine parsing. The correct message would be:
+
+      ```
+      feat(#payment-form): add Apple Pay support
+
+      - Add #apple-pay-button component
+      - Update $checkout-flow with new payment step
+
+      Symbols: #payment-form, #apple-pay-button, $checkout-flow
+      ```
+
+      The `Symbols:` trailer is parsed by the post-commit hook for automatic history capture.
+    section: para-201
+  - id: plsat-023
+    scenario: You're building a real-time notification system. Notifications can arrive via WebSocket, and the user can mark them as read, archive them, or delete them. The system also needs to handle notification preferences (email, push, in-app) and batching for high-volume scenarios.
+    question: A team member suggests modeling each notification action (read, archive, delete) as a separate `$` flow. What is the BEST response?
+    choices:
+      A: Agree — each action is a distinct process that should have its own flow
+      B: Disagree — single actions are not flows; use `#` components for each action and a `$notification-lifecycle` flow for the overall process
+      C: Disagree — these should all be `!` signals since they're user-triggered events
+      D: Agree, but only if each action involves 3+ components
+      E: Disagree — model them as `^` gates since they require condition checks
+    correct: B
+    explanation: 'Flows (`$`) are for multi-step processes spanning 3+ components. A single action like ''mark as read'' is just a component method, not a flow. The correct modeling is: `#notification-reader`, `#notification-archiver`, etc. as components, with `!notification-read`, `!notification-archived` as signals for side effects. If the OVERALL lifecycle (receive → display → interact → archive/delete) is worth documenting, THAT is the flow: `$notification-lifecycle`. Choice D gets close but misses the key insight about modeling the lifecycle.'
+    section: para-201
+  - id: plsat-024
+    scenario: |-
+      Your project has the following aspect definition:
+
+      ```yaml
+      ~audit-required:
+        description: Financial operations must produce audit logs
+        anchors:
+          - src/middleware/audit.ts:15-35
+          - src/decorators/auditable.ts:1-20
+        applies-to: ["#*Service"]
+        enforcement: middleware
+      ```
+
+      A colleague refactors `audit.ts` and moves the audit logic from lines 15-35 to lines 50-70.
+    question: What happens if the anchors are not updated?
+    choices:
+      A: Nothing — anchors are just documentation hints and aren't validated
+      B: '`paradigm doctor` will report stale anchors, and `paradigm_aspect_check` will flag the mismatch'
+      C: The application will crash because the aspect can't find its enforcement code
+      D: The audit middleware will stop working because Paradigm controls execution
+      E: The CI pipeline will block the merge due to anchor validation
+    correct: B
+    explanation: Paradigm is a documentation/intelligence layer, not a runtime. Stale anchors won't crash your app or stop middleware from working. However, `paradigm doctor` (the validation command) and `paradigm_aspect_check` (the MCP tool) will detect that the anchored lines no longer match the expected code. This is important because anchors are the mechanism that keeps aspects grounded in real code rather than becoming aspirational documentation. The developer should update anchors to `src/middleware/audit.ts:50-70` as part of the refactor.
+    section: para-201
+  - id: plsat-025
+    scenario: You're adding a new API endpoint `POST /api/billing/invoices` to your project. Before writing any code, you want to follow Paradigm best practices.
+    question: What is the recommended sequence of steps?
+    choices:
+      A: Write the code → Update `.purpose` file → Update `portal.yaml` → Commit
+      B: Call `paradigm_gates_for_route` → Update `portal.yaml` → Write the code → Update `.purpose` file → Commit
+      C: Update `portal.yaml` → Write the code → Run `paradigm doctor` → Commit
+      D: Write the code → Run `paradigm scan` → Let it auto-generate the purpose file → Commit
+      E: Call `paradigm_orchestrate_inline` → Spawn agents → Let agents handle everything
+    correct: B
+    explanation: 'The recommended flow for adding endpoints is: (1) Call `paradigm_gates_for_route` to get gate suggestions for `POST /api/billing/invoices`, (2) Update `portal.yaml` with the route and its gates, (3) Implement the endpoint with proper gate enforcement, (4) Update the nearest `.purpose` file with the new `#` component, signals, etc. (5) Commit with proper Paradigm commit format. This ''portal first'' approach ensures security is designed before implementation. Choice D is wrong because `paradigm scan` discovers existing symbols but doesn''t auto-generate purpose files from code.'
+    section: para-201
+  - id: plsat-026
+    scenario: You're in the middle of a long Claude Code session. You've made 47 tool calls, modified 12 files, and you're about to start a complex refactor of the payment system. You vaguely recall something about context management but can't remember the details.
+    question: What should you do before starting the refactor?
+    choices:
+      A: Just continue — context management is handled automatically
+      B: Call `paradigm_session_health` to see if a handoff is recommended
+      C: Start a new Claude session immediately to get fresh context
+      D: Save all files and run `paradigm scan` to rebuild the index
+      E: Call `paradigm_session_stats` and if over 100 tool calls, panic
+    correct: B
+    explanation: The protocol says to call `paradigm_session_health` periodically (every 10-15 tool calls) during long sessions. At 47 tool calls, you're well overdue for a check. This tool analyzes your context window usage and recommends whether to continue, prepare a handoff, or urgently wrap up. If usage is over 85%, you should prioritize completing your current task and prepare a handoff with `paradigm_handoff_prepare`. Don't just start a new session (C) without preparing a handoff — you'd lose all context about what was done.
+    section: para-301
+  - id: plsat-027
+    scenario: |-
+      You run `paradigm doctor` and get the following output:
+
+      ```
+      WARNING: #payment-processor has been modified 7 times in 14 days
+      WARNING: #payment-processor has 3 rollbacks in history
+      FRAGILITY SCORE: 0.85 (HIGH)
+      ```
+    question: What does a fragility score of 0.85 indicate, and what should you do?
+    choices:
+      A: The component has a bug 85% of the time — rewrite it from scratch
+      B: 85% of the codebase depends on it — extract it into a separate service
+      C: The component is highly unstable due to frequent changes and rollbacks — proceed with extra caution, review wisdom, and consider refactoring
+      D: The component needs 85% more test coverage — write tests first
+      E: The score is informational only — ignore it and proceed normally
+    correct: C
+    explanation: 'A fragility score of 0.85 (out of 1.0) means the component is highly unstable. It''s been changed 7 times in 2 weeks with 3 rollbacks — a clear pattern of churn. Before modifying it: (1) Call `paradigm_wisdom_context` to check for antipatterns and `paradigm_decision_search` for prior decisions about it, (2) Call `paradigm_history_context` to understand the recent changes, (3) Consider whether a refactor is needed before adding more changes. The score doesn''t mean ''has bugs 85%'' or ''needs 85% coverage'' — it''s a stability metric based on change frequency and rollback rate.'
+    section: para-301
+  - id: plsat-028
+    scenario: 'After a production incident where the payment system double-charged a customer, the team discovers the root cause: a developer removed a deduplication check while refactoring `#payment-processor`. The team wants to prevent this from happening again.'
+    question: What is the MOST appropriate Paradigm response to this incident?
+    choices:
+      A: 'Add a comment in the code: `// DO NOT REMOVE THIS CHECK`'
+      B: 'Record an antipattern in wisdom: ''Never remove deduplication from #payment-processor'' with the alternative approach'
+      C: Create a `^deduplication-enforced` gate in portal.yaml
+      D: Add `#payment-processor` to a 'do not touch' list in `.paradigm/config.yaml`
+      E: Record the incident in Sentinel AND record an antipattern in wisdom
+    correct: E
+    explanation: 'The most complete response uses both Sentinel and Wisdom. (1) Record the incident with `paradigm_sentinel_record` so it appears in incident tracking with symbolic context (the `#payment-processor` symbol, error details, timeline). (2) Record an antipattern with `paradigm_wisdom_record` so future AI agents and developers are warned before modifying `#payment-processor`. The antipattern would say: ''Never remove deduplication logic'' with alternative: ''If refactoring payment processing, always preserve the deduplication middleware and add tests for it.'' A code comment (A) is easily missed. A gate (C) is for condition checks on routes, not business logic.'
+    section: para-301
+  - id: plsat-029
+    scenario: You need to understand the impact of changing `^authenticated` — the main authentication gate used across your entire application. You want to know what depends on it.
+    question: Which MCP tool call gives you the MOST useful dependency information?
+    choices:
+      A: '`paradigm_search({ query: ''^authenticated'' })` — find all references'
+      B: '`paradigm_related({ symbol: ''^authenticated'' })` — show direct relations'
+      C: '`paradigm_ripple({ symbol: ''^authenticated'', depth: 3 })` — show direct AND indirect dependencies up to 3 levels'
+      D: '`paradigm_navigate({ intent: ''find'', target: ''^authenticated'' })` — locate the gate'
+      E: '`paradigm_flows_affected({ symbol: ''^authenticated'' })` — show affected flows'
+    correct: C
+    explanation: '`paradigm_ripple` with a depth parameter gives you the cascading dependency analysis. For a widely-used gate like `^authenticated`, you need to see not just what directly references it, but what depends on things that depend on it (transitive dependencies). At depth 3, you''d see: Level 1 — all gates with `requires: [^authenticated]`, all routes using it. Level 2 — all components behind those routes. Level 3 — flows involving those components. `paradigm_related` (B) only shows direct connections. `paradigm_search` (A) finds textual references but doesn''t analyze the dependency graph.'
+    section: para-301
+  - id: plsat-030
+    scenario: It's Monday morning. You open Claude Code to continue work on a project. Last Friday, a different Claude session was making changes to the user management module. You have no idea what state things are in.
+    question: What is the FIRST thing you should do?
+    choices:
+      A: Run `git log` to see recent commits
+      B: Call `paradigm_session_recover` to load breadcrumbs from the previous session
+      C: Call `paradigm_status` for a general project overview
+      D: Read the `.paradigm/config.yaml` to understand the project
+      E: Start fresh — don't worry about what the previous session did
+    correct: B
+    explanation: '`paradigm_session_recover` is designed exactly for this scenario. It loads breadcrumbs from previous sessions, showing you what was done, what files were modified, what symbols were touched, and what the next steps were. This is more useful than `paradigm_status` (C) because status gives you general project info, not session-specific context. After recovering the session, THEN you''d call `paradigm_status` and check the relevant files. Starting fresh (E) risks duplicating work or missing important context.'
+    section: para-301
+  - id: plsat-031
+    scenario: Your application is experiencing intermittent 500 errors on the checkout flow. You suspect it's related to the Stripe integration. You want to check if there's a known pattern for this type of failure.
+    question: Which sequence of Sentinel tools should you use?
+    choices:
+      A: '`paradigm_sentinel_triage` to see open incidents, then `paradigm_sentinel_patterns` to find matching failure patterns'
+      B: '`paradigm_sentinel_stats` to see overall health, then guess at the root cause'
+      C: '`paradigm_sentinel_record` to create a new incident immediately'
+      D: '`paradigm_sentinel_suggest_pattern` without any incident context'
+      E: '`paradigm_sentinel_resolve` to close any open incidents and hope it goes away'
+    correct: A
+    explanation: 'The diagnostic workflow is: (1) `paradigm_sentinel_triage` with a filter like `search: ''500''` or `symbol: ''#stripe-service''` to see if there are existing open incidents matching your symptoms. (2) `paradigm_sentinel_patterns` to find known failure patterns (with confidence scores) that match the error. If a pattern matches, it includes resolution steps and code hints. You''d only record a NEW incident (C) if triage shows this is a novel failure. Resolving without investigating (E) is never the right answer. Stats (B) give you health metrics but not diagnostic details.'
+    section: para-301
+  - id: plsat-032
+    scenario: You want to find who on your team has the most expertise with the payment system before making a significant architectural change.
+    question: Which Paradigm tool helps you find the right person?
+    choices:
+      A: '`paradigm_search({ query: ''payments'' })` and look at file authors in git blame'
+      B: '`paradigm_wisdom_expert({ area: ''payments'' })` to find recognized experts'
+      C: '`paradigm_history_context({ symbols: [''#payment-service''] })` and infer from commit history'
+      D: '`paradigm_navigate({ intent: ''explore'', target: ''payments'' })` and read the code to figure out who wrote it'
+      E: Ask in Deus / Slack / Teams
+    correct: B
+    explanation: '`paradigm_wisdom_expert` is purpose-built for finding human experts by area or symbol. It returns people who are recognized as knowledgeable about the payment system, based on recorded wisdom and history. While `paradigm_history_context` (C) can show who recently worked on the code, that doesn''t mean they''re the expert — they might have just fixed a typo. `paradigm_wisdom_expert` tracks deliberate expertise attribution, not just commit frequency.'
+    section: para-301
+  - id: plsat-033
+    scenario: After completing a significant refactor of the authentication module, you want to record what you did for future sessions and team members.
+    question: What is the correct way to record this in Paradigm's history system?
+    choices:
+      A: Write a detailed comment in the `.purpose` file
+      B: Call `paradigm_history_record` with type 'refactor', affected symbols, and description
+      C: Update `.paradigm/docs/changelog.md` with the changes
+      D: Just commit with a good message — git history is sufficient
+      E: Call `paradigm_decision_record` with title, rationale, and participants explaining the refactor rationale
+    correct: B
+    explanation: '`paradigm_history_record` is the right tool for recording implementation events. You''d call it with `type: ''refactor''`, `symbols: [''^authenticated'', ''#auth-middleware'', ...]`, and a description of what was changed. This feeds into the history system that powers `paradigm_history_context` and `paradigm_history_fragility`. A good commit message (D) is important but separate — Paradigm''s history provides symbolic context that git alone doesn''t. If the refactor involved an architectural DECISION, you''d ALSO record it via `paradigm_decision_record` (E), but that''s supplementary, not a replacement — the implementation event itself belongs in the history system. (Note: `paradigm_wisdom_record` no longer accepts `type: ''decision''` in v6.0; decisions live in the dedicated decision store.)'
+    section: para-301
+  - id: plsat-034
+    scenario: You've run tests after implementing a new feature. 15 tests passed, 2 failed, and 1 was skipped. You previously recorded the implementation with `paradigm_history_record` and got back an implementation ID.
+    question: How should you record the test results?
+    choices:
+      A: Update the implementation record by calling `paradigm_history_record` again
+      B: Call `paradigm_history_validate` with result 'partial' and the test counts
+      C: Call `paradigm_history_validate` with result 'fail' because not all tests passed
+      D: Don't record it — fix the failing tests first, then record a 'pass'
+      E: Call `paradigm_sentinel_record` to log the test failures as incidents
+    correct: B
+    explanation: '`paradigm_history_validate` is the validation companion to `paradigm_history_record`. With 15 passed, 2 failed, and 1 skipped, the result is ''partial'' (not full pass, not complete failure). You''d call it with `result: ''partial''` and `tests: { passed: 15, failed: 2, skipped: 1 }`. This creates a validation record linked to the implementation. Recording it as ''fail'' (C) is too harsh — partial acknowledges progress. Waiting to record (D) loses valuable history about the initial state. Test failures aren''t production incidents (E) unless they indicate a production problem.'
+    section: para-301
+  - id: plsat-035
+    scenario: |-
+      A context check returns the following:
+
+      ```
+      Context usage: ~82%
+      Recommendation: prepare-handoff
+      Message: Context getting full. Complete current task and prepare handoff.
+      ```
+
+      You're in the middle of implementing a feature that's about 70% done.
+    question: What is the correct course of action?
+    choices:
+      A: Ignore the warning and finish the feature — 82% means you still have 18% left
+      B: Stop immediately and call `paradigm_handoff_prepare` with what you've done so far
+      C: Finish the current task as quickly as possible, then call `paradigm_handoff_prepare` with a summary, modified files, and next steps
+      D: Delete some earlier context by running `paradigm_session_recover` to free up space
+      E: Switch to a different, smaller task that can be completed in the remaining context
+    correct: C
+    explanation: 'At 82% with a ''prepare-handoff'' recommendation, you should complete your current task (not start new ones) and then hand off. The protocol says: when context usage is high but not critical (>85%), prioritize completing the current task, then prepare a handoff. `paradigm_handoff_prepare` takes your summary, modified files, symbols touched, and next steps — giving the next session everything it needs to pick up where you left off. Ignoring it (A) risks running out of context mid-task. Stopping immediately (B) wastes the 70% progress. You can''t delete context (D).'
+    section: para-301
+  - id: plsat-036
+    scenario: You want to understand the complete structure of the authentication module without reading every file. The project has 200+ files across nested directories.
+    question: What is the MOST token-efficient way to explore this?
+    choices:
+      A: Read every file in `src/auth/` one by one
+      B: 'Call `paradigm_navigate({ intent: ''explore'', target: ''auth'' })` to browse the area'
+      C: 'Run `paradigm_search({ query: ''auth'' })` and read every matching file'
+      D: Read `.paradigm/navigator.yaml` and then every file it references
+      E: Call `paradigm_status` and hope it includes auth module details
+    correct: B
+    explanation: '`paradigm_navigate` with intent ''explore'' is designed for exactly this: browsing an area of the codebase without reading individual files. At ~200 tokens per call, it''s vastly more efficient than reading files (~500-2000 tokens each). It returns the structural overview of the auth area — components, gates, flows, signals — from the indexed symbols. If you need specific implementation details AFTER exploring, then you read individual files. The rule is: MCP for discovery, files for implementation.'
+    section: para-301
+  - id: plsat-037
+    scenario: You're debugging an issue where the `$order-fulfillment` flow is failing at the 'ship order' step. The flow has 6 steps spanning 4 components. You suspect the gate `^warehouse-authorized` is rejecting valid requests.
+    question: Which combination of tools gives you the MOST diagnostic information?
+    choices:
+      A: '`paradigm_flow_check({ flowId: ''$order-fulfillment'' })` + `paradigm_sentinel_triage({ symbol: ''^warehouse-authorized'' })`'
+      B: '`paradigm_search({ query: ''warehouse'' })` + read all matching files'
+      C: '`paradigm_ripple({ symbol: ''$order-fulfillment'' })` only'
+      D: '`paradigm_history_context({ symbols: [''$order-fulfillment''] })` only'
+      E: '`paradigm_navigate({ intent: ''find'', target: ''^warehouse-authorized'' })` + read the gate code'
+    correct: A
+    explanation: 'The best combination is: (1) `paradigm_flow_check` checks the flow definition against the codebase — are all steps implemented, do the gates exist, are signals emitted? This could reveal if the flow definition is out of sync with the code. (2) `paradigm_sentinel_triage` filtered by `^warehouse-authorized` shows if there are incidents or known patterns for this gate failing. Together, these give you structural validation AND operational history. Ripple (C) shows dependencies but not failures. History (D) shows changes but not current errors.'
+    section: para-301
+  - id: plsat-038
+    scenario: 'Your team has been using Paradigm for 6 months. A new developer joins and asks: ''How do I know if the Paradigm files are actually accurate? What if the code has drifted from the documentation?'''
+    question: What is the correct answer?
+    choices:
+      A: Trust the Paradigm files — they're always accurate because they're machine-generated
+      B: Run `paradigm doctor` to validate consistency between Paradigm files and the codebase, and check `paradigm_aspect_check` for aspect anchor drift
+      C: Paradigm files are aspirational — they describe what the code SHOULD be, not what it IS
+      D: Run `paradigm scan` to regenerate all Paradigm files from scratch
+      E: Check the git blame on `.purpose` files to see when they were last updated
+    correct: B
+    explanation: '`paradigm doctor` is the validation tool that checks for inconsistencies between Paradigm files and the codebase. It flags missing anchors, undefined symbols referenced in flows, gates referenced in portal.yaml that don''t have implementations, and more. `paradigm_aspect_check` specifically validates that aspect anchors still point to valid code. `paradigm_purpose_validate` checks `.purpose` file structural validity. These tools are how you verify accuracy. Paradigm files are NOT auto-generated (A) or aspirational (C) — they''re maintained documentation that has validation tools.'
+    section: para-301
+  - id: plsat-039
+    scenario: 'You need to build a complete user profile feature: a UI component, API endpoint, database service, validation logic, and tests. This will touch at least 6 files across 3 directories.'
+    question: Before writing ANY code, what should you do FIRST?
+    choices:
+      A: Start coding the UI component — start with the frontend and work backwards
+      B: 'Call `paradigm_orchestrate_inline({ task: ''Build user profile feature'', mode: ''plan'' })` to get the right agents and plan'
+      C: Call `paradigm_search` for existing profile-related symbols
+      D: Create the `.purpose` file first to define all the symbols
+      E: Call `paradigm_ripple` on every component you plan to create
+    correct: B
+    explanation: 'When a task affects 3+ files, involves multiple features, or spans security and implementation, the FIRST step is calling `paradigm_orchestrate_inline` with mode=''plan''. This returns: the right agent team (e.g., architect + security + builder + tester), estimated token cost, and an execution plan with stages. This prevents you from wasting tokens on ad-hoc implementation when a structured approach would be more efficient. After the plan, you''d call with mode=''execute'' to get full agent prompts. You can''t ripple (E) symbols that don''t exist yet.'
+    section: para-401
+  - id: plsat-040
+    scenario: |-
+      You call `paradigm_orchestrate_inline` with mode='plan' for a task involving JWT authentication. The plan returns four agents: architect, security, builder, tester. The plan shows two stages:
+
+      ```
+      Stage 1: [architect, security] (canRunParallel: true)
+      Stage 2: [builder, tester] (canRunParallel: false)
+      ```
+    question: How should you execute this plan?
+    choices:
+      A: Run all four agents simultaneously for maximum speed
+      B: Run architect and security in parallel, wait for both to complete, then run builder, then tester sequentially
+      C: Run architect first, then security, then builder, then tester — always sequential
+      D: Skip the architect and security agents — just run builder and tester
+      E: Run builder first to get code written, then architect and security for review
+    correct: B
+    explanation: 'The orchestration plan explicitly marks `canRunParallel: true` for Stage 1 (architect + security), meaning they can run simultaneously. Stage 2 has `canRunParallel: false`, meaning builder must complete before tester starts. The correct execution is: launch architect and security in parallel (Stage 1), wait for both to finish, run builder with handoff context from Stage 1, then run tester after builder completes. Skipping agents (D) defeats the purpose of orchestration. Running builder first (E) ignores architecture and security design.'
+    section: para-401
+  - id: plsat-041
+    scenario: |-
+      Your team is evaluating which agent provider to use for orchestration. The environment has:
+      - `ANTHROPIC_API_KEY` set
+      - Claude Code installed (Max subscription)
+      - Cursor IDE open
+      - No `.paradigm/config.yaml` provider override
+
+      The team runs `paradigm team providers`.
+    question: Which provider will be used by default based on the cascade?
+    choices:
+      A: Cursor agent CLI — because Cursor IDE is detected
+      B: Claude Code Task tool — because Max subscription is available
+      C: Anthropic API (claude) — because it's first in the cascade and the API key is set
+      D: Manual file-based handoffs — because no provider is explicitly configured
+      E: Claude Code Agent Teams — because it supports parallel execution
+    correct: C
+    explanation: 'The provider cascade tries providers in order: (1) claude (Anthropic API), (2) claude-code-teams, (3) claude-code, (4) cursor-cli, (5) claude-cli, (6) manual. Since `ANTHROPIC_API_KEY` is set, the first provider (`claude` — Anthropic API) is available and will be used. The cascade stops at the first available provider unless overridden. Even though Cursor and Claude Code are available, they''re lower priority. To override, use `paradigm team providers --set cursor-cli` or set `agent-provider` in config.'
+    section: para-401
+  - id: plsat-042
+    scenario: |-
+      You're configuring agent models for your team. The task involves:
+      - An architectural review (complex reasoning needed)
+      - A security audit (critical, needs thoroughness)
+      - Building 3 UI components (straightforward implementation)
+      - Writing unit tests (repetitive, pattern-based)
+
+      Your budget is limited.
+    question: Which model assignment follows Paradigm's recommended configuration?
+    choices:
+      A: All agents use opus for maximum quality
+      B: 'Architect: opus, Security: opus, Builder: haiku, Tester: haiku'
+      C: All agents use haiku for cost efficiency
+      D: 'Architect: sonnet, Security: sonnet, Builder: sonnet, Tester: sonnet'
+      E: 'Architect: opus, Security: sonnet, Builder: opus, Tester: haiku'
+    correct: B
+    explanation: 'Paradigm''s recommended model configuration is: architect and security agents use opus (complex reasoning, critical decisions), builder uses haiku (fast, cost-effective for straightforward implementation), and tester uses haiku (pattern-based, repetitive work). The reviewer role (not in this scenario) uses sonnet (balanced critique). This balances quality where it matters most (architecture, security) with cost efficiency where tasks are more mechanical (building, testing). All-opus (A) blows the budget. All-haiku (C) risks poor architectural decisions.'
+    section: para-401
+  - id: plsat-043
+    scenario: |-
+      You're about to call an MCP tool. Your choices are:
+      1. `paradigm_status` (~100 tokens)
+      2. `paradigm_navigate` (~200 tokens)
+      3. Reading a 400-line TypeScript file (~2000 tokens)
+      4. `paradigm_ripple` (~300 tokens)
+
+      You need to understand what components exist in the payments area before modifying `#payment-service`.
+    question: What is the MOST token-efficient approach?
+    choices:
+      A: Read the TypeScript file directly — you need to see the actual code
+      B: Call `paradigm_navigate` to explore the payments area, then `paradigm_ripple` on `#payment-service`, then read only the specific file you need to change
+      C: Call `paradigm_status` first, then read all payment-related files
+      D: Call all four tools to be thorough
+      E: Skip all tools and just start coding — you'll figure it out
+    correct: B
+    explanation: 'The optimal approach is: (1) `paradigm_navigate` (~200 tokens) to discover what exists in the payments area without reading files. (2) `paradigm_ripple` (~300 tokens) on `#payment-service` to understand impact before modifying. (3) THEN read the specific file you need to change. Total: ~500 tokens + one targeted file read. This follows the rule: ''MCP for discovery, files for implementation.'' Reading files first (A) costs ~2000 tokens before you even know what you''re looking at. Calling everything (D) wastes `paradigm_status` tokens on info you don''t need for this task.'
+    section: para-401
+  - id: plsat-044
+    scenario: Your team decides that all API responses should include a `requestId` header for tracing. This is an architectural decision that affects every API endpoint in the project.
+    question: How should this decision be recorded in Paradigm?
+    choices:
+      A: Add a comment in every API route file
+      B: Call `paradigm_decision_record` with title, rationale, participants, and alternatives_considered — the decision lives in `.paradigm/decisions/` and writes a companion lore `insight` automatically
+      C: Create a `~request-id-required` aspect and add it to every component
+      D: Update `.paradigm/config.yaml` with a new convention
+      E: Both B and C — record the decision AND create an aspect with code anchors
+    correct: E
+    explanation: 'The most complete answer is both. (1) Record the architectural decision with `paradigm_decision_record` including title, decision text, rationale (tracing, debugging, support requirements), participants with stances, and alternatives_considered (response body field rejected_because clients prefer headers). The decision is stored in `.paradigm/decisions/` and a companion lore `insight` is auto-written so the timeline shows the moment the choice was made. (2) Create `~request-id-required` aspect with anchors pointing to the middleware that adds the header. The decision documents the WHY, the aspect enforces the WHAT with verifiable code anchors. Just the decision (B) lacks enforcement. Just the aspect (C) lacks rationale.'
+    section: para-401
+  - id: plsat-045
+    scenario: |-
+      You're writing a commit message for a change that added rate limiting to the payment API, modified the Stripe webhook handler, and added a new `!rate-limit-exceeded` signal.
+
+      The affected symbols are: `#payment-api`, `#stripe-webhook-handler`, `~rate-limited`, `!rate-limit-exceeded`.
+    question: Which commit message follows Paradigm conventions?
+    choices:
+      A: |-
+        ```
+        feat: add rate limiting to payments
+        ```
+      B: |-
+        ```
+        feat(#payment-api): add rate limiting to payment endpoints
+
+        - Apply ~rate-limited aspect to #payment-api
+        - Update #stripe-webhook-handler with rate limit checks
+        - Add !rate-limit-exceeded signal for monitoring
+
+        Symbols: #payment-api, #stripe-webhook-handler, ~rate-limited, !rate-limit-exceeded
+        ```
+      C: |-
+        ```
+        feat(payments): add rate limiting
+
+        Added rate limiting to payment API and webhook handler.
+        ```
+      D: |-
+        ```
+        FEAT(#payment-api): ADD RATE LIMITING
+
+        Symbols: ALL PAYMENT SYMBOLS
+        ```
+      E: |-
+        ```
+        feat(~rate-limited): apply rate limiting aspect
+
+        - Updated payment-api
+        - Updated stripe-webhook-handler
+
+        Symbols: ~rate-limited
+        ```
+    correct: B
+    explanation: 'Choice B follows all Paradigm commit conventions: (1) Subject line: `type(#primary-symbol): description` with the primary affected component. (2) Body: references all affected symbols with their prefixes (#, ~, !). (3) `Symbols:` trailer: machine-readable list of ALL affected symbols for the post-commit hook to parse. Choice A lacks symbols entirely. Choice C uses a generic scope instead of a symbol. Choice D is SCREAMING_CASE (no). Choice E uses the aspect as the primary symbol, but the primary change is to `#payment-api`, and the Symbols trailer is incomplete.'
+    section: para-401
+  - id: plsat-046
+    scenario: 'A developer on your team proposes a new tag: `[webhook-handler]`. They''ve noticed 5 components across the project that handle incoming webhooks and think a dedicated tag would be useful for classification.'
+    question: What is the correct process for adding this tag?
+    choices:
+      A: Add it directly to the `core` section of `tags.yaml`
+      B: Add it directly to the `project` section of `tags.yaml`
+      C: Call `paradigm_tags_suggest` with the tag name, description, reason, and example symbols — it goes to `suggested` for human approval
+      D: 'Just start using `tags: [webhook-handler]` on components — tags are freeform'
+      E: Create a new aspect `~webhook-handler` instead — tags aren't for this
+    correct: C
+    explanation: 'The proper process is `paradigm_tags_suggest`, which adds the tag to the `suggested` section of `tags.yaml` for human review. This is Paradigm''s governance model: AI can propose tags, but humans must approve them before they become official. Once approved, a human promotes it to `project` (team-specific) or `core` (if it should ship with Paradigm). Adding directly to `core` (A) is only for Paradigm framework maintainers. Freeform usage (D) leads to tag sprawl. An aspect (E) is wrong because webhook handling isn''t a cross-cutting rule requiring code anchors.'
+    section: para-401
+  - id: plsat-047
+    scenario: |-
+      Your CI/CD pipeline runs `paradigm doctor` as a check. The latest run shows:
+
+      ```
+      ERROR: Gate ^project-owner referenced in portal.yaml but not defined
+      WARNING: Aspect ~cache-invalidation has stale anchors (file moved)
+      ERROR: Flow $signup-flow references undefined component #sms-verifier
+      INFO: 3 suggested tags awaiting human review
+      ```
+    question: Which issues MUST be fixed before merging, and which can wait?
+    choices:
+      A: All four must be fixed — `paradigm doctor` errors should block the merge
+      B: The two ERRORs must be fixed (undefined gate and undefined component). The WARNING and INFO can wait.
+      C: Only the gate error must be fixed (security). Everything else is documentation.
+      D: None need to block the merge — `paradigm doctor` is advisory only
+      E: The errors and warning must be fixed. Only the INFO about suggested tags can wait.
+    correct: B
+    explanation: 'ERRORs indicate broken references that will cause real problems: a gate referenced in `portal.yaml` that doesn''t exist means route protection is undefined, and a flow referencing an undefined component means the flow documentation is actively misleading. These MUST be fixed. The WARNING about stale anchors is important but not merge-blocking — the aspect still works, the documentation just needs updating. The INFO about suggested tags is purely administrative. In practice, many teams also fix WARNINGs before merge, but the ERRORs are the must-fix items.'
+    section: para-401
+  - id: plsat-048
+    scenario: You're preparing a handoff because your context window is at 87%. You've been working on a migration from REST to GraphQL for the user module. You've completed the schema and resolvers but haven't written tests yet.
+    question: What information should you include in `paradigm_handoff_prepare`?
+    choices:
+      A: Just the summary — the next session can figure out the rest
+      B: Summary, list of modified files, symbols touched, next steps (write tests), and the open question about whether to keep the REST endpoints during migration
+      C: A complete transcript of everything you did in this session
+      D: Only the list of modified files — the next session can read them
+      E: Summary and next steps only — modified files are in git
+    correct: B
+    explanation: '`paradigm_handoff_prepare` accepts: summary (what was done), modifiedFiles (what changed), symbolsTouched (which symbols were affected), nextSteps (what to do next), and openQuestions (unresolved decisions). The MOST useful handoff includes ALL of these. The next session needs to know: (1) what was accomplished (summary), (2) which files to look at (modifiedFiles), (3) which symbols are in play (symbolsTouched), (4) exactly what to do next (write tests), and (5) any decisions that still need to be made (keep REST endpoints?). A transcript (C) is too much. Just files (D) lacks context.'
+    section: para-401
+  - id: plsat-049
+    scenario: You want to validate that a specific flow `$checkout-flow` is correctly implemented. The flow has 5 steps, involves 3 gates, and emits 2 signals. You want to verify that all steps have implementations, gates exist in portal.yaml, and signals are actually emitted in the code.
+    question: Which MCP tool call gives you this deep implementation check?
+    choices:
+      A: '`paradigm_flow_check({ flowId: ''$checkout-flow'' })` — validates flow definition only'
+      B: '`paradigm_flow_check({ flowId: ''$checkout-flow'', checkImplementation: true })` — deep check against codebase'
+      C: '`paradigm_purpose_validate()` — validates all purpose files including flows'
+      D: '`paradigm_ripple({ symbol: ''$checkout-flow'' })` — shows flow dependencies'
+      E: '`paradigm_related({ symbol: ''$checkout-flow'' })` — shows what''s connected to the flow'
+    correct: B
+    explanation: '`paradigm_flow_check` with `checkImplementation: true` performs a deep validation: it checks that gates exist in portal.yaml, actions are implemented in the codebase, and signals are emitted. Without `checkImplementation`, it only validates the YAML structure (A). `paradigm_purpose_validate` (C) checks structural validity of purpose files but doesn''t do the deep codebase cross-reference. `paradigm_ripple` (D) shows what depends on the flow, not whether it''s correctly implemented. The `checkImplementation` flag is the key to going from structural validation to implementation verification.'
+    section: para-401
+  - id: plsat-050
+    scenario: |-
+      It's 2 AM. Your production system is down. The error logs show:
+
+      ```
+      ERROR: Cannot read property 'id' of null
+        at PaymentProcessor.processRefund (payment-processor.ts:142)
+        at RefundHandler.handle (refund-handler.ts:67)
+      ```
+
+      You need to investigate and fix this as fast as possible using Paradigm tools. The on-call engineer has no context about the payment system.
+    question: What is the optimal 2 AM sequence of actions using Paradigm?
+    choices:
+      A: Read the source files, find the bug, fix it, deploy
+      B: '`paradigm_sentinel_record` the incident → `paradigm_sentinel_patterns` for known fixes → `paradigm_wisdom_context` for `#payment-processor` antipatterns → Fix → `paradigm_sentinel_resolve`'
+      C: '`paradigm_orchestrate_inline` to spin up an architect and security agent'
+      D: '`paradigm_status` → `paradigm_navigate` → Read every file in payments/ → Eventually find the bug'
+      E: '`paradigm_ripple` on `#payment-processor` → Fix everything that depends on it'
+    correct: B
+    explanation: 'At 2 AM with production down, you want the fastest path to resolution with full traceability: (1) `paradigm_sentinel_record` the incident with the error and stack trace — this starts the clock and provides symbolic context. (2) `paradigm_sentinel_patterns` to check if this is a KNOWN failure pattern with an existing resolution — this could save you hours. (3) `paradigm_wisdom_context` for `#payment-processor` to check if there are recorded antipatterns (e.g., ''null check required before accessing refund.id''). (4) Fix the issue with full context. (5) `paradigm_sentinel_resolve` to close the incident with the fix commit. Orchestration (C) is overkill for an emergency fix. Reading everything (D) burns time you don''t have.'
+    section: para-401