@a-company/paradigm 5.38.0 → 6.0.4

package/dist/university-content/quizzes/Q-para-701-model-tier-resolution.yaml

@@ -0,0 +1,66 @@
+id: Q-para-701-model-tier-resolution
+title: 'PARA 701: Agent Mastery — Lesson 6: Model Tier Resolution'
+description: 'Quiz for lesson: Lesson 6: Model Tier Resolution'
+author: paradigm
+created: '2026-04-22'
+updated: '2026-04-22'
+tags:
+  - course
+  - para-701
+symbols: []
+difficulty: beginner
+passThreshold: 0.7
+category: paradigm-core
+origin: imported
+source: courses/para-701.json
+questions:
+  - id: q1
+    question: A team wants to reduce costs by running all agents on the same model. What is the simplest configuration change?
+    choices:
+      A: Edit every .agent file to change modelTier to tier-3
+      B: 'Map all three tiers to the same model in the model-resolution config block: `tier-1: claude-sonnet-4-6`, `tier-2: claude-sonnet-4-6`, `tier-3: claude-sonnet-4-6`'
+      C: Remove the model-resolution block entirely
+      D: 'Set a global `maxTier: tier-3` flag in config.yaml'
+      E: Deactivate all tier-1 agents from the roster
+    correct: B
+    explanation: The model-resolution block is the single control point. Mapping all three tiers to `claude-sonnet-4-6` means every agent — regardless of what tier they request — runs on Sonnet. This is a 3-line change in `.paradigm/config.yaml`. The agents still have different personalities, expertise, and behaviors; only the underlying model changes. Option A would work but requires editing dozens of files. Option E would lose important agents like architect and security.
+  - id: q2
+    question: 'An agent profile has `modelTier: tier-1`. The project config maps `tier-1: claude-sonnet-4-6`. The global config maps `tier-1: claude-opus-4-6`. Which model is used?'
+    choices:
+      A: claude-opus-4-6 — global config takes precedence
+      B: claude-sonnet-4-6 — project config overrides global config in the resolution cascade
+      C: The agent's defaultModel field is used instead
+      D: An error is thrown because of conflicting configurations
+      E: The IDE detection result is used
+    correct: B
+    explanation: 'The resolution cascade is: agent profile (determines tier) > project config > global config > IDE detection > fallback. The agent requests tier-1. The project config maps tier-1 to `claude-sonnet-4-6`. The project config has higher priority than global config, so Sonnet is used. This allows a project to override the user''s global preference — useful when a project has a budget constraint that the user''s default does not account for.'
+  - id: q3
+    question: Why does the security agent default to tier-1 (reasoning) while the builder defaults to tier-3 (fast)?
+    choices:
+      A: The security agent costs more to run
+      B: The builder handles more requests and needs to be faster
+      C: Security work requires deep reasoning (vulnerability analysis, threat modeling) that benefits from the most capable model, while builder work is more mechanical (implement a spec, write code to match a design) where speed matters more than reasoning depth
+      D: Tier-1 agents have access to more MCP tools
+      E: It is an arbitrary default with no rationale
+    correct: C
+    explanation: 'Tier assignments reflect the cognitive demands of each role. Security analysis involves complex reasoning: evaluating attack surfaces, identifying subtle vulnerabilities, understanding interaction effects between auth mechanisms. This benefits from a model with stronger reasoning capabilities (tier-1). Builder work is typically more structured: implement this API endpoint per the spec, add this component per the design. The spec defines what to build; the model executes. Speed and cost efficiency (tier-3) matter more than reasoning depth.'
+  - id: q4
+    question: A user is running Paradigm in Cursor (detected via CURSOR_SESSION environment variable). What tier-1 model does auto-detection assign, and why?
+    choices:
+      A: claude-opus-4-6 — always use the best available model
+      B: claude-sonnet-4-6 — because Opus may not be available in Cursor's model selection, so the detection gracefully degrades tier-1 to the best confirmed-available model
+      C: gpt-4o — Cursor defaults to OpenAI
+      D: The user must manually configure it — Cursor is not auto-detected
+      E: claude-haiku-4-5 — Cursor uses cheaper models by default
+    correct: B
+    explanation: 'The `detectEnvironment()` function checks for `process.env.CURSOR_SESSION`. When detected, it assigns `claude-sonnet-4-6` for tier-1 because Cursor may not expose Opus in its model selection. Assigning Opus would cause orchestration failures if the model is unavailable. The detection gracefully degrades: Claude Code gets the full tier spread, Cursor gets Sonnet as the ceiling. The user can override this in their config if they do have Opus access.'
+  - id: q5
+    question: 'An old agent profile has `defaultModel: opus` but no `modelTier` field. How does the system handle this?'
+    choices:
+      A: An error is thrown — modelTier is required
+      B: The agent runs with no model preference (fallback to tier-2)
+      C: 'The system maps defaultModel to a tier: opus maps to tier-1, which is then resolved through the model-resolution config like any other tier request'
+      D: The agent is excluded from orchestration until its profile is updated
+      E: The defaultModel value is passed directly to the API as the model name
+    correct: C
+    explanation: 'Backward compatibility is handled by mapping old model names to tiers: `opus` to `tier-1`, `sonnet` to `tier-2`, `haiku` to `tier-3`. The resolution logic checks `modelTier` first; if absent, it reads `defaultModel` and maps it. The resulting tier is then resolved through the normal cascade (project config > global config > IDE detection > fallback). This means existing agent profiles continue working without any modification.'

package/dist/university-content/quizzes/Q-para-701-orchestration-enforcement.yaml

@@ -0,0 +1,66 @@
+id: Q-para-701-orchestration-enforcement
+title: 'PARA 701: Agent Mastery — Lesson 7: Orchestration Enforcement'
+description: 'Quiz for lesson: Lesson 7: Orchestration Enforcement'
+author: paradigm
+created: '2026-04-22'
+updated: '2026-04-22'
+tags:
+  - course
+  - para-701
+symbols: []
+difficulty: beginner
+passThreshold: 0.7
+category: paradigm-core
+origin: imported
+source: courses/para-701.json
+questions:
+  - id: q1
+    question: A developer implements a 5-file feature without calling paradigm_orchestrate_inline. What happens?
+    choices:
+      A: The session is blocked and the developer must orchestrate before proceeding
+      B: At preflight, the `orchestration-required` habit emits a warning suggesting orchestration. At postflight, `agent-coverage-validated` advises reviewing paradigm_ambient_nominations for any self-nominated contributions.
+      C: Nothing — orchestration is entirely optional with no enforcement
+      D: The commit is rejected by the pre-commit hook
+      E: All modified files are automatically reverted
+    correct: B
+    explanation: Orchestration enforcement uses `warn` and `advisory` severities, not `block`. The developer receives a warning at preflight ("Consider calling paradigm_orchestrate_inline") and an advisory at postflight ("Check paradigm_ambient_nominations for pending contributions"). The work is not blocked because the severity is `warn`, not `block`. However, the developer is informed that agents may have had relevant contributions, and the security agent may have self-nominated a gate review that was never seen.
+  - id: q2
+    question: Why is orchestration enforcement implemented as habits rather than hardcoded into the orchestrator?
+    choices:
+      A: Habits are faster to evaluate than hardcoded checks
+      B: The orchestrator cannot access the habit system
+      C: Habits are configurable (enable/disable), tunable (warn/block/advisory), extensible (custom habits), and transparent (declared in YAML) — hardcoded enforcement would be rigid and impossible to customize per project
+      D: Hardcoded enforcement would require a database connection
+      E: Habits are only evaluated once per day, reducing overhead
+    correct: C
+    explanation: 'The habit system provides four advantages over hardcoded enforcement: (1) Configurable — a project can disable `orchestration-required` by setting `enabled: false`. (2) Tunable — severity can be changed from `warn` to `block` for strict enforcement or `advisory` for a softer touch. (3) Extensible — teams can add custom habits (e.g., require security review for any `auth/**` changes). (4) Transparent — habits are declared in YAML and evaluated at predictable trigger points. Hardcoded logic would be a black box that every project lives with regardless of their needs.'
+  - id: q3
+    question: Production is down. A developer needs to push a hot fix immediately. How does orchestration enforcement handle this?
+    choices:
+      A: The developer must still orchestrate — there are no exceptions
+      B: The `hot-mode-incident` habit acknowledges incidents by waiving orchestration enforcement and only requiring a post-incident lore entry
+      C: The developer must manually disable all three habits before proceeding
+      D: The system detects production incidents automatically and suspends all enforcement
+      E: Orchestration enforcement does not apply to hot fixes by default because all severities are `warn` or `advisory`
+    correct: B
+    explanation: 'The `hot-mode-incident` habit is designed for this exact scenario. It fires at on-stop (session end) with `advisory` severity and only checks that a lore entry was recorded (`check: { type: ''lore-recorded'' }`). The rationale: during incidents, you fix first and document later. The lore entry requirement ensures the learning loop captures the incident for future prevention. The other two habits (`orchestration-required` at `warn`, `agent-coverage-validated` at `advisory`) do not block, so the hot fix proceeds with only advisories.'
+  - id: q4
+    question: A team wants to strictly require orchestration for all tasks. How do they configure this?
+    choices:
+      A: Edit the orchestrator source code to block unorchestrated tasks
+      B: Change the `orchestration-required` habit's severity from `warn` to `block` in their project's habit overrides
+      C: Add a pre-commit hook that checks for orchestration
+      D: 'Set `orchestration: mandatory` in config.yaml'
+      E: Remove all agents from the roster except the orchestrator
+    correct: B
+    explanation: 'Habit severity is tunable per project. Changing `orchestration-required` from `warn` to `block` in the project''s habits override means the habit will block session completion if `paradigm_orchestrate_inline` was not called. This is the designed customization path: the seed habit provides a sensible default (`warn`), and projects can upgrade to `block` if they need strict enforcement. No source code modification is needed.'
+  - id: q5
+    question: The `agent-coverage-validated` habit checks for which tools in its evaluation?
+    choices:
+      A: paradigm_orchestrate_inline only
+      B: paradigm_ambient_nominations and paradigm_agent_list — it verifies that agent contributions were reviewed, not just that orchestration was invoked
+      C: paradigm_reindex and paradigm_purpose_validate
+      D: paradigm_ripple and paradigm_search
+      E: All MCP tools — it checks that at least one was called
+    correct: B
+    explanation: 'The `agent-coverage-validated` habit''s check is `{ type: ''tool-called'', params: { tools: [''paradigm_ambient_nominations'', ''paradigm_agent_list''] } }`. It verifies that agent contributions were reviewed — either by checking ambient nominations or listing agents. This is distinct from `orchestration-required` which checks for `paradigm_orchestrate_inline`. The two habits complement each other: one ensures orchestration was considered (preflight), the other ensures agent contributions were reviewed (postflight).'

package/dist/university-content/quizzes/Q-para-701-per-project-rosters.yaml

@@ -0,0 +1,66 @@
+id: Q-para-701-per-project-rosters
+title: 'PARA 701: Agent Mastery — Lesson 5: Per-Project Rosters'
+description: 'Quiz for lesson: Lesson 5: Per-Project Rosters'
+author: paradigm
+created: '2026-04-22'
+updated: '2026-04-22'
+tags:
+  - course
+  - para-701
+symbols: []
+difficulty: beginner
+passThreshold: 0.7
+category: paradigm-core
+origin: imported
+source: courses/para-701.json
+questions:
+  - id: q1
+    question: A developer runs `paradigm agents deactivate gamedev 3d audio` on their SaaS project. What happens to these agents globally?
+    choices:
+      A: Their .agent files are deleted from ~/.paradigm/agents/
+      B: 'Their .agent files get `benched: true` added'
+      C: Nothing — the command only removes them from this project's roster.yaml. They remain fully available globally and on other projects.
+      D: Their expertise scores are reset to 0
+      E: They are moved to a .paradigm/deactivated/ directory
+    correct: C
+    explanation: 'Roster commands modify `.paradigm/roster.yaml` and nothing else. The global .agent files at `~/.paradigm/agents/` are never touched by roster operations. Deactivating gamedev on a SaaS project removes it from that project''s `active` list. The gamedev agent remains fully intact globally and would appear in the roster of a game project. This is the key architectural decision: rosters are project-level filters over global agents.'
+  - id: q2
+    question: A project has no roster.yaml file. A developer runs `paradigm_orchestrate_inline` on a task. How many agents does the orchestrator consider?
+    choices:
+      A: None — a roster is required for orchestration
+      B: 8 — the generic default roster
+      C: All global agents — no roster means no filtering (backward compatibility)
+      D: Only the architect and builder — the minimum required
+      E: The orchestrator prompts for roster creation before proceeding
+    correct: C
+    explanation: '`loadProjectRoster()` returns `null` if no roster.yaml exists. `isAgentActive()` returns `true` for all agents when the roster is null. The orchestrator''s `getActiveAgents()` function falls back to listing all global agents. This is the backward compatibility guarantee: projects that predate the roster feature continue working exactly as before. All 54 agents are considered during planning.'
+  - id: q3
+    question: The project type detection finds both `supabase/` and `next.config.ts` in the project root. What project type is detected and what does the suggested roster include?
+    choices:
+      A: backend-api — Supabase indicates a database-heavy project
+      B: web-app — Next.js indicates a web application
+      C: saas-web-app — the combination of Supabase + Next.js triggers this type, which suggests ~24 agents including designer, dba, seo, sales, and legal
+      D: generic — mixed signals default to generic
+      E: fullstack-app — a dedicated type for Supabase + Next.js
+    correct: C
+    explanation: 'The detection logic checks `signals.hasSupabase && signals.hasNextConfig` early in the chain and returns `saas-web-app`. This type gets the largest suggested roster (~24 agents) because a SaaS web app typically needs the full spectrum: frontend (designer, a11y), backend (dba, devops), content (copywriter, seo), quality (tester, e2e, qa), business (pm, product, sales), and compliance (legal, security). The Supabase + Next.js combination is a strong signal for this project type.'
+  - id: q4
+    question: Why does the `generic` project type suggest only 8 agents instead of 20+?
+    choices:
+      A: Generic projects are considered less important
+      B: 8 agents is the minimum the orchestrator can work with
+      C: When the project type is ambiguous, a minimal roster avoids activating specialists that may be irrelevant — the developer can add more as needed
+      D: Generic projects cannot use more than 8 agents due to a technical limitation
+      E: The 8 agents are free tier; additional agents require a paid plan
+    correct: C
+    explanation: 'The generic roster includes architect, builder, reviewer, tester, security, documentor, debugger, and qa — the universal quality baseline. When the system cannot detect the project type, it avoids false positives: activating a designer on a CLI tool or a DBA on a static site would add noise. The developer knows their project better than the detection heuristic, so a minimal starting point with easy expansion (`paradigm agents activate designer`) is better than an over-eager default.'
+  - id: q5
+    question: A developer activates the designer on a project, does some UI work with Mika, then deactivates the designer. Later, they reactivate the designer. Does Mika remember the previous UI work on this project?
+    choices:
+      A: No — deactivating an agent deletes its state
+      B: Yes — roster changes only affect the active list in roster.yaml. The agent's project state (.paradigm/agent-state/designer.yaml), notebooks, and expertise are untouched by deactivation.
+      C: Partially — state is preserved but expertise resets
+      D: Only if the deactivation was less than 24 hours ago
+      E: The developer must run paradigm_session_recover to restore state
+    correct: B
+    explanation: Roster deactivation removes the agent from the `active` list in roster.yaml — that is all it does. The agent's project state at `.paradigm/agent-state/designer.yaml` remains on disk. Its notebooks at `.paradigm/notebooks/designer/` remain. Its expertise in the `.agent` file remains. When reactivated, `buildProfileEnrichment()` loads the existing project state and the agent sees its last session summary, pending work, and learned patterns. Rosters are a visibility filter, not a state manager.

package/dist/university-content/quizzes/Q-para-701-symphony-visibility.yaml

@@ -0,0 +1,66 @@
+id: Q-para-701-symphony-visibility
+title: 'PARA 701: Agent Mastery — Lesson 8: Live Visibility via Symphony'
+description: 'Quiz for lesson: Lesson 8: Live Visibility via Symphony'
+author: paradigm
+created: '2026-04-22'
+updated: '2026-04-22'
+tags:
+  - course
+  - para-701
+symbols: []
+difficulty: beginner
+passThreshold: 0.7
+category: paradigm-core
+origin: imported
+source: courses/para-701.json
+questions:
+  - id: q1
+    question: An orchestration plan includes architect, security, builder, and documentor. The human watches the Conductor overlay. In what order do notes typically appear?
+    choices:
+      A: Alphabetically by agent name
+      B: Randomly — agents run in parallel with no ordering
+      C: 'Chronologically based on orchestration stages: architect plans first, builder implements, security reviews, documentor updates last — matching the staged execution order'
+      D: All notes appear simultaneously when orchestration completes
+      E: Fastest agent first, slowest last
+    correct: C
+    explanation: 'The orchestrator executes agents in staged dependency order: the architect plans first (stage 1), the builder implements based on the plan (stage 2), the security agent reviews the implementation (stage 3), and the documentor updates .purpose files last (final stage). Notes are posted chronologically as each stage completes, so the Conductor shows a natural progression of planning, implementation, review, and documentation.'
+  - id: q2
+    question: NoteRelay polls at 5-second intervals and SymphonyThreadWatcher at 3-second intervals. What is the worst-case latency from an agent posting a note to it appearing in the Conductor?
+    choices:
+      A: Exactly 5 seconds — NoteRelay is the bottleneck
+      B: Exactly 3 seconds — ThreadWatcher is the bottleneck
+      C: Up to ~8 seconds in the worst case (5s NoteRelay + 3s ThreadWatcher if both polls just missed the change)
+      D: Instant — filesystem events trigger immediate updates
+      E: 30 seconds — there is a buffer delay
+    correct: C
+    explanation: 'In the worst case, NoteRelay just polled (misses the new file by 1ms) and polls again in 5 seconds. Then SymphonyThreadWatcher just polled (misses the state update by 1ms) and polls again in 3 seconds. Total worst case: ~8 seconds. In practice, the two polls are offset and the average latency is 3-5 seconds. This is acceptable for human observation — you are watching orchestration progress, not debugging a real-time system.'
+  - id: q3
+    question: Why does the orchestrator use the `thr-orch-` prefix on thread names?
+    choices:
+      A: It is a naming convention with no functional purpose
+      B: It allows SymphonyThreadWatcher to distinguish orchestration threads from regular Symphony threads (team chat, notes) using a simple prefix filter
+      C: It enables encryption of orchestration data
+      D: It prevents other agents from reading the thread
+      E: It is required by the Symphony API
+    correct: B
+    explanation: SymphonyThreadWatcher filters threads by the `thr-orch-` prefix to separate orchestration threads from regular communication threads. Without this prefix, the Team view in Conductor would mix orchestration progress with team chat, personal notes, and other thread types. The prefix is a simple, reliable discrimination mechanism that avoids complex content parsing.
+  - id: q4
+    question: Why was polling chosen over filesystem watching (FSEvents) for the NoteRelay architecture?
+    choices:
+      A: Polling is faster than filesystem events
+      B: macOS does not support filesystem watching
+      C: FSEvents is brittle across sandboxed processes and does not work reliably when the MCP server writes files from a different process tree — polling a directory is simpler and more reliable
+      D: Filesystem watching requires root permissions
+      E: Polling uses less memory than filesystem watching
+    correct: C
+    explanation: The MCP server and the Conductor run as separate processes, potentially in different sandbox contexts. FSEvents (macOS filesystem watching) has known reliability issues when watching files written by a different process tree, especially across sandbox boundaries. Polling the `~/.paradigm/score/threads/` directory at a known interval is architecturally simpler, reliably cross-process, and introduces only 3-8 seconds of latency — an acceptable tradeoff for avoiding process-coupling complexity.
+  - id: q5
+    question: The security agent emits a finding note ('Found gate coverage gap on POST /api/payments') during orchestration. How does this note reach the TeamThreadView in Conductor?
+    choices:
+      A: The security agent sends the note directly to the Conductor via a WebSocket connection
+      B: The orchestrator posts the note to the thr-orch-{id} thread file in ~/.paradigm/score/threads/, NoteRelay detects the file change within 5 seconds, SymphonyThreadWatcher filters it as an orchestration thread within 3 seconds, and TeamThreadView renders it with the security agent's colored role badge
+      C: The note is stored in the event stream and Conductor reads events directly
+      D: The note is emailed to the developer and they manually check Conductor
+      E: The note is only visible after orchestration completes, not during execution
+    correct: B
+    explanation: 'The full pipeline is: (1) The orchestrator posts the security agent''s finding as a note in the `thr-orch-{id}` Symphony thread file. (2) NoteRelay polls `~/.paradigm/score/threads/` every 5 seconds and detects the updated thread file. (3) SymphonyThreadWatcher filters the thread by its `thr-orch-` prefix and routes it to the Team view. (4) TeamThreadView renders the note with the security agent''s colored role badge, intent indicator, and nickname. The maximum latency is ~8 seconds (5s + 3s worst case), providing near-real-time visibility during orchestration.'