@phuetz/code-buddy 1.6.1 → 2.1.0

package/dist/services/prompt-builder.js

@@ -11,11 +11,58 @@
  */
 import { logger } from "../utils/logger.js";
 import { getErrorMessage } from "../errors/index.js";
+import { createHash } from "node:crypto";
 import { getSystemPromptForMode, getPromptManager, autoSelectPromptId, getChatOnlySystemPrompt, } from "../prompts/index.js";
 import { getModelToolConfig } from "../config/model-tools.js";
 import { resolveProjectContext, createContextRegistry, setActiveContextRegistry } from "../context/project-context.js";
 import { classifyQuery } from "../agent/execution/query-classifier.js";
 import { filterToolNames, getToolFilter, isToolNameAllowed, } from "../utils/tool-filter.js";
+import { HEADLESS_LOCAL_COMPACT_MAX_TOKENS, isHeadlessLocalPromptCompact, } from "../config/headless-local-prompt.js";
+/** Lower values survive budget pressure first. Keep safety ahead of tools,
+ * tools ahead of style, and style ahead of examples/context. */
+export const PROMPT_PRIORITIES = {
+    security: 10,
+    workspace: 20,
+    tools: 30,
+    style: 40,
+    context: 50,
+    examples: 60,
+};
+/**
+ * Select complete prompt blocks under a character budget. A block that is
+ * itself larger than the budget is retained intact as a fail-safe: partial
+ * security/tool instructions are more dangerous than a budget overrun.
+ */
+export function truncatePromptBlocksByPriority(blocks, budgetChars) {
+    if (budgetChars <= 0) {
+        return { prompt: '', removed: blocks.map(block => block.id) };
+    }
+    const ranked = blocks
+        .map((block, index) => ({ block, index }))
+        .sort((left, right) => left.block.priority - right.block.priority || left.index - right.index);
+    const selected = new Set();
+    const removed = [];
+    let used = 0;
+    for (const { block, index } of ranked) {
+        const separator = selected.size > 0 ? 2 : 0;
+        const candidateSize = used + separator + block.content.length;
+        if (candidateSize <= budgetChars || selected.size === 0) {
+            selected.add(index);
+            used = candidateSize;
+        }
+        else {
+            removed.push(index);
+        }
+    }
+    const prompt = blocks
+        .filter((_block, index) => selected.has(index))
+        .map(block => block.content)
+        .join('\n\n');
+    return {
+        prompt,
+        removed: blocks.filter((_block, index) => removed.includes(index)).map(block => block.id),
+    };
+}
 const ALL_BLOCKS = {
     includeBootstrap: true,
     includePersona: true,
@@ -34,6 +81,7 @@ const ALL_BLOCKS = {
     includeExecutionDiscipline: true,
     includeVariation: true,
 };
+const CODING_STYLE_CACHE_TTL_MS = 10 * 60 * 1000;
 const EXTERNAL_PROMPT_MANAGER_TOOLS = [
     'view_file',
     'str_replace_editor',
@@ -43,6 +91,7 @@ const EXTERNAL_PROMPT_MANAGER_TOOLS = [
     'todo',
     'reason',
 ];
+const STARTUP_PROJECT_CONTEXT_FILES = ['AGENTS.md', 'CODEBUDDY.md'];
 function hasActiveToolFilter(config) {
     return config.enabledPatterns.length > 0 || config.disabledPatterns.length > 0;
 }
@@ -60,6 +109,24 @@ The actual model-facing tool schema for this turn has an active filter.
 - Do not claim unavailable tools exist, suggest calling them, or emit calls for them.
 </active_tool_filter>`;
 }
+export function buildKnowledgeIndexBlock(entries) {
+    const lines = [
+        '<knowledge_index>',
+        `The knowledge base has ${entries.length} entr${entries.length === 1 ? 'y' : 'ies'}.`,
+        'Use `knowledge_search` with a focused query before relying on domain-specific details; full entries stay out of the startup prompt to preserve context.',
+    ];
+    let chars = lines.join('\n').length;
+    for (const entry of entries) {
+        const tags = entry.tags.length > 0 ? ` [${entry.tags.join(', ')}]` : '';
+        const line = `- ${entry.title}${tags}`;
+        if (chars + line.length + 1 > 1_600)
+            break;
+        lines.push(line);
+        chars += line.length + 1;
+    }
+    lines.push('</knowledge_index>');
+    return lines.join('\n');
+}
 export class PromptBuilder {
     config;
     promptCacheManager;
@@ -73,6 +140,9 @@ export class PromptBuilder {
      * re-injected when a tool later touches a file in the same tree.
      */
     contextRegistry = null;
+    codingStyleCache = null;
+    lastPromptBlocks = [];
+    lastPromptParts = [];
     constructor(config, promptCacheManager, memory, moltbotHooksManager, persistentMemory) {
         this.config = config;
         this.promptCacheManager = promptCacheManager;
@@ -84,13 +154,48 @@ export class PromptBuilder {
     getContextRegistry() {
         return this.contextRegistry;
     }
+    /** Return the block ledger from the most recent build (without prompt text). */
+    getLastPromptBlocks() {
+        return this.lastPromptBlocks.map(block => ({ ...block }));
+    }
+    recordPromptBlock(id, source, content, priority, includesSeparator, placement = 'append') {
+        const contribution = includesSeparator ? `\n\n${content}` : content;
+        const measurement = {
+            id,
+            source,
+            priority,
+            chars: contribution.length,
+            estimatedTokens: Math.ceil(contribution.length / 4),
+            sha256: createHash('sha256').update(content).digest('hex'),
+        };
+        const part = { id, source, content, priority };
+        if (placement === 'prepend') {
+            this.lastPromptBlocks.unshift(measurement);
+            this.lastPromptParts.unshift(part);
+        }
+        else {
+            this.lastPromptBlocks.push(measurement);
+            this.lastPromptParts.push(part);
+        }
+    }
+    appendPromptBlock(systemPrompt, id, source, content, priority) {
+        if (!content)
+            return systemPrompt;
+        this.recordPromptBlock(id, source, content, priority, systemPrompt.length > 0);
+        return systemPrompt + (systemPrompt.length > 0 ? '\n\n' : '') + content;
+    }
     /**
      * Build the system prompt for the agent. The optional `options`
      * parameter gates per-block injection. All gates default to `true`
      * so existing callers see V1.0 behavior unchanged.
      */
-    async buildSystemPrompt(systemPromptId, modelName, customInstructions, options) {
+    async buildSystemPrompt(systemPromptId, modelName, customInstructions, options, query) {
         const gates = { ...ALL_BLOCKS, ...options };
+        if (isHeadlessLocalPromptCompact()) {
+            Object.assign(gates, gatesForComplexity('trivial'));
+        }
+        this.lastPromptBlocks = [];
+        this.lastPromptParts = [];
         // When the model can't actually call tools (Ollama small/medium without
         // OpenAI tool_calls support), the auto-memory + lessons directives just
         // confuse the LLM into hallucinating JSON tool calls. Force-off here.
@@ -219,6 +324,14 @@ export class PromptBuilder {
                 const promptMode = this.config.yoloMode ? "yolo" : "default";
                 systemPrompt = getSystemPromptForMode(promptMode, this.config.morphEditorEnabled, this.config.cwd, customInstructions || undefined);
             }
+            const baseSource = systemPromptId && systemPromptId !== 'auto'
+                ? `prompts/${systemPromptId}.md + src/prompts/prompt-manager.ts`
+                : systemPromptId === 'auto'
+                    ? 'prompts/auto-selected.md + src/prompts/prompt-manager.ts'
+                    : toolCfg.supportsToolCalls === false && !forceTools
+                        ? 'src/prompts/system-base.ts (chat-only)'
+                        : 'src/prompts/system-base.ts';
+            this.recordPromptBlock('base', baseSource, systemPrompt, PROMPT_PRIORITIES.security, false);
             // Inject persistent memory context for paths that don't already
             // pass it to a PromptManager (legacy + chat-only). Without this,
             // the user's `remember`-stored facts (~/.codebuddy/memory.md)
@@ -230,14 +343,17 @@ export class PromptBuilder {
             // memoryContext })`, so we skip injection there.
             const wentThroughPromptManager = (systemPromptId && systemPromptId !== 'auto') || systemPromptId === 'auto';
             if (memoryContext && !wentThroughPromptManager) {
-                systemPrompt += `\n\n<persistent_memory>\n${memoryContext}\n</persistent_memory>`;
+                const memoryBlock = `<persistent_memory>\n${memoryContext}\n</persistent_memory>`;
+                systemPrompt = this.appendPromptBlock(systemPrompt, 'persistent-memory', 'memory', memoryBlock, PROMPT_PRIORITIES.context);
                 logger.debug('Injected persistent memory context into system prompt', {
                     chars: memoryContext.length,
                 });
             }
             // Prepend intro hook content if available (Moltbot-style role injection)
             if (introHookContent) {
-                systemPrompt = `# Role & Instructions (from intro_hook.txt)\n\n${introHookContent}\n\n---\n\n${systemPrompt}`;
+                const introBlock = `# Role & Instructions (from intro_hook.txt)\n\n${introHookContent}\n\n---`;
+                this.recordPromptBlock('intro-hook', 'intro_hook.txt', introBlock, PROMPT_PRIORITIES.style, true, 'prepend');
+                systemPrompt = `${introBlock}\n\n${systemPrompt}`;
                 logger.debug("Prepended intro hook content to system prompt");
             }
             // Inject execution-discipline guidance (tool-use enforcement, anti-stub
@@ -248,18 +364,32 @@ export class PromptBuilder {
             // injector (varySystemPrompt → extractBlocks splits on bullet lines), so
             // a late placement fragmented this block — foreign bullets got interleaved
             // between its lines. Up here it stays contiguous, cache-stable, and
-            // survives head-truncation. Gated off for trivial/lite + tool-callless
+            // stays contiguous and cache-stable. Gated off for trivial/lite + tool-callless
             // models (see gating above).
             if (gates.includeExecutionDiscipline) {
                 try {
                     const { getExecutionDisciplineBlock } = await import('../prompts/execution-discipline.js');
-                    systemPrompt += '\n\n' + getExecutionDisciplineBlock();
+                    systemPrompt = this.appendPromptBlock(systemPrompt, 'execution-discipline', 'src/prompts/execution-discipline.ts', getExecutionDisciplineBlock(), PROMPT_PRIORITIES.tools);
                     logger.debug('Injected execution-discipline guidance into system prompt');
                 }
                 catch (err) {
                     logger.warn('Failed to inject execution-discipline block', { error: getErrorMessage(err) });
                 }
             }
+            // Collective Knowledge Graph — relevance-ranked on the current query.
+            // Placed BEFORE optional blocks (knowledge/docs/skills/identity/…) so
+            // It remains its own atomic context block for priority selection.
+            if (query && process.env.CODEBUDDY_COLLECTIVE_MEMORY === 'true') {
+                try {
+                    const { getCollectiveKnowledgeGraph } = await import('../memory/collective-knowledge-graph.js');
+                    const ckgBlock = await getCollectiveKnowledgeGraph().formatCollectiveContext(query, 1_600);
+                    if (ckgBlock) {
+                        systemPrompt = this.appendPromptBlock(systemPrompt, 'collective-knowledge', 'memory', ckgBlock, PROMPT_PRIORITIES.context);
+                        logger.debug('Injected collective knowledge into system prompt', { chars: ckgBlock.length });
+                    }
+                }
+                catch { /* collective graph optional */ }
+            }
             // Inject project-instruction context (AGENTS.md / CODEBUDDY.md / CLAUDE.md
             // / GEMINI.md / CONTEXT.md / INSTRUCTIONS.md) via the unified hierarchical
             // loader, then soul/bootstrap files. A fresh dedup registry is created per
@@ -269,9 +399,19 @@ export class PromptBuilder {
                 // Publish for the JIT pass so it skips files injected here at startup.
                 setActiveContextRegistry(this.contextRegistry);
                 try {
-                    const ctx = resolveProjectContext({ cwd: this.config.cwd, registry: this.contextRegistry });
+                    const contextFileNames = process.env.CODEBUDDY_INCLUDE_INTEROP_CONTEXT === 'true'
+                        ? undefined
+                        : [...STARTUP_PROJECT_CONTEXT_FILES];
+                    const ctx = resolveProjectContext({
+                        cwd: this.config.cwd,
+                        registry: this.contextRegistry,
+                        ...(contextFileNames ? { fileNames: contextFileNames } : {}),
+                    });
                     if (ctx.text) {
-                        systemPrompt += '\n\n# Workspace Context\n\n' + ctx.text;
+                        const workspaceBlock = '# Workspace Context\n\n' + ctx.text;
+                        systemPrompt = this.appendPromptBlock(systemPrompt, 'workspace-context', ctx.sources.length > 0
+                            ? `project instruction files: ${ctx.sources.map(source => source.relPath).join(', ')}`
+                            : 'project instruction files', workspaceBlock, PROMPT_PRIORITIES.workspace);
                         logger.debug(`Loaded project context from ${ctx.sources.length} file(s)`, {
                             sources: ctx.sources.map((s) => s.relPath),
                             chars: ctx.bytes,
@@ -288,7 +428,7 @@ export class PromptBuilder {
                     const { BootstrapLoader } = await import('../context/bootstrap-loader.js');
                     const bootstrap = await new BootstrapLoader().load(this.config.cwd);
                     if (bootstrap.content) {
-                        systemPrompt += '\n\n' + bootstrap.content;
+                        systemPrompt = this.appendPromptBlock(systemPrompt, 'bootstrap', 'SOUL.md / USER.md / PROJECT_KNOWLEDGE.md', bootstrap.content, PROMPT_PRIORITIES.context);
                         logger.debug(`Loaded bootstrap/soul context from ${bootstrap.sources.length} file(s)`);
                     }
                 }
@@ -302,7 +442,7 @@ export class PromptBuilder {
                     const { getPersonaManager } = await import('../personas/persona-manager.js');
                     const personaBlock = getPersonaManager().buildSystemPrompt();
                     if (personaBlock) {
-                        systemPrompt += `\n\n<persona>\n${personaBlock}\n</persona>`;
+                        systemPrompt = this.appendPromptBlock(systemPrompt, 'persona', 'src/personas/persona-manager.ts', `<persona>\n${personaBlock}\n</persona>`, PROMPT_PRIORITIES.style);
                         logger.debug('Injected active persona into system prompt');
                     }
                 }
@@ -316,9 +456,14 @@ export class PromptBuilder {
                     if (!km.isLoaded) {
                         await km.load();
                     }
-                    const knowledgeBlock = km.buildContextBlock();
+                    const knowledgeEntries = km.list();
+                    const knowledgeBlock = knowledgeEntries.length > 0
+                        ? isToolNameAllowed('knowledge_search', activeToolFilter)
+                            ? buildKnowledgeIndexBlock(knowledgeEntries)
+                            : km.buildContextBlock()
+                        : '';
                     if (knowledgeBlock) {
-                        systemPrompt += `\n\n<knowledge>\n${knowledgeBlock}\n</knowledge>`;
+                        systemPrompt = this.appendPromptBlock(systemPrompt, 'knowledge', '.codebuddy/knowledge + src/knowledge/knowledge-manager.ts', `<knowledge>\n${knowledgeBlock}\n</knowledge>`, PROMPT_PRIORITIES.context);
                         logger.debug('Injected knowledge base into system prompt');
                     }
                 }
@@ -334,7 +479,7 @@ export class PromptBuilder {
                     }
                     const architectureSummary = docsProvider.getArchitectureSummary();
                     if (architectureSummary) {
-                        systemPrompt += `\n\n<project_docs>\n${architectureSummary}\n</project_docs>`;
+                        systemPrompt = this.appendPromptBlock(systemPrompt, 'project-docs', '.codebuddy/docs + src/docs/docs-context-provider.ts', `<project_docs>\n${architectureSummary}\n</project_docs>`, PROMPT_PRIORITIES.context);
                     }
                 }
                 catch { /* docs context module optional */ }
@@ -349,7 +494,7 @@ export class PromptBuilder {
                     }
                     const rulesBlock = rulesLoader.buildContextBlock();
                     if (rulesBlock) {
-                        systemPrompt += `\n\n<rules>\n${rulesBlock}\n</rules>`;
+                        systemPrompt = this.appendPromptBlock(systemPrompt, 'rules', '.codebuddy/rules + src/rules/rules-loader.ts', `<rules>\n${rulesBlock}\n</rules>`, PROMPT_PRIORITIES.tools);
                         logger.debug('Injected modular rules into system prompt');
                     }
                 }
@@ -360,22 +505,43 @@ export class PromptBuilder {
             // code_graph/codebase_map behaviour is unchanged. Presence is session-
             // stable, so this stays in the cache-stable prefix.
             try {
-                const { isCodeExplorerAvailable } = await import('../codebuddy/tools.js');
-                if (isCodeExplorerAvailable()) {
-                    systemPrompt +=
-                        `\n\n<code_explorer_priority>\n` +
-                            `Code Explorer (code-explorer) is connected. For ANY question about code relationships — ` +
-                            `callers/callees, blast radius / impact ("what breaks if I change X"), dead code, cycles, ` +
-                            `coupling, complexity — PREFER its MCP tools (\`mcp__code-explorer__impact\`, ` +
-                            `\`mcp__code-explorer__context\`, \`mcp__code-explorer__query\`, \`mcp__code-explorer__find_cycles\`, …) ` +
-                            `over the built-in \`code_graph\` / \`codebase_map\`: the code-explorer graph is broader and more ` +
-                            `complete (whole-repo, 14 languages).\n` +
-                            `Usage: first call \`mcp__code-explorer__list_repos\` once to get the repo \`path\`/\`id\`, then call ` +
-                            `\`mcp__code-explorer__impact\` with the REQUIRED \`target\` = the symbol name (e.g. \`target: "executePlan"\`, ` +
-                            `optionally \`direction: "both"\`) and \`repo\` = that path; or \`mcp__code-explorer__context\` with \`name\` = ` +
-                            `the symbol. Always include \`target\`/\`name\` — never call these tools with empty arguments. ` +
-                            `Use the built-in \`code_graph\`/\`codebase_map\` only as a fallback if a code-explorer tool errors.\n` +
-                            `</code_explorer_priority>`;
+                const { codeExplorerToolPrefix } = await import('../codebuddy/tools.js');
+                const p = codeExplorerToolPrefix(); // 'mcp__code-explorer__' | 'mcp__gitnexus__' | null
+                if (p) {
+                    // Best-effort staleness check: warn the agent when the index lags HEAD
+                    // so it doesn't silently reason over an out-of-date graph.
+                    let staleNote = '';
+                    try {
+                        const { getCodeExplorerManager } = await import('../plugins/code-explorer/CodeExplorerManager.js');
+                        const fresh = getCodeExplorerManager(this.config.cwd).getFreshness();
+                        if (fresh.stale) {
+                            const state = fresh.unverified
+                                ? 'could not be verified against Git HEAD'
+                                : 'does not match Git HEAD';
+                            staleNote =
+                                `\n⚠️ The Code Explorer index ${state}. Its answers may miss current code; ` +
+                                    `treat relationship results as approximate and suggest re-running ` +
+                                    `\`code-explorer analyze --incremental\` if they look wrong.`;
+                        }
+                    }
+                    catch { /* freshness best-effort */ }
+                    const codeExplorerBlock = `<code_explorer_priority>\n` +
+                        `Code Explorer is connected through MCP on the host. Use these MCP tools directly; ` +
+                        `do not run the host code-explorer binary through Bash, which may execute inside an isolated container. ` +
+                        `For questions about code relationships — ` +
+                        `callers/callees, blast radius / impact ("what breaks if I change X"), dead code, cycles, ` +
+                        `coupling, complexity — PREFER its MCP tools (\`${p}impact\`, ` +
+                        `\`${p}context\`, \`${p}query\`, \`${p}find_cycles\`, …) ` +
+                        `over the built-in \`code_graph\` / \`codebase_map\`: the Code Explorer graph is broader and more ` +
+                        `complete (whole-repo, 14 languages).\n` +
+                        `Usage: first call \`${p}list_repos\` once to get the repo \`path\`/\`id\`, then call ` +
+                        `\`${p}impact\` with the REQUIRED \`target\` = the symbol name (e.g. \`target: "executePlan"\`, ` +
+                        `optionally \`direction: "both"\`) and \`repo\` = that path; or \`${p}context\` with \`name\` = ` +
+                        `the symbol. Always include \`target\`/\`name\` — never call these tools with empty arguments. ` +
+                        `Use the built-in \`code_graph\`/\`codebase_map\` only as a fallback if it errors.` +
+                        staleNote +
+                        `\n</code_explorer_priority>`;
+                    systemPrompt = this.appendPromptBlock(systemPrompt, 'code-explorer', 'src/codebuddy/tools.ts + Code Explorer MCP', codeExplorerBlock, PROMPT_PRIORITIES.tools);
                     logger.debug('Injected Code Explorer priority directive');
                 }
             }
@@ -387,7 +553,7 @@ export class PromptBuilder {
                     const skillManager = getSkillManager();
                     const skillBlock = skillManager.getSkillPromptEnhancement();
                     if (skillBlock) {
-                        systemPrompt += `\n\n${skillBlock}`;
+                        systemPrompt = this.appendPromptBlock(systemPrompt, 'skills', 'src/skills/skill-manager.ts + active skills', skillBlock, PROMPT_PRIORITIES.tools);
                         logger.debug('Injected active skill enhancement into system prompt');
                     }
                 }
@@ -403,7 +569,10 @@ export class PromptBuilder {
                         await identityMgr.load(this.config.cwd);
                         const identityBlock = identityMgr.getPromptInjection();
                         if (identityBlock) {
-                            systemPrompt += `\n\n<identity>\n${identityBlock}\n</identity>`;
+                            const identityFiles = typeof identityMgr.getAll === 'function' ? identityMgr.getAll() : [];
+                            systemPrompt = this.appendPromptBlock(systemPrompt, 'identity', identityFiles.length > 0
+                                ? `identity files: ${identityFiles.map(file => `${file.source}:${file.name}`).join(', ')}`
+                                : 'identity files', `<identity>\n${identityBlock}\n</identity>`, PROMPT_PRIORITIES.style);
                             logger.debug('Injected identity into system prompt');
                         }
                     }
@@ -419,24 +588,24 @@ export class PromptBuilder {
                     const peerCount = getFleetRegistry().size();
                     if (peerCount > 0) {
                         const { FLEET_DISPATCH_PROFILE_GUIDANCE_TEXT, } = await import('../fleet/dispatch-profile.js');
-                        systemPrompt +=
-                            `\n\n<fleet>Connected fleet peers: ${peerCount}. ` +
-                                `Use route_peer to choose the best peer/model for a task, ` +
-                                `pass dispatchProfile when the task has a clear posture ` +
-                                `(research, code, review, safe, or balanced), ` +
-                                `using this guide: ${FLEET_DISPATCH_PROFILE_GUIDANCE_TEXT}. ` +
-                                `list_peers({includeCapabilities:true}) when you need raw ` +
-                                `provider status, or list_peers() for a quick status. Then ` +
-                                `peer_delegate can ask the chosen peer a question; reuse the ` +
-                                `dispatchProfile returned by route_peer so the peer receives ` +
-                                `matching guidance. For ordered specialist collaboration, pass ` +
-                                `chainRoles such as ["code","review","safe"] to route_peer and ` +
-                                `then run the returned nextCalls in order, or call peer_chain ` +
-                                `to route and execute the chain with stage handoffs. The peer answers ` +
-                                `independently with its own model and the response is fed back ` +
-                                `into your context. Useful for delegating heavy compute, asking a ` +
-                                `peer with different domain knowledge, or coordinating across ` +
-                                `hosts.</fleet>`;
+                        const fleetBlock = `<fleet>Connected fleet peers: ${peerCount}. ` +
+                            `Use route_peer to choose the best peer/model for a task, ` +
+                            `pass dispatchProfile when the task has a clear posture ` +
+                            `(research, code, review, safe, or balanced), ` +
+                            `using this guide: ${FLEET_DISPATCH_PROFILE_GUIDANCE_TEXT}. ` +
+                            `list_peers({includeCapabilities:true}) when you need raw ` +
+                            `provider status, or list_peers() for a quick status. Then ` +
+                            `peer_delegate can ask the chosen peer a question; reuse the ` +
+                            `dispatchProfile returned by route_peer so the peer receives ` +
+                            `matching guidance. For ordered specialist collaboration, pass ` +
+                            `chainRoles such as ["code","review","safe"] to route_peer and ` +
+                            `then run the returned nextCalls in order, or call peer_chain ` +
+                            `to route and execute the chain with stage handoffs. The peer answers ` +
+                            `independently with its own model and the response is fed back ` +
+                            `into your context. Useful for delegating heavy compute, asking a ` +
+                            `peer with different domain knowledge, or coordinating across ` +
+                            `hosts.</fleet>`;
+                        systemPrompt = this.appendPromptBlock(systemPrompt, 'fleet', 'src/fleet + fleet tools', fleetBlock, PROMPT_PRIORITIES.tools);
                         logger.debug(`Injected fleet nudge into system prompt (${peerCount} peer(s))`);
                     }
                 }
@@ -459,7 +628,7 @@ export class PromptBuilder {
                 const closingMemoryInstruction = memoryProposeToolAllowed
                     ? 'Prefer `memory_propose` over `remember` when the fact came from your interpretation rather than an explicit user instruction.'
                     : 'Only call `remember` when the fact came from an explicit user instruction or correction.';
-                systemPrompt += `\n\n<auto_memory_directive>
+                const autoMemoryBlock = `<auto_memory_directive>
 You have a persistent memory system at .codebuddy/CODEBUDDY_MEMORY.md (project-scoped) and ~/.codebuddy/memory.md (user-scoped, all projects).
 ${memoryWriteInstruction}
 
@@ -486,6 +655,7 @@ Format:
 
 ${closingMemoryInstruction}
 </auto_memory_directive>`;
+                systemPrompt = this.appendPromptBlock(systemPrompt, 'auto-memory-directive', 'memory tools', autoMemoryBlock, PROMPT_PRIORITIES.tools);
                 logger.debug('Injected auto-memory directive into system prompt');
             }
             // Lessons directive — Manus AI-inspired self-improvement loop
@@ -495,7 +665,7 @@ ${closingMemoryInstruction}
             // because no system directive told it WHEN. This block fixes that
             // (mirror of the auto-memory directive above).
             if (this.config.memoryEnabled && this.persistentMemory && gates.includeLessonsDirective) {
-                systemPrompt += `\n\n<lessons_directive>
+                const lessonsBlock = `<lessons_directive>
 Code Buddy maintains a self-improvement loop via the \`lessons_add\`, \`lessons_search\`, and \`lessons_graph\` tools (Manus AI-inspired pattern). Lessons persist to .codebuddy/lessons.md (project-scoped) and ~/.codebuddy/lessons.md (global, all projects). They differ from \`remember\` by capturing actionable patterns rather than facts.
 
 Four categories — pick the right one:
@@ -529,20 +699,21 @@ What NOT to add:
 
 Lessons complement \`remember\`: \`remember\` stores facts (preferences, decisions); \`lessons_add\` stores actionable patterns and rules. Use whichever fits — both persist across sessions.
 </lessons_directive>`;
+                systemPrompt = this.appendPromptBlock(systemPrompt, 'lessons-directive', 'memory tools', lessonsBlock, PROMPT_PRIORITIES.tools);
                 logger.debug('Injected lessons directive into system prompt');
             }
-            // Self-knowledge — only when self-improvement is explicitly opted in. Makes
-            // the agent aware it can author its own tools/skills (and the hard `src/` limit).
-            if (process.env.CODEBUDDY_SELF_IMPROVE === 'true') {
+            // The safe extension forge is a default capability, so tool-capable
+            // full-context turns get a compact description of it.
+            if (gates.includeIdentity && gates.includeExecutionDiscipline) {
                 try {
                     const { buildSelfKnowledgeBlock } = await import('../agent/self-improvement/self-knowledge.js');
-                    systemPrompt += `\n\n<self_knowledge>\n${buildSelfKnowledgeBlock()}\n</self_knowledge>`;
+                    systemPrompt = this.appendPromptBlock(systemPrompt, 'self-knowledge', 'src/agent/self-improvement/self-knowledge.ts', `<self_knowledge>\n${buildSelfKnowledgeBlock()}\n</self_knowledge>`, PROMPT_PRIORITIES.tools);
                     logger.debug('Injected self-knowledge block into system prompt');
                 }
-                catch { /* self-improvement module optional */ }
+                catch { /* extension module optional */ }
             }
             if (this.config.memoryEnabled && gates.includeUserModelDirective) {
-                systemPrompt += `\n\n<user_model_directive>
+                const userModelBlock = `<user_model_directive>
 You have a persistent user model that builds a deepening profile of who you are, your traits, preferences, expertise, and working style.
 
 When you learn something about the user that is stable across sessions (such as preferred libraries, styling choices, expertise level, or working style), you MUST use the \`user_model_observe\` tool to propose a structured observation.
@@ -560,6 +731,7 @@ Important Constraints:
 
 Use the \`user_model_observe\` tool proactively when you learn a stable coding preference or trait.
 </user_model_directive>`;
+                systemPrompt = this.appendPromptBlock(systemPrompt, 'user-model-directive', 'memory tools', userModelBlock, PROMPT_PRIORITIES.tools);
                 logger.debug('Injected user model directive into system prompt');
             }
             // Inject `<writing_rules>` directive — proactive output discipline.
@@ -573,7 +745,7 @@ Use the \`user_model_observe\` tool proactively when you learn a stable coding p
                 //
                 // Always-on (no `memoryEnabled` gate) — output discipline is
                 // universally useful, even for sessions with no persistent memory.
-                systemPrompt += `\n\n<writing_rules>
+                const writingRulesBlock = `<writing_rules>
 Output formatting discipline:
 
 - Never emit model control tokens in your output: no \`<|im_start|>\`, \`<|im_end|>\`, \`<think>\`, \`<reasoning>\`, \`[INST]\`, \`<<SYS>>\`, GLM-5 full-width brackets, or any \`<|…|>\` variant. The runtime strips these as a safety net but the cost is wasted tokens.
@@ -585,25 +757,38 @@ Output formatting discipline:
   - Bold/italic sparingly — only when emphasis is load-bearing
 - No emoji unless the user explicitly requested them or they convey load-bearing information (e.g. ✅/❌ status markers in a table).
 - No meta-commentary about being an AI: skip "As an AI...", "I'll help you with...", "Let me explain...". Just answer.
-- Tone: direct, factual, terse. Match the user's register (formal ↔ casual).
+- Tone: direct, natural, and calm. Match the user's language and register (formal ↔ casual) without caricaturing slang or adding canned enthusiasm.
+- Write like an experienced teammate in an ongoing conversation: use ordinary phrasing, refer naturally to prior context, and acknowledge corrections or uncertainty briefly when relevant.
+- For work that needs several tool rounds, give a short, concrete orientation before or between meaningful phases when it helps the user understand the wait. Do not narrate every obvious action.
+- Avoid robotic templates and repetitive headings. Let the response structure follow the task; a simple exchange should read like a simple exchange.
 - Links: markdown hyperlinks \`[label](url)\`, not raw URLs in flowing text.
 - File references: use \`path/to/file.ts:42\` format so the user can navigate by click.
 - When uncertain about facts, say "I don't know" rather than fabricating. When uncertain about correctness of code, mark it as untested.
 </writing_rules>`;
+                systemPrompt = this.appendPromptBlock(systemPrompt, 'writing-rules', 'style', writingRulesBlock, PROMPT_PRIORITIES.style);
                 logger.debug('Injected writing_rules directive into system prompt');
             }
             // Inject auto-detected coding style conventions
             if (gates.includeCodingStyle) {
                 try {
-                    const { getCodingStyleAnalyzer } = await import('../memory/coding-style-analyzer.js');
-                    const analyzer = getCodingStyleAnalyzer();
-                    const profile = await analyzer.analyzeDirectory(this.config.cwd);
-                    if (profile) {
-                        const styleBlock = analyzer.buildPromptSnippet(profile);
-                        if (styleBlock) {
-                            systemPrompt += `\n\n${styleBlock}`;
-                            logger.debug('Injected coding style conventions into system prompt');
-                        }
+                    const now = Date.now();
+                    const cached = this.codingStyleCache;
+                    let styleBlock;
+                    if (cached &&
+                        cached.cwd === this.config.cwd &&
+                        now - cached.analyzedAt < CODING_STYLE_CACHE_TTL_MS) {
+                        styleBlock = cached.styleBlock;
+                    }
+                    else {
+                        const { getCodingStyleAnalyzer } = await import('../memory/coding-style-analyzer.js');
+                        const analyzer = getCodingStyleAnalyzer();
+                        const profile = await analyzer.analyzeDirectory(this.config.cwd);
+                        styleBlock = profile ? analyzer.buildPromptSnippet(profile) : '';
+                        this.codingStyleCache = { cwd: this.config.cwd, styleBlock, analyzedAt: now };
+                    }
+                    if (styleBlock) {
+                        systemPrompt = this.appendPromptBlock(systemPrompt, 'coding-style', 'src/memory/coding-style-analyzer.ts', styleBlock, PROMPT_PRIORITIES.style);
+                        logger.debug('Injected coding style conventions into system prompt');
                     }
                 }
                 catch { /* coding-style module optional */ }
@@ -612,19 +797,61 @@ Output formatting discipline:
             if (gates.includeWorkflowRules) {
                 try {
                     const { getWorkflowRulesBlock } = await import('../prompts/workflow-rules.js');
-                    systemPrompt += '\n\n' + getWorkflowRulesBlock({
+                    const workflowRulesBlock = getWorkflowRulesBlock({
                         isToolAvailable: toolName => isToolNameAllowed(toolName, activeToolFilter),
                     });
+                    systemPrompt = this.appendPromptBlock(systemPrompt, 'workflow-rules', 'src/prompts/workflow-rules.ts', workflowRulesBlock, PROMPT_PRIORITIES.tools);
                     logger.debug('Injected workflow orchestration rules into system prompt');
                 }
                 catch (err) {
                     logger.warn('Failed to inject workflow rules', { error: getErrorMessage(err) });
                 }
             }
+            const activeToolFilterDirective = buildActiveToolFilterDirective(activeToolFilter);
+            if (activeToolFilterDirective) {
+                systemPrompt = this.appendPromptBlock(systemPrompt, 'active-tool-filter', 'tool schema/filter', activeToolFilterDirective, PROMPT_PRIORITIES.tools);
+                logger.debug('Injected active tool filter directive into system prompt', {
+                    enabledPatterns: activeToolFilter.enabledPatterns,
+                    disabledPatterns: activeToolFilter.disabledPatterns,
+                });
+            }
+            // Truncate system prompt if it exceeds the model's context budget.
+            // Reserve 50% of (contextWindow - maxOutputTokens) for the system prompt;
+            // the rest goes to conversation history. The selector below keeps whole
+            // blocks and ranks them by the declared security/tools/style/context
+            // priorities instead of cutting through arbitrary text.
+            // Reuse `toolCfg` from the top of the function so test mocks that
+            // use `mockReturnValueOnce` aren't consumed twice.
+            const contextWindow = toolCfg.contextWindow ?? 8192;
+            const maxOutputTokens = toolCfg.maxOutputTokens ?? 2048;
+            // Guard the degenerate case where maxOutputTokens >= contextWindow (some
+            // custom/reasoning model configs, or CODEBUDDY_MAX_CONTEXT capping a
+            // 262k model down to its own maxOutputTokens): (cw - maxOut) can be <= 0.
+            // A 0-token budget used to wipe the system prompt (GK21: 16384/16384 → 0).
+            // Fall back to 25% of the window (floor 256) instead of an empty prompt.
+            const leftover = contextWindow - maxOutputTokens;
+            const rawBudget = leftover > 0
+                ? Math.floor(leftover * 0.5)
+                : Math.floor(contextWindow * 0.25);
+            let budgetTokens = leftover > 0
+                ? Math.min(rawBudget, 32_000)
+                : Math.max(256, Math.min(rawBudget, 32_000));
+            if (isHeadlessLocalPromptCompact()) {
+                budgetTokens = Math.min(budgetTokens, HEADLESS_LOCAL_COMPACT_MAX_TOKENS);
+            }
+            const budgetChars = budgetTokens * 4; // ~4 chars per token
+            if (systemPrompt.length > budgetChars) {
+                const originalChars = systemPrompt.length;
+                const truncated = truncatePromptBlocksByPriority(this.lastPromptParts, budgetChars);
+                const removed = truncated.removed.length > 0 ? truncated.removed.join(', ') : 'aucun';
+                logger.warn(`System prompt truncated for ${modelName}: ${originalChars} chars → ${truncated.prompt.length} ` +
+                    `(budget: ${budgetTokens} tokens, 32K hard cap); blocs retirés : ${removed}`);
+                systemPrompt = truncated.prompt;
+            }
             // Manus AI structured variation — shuffle reminder blocks to prevent
-            // the model from falling into brittle repetition patterns.
-            // Only the footer guideline section is varied; the preamble/tools are left
-            // untouched so prompt caching remains effective on the stable prefix.
+            // the model from falling into brittle repetition patterns. It runs only
+            // after budget selection, so variation can reorder complete blocks but
+            // can never cause the truncator to cut one in half.
             if (gates.includeVariation) {
                 try {
                     const { varySystemPrompt } = await import('../prompts/variation-injector.js');
@@ -642,28 +869,6 @@ Output formatting discipline:
                     // non-critical — proceed with original prompt
                 }
             }
-            const activeToolFilterDirective = buildActiveToolFilterDirective(activeToolFilter);
-            if (activeToolFilterDirective) {
-                systemPrompt += '\n\n' + activeToolFilterDirective;
-                logger.debug('Injected active tool filter directive into system prompt', {
-                    enabledPatterns: activeToolFilter.enabledPatterns,
-                    disabledPatterns: activeToolFilter.disabledPatterns,
-                });
-            }
-            // Truncate system prompt if it exceeds the model's context budget.
-            // Reserve 50% of (contextWindow - maxOutputTokens) for the system prompt;
-            // the rest goes to conversation history. Simple head-truncation keeps the
-            // most critical instructions (always at the top) intact.
-            // Reuse `toolCfg` from the top of the function so test mocks that
-            // use `mockReturnValueOnce` aren't consumed twice.
-            const contextWindow = toolCfg.contextWindow ?? 8192;
-            const maxOutputTokens = toolCfg.maxOutputTokens ?? 2048;
-            const budgetTokens = Math.min(Math.floor((contextWindow - maxOutputTokens) * 0.5), 32_000); // 32K hard cap
-            const budgetChars = budgetTokens * 4; // ~4 chars per token
-            if (systemPrompt.length > budgetChars) {
-                logger.warn(`System prompt truncated for ${modelName}: ${systemPrompt.length} chars → ${budgetChars} (budget: ${budgetTokens} tokens, 32K hard cap)`);
-                systemPrompt = systemPrompt.slice(0, budgetChars - 3) + '...';
-            }
             // Cache system prompt for optimization
             this.promptCacheManager.cacheSystemPrompt(systemPrompt);
             // Store stable/dynamic split for cache-breakpoint injection (Manus AI #11/#20)
@@ -706,9 +911,10 @@ Output formatting discipline:
     async buildForQuery(message, systemPromptId, modelName, customInstructions) {
         const toolCfg = getModelToolConfig(modelName);
         const profile = toolCfg.promptProfile ?? 'standard';
-        const complexity = profile === 'lite' ? 'trivial'
-            : profile === 'rich' ? 'complex'
-                : classifyQuery(message).complexity;
+        const complexity = isHeadlessLocalPromptCompact() ? 'trivial'
+            : profile === 'lite' ? 'trivial'
+                : profile === 'rich' ? 'complex'
+                    : classifyQuery(message).complexity;
         const gates = gatesForComplexity(complexity);
         logger.debug('buildForQuery gating', {
             modelName,
@@ -717,7 +923,11 @@ Output formatting discipline:
             messageLen: message.length,
             gatesOff: Object.entries(gates).filter(([, v]) => !v).map(([k]) => k),
         });
-        return this.buildSystemPrompt(systemPromptId, modelName, customInstructions, gates);
+        return this.buildSystemPrompt(systemPromptId, modelName, customInstructions, gates, message);
+    }
+    /** Keep prompt reads bound to the same project/bot manager as tool writes. */
+    setPersistentMemory(manager) {
+        this.persistentMemory = manager;
     }
     /**
      * Update configuration
@@ -731,6 +941,10 @@ Output formatting discipline:
  * to `trivial` (minimal prompt); `rich` maps to `complex` (everything).
  */
 export function gatesForComplexity(complexity) {
+    // NOTE: the return type is Required<BuildOptions> on purpose — the result is
+    // merged over ALL_BLOCKS (all-true) by the caller, so ANY omitted key would
+    // silently default to `true` and leak that block into a cheap tier (defeating
+    // the classifier's token savings). Keep these objects exhaustive.
     switch (complexity) {
         case 'trivial':
             // Greetings, "thanks", yes/no — only base SP + writing rules.
@@ -745,6 +959,7 @@ export function gatesForComplexity(complexity) {
                 includeFleet: false,
                 includeMemoryDirective: false,
                 includeLessonsDirective: false,
+                includeUserModelDirective: false,
                 includeWritingRules: true,
                 includeCodingStyle: false,
                 includeWorkflowRules: false,
@@ -753,7 +968,9 @@ export function gatesForComplexity(complexity) {
             };
         case 'simple':
             // Short questions, no code signals — base + identity + memory
-            // directives + rules + writing rules. Skip heavy bootstrap/docs/knowledge.
+            // directives + rules + writing rules. Skip heavy bootstrap/docs/knowledge
+            // AND the execution-discipline / user-model blocks (the tier is meant to
+            // be cheap; it already drops workflow rules for the same reason).
             return {
                 includeBootstrap: false,
                 includePersona: true,
@@ -765,9 +982,11 @@ export function gatesForComplexity(complexity) {
                 includeFleet: true,
                 includeMemoryDirective: true,
                 includeLessonsDirective: true,
+                includeUserModelDirective: false,
                 includeWritingRules: true,
                 includeCodingStyle: false,
                 includeWorkflowRules: false,
+                includeExecutionDiscipline: false,
                 includeVariation: true,
             };
         case 'complex':