@a-company/paradigm 5.4.0 → 5.6.0

package/dist/mcp.js

@@ -1,4 +1,9 @@
 #!/usr/bin/env node
+import {
+  getDecisionSummary,
+  loadDecisions,
+  recordDecision
+} from "./chunk-EZ3GOCYC.js";
 import {
   addStep,
   addToolBreadcrumb,
@@ -74,7 +79,7 @@ import {
   validateProtocol,
   validatePurposeFile,
   validateUniversityContent
-} from "./chunk-7HRBT23N.js";
+} from "./chunk-SU3WDCRR.js";
 import "./chunk-L27I3CPZ.js";
 import {
   getWorkLogSummary,
@@ -84,7 +89,8 @@ import {
 import {
   getPluginUpdateNotice,
   schedulePluginUpdateCheck
-} from "./chunk-MP73YDXF.js";
+} from "./chunk-5EWAQHFY.js";
+import "./chunk-SDDCVUCV.js";
 import {
   completeTask,
   createTask,
@@ -127,7 +133,7 @@ import {
   queryEvents,
   resolveDebate,
   searchNotebooks
-} from "./chunk-ICSLIPUS.js";
+} from "./chunk-B2RC3HEB.js";
 import {
   buildProfileEnrichment,
   init_agent_loader,
@@ -136,7 +142,7 @@ import {
   queryExpertise,
   saveAgentProfile,
   verifyIntegrity
-} from "./chunk-A2L4TSLZ.js";
+} from "./chunk-ITPJJIHG.js";
 import {
   getJournalStats,
   init_journal_loader,
@@ -152,11 +158,6 @@ import {
   TimelineBuilder,
   loadAllSeedPatterns
 } from "./chunk-ZDHLG5VP.js";
-import {
-  getDecisionSummary,
-  loadDecisions,
-  recordDecision
-} from "./chunk-EZ3GOCYC.js";
 import {
   __esm,
   __export,
@@ -2249,35 +2250,108 @@ paradigm_flows_affected({ symbol: "#tasks" })
 \`\`\``
   },
   "orchestration": {
-    description: "Multi-agent orchestration \u2014 team commands, agent suggestions, faceted/solo modes",
-    generate: () => `# Multi-Agent Orchestration
+    description: "Maestro team orchestration \u2014 attributed responses, ambient context, learning loop, bench/activate, documentor agent",
+    generate: () => `# Maestro Team Orchestration
 
-Paradigm supports multi-agent orchestration via \`paradigm team\` commands.
+The Maestro model: the active Claude Code session orchestrates domain-specific subagents, makes their contributions visible as distinct attributed messages, and learns from feedback to improve agent performance over time.
 
-## Commands
+## How Maestro Works
 
-| Command | Description |
-|---------|-------------|
-| \`paradigm team spawn <agent> --task "..."\` | Spawn a single agent |
-| \`paradigm team orchestrate "task"\` | AI orchestrator coordinates agents |
-| \`paradigm team orchestrate "task" --solo\` | Single Claude mode (no splitting) |
-| \`paradigm team orchestrate "task" --compare\` | A/B test solo vs faceted |
-| \`paradigm team agents suggest "task"\` | Suggest agents based on task triggers |
-| \`paradigm team providers\` | Show available providers |
-| \`paradigm team models\` | View/configure agent model assignments |
+1. **Evaluate expertise** \u2014 Which agents have the highest confidence scores on relevant symbols?
+2. **Load ambient context** \u2014 Recent team decisions, journal insights, and pending nominations are injected into each agent's prompt via \`buildProfileEnrichment()\`.
+3. **Spawn subagents** \u2014 Each agent receives its full profile: personality, expertise history, transferable patterns, notebook entries, and ambient context.
+4. **Present attributed responses** \u2014 Each agent's response appears with a \`[role]\` or \`[nickname (role)]\` prefix. Do NOT synthesize \u2014 show distinct contributions.
+5. **Record to Symphony** \u2014 Each contribution is written as a Symphony message to \`thr-orch-*\` thread for Conductor/Platform visibility.
+6. **Learn from feedback** \u2014 At session end, Maestro reads the session work log and writes targeted journal entries per agent.
 
-## Agent Suggestions
+## Attributed Responses
 
-Before orchestrating, preview which agents will be involved:
+When presenting agent responses, use the \`attribution\` field from orchestration output:
+- \`[architect]\` \u2014 default format
+- \`[George (architect)]\` \u2014 if agent has a \`nickname\` in its profile
 
-\`\`\`bash
-paradigm team agents suggest "Add user authentication with JWT"
-\`\`\`
+Do NOT combine or summarize multiple agents into one response. Each agent speaks for itself.
 
-Or via MCP (returns \`suggestedAgents\` in plan mode):
-\`\`\`
-paradigm_orchestrate_inline({ task: "...", mode: "plan" })
-\`\`\``
+## Agent Roster
+
+| Agent | Model | Role |
+|-------|-------|------|
+| architect | opus | Design, specifications, file plans |
+| builder | haiku | Implementation from specs |
+| security | opus | Auth, permissions, vulnerability review |
+| reviewer | sonnet | Code quality, patterns, conventions |
+| tester | haiku | Test coverage, assertions |
+| documentor | haiku | .purpose, portal.yaml, symbol updates (always final stage) |
+
+### Bench / Activate
+
+Silence a noisy agent without deleting its profile:
+- \`paradigm agent bench security\` \u2014 Maestro and nomination engine skip this agent
+- \`paradigm agent activate security\` \u2014 restore to active orchestration
+- \`paradigm agent roster\` \u2014 see active vs benched with stats
+
+### Documentor Agent
+
+The documentor always runs as the **final orchestration stage**. It:
+- Reviews what other agents changed
+- Updates .purpose files, portal.yaml, and symbol registrations
+- Uses only \`paradigm_purpose_*\` and \`paradigm_portal_*\` MCP tools
+- Runs \`paradigm_reindex\` when done
+- Never modifies source code
+
+This relieves all other agents of Paradigm file maintenance.
+
+## Session Work Log
+
+During a session, a running log captures:
+- **Agent contributions** \u2014 what each agent was asked to do (from orchestration)
+- **User verdicts** \u2014 accepted / dismissed / revised, with reason (from ambient engage)
+
+Stored at \`.paradigm/events/session-log.jsonl\`. Read by Maestro at postflight.
+
+## Learning Loop
+
+At session end (via postflight skill Step 8b):
+
+1. **Read session work log** \u2014 cross-reference contributions with verdicts
+2. **Write journal entries** \u2014 targeted feedback per agent:
+   - Accepted \u2192 \`human_feedback\` trigger, high confidence, extractable pattern
+   - Dismissed \u2192 \`correction_received\` trigger, low confidence, explains what was wrong
+   - Revised \u2192 \`correction_received\` trigger, medium confidence, includes delta
+3. **Adjust thresholds** \u2014 \`paradigm_ambient_learn\` per agent
+4. **Promote to notebooks** \u2014 \`paradigm_ambient_promote\` auto-promotes high-confidence journal entries
+
+Journal entries with patterns flow through to notebooks, which appear in future \`buildProfileEnrichment()\` calls. This is how agents accumulate domain knowledge.
+
+## Training New Behaviors
+
+To teach an agent a new skill (e.g., "documentor should also draft CHANGELOG entries"):
+1. Tell the agent during the session \u2014 Maestro records the instruction
+2. The postflight pass writes a \`human_feedback\` journal entry with the new behavior
+3. On promotion, it becomes a notebook entry
+4. Next session, \`buildProfileEnrichment()\` injects that knowledge into the agent's context
+
+No configuration needed \u2014 the learning pipeline IS the training mechanism.
+
+## Neverland Validation
+
+Track learning progress with \`paradigm_ambient_neverland\`:
+- Per-agent: acceptance rate, threshold, expertise count, notebook count
+- Aggregate: average accept rate, total expertise, total notebooks
+- Health status: cold-start \u2192 accumulating \u2192 calibrating \u2192 mature
+- Target: >80% routing accuracy by session 10, >70% acceptance rate
+
+## MCP Tools
+
+| Tool | Purpose |
+|------|---------|
+| \`paradigm_orchestrate_inline\` | Plan (mode=plan) or execute (mode=execute) multi-agent orchestration |
+| \`paradigm_agent_prompt\` | Get enriched prompt for a single agent |
+| \`paradigm_agent_list\` | List all agents with expertise + bench status |
+| \`paradigm_agent_bench\` | Bench an agent |
+| \`paradigm_agent_activate\` | Activate a benched agent |
+| \`paradigm_ambient_neverland\` | Neverland validation metrics |
+| \`paradigm_context_compose\` | Compose full ambient context for an agent |`
   },
   "workspaces": {
     description: "Multi-project workspaces \u2014 setup, cross-project tools, reindexing",
@@ -5618,7 +5692,8 @@ var DEFAULT_MODELS = {
   security: "opus",
   reviewer: "sonnet",
   builder: "haiku",
-  tester: "haiku"
+  tester: "haiku",
+  documentor: "haiku"
 };
 var AGENT_TOKEN_ESTIMATES = {
   architect: { min: 5e3, max: 2e4 },
@@ -5782,7 +5857,35 @@ You flag issues but do NOT implement fixes - hand to Builder for that.
 ## What You DON'T Do
 - Implement security fixes yourself
 - Skip checking ^gate routes
-- Approve code with known vulnerabilities`
+- Approve code with known vulnerabilities`,
+  documentor: `You are the DOCUMENTOR agent.
+
+## Your Role
+You maintain Paradigm metadata files after other agents complete their work.
+You are the ONLY agent responsible for .purpose files, portal.yaml, and symbol registrations.
+Other agents focus on their domain \u2014 you handle all Paradigm compliance.
+
+## Key Responsibilities
+1. Review what other agents changed (read git diff, session work log)
+2. Update .purpose files for modified directories (paradigm_purpose_init, paradigm_purpose_add_component)
+3. Update portal.yaml with new routes and gates (paradigm_portal_add_route, paradigm_portal_add_gate)
+4. Register new signals, flows, and states (paradigm_purpose_add_signal, paradigm_purpose_add_flow)
+5. Run paradigm_reindex when done to rebuild the symbol index
+6. Ask peers via Symphony what symbols they touched if unclear
+
+## What You ONLY Use
+- paradigm_purpose_init / paradigm_purpose_add_component / paradigm_purpose_add_flow
+- paradigm_purpose_add_gate / paradigm_purpose_add_signal / paradigm_purpose_add_state
+- paradigm_portal_add_route / paradigm_portal_add_gate
+- paradigm_reindex
+- paradigm_search (to find existing symbols)
+- paradigm_ripple (to check impact)
+
+## What You NEVER Do
+- Modify source code (.ts, .js, .py, .rs files)
+- Write implementation code
+- Change application logic
+- Skip .purpose coverage for new code directories`
 };
 function getOrchestrationToolsList() {
   return [
@@ -5918,10 +6021,10 @@ async function handleOrchestrateInline(args, ctx) {
   }
   let agentProfiles = /* @__PURE__ */ new Map();
   try {
-    const { loadAgentProfile: loadAgentProfile2, buildProfileEnrichment: buildProfileEnrichment2 } = await import("./agent-loader-SJPJJS33.js");
+    const { loadAgentProfile: loadAgentProfile2, buildProfileEnrichment: buildProfileEnrichment2 } = await import("./agent-loader-DBF4OARL.js");
     const { loadDecisions: loadDecisions3 } = await import("./decision-loader-WWCLIQPJ.js");
     const { loadJournalEntries: loadJournalEntries2 } = await import("./journal-loader-5EYSBFFY.js");
-    const { loadNominations: loadNominations2 } = await import("./nomination-engine-HDWMN4IO.js");
+    const { loadNominations: loadNominations2 } = await import("./nomination-engine-LPLCCDW2.js");
     const recentDecisions = loadDecisions3(ctx.rootDir, { status: "active", limit: 5 }).map((d) => ({ title: d.title, decision: d.decision.slice(0, 150) }));
     const pendingNominations = loadNominations2(ctx.rootDir, { pending_only: true, limit: 10 }).map((n) => ({ urgency: n.urgency, brief: n.brief }));
     for (const stage of plan.stages) {
@@ -5992,6 +6095,22 @@ async function handleOrchestrateInline(args, ctx) {
   }
   const orchestrationId = `orch-${Date.now().toString(36)}-${Math.random().toString(36).substring(2, 6)}`;
   logOrchestration(ctx.rootDir, orchestrationId, task, plan);
+  try {
+    const { appendSessionWorkEntry } = await import("./session-work-log-KDOH4GER.js");
+    for (const stage of stagePrompts) {
+      for (const agent of stage.agents) {
+        appendSessionWorkEntry(ctx.rootDir, {
+          timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+          type: "agent-contribution",
+          agent: agent.agent,
+          contribution: agent.taskDescription?.slice(0, 200) || task.slice(0, 200),
+          attribution: agent.attribution,
+          symbols
+        });
+      }
+    }
+  } catch {
+  }
   const result = {
     orchestrationId,
     task,
@@ -6075,10 +6194,10 @@ async function handleAgentPrompt(args, ctx) {
   let profileEnrichment;
   let nickname;
   try {
-    const { loadAgentProfile: loadAgentProfile2, buildProfileEnrichment: buildProfileEnrichment2 } = await import("./agent-loader-SJPJJS33.js");
+    const { loadAgentProfile: loadAgentProfile2, buildProfileEnrichment: buildProfileEnrichment2 } = await import("./agent-loader-DBF4OARL.js");
     const { loadDecisions: loadDecisions3 } = await import("./decision-loader-WWCLIQPJ.js");
     const { loadJournalEntries: loadJournalEntries2 } = await import("./journal-loader-5EYSBFFY.js");
-    const { loadNominations: loadNominations2 } = await import("./nomination-engine-HDWMN4IO.js");
+    const { loadNominations: loadNominations2 } = await import("./nomination-engine-LPLCCDW2.js");
     const profile = loadAgentProfile2(ctx.rootDir, agentName);
     if (profile) {
       nickname = profile.nickname;
@@ -6257,6 +6376,17 @@ function planAgentSequence(task, agents, agentOverride, classification) {
       canRunParallel: stageAgents.length > 1
     });
   }
+  const lastStageNum = sortedStages.length > 0 ? sortedStages[sortedStages.length - 1] + 1 : 0;
+  stages.push({
+    stage: lastStageNum,
+    agents: [{
+      name: "documentor",
+      task: "Review all changes made by previous agents. Update .purpose files, portal.yaml, and symbol registrations using only paradigm_purpose_* and paradigm_portal_* MCP tools. Run paradigm_reindex when done. Do NOT modify source code.",
+      dependsOn: plannedAgents.map((a) => a.name),
+      required: true
+    }],
+    canRunParallel: false
+  });
   let minTokens = 0;
   let maxTokens = 0;
   for (const agent of plannedAgents) {
@@ -6264,12 +6394,15 @@ function planAgentSequence(task, agents, agentOverride, classification) {
     minTokens += estimate.min;
     maxTokens += estimate.max;
   }
+  minTokens += 2e3;
+  maxTokens += 8e3;
   return {
     task,
     mode: "faceted",
     stages,
     symbols,
-    estimatedAgents: plannedAgents.length,
+    estimatedAgents: plannedAgents.length + 1,
+    // +1 for documentor
     estimatedTokens: { min: minTokens, max: maxTokens }
   };
 }
@@ -9969,7 +10102,7 @@ async function handleLoreTool(name, args, ctx) {
       try {
         const agentId = process.env.PARADIGM_AGENT_ID;
         if (agentId && symbols_touched && symbols_touched.length > 0) {
-          const { updateExpertiseFromLore } = await import("./agent-loader-SJPJJS33.js");
+          const { updateExpertiseFromLore } = await import("./agent-loader-DBF4OARL.js");
           updateExpertiseFromLore(ctx.rootDir, agentId, {
             symbols_touched,
             confidence: confidence != null && confidence >= 0 && confidence <= 1 ? confidence : void 0
@@ -10140,7 +10273,7 @@ async function handleLoreTool(name, args, ctx) {
       try {
         const agentId = process.env.PARADIGM_AGENT_ID;
         if (agentId && success && entryToAssess.symbols_touched?.length) {
-          const { updateExpertiseFromAssessment } = await import("./agent-loader-SJPJJS33.js");
+          const { updateExpertiseFromAssessment } = await import("./agent-loader-DBF4OARL.js");
           updateExpertiseFromAssessment(ctx.rootDir, agentId, {
             symbols_touched: entryToAssess.symbols_touched,
             verdict
@@ -19567,7 +19700,7 @@ function getAmbientToolsList() {
           nomination_id: { type: "string", description: "Nomination ID to engage with" },
           response: { type: "string", enum: ["accepted", "dismissed", "deferred"], description: "How to respond" },
           resolve_debate: { type: "string", description: "Optional debate ID to resolve by choosing this nomination" },
-          reason: { type: "string", description: "Optional reason (used when resolving debates)" }
+          reason: { type: "string", description: "Reason for response \u2014 stored on nomination for learning feedback. Especially valuable for dismissals." }
         },
         required: ["nomination_id", "response"]
       },
@@ -19750,7 +19883,24 @@ async function handleAmbientTool(name, args, ctx) {
     case "paradigm_ambient_engage": {
       const nominationId = args.nomination_id;
       const response = args.response;
-      const engaged = engageNomination(ctx.rootDir, nominationId, response);
+      const reason = args.reason;
+      const engaged = engageNomination(ctx.rootDir, nominationId, response, reason);
+      if (engaged) {
+        try {
+          const { appendSessionWorkEntry } = await import("./session-work-log-KDOH4GER.js");
+          const noms = loadNominations(ctx.rootDir, { limit: 500 });
+          const nom = noms.find((n) => n.id === nominationId);
+          appendSessionWorkEntry(ctx.rootDir, {
+            timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+            type: "user-verdict",
+            agent: nom?.agent,
+            nominationId,
+            verdict: response,
+            reason
+          });
+        } catch {
+        }
+      }
       let debateResolved = false;
       if (args.resolve_debate && engaged) {
         debateResolved = resolveDebate(
@@ -20922,7 +21072,7 @@ function registerTools(server, getContext2, reloadContext2) {
             };
           }
           case "paradigm_plugin_check": {
-            const { runPluginUpdateCheck } = await import("./plugin-update-checker-ELOEEQYS.js");
+            const { runPluginUpdateCheck } = await import("./plugin-update-checker-KRRSGXMV.js");
             const results = await runPluginUpdateCheck();
             const updatable = results.filter((r) => r.hasRemoteUpdate || r.hasCacheStale);
             if (updatable.length === 0) {
@@ -20961,7 +21111,7 @@ Update command:
               trackToolCall(noWsText.length, name);
               return { content: [{ type: "text", text: noWsText }] };
             }
-            const { rebuildStaticFiles: rebuildStaticFiles2 } = await import("./reindex-65H4WULU.js");
+            const { rebuildStaticFiles: rebuildStaticFiles2 } = await import("./reindex-J5SEDVTT.js");
             const memberResults = [];
             for (const member of ctx.workspace.config.members) {
               const memberAbsPath = path34.resolve(path34.dirname(ctx.workspace.workspacePath), member.path);

package/dist/{nomination-engine-HDWMN4IO.js → nomination-engine-LPLCCDW2.js}

@@ -17,8 +17,8 @@ import {
   processEvent,
   processPendingEvents,
   resolveDebate
-} from "./chunk-ICSLIPUS.js";
-import "./chunk-A2L4TSLZ.js";
+} from "./chunk-B2RC3HEB.js";
+import "./chunk-ITPJJIHG.js";
 import "./chunk-MCMOGQMU.js";
 import "./chunk-7N7GSU6K.js";
 init_nomination_engine();

package/dist/{plugin-update-checker-ELOEEQYS.js → plugin-update-checker-KRRSGXMV.js}

@@ -3,7 +3,7 @@ import {
   getPluginUpdateNotice,
   runPluginUpdateCheck,
   schedulePluginUpdateCheck
-} from "./chunk-MP73YDXF.js";
+} from "./chunk-5EWAQHFY.js";
 import "./chunk-7N7GSU6K.js";
 export {
   getPluginUpdateNotice,

package/dist/{reindex-65H4WULU.js → reindex-J5SEDVTT.js}

@@ -3,8 +3,9 @@ import {
   getReindexToolsList,
   handleReindexTool,
   rebuildStaticFiles
-} from "./chunk-7HRBT23N.js";
+} from "./chunk-SU3WDCRR.js";
 import "./chunk-L27I3CPZ.js";
+import "./chunk-SDDCVUCV.js";
 import "./chunk-5VKJBNJL.js";
 import "./chunk-7N7GSU6K.js";
 export {

package/dist/session-work-log-KDOH4GER.js

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+import {
+  appendSessionWorkEntry,
+  clearSessionWorkLog,
+  getAgentEntries,
+  getAgentVerdicts,
+  getContributingAgents,
+  init_session_work_log,
+  readSessionWorkLog
+} from "./chunk-SDDCVUCV.js";
+import "./chunk-7N7GSU6K.js";
+init_session_work_log();
+export {
+  appendSessionWorkEntry,
+  clearSessionWorkLog,
+  getAgentEntries,
+  getAgentVerdicts,
+  getContributingAgents,
+  readSessionWorkLog
+};