@a-company/paradigm 5.38.0 → 6.0.2

package/dist/university-content/notes/N-para-701-agent-profiles.md

@@ -0,0 +1,197 @@
+---
+id: N-para-701-agent-profiles
+title: 'Lesson 2: Agent Profiles Deep Dive'
+type: note
+author: paradigm
+created: '2026-04-22'
+updated: '2026-04-22'
+tags:
+  - course
+  - para-701
+  - the-agent-file
+  - personality-style-risk
+  - collaboration-graph-defines
+symbols: []
+difficulty: beginner
+estimatedMinutes: 7
+prerequisites: []
+category: paradigm-core
+origin: imported
+source: courses/para-701.json
+---
+
+## The .agent File
+
+Every agent's identity lives in a `.agent` file stored at `~/.paradigm/agents/{id}.agent`. This is a YAML file that defines who the agent is: not just what it does, but how it thinks, who it works with, what it watches, and what it has learned. The `.agent` file is the complete specification of an agent's identity.
+
+## Core Identity Fields
+
+The top-level fields establish the agent's identity:
+
+```yaml
+id: security
+nickname: null              # Optional display name (e.g., "Jinx", "Mika")
+role: Security agent
+description: >-
+  Security specialist who audits auth flows, reviews gate implementations,
+  and hunts for vulnerabilities. He is the Portal/Gates champion.
+version: 1.0.0
+```
+
+`id` is the machine-readable identifier used in rosters, orchestration plans, and file paths. `nickname` is the optional human-friendly name displayed in attributed responses and Symphony threads (e.g., Mika for designer, Atlas for devops). `role` is a short description of the agent's function. `description` is a detailed paragraph that explains the agent's responsibilities, expertise boundaries, and what it does NOT do.
+
+The description is critically important because it is injected into the agent's prompt during orchestration. A vague description produces vague behavior. A precise description like "He flags issues but does NOT implement fixes — that's the Builder's job" creates a clear boundary.
+
+## Personality Configuration
+
+The `personality` block defines the agent's behavioral parameters:
+
+```yaml
+personality:
+  style: methodical        # How the agent approaches work
+  risk: conservative       # Risk tolerance for decisions
+  verbosity: detailed      # How much output the agent produces
+```
+
+**Style** options include `rapid` (moves fast, starts immediately), `deliberate` (thinks before acting, maps impact first), `methodical` (follows systematic processes), `analytical` (data-driven, evidence-based), `opinionated` (has strong views, will lead), `confrontational` (challenges everything), `patient` (takes time to understand context), `proactive` (anticipates needs, speaks up unprompted), `strategic` (thinks about long-term implications), and `meticulous` (leaves nothing unchecked).
+
+**Risk** values are `conservative` (prefers proven approaches, avoids experimentation), `balanced` (will take calculated risks with evidence), `moderate` (open to new approaches when justified), and `aggressive` (pushes boundaries, challenges the status quo).
+
+**Verbosity** values are `concise` (minimal output, just the essentials), `precise` (exact and specific, no filler), `detailed` (thorough explanations with context), and `thorough` (comprehensive coverage with examples and rationale).
+
+These values are not decorative. During orchestration, `buildProfileEnrichment()` injects them into the agent's prompt as `**Style:** methodical | **Risk:** conservative | **Verbosity:** detailed`. The LLM uses these parameters to calibrate its response style.
+
+## Collaboration Graph
+
+The `collaboration` block defines how the agent works with others:
+
+```yaml
+collaboration:
+  stance: advisory                   # Default relationship to other agents
+  pairs_well_with:
+    - architect: Security validates the architect's auth model and gate design
+    - devops: Atlas handles infra hardening, security handles app-layer auth
+    - builder: Security reviews builder's auth code before it ships
+  with:
+    architect:
+      stance: peer                   # Treat as equal, not subordinate
+      can_contradict: true           # Allowed to disagree with architect
+    builder:
+      stance: advisory               # Give guidance, not orders
+      review_output: true            # Review what builder produces
+  debate:
+    will_challenge: true             # Will push back on decisions
+    evidence_required: true          # Requires evidence to challenge
+    escalate_to_human: true          # Will ask the human to break ties
+  onboarding: >-
+    When joining a project, security:
+    1. Reads portal.yaml
+    2. Calls paradigm_gates_for_route on key routes
+    3. Checks Sentinel for auth-related events
+    4. Reviews auth middleware implementations
+    5. Identifies unprotected routes
+```
+
+The `stance` field defines the default relationship: `lead` (drives decisions), `advisory` (gives guidance), `support` (executes direction from leads), `peer` (equal footing), `challenger` (pushes back on everything). The `pairs_well_with` array lists productive agent pairings with explanations — these are surfaced during orchestration planning.
+
+The `debate` section controls disagreement behavior. Jinx (advocate) has `will_challenge: true` and `evidence_required: false` — she challenges instinctively. The security agent has `evidence_required: true` — it backs challenges with OWASP references and CVE data. The `onboarding` field is a step-by-step procedure the agent follows when it first encounters a project.
+
+## Expertise Tracking
+
+The `expertise` array tracks the agent's confidence on specific symbols:
+
+```yaml
+expertise:
+  - symbol: '#portal-gates'
+    confidence: 0.95            # 0.0-1.0
+    sessions: 12                # Times this agent worked on this symbol
+    lastTouch: '2026-03-24T11:30:00.000Z'
+  - symbol: '#auth-security'
+    confidence: 0.95
+    sessions: 8
+    lastTouch: '2026-03-24T11:30:00.000Z'
+```
+
+Confidence scores are not static. They adjust automatically based on user verdicts in the session work log: `+0.03` for accepted contributions, `-0.02` for dismissed ones, `-0.01` for revised ones. An agent that consistently gets security reviews accepted will see its `#auth-security` confidence rise over time. An agent whose suggestions are frequently dismissed will see confidence drop.
+
+The `sessions` count and `lastTouch` timestamp provide recency context. An agent with 50 sessions on `#payment-service` that last touched it yesterday has stronger expertise than one with 2 sessions from three months ago.
+
+## Attention Patterns
+
+The `attention` block defines what the agent notices in the event stream:
+
+```yaml
+attention:
+  symbols:
+    - ^*                      # All gate symbols
+    - '#*-auth'
+    - '#*-middleware'
+  paths:
+    - auth/**
+    - middleware/**
+  concepts:
+    - JWT
+    - RBAC
+    - injection
+    - CSRF
+  signals:
+    - type: gate-added
+    - type: route-created
+  threshold: 0.45
+```
+
+Attention patterns were covered in depth in PARA 601. The key point here is that they are part of the agent profile, not a separate system. The agent's identity (who it is) and its attention (what it notices) are defined in the same file.
+
+## Behaviors
+
+The `behaviors` block defines named behavior protocols the agent follows:
+
+```yaml
+behaviors:
+  portal-gates-mastery: >-
+    Security owns the portal.yaml gate model:
+    1. Every route that checks auth MUST have a corresponding ^gate
+    2. Use paradigm_gates_for_route to check gate coverage
+    3. Gates need prizes: [] (v2 requirement)
+  sentinel-security-monitoring: >-
+    Security uses Sentinel for threat detection:
+    - paradigm_sentinel_events to find auth failures
+    - paradigm_sentinel_patterns for security patterns
+  security-review-checklist: >-
+    Before approving auth-related code:
+    1. Check portal.yaml coverage
+    2. Verify JWT validation
+    3. Check for OWASP Top 10 vulnerabilities
+```
+
+Behaviors are injected into the agent's orchestration prompt. They are named so that other agents and humans can reference them ("use the security-review-checklist behavior"). They define step-by-step procedures that make the agent's actions predictable and auditable.
+
+## Transferable Patterns
+
+The `transferable` array contains patterns the agent has learned that apply across projects:
+
+```yaml
+transferable:
+  - pattern: gate-coverage-check
+    description: >-
+      Every new route gets paradigm_gates_for_route called on it.
+      No exceptions. If it returns no gates and the route modifies data,
+      that's a security violation.
+    successRate: 1.0
+    sessions: 0
+```
+
+Transferable patterns travel with the agent across projects. When the security agent joins a new project, it brings its `gate-coverage-check` pattern regardless of whether the previous project was a SaaS app or a CLI tool. Patterns with `successRate >= 0.7` are included in prompt enrichment; lower success rate patterns are excluded.
+
+## How Profiles Define WHO the Agent Is
+
+The `.agent` file is not a configuration file — it is an identity specification. It answers:
+
+- **Who am I?** — id, nickname, role, description, personality
+- **What do I know?** — expertise with confidence scores
+- **What do I notice?** — attention patterns and threshold
+- **How do I work with others?** — collaboration stance, pairings, debate rules
+- **How do I behave?** — named behavior protocols
+- **What have I learned?** — transferable patterns
+
+When the orchestrator invokes an agent, `buildProfileEnrichment()` assembles all of these fields into a prompt section that makes the LLM behave as that specific agent. The same base model (e.g., Claude Sonnet) becomes the security agent or the designer based entirely on the profile enrichment injected from the `.agent` file.

package/dist/university-content/notes/N-para-701-agent-roster.md

@@ -0,0 +1,82 @@
+---
+id: N-para-701-agent-roster
+title: 'Lesson 1: The Agent Roster'
+type: note
+author: paradigm
+created: '2026-04-22'
+updated: '2026-04-22'
+tags:
+  - course
+  - para-701
+  - 54-agents-organized
+  - each-agent-has
+  - the-orchestrator-selects
+symbols: []
+difficulty: beginner
+estimatedMinutes: 5
+prerequisites: []
+category: paradigm-core
+origin: imported
+source: courses/para-701.json
+---
+
+## 54 Agents, 7 Tiers
+
+Paradigm ships with 54 named agents organized into seven functional tiers. Each agent is a narrow specialist with a defined personality, expertise domain, attention patterns, and collaboration graph. The roster is not a menu of interchangeable generalists — it is a team of specialists who are each the best at one thing.
+
+The seven tiers group agents by function:
+
+**Builders** — Agents that produce code and artifacts. The builder agent writes implementation code. Mika (designer) produces UI/UX designs. Wren (copywriter) writes user-facing text. Ghost (e2e) writes end-to-end tests. The tester writes unit and integration tests. These agents produce output that becomes part of the codebase.
+
+**Reviewers** — Agents that evaluate what builders produce. The reviewer checks code quality and Paradigm compliance. Shield (qa) designs test strategy and validates acceptance criteria. Jinx (advocate) is the devil's advocate who stress-tests assumptions and finds edge cases nobody considered. Bolt (performance) reviews for performance regressions.
+
+**Strategists** — Agents that plan and decide. The architect designs systems and leads orchestration. North (product) owns the product vision and prioritization. Yuki (pm) manages tickets and tracking. Scout (researcher) conducts competitive analysis and market research. Clause (legal) handles compliance and legal review.
+
+**Intelligence** — Agents that gather and analyze information. Sage (analyst) performs data analysis. Beacon (seo) handles search optimization. Lens (content-intel) analyzes content strategy. Oracle (ai) specializes in AI/ML patterns and prompt engineering. Cipher (reverser) reverse-engineers systems and protocols.
+
+**Infrastructure** — Agents that manage the platform and deployment. Atlas (devops) owns CI/CD, deployment, and monitoring. Vault (dba) manages databases, migrations, and query optimization. Root (sysadmin) handles system administration. Wire (network) specializes in networking and protocols. Ship (release) manages release coordination.
+
+**Meta** — Agents that manage other agents. Loid (forge) designs and builds new agents — she understands the full .agent profile schema and recommends team compositions. Sensei (trainer) trains agents by reviewing their performance and curating notebook entries. The documentor maintains .purpose files and portal.yaml after other agents finish their work. Bridge (mediator) resolves disagreements between agents.
+
+**Human Ops** — Agents that support the human directly. Sunday (secretary) is a personal operations agent who tracks goals, schedules, and commitments across all projects. Obi (mentor) provides career guidance. Sheila (educator) creates learning materials for humans. Leila (operations) handles business operations.
+
+## Named Agents Have Personalities
+
+Every agent has a unique nickname and personality configuration. Jinx is confrontational and aggressive — her job is to argue against the current approach. Mika is opinionated and precise — she leads design discussions and will challenge decisions. Sunday is proactive and conservative — she watches the human's commitments across all contexts. Atlas is methodical and conservative — he does not take risks with infrastructure.
+
+These are not cosmetic names. The personality (style, risk tolerance, verbosity) shapes how the agent behaves during orchestration. A `deliberate` architect thinks carefully before responding. A `rapid` builder moves fast. A `confrontational` advocate pushes back on every assumption.
+
+## How the Orchestrator Picks Agents
+
+When `paradigm_orchestrate_inline` runs in plan mode, it evaluates which agents are relevant to the task. The selection process considers:
+
+1. **Task classification** — What kind of work is this? A new feature needs builders, reviewers, and possibly security. A refactor needs the architect and reviewer. An incident needs devops, debugger, and security.
+
+2. **Symbol matching** — Which symbols does the task touch? Each agent has attention patterns (symbols, paths, concepts, signals) that define what they notice. If the task involves `^authenticated` gates, the security agent's symbol pattern `^*` matches. If it touches `src/design/**` files, Mika's path patterns match.
+
+3. **Attention threshold** — Each agent scores events against their attention patterns. Only agents whose relevance score meets their threshold are included. Security has a low threshold (0.45) because missing a security issue is expensive. The builder has a higher threshold (0.75) because it should only be included when directly relevant.
+
+4. **Roster filtering** — If the project has a `roster.yaml`, only agents listed there are considered. A game project does not need SEO or legal agents. A backend API does not need a designer.
+
+The orchestrator then stages agents in dependency order: the architect plans first, builders implement, the reviewer and security check, the documentor updates Paradigm files last.
+
+## Why Narrow Specialists Beat Broad Generalists
+
+A single "coding agent" that tries to build, review, test, and document produces mediocre results across all dimensions. The specialist model works because:
+
+- **Expertise compounds** — The security agent's confidence on `#portal-gates` is 0.95 because that is all it focuses on. A generalist's confidence would be 0.5 across many domains.
+- **Attention is focused** — The security agent watches gate symbols, auth paths, and security concepts. It does not waste attention on typography or test fixtures.
+- **Collaboration is explicit** — The architect pairs with security to validate auth models. The builder pairs with the tester to verify implementation. These pairs are defined in the agent's collaboration graph, not left to chance.
+- **Accountability is clear** — When a security issue ships, the security agent's acceptance rate drops. When a design is inconsistent, Mika's patterns need updating. Each agent owns a specific quality dimension.
+
+The full roster provides coverage across code quality, security, performance, accessibility, design, testing, documentation, and business strategy. Most projects activate 15-25 agents depending on the domain. The orchestrator handles routing — the human never manually assigns agents to tasks.
+
+| Tier | Count | Example Agents |
+|---|---|---|
+| Builders | ~10 | builder, designer (Mika), copywriter (Wren), tester, e2e (Ghost) |
+| Reviewers | ~6 | reviewer, qa (Shield), advocate (Jinx), performance (Bolt) |
+| Strategists | ~8 | architect, product (North), pm (Yuki), researcher (Scout) |
+| Intelligence | ~7 | analyst (Sage), seo (Beacon), content-intel (Lens), ai (Oracle) |
+| Infrastructure | ~8 | devops (Atlas), dba (Vault), sysadmin (Root), release (Ship) |
+| Meta | ~6 | forge (Loid), trainer (Sensei), documentor, mediator (Bridge) |
+| Human Ops | ~9 | secretary (Sunday), mentor (Obi), educator (Sheila), operations (Leila) |

package/dist/university-content/notes/N-para-701-agent-state.md

@@ -0,0 +1,180 @@
+---
+id: N-para-701-agent-state
+title: 'Lesson 4: Agent State & Continuity'
+type: note
+author: paradigm
+created: '2026-04-22'
+updated: '2026-04-22'
+tags:
+  - course
+  - para-701
+  - project-state-at
+  - global-state-at
+  - buildprofileenrichment-injects-agent
+symbols: []
+difficulty: beginner
+estimatedMinutes: 6
+prerequisites: []
+category: paradigm-core
+origin: imported
+source: courses/para-701.json
+---
+
+## The Continuity Problem
+
+Every AI session starts from zero. The model has no memory of previous sessions. If the security agent reviewed 8 files yesterday, identified 3 gate coverage gaps, and deferred 2 items to today — all of that context is lost when the session ends. The next session's security agent starts fresh, potentially re-reviewing the same files and missing the deferred items entirely.
+
+Agent state solves this by persisting key information between sessions at two scopes: project-level state (what happened on this specific project) and global state (career statistics across all projects).
+
+## Project State: AgentProjectState
+
+Project-scoped state lives at `.paradigm/agent-state/{agent-id}.yaml` and captures what the agent has done on THIS project:
+
+```typescript
+interface AgentProjectState {
+  id: string;                    // Agent ID
+  project: string;               // Project name
+  lastSession: {                 // Most recent session summary
+    date: string;                // ISO timestamp
+    sessionId: string;           // Session identifier
+    summary: string;             // What was done
+    filesReviewed?: string[];    // Files the agent looked at
+    symbolsTouched?: string[];   // Symbols the agent worked on
+    decisions?: string[];        // Decisions made in the session
+  };
+  pendingWork: string[];         // Items deferred to next session
+  recentPatterns: string[];      // Patterns learned about this project
+  sessionsOnProject: number;     // Total session count
+  lastPurposeUpdate?: string;    // When .purpose was last updated
+}
+```
+
+The `lastSession` field is the most valuable for continuity. When the agent is invoked in the next session, `buildProfileEnrichment()` injects this into the prompt:
+
+```markdown
+## Your Recent Work on This Project
+Last session (3h ago): Reviewed auth middleware, found 2 missing gate
+declarations for POST /api/payments and PUT /api/subscriptions.
+Sessions on this project: 8
+**Pending from last session:**
+- Review the new webhook endpoint for gate coverage
+- Check Sentinel for auth anomalies on the payment routes
+**Project patterns you've learned:**
+- This project uses sliding-window JWT rotation
+- RLS policies follow the tenant-scoped pattern
+```
+
+The agent now has context. It knows what it did last time, what remains unfinished, and what project-specific patterns it has discovered. It does not re-review files it already checked. It picks up the pending items and continues where it left off.
+
+## Pending Work Tracking
+
+The `pendingWork` array is a simple but powerful mechanism. When an agent encounters work it cannot complete in the current session, it adds items:
+
+```typescript
+addPendingWork('security', rootDir, [
+  'Review webhook endpoint /api/webhooks/stripe for gate coverage',
+  'Check Sentinel for auth anomalies on payment routes',
+]);
+```
+
+When the work is completed in a future session:
+
+```typescript
+completePendingWork('security', rootDir, [
+  'Review webhook endpoint /api/webhooks/stripe for gate coverage',
+]);
+```
+
+Pending items accumulate across sessions until explicitly completed. This creates a persistent to-do list that survives session boundaries. If the security agent defers 3 items across 3 different sessions, all 3 appear in the next session's prompt enrichment.
+
+## Recent Patterns
+
+The `recentPatterns` array captures project-specific knowledge:
+
+```typescript
+addProjectPattern('security', rootDir,
+  'This project uses Supabase RLS with tenant-scoped policies'
+);
+```
+
+Patterns are kept to a maximum of 10 (oldest are dropped when new ones are added). These are different from transferable patterns in the `.agent` file — recent patterns are project-specific and do not travel. The security agent learning "this project uses tenant-scoped RLS" is only relevant to this project. The transferable pattern "always check RLS policies on Supabase tables" applies everywhere.
+
+## Global State: GlobalAgentState
+
+Global state lives at `~/.paradigm/agents/{agent-id}/state.yaml` and tracks the agent's career across all projects:
+
+```typescript
+interface GlobalAgentState {
+  id: string;                    // Agent ID
+  totalSessions: number;         // Lifetime session count
+  lastActiveProject: string;     // Most recent project
+  lastActiveDate: string;        // ISO timestamp
+  projectHistory: Array<{        // Per-project stats
+    project: string;
+    sessions: number;
+    lastActive: string;
+  }>;
+}
+```
+
+Global state provides aggregate context: "This agent has worked 47 sessions across 5 projects, most recently on dealoracle 2 hours ago." This is useful for:
+
+- **Expertise calibration** — An agent with 47 total sessions has more experience than one with 3.
+- **Project affinity** — An agent with 30 sessions on project A and 2 on project B has deep expertise on A.
+- **Recency** — An agent that was last active 3 months ago may need a full onboarding pass.
+
+Global state is updated automatically whenever `recordAgentSession()` is called — it increments `totalSessions`, updates `lastActiveProject` and `lastActiveDate`, and maintains the `projectHistory` array sorted by most recent.
+
+## How State Feeds Into Prompts
+
+The `buildProfileEnrichment()` function accepts an optional `agentState` parameter:
+
+```typescript
+buildProfileEnrichment(
+  profile,
+  relevantSymbols,
+  notebookEntries,
+  ambientContext,
+  agentState: {
+    lastSession: { summary: '...', date: '...' },
+    pendingWork: ['...'],
+    recentPatterns: ['...'],
+    sessionsOnProject: 8
+  }
+);
+```
+
+The function assembles this into a `## Your Recent Work on This Project` section with:
+
+1. **Last session summary with age** — "Last session (3h ago): Reviewed auth middleware..." The age is computed from the timestamp and displayed as hours or days.
+2. **Session count** — "Sessions on this project: 8" (context for experience level)
+3. **Pending work** — Up to 5 items from the pending work list.
+4. **Project patterns** — Up to 5 recently learned patterns.
+
+This section typically consumes 100-300 tokens depending on the amount of pending work and patterns. It is one of the highest-value sections in the prompt because it provides the specific, recent context that enables continuity.
+
+## Recording Sessions
+
+At the end of an orchestration pass, the orchestrator calls `recordAgentSession()` for each agent that participated:
+
+```typescript
+recordAgentSession('security', rootDir, {
+  sessionId: 'sess-2026-03-24-001',
+  summary: 'Reviewed 5 new routes for gate coverage. Found 2 gaps.',
+  filesReviewed: ['src/routes/payments.ts', 'src/routes/webhooks.ts'],
+  symbolsTouched: ['^authenticated', '^payment-owner', '#payment-service'],
+  decisions: ['Recommended adding ^payment-owner gate for refund endpoints'],
+  pendingWork: ['Review webhook endpoint for Stripe signature verification'],
+  patterns: ['This project stores Stripe webhook secrets in Supabase vault'],
+});
+```
+
+This writes the project state file, increments the session count, and also updates global state. The next time the security agent is invoked on this project, it will see this session's summary and pending work in its prompt.
+
+## Loading All States
+
+The `loadAllAgentStates()` function reads all agent state files for a project, returning an array of `AgentProjectState` objects. This is useful for:
+
+- **Dashboard views** — Conductor's agent roster view shows each agent's last session and pending work count.
+- **Orchestration planning** — The orchestrator can check which agents have pending work on the current project and prioritize their inclusion.
+- **Stale detection** — If an agent's last session was months ago, the orchestrator may trigger a fresh onboarding pass.

package/dist/university-content/notes/N-para-701-learning-feedback-loop.md

@@ -0,0 +1,188 @@
+---
+id: N-para-701-learning-feedback-loop
+title: 'Lesson 9: The Learning Feedback Loop'
+type: note
+author: paradigm
+created: '2026-04-22'
+updated: '2026-04-22'
+tags:
+  - course
+  - para-701
+  - session-work-log
+  - auto-expertise-adjustment-003
+  - teacher-model-runs
+symbols: []
+difficulty: beginner
+estimatedMinutes: 6
+prerequisites: []
+category: paradigm-core
+origin: imported
+source: courses/para-701.json
+---
+
+## The Full Loop: DO-RECORD-ASSESS-LEARN-ADAPT-DO
+
+PARA 601 introduced the six-phase learning loop. In the context of the agent system, this loop operates at the agent level: each agent does work, records its contributions, receives verdicts, learns from the feedback, and adapts its behavior for the next session. The agent system provides the concrete mechanisms that make each phase work.
+
+## Phase 1: DO — Agent Work
+
+Agents perform work during orchestration. The builder writes code. The security agent reviews gates. The designer proposes UI patterns. Each contribution is captured in the session work log as an `agent-contribution` entry:
+
+```typescript
+interface SessionWorkEntry {
+  timestamp: string;
+  type: 'agent-contribution' | 'user-verdict' | 'decision';
+  agent?: string;
+  contribution?: string;
+  attribution?: string;
+  symbols?: string[];
+}
+```
+
+The session work log is stored at `.paradigm/events/session-log.jsonl` as append-only JSONL, bounded to 200 entries per session. Unlike breadcrumbs (which are recovery-focused with a 50-entry limit), the session work log captures rich context specifically for the learning pass.
+
+## Phase 2: RECORD — Verdict Capture
+
+When a human accepts, dismisses, or revises an agent's contribution, the verdict is recorded:
+
+```typescript
+{
+  type: 'user-verdict',
+  agent: 'security',
+  nominationId: 'nom-2026-03-24-001',
+  verdict: 'accepted' | 'dismissed' | 'revised' | 'deferred',
+  reason: 'Gate coverage recommendation was accurate',
+  symbols: ['^authenticated', '#payment-service'],
+  revisionDelta?: '...',  // What the human changed (for revised)
+}
+```
+
+Four verdict types capture the full range of human feedback:
+
+- **accepted** — The contribution was correct and applied as-is.
+- **dismissed** — The contribution was wrong or irrelevant.
+- **revised** — The contribution was partially correct; the human modified it. The `revisionDelta` captures what changed.
+- **deferred** — The contribution may be valid but is not relevant now.
+
+Each verdict is linked to the agent and the symbols involved, enabling per-symbol confidence tracking.
+
+## Phase 3: ASSESS — Auto-Expertise Adjustment
+
+When a verdict is recorded, the session work log automatically adjusts the agent's expertise confidence:
+
+```typescript
+const delta = entry.verdict === 'accepted' ? 0.03
+  : entry.verdict === 'dismissed' ? -0.02
+  : entry.verdict === 'revised' ? -0.01
+  : 0; // deferred = no change
+```
+
+This adjustment is asymmetric by design:
+
+- **+0.03 for accepted** — Positive reinforcement is slightly stronger than negative. This prevents a single bad review from tanking an otherwise reliable agent.
+- **-0.02 for dismissed** — A dismissed contribution means the agent was wrong. Confidence should decrease, but not catastrophically.
+- **-0.01 for revised** — A revised contribution was partially right. The penalty is smaller because the agent was in the right direction.
+- **0 for deferred** — Deferral says nothing about correctness, only timing. No confidence change.
+
+The adjustment is applied per-symbol. If the security agent's gate recommendation for `^authenticated` was accepted, its confidence on `^authenticated` increases by 0.03. Its confidence on unrelated symbols is unchanged.
+
+```typescript
+for (const symbol of entry.symbols!) {
+  const exp = profile.expertise!.find(e => e.symbol === symbol);
+  if (exp) {
+    exp.confidence = Math.max(0, Math.min(1, exp.confidence + delta));
+    exp.sessions = (exp.sessions || 0) + 1;
+    exp.lastTouch = new Date().toISOString();
+  }
+}
+```
+
+Confidence is clamped to `[0.0, 1.0]`. Sessions are incremented. The `lastTouch` timestamp is updated. This all happens as a fire-and-forget side effect of recording the verdict — the human never manually adjusts expertise scores.
+
+## Phase 4: LEARN — Teacher Model and Journal Entries
+
+At the end of an orchestration session, the Teacher Model runs a postflight learning pass. It reads the session work log, identifies patterns in the verdicts, and writes journal entries for each agent that participated:
+
+```yaml
+# Learning journal entry written by Teacher Model
+id: LJ-2026-03-24-001
+agent: security
+timestamp: '2026-03-24T16:00:00.000Z'
+trigger: human_feedback
+insight: >-
+  Security review of webhook endpoints should check for Stripe
+  signature verification, not just gate coverage. The human revised
+  the gate recommendation to include webhook-specific checks.
+project: dealoracle
+transferable: true
+confidence_before: 0.85
+confidence_after: 0.84
+pattern:
+  id: webhook-stripe-signature
+  applies_when: Reviewing webhook endpoints that receive Stripe events
+  correct_approach: Check for webhook signature verification in addition to gate coverage
+```
+
+The Teacher Model synthesizes verdict patterns into actionable journal entries. A single "revised" verdict becomes an insight about what the agent should do differently. The `trigger: human_feedback` records that this learning came from a human correction, not self-reflection.
+
+## Phase 5: ADAPT — Journal Promotion to Notebooks
+
+Journal entries that prove valuable over time are promoted into notebook entries by Sensei (trainer). The promotion pipeline:
+
+```
+Journal entry (agent-private) → Sensei reviews → 
+promoteFromLore() → Notebook entry (reusable snippet) → 
+buildProfileEnrichment() → Injected into future prompts
+```
+
+The key distinction: journal entries are raw learnings ("I was wrong about X because Y"). Notebook entries are distilled knowledge ("When doing X, use this pattern"). Sensei's job is to transform the former into the latter.
+
+Not every journal entry becomes a notebook entry. Sensei evaluates:
+- Is the insight transferable to other projects?
+- Is it actionable (specific enough to apply)?
+- Has the same insight appeared in multiple sessions (pattern confirmation)?
+- Is the confidence high enough to be reliable?
+
+## Phase 6: The Nomination Engine
+
+The nomination engine connects the learning loop to real-time project activity. As events flow through the event stream, each active agent scores them against their attention patterns:
+
+```
+Event (file-modified, gate-added, etc.)
+  ↓
+scoreEventForAgent(event, agentId, attention)
+  ↓
+AttentionScore { score, shouldNominate, breakdown }
+  ↓
+If shouldNominate → Create nomination
+  ↓
+Nomination surfaced in orchestration or paradigm_ambient_nominations
+```
+
+The nomination engine is the adaptive component: as an agent's attention patterns evolve (new concepts, adjusted thresholds), its nominations change. As its expertise confidence adjusts, its contributions become more or less influential. The system adapts based on empirical performance, not fixed rules.
+
+## The Complete Cycle
+
+Putting all six phases together for a single agent:
+
+```
+1. DO:     Security agent reviews webhook endpoint, flags missing gate
+2. RECORD: Human accepts the gate recommendation → verdict: accepted
+3. ASSESS: Security confidence on ^authenticated: 0.85 → 0.88 (+0.03)
+4. LEARN:  Teacher Model writes journal entry about webhook gate patterns
+5. ADAPT:  Sensei promotes journal → notebook entry for webhook security
+6. DO:     Next session, security agent starts with webhook pattern in
+           its prompt via buildProfileEnrichment(). It applies the pattern
+           without needing to rediscover it.
+```
+
+Each iteration through the loop makes the agent incrementally better. After 10 sessions with consistent feedback, the security agent's webhook review pattern is battle-tested, high-confidence, and automatically injected into every relevant orchestration. The human no longer needs to remind the agent about webhook-specific checks — the learning loop closed.
+
+## What Makes This Different
+
+Most AI systems have observation without adaptation. They log what happened but do not feed it back. Paradigm's agent system closes the loop through four mechanisms:
+
+1. **Per-symbol expertise tracking** — Confidence adjusts based on verdicts, not manual scoring
+2. **Asymmetric reinforcement** — +0.03/-0.02/-0.01 prevents a single bad session from destroying confidence
+3. **Teacher Model postflight** — Journal entries are written automatically, not relying on agents to self-reflect
+4. **Notebook promotion** — Insights become reusable patterns via Sensei, surfaced through buildProfileEnrichment()