@a-company/paradigm 3.15.0 → 3.16.0

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

@@ -574,10 +574,77 @@
         }
       ]
     },
+    {
+      "id": "protocols",
+      "title": "Protocols — Repeatable Patterns",
+      "content": "## Protocols — Repeatable Patterns\n\nAI agents routinely spend tens of thousands of tokens exploring codebases to reverse-engineer implementation patterns before they can start working. In a well-structured project, the answer to \"how do I add a new view?\" is the same every time: create a component file, create a store, register a route, add CSS. But this knowledge lives nowhere explicit, so every agent re-discovers it from scratch.\n\nProtocols solve this problem. They are procedural, step-by-step instructions with exact file references, learned from actual completed work. When an agent receives a task like \"add a Settings page,\" it first calls `paradigm_protocol_search` with the task description. If a matching protocol exists, the agent gets back ordered steps, an exemplar file to study, and freshness information -- all within a few hundred tokens instead of exploring for thousands.\n\n### Storage and Format\n\nProtocols are stored as `.protocol` files (YAML syntax, semantic extension) in `.paradigm/protocols/`. Each protocol has an ID, a name, a description, trigger phrases for fuzzy matching, tags for classification, an exemplar file (the canonical example to follow), and an ordered list of steps.\n\n```\n.paradigm/protocols/\n  index.yaml            # Auto-generated by reindex\n  add-view.protocol     # One file per protocol\n  add-api-route.protocol\n```\n\n### Step Types\n\nProtocol steps use four action types:\n\n- **create** -- Create a new file. Specifies `target` (the file to create, with placeholders) and `template_from` (an existing file to follow as a model).\n- **modify** -- Edit an existing file. Specifies `target`, `reference` (where in the file to make changes), and `notes` explaining what to add.\n- **run** -- Execute a command. Specifies `command` and `notes`.\n- **verify** -- Confirm something works. Specifies `notes` with what to check.\n\nSteps support placeholders: `{Name}` for PascalCase and `{name}` for kebab-case. When following the protocol, the agent substitutes the actual name.\n\n### Searching for Protocols\n\nThe primary entry point is `paradigm_protocol_search`. Pass a natural language task description and it returns matching protocols ranked by relevance.\n\n```\nparadigm_protocol_search({ task: \"add a new settings page\" })\n```\n\nThe search uses weighted fuzzy matching: trigger phrases (weight 3), tags (weight 2), name and description (weight 1), and step notes (weight 0.5). The protocol set per project is small (5-30 entries), so a full scan is efficient.\n\nTo get full details for a specific protocol, use `paradigm_protocol_get`:\n\n```\nparadigm_protocol_get({ id: \"P-add-view\" })\n```\n\n### Recording Protocols\n\nProtocols are captured *after* completing work, not before. Two paths lead to a new protocol:\n\n1. **Agent-initiated** -- After implementing a repeatable task, the agent calls `paradigm_protocol_record` with the steps it followed:\n\n```\nparadigm_protocol_record({\n  name: \"Add a new view\",\n  description: \"Create a new page with store, route, and CSS\",\n  trigger: [\"add view\", \"new page\", \"create view\"],\n  tags: [\"ui\", \"frontend\"],\n  exemplar: \"ui/src/views/LogsView.tsx\",\n  steps: [\n    { action: \"create\", target: \"ui/src/views/{Name}View.tsx\", template_from: \"ui/src/views/LogsView.tsx\" },\n    { action: \"modify\", target: \"ui/src/App.tsx\", reference: \"Route elements\", notes: \"Add Route\" },\n    { action: \"verify\", notes: \"Run build, check route loads\" }\n  ],\n  recorded_from: \"L-2026-03-01-001\"\n})\n```\n\n2. **Lore-prompted** -- When `paradigm_lore_record` is called, the response includes a `protocol_suggestion` if the session created new files following existing patterns. This nudges agents to capture repeatable work without manual intervention.\n\n### Freshness and Maintenance\n\nProtocols go stale as code evolves. Three mechanisms keep them fresh:\n\n- **Reindex validation** -- During `paradigm_reindex`, all protocol references are checked. Missing files mark the protocol as `broken`. An exemplar modified since `last_verified` marks it `stale`. All references valid means `current`.\n- **On-use refresh** -- After successfully following a protocol, the agent calls `paradigm_protocol_update` with `refresh: true` to bump `last_verified` and fix outdated references.\n- **Status visibility** -- `paradigm_status` includes protocol health (X current, Y stale, Z broken). Stale protocols surface naturally during normal workflow.\n\nYou can also explicitly validate protocols:\n\n```\nparadigm_protocol_validate({ id: \"P-add-view\" })\n```\n\n### The Workflow\n\nThe protocol workflow integrates into the Paradigm operational loop:\n\n1. **Before implementing**: Call `paradigm_protocol_search` with your task description. If a match exists, follow the steps -- skip codebase exploration.\n2. **During implementation**: Use the protocol's exemplar as a reference. Follow each step in order.\n3. **After completion**: If no protocol existed and the work was repeatable, record one. If a protocol existed and you followed it successfully, call `paradigm_protocol_update` to refresh its timestamp.\n\nThis creates a virtuous cycle: each agent session that follows a protocol validates it, and each session that does repeatable work without a protocol can create one for future agents.",
+      "keyConcepts": [
+        "Protocols as repeatable implementation patterns with exact file references",
+        "paradigm_protocol_search — find protocols by task description",
+        "paradigm_protocol_record — capture patterns after completing work",
+        "Step types: create, modify, run, verify",
+        "Freshness tracking: current, stale, broken",
+        "Lore integration: protocol_suggestion on repeatable work"
+      ],
+      "quiz": [
+        {
+          "id": "q1",
+          "question": "What is the PRIMARY purpose of Paradigm protocols?",
+          "choices": {
+            "A": "To enforce coding standards through automated linting",
+            "B": "To provide step-by-step implementation patterns that save agents from re-exploring codebases",
+            "C": "To track all changes made to the codebase in a history log",
+            "D": "To generate code automatically from templates",
+            "E": "To replace .purpose files with more detailed documentation"
+          },
+          "correct": "B",
+          "explanation": "Protocols are repeatable implementation patterns with exact file references. Their primary value is saving AI agents from spending thousands of tokens exploring a codebase to reverse-engineer patterns that are the same every time. They do not enforce linting (A), track history (C), generate code (D), or replace .purpose files (E)."
+        },
+        {
+          "id": "q2",
+          "question": "When should an agent call paradigm_protocol_search?",
+          "choices": {
+            "A": "After completing a task to verify the work matches a known pattern",
+            "B": "Before implementing a task, to check if a repeatable pattern already exists",
+            "C": "Only when the user explicitly asks for protocol guidance",
+            "D": "During reindex to validate protocol references",
+            "E": "When recording lore to check for protocol suggestions"
+          },
+          "correct": "B",
+          "explanation": "paradigm_protocol_search is the agent's first stop before exploring the codebase. When receiving a task like 'add a Settings page,' the agent searches for a matching protocol BEFORE spending tokens on exploration. If a match exists, the steps and exemplar provide everything needed. After completion (A) is when you record or refresh, not search."
+        },
+        {
+          "id": "q3",
+          "question": "When are protocols recorded?",
+          "choices": {
+            "A": "Before starting work, to plan the implementation steps",
+            "B": "During implementation, as each step is completed",
+            "C": "After completing work, capturing the steps that were actually followed",
+            "D": "During reindex, by analyzing git history",
+            "E": "Only by project maintainers, never by AI agents"
+          },
+          "correct": "C",
+          "explanation": "Protocols are captured AFTER completing work, not before. This ensures the steps reflect what actually works, not what was planned. Two paths lead to recording: agent-initiated (calling paradigm_protocol_record with the steps followed) and lore-prompted (the lore_record response includes a protocol_suggestion hint when it detects repeatable patterns)."
+        },
+        {
+          "id": "q4",
+          "question": "A protocol's status is 'stale'. What does this mean?",
+          "choices": {
+            "A": "The protocol has a syntax error in its YAML",
+            "B": "The protocol's exemplar file has been modified since the protocol was last verified",
+            "C": "The protocol has never been used by any agent",
+            "D": "The protocol references files that no longer exist",
+            "E": "The protocol was recorded more than 30 days ago"
+          },
+          "correct": "B",
+          "explanation": "A 'stale' status means the protocol's exemplar or referenced files have been modified since last_verified — the protocol's steps might no longer match the actual code patterns. 'Broken' (D) means referenced files are missing entirely. Stale protocols still work but should be reviewed and refreshed after successful use."
+        }
+      ]
+    },
     {
       "id": "operations-review",
       "title": "Operational Excellence",
-      "content": "## Operational Excellence\n\nThis lesson brings together everything from PARA 301 into a cohesive daily workflow. Operational excellence in Paradigm is not about memorizing individual tools -- it is about building habits that keep your project healthy, your metadata accurate, and your development sessions productive.\n\n### The Operational Loop\n\nEvery development session follows a predictable pattern:\n\n**1. Orient** -- Start by calling `paradigm_status` to see the project overview: how many symbols are defined, recent changes, any outstanding issues. If this is a continuation session, call `paradigm_session_recover` to load context from the previous session.\n\n**2. Discover** -- Before touching code, understand the area you will work in. Call `paradigm_wisdom_context` with the symbols you plan to modify to learn team conventions and avoid known pitfalls. Use `paradigm_navigate` with the \"context\" intent to find all relevant files for your task.\n\n**3. Assess Risk** -- Run `paradigm_ripple` on every symbol you plan to modify to understand the blast radius. Check `paradigm_history_fragility` on anything flagged as a dependency. If the task is complex (3+ files, security + implementation), call `paradigm_orchestrate_inline` with mode=\"plan\" to get the right agent team.\n\n**4. Implement** -- Write code, updating `.purpose` files as you go. If you add routes, update `portal.yaml`. If you add signals, register them. Do not defer metadata updates to \"later\" -- later never comes.\n\n**5. Validate** -- Run `paradigm doctor` or `paradigm_purpose_validate` to catch any drift. Use `paradigm_flow_validate` if you modified flows. Record the implementation with `paradigm_history_record`.\n\n**6. Capture Knowledge** -- Did you discover an antipattern? Record it with `paradigm_wisdom_record`. Did you make an architectural decision? Record that too. Did the implementation reveal a fragile area? Note it for the team.\n\n**7. Monitor Context** -- Check `paradigm_context_check` periodically. If approaching limits, prepare a handoff.\n\n### Common Pitfalls\n\n- **Skipping wisdom checks**: Leads to repeating mistakes the team already knows about\n- **Skipping ripple analysis**: Leads to breaking downstream dependencies\n- **Deferring metadata updates**: Leads to stale `.purpose` files and misleading navigation\n- **Ignoring fragility warnings**: Leads to cascading failures in unstable areas\n- **Not recording history**: Loses the trail that fragility analysis depends on\n\n### The Measure of Excellence\n\nA well-operated Paradigm project has: accurate `.purpose` files that match the code, a `portal.yaml` that reflects all protected routes, wisdom entries that prevent repeated mistakes, history records that enable fragility analysis, and context handoffs that allow seamless multi-session work. When all of these are in place, every AI agent session starts with full context and every change is informed by the project's complete institutional knowledge.",
+      "content": "## Operational Excellence\n\nThis lesson brings together everything from PARA 301 into a cohesive daily workflow. Operational excellence in Paradigm is not about memorizing individual tools -- it is about building habits that keep your project healthy, your metadata accurate, and your development sessions productive.\n\n### The Operational Loop\n\nEvery development session follows a predictable pattern:\n\n**1. Orient** -- Start by calling `paradigm_status` to see the project overview: how many symbols are defined, recent changes, any outstanding issues. If this is a continuation session, call `paradigm_session_recover` to load context from the previous session.\n\n**2. Discover** -- Before touching code, check for existing protocols: call `paradigm_protocol_search` with your task description. If a match exists, follow its steps and skip exploration. Otherwise, call `paradigm_wisdom_context` with the symbols you plan to modify to learn team conventions and avoid known pitfalls. Use `paradigm_navigate` with the \"context\" intent to find all relevant files for your task.\n\n**3. Assess Risk** -- Run `paradigm_ripple` on every symbol you plan to modify to understand the blast radius. Check `paradigm_history_fragility` on anything flagged as a dependency. If the task is complex (3+ files, security + implementation), call `paradigm_orchestrate_inline` with mode=\"plan\" to get the right agent team.\n\n**4. Implement** -- Write code, updating `.purpose` files as you go. If you add routes, update `portal.yaml`. If you add signals, register them. Do not defer metadata updates to \"later\" -- later never comes.\n\n**5. Validate** -- Run `paradigm doctor` or `paradigm_purpose_validate` to catch any drift. Use `paradigm_flow_validate` if you modified flows. Record the implementation with `paradigm_history_record`.\n\n**6. Capture Knowledge** -- Did you discover an antipattern? Record it with `paradigm_wisdom_record`. Did you make an architectural decision? Record that too. Did the implementation follow a repeatable pattern? Record a protocol with `paradigm_protocol_record`. Did the implementation reveal a fragile area? Note it for the team.\n\n**7. Monitor Context** -- Check `paradigm_context_check` periodically. If approaching limits, prepare a handoff.\n\n### Common Pitfalls\n\n- **Skipping wisdom checks**: Leads to repeating mistakes the team already knows about\n- **Skipping ripple analysis**: Leads to breaking downstream dependencies\n- **Deferring metadata updates**: Leads to stale `.purpose` files and misleading navigation\n- **Ignoring fragility warnings**: Leads to cascading failures in unstable areas\n- **Not recording history**: Loses the trail that fragility analysis depends on\n\n### The Measure of Excellence\n\nA well-operated Paradigm project has: accurate `.purpose` files that match the code, a `portal.yaml` that reflects all protected routes, wisdom entries that prevent repeated mistakes, history records that enable fragility analysis, and context handoffs that allow seamless multi-session work. When all of these are in place, every AI agent session starts with full context and every change is informed by the project's complete institutional knowledge.",
       "keyConcepts": [
         "The operational loop: orient, discover, assess, implement, validate, capture, monitor",
         "Combining tools for comprehensive safety",

package/dist/university-content/plsat/v3.0.json

@@ -2,10 +2,10 @@
   "version": "3.0",
   "frameworkVersion": "2.0",
   "timeLimit": 5400,
-  "totalSlots": 90,
+  "totalSlots": 99,
   "passThreshold": 0.8,
   "title": "The PLSAT \u2014 Paradigm Licensure Standardized Assessment Test",
-  "description": "90 questions. 90 minutes. 80% to pass. Good luck, scholar.",
+  "description": "99 questions. 90 minutes. 80% to pass. Good luck, scholar.",
   "items": [
     {
       "type": "standalone",
@@ -2279,6 +2279,111 @@
           "explanation": "Paradigm's three-layer knowledge model is: Commits (raw facts \u2014 what code changed, captured by git), Lore (session events \u2014 what happened during a work session and why, captured by the post-commit hook into `.paradigm/history/`), and Assessments (synthesized insight \u2014 what the team learned across multiple sessions, recorded into `.paradigm/assessments/`). Each layer adds interpretation: commits are mechanical diffs, lore adds narrative context, and assessments distill patterns and decisions. All three layers persist and remain valuable \u2014 none replaces or supersedes the others."
         }
       ]
+    },
+    {
+      "type": "standalone",
+      "slot": "slot-094",
+      "course": "para-301",
+      "variants": [
+        {
+          "id": "plsat-094",
+          "scenario": "You receive a task: \"Add a new Settings page to the application.\" The project has a `.paradigm/protocols/` directory with several `.protocol` files. You know that previous agents added similar pages (Logs, Events, Dashboard) following the same pattern each time.",
+          "question": "What should you do FIRST before exploring the codebase?",
+          "choices": {
+            "A": "Read every existing page component to understand the pattern",
+            "B": "Call `paradigm_protocol_search` with your task description to check for a matching protocol",
+            "C": "Call `paradigm_lore_record` to document that you are starting the task",
+            "D": "Call `paradigm_protocol_record` to create a new protocol for the Settings page",
+            "E": "Read the `.paradigm/protocols/index.yaml` file directly to scan for relevant entries"
+          },
+          "correct": "B",
+          "explanation": "paradigm_protocol_search is the agent's first stop before exploring the codebase. It takes a natural language task description and returns matching protocols with steps, exemplar files, and freshness info — typically saving thousands of exploration tokens. Reading existing pages (A) is exactly the expensive exploration that protocols prevent. Recording lore (C) is done after work, not before. Recording a protocol (D) is done after completing repeatable work. Reading index.yaml directly (E) bypasses the fuzzy search that matches task descriptions to protocols."
+        },
+        {
+          "id": "plsat-094b",
+          "scenario": "An agent needs to add a new API endpoint to the project. The project has 15 recorded protocols covering common tasks. The agent calls `paradigm_protocol_search({ task: \"add a new API endpoint\" })` and gets back a protocol with 4 steps: create route file, add handler, register route, verify with build.",
+          "question": "What should the agent do next?",
+          "choices": {
+            "A": "Ignore the protocol and explore the codebase to find its own approach",
+            "B": "Call `paradigm_protocol_get` with the protocol ID to get full details, then follow the steps using the exemplar as reference",
+            "C": "Call `paradigm_protocol_record` to save the protocol it just found",
+            "D": "Run `paradigm_reindex` to make sure the protocol is up to date",
+            "E": "Call `paradigm_protocol_validate` to check all protocols before proceeding"
+          },
+          "correct": "B",
+          "explanation": "After finding a matching protocol via search, the next step is paradigm_protocol_get to retrieve full details (including the exemplar file path and detailed step notes), then follow the steps. The exemplar is the canonical file to study for the pattern. Ignoring the protocol (A) wastes the lookup. Recording (C) is for new protocols. Reindex (D) and full validation (E) are maintenance operations, not implementation steps."
+        }
+      ]
+    },
+    {
+      "type": "standalone",
+      "slot": "slot-095",
+      "course": "para-301",
+      "variants": [
+        {
+          "id": "plsat-095",
+          "scenario": "An agent just finished adding a new Sentinel event schema — the third such schema added to the project this month. Each time, the agent followed the same steps: create a schema file, register it in the schema index, add a migration, and verify. No protocol exists for this task yet.",
+          "question": "What should the agent do regarding protocols?",
+          "choices": {
+            "A": "Nothing — protocols are only created by project maintainers, not agents",
+            "B": "Call `paradigm_protocol_record` to capture the repeatable pattern it just followed",
+            "C": "Edit an existing protocol to add the schema steps as a sub-procedure",
+            "D": "Wait for `paradigm_reindex` to auto-generate a protocol from git history",
+            "E": "File an issue asking a human to write the protocol later"
+          },
+          "correct": "B",
+          "explanation": "Protocols are captured AFTER completing work, by the agent that did the work. When an agent completes a repeatable task and no protocol existed, it should call paradigm_protocol_record with the steps it followed, trigger phrases, tags, and an exemplar file. This ensures the next agent that receives a similar task can skip exploration entirely. Reindex (D) validates existing protocols but does not auto-generate new ones from git history."
+        },
+        {
+          "id": "plsat-095b",
+          "scenario": "After recording lore for a session where the agent created two new view components following the existing LogsView pattern, the `paradigm_lore_record` response includes a `protocol_suggestion` field with a draft protocol.",
+          "question": "What triggered this protocol suggestion?",
+          "choices": {
+            "A": "The agent explicitly asked for protocol suggestions in the lore_record call",
+            "B": "The lore system detected that the session created new files following existing patterns in the same directory",
+            "C": "All lore entries automatically include protocol suggestions",
+            "D": "The protocol suggestion was cached from a previous session",
+            "E": "The lore system runs paradigm_protocol_search on every lore entry"
+          },
+          "correct": "B",
+          "explanation": "When paradigm_lore_record is called, it runs a detection heuristic: if the session created 2+ new files in a directory that already has similar files, or modified the same 'registration' files that existing protocols touch, it includes a protocol_suggestion in the response. This nudges agents to capture repeatable patterns without manual intervention. Not all lore entries trigger suggestions (C) — only those with detectable repeatable patterns."
+        }
+      ]
+    },
+    {
+      "type": "standalone",
+      "slot": "slot-096",
+      "course": "para-301",
+      "variants": [
+        {
+          "id": "plsat-096",
+          "scenario": "During `paradigm_reindex`, the system validates all protocols. Protocol P-add-view references `ui/src/views/LogsView.tsx` as its exemplar. The file still exists but was significantly refactored two weeks after the protocol was last verified.",
+          "question": "What status will the reindex assign to this protocol?",
+          "choices": {
+            "A": "`current` — the file still exists, so the protocol is valid",
+            "B": "`stale` — the exemplar has been modified since the protocol was last verified",
+            "C": "`broken` — any change to a referenced file invalidates the protocol",
+            "D": "`deprecated` — protocols older than 30 days are automatically deprecated",
+            "E": "`unknown` — reindex cannot determine status without running the protocol"
+          },
+          "correct": "B",
+          "explanation": "During reindex validation, a protocol is marked 'stale' when its exemplar or referenced files have been modified since last_verified. The file still exists (so it is not 'broken'), but the protocol's steps might no longer match the current code pattern. A 'broken' status (C) is reserved for when referenced files are missing entirely. Stale protocols still work but should be reviewed and refreshed after successful use via paradigm_protocol_update with refresh: true."
+        },
+        {
+          "id": "plsat-096b",
+          "scenario": "An agent calls `paradigm_protocol_validate({ id: \"P-add-api-route\" })`. The protocol's step 2 references the file `src/routes/index.ts`, but that file was deleted during a recent refactoring.",
+          "question": "What status will the validation assign?",
+          "choices": {
+            "A": "`stale` — a referenced file has changed",
+            "B": "`current` — the protocol itself is still syntactically valid",
+            "C": "`broken` — a referenced file no longer exists",
+            "D": "`warning` — the file might be temporarily missing",
+            "E": "`archived` — protocols with missing references are auto-archived"
+          },
+          "correct": "C",
+          "explanation": "A 'broken' status means one or more files referenced by the protocol (targets, exemplars, or template_from) no longer exist. This is more severe than 'stale' (where files exist but have been modified). A broken protocol cannot be reliably followed until its references are updated to point to existing files via paradigm_protocol_update."
+        }
+      ]
     }
   ]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@a-company/paradigm",
-  "version": "3.15.0",
+  "version": "3.16.0",
   "description": "Unified CLI for Paradigm developer tools",
   "type": "module",
   "main": "./dist/index.js",