nexus-prime 3.17.0 → 3.18.0

package/README.md

@@ -293,9 +293,9 @@ Read the full tiered market map: [Comparison](https://sir-ad.github.io/nexus-pri
 <details>
 <summary><b>🧭 Platform Feature Registry</b></summary>
 
-Generated from shared feature metadata at 2026-03-14T14:43:20.108Z.
+Generated from shared feature metadata at 2026-03-21T02:48:13.064Z.
 
-Inventory Snapshot: 109 skills · 64 workflows · 5 hooks · 3 automations · 7 crews · 139 specialists
+Inventory Snapshot: 109 skills · 64 workflows · 9 hooks · 5 automations · 7 crews · 139 specialists
 
 Control Plane Snapshot: 9 MCP surfaces · 6 client targets · 5 dashboard capabilities · 6 runtime subsystems · 5 release gates
 
@@ -310,11 +310,11 @@ Operator-facing entrypoints and expert control surfaces.
 | nexus_orchestrate | core MCP | Plan, select assets, execute through worktree-backed runtime, and persist truth. | Default raw-prompt execution path. |
 | nexus_plan_execution | planning MCP | Inspect the planner ledger before mutation. | Used when operators want a pre-run ledger. |
 | nexus_recall_memory / nexus_memory_stats / nexus_store_memory | memory MCP | Inspect and persist durable learnings. | Feeds the memory fabric and handoff flow. |
-| nexus_optimize_tokens | optimization MCP | Inspect or override source-aware token budgeting. | Manual/diagnostic surface; orchestration applies budgeting automatically. |
-| nexus_mindkit_check / nexus_ghost_pass / nexus_spawn_workers | safety + runtime MCP | Run governance preflight, pre-read analysis, and explicit swarm control. | Expert or low-level surfaces. |
+| nexus_optimize_tokens | optimization MCP | Generate a token-saving reading plan before broad file inspection. | Mandatory before reading 3+ files from client-visible intent. |
+| nexus_mindkit_check / nexus_ghost_pass / nexus_spawn_workers | safety + runtime MCP | Run governance preflight, refactor pre-flight analysis, and explicit swarm control. | Mindkit and ghost-pass are required lifecycle checks for risky or multi-file mutation. |
 | nexus_memory_export / import / backup / maintain / trace | memory portability MCP | Export, restore, maintain, and inspect local-first memory bundles. | Supports backup/resume and OpenClaw-oriented bridge packs. |
 | nexus_list_skills / workflows / hooks / automations / specialists / crews | catalog MCP | Expose what the runtime can activate. | Used for explicit operator control and diagnostics. |
-| nexus_run_status / nexus_federation_status / nexus_session_dna | runtime truth MCP | Inspect persisted run state, federation status, and handoff DNA. | Used after execution or during operating-layer work. |
+| nexus_run_status / nexus_federation_status / nexus_session_dna | runtime truth MCP | Inspect persisted run state, federation status, and handoff DNA. | Session DNA generation is mandatory before ending a meaningful session. |
 
 </details>
 
@@ -362,7 +362,7 @@ Core architecture layers that shape execution, memory, and visibility.
 | Source-Aware Token Budget | runtime subsystem | Allocates token budget across repo, memory, RAG, patterns, and runtime traces. | Persists selected and dropped context. |
 | Bootstrap Manifest Truth | runtime subsystem | Tracks configured client bootstrap artifacts independently from active heartbeats. | Supports installed vs active truth in the dashboard. |
 | Artifact Selection Audit | runtime subsystem | Explains why skills/workflows/crews/specialists were selected or rejected. | Persists auditable selection rationale. |
-| Bundled assets: 109 skills · 64 workflows · 5 hooks · 3 automations · 7 crews · 139 specialists | runtime subsystem | Summarizes the current bundled runtime inventory. | Detailed lists live in the runtime catalog section and dashboard catalog view. |
+| Bundled assets: 109 skills · 64 workflows · 9 hooks · 5 automations · 7 crews · 139 specialists | runtime subsystem | Summarizes the current bundled runtime inventory. | Detailed lists live in the runtime catalog section and dashboard catalog view. |
 
 </details>
 
@@ -390,7 +390,7 @@ Quality and security checks required before release.
 
 Generated from bundled runtime catalogs plus repo-local overrides via `npm run generate:readme-catalog`.
 
-Inventory Snapshot: 109 skills · 64 workflows · 5 hooks · 3 automations · 7 crews
+Inventory Snapshot: 109 skills · 64 workflows · 9 hooks · 5 automations · 7 crews
 
 <details>
 <summary><b>Skills</b> (109)</summary>
@@ -582,12 +582,16 @@ Inventory Snapshot: 109 skills · 64 workflows · 5 hooks · 3 automations · 7
 </details>
 
 <details>
-<summary><b>Hooks</b> (5)</summary>
+<summary><b>Hooks</b> (9)</summary>
 
 | Name | Type/Scope | Purpose | Trigger / When used |
 | --- | --- | --- | --- |
+| before-compaction-flush | read · base | Flush memory prefrontal to SQLite before context compaction. | before-compaction · context budget nearing limit |
+| before-mutate-guard | read · base | Local checkpoint before bounded file mutation. | before-mutate |
 | before-verify-approval | orchestrate · base | Attach approval-loop workflows before verification for domain work. | before-verify · verification checkpoint |
+| failure-summary | read · base | Local failure checkpoint for recovery notes and retry scope. | run.failed |
 | memory-shield-escalation | read · base | Flag stored memories for shield review when policy risk is detected. | memory.stored · high priority memory stored |
+| memory-stored-review | read · base | Local review hook for important stored memories. | memory.stored |
 | promotion-audit | read · base | Require a security-oriented audit note on promotion approval. | promotion.approved · promotion approved |
 | retry-narrow-scope | orchestrate · base | Focus retries on the failing surface after an error cluster. | retry · retry requested |
 | run-created-brief | read · base | Attach planning context and default orchestration on run creation. | run.created · run created |
@@ -595,12 +599,14 @@ Inventory Snapshot: 109 skills · 64 workflows · 5 hooks · 3 automations · 7
 </details>
 
 <details>
-<summary><b>Automations</b> (3)</summary>
+<summary><b>Automations</b> (5)</summary>
 
 | Name | Type/Scope | Purpose | Trigger / When used |
 | --- | --- | --- | --- |
+| failure-followup | event · base | Queue a bounded retry follow-up after a failed run. | event:run.failed |
 | failure-recovery-automation | event · base | Queue retry and review workflows after a failed run. | event:run.failed |
 | memory-governance-automation | event · base | Attach memory and security review after memory storage events. | event:memory.stored |
+| session-close-followup | event · base | Queue a bounded approval follow-up after a verified run. | event:run.verified |
 | verified-followup-automation | event · base | Queue a bounded approval workflow after a verified run. | event:run.verified |
 
 </details>
@@ -626,6 +632,17 @@ Inventory Snapshot: 109 skills · 64 workflows · 5 hooks · 3 automations · 7
 ## 📜 Release History
 
 <details open>
+<summary><b>v3.18.0</b> · 2026-03-21 · Lifecycle hardening across MCP, bootstrap artifacts, and release surfaces</summary>
+
+- **Lifecycle checklists and footers**: `nexus_session_bootstrap` now appends a mandatory protocol checklist, and `nexus_orchestrate` now appends a mandatory remaining-steps footer.
+- **Lifecycle warnings**: MCP responses now warn when 15+ post-orchestrate tool calls happen without `nexus_store_memory`, and when Nexus-visible 3+ file intent appears without `nexus_optimize_tokens`.
+- **Shared instruction closure**: `CLAUDE.md`, `AGENTS.md`, client bootstrap artifacts, and the feature registry now agree that `nexus_orchestrate` does not replace during-work or end-of-session lifecycle steps.
+- **Release-surface alignment**: Protocol, integrations, knowledge-base, README, and generated bootstrap surfaces now use the same mandatory lifecycle wording.
+
+Full notes: [releases/v3.18.0.md](./releases/v3.18.0.md) · Full history: [CHANGELOG.md](./CHANGELOG.md)
+</details>
+
+<details>
 <summary><b>v3.17.0</b> · 2026-03-20 · Agent adoption hardening, memory readability, atlas code intelligence peer</summary>
 
 - **Hard bootstrap enforcement**: Non-bootstrap MCP tool calls return a structured `blocked` response with next-step guidance instead of a soft warning agents ignored. Read-only tools remain exempt.

package/dist/agents/adapters/mcp.d.ts

@@ -24,6 +24,10 @@ export declare class MCPAdapter implements Adapter {
     private getRuntime;
     private getOrchestrator;
     private getToolProfile;
+    private formatProtocolChecklist;
+    private formatRemainingProtocolSteps;
+    private prependTextToResponse;
+    private decorateLifecycleResponse;
     private describeClientInstructionStatus;
     private finalizeToolDefinitions;
     private decorateToolDescription;

package/dist/agents/adapters/mcp.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mcp.d.ts","sourceRoot":"","sources":["../../../src/agents/adapters/mcp.ts"],"names":[],"mappings":"AAYA,OAAO,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAC3D,OAAO,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAiE5C,KAAK,cAAc,GAAG,YAAY,GAAG,MAAM,CAAC;AAC5C,KAAK,iBAAiB,GAAG;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACxC,CAAC;AAmKF,qBAAa,UAAW,YAAW,OAAO;IACtC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAG,KAAK,CAAU;IACtB,SAAS,UAAS;IAClB,MAAM,EAAE,MAAM,EAAE,CAAM;IAEtB,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,QAAQ,CAAC,CAAa;IAC9B,OAAO,CAAC,SAAS,CAA4C;IAC7D,OAAO,CAAC,UAAU,CAAoB;IACtC,OAAO,CAAC,OAAO,CAAC,CAAkB;IAElC,OAAO,CAAC,cAAc;IA+BtB,OAAO,CAAC,GAAG;;IAmBX,OAAO,CAAC,gBAAgB;IA4BxB,WAAW,CAAC,KAAK,EAAE,UAAU;IAI7B,OAAO,CAAC,UAAU;IAYlB,OAAO,CAAC,eAAe;IAOvB,OAAO,CAAC,cAAc;IAMtB,OAAO,CAAC,+BAA+B;IAMvC,OAAO,CAAC,uBAAuB;IAqB/B,OAAO,CAAC,uBAAuB;IAsB/B,cAAc,CAAC,OAAO,GAAE,cAAsC,GAAG,iBAAiB,EAAE;IAIpF,OAAO,CAAC,oBAAoB;IA8yB5B,OAAO,CAAC,iBAAiB;YAyFX,cAAc;IAy1D5B,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,EAAE;IAItC,OAAO,CAAC,IAAI;IAmBN,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAOxB,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAmB3B,IAAI,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;IAClD,OAAO,CAAC,OAAO,EAAE,cAAc,GAAG,IAAI;CACzC"}
+{"version":3,"file":"mcp.d.ts","sourceRoot":"","sources":["../../../src/agents/adapters/mcp.ts"],"names":[],"mappings":"AAYA,OAAO,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAC3D,OAAO,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAiE5C,KAAK,cAAc,GAAG,YAAY,GAAG,MAAM,CAAC;AAE5C,KAAK,iBAAiB,GAAG;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACxC,CAAC;AA4SF,qBAAa,UAAW,YAAW,OAAO;IACtC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAG,KAAK,CAAU;IACtB,SAAS,UAAS;IAClB,MAAM,EAAE,MAAM,EAAE,CAAM;IAEtB,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,QAAQ,CAAC,CAAa;IAC9B,OAAO,CAAC,SAAS,CAA4C;IAC7D,OAAO,CAAC,UAAU,CAAoB;IACtC,OAAO,CAAC,OAAO,CAAC,CAAkB;IAElC,OAAO,CAAC,cAAc;IA6BtB,OAAO,CAAC,GAAG;;IAmBX,OAAO,CAAC,gBAAgB;IA4BxB,WAAW,CAAC,KAAK,EAAE,UAAU;IAI7B,OAAO,CAAC,UAAU;IAYlB,OAAO,CAAC,eAAe;IAOvB,OAAO,CAAC,cAAc;IAMtB,OAAO,CAAC,uBAAuB;IAY/B,OAAO,CAAC,4BAA4B;IAWpC,OAAO,CAAC,qBAAqB;IAiB7B,OAAO,CAAC,yBAAyB;IA8BjC,OAAO,CAAC,+BAA+B;IAMvC,OAAO,CAAC,uBAAuB;IAqB/B,OAAO,CAAC,uBAAuB;IAkC/B,cAAc,CAAC,OAAO,GAAE,cAAsC,GAAG,iBAAiB,EAAE;IAIpF,OAAO,CAAC,oBAAoB;IA8yB5B,OAAO,CAAC,iBAAiB;YA4FX,cAAc;IA01D5B,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,EAAE;IAItC,OAAO,CAAC,IAAI;IAmBN,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAOxB,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAoB3B,IAAI,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;IAClD,OAAO,CAAC,OAAO,EAAE,cAAc,GAAG,IAAI;CACzC"}

package/dist/agents/adapters/mcp.js

@@ -130,11 +130,122 @@ class SessionTelemetry {
     tokensOptimized = 0;
     memoriesStored = 0;
     memoriesRecalled = 0;
+    lifecyclePhase = 'pre-bootstrap';
+    optimizeTokensCalled = false;
+    mindkitCheckCalled = false;
+    storeMemoryCalledPostOrchestrate = false;
+    sessionDnaCalled = false;
+    fileReadIntentCount = 0;
+    callsSinceOrchestrate = 0;
+    fileIntentPaths = new Set();
     bootstrapped = false;
-    recordCall() { this.callCount++; }
+    recordCall() {
+        this.callCount++;
+        if (this.isPostOrchestratePhase()) {
+            this.callsSinceOrchestrate++;
+        }
+    }
     recordTokens(saved) { this.tokensOptimized += saved; }
     recordStore() { this.memoriesStored++; }
     recordRecall(count) { this.memoriesRecalled += count; }
+    snapshot() {
+        return {
+            callCount: this.callCount,
+            tokensOptimized: this.tokensOptimized,
+            memoriesStored: this.memoriesStored,
+            memoriesRecalled: this.memoriesRecalled,
+            lifecyclePhase: this.lifecyclePhase,
+            optimizeTokensCalled: this.optimizeTokensCalled,
+            mindkitCheckCalled: this.mindkitCheckCalled,
+            storeMemoryCalledPostOrchestrate: this.storeMemoryCalledPostOrchestrate,
+            sessionDnaCalled: this.sessionDnaCalled,
+            fileReadIntentCount: this.fileReadIntentCount,
+            callsSinceOrchestrate: this.callsSinceOrchestrate,
+        };
+    }
+    advancePhase(nextPhase) {
+        if (this.lifecyclePhase === nextPhase)
+            return;
+        this.lifecyclePhase = nextPhase;
+        if (nextPhase === 'bootstrapped' || nextPhase === 'orchestrated') {
+            this.resetFileIntentTracking();
+            this.optimizeTokensCalled = false;
+        }
+        if (nextPhase === 'orchestrated') {
+            this.mindkitCheckCalled = false;
+            this.storeMemoryCalledPostOrchestrate = false;
+            this.sessionDnaCalled = false;
+            this.callsSinceOrchestrate = 0;
+        }
+    }
+    observeSuccessfulToolCall(toolName, args) {
+        if (toolName === 'nexus_session_bootstrap') {
+            this.bootstrapped = true;
+            this.advancePhase('bootstrapped');
+            this.noteFileIntent(args.files);
+            return;
+        }
+        if (toolName === 'nexus_orchestrate') {
+            this.advancePhase('orchestrated');
+            this.noteFileIntent(args.files);
+            return;
+        }
+        if (toolName === 'nexus_optimize_tokens') {
+            this.optimizeTokensCalled = true;
+            if (this.lifecyclePhase === 'orchestrated')
+                this.advancePhase('working');
+            this.noteFileIntent(args.files);
+            return;
+        }
+        if (toolName === 'nexus_mindkit_check') {
+            this.mindkitCheckCalled = true;
+            if (this.lifecyclePhase === 'orchestrated')
+                this.advancePhase('working');
+            this.noteFileIntent(args.filesToModify);
+            return;
+        }
+        if (toolName === 'nexus_ghost_pass') {
+            if (this.lifecyclePhase === 'orchestrated')
+                this.advancePhase('working');
+            this.noteFileIntent(args.files);
+            return;
+        }
+        if (toolName === 'nexus_store_memory') {
+            if (this.isPostOrchestratePhase()) {
+                this.storeMemoryCalledPostOrchestrate = true;
+            }
+            if (this.lifecyclePhase === 'orchestrated')
+                this.advancePhase('working');
+            return;
+        }
+        if (toolName === 'nexus_session_dna' && String(args.action ?? 'load') === 'generate') {
+            this.sessionDnaCalled = true;
+            this.advancePhase('closing');
+            return;
+        }
+        if (this.lifecyclePhase === 'orchestrated') {
+            this.advancePhase('working');
+        }
+    }
+    needsOptimizeTokens(currentToolName) {
+        if (currentToolName === 'nexus_optimize_tokens')
+            return false;
+        if (this.lifecyclePhase === 'pre-bootstrap')
+            return false;
+        return this.fileReadIntentCount >= 3 && !this.optimizeTokensCalled;
+    }
+    needsStoreMemory(currentToolName) {
+        if (currentToolName === 'nexus_store_memory')
+            return false;
+        return this.isPostOrchestratePhase()
+            && this.callsSinceOrchestrate >= 15
+            && !this.storeMemoryCalledPostOrchestrate;
+    }
+    needsSessionDna(currentToolName) {
+        if (currentToolName === 'nexus_session_dna')
+            return false;
+        return this.isPostOrchestratePhase() && !this.sessionDnaCalled;
+    }
     notifyStore(priority, tags, memStats) {
         return `\nMemory telemetry: priority ${priority.toFixed(2)} · tags ${tags.join(', ') || 'none'} · cortex ${memStats.cortex} · zettel ${memStats.totalLinks}`;
     }
@@ -175,14 +286,14 @@ class SessionTelemetry {
                 nudges.push('Guardrail FAILED. Do NOT proceed. Re-scope the task or call nexus_ghost_pass for a safer approach.');
                 break;
             case 'high_call_count':
-                if (this.callCount > 20) {
-                    nudges.push('20+ tool calls reached. Next: call nexus_store_memory with a session summary.');
+                if (this.callsSinceOrchestrate >= 15 && !this.storeMemoryCalledPostOrchestrate) {
+                    nudges.push('15+ post-orchestrate tool calls reached. Next: call nexus_store_memory with a session summary.');
                 }
                 break;
         }
         if (nudges.length === 0)
             return '';
-        return `\n<nexus-next-step>\n${nudges.map(n => `  → ${n}`).join('\n')}\n</nexus-next-step>`;
+        return `\n\nMANDATORY NEXT STEPS:\n${nudges.map((n) => `- ${n}`).join('\n')}\nDo NOT proceed without completing these steps.`;
     }
     format(memStats) {
         const uptime = Math.round((Date.now() - this.startTime) / 1000);
@@ -190,9 +301,30 @@ class SessionTelemetry {
         const parts = [
             `${this.callCount} calls`,
             memStats ? `${memStats.totalLinks} Zettel links` : null,
+            `phase ${this.lifecyclePhase}`,
         ].filter(Boolean);
         return `\nSession telemetry (${uptimeStr}): ${parts.join(' · ')}`;
     }
+    noteFileIntent(rawPaths) {
+        if (!Array.isArray(rawPaths))
+            return;
+        for (const rawPath of rawPaths) {
+            const normalized = String(rawPath || '').trim();
+            if (!normalized)
+                continue;
+            this.fileIntentPaths.add(normalized);
+        }
+        this.fileReadIntentCount = this.fileIntentPaths.size;
+    }
+    resetFileIntentTracking() {
+        this.fileIntentPaths.clear();
+        this.fileReadIntentCount = 0;
+    }
+    isPostOrchestratePhase() {
+        return this.lifecyclePhase === 'orchestrated'
+            || this.lifecyclePhase === 'working'
+            || this.lifecyclePhase === 'closing';
+    }
 }
 function formatBullets(lines) {
     return lines.filter(Boolean).map((line) => `- ${line}`).join('\n');
@@ -223,11 +355,9 @@ export class MCPAdapter {
         for (let i = 0; i < keys.length; i += 2) {
             const k1 = keys[i];
             const v1 = String(metrics[k1]).substring(0, 20);
-            const p1 = `\x1b[33m${k1}:\x1b[0m ${v1}`.padEnd(42, ' ');
             if (i + 1 < keys.length) {
                 const k2 = keys[i + 1];
                 const v2 = String(metrics[k2]).substring(0, 20);
-                const p2 = `\x1b[33m${k2}:\x1b[0m ${v2}`.padEnd(42, ' ');
                 // We have to hardcode padding because ansi escape codes mess with .padEnd length
                 console.error(`\x1b[36m║ \x1b[33m${k1}:\x1b[37m ${v1.padEnd(20, ' ')} │ \x1b[33m${k2}:\x1b[37m ${v2.padEnd(19, ' ')} \x1b[36m║\x1b[0m`);
             }
@@ -312,9 +442,60 @@ export class MCPAdapter {
             ? 'full'
             : 'autonomous';
     }
+    formatProtocolChecklist() {
+        return [
+            'PROTOCOL CHECKLIST (follow every step):',
+            '[x] nexus_session_bootstrap — DONE',
+            '[ ] nexus_orchestrate — Call NOW with the user\'s request',
+            '[ ] nexus_optimize_tokens — Call BEFORE reading 3+ files',
+            '[ ] nexus_mindkit_check — Call BEFORE any file modifications',
+            '[ ] nexus_store_memory — Call AFTER significant findings AND at session end',
+            '[ ] nexus_session_dna — Call BEFORE ending this session',
+        ].join('\n');
+    }
+    formatRemainingProtocolSteps() {
+        return [
+            'REMAINING PROTOCOL STEPS (MANDATORY):',
+            '- Call nexus_optimize_tokens(goal, files) BEFORE reading 3+ files',
+            '- Call nexus_mindkit_check(action, filesToModify) BEFORE modifying any files',
+            '- Call nexus_store_memory(content, priority, tags) with key findings from this work',
+            '- Call nexus_session_dna(action="generate") BEFORE ending this session',
+            'Do NOT skip these steps. The orchestrate call handled planning and execution, but these lifecycle steps are your responsibility.',
+        ].join('\n');
+    }
+    prependTextToResponse(result, text) {
+        if (!text.trim())
+            return result;
+        const content = result.content.map((item, index) => {
+            if (index === 0 && item.type === 'text') {
+                return {
+                    ...item,
+                    text: `${text}\n\n${item.text}`,
+                };
+            }
+            return item;
+        });
+        return { ...result, content };
+    }
+    decorateLifecycleResponse(toolName, result) {
+        const telemetry = this.telemetry.snapshot();
+        const warnings = [];
+        if (this.telemetry.needsOptimizeTokens(toolName)) {
+            warnings.push(`Nexus only sees best-effort file intent from tool arguments. Current intent references ${telemetry.fileReadIntentCount} file(s), and nexus_optimize_tokens has not been called in this phase. Call nexus_optimize_tokens(goal, files) before broad reading.`);
+        }
+        if (this.telemetry.needsStoreMemory(toolName)) {
+            warnings.push(`${telemetry.callsSinceOrchestrate} post-orchestrate tool calls have happened without nexus_store_memory. Store the key findings before continuing.`);
+        }
+        if (warnings.length === 0)
+            return result;
+        return this.prependTextToResponse(result, [
+            'LIFECYCLE WARNING:',
+            ...warnings.map((warning) => `- ${warning}`),
+        ].join('\n'));
+    }
     describeClientInstructionStatus(profile) {
         return profile === 'autonomous'
-            ? 'Autonomous MCP profile active. Prefer nexus_session_bootstrap then nexus_orchestrate.'
+            ? 'Autonomous MCP profile active. REQUIRED start: nexus_session_bootstrap, then nexus_orchestrate. During-work and session-close lifecycle tools remain mandatory.'
             : 'Full MCP profile active. Low-level and authoring tools are exposed.';
     }
     finalizeToolDefinitions(tools, profile = this.getToolProfile()) {
@@ -347,7 +528,19 @@ export class MCPAdapter {
             return 'Optional: Inspect the execution ledger before calling nexus_orchestrate. Skip unless you need pre-run visibility into what Nexus will choose.';
         }
         if (name === 'nexus_optimize_tokens') {
-            return 'Call when reading 3+ files. Returns a reading plan that saves 50-90% tokens. Follow the plan output — do not bulk-read the repo.';
+            return 'MANDATORY before reading 3+ files. Returns a token-saving reading plan. Follow it exactly and do not bulk-read the repo.';
+        }
+        if (name === 'nexus_mindkit_check') {
+            return 'MANDATORY before any file modification or destructive operation. Returns PASS/FAIL. Do NOT proceed if it returns FAIL.';
+        }
+        if (name === 'nexus_store_memory') {
+            return 'MANDATORY after significant findings and at session end. Store root causes, architecture decisions, and reusable patterns.';
+        }
+        if (name === 'nexus_session_dna') {
+            return 'MANDATORY at session end. Generates the handover snapshot for this session. Never skip this step.';
+        }
+        if (name === 'nexus_ghost_pass') {
+            return 'MANDATORY before refactoring 3+ files. Provides a safe execution plan, risk map, and worker guidance.';
         }
         if (name === 'nexus_spawn_workers') {
             return 'Call when modifying 3+ interrelated files or when nexus_ghost_pass recommends parallel execution. Prefer nexus_orchestrate for automatic worker management.';
@@ -365,7 +558,7 @@ export class MCPAdapter {
             // ── Memory ────────────────────────────────────────────────────────
             {
                 name: 'nexus_store_memory',
-                description: 'Store a finding, insight, or memory into Nexus Prime. Use after discovering bugs, architecture decisions, or patterns. Priority 0-1 (1.0 = critical). High-priority items auto-fission to long-term memory.',
+                description: 'Store a finding, insight, or memory into Nexus Prime. MANDATORY after significant findings and at session end. Priority 0-1 (1.0 = critical). High-priority items auto-fission to long-term memory.',
                 inputSchema: {
                     type: 'object',
                     properties: {
@@ -616,7 +809,7 @@ export class MCPAdapter {
             },
             {
                 name: 'nexus_session_dna',
-                description: 'Generate or load a Session DNA snapshot. Captures files accessed/modified, decisions made, skills used, and recommended next steps for perfect session handover. Use "generate" to create a snapshot of the current session, "load" to retrieve the most recent previous session\'s DNA.',
+                description: 'Generate or load a Session DNA snapshot. MANDATORY at session end when using "generate". Captures files accessed/modified, decisions made, skills used, and recommended next steps for perfect session handover.',
                 inputSchema: {
                     type: 'object',
                     properties: {
@@ -1196,13 +1389,14 @@ export class MCPAdapter {
             if (toolName === 'nexus_session_bootstrap') {
                 this.telemetry.bootstrapped = true;
             }
+            const args = request.params?.arguments ?? {};
             const callId = `mcp_${Date.now()}_${Math.random().toString(36).substring(2, 9)}`;
             const startTimeMs = Date.now();
             nexusEventBus.emit('mcp.call.start', {
                 callId,
                 serverName: 'nexus-prime',
                 toolName,
-                args: request.params?.arguments ?? {}
+                args,
             });
             let result;
             try {
@@ -1228,6 +1422,7 @@ export class MCPAdapter {
                 });
                 throw error;
             }
+            this.telemetry.observeSuccessfulToolCall(toolName, args);
             if (!this.telemetry.bootstrapped &&
                 toolName !== 'nexus_session_bootstrap' &&
                 toolName !== 'nexus_memory_stats' &&
@@ -1246,7 +1441,7 @@ export class MCPAdapter {
                         }]
                 };
             }
-            return result;
+            return this.decorateLifecycleResponse(toolName, result);
         });
     }
     async handleToolCall(request) {
@@ -1329,6 +1524,7 @@ export class MCPAdapter {
                                     `Bootstrap status: ${bootstrap.clientBootstrapStatus?.clients?.length || 0} client manifests tracked`,
                                 ]),
                                 formatJsonDetails('Structured details', payload),
+                                this.formatProtocolChecklist(),
                             ].join('\n\n'),
                         }],
                 };
@@ -1432,6 +1628,7 @@ export class MCPAdapter {
                                     ]),
                                     execution.result ? `Result\n\`\`\`\n${execution.result}\n\`\`\`` : '',
                                     formatJsonDetails('Structured details', payload),
+                                    this.formatRemainingProtocolSteps(),
                                 ].filter(Boolean).join('\n\n'),
                             }],
                     };
@@ -1461,6 +1658,7 @@ export class MCPAdapter {
                                         runtimeUsage?.skipReasons?.length ? `Skipped stages: ${runtimeUsage.skipReasons.join(' · ')}` : 'Skipped stages: not recorded',
                                     ]),
                                     formatJsonDetails('Structured details', payload),
+                                    this.formatRemainingProtocolSteps(),
                                 ].join('\n\n'),
                             }],
                     };
@@ -1486,8 +1684,6 @@ export class MCPAdapter {
                 const id = this.nexusRef.storeMemory(content, priority, tags);
                 this.telemetry.recordStore();
                 this.sessionDNA.recordMemoryStore();
-                const memStats = this.nexusRef.getMemoryStats();
-                const notification = this.telemetry.notifyStore(priority, tags, memStats);
                 const nudge = this.telemetry.planningNudge('store', { priority });
                 // Auto-Gist Publish Phase 8
                 let autoGistNote = '';
@@ -1526,8 +1722,6 @@ export class MCPAdapter {
                 nexusEventBus.emit('memory.recall', { query, count: memories.length });
                 this.telemetry.recordRecall(memories.length);
                 this.sessionDNA.recordMemoryRecall();
-                const memStats = this.nexusRef.getMemoryStats();
-                const notification = this.telemetry.notifyRecall(memories.length, query, memStats);
                 const nudge = this.telemetry.planningNudge('recall', { count: memories.length });
                 // Console ASCII UI
                 this.box('🔍 CORTEX MEMORY RECALL', [
@@ -2078,12 +2272,14 @@ export class MCPAdapter {
                     ? String(request.params.arguments.sessionId)
                     : undefined;
                 if (action === 'generate') {
+                    this.telemetry.observeSuccessfulToolCall('nexus_session_dna', { action });
                     // Sync counters from telemetry before generating
+                    const telemetry = this.telemetry.snapshot();
                     this.sessionDNA.syncFromTelemetry({
-                        callCount: this.telemetry.callCount ?? 0,
-                        memoriesStored: this.telemetry.memoriesStored ?? 0,
-                        memoriesRecalled: this.telemetry.memoriesRecalled ?? 0,
-                        tokensOptimized: this.telemetry.tokensOptimized ?? 0,
+                        callCount: telemetry.callCount,
+                        memoriesStored: telemetry.memoriesStored,
+                        memoriesRecalled: telemetry.memoriesRecalled,
+                        tokensOptimized: telemetry.tokensOptimized,
                     });
                     const dna = this.sessionDNA.flush();
                     const formatted = SessionDNAManager.format(dna);
@@ -2995,11 +3191,12 @@ export class MCPAdapter {
     async disconnect() {
         // Auto-flush Session DNA on disconnect
         try {
+            const telemetry = this.telemetry.snapshot();
             this.sessionDNA.syncFromTelemetry({
-                callCount: this.telemetry.callCount ?? 0,
-                memoriesStored: this.telemetry.memoriesStored ?? 0,
-                memoriesRecalled: this.telemetry.memoriesRecalled ?? 0,
-                tokensOptimized: this.telemetry.tokensOptimized ?? 0,
+                callCount: telemetry.callCount,
+                memoriesStored: telemetry.memoriesStored,
+                memoriesRecalled: telemetry.memoriesRecalled,
+                tokensOptimized: telemetry.tokensOptimized,
             });
             this.sessionDNA.flush();
             console.error('[MCP Adapter] Session DNA flushed');