codymaster 4.8.0 → 5.2.0

package/dist/indexer/skills.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateProjectSkillsIndex = generateProjectSkillsIndex;
+const skills_lib_1 = require("./skills-lib");
+/**
+ * Parses the project directory to detect the tech stack (using deterministic config file checks)
+ * and returns a miniaturized list of recommended AI skills.
+ */
+function generateProjectSkillsIndex(projectDir) {
+    const { detected, isFrontend, combos } = (0, skills_lib_1.detectTechnologies)(projectDir);
+    const skills = (0, skills_lib_1.collectSkills)({ detected, isFrontend, combos });
+    return {
+        detectedTechnologies: detected.map((tech) => tech.name),
+        recommendedSkills: skills.map((s) => s.skill),
+    };
+}

package/dist/learning-promoter.js

@@ -0,0 +1,246 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LearningPromoter = void 0;
+exports.formatPromotionCandidates = formatPromotionCandidates;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const storage_backend_1 = require("./storage-backend");
+// ─── Constants ──────────────────────────────────────────────────────────────
+const MIN_REINFORCEMENT = 3; // Minimum times a learning must be reinforced
+const MIN_PROMOTION_SCORE = 0.50; // Minimum score to qualify for promotion
+const PROMOTION_LOG = '.cm/evolution/promotions.jsonl';
+// ─── Learning Promoter ──────────────────────────────────────────────────────
+// TRIZ #22 "Blessing in Disguise" — failures become reusable knowledge
+/**
+ * LearningPromoter — Promotes mature learnings into reusable skills.
+ *
+ * When a learning has been reinforced enough times (appearing in multiple
+ * execution analyses or being manually confirmed), it graduates from
+ * ephemeral memory into a permanent skill entry.
+ *
+ * Flow:
+ *   1. Scan learnings in SQLite for candidates with high reinforcement
+ *   2. Score each candidate based on: reinforcement count, recency, category
+ *   3. Generate a minimal SKILL.md from the learning content
+ *   4. Save to skills/ directory
+ */
+class LearningPromoter {
+    constructor(projectPath, backend) {
+        this.projectPath = projectPath;
+        this.backend = backend !== null && backend !== void 0 ? backend : (0, storage_backend_1.getBackend)(projectPath);
+        this.backend.initialize();
+        this.skillsDir = this.findSkillsDir();
+    }
+    /**
+     * Find learnings that qualify for promotion.
+     */
+    findCandidates(limit = 10) {
+        var _a;
+        // Query all learnings and count reinforcement (same what_failed pattern)
+        const allLearnings = this.backend.queryLearnings('', undefined, 200);
+        const patternCounts = new Map();
+        for (const learning of allLearnings) {
+            const pattern = this.normalizePattern(learning.what_failed);
+            const existing = (_a = patternCounts.get(pattern)) !== null && _a !== void 0 ? _a : { count: 0, learnings: [] };
+            existing.count++;
+            existing.learnings.push(learning);
+            patternCounts.set(pattern, existing);
+        }
+        const candidates = [];
+        for (const [_pattern, { count, learnings }] of patternCounts) {
+            if (count < MIN_REINFORCEMENT)
+                continue;
+            // Use the most recent learning as the representative
+            const representative = learnings.sort((a, b) => new Date(b.created_at).getTime() - new Date(a.created_at).getTime())[0];
+            const score = this.calculateScore(count, representative);
+            if (score >= MIN_PROMOTION_SCORE) {
+                candidates.push({
+                    learning: representative,
+                    reinforcementCount: count,
+                    score,
+                    reason: `Reinforced ${count}x, score ${(score * 100).toFixed(0)}%`,
+                });
+            }
+        }
+        return candidates
+            .sort((a, b) => b.score - a.score)
+            .slice(0, limit);
+    }
+    /**
+     * Promote a specific learning to a skill.
+     */
+    promote(learningId) {
+        const learning = this.backend.getLearningById(learningId);
+        if (!learning) {
+            return {
+                promoted: false,
+                skillName: '',
+                skillPath: '',
+                learningId,
+                reason: `Learning ${learningId} not found.`,
+            };
+        }
+        // Generate skill name from the learning content
+        const skillName = this.generateSkillName(learning);
+        const skillDir = path_1.default.join(this.skillsDir, skillName);
+        if (fs_1.default.existsSync(skillDir)) {
+            return {
+                promoted: false,
+                skillName,
+                skillPath: skillDir,
+                learningId,
+                reason: `Skill ${skillName} already exists.`,
+            };
+        }
+        // Generate the SKILL.md content
+        const skillContent = this.generateSkillContent(learning, skillName);
+        // Create the skill
+        fs_1.default.mkdirSync(skillDir, { recursive: true });
+        const skillPath = path_1.default.join(skillDir, 'SKILL.md');
+        fs_1.default.writeFileSync(skillPath, skillContent, 'utf-8');
+        // Log the promotion
+        this.logPromotion(learningId, skillName, skillPath);
+        return {
+            promoted: true,
+            skillName,
+            skillPath,
+            learningId,
+            reason: `Learning promoted to skill: ${skillName}`,
+        };
+    }
+    /**
+     * Auto-promote: find candidates and promote the top one.
+     */
+    autoPromote() {
+        const candidates = this.findCandidates(1);
+        if (candidates.length === 0)
+            return null;
+        return this.promote(candidates[0].learning.id);
+    }
+    /**
+     * Get promotion history.
+     */
+    getPromotionHistory(limit = 20) {
+        const logPath = path_1.default.join(this.projectPath, PROMOTION_LOG);
+        if (!fs_1.default.existsSync(logPath))
+            return [];
+        const lines = fs_1.default.readFileSync(logPath, 'utf-8').trim().split('\n').filter(Boolean);
+        const entries = [];
+        for (const line of lines) {
+            try {
+                entries.push(JSON.parse(line));
+            }
+            catch ( /* skip */_a) { /* skip */ }
+        }
+        return entries.slice(-limit).reverse();
+    }
+    // ─── Private Helpers ────────────────────────────────────────────────────
+    findSkillsDir() {
+        const candidates = [
+            path_1.default.join(this.projectPath, 'skills'),
+            path_1.default.join(this.projectPath, '.agent', 'skills'),
+        ];
+        for (const dir of candidates) {
+            if (fs_1.default.existsSync(dir))
+                return dir;
+        }
+        return path_1.default.join(this.projectPath, 'skills');
+    }
+    normalizePattern(text) {
+        return text
+            .toLowerCase()
+            .replace(/[^\w\s]/g, '')
+            .replace(/\s+/g, ' ')
+            .trim()
+            .split(' ')
+            .sort()
+            .join(' ');
+    }
+    calculateScore(reinforcementCount, learning) {
+        // Reinforcement factor (0-0.5): more reinforcement = higher score
+        const reinforcementFactor = Math.min(0.5, reinforcementCount / 10);
+        // Recency factor (0-0.3): newer learnings score higher
+        const daysSince = (Date.now() - new Date(learning.created_at).getTime()) / (1000 * 60 * 60 * 24);
+        const recencyFactor = Math.max(0, 0.3 - (daysSince / 365) * 0.3);
+        // Content quality factor (0-0.2): longer, more detailed = better
+        const contentLength = (learning.what_failed.length + learning.how_to_prevent.length);
+        const qualityFactor = Math.min(0.2, contentLength / 500 * 0.2);
+        return reinforcementFactor + recencyFactor + qualityFactor;
+    }
+    generateSkillName(learning) {
+        const words = learning.what_failed
+            .toLowerCase()
+            .replace(/[^\w\s]/g, '')
+            .split(/\s+/)
+            .filter(w => w.length > 3)
+            .slice(0, 3);
+        const base = words.length > 0 ? words.join('-') : 'promoted';
+        return `cm-learned-${base}`;
+    }
+    generateSkillContent(learning, skillName) {
+        return [
+            '---',
+            `name: ${skillName}`,
+            `description: Auto-promoted from reinforced learning`,
+            '---',
+            '',
+            `# ${skillName}`,
+            '',
+            `> 🎓 Auto-promoted from learning on ${new Date().toISOString().split('T')[0]}`,
+            `> Original module: ${learning.module}`,
+            `> Agent: ${learning.agent}`,
+            '',
+            '## Problem Pattern',
+            '',
+            learning.what_failed,
+            '',
+            '## Root Cause',
+            '',
+            learning.why_failed,
+            '',
+            '## Prevention / Solution',
+            '',
+            learning.how_to_prevent,
+            '',
+            '## When to Apply',
+            '',
+            `Apply this skill when encountering patterns similar to: "${learning.what_failed.slice(0, 100)}"`,
+            '',
+            '## Steps',
+            '',
+            `1. Recognize the problem pattern described above`,
+            `2. Apply the prevention strategy: ${learning.how_to_prevent.slice(0, 100)}`,
+            `3. Verify the fix resolves the root cause`,
+            '',
+        ].join('\n');
+    }
+    logPromotion(learningId, skillName, skillPath) {
+        const logPath = path_1.default.join(this.projectPath, PROMOTION_LOG);
+        const dir = path_1.default.dirname(logPath);
+        if (!fs_1.default.existsSync(dir))
+            fs_1.default.mkdirSync(dir, { recursive: true });
+        const entry = { learningId, skillName, skillPath, promotedAt: new Date().toISOString() };
+        fs_1.default.appendFileSync(logPath, JSON.stringify(entry) + '\n');
+    }
+}
+exports.LearningPromoter = LearningPromoter;
+// ─── Display Helpers ─────────────────────────────────────────────────────────
+function formatPromotionCandidates(candidates) {
+    if (candidates.length === 0)
+        return 'No learnings qualify for promotion yet. Need ≥3 reinforcements.';
+    const lines = [
+        '🎓 Learning → Skill Promotion Candidates',
+        '─'.repeat(70),
+        `${'Score'.padEnd(8)} ${'Reinf'.padEnd(8)} Pattern`,
+        '─'.repeat(70),
+    ];
+    for (const c of candidates) {
+        const score = (c.score * 100).toFixed(0) + '%';
+        const pattern = c.learning.what_failed.slice(0, 50);
+        lines.push(`${score.padEnd(8)} ${(c.reinforcementCount + 'x').padEnd(8)} ${pattern}`);
+    }
+    return lines.join('\n');
+}

package/dist/mcp-context-server.js

@@ -3,7 +3,7 @@
 /**
  * CodyMaster MCP Context Server
  *
- * Exposes 13 tools over JSON-RPC 2.0 / stdio (Content-Length framing):
+ * Exposes 18 tools over JSON-RPC 2.0 / stdio (Content-Length framing):
  *   cm_query         — FTS5 search across learnings + decisions
  *   cm_resolve       — resolve a cm:// URI at L0/L1/L2
  *   cm_bus_read      — read context bus state
@@ -11,6 +11,7 @@
  *   cm_budget_check  — check token budget for a category
  *   cm_memory_decay  — TTL cleanup for learnings
  *   cm_index_refresh — regenerate L0 indexes
+ *   cm_advisory_report / cm_advisory_metrics / cm_advisory_handoff — advisory loop JSON surfaces
  *   cm_plan / cm_review / cm_qa / cm_deploy / cm_search / cm_memory_query — engineering kit bridge
  *
  * Usage (stdio MCP):
@@ -39,6 +40,9 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.cmAdvisoryReport = cmAdvisoryReport;
+exports.cmAdvisoryMetrics = cmAdvisoryMetrics;
+exports.cmAdvisoryHandoff = cmAdvisoryHandoff;
 const path_1 = __importDefault(require("path"));
 const context_db_1 = require("./context-db");
 const uri_resolver_1 = require("./uri-resolver");
@@ -46,6 +50,9 @@ const context_bus_1 = require("./context-bus");
 const token_budget_1 = require("./token-budget");
 const l0_indexer_1 = require("./l0-indexer");
 const mcp_skills_tools_1 = require("./mcp-skills-tools");
+const storage_backend_1 = require("./storage-backend");
+const advisory_report_1 = require("./advisory-report");
+const advisory_handoff_1 = require("./advisory-handoff");
 // ─── Config ──────────────────────────────────────────────────────────────────
 const SERVER_NAME = 'cm-context';
 const SERVER_VERSION = '1.0.0';
@@ -132,6 +139,84 @@ function cmBudgetCheck(args) {
         suggestion: check.suggestion,
     };
 }
+function autoDetectCategory(content) {
+    const c = content.toLowerCase();
+    if (/\b(decided|architecture|we chose|design decision|chose to)\b/.test(c))
+        return 'arch_decision';
+    if (/\b(bug|fixed|caused by|root cause|crash)\b/.test(c))
+        return 'bug_fix';
+    if (/\b(prefer|always use|never use|avoid|convention|standard)\b/.test(c))
+        return 'user_pref';
+    if (/\b(function|pattern|approach|method|implementation)\b/.test(c))
+        return 'code_pattern';
+    return 'context';
+}
+function cmMemoryWrite(args) {
+    var _a;
+    const { content, scope = 'project', category, ttl_days, importance = 'medium' } = args;
+    if (!(content === null || content === void 0 ? void 0 : content.trim()))
+        throw new Error('content is required');
+    const detectedCategory = category || autoDetectCategory(content);
+    const defaultTtl = { session: 30, project: 90, global: 365 };
+    const ttl = (_a = ttl_days !== null && ttl_days !== void 0 ? ttl_days : defaultTtl[scope]) !== null && _a !== void 0 ? _a : 90;
+    const now = new Date().toISOString();
+    const id = `nli-${Date.now()}-${Math.random().toString(36).slice(2, 7)}`;
+    const dbPath = (0, context_db_1.getDbPath)(PROJECT_PATH);
+    (0, context_db_1.insertLearning)(dbPath, {
+        id,
+        what_failed: content,
+        why_failed: detectedCategory,
+        how_to_prevent: `importance:${importance}`,
+        scope,
+        ttl,
+        reinforce_count: 0,
+        status: 'active',
+        created_at: now,
+        updated_at: now,
+        agent: 'cm_natural',
+    });
+    return { ok: true, id, content, category: detectedCategory, scope, ttl_days: ttl, importance };
+}
+const NLI_PATTERNS = [
+    { pattern: /\b(remember|save|note)\s+that\s+/i, action: 'write', scope: 'project' },
+    { pattern: /\b(remember|save)\s+this[:\s]/i, action: 'write', scope: 'project' },
+    { pattern: /\bimportant[:\s]+/i, action: 'write', scope: 'project', importance: 'high' },
+    { pattern: /\b(forget|remove|ignore)\s+(about\s+)?/i, action: 'decay' },
+    { pattern: /\bwhat\s+did\s+we\s+(learn|know)\b/i, action: 'query' },
+    { pattern: /\bwhat\s+do\s+we\s+know\b/i, action: 'query' },
+    { pattern: /\blessons?\s+learned\b/i, action: 'query' },
+    { pattern: /\b(search|find|look\s+up)\b/i, action: 'query' },
+];
+function cmNatural(args) {
+    var _a, _b, _c;
+    const { text } = args;
+    if (!(text === null || text === void 0 ? void 0 : text.trim()))
+        throw new Error('text is required');
+    for (const rule of NLI_PATTERNS) {
+        const match = text.match(rule.pattern);
+        if (!match)
+            continue;
+        const extracted = text.slice(((_a = match.index) !== null && _a !== void 0 ? _a : 0) + match[0].length).trim();
+        if (rule.action === 'write') {
+            const result = cmMemoryWrite({
+                content: extracted || text,
+                scope: (_b = rule.scope) !== null && _b !== void 0 ? _b : 'project',
+                importance: (_c = rule.importance) !== null && _c !== void 0 ? _c : 'medium',
+            });
+            return Object.assign(Object.assign({}, result), { matched_pattern: rule.pattern.source, routed_to: 'cm_memory_write' });
+        }
+        if (rule.action === 'decay') {
+            const result = cmMemoryDecay({ dry_run: false });
+            return Object.assign(Object.assign({}, result), { matched_pattern: rule.pattern.source, routed_to: 'cm_memory_decay' });
+        }
+        // query / search
+        const result = cmQuery({ query: extracted || text, scope: 'all', limit: 10 });
+        return Object.assign(Object.assign({}, result), { matched_pattern: rule.pattern.source, routed_to: 'cm_query' });
+    }
+    // No pattern matched — default to search
+    const result = cmQuery({ query: text, scope: 'all', limit: 10 });
+    return Object.assign(Object.assign({}, result), { matched_pattern: null, routed_to: 'cm_query (default)' });
+}
 function cmMemoryDecay(args) {
     const { dry_run = false } = args;
     const dbPath = (0, context_db_1.getDbPath)(PROJECT_PATH);
@@ -188,6 +273,55 @@ function cmIndexRefresh(args) {
     }
     throw new Error(`Unknown target: ${target}. Valid: learnings, skeleton, all`);
 }
+function cmAdvisoryReport(args) {
+    var _a;
+    const backend = (0, storage_backend_1.getBackend)(PROJECT_PATH);
+    backend.initialize();
+    try {
+        const limit = Math.max(1, (_a = args.limit) !== null && _a !== void 0 ? _a : 10);
+        const analyses = (0, advisory_report_1.buildAdvisoryReportData)(backend, { limit });
+        return {
+            count: analyses.length,
+            analyses,
+            generated_at: new Date().toISOString(),
+        };
+    }
+    finally {
+        backend.close();
+    }
+}
+function cmAdvisoryMetrics(args) {
+    var _a;
+    const backend = (0, storage_backend_1.getBackend)(PROJECT_PATH);
+    backend.initialize();
+    try {
+        const limit = Math.max(1, (_a = args.limit) !== null && _a !== void 0 ? _a : 10);
+        const metrics = (0, advisory_report_1.buildAdvisoryMetricsData)(backend, { limit });
+        return {
+            count: metrics.length,
+            metrics,
+            generated_at: new Date().toISOString(),
+        };
+    }
+    finally {
+        backend.close();
+    }
+}
+function cmAdvisoryHandoff(args) {
+    const backend = (0, storage_backend_1.getBackend)(PROJECT_PATH);
+    backend.initialize();
+    try {
+        return (0, advisory_handoff_1.buildAdvisoryHandoff)(backend, {
+            consumer: args.consumer,
+            analysisId: args.analysis_id,
+            skill: args.skill,
+            searchLimit: args.limit,
+        });
+    }
+    finally {
+        backend.close();
+    }
+}
 // ─── Tool Registry ─────────────────────────────────────────────────────────────
 const TOOLS = [
     {
@@ -297,6 +431,53 @@ const TOOLS = [
             },
         },
     },
+    {
+        name: 'cm_advisory_report',
+        description: 'Return recent advisory analyses as structured JSON for agent consumption.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                limit: { type: 'number', description: 'Max analyses to return (default: 10)' },
+            },
+        },
+    },
+    {
+        name: 'cm_advisory_metrics',
+        description: 'Return aggregated skill metrics and quality weights as structured JSON.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                limit: { type: 'number', description: 'Max skills to return (default: 10)' },
+            },
+        },
+    },
+    {
+        name: 'cm_advisory_handoff',
+        description: 'Build a structured advisory handoff for cm-skill-health or cm-skill-evolution.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                consumer: {
+                    type: 'string',
+                    enum: ['cm-skill-health', 'cm-skill-evolution'],
+                    description: 'Which self-healing skill should consume the handoff',
+                },
+                analysis_id: {
+                    type: 'string',
+                    description: 'Optional analysis id prefix (defaults to latest advisory analysis)',
+                },
+                skill: {
+                    type: 'string',
+                    description: 'Optional skill override when the target skill should be forced',
+                },
+                limit: {
+                    type: 'number',
+                    description: 'How many recent analyses to search while resolving analysis_id (default: 50)',
+                },
+            },
+            required: ['consumer'],
+        },
+    },
     {
         name: 'cm_plan',
         description: 'Sprint + context bus snapshot: pipeline state, next skill hint, artifact paths.',
@@ -342,6 +523,44 @@ const TOOLS = [
             required: ['query'],
         },
     },
+    {
+        name: 'cm_memory_write',
+        description: 'Write a new memory/learning to persistent storage. Use to save knowledge, decisions, preferences, or patterns for future sessions.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                content: { type: 'string', description: 'What to remember (the memory content)' },
+                scope: {
+                    type: 'string',
+                    enum: ['session', 'project', 'global'],
+                    description: 'Memory scope: session=30d, project=90d, global=365d (default: project)',
+                },
+                category: {
+                    type: 'string',
+                    enum: ['code_pattern', 'arch_decision', 'bug_fix', 'user_pref', 'context'],
+                    description: 'Category (auto-detected from content if omitted)',
+                },
+                ttl_days: { type: 'number', description: 'Override TTL in days' },
+                importance: {
+                    type: 'string',
+                    enum: ['low', 'medium', 'high'],
+                    description: 'Importance level (default: medium)',
+                },
+            },
+            required: ['content'],
+        },
+    },
+    {
+        name: 'cm_natural',
+        description: 'Natural language memory interface. Understands "remember that...", "forget about...", "what did we learn about...", "find...". Routes to appropriate memory operation automatically.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                text: { type: 'string', description: 'Freeform natural language instruction or question' },
+            },
+            required: ['text'],
+        },
+    },
 ];
 // ─── MCP stdio protocol (JSON-RPC 2.0, Content-Length framing) ───────────────
 function sendMessage(msg) {
@@ -391,6 +610,12 @@ function handleRequest(msg) {
                     result = cmMemoryDecay(a);
                 else if (name === 'cm_index_refresh')
                     result = cmIndexRefresh(a);
+                else if (name === 'cm_advisory_report')
+                    result = cmAdvisoryReport(a);
+                else if (name === 'cm_advisory_metrics')
+                    result = cmAdvisoryMetrics(a);
+                else if (name === 'cm_advisory_handoff')
+                    result = cmAdvisoryHandoff(a);
                 else if (name === 'cm_plan')
                     result = (0, mcp_skills_tools_1.cmPlanTool)(PROJECT_PATH);
                 else if (name === 'cm_review')
@@ -403,6 +628,10 @@ function handleRequest(msg) {
                     result = (0, mcp_skills_tools_1.cmSearchTool)(PROJECT_PATH, a);
                 else if (name === 'cm_memory_query')
                     result = (0, mcp_skills_tools_1.cmMemoryQueryTool)(PROJECT_PATH, a);
+                else if (name === 'cm_memory_write')
+                    result = cmMemoryWrite(a);
+                else if (name === 'cm_natural')
+                    result = cmNatural(a);
                 else
                     throw new Error(`Unknown tool: ${name}`);
                 respond(id, {

package/dist/skill-chain.js

@@ -4,6 +4,8 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.matchChain = matchChain;
+exports.scoreStepRelevance = scoreStepRelevance;
+exports.selectTopSkills = selectTopSkills;
 exports.listChains = listChains;
 exports.findChain = findChain;
 exports.createChainExecution = createChainExecution;
@@ -17,6 +19,8 @@ exports.getCurrentSkill = getCurrentSkill;
 const crypto_1 = __importDefault(require("crypto"));
 const builtin_1 = require("./chains/builtin");
 const context_bus_1 = require("./context-bus");
+const execution_analyzer_1 = require("./execution-analyzer");
+const storage_backend_1 = require("./storage-backend");
 // ─── Chain Matching ─────────────────────────────────────────────────────────
 // TRIZ #10: Preliminary Action — analyze task BEFORE dispatching
 /**
@@ -43,6 +47,53 @@ function matchChain(taskTitle) {
     }
     return bestMatch;
 }
+// ─── Intelligent Skill Selection (SkillsBench: 2-3 skills = +18.6pp) ────────
+// TRIZ #1: Segmentation — select only relevant sub-components
+/**
+ * Score a single chain step's relevance to the given task title.
+ * Mandatory steps (optional=false, condition='always') receive a +100 base bonus
+ * to ensure they are always prioritised over optional ones.
+ */
+function scoreStepRelevance(taskTitle, step) {
+    const taskTokens = new Set(taskTitle.toLowerCase().split(/\W+/).filter(t => t.length > 2));
+    const descTokens = step.description.toLowerCase().split(/\W+/).filter(t => t.length > 2);
+    const overlap = descTokens.filter(t => taskTokens.has(t)).length;
+    const mandatoryBonus = (!step.optional && step.condition === 'always') ? 100 : 0;
+    return overlap + mandatoryBonus;
+}
+/**
+ * Select the most relevant skills for a task, capped at maxSkills.
+ *
+ * Rules:
+ * - Mandatory steps (optional=false AND condition='always') are ALWAYS included,
+ *   even if their count exceeds maxSkills (safety > optimisation).
+ * - Remaining slots are filled with the highest-scoring optional steps.
+ * - If mandatory count > maxSkills, a performance warning is emitted.
+ */
+function selectTopSkills(taskTitle, chain, maxSkills = 3, options = {}) {
+    const mandatory = chain.steps.filter(s => !s.optional && s.condition === 'always');
+    const optional = chain.steps.filter(s => s.optional || s.condition !== 'always');
+    if (mandatory.length > maxSkills) {
+        process.stderr.write(`[CodyMaster] Chain "${chain.name}" has ${mandatory.length} mandatory steps (>${maxSkills}). ` +
+            `Consider splitting this chain. (SkillsBench: 2-3 skills = +18.6pp)\n`);
+        return mandatory; // include all mandatory — cannot safely drop them
+    }
+    const remaining = maxSkills - mandatory.length;
+    const scoredOptional = optional
+        .map(step => {
+        var _a, _b;
+        const relevance = scoreStepRelevance(taskTitle, step);
+        const metric = (_b = (_a = options.getSkillMetric) === null || _a === void 0 ? void 0 : _a.call(options, step.skill)) !== null && _b !== void 0 ? _b : null;
+        const quality = (0, execution_analyzer_1.qualityWeight)(metric);
+        return { step, score: relevance + quality, relevance, quality };
+    })
+        .sort((a, b) => b.score - a.score)
+        .slice(0, remaining)
+        .map(({ step }) => step);
+    // Preserve original chain order
+    const selected = new Set([...mandatory, ...scoredOptional]);
+    return chain.steps.filter(s => selected.has(s));
+}
 /**
  * List all available chains (built-in + user-defined in the future).
  */
@@ -62,7 +113,18 @@ function findChain(chainId) {
  */
 function createChainExecution(chain, projectId, taskTitle, agent, projectPath) {
     const now = new Date().toISOString();
-    const steps = chain.steps.map((step, index) => ({
+    const backend = projectPath ? (0, storage_backend_1.getBackend)(projectPath) : undefined;
+    let selectedSteps;
+    backend === null || backend === void 0 ? void 0 : backend.initialize();
+    try {
+        selectedSteps = selectTopSkills(taskTitle, chain, 3, {
+            getSkillMetric: backend ? (skill) => backend.getSkillMetric(skill) : undefined,
+        });
+    }
+    finally {
+        backend === null || backend === void 0 ? void 0 : backend.close();
+    }
+    const steps = selectedSteps.map((step, index) => ({
         index,
         skill: step.skill,
         description: step.description,