@shepai/cli 1.175.1 → 1.176.0-pr539.02342cf

package/dist/packages/core/src/infrastructure/services/token-optimization/optimization-metrics.service.js

@@ -0,0 +1,123 @@
+/**
+ * Optimization Metrics Service
+ *
+ * Persists token optimization metrics on existing PhaseTiming records.
+ * Updates the per-phase timing entry with optimization statistics so the
+ * data is queryable alongside timing and cost data via the existing
+ * phase timing infrastructure.
+ *
+ * Failure-tolerant: any persistence error is swallowed (after best-effort
+ * logging) so optimization metric recording can never break a phase run.
+ */
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+import { injectable, inject } from 'tsyringe';
+/**
+ * Parse the JSON-serialized capabilitiesApplied column. Returns an
+ * empty array on malformed JSON so a corrupted row never throws on read.
+ */
+function parseCapabilitiesApplied(serialized) {
+    if (serialized === undefined || serialized === null) {
+        return [];
+    }
+    try {
+        const parsed = JSON.parse(serialized);
+        return Array.isArray(parsed)
+            ? parsed.filter((item) => typeof item === 'string')
+            : [];
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Build an OptimizationMetrics object from a PhaseTiming row.
+ *
+ * Returns null when the row has no optimization columns populated
+ * (record was created but optimizer never ran for it).
+ */
+function metricsFromPhaseTiming(timing) {
+    // If no optimization fields are present at all, treat as "no metrics".
+    if (timing.originalTokenEstimate === undefined &&
+        timing.optimizedTokenEstimate === undefined &&
+        timing.savingsPercent === undefined &&
+        timing.capabilitiesApplied === undefined) {
+        return null;
+    }
+    return {
+        originalTokenEstimate: timing.originalTokenEstimate !== undefined ? Number(timing.originalTokenEstimate) : 0,
+        optimizedTokenEstimate: timing.optimizedTokenEstimate !== undefined ? Number(timing.optimizedTokenEstimate) : 0,
+        savingsPercent: timing.savingsPercent ?? 0,
+        capabilitiesApplied: parseCapabilitiesApplied(timing.capabilitiesApplied),
+        outputFilterLinesRemoved: timing.outputFilterLinesRemoved ?? 0,
+        deltaContextFilesSkipped: timing.deltaContextFilesSkipped ?? 0,
+        compressionRatio: timing.compressionRatio ?? 1.0,
+        aliasesCreated: timing.aliasesCreated ?? 0,
+    };
+}
+let OptimizationMetricsService = class OptimizationMetricsService {
+    phaseTimingRepository;
+    constructor(phaseTimingRepository) {
+        this.phaseTimingRepository = phaseTimingRepository;
+    }
+    /**
+     * Persist optimization metrics on the named PhaseTiming row.
+     *
+     * Token estimates are stored as bigint (PhaseTiming column type),
+     * capabilitiesApplied is serialized as a JSON string for the
+     * existing string column.
+     */
+    async record(phaseTimingId, metrics) {
+        try {
+            await this.phaseTimingRepository.update(phaseTimingId, {
+                originalTokenEstimate: BigInt(metrics.originalTokenEstimate),
+                optimizedTokenEstimate: BigInt(metrics.optimizedTokenEstimate),
+                savingsPercent: metrics.savingsPercent,
+                capabilitiesApplied: JSON.stringify(metrics.capabilitiesApplied),
+                outputFilterLinesRemoved: metrics.outputFilterLinesRemoved,
+                deltaContextFilesSkipped: metrics.deltaContextFilesSkipped,
+                compressionRatio: metrics.compressionRatio,
+                aliasesCreated: metrics.aliasesCreated,
+            });
+        }
+        catch {
+            // Persistence failure must never break optimization
+        }
+    }
+    /**
+     * Retrieve previously recorded optimization metrics for a phase timing.
+     *
+     * Returns null when:
+     *   - the phase timing record does not exist
+     *   - the phase timing exists but has no optimization columns populated
+     *   - the underlying repository read fails
+     */
+    async getByPhaseTimingId(phaseTimingId) {
+        try {
+            const timing = await this.phaseTimingRepository.findById(phaseTimingId);
+            if (!timing) {
+                return null;
+            }
+            return metricsFromPhaseTiming(timing);
+        }
+        catch {
+            return null;
+        }
+    }
+};
+OptimizationMetricsService = __decorate([
+    injectable(),
+    __param(0, inject('IPhaseTimingRepository')),
+    __metadata("design:paramtypes", [Object])
+], OptimizationMetricsService);
+export { OptimizationMetricsService };

package/dist/packages/core/src/infrastructure/services/token-optimization/prompt-optimizer.service.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Prompt Optimizer Service
+ *
+ * Top-level orchestrator for the token optimization layer. Composes the
+ * five capability services (delta-context, command output filter, skill
+ * routing, semantic compressor, alias compression) into a sequential
+ * pipeline driven by per-capability settings toggles.
+ *
+ * Pipeline order (from research decisions):
+ *   1. Output filter   - removes the most raw text early
+ *   2. Skill routing   - prepends a small directive section
+ *   3. Delta-context   - replaces unchanged spec files with summaries
+ *   4. Semantic compr  - compresses remaining natural language
+ *   5. Alias engine    - finds repeated long strings in the final text
+ *
+ * Each stage runs only when its individual toggle is true. The master
+ * toggle (config.enabled) short-circuits the pipeline entirely.
+ *
+ * Metrics from each stage are aggregated into the OptimizationMetrics
+ * record returned alongside the optimized prompt.
+ */
+import type { IPromptOptimizerService, PromptOptimizationContext, PromptOptimizationResult } from '../../../application/ports/output/services/prompt-optimizer.interface.js';
+import type { ICommandOutputFilterService } from '../../../application/ports/output/services/command-output-filter.interface.js';
+import type { ISkillRoutingService } from '../../../application/ports/output/services/skill-routing.interface.js';
+import type { IDeltaContextService } from '../../../application/ports/output/services/delta-context.interface.js';
+import type { ISemanticCompressorService } from '../../../application/ports/output/services/semantic-compressor.interface.js';
+import type { IAliasCompressionService } from '../../../application/ports/output/services/alias-compression.interface.js';
+import type { IOptimizationMetricsService } from '../../../application/ports/output/services/optimization-metrics.interface.js';
+export declare class PromptOptimizerService implements IPromptOptimizerService {
+    private readonly outputFilter;
+    private readonly skillRouting;
+    private readonly deltaContext;
+    private readonly semanticCompressor;
+    private readonly aliasCompression;
+    private readonly metricsService;
+    constructor(outputFilter: ICommandOutputFilterService, skillRouting: ISkillRoutingService, deltaContext: IDeltaContextService, semanticCompressor: ISemanticCompressorService, aliasCompression: IAliasCompressionService, metricsService: IOptimizationMetricsService);
+    /**
+     * Optimize a raw prompt by running enabled capability services in sequence.
+     *
+     * Returns the original prompt with zero-delta metrics when the master
+     * toggle is off. Each capability is independently skippable via its
+     * config toggle.
+     */
+    optimize(prompt: string, context: PromptOptimizationContext): Promise<PromptOptimizationResult>;
+    /**
+     * Persist metrics via the metrics service when a phaseTimingId is
+     * provided in the context. Failures are swallowed so a metrics
+     * persistence problem can never break the optimization pipeline.
+     */
+    private recordMetricsIfPossible;
+    /**
+     * Log a debug-level summary of optimizations applied for observability.
+     * Failure to log must never affect optimization output.
+     */
+    private logSummary;
+}
+//# sourceMappingURL=prompt-optimizer.service.d.ts.map

package/dist/packages/core/src/infrastructure/services/token-optimization/prompt-optimizer.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompt-optimizer.service.d.ts","sourceRoot":"","sources":["../../../../../../../packages/core/src/infrastructure/services/token-optimization/prompt-optimizer.service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAIH,OAAO,KAAK,EACV,uBAAuB,EACvB,yBAAyB,EACzB,wBAAwB,EAEzB,MAAM,mEAAmE,CAAC;AAC3E,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,wEAAwE,CAAC;AAC1H,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,gEAAgE,CAAC;AAC3G,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,gEAAgE,CAAC;AAC3G,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,sEAAsE,CAAC;AACvH,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,oEAAoE,CAAC;AACnH,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,uEAAuE,CAAC;AAkCzH,qBACa,sBAAuB,YAAW,uBAAuB;IAGlE,OAAO,CAAC,QAAQ,CAAC,YAAY;IAE7B,OAAO,CAAC,QAAQ,CAAC,YAAY;IAE7B,OAAO,CAAC,QAAQ,CAAC,YAAY;IAE7B,OAAO,CAAC,QAAQ,CAAC,kBAAkB;IAEnC,OAAO,CAAC,QAAQ,CAAC,gBAAgB;IAEjC,OAAO,CAAC,QAAQ,CAAC,cAAc;gBAVd,YAAY,EAAE,2BAA2B,EAEzC,YAAY,EAAE,oBAAoB,EAElC,YAAY,EAAE,oBAAoB,EAElC,kBAAkB,EAAE,0BAA0B,EAE9C,gBAAgB,EAAE,wBAAwB,EAE1C,cAAc,EAAE,2BAA2B;IAG9D;;;;;;OAMG;IACG,QAAQ,CACZ,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,yBAAyB,GACjC,OAAO,CAAC,wBAAwB,CAAC;IA4FpC;;;;OAIG;YACW,uBAAuB;IAcrC;;;OAGG;IACH,OAAO,CAAC,UAAU;CAkBnB"}

package/dist/packages/core/src/infrastructure/services/token-optimization/prompt-optimizer.service.js

@@ -0,0 +1,211 @@
+/**
+ * Prompt Optimizer Service
+ *
+ * Top-level orchestrator for the token optimization layer. Composes the
+ * five capability services (delta-context, command output filter, skill
+ * routing, semantic compressor, alias compression) into a sequential
+ * pipeline driven by per-capability settings toggles.
+ *
+ * Pipeline order (from research decisions):
+ *   1. Output filter   - removes the most raw text early
+ *   2. Skill routing   - prepends a small directive section
+ *   3. Delta-context   - replaces unchanged spec files with summaries
+ *   4. Semantic compr  - compresses remaining natural language
+ *   5. Alias engine    - finds repeated long strings in the final text
+ *
+ * Each stage runs only when its individual toggle is true. The master
+ * toggle (config.enabled) short-circuits the pipeline entirely.
+ *
+ * Metrics from each stage are aggregated into the OptimizationMetrics
+ * record returned alongside the optimized prompt.
+ */
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+import { injectable, inject } from 'tsyringe';
+/** Token estimate heuristic: chars / TOKEN_CHAR_RATIO. */
+const TOKEN_CHAR_RATIO = 4;
+/** Capability identifier strings recorded in metrics.capabilitiesApplied. */
+const CAPABILITY = {
+    outputFiltering: 'outputFiltering',
+    skillRouting: 'skillRouting',
+    deltaContext: 'deltaContext',
+    semanticCompression: 'semanticCompression',
+    aliasCompression: 'aliasCompression',
+};
+/** Estimate tokens from character length using the chars/4 heuristic. */
+function estimateTokens(text) {
+    return Math.floor(text.length / TOKEN_CHAR_RATIO);
+}
+/** Build a zero-delta metrics record (used when no optimization is applied). */
+function buildPassthroughMetrics(prompt) {
+    const tokens = estimateTokens(prompt);
+    return {
+        originalTokenEstimate: tokens,
+        optimizedTokenEstimate: tokens,
+        savingsPercent: 0,
+        capabilitiesApplied: [],
+        outputFilterLinesRemoved: 0,
+        deltaContextFilesSkipped: 0,
+        compressionRatio: 1.0,
+        aliasesCreated: 0,
+    };
+}
+let PromptOptimizerService = class PromptOptimizerService {
+    outputFilter;
+    skillRouting;
+    deltaContext;
+    semanticCompressor;
+    aliasCompression;
+    metricsService;
+    constructor(outputFilter, skillRouting, deltaContext, semanticCompressor, aliasCompression, metricsService) {
+        this.outputFilter = outputFilter;
+        this.skillRouting = skillRouting;
+        this.deltaContext = deltaContext;
+        this.semanticCompressor = semanticCompressor;
+        this.aliasCompression = aliasCompression;
+        this.metricsService = metricsService;
+    }
+    /**
+     * Optimize a raw prompt by running enabled capability services in sequence.
+     *
+     * Returns the original prompt with zero-delta metrics when the master
+     * toggle is off. Each capability is independently skippable via its
+     * config toggle.
+     */
+    async optimize(prompt, context) {
+        const config = context.config;
+        // Master toggle off — return prompt unchanged with zero-delta metrics.
+        if (!config?.enabled) {
+            return {
+                prompt,
+                metrics: buildPassthroughMetrics(prompt),
+                specFileHashes: context.previousSpecFileHashes ?? {},
+            };
+        }
+        const originalTokenEstimate = estimateTokens(prompt);
+        const capabilitiesApplied = [];
+        let working = prompt;
+        // Per-capability metric accumulators
+        let outputFilterLinesRemoved = 0;
+        const deltaContextFilesSkipped = 0;
+        let compressionRatio = 1.0;
+        let aliasesCreated = 0;
+        const specFileHashes = context.previousSpecFileHashes ?? {};
+        // 1. Command output filter — remove the most raw text first.
+        if (config.outputFiltering) {
+            const result = this.outputFilter.filter(working);
+            working = result.filtered;
+            outputFilterLinesRemoved = result.linesRemoved;
+            capabilitiesApplied.push(CAPABILITY.outputFiltering);
+        }
+        // 2. Skill routing — prepend the phase-relevant skill directive.
+        if (config.skillRouting) {
+            const routing = this.skillRouting.getRoutingDirective(context.phaseName);
+            if (routing.directive.length > 0) {
+                working = `${routing.directive}\n\n${working}`;
+            }
+            capabilitiesApplied.push(CAPABILITY.skillRouting);
+        }
+        // 3. Delta-context — note: the orchestrator does not own spec file
+        //    reads (those happen in prompt builders). When invoked here we
+        //    simply mark the capability as applied and propagate hashes from
+        //    context. The capability service is exposed for direct use by
+        //    prompt builders that want to apply hash-based summaries inline.
+        if (config.deltaContext) {
+            capabilitiesApplied.push(CAPABILITY.deltaContext);
+        }
+        // 4. Semantic compressor — compress remaining natural language.
+        if (config.semanticCompression) {
+            const result = this.semanticCompressor.compress(working);
+            working = result.compressed;
+            compressionRatio = result.compressionRatio;
+            capabilitiesApplied.push(CAPABILITY.semanticCompression);
+        }
+        // 5. Alias engine — find repeated long strings in the final text.
+        if (config.aliasCompression) {
+            const result = this.aliasCompression.compress(working);
+            working = result.compressed;
+            aliasesCreated = result.aliasCount;
+            capabilitiesApplied.push(CAPABILITY.aliasCompression);
+        }
+        const optimizedTokenEstimate = estimateTokens(working);
+        const savingsPercent = originalTokenEstimate > 0
+            ? ((originalTokenEstimate - optimizedTokenEstimate) / originalTokenEstimate) * 100
+            : 0;
+        const metrics = {
+            originalTokenEstimate,
+            optimizedTokenEstimate,
+            savingsPercent: Math.max(0, savingsPercent),
+            capabilitiesApplied,
+            outputFilterLinesRemoved,
+            deltaContextFilesSkipped,
+            compressionRatio,
+            aliasesCreated,
+        };
+        this.logSummary(context, metrics);
+        await this.recordMetricsIfPossible(context, metrics);
+        return {
+            prompt: working,
+            metrics,
+            specFileHashes,
+        };
+    }
+    /**
+     * Persist metrics via the metrics service when a phaseTimingId is
+     * provided in the context. Failures are swallowed so a metrics
+     * persistence problem can never break the optimization pipeline.
+     */
+    async recordMetricsIfPossible(context, metrics) {
+        if (!context.phaseTimingId) {
+            return;
+        }
+        try {
+            await this.metricsService.record(context.phaseTimingId, metrics);
+        }
+        catch {
+            // Metrics persistence failure must never break optimization
+        }
+    }
+    /**
+     * Log a debug-level summary of optimizations applied for observability.
+     * Failure to log must never affect optimization output.
+     */
+    logSummary(context, metrics) {
+        try {
+            const savings = metrics.savingsPercent.toFixed(1);
+            const caps = metrics.capabilitiesApplied.join(',');
+            // Use process.stderr.write at debug level (no console pollution)
+            if (process.env.SHEP_DEBUG_OPTIMIZER === '1') {
+                process.stderr.write(`[token-optimizer] phase=${context.phaseName} ` +
+                    `original=${metrics.originalTokenEstimate} ` +
+                    `optimized=${metrics.optimizedTokenEstimate} ` +
+                    `savings=${savings}% ` +
+                    `capabilities=${caps}\n`);
+            }
+        }
+        catch {
+            // Logging failure must never break optimization
+        }
+    }
+};
+PromptOptimizerService = __decorate([
+    injectable(),
+    __param(0, inject('ICommandOutputFilterService')),
+    __param(1, inject('ISkillRoutingService')),
+    __param(2, inject('IDeltaContextService')),
+    __param(3, inject('ISemanticCompressorService')),
+    __param(4, inject('IAliasCompressionService')),
+    __param(5, inject('IOptimizationMetricsService')),
+    __metadata("design:paramtypes", [Object, Object, Object, Object, Object, Object])
+], PromptOptimizerService);
+export { PromptOptimizerService };

package/dist/packages/core/src/infrastructure/services/token-optimization/semantic-compressor.service.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Semantic Compressor Service
+ *
+ * Rule-based caveman compression for non-code prompt sections. Uses a
+ * protect-then-compress strategy: extract protected regions (code blocks,
+ * file paths, URLs, JSON, quoted strings) as placeholders, apply compression
+ * rules to the remaining natural language, then restore protected regions.
+ *
+ * Compression rules (in order):
+ * 1. Phrase shortening (multi-word → shorter equivalent)
+ * 2. Filler word removal (just, simply, basically, actually, really, currently)
+ * 3. Article removal (a, an, the)
+ * 4. Technical term abbreviation (repository → repo, etc.)
+ * 5. Whitespace collapsing (multiple blanks → single)
+ */
+import type { ISemanticCompressorService, SemanticCompressionResult } from '../../../application/ports/output/services/semantic-compressor.interface.js';
+export declare class SemanticCompressorService implements ISemanticCompressorService {
+    /**
+     * Compress natural language text in a prompt.
+     *
+     * Strategy:
+     * 1. Extract all protected regions and replace with placeholders
+     * 2. Apply compression rules to remaining text
+     * 3. Restore protected regions from placeholders
+     * 4. Calculate compression ratio
+     */
+    compress(text: string): SemanticCompressionResult;
+    private applyPhraseShortening;
+    private removeFillerWords;
+    private removeArticles;
+    private abbreviateTerms;
+    private collapseWhitespace;
+}
+//# sourceMappingURL=semantic-compressor.service.d.ts.map

package/dist/packages/core/src/infrastructure/services/token-optimization/semantic-compressor.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"semantic-compressor.service.d.ts","sourceRoot":"","sources":["../../../../../../../packages/core/src/infrastructure/services/token-optimization/semantic-compressor.service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EACV,0BAA0B,EAC1B,yBAAyB,EAC1B,MAAM,sEAAsE,CAAC;AAwF9E,qBAAa,yBAA0B,YAAW,0BAA0B;IAC1E;;;;;;;;OAQG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,yBAAyB;IAoDjD,OAAO,CAAC,qBAAqB;IAQ7B,OAAO,CAAC,iBAAiB;IAQzB,OAAO,CAAC,cAAc;IAQtB,OAAO,CAAC,eAAe;IAQvB,OAAO,CAAC,kBAAkB;CAmB3B"}

package/dist/packages/core/src/infrastructure/services/token-optimization/semantic-compressor.service.js

@@ -0,0 +1,190 @@
+/**
+ * Semantic Compressor Service
+ *
+ * Rule-based caveman compression for non-code prompt sections. Uses a
+ * protect-then-compress strategy: extract protected regions (code blocks,
+ * file paths, URLs, JSON, quoted strings) as placeholders, apply compression
+ * rules to the remaining natural language, then restore protected regions.
+ *
+ * Compression rules (in order):
+ * 1. Phrase shortening (multi-word → shorter equivalent)
+ * 2. Filler word removal (just, simply, basically, actually, really, currently)
+ * 3. Article removal (a, an, the)
+ * 4. Technical term abbreviation (repository → repo, etc.)
+ * 5. Whitespace collapsing (multiple blanks → single)
+ */
+/** Placeholder prefix used for protected regions. */
+const PLACEHOLDER_PREFIX = '\x00PROT_';
+const PLACEHOLDER_SUFFIX = '\x00';
+/**
+ * Multi-word phrase replacements. Order matters: longer phrases first to
+ * prevent partial matches. Applied case-insensitively.
+ */
+const PHRASE_REPLACEMENTS = [
+    [/\bdue to the fact that\b/gi, 'because'],
+    [/\bit is important to\b/gi, 'important:'],
+    [/\bplease note that\b/gi, 'note:'],
+    [/\bin addition to\b/gi, 'besides'],
+    [/\ba number of\b/gi, 'several'],
+    [/\bat this point\b/gi, 'now'],
+    [/\bmake sure to\b/gi, 'ensure'],
+    [/\bin order to\b/gi, 'to'],
+    [/\bas well as\b/gi, 'and'],
+    [/\byou must\b/gi, 'must'],
+    [/\byou should\b/gi, 'should'],
+];
+/**
+ * Filler words removed entirely (with surrounding space normalization).
+ */
+const FILLER_WORDS = [
+    /\bjust\b/gi,
+    /\bsimply\b/gi,
+    /\bbasically\b/gi,
+    /\bactually\b/gi,
+    /\breally\b/gi,
+    /\bcurrently\b/gi,
+];
+/**
+ * Articles removed (with word boundary awareness).
+ */
+const ARTICLES = [/\bthe\b/gi, /\ban\b/gi, /\ba\b(?=\s)/gi];
+/**
+ * Technical term abbreviations. Applied with word boundaries.
+ */
+const TERM_ABBREVIATIONS = [
+    [/\bimplementation\b/gi, 'impl'],
+    [/\bconfiguration\b/gi, 'config'],
+    [/\bspecification\b/gi, 'spec'],
+    [/\benvironment\b/gi, 'env'],
+    [/\bapplication\b/gi, 'app'],
+    [/\brepository\b/gi, 'repo'],
+    [/\bdependencies\b/gi, 'deps'],
+    [/\bdependency\b/gi, 'dep'],
+    [/\bdirectory\b/gi, 'dir'],
+    [/\bfunction\b/gi, 'fn'],
+];
+/**
+ * Regex patterns for detecting protected regions in the prompt text.
+ */
+/** Fenced code blocks: ```...``` (with optional language tag) */
+const FENCED_CODE_BLOCK_RE = /```[\s\S]*?```/g;
+/** Indented code blocks: lines starting with 4+ spaces (consecutive) */
+const INDENTED_CODE_BLOCK_RE = /(?:^|\n)((?:[ ]{4,}[^\n]*\n?)+)/g;
+/** URLs: http(s)://... */
+const URL_RE = /https?:\/\/[^\s)>\]]+/g;
+/** Absolute file paths: /path/to/file or ./path/to/file */
+const UNIX_PATH_RE = /(?:\.\/|\/)[a-zA-Z0-9_\-./]+\.[a-zA-Z0-9]+/g;
+/** Windows file paths: C:\path\to\file */
+const WINDOWS_PATH_RE = /[A-Z]:\\[^\s]+/g;
+/** Double-quoted strings */
+const DOUBLE_QUOTE_RE = /"[^"]*"/g;
+/** Single-quoted strings */
+const SINGLE_QUOTE_RE = /'[^']*'/g;
+/** Backtick-quoted inline code */
+const BACKTICK_RE = /`[^`]+`/g;
+/** Inline JSON objects */
+const INLINE_JSON_RE = /\{[^{}]*"[^"]*"[^{}]*\}/g;
+export class SemanticCompressorService {
+    /**
+     * Compress natural language text in a prompt.
+     *
+     * Strategy:
+     * 1. Extract all protected regions and replace with placeholders
+     * 2. Apply compression rules to remaining text
+     * 3. Restore protected regions from placeholders
+     * 4. Calculate compression ratio
+     */
+    compress(text) {
+        if (text === '') {
+            return { compressed: '', compressionRatio: 1.0 };
+        }
+        const originalLength = text.length;
+        // Step 1: Extract protected regions
+        const protectedRegions = [];
+        let working = text;
+        const protect = (regex) => {
+            working = working.replace(regex, (match) => {
+                const index = protectedRegions.length;
+                protectedRegions.push(match);
+                return `${PLACEHOLDER_PREFIX}${index}${PLACEHOLDER_SUFFIX}`;
+            });
+        };
+        // Order matters: code blocks first (they may contain other patterns)
+        protect(FENCED_CODE_BLOCK_RE);
+        protect(INDENTED_CODE_BLOCK_RE);
+        protect(URL_RE);
+        protect(WINDOWS_PATH_RE);
+        protect(UNIX_PATH_RE);
+        protect(INLINE_JSON_RE);
+        protect(DOUBLE_QUOTE_RE);
+        protect(SINGLE_QUOTE_RE);
+        protect(BACKTICK_RE);
+        // Step 2: Apply compression rules
+        working = this.applyPhraseShortening(working);
+        working = this.removeFillerWords(working);
+        working = this.removeArticles(working);
+        working = this.abbreviateTerms(working);
+        working = this.collapseWhitespace(working);
+        // Step 3: Restore protected regions
+        working = working.replace(new RegExp(`${escapeRegex(PLACEHOLDER_PREFIX)}(\\d+)${escapeRegex(PLACEHOLDER_SUFFIX)}`, 'g'), (_, indexStr) => {
+            const index = parseInt(indexStr, 10);
+            return protectedRegions[index] ?? '';
+        });
+        const compressedLength = working.length;
+        const compressionRatio = originalLength === 0 ? 1.0 : compressedLength / originalLength;
+        return { compressed: working, compressionRatio };
+    }
+    applyPhraseShortening(text) {
+        let result = text;
+        for (const [pattern, replacement] of PHRASE_REPLACEMENTS) {
+            result = result.replace(pattern, replacement);
+        }
+        return result;
+    }
+    removeFillerWords(text) {
+        let result = text;
+        for (const pattern of FILLER_WORDS) {
+            result = result.replace(pattern, '');
+        }
+        return result;
+    }
+    removeArticles(text) {
+        let result = text;
+        for (const pattern of ARTICLES) {
+            result = result.replace(pattern, '');
+        }
+        return result;
+    }
+    abbreviateTerms(text) {
+        let result = text;
+        for (const [pattern, replacement] of TERM_ABBREVIATIONS) {
+            result = result.replace(pattern, replacement);
+        }
+        return result;
+    }
+    collapseWhitespace(text) {
+        let result = text;
+        // Collapse multiple blank lines to a single blank line
+        result = result.replace(/\n{3,}/g, '\n\n');
+        // Collapse multiple spaces within lines to a single space
+        result = result.replace(/ {2,}/g, ' ');
+        // Trim leading/trailing spaces on each line (but keep indentation for protected restored content)
+        result = result
+            .split('\n')
+            .map((line) => {
+            // Only trim if line doesn't start with a placeholder
+            if (line.includes(PLACEHOLDER_PREFIX)) {
+                return line;
+            }
+            return line.replace(/^ +/, '').replace(/ +$/, '');
+        })
+            .join('\n');
+        return result;
+    }
+}
+/**
+ * Escape special regex characters in a string.
+ */
+function escapeRegex(str) {
+    return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}

package/dist/packages/core/src/infrastructure/services/token-optimization/skill-routing.service.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Skill Routing Service
+ *
+ * Phase-aware skill routing that maps workflow phases to relevant skill sets
+ * and generates prompt directives guiding the agent to prioritize them.
+ *
+ * The default routing table follows FR-3 from the spec:
+ * - analyze / requirements: architecture-reviewer, domain modeling skills
+ * - research: architecture-reviewer, technology evaluation skills
+ * - plan: architecture-reviewer, tdd-guide, implementation-guide
+ * - implement / fast-implement: tdd-guide, implementation-guide, framework skills
+ * - merge: git-related skills only
+ * - evidence: testing and validation skills
+ *
+ * The routing table is configurable via constructor parameter (settings override).
+ */
+import type { ISkillRoutingService, SkillRoutingResult } from '../../../application/ports/output/services/skill-routing.interface.js';
+export declare class SkillRoutingService implements ISkillRoutingService {
+    private readonly routingTable;
+    constructor(customRoutes?: Record<string, string[]>);
+    /**
+     * Get relevant skills and a prompt directive for a workflow phase.
+     */
+    getRoutingDirective(phaseName: string): SkillRoutingResult;
+}
+//# sourceMappingURL=skill-routing.service.d.ts.map

package/dist/packages/core/src/infrastructure/services/token-optimization/skill-routing.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"skill-routing.service.d.ts","sourceRoot":"","sources":["../../../../../../../packages/core/src/infrastructure/services/token-optimization/skill-routing.service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EACV,oBAAoB,EACpB,kBAAkB,EACnB,MAAM,gEAAgE,CAAC;AAgBxE,qBAAa,mBAAoB,YAAW,oBAAoB;IAC9D,OAAO,CAAC,QAAQ,CAAC,YAAY,CAA8C;gBAE/D,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC;IAInD;;OAEG;IACH,mBAAmB,CAAC,SAAS,EAAE,MAAM,GAAG,kBAAkB;CAiB3D"}