@a-company/paradigm 5.38.0 → 6.0.2

package/dist/university-content/notes/N-para-501-symphony-a-mail.md

@@ -0,0 +1,120 @@
+---
+id: N-para-501-symphony-a-mail
+title: 'Symphony: Multi-Agent Messaging with The Score'
+type: note
+author: paradigm
+created: '2026-04-22'
+updated: '2026-04-22'
+tags:
+  - course
+  - para-501
+  - the-score-is
+  - agent-identity-is
+  - mailbox-protocol-uses
+symbols: []
+difficulty: beginner
+estimatedMinutes: 7
+prerequisites: []
+category: paradigm-core
+origin: imported
+source: courses/para-501.json
+---
+
+## Agents Need to Talk
+
+Until now, every Paradigm agent has worked in isolation. A Claude Code session modifying the backend has no awareness of what the session working on the frontend is doing. Two developers on the same team, each with their own AI assistant, have no way for those assistants to coordinate — even when they are working on the same project at the same time.
+
+Symphony changes this. It is Paradigm's multi-agent, multi-human collaborative intelligence layer. And its foundation is The Score: a lightweight, file-based messaging protocol that gives every Claude Code session its own mailbox.
+
+## The Metaphor: Email for AI Agents
+
+The Score works exactly like email. Each agent has an identity, an inbox, and an outbox. Messages are delivered as JSONL files on the filesystem. Agents poll for new messages on a timer. There is no persistent server, no WebSocket connection, and no cloud dependency. If two agents are running on the same machine, they can message each other through nothing more than file reads and writes.
+
+This simplicity is deliberate. The Score is the CLI-only foundation of Symphony — it works with zero dependencies beyond the Paradigm CLI. No Conductor, no Sentinel, no network configuration. The only requirement is that agents are running on the same machine (or connected via a lightweight TCP relay for cross-machine scenarios).
+
+## Agent Identity and Discovery
+
+Every Claude Code session that participates in The Score has a stable identity. The identity is derived from the project directory and the agent's role — for example, `a-paradigm/backend` or `a-kamiki/frontend`. This deterministic naming means the same project opened in the same context always gets the same identity, even across session restarts.
+
+When you run `paradigm symphony join`, the CLI discovers all Claude Code sessions on the current machine and connects them into a mail network. Each session gets a mailbox directory at `~/.paradigm/score/agents/{agent-id}/` containing four files:
+
+- **`inbox.jsonl`** — Messages waiting for this agent, one per line, append-only
+- **`outbox.jsonl`** — Replies from this agent, append-only
+- **`ack.json`** — The ID of the last acknowledged message (for garbage collection)
+- **`identity.json`** — Agent ID, project, role, PID, and session start time
+
+The JSONL format — one JSON object per line — makes appending atomic and parsing trivial. No file locking, no corruption risk from concurrent writes, no binary format to decode.
+
+## Messaging and Threading
+
+Messages in The Score carry structured metadata beyond plain text. Every message has an **intent** that classifies its purpose:
+
+| Intent | Meaning |
+|---|---|
+| `question` | Asking for information from other agents |
+| `context` | Providing background or context |
+| `proposal` | Proposing an action or fix |
+| `action` | Announcing an action the agent took |
+| `decision` | Recording a decision |
+| `alert` | Forwarding a Sentinel alert |
+| `approval` / `rejection` | Responding to a proposal |
+| `handoff` | Transferring responsibility to another agent |
+| `fileRequest` | Requesting a file from another agent |
+| `fileDelivery` | Delivering a requested file |
+
+Intents serve two purposes. First, they give the receiving agent structured context about what kind of response is expected — a question needs an answer, a proposal needs approval or rejection, a decision needs acknowledgment. Second, they feed into Lore: when a message has `intent: decision`, Symphony can automatically record it as a lore entry.
+
+Messages belong to **threads**. A thread starts when the first message on a topic is sent (with no `parentId`). Subsequent replies reference the thread root, building a conversation tree. Thread state is tracked in `~/.paradigm/score/threads/{thread-id}.json`, which records the topic, participants, message count, and last activity timestamp.
+
+## The File Pipeline
+
+Agents often need to share files — a type definition, an API contract, a configuration file. The Score's file pipeline enables this with a critical security constraint: **every file transfer requires explicit human approval**.
+
+The flow works like this: Agent A sends a `fileRequest` message specifying the file path, a reason, and the target agent. The request appears in the owning human's terminal (via `paradigm symphony requests`). The human reviews and either approves, denies, or approves with redaction (stripping sensitive lines). Only after human approval does the file content get written to the requester's inbox.
+
+Trust configuration lives in `~/.paradigm/score/trust.yaml`. You can define auto-approve patterns for trusted users (`docs/**`, `*.md`) and never-approve patterns for sensitive files (`.env*`, `*.key`, `*.pem`, `**/secrets/**`). The never-approve list is enforced absolutely — even clicking approve on a `.env` file will be denied by the system. File requests expire after one hour without action, and all transfers are logged.
+
+## /loop: The Agent Heartbeat
+
+The glue that makes The Score work is `/loop`. Each Claude Code session runs `/loop 10s paradigm_symphony_poll`, which polls the inbox every 10 seconds for new messages. The `paradigm_symphony_poll` MCP tool reads `inbox.jsonl`, formats messages as structured prompts the agent can reason about, and suggests actions.
+
+Without `/loop`, messages would accumulate in the inbox with nobody reading them. The loop is the heartbeat — it keeps agents responsive. When an agent processes a message and replies via `paradigm_symphony_send`, the reply goes to `outbox.jsonl`. A mail router (or Conductor, in later phases) picks up outbox messages and delivers them to the appropriate inbox files.
+
+The convenience command `paradigm symphony join` combines registration and loop setup in one step — it registers the session's identity and starts the polling loop automatically.
+
+## Thread Resolution and Lore Integration
+
+Conversation threads are not meant to live forever. When a thread reaches a conclusion, any participant (human or agent) can resolve it with `paradigm symphony resolve <thread-id>`. Resolution triggers an automatic lore entry that captures the full conversation: topic, participants, decisions made, actions taken, and symbols discussed.
+
+This is the bridge between ephemeral conversation and permanent project memory. A 15-minute exchange between three agents about a serialization bug becomes a searchable lore entry tagged with the relevant symbols and arc. The next developer encountering a similar issue can find the conversation, the decision, and the fix — all linked together.
+
+## CLI Commands
+
+The `paradigm symphony` command group provides the complete human interface:
+
+- `paradigm symphony whoami` — Show this agent's identity and linked peers
+- `paradigm symphony list` — List all known agents with status (awake/asleep) and location
+- `paradigm symphony join` — Discover and connect Claude Code sessions on this machine
+- `paradigm symphony join --remote <ip>` — Connect to a remote machine's mail server
+- `paradigm symphony send "message"` — Broadcast to all linked agents
+- `paradigm symphony send --to <agent> "message"` — Direct message to a specific agent
+- `paradigm symphony send --thread <id> "message"` — Reply to an existing thread
+- `paradigm symphony read` — Show unread messages
+- `paradigm symphony threads` — List active threads
+- `paradigm symphony resolve <id>` — Resolve a thread, creating a lore entry
+- `paradigm symphony status` — Network overview (agents, threads, unread count)
+
+For the file pipeline: `paradigm symphony request`, `paradigm symphony requests`, `paradigm symphony approve`, and `paradigm symphony deny`.
+
+## MCP Tools for Agent Participation
+
+Six MCP tools power agent-side Symphony participation:
+
+- **`paradigm_symphony_poll`** — The heartbeat. Reads inbox, returns formatted messages and thread summaries. Called by `/loop`.
+- **`paradigm_symphony_send`** — Send a message with intent, text, optional symbols, diff, or decision. Writes to outbox.
+- **`paradigm_symphony_status`** — Overview of the local network: agents, threads, Sentinel endpoint.
+- **`paradigm_symphony_thread`** — Get full context of a conversation thread with messages, participants, and extracted decisions.
+- **`paradigm_symphony_request_file`** — Request a file from another agent. Returns immediately with `pending` status; delivery arrives via future poll.
+- **`paradigm_symphony_approve_file`** — Approve or deny a pending file request after human confirmation.
+
+These tools compose naturally with existing Paradigm workflows. An agent can poll for messages, discover a question about `#payment-serializer`, call `paradigm_ripple` to check impact, and respond with full context — all within a single `/loop` cycle.

package/dist/university-content/notes/N-para-501-symphony-networking.md

@@ -0,0 +1,119 @@
+---
+id: N-para-501-symphony-networking
+title: 'Symphony Networking: Cross-Machine Relay'
+type: note
+author: paradigm
+created: '2026-04-22'
+updated: '2026-04-22'
+tags:
+  - course
+  - para-501
+  - hub-and-spoke-topology-one
+  - websocket-relay-watches
+  - pairing-6-digit-code
+symbols: []
+difficulty: beginner
+estimatedMinutes: 4
+prerequisites: []
+category: paradigm-core
+origin: imported
+source: courses/para-501.json
+---
+
+## Beyond Single-Machine Messaging
+
+Symphony Phase 0 (A-Mail) established file-based agent-to-agent messaging on a single machine — JSONL mailboxes at `~/.paradigm/score/`, polled via `/loop`. But what happens when two developers on the same WiFi, or at different locations, want their Claude instances to collaborate?
+
+Symphony Phase 1 adds cross-machine networking via a WebSocket relay. The key design principle: **the local mailbox model is unchanged**. Networking is a transparent sync layer that watches local outboxes and delivers remote messages to local inboxes.
+
+## Hub-and-Spoke Topology
+
+One machine runs `paradigm symphony serve` (the **hub**), and others connect with `paradigm symphony join --remote` (the **spokes**). The hub relays messages between all connected machines.
+
+```
+Machine A (Hub)                     Machine B (Spoke)
+┌─────────────────────┐           ┌─────────────────────┐
+│ ~/.paradigm/score/  │           │ ~/.paradigm/score/  │
+│   agents/projA/core │           │   agents/projB/core │
+│     inbox.jsonl     │◄────ws───►│     inbox.jsonl     │
+│     outbox.jsonl    │  :3939    │     outbox.jsonl    │
+└─────────────────────┘           └─────────────────────┘
+```
+
+The relay watches each local agent's outbox file (polling every 2 seconds via `fs.stat`). When new messages appear, they're pushed to all connected peers as WebSocket frames. Incoming messages from peers are written to the appropriate local inbox via `appendToInbox()`.
+
+## Pairing & Authentication
+
+Security is critical when connecting machines over a network. Symphony uses a pairing code + HMAC challenge-response protocol:
+
+1. The hub generates a 32-byte random secret and derives a **6-digit pairing code**
+2. The code is displayed on the hub's terminal
+3. The spoke connects and receives a `hello` frame with a random challenge nonce
+4. The user enters the code on the spoke terminal (or embeds it in the connection string)
+5. The spoke computes `HMAC-SHA256(challenge, SHA256(code))` and sends an `auth` frame
+6. The hub verifies the code and HMAC proof, then sends `auth_ok` with its agent list
+
+Pairing codes rotate every 5 minutes. After 3 failed attempts from the same IP, a 60-second cooldown is enforced. Peer records are saved to `~/.paradigm/score/peers.json` (file mode 0600) for auto-reconnect.
+
+## Two Connection Modes
+
+### LAN Pairing (same WiFi)
+
+```sh
+# Machine A (hub)
+paradigm symphony serve
+# Shows: Pairing Code: 847 291
+
+# Machine B (spoke)
+paradigm symphony join --remote 192.168.1.42:3939
+# Prompted for code
+```
+
+### Internet Direct Connect
+
+```sh
+# Machine A
+paradigm symphony serve --public
+# Shows connection string
+
+# Machine B
+paradigm symphony join --remote 73.162.44.103:3939#847291
+# Code embedded — no prompt
+```
+
+Internet mode requires port 3939 to be reachable (port forward, VPN, or SSH tunnel).
+
+## Trust Management
+
+Peers are managed via CLI commands:
+
+- `paradigm symphony peers` — List trusted peers with agent counts and last-seen times
+- `paradigm symphony peers revoke <id>` — Immediately disconnect and block reconnection
+- `paradigm symphony peers forget --force` — Clear all peer trust records
+
+Existing `trust.yaml` hard-deny patterns (`.env*`, `*.key`, `*.pem`) apply to remote file requests — the trust boundary extends across the network.
+
+## Relay Internals
+
+The `SymphonyRelay` class handles both server and client modes:
+
+- **Outbox watcher**: Polls every 2s, compares outbox line counts against stored positions, forwards new messages
+- **Deduplication**: Bounded `Set<string>` of message IDs (max 10,000) prevents duplicate delivery
+- **Keepalive**: Ping/pong every 30s with 10s pong timeout. Dead connections are auto-terminated
+- **Auto-reconnect**: Client mode uses exponential backoff (1s → 2s → 4s → ... → 30s max)
+- **Rate limiting**: 3 failed auth attempts from the same IP triggers a 60s cooldown
+
+## Remote Agent Visibility
+
+Remote agents appear throughout the Symphony CLI and MCP tools:
+
+- `paradigm symphony list` shows remote agents with a `(remote: peer-name)` tag
+- `paradigm symphony status` includes peer count and remote agent totals
+- `paradigm_symphony_status` MCP tool returns a `peers` array in its response
+- Platform UI `GET /api/symphony/peers` endpoint returns connected peer data
+
+Local MCP tools (`peek`, `poll`, `send`) work unchanged — they just read/write local files. The relay handles the network transport transparently.
+
+## Backward Compatibility
+
+If `paradigm symphony serve` is never run, Symphony operates exactly as Phase 0: local-only file-based messaging. Networking is purely additive — no existing workflows change.

package/dist/university-content/notes/N-para-501-task-management.md

@@ -0,0 +1,100 @@
+---
+id: N-para-501-task-management
+title: Task Management
+type: note
+author: paradigm
+created: '2026-04-22'
+updated: '2026-04-22'
+tags:
+  - course
+  - para-501
+  - tasks-are-persistent
+  - auto-generated-ids-t-date-sequence
+  - three-priority-levels
+symbols: []
+difficulty: beginner
+estimatedMinutes: 4
+prerequisites: []
+category: paradigm-core
+origin: imported
+source: courses/para-501.json
+---
+
+## Why Tasks Exist
+
+AI agent sessions are stateless. You can discuss a plan, identify five things that need doing, and then the session ends. The next session starts blank — those five items are gone. Sticky notes on a monitor do not help when your developer is a language model.
+
+Paradigm's Task Management system provides a persistent scratch pad that survives context windows. Tasks are lightweight, date-partitioned YAML entries that capture what needs doing, how urgent it is, and what project knowledge relates to it. They are not a full project management system — they are the missing short-term memory between sessions.
+
+The key difference from lore: lore records what happened (past tense). Tasks record what should happen (future tense). Together they form a complete timeline — memory of the past and intention for the future.
+
+## Anatomy of a Task
+
+Every task follows a consistent structure:
+
+```yaml
+id: T-2026-02-26-001
+blurb: "Add rate limiting to the /api/payments endpoint"
+priority: high
+status: open
+tags: [security, payments]
+related_lore: [L-2026-02-25-003]
+created: "2026-02-26T10:15:00Z"
+updated: "2026-02-26T10:15:00Z"
+```
+
+The `id` field is auto-generated: `T-{date}-{sequence}`, following the same date-partitioned pattern as lore entries. The `blurb` is the only required field — a concise description of what needs to be done. Everything else is optional but useful.
+
+Three priority levels exist: `high` (do this soon), `medium` (do this eventually), and `low` (nice to have). Tasks without an explicit priority default to `medium`.
+
+Three statuses track lifecycle: `open` (needs doing), `done` (completed), and `shelved` (parked for later — not abandoned, just deferred).
+
+## Storage: Date-Partitioned YAML
+
+Tasks live in `.paradigm/tasks/entries/` organized by creation date:
+
+```
+.paradigm/tasks/
+  entries/
+    2026-02-25/
+      T-2026-02-25-001.yaml
+      T-2026-02-25-002.yaml
+    2026-02-26/
+      T-2026-02-26-001.yaml
+```
+
+Date partitioning keeps directories small. Each task is a standalone YAML file, making them easy to read, edit, and version-control. The date in the path matches the date in the task ID.
+
+## The Five MCP Tools
+
+**`paradigm_task_create`** — Create a new task. The `blurb` field is required — a short description of what needs to be done. Optional fields include `priority` (high/medium/low), `tags` (for categorization and filtering), and `related_lore` (linking to lore entries that provide context). The task is written to the correct date directory with an auto-incremented ID and starts with status `open`.
+
+**`paradigm_task_list`** — List tasks with filters. Filter by `status` (open/done/shelved/all), `priority` (high/medium/low), or `tag`. Results are sorted by priority (high first) then by date (newest first). Without filters, it returns all open tasks.
+
+**`paradigm_task_update`** — Update any field on an existing task by ID. You can change the blurb, priority, status, tags, or related_lore. Only specified fields are modified — everything else is preserved.
+
+**`paradigm_task_done`** — Shorthand to mark a task as complete. Pass the task ID and the status changes to `done` with an updated timestamp. This is equivalent to `paradigm_task_update` with `status: done` but more ergonomic for the common case.
+
+**`paradigm_task_shelve`** — Shorthand to shelve a task for later. Pass the task ID and the status changes to `shelved`. Shelved tasks are not deleted — they remain searchable and can be reopened by updating their status back to `open`.
+
+## Session Recovery Integration
+
+The top 5 open tasks are automatically surfaced during session recovery. When a new session starts and the agent calls any Paradigm MCP tool, the recovery data includes the highest-priority open tasks alongside the usual breadcrumbs and checkpoint data.
+
+This means every session begins with awareness of outstanding work. The agent does not need to ask "what should I work on?" — the task list is already there, sorted by priority. This is the scratch-pad-that-survives pattern: write tasks in one session, see them in the next.
+
+## When to Create Tasks
+
+Create tasks when:
+- You identify work that cannot be completed in the current session
+- A code review surfaces follow-up items
+- You discover a bug or improvement while working on something else
+- The user mentions something that should be tracked but is not the current focus
+- A handoff needs to communicate specific next steps
+
+Do not use tasks for:
+- Tracking completed work (that is what lore is for)
+- Long-term roadmap items (use your project management tool)
+- Architectural decisions (use lore entries with type `decision`)
+
+Tasks are ephemeral intentions — they should be created quickly, completed or shelved promptly, and never allowed to accumulate into a backlog of hundreds. If your task list grows beyond 20-30 open items, it is time to triage: shelve the low-priority items and focus on what matters.

package/dist/university-content/notes/N-para-601-agent-renaissance.md

@@ -0,0 +1,121 @@
+---
+id: N-para-601-agent-renaissance
+title: Agent Manifest Renaissance
+type: note
+author: paradigm
+created: '2026-04-22'
+updated: '2026-04-22'
+tags:
+  - course
+  - para-601
+  - six-new-dimensions
+  - intrinsic-learning-optional
+  - five-collaboration-stances
+symbols: []
+difficulty: beginner
+estimatedMinutes: 5
+prerequisites: []
+category: paradigm-core
+origin: imported
+source: courses/para-601.json
+---
+
+## Six New Dimensions
+
+Before v5.0, an agent profile (`AgentProfile`) had six core fields: `id`, `role`, `description`, `personality`, `expertise`, and `transferable` patterns. These covered identity and knowledge but said nothing about how agents observe, learn, contribute context, report work, collaborate, or decide when to speak up.
+
+v5.0 adds six new dimensions to the agent manifest, transforming it from a static identity card into a living behavioral specification:
+
+1. **Attention** (`AgentAttention`) — What this agent notices in the event stream
+2. **Learning** (`AgentLearning`) — How this agent improves over time
+3. **Context** (`AgentContext`) — What this agent contributes to shared context
+4. **Reporting** (`AgentReporting`) — How this agent logs work and learnings
+5. **Collaboration** (`AgentCollaboration`) — How this agent interacts with others
+6. **Nomination** (`AgentNomination`) — When this agent speaks up in ambient mode
+
+All six are optional on the `AgentProfile` interface for backward compatibility. Agents without these fields use sensible defaults or are treated as non-ambient (they do not participate in the observation-nomination loop).
+
+## Attention (AgentAttention)
+
+Covered in detail in the Attention & Scoring lesson. The attention dimension defines what the agent watches for: symbol patterns, file paths, semantic concepts, and signal types. The threshold determines sensitivity.
+
+Default configs exist for five standard roles via `DEFAULT_ATTENTION`. For example, the security agent defaults to watching all gate symbols (`^*`), auth-related components and paths, security concepts, and gate/route signals with a low threshold of 0.4.
+
+## Learning (AgentLearning)
+
+The learning dimension has two layers:
+
+**Intrinsic Learning** (`IntrinsicLearning`) — The agent's own drive to improve. This is optional for downloaded agents (they may or may not want to learn from user feedback). Four sub-sections:
+
+- **feedback** — When to ask for assessment: after work, after recommendations, from which agents, from humans. A security agent might configure `from_agents: ['architect', 'reviewer']` to weight peer feedback.
+- **adaptation** — How to adjust: `confidence_ema_alpha` (default 0.3) controls how quickly confidence scores move. `notebook_auto_promote` auto-promotes high-value journal entries. `pattern_extraction` extracts reusable patterns from learnings.
+- **reflection** — When to self-reflect: on failure, on correction, on debate loss. Each trigger records a journal entry with the relevant trigger type.
+- **calibration** — Accuracy targets: `target_accuracy` (default 0.85) is the goal. `overconfidence_alert` (default 0.15) triggers when estimated confidence exceeds actual accuracy by more than 15 points.
+
+**Platform Learning** (`PlatformLearning`) — Mandated for all marketplace agents. `feedback_required: true` is always set. Collects `work_outcome`, `helpfulness`, and `would_use_again` metrics. Feedback flows upstream anonymized. Aggregation is configurable per-offering, per-session, or per-project.
+
+## Context (AgentContext)
+
+The context dimension defines what the agent contributes to the composed context and what it requires to be loaded.
+
+**Contributions** — An array of `ContextContribution` items. Each specifies a `section` name (e.g., "Security Warnings"), inline `content` or a `content_ref` MCP resource URI, and a `priority` (high, medium, low). High-priority contributions are always included in composed context. Medium-priority contributions are included if token budget allows. Low-priority contributions are loaded on demand.
+
+**Requirements** — An array of `ContextRequirement` items specifying files or sections the agent needs loaded before it can work effectively. A security agent might require `portal.yaml` and the "gates" section of CLAUDE.md.
+
+## Reporting (AgentReporting)
+
+The reporting dimension controls how the agent captures its work and learnings in the knowledge streams.
+
+**Work Log Config** (`WorkLogConfig`):
+- `auto_record` — Automatically create work log entries when work completes
+- `structure` — Which structured fields to include: `task_ref`, `files_modified`, `symbols_touched`, `next_steps`, `blockers`
+- `destination` — Always `'work-log'`
+
+**Learning Journal Config** (`LearningJournalConfig`):
+- `auto_record` — Automatically record learning moments
+- `triggers` — Which events trigger journal entries: `correction_received`, `confidence_miss`, `pattern_discovered`
+- `destination` — Always `'journal'` (agent-private)
+
+## Collaboration (AgentCollaboration)
+
+The collaboration dimension defines how the agent interacts with others in multi-agent contexts.
+
+**Default Stance** (`CollaborationStance`) — One of five stances:
+- `lead` — Drives decisions, sets direction (architect default)
+- `advisory` — Offers guidance but does not drive (reviewer, security defaults)
+- `supportive` — Follows direction, executes (builder default)
+- `observer` — Watches but rarely acts
+- `peer` — Equal footing with no hierarchy
+
+**Per-Agent Relationships** — The `with` record allows overriding stance per agent. A builder might be `supportive` by default but `peer` with another builder.
+
+**Debate Config** — Controls debate behavior: `will_challenge` (will push back), `evidence_required` (must cite specific code/patterns), `escalate_to_human` (ask human if debate does not resolve).
+
+Default configs exist via `DEFAULT_COLLABORATION`. The architect defaults to `lead` stance with evidence-based challenging and human escalation. The builder defaults to `supportive` with `can_contradict: false` toward the architect.
+
+## Nomination (AgentNomination)
+
+The nomination dimension defines behavioral rules for self-nomination beyond the threshold check.
+
+**speak_when** — Conditions for speaking up:
+- `relevance_above` — Score threshold (default 0.6, mirrors attention threshold)
+- `urgency` — Always speak for specific urgency types: `security_risk`, `breaking_change`, `gate_missing`, `test_failure`, `performance_risk`
+- `asked_directly` — Always respond to direct questions (default: true)
+
+**quiet_when** — Conditions for staying silent:
+- `relevance_below` — Hard floor below which the agent never speaks
+- `another_agent_handling` — Stay quiet if another agent is already addressing this
+- `human_explicitly_excluded` — Respect human's explicit exclusion
+
+**contribution_style** — How the agent communicates:
+- `brief_first` — Start with a short summary, elaborate if asked
+- `cite_sources` — Reference specific code and patterns
+- `offer_action` — Offer concrete actions rather than just observations
+
+## buildProfileEnrichment
+
+The `buildProfileEnrichment` function composes all six dimensions into a prompt enrichment string for orchestration. It takes the agent profile, relevant symbols, optional notebook entries, and optional ambient context (recent decisions, journal insights, pending nominations).
+
+The output is structured markdown with sections for: Agent Identity, Expertise on Relevant Symbols, Transferable Patterns, Relevant Notebook Entries, Attention patterns, Collaboration stance, Nomination preferences, Recent Team Decisions, Transferable Insights, and Pending Nominations.
+
+This enrichment is injected into the agent's prompt during orchestration, giving it full awareness of its identity, capabilities, behavioral rules, and ambient context — all derived from the `.agent` file and the knowledge streams.

package/dist/university-content/notes/N-para-601-attention-scoring.md

@@ -0,0 +1,129 @@
+---
+id: N-para-601-attention-scoring
+title: Attention & Scoring
+type: note
+author: paradigm
+created: '2026-04-22'
+updated: '2026-04-22'
+tags:
+  - course
+  - para-601
+  - agentattention-has-four
+  - four-scoring-dimensions
+  - score-is-max-based
+symbols: []
+difficulty: beginner
+estimatedMinutes: 5
+prerequisites: []
+category: paradigm-core
+origin: imported
+source: courses/para-601.json
+---
+
+## AgentAttention Patterns
+
+Every agent in the ambient system has an attention configuration — a set of patterns that define what the agent notices. Think of it as a personalized filter: events that match the agent's attention patterns are potentially relevant; events that do not match are noise.
+
+The `AgentAttention` interface has five fields:
+
+```typescript
+interface AgentAttention {
+  symbols?: string[];       // Symbol patterns (e.g., ["^*", "#*-middleware"])
+  paths?: string[];         // File path patterns (e.g., ["auth/**", "middleware/**"])
+  concepts?: string[];      // Semantic triggers (e.g., ["JWT", "RBAC", "injection"])
+  signals?: AttentionSignal[]; // Event type triggers (e.g., [{ type: "gate-added" }])
+  threshold?: number;       // Confidence threshold (default 0.6)
+}
+```
+
+**Symbols** use glob patterns to match against the `symbols` array on events. A security agent watching `["^*", "#*-auth", "#*-middleware"]` will match any gate symbol and any component whose name ends in `-auth` or `-middleware`.
+
+**Paths** use glob patterns to match against the `path` field on events. A builder watching `["src/**", "lib/**", "packages/**"]` matches any source file change.
+
+**Concepts** are semantic keywords matched against the event's `context`, `keywords`, and `type` fields (all lowercased). A tester watching `["test", "coverage", "assertion"]` will match events mentioning those terms.
+
+**Signals** match against the event's `type` field. A security agent with `signals: [{ type: 'gate-added' }, { type: 'route-created' }]` will match whenever a new gate or route appears in the stream.
+
+## Four Scoring Dimensions
+
+When an event enters the stream, each agent scores it against their attention patterns across four dimensions:
+
+**symbolMatch (0.0-1.0):** For each pattern in the agent's `symbols` array, check if any symbol in the event matches (using glob). If any match is found, `symbolMatch = 1.0`. If no agent symbols are defined or no event symbols exist, `symbolMatch = 0.0`.
+
+**pathMatch (0.0-1.0):** For each pattern in the agent's `paths` array, check if the event's `path` matches. If any match is found, `pathMatch = 1.0`. Binary: either a path matches or it does not.
+
+**conceptMatch (0.0-1.0):** The event's `context`, `keywords`, and `type` are joined into a lowercased text. Each concept in the agent's `concepts` array is checked for inclusion. The score is `matched / total_concepts`. If the agent watches 5 concepts and 3 appear in the event text, `conceptMatch = 0.6`.
+
+**signalMatch (0.0-1.0):** For each signal in the agent's `signals` array, check if the event's `type` matches. If any match, `signalMatch = 1.0`. Binary.
+
+## Max-Based Score
+
+The overall score is the **maximum** of the four dimensions:
+
+```typescript
+const score = Math.max(symbolMatch, pathMatch, conceptMatch, signalMatch);
+```
+
+This is a deliberate design choice. Using max (rather than average or weighted sum) means a single strong match is enough to trigger attention. A security agent does not need to match on all four dimensions — if the event mentions a gate symbol (`symbolMatch = 1.0`), that alone is sufficient even if the file path, concepts, and signals do not match.
+
+The alternative (averaging) would dilute strong signals: a perfect symbol match (1.0) with no other matches would average to 0.25, likely falling below the threshold. Max scoring ensures that domain-specific expertise in any single dimension is respected.
+
+## Threshold-Based Self-Nomination
+
+After scoring, the agent checks its threshold:
+
+```typescript
+const threshold = attention.threshold ?? 0.6;
+const shouldNominate = score >= threshold;
+```
+
+If the score meets or exceeds the threshold, the agent should self-nominate a contribution. If not, the agent stays quiet, and the `quietReason` field records why: `'below-threshold'`.
+
+The default threshold is 0.6, but different agent roles have different defaults based on their domain:
+
+| Role | Default Threshold | Rationale |
+|---|---|---|
+| architect | 0.5 | Broad awareness — should notice most structural changes |
+| builder | 0.7 | Focused — only speaks when directly relevant to implementation |
+| reviewer | 0.6 | Balanced — watches code quality and patterns |
+| tester | 0.5 | Broad — testing intersects all areas |
+| security | 0.4 | Most sensitive — should speak up early and often |
+
+A lower threshold means the agent speaks up more often (more false positives, fewer missed issues). A higher threshold means the agent speaks up less often (fewer false positives, more missed issues). Security uses 0.4 because the cost of missing a security issue far outweighs the cost of a false alarm.
+
+## scoreEventForAgent
+
+The `scoreEventForAgent` function ties everything together:
+
+```typescript
+function scoreEventForAgent(
+  event: StreamEvent,
+  agentId: string,
+  attention: AgentAttention
+): AttentionScore
+```
+
+It returns an `AttentionScore` with five fields:
+- `agentId` — Which agent evaluated this event
+- `score` — Overall relevance (0.0-1.0)
+- `breakdown` — The four dimension scores (`symbolMatch`, `pathMatch`, `conceptMatch`, `signalMatch`)
+- `shouldNominate` — Whether the score exceeds the agent's threshold
+- `quietReason` — Why the agent stayed quiet (if it did)
+
+The breakdown is valuable for debugging attention patterns. If an agent is not speaking up when expected, the breakdown shows which dimension scored low. If `symbolMatch = 0.0` but the event clearly involves the agent's domain, the agent's symbol patterns may need expanding.
+
+## DEFAULT_ATTENTION for Standard Roles
+
+Paradigm provides default attention configurations for five standard roles:
+
+**Architect** — Watches all flows (`$*`) and components (`#*`), concepts like `architecture`, `design`, `pattern`, `refactor`. Threshold 0.5.
+
+**Builder** — Watches source paths (`src/**`, `lib/**`, `packages/**`). Threshold 0.7.
+
+**Reviewer** — Watches concepts like `code quality`, `bug`, `smell`, `convention`. Threshold 0.6.
+
+**Tester** — Watches test paths (`**/*.test.*`, `**/*.spec.*`), concepts like `test`, `coverage`, `assertion`, and `error-encountered` signals. Threshold 0.5.
+
+**Security** — Watches gate symbols (`^*`), auth components (`#*-auth`, `#*-middleware`), auth paths (`auth/**`, `middleware/**`, `guards/**`), concepts like `permission`, `JWT`, `session`, `RBAC`, `XSS`, `injection`, and signals `gate-added` and `route-created`. Threshold 0.4.
+
+These defaults are overridable in the agent's `.agent` file via the `attention` field. A security agent working on a project with no web routes might raise its threshold to 0.6 and remove the path patterns.