agentic-qe 3.9.0 → 3.9.2

package/dist/domains/quality-assessment/coherence/types.d.ts

@@ -236,4 +236,43 @@ export interface LambdaTrend {
     /** Is trend concerning */
     isConcerning: boolean;
 }
+/**
+ * Configuration for monotonic gate threshold ratcheting (ADR-062 Action 4).
+ * Thresholds can only increase, never decrease.
+ */
+export interface RatchetConfig {
+    /** Whether ratcheting is enabled */
+    enabled: boolean;
+    /** Number of consecutive gate passes required before ratcheting (default: 5) */
+    consecutivePassesRequired: number;
+    /** Percentage to increase threshold on each ratchet (default: 2) */
+    ratchetIncrementPercent: number;
+    /** Maximum threshold ceiling (default: 95) */
+    maxThreshold: number;
+    /** Enforced by type system: threshold can only go up */
+    monotonic: true;
+    /** Cooldown period in milliseconds between ratchets (default: 7 days) */
+    cooldownMs: number;
+}
+/**
+ * Runtime state for gate ratcheting.
+ * Tracks consecutive passes, current threshold, and ratchet history.
+ */
+export interface RatchetState {
+    /** Current quality gate threshold */
+    currentThreshold: number;
+    /** Number of consecutive gate passes since last failure or ratchet */
+    consecutivePasses: number;
+    /** Timestamp (ms) of the last ratchet event */
+    lastRatchetTime: number;
+    /** History of all ratchet events */
+    history: Array<{
+        threshold: number;
+        ratchetedAt: number;
+    }>;
+}
+/**
+ * Default ratchet configuration
+ */
+export declare const DEFAULT_RATCHET_CONFIG: RatchetConfig;
 //# sourceMappingURL=types.d.ts.map

package/dist/domains/quality-assessment/coherence/types.js

@@ -59,4 +59,15 @@ export const DEFAULT_COHERENCE_GATE_POLICY = {
     enableTrendAnalysis: true,
     minTrendSamples: 3,
 };
+/**
+ * Default ratchet configuration
+ */
+export const DEFAULT_RATCHET_CONFIG = {
+    enabled: false,
+    consecutivePassesRequired: 5,
+    ratchetIncrementPercent: 2,
+    maxThreshold: 95,
+    monotonic: true,
+    cooldownMs: 7 * 24 * 60 * 60 * 1000, // 7 days
+};
 //# sourceMappingURL=types.js.map

package/dist/domains/quality-assessment/coordinator.d.ts

@@ -75,6 +75,7 @@ export declare class QualityAssessmentCoordinator extends BaseDomainCoordinator<
     private claimVerifier?;
     private readonly domain;
     private recentDreamInsights;
+    private ratchetState;
     constructor(eventBus: EventBus, memory: MemoryBackend, agentCoordinator: AgentCoordinator, config?: Partial<CoordinatorConfig>);
     /**
      * Initialize the coordinator
@@ -261,6 +262,19 @@ export declare class QualityAssessmentCoordinator extends BaseDomainCoordinator<
     private handleSecurityAuditCompleted;
     private loadWorkflowState;
     private saveWorkflowState;
+    /**
+     * ADR-062: Load persisted ratchet state from MemoryBackend.
+     * If no saved state exists the in-memory default (threshold 70) is kept.
+     * Persistence failures are logged but never propagated — the coordinator
+     * must remain functional even when the memory backend is degraded.
+     */
+    private loadRatchetState;
+    /**
+     * ADR-062: Persist current ratchet state to MemoryBackend.
+     * Called after checkRatchet() when the threshold actually ratcheted upward.
+     * Persistence failures are logged but never propagated.
+     */
+    private saveRatchetState;
     /**
      * Initialize Actor-Critic RL for quality gate threshold tuning
      */

package/dist/domains/quality-assessment/coordinator.js

@@ -26,6 +26,9 @@ import * as ReportHelpers from './coordinator-reports.js';
 import * as RLIntegration from './coordinator-rl-integration.js';
 import * as ClaimVerifierHelpers from './coordinator-claim-verifier.js';
 import * as GateEvalHelpers from './coordinator-gate-evaluation.js';
+// ADR-062: Gate ratcheting
+import { checkRatchet, } from './coherence/gate-controller.js';
+import { DEFAULT_RATCHET_CONFIG, } from './coherence/types.js';
 // ADR-070: Witness Chain audit trail
 import { getWitnessChain } from '../../audit/witness-chain.js';
 // Three-loop feature flag for instantAdapt protocol
@@ -85,6 +88,13 @@ export class QualityAssessmentCoordinator extends BaseDomainCoordinator {
     domain = 'quality-assessment';
     // Cache of recent dream insights for quality assessment enhancement
     recentDreamInsights = [];
+    // ADR-062: Monotonic gate threshold ratcheting state
+    ratchetState = {
+        currentThreshold: 70,
+        consecutivePasses: 0,
+        lastRatchetTime: 0,
+        history: [],
+    };
     constructor(eventBus, memory, agentCoordinator, config = {}) {
         const fullConfig = { ...DEFAULT_CONFIG, ...config };
         super(eventBus, 'quality-assessment', fullConfig, {
@@ -116,6 +126,9 @@ export class QualityAssessmentCoordinator extends BaseDomainCoordinator {
             this.subscribeToEvents();
             // Load any persisted workflow state
             await this.loadWorkflowState();
+            // ADR-062: Restore persisted ratchet state so the monotonic invariant
+            // survives coordinator restarts.
+            await this.loadRatchetState();
             // Initialize Actor-Critic RL for threshold tuning
             if (this.config.enableRLThresholdTuning) {
                 await this.initializeActorCritic();
@@ -242,6 +255,17 @@ export class QualityAssessmentCoordinator extends BaseDomainCoordinator {
                     m.duplications / 100,
                     finalResult.overallScore / 100,
                 ]);
+                // EWC++ outcome recording: reward scaled by gate score
+                try {
+                    this.qesona.recordOutcome(finalResult.overallScore / 100);
+                    if (this.qesona.shouldConsolidate()) {
+                        try {
+                            this.qesona.backgroundConsolidate();
+                        }
+                        catch { /* best-effort */ }
+                    }
+                }
+                catch { /* must not break main flow */ }
             }
             // Store quality pattern in SONA if enabled
             if (this.config.enableSONAPatternLearning && this.qesona) {
@@ -257,6 +281,26 @@ export class QualityAssessmentCoordinator extends BaseDomainCoordinator {
                 wc.append(finalResult.passed ? 'QUALITY_GATE_PASS' : 'QUALITY_GATE_FAIL', { gateName: request.gateName, passed: finalResult.passed, score: finalResult.overallScore, failedChecks: finalResult.failedChecks }, 'quality-gate');
             }
             catch (_wcErr) { /* non-critical */ }
+            // ADR-062: Monotonic gate threshold ratcheting
+            // After gate decision is final, check if threshold should ratchet upward
+            if (process.env.AQE_GATE_RATCHETING_ENABLED === 'true') {
+                try {
+                    const prevThreshold = this.ratchetState.currentThreshold;
+                    this.ratchetState = checkRatchet(finalResult.passed, DEFAULT_RATCHET_CONFIG, this.ratchetState);
+                    if (this.ratchetState.currentThreshold > prevThreshold) {
+                        logger.info(`Gate threshold ratcheted: ${prevThreshold} -> ${this.ratchetState.currentThreshold}`);
+                        // ADR-062: Persist updated ratchet state so the monotonic invariant
+                        // survives coordinator restarts.
+                        await this.saveRatchetState();
+                    }
+                }
+                catch (ratchetErr) {
+                    // Ratcheting failure must never break gate evaluation
+                    logger.warn('Gate ratcheting failed (non-critical)', {
+                        error: ratchetErr instanceof Error ? ratchetErr.message : String(ratchetErr),
+                    });
+                }
+            }
             // Publish event
             if (this.config.publishEvents) {
                 await this.publishQualityGateEvaluated(finalResult);
@@ -347,6 +391,17 @@ export class QualityAssessmentCoordinator extends BaseDomainCoordinator {
                     result.value.trends.length / 10,
                     result.value.recommendations.length / 10,
                 ]);
+                // EWC++ outcome recording: reward scaled by analysis score
+                try {
+                    this.qesona.recordOutcome(score.overall / 100);
+                    if (this.qesona.shouldConsolidate()) {
+                        try {
+                            this.qesona.backgroundConsolidate();
+                        }
+                        catch { /* best-effort */ }
+                    }
+                }
+                catch { /* must not break main flow */ }
             }
             // Store quality pattern in SONA
             if (this.config.enableSONAPatternLearning && this.qesona) {
@@ -798,6 +853,43 @@ export class QualityAssessmentCoordinator extends BaseDomainCoordinator {
         const workflows = Array.from(this.workflows.values());
         await this.memory.set('quality-assessment:coordinator:workflows', workflows, { namespace: 'quality-assessment', persist: true });
     }
+    /**
+     * ADR-062: Load persisted ratchet state from MemoryBackend.
+     * If no saved state exists the in-memory default (threshold 70) is kept.
+     * Persistence failures are logged but never propagated — the coordinator
+     * must remain functional even when the memory backend is degraded.
+     */
+    async loadRatchetState() {
+        try {
+            const saved = await this.memory.get('quality-assessment:ratchet-state');
+            if (saved) {
+                this.ratchetState = saved;
+                logger.info(`Restored ratchet state (threshold=${saved.currentThreshold}, passes=${saved.consecutivePasses})`);
+            }
+        }
+        catch (loadErr) {
+            // Non-critical: default ratchet state is safe
+            logger.warn('Failed to load ratchet state (using default)', {
+                error: loadErr instanceof Error ? loadErr.message : String(loadErr),
+            });
+        }
+    }
+    /**
+     * ADR-062: Persist current ratchet state to MemoryBackend.
+     * Called after checkRatchet() when the threshold actually ratcheted upward.
+     * Persistence failures are logged but never propagated.
+     */
+    async saveRatchetState() {
+        try {
+            await this.memory.set('quality-assessment:ratchet-state', this.ratchetState, { namespace: 'quality-assessment', persist: true });
+        }
+        catch (saveErr) {
+            // Non-critical: next restart will use the previous persisted value
+            logger.warn('Failed to persist ratchet state', {
+                error: saveErr instanceof Error ? saveErr.message : String(saveErr),
+            });
+        }
+    }
     // ============================================================================
     // Ruvector Integration Methods (ADR-040)
     // ============================================================================

package/dist/domains/test-execution/coordinator.d.ts

@@ -98,6 +98,7 @@ export interface ITestExecutionCoordinator extends TestExecutionAPI {
     isConsensusAvailable(): boolean;
 }
 export declare class TestExecutionCoordinator extends BaseDomainCoordinator<TestExecutionCoordinatorConfig> implements ITestExecutionCoordinator {
+    private readonly memory;
     private readonly executor;
     private readonly flakyDetector;
     private readonly retryHandler;
@@ -186,6 +187,24 @@ export declare class TestExecutionCoordinator extends BaseDomainCoordinator<Test
      * Extract test name from file path
      */
     private extractTestName;
+    /**
+     * ADR-062: Partition test files into normal and holdout sets.
+     *
+     * When AQE_HOLDOUT_TESTING_ENABLED is 'true', holdout test file paths are
+     * looked up from memory (stored by the test-generation domain when a test
+     * is created with `holdout: true`).
+     *
+     * - Normal runs execute only non-holdout tests.
+     * - Holdout runs (AQE_RUN_HOLDOUT_TESTS === 'true' or runHoldout flag)
+     *   execute only holdout tests.
+     *
+     * If the feature flag is disabled, all tests are returned as normal tests.
+     * Failures in holdout lookup are logged and treated as "no holdout tests"
+     * so that normal execution is never blocked.
+     *
+     * @returns Object with testsToRun and holdoutCount.
+     */
+    private partitionHoldoutTests;
     /**
      * Execute E2E test case
      */

package/dist/domains/test-execution/coordinator.js

@@ -37,6 +37,7 @@ const DEFAULT_COORDINATOR_CONFIG = {
 // ============================================================================
 const logger = LoggerFactory.create('test-execution');
 export class TestExecutionCoordinator extends BaseDomainCoordinator {
+    memory;
     executor;
     flakyDetector;
     retryHandler;
@@ -52,6 +53,7 @@ export class TestExecutionCoordinator extends BaseDomainCoordinator {
             verifyFindingTypes: ['flaky-test-detection', 'test-failure-analysis', 'retry-strategy'],
             ...fullConfig.consensusConfig,
         });
+        this.memory = memory;
         // Create services with appropriate configuration
         this.executor = new TestExecutorService({ memory }, {
             simulateForTesting: fullConfig.simulateForTesting,
@@ -116,13 +118,21 @@ export class TestExecutionCoordinator extends BaseDomainCoordinator {
      * Auto-detects framework and uses sensible defaults
      */
     async runTests(request) {
-        const framework = this.detectFramework(request.testFiles);
-        const workers = request.workers ?? Math.min(4, Math.max(1, request.testFiles.length));
+        // ADR-062: Filter holdout tests before execution
+        const { testsToRun } = await this.partitionHoldoutTests(request.testFiles);
+        if (testsToRun.length === 0) {
+            return ok({
+                runId: uuidv4(), status: 'passed', total: 0, passed: 0,
+                failed: 0, skipped: 0, duration: 0, failedTests: [],
+            });
+        }
+        const framework = this.detectFramework(testsToRun);
+        const workers = request.workers ?? Math.min(4, Math.max(1, testsToRun.length));
         const timeout = request.timeout ?? 60000;
         // Use parallel execution by default (unless explicitly disabled)
-        if (request.parallel !== false && request.testFiles.length > 1) {
+        if (request.parallel !== false && testsToRun.length > 1) {
             const result = await this.executeParallel({
-                testFiles: request.testFiles,
+                testFiles: testsToRun,
                 framework,
                 workers,
                 timeout,
@@ -141,7 +151,7 @@ export class TestExecutionCoordinator extends BaseDomainCoordinator {
         }
         // Sequential execution
         const result = await this.execute({
-            testFiles: request.testFiles,
+            testFiles: testsToRun,
             framework,
             timeout,
         });
@@ -181,6 +191,17 @@ export class TestExecutionCoordinator extends BaseDomainCoordinator {
         // ADR-057: Reset recovery attempt counter for each top-level execution
         this.infraRecoveryAttempts = 0;
         try {
+            // ADR-062: Filter holdout tests before execution
+            const { testsToRun } = await this.partitionHoldoutTests(request.testFiles);
+            if (testsToRun.length === 0) {
+                this.activeRuns.delete(runId);
+                return ok({
+                    runId, status: 'passed', total: 0, passed: 0,
+                    failed: 0, skipped: 0, duration: 0, failedTests: [],
+                });
+            }
+            // Replace testFiles with filtered set for the remainder of execution
+            request = { ...request, testFiles: testsToRun };
             // Prioritize tests if enabled
             let orderedTestFiles = request.testFiles;
             let prioritizationResult = null;
@@ -273,6 +294,16 @@ export class TestExecutionCoordinator extends BaseDomainCoordinator {
         // ADR-057: Reset recovery attempt counter for each top-level execution
         this.infraRecoveryAttempts = 0;
         try {
+            // ADR-062: Filter holdout tests before execution
+            const { testsToRun } = await this.partitionHoldoutTests(request.testFiles);
+            if (testsToRun.length === 0) {
+                this.activeRuns.delete(runId);
+                return ok({
+                    runId, status: 'passed', total: 0, passed: 0,
+                    failed: 0, skipped: 0, duration: 0, failedTests: [],
+                });
+            }
+            request = { ...request, testFiles: testsToRun };
             // ADR-047: Check topology health before expensive parallel operations
             if (this.config.enableMinCutAwareness && !this.isTopologyHealthy()) {
                 logger.warn(`Topology degraded, reducing parallel workers`);
@@ -677,6 +708,72 @@ export class TestExecutionCoordinator extends BaseDomainCoordinator {
         return parts[parts.length - 1] || filePath;
     }
     // ============================================================================
+    // ADR-062: Holdout Test Filtering
+    // ============================================================================
+    /**
+     * ADR-062: Partition test files into normal and holdout sets.
+     *
+     * When AQE_HOLDOUT_TESTING_ENABLED is 'true', holdout test file paths are
+     * looked up from memory (stored by the test-generation domain when a test
+     * is created with `holdout: true`).
+     *
+     * - Normal runs execute only non-holdout tests.
+     * - Holdout runs (AQE_RUN_HOLDOUT_TESTS === 'true' or runHoldout flag)
+     *   execute only holdout tests.
+     *
+     * If the feature flag is disabled, all tests are returned as normal tests.
+     * Failures in holdout lookup are logged and treated as "no holdout tests"
+     * so that normal execution is never blocked.
+     *
+     * @returns Object with testsToRun and holdoutCount.
+     */
+    async partitionHoldoutTests(testFiles, runHoldout) {
+        const holdoutEnabled = process.env.AQE_HOLDOUT_TESTING_ENABLED === 'true';
+        if (!holdoutEnabled) {
+            return { testsToRun: testFiles, holdoutCount: 0 };
+        }
+        try {
+            // Retrieve the set of holdout test file paths stored by test-generation
+            const holdoutSet = await this.memory.get('test-generation:holdout-test-files');
+            if (!holdoutSet || holdoutSet.length === 0) {
+                return { testsToRun: testFiles, holdoutCount: 0 };
+            }
+            const holdoutPaths = new Set(holdoutSet);
+            const normalTests = [];
+            const holdoutTests = [];
+            for (const file of testFiles) {
+                if (holdoutPaths.has(file)) {
+                    holdoutTests.push(file);
+                }
+                else {
+                    normalTests.push(file);
+                }
+            }
+            // Determine if this is a holdout-only run
+            const isHoldoutRun = runHoldout === true ||
+                process.env.AQE_RUN_HOLDOUT_TESTS === 'true';
+            if (isHoldoutRun) {
+                logger.info(`Holdout run: executing ${holdoutTests.length} holdout tests, skipping ${normalTests.length} normal tests`);
+                // Store metadata about the holdout run
+                await this.memory.set(`test-execution:holdout-run:${Date.now()}`, { holdoutCount: holdoutTests.length, holdoutFiles: holdoutTests }, { namespace: 'test-execution', ttl: 86400 });
+                return { testsToRun: holdoutTests, holdoutCount: holdoutTests.length };
+            }
+            if (holdoutTests.length > 0) {
+                logger.info(`Normal run: filtered out ${holdoutTests.length} holdout test(s), running ${normalTests.length} normal tests`);
+                // Store metadata for visibility
+                await this.memory.set(`test-execution:holdout-filtered:${Date.now()}`, { holdoutCount: holdoutTests.length, holdoutFiles: holdoutTests }, { namespace: 'test-execution', ttl: 86400 });
+            }
+            return { testsToRun: normalTests, holdoutCount: holdoutTests.length };
+        }
+        catch (partitionErr) {
+            // Non-critical: if holdout lookup fails, run all tests
+            logger.warn('Holdout test partitioning failed (running all tests)', {
+                error: partitionErr instanceof Error ? partitionErr.message : String(partitionErr),
+            });
+            return { testsToRun: testFiles, holdoutCount: 0 };
+        }
+    }
+    // ============================================================================
     // E2E Test Execution Methods
     // ============================================================================
     /**

package/dist/domains/test-generation/coordinator.js

@@ -320,6 +320,17 @@ export class TestGenerationCoordinator extends BaseDomainCoordinator {
                         (request.coverageTarget ?? 80) / 100,
                         tests.tests.filter(t => t.type === 'unit').length / 20,
                     ]);
+                    // EWC++ outcome recording: close the feedback loop
+                    try {
+                        this.qesona.recordOutcome(1.0);
+                        if (this.qesona.shouldConsolidate()) {
+                            try {
+                                this.qesona.backgroundConsolidate();
+                            }
+                            catch { /* best-effort */ }
+                        }
+                    }
+                    catch { /* must not break main flow */ }
                 }
                 // Learn from successful generation using QESONA
                 if (this.config.enableQESONA && this.qesona) {

package/dist/domains/test-generation/interfaces.d.ts

@@ -48,6 +48,8 @@ export interface IGeneratedTest {
     llmEnhanced?: boolean;
     /** Test quality gate validation result (loki-mode Gates 8 & 9) */
     qualityGateResult?: TestQualityGateResult;
+    /** ADR-062: Whether this test is a holdout test (not shown to developer, runs in CI only) */
+    holdout?: boolean;
 }
 export interface ITDDRequest {
     feature: string;

package/dist/domains/test-generation/services/test-generator.d.ts

@@ -15,6 +15,15 @@ import { type ITDDGeneratorService } from './tdd-generator';
 import { type IPropertyTestGeneratorService } from './property-test-generator';
 import { type ITestDataGeneratorService } from './test-data-generator';
 import type { HybridRouter } from '../../../shared/llm';
+/**
+ * Deterministically decide whether a test ID should be a holdout test.
+ * Uses FNV-1a hash of the testId to select ~10% of tests as holdout.
+ *
+ * @param testId - Unique identifier for the test
+ * @param seed - Optional seed for the hash (default: 0)
+ * @returns true if this test should be flagged as holdout
+ */
+export declare function isHoldoutTest(testId: string, seed?: number): boolean;
 /**
  * Interface for the test generation service
  */

package/dist/domains/test-generation/services/test-generator.js

@@ -27,6 +27,35 @@ import { resolveRequest } from '../../../shared/language-detector.js';
 import { compilationValidator } from './compilation-validator.js';
 import { resolveTestFilePath } from './test-file-resolver.js';
 import { getPromptConfig } from '../prompts/language-prompts.js';
+// ============================================================================
+// ADR-062 Tier 2: Holdout Test Selection
+// ============================================================================
+/**
+ * FNV-1a hash of a string, returning a 32-bit unsigned integer.
+ * Deterministic: same input always produces the same output.
+ */
+function fnv1aHashU32(input, seed = 0) {
+    let hash = (0x811c9dc5 ^ seed) >>> 0; // FNV offset basis, XOR with seed
+    for (let i = 0; i < input.length; i++) {
+        hash ^= input.charCodeAt(i);
+        hash = Math.imul(hash, 0x01000193); // FNV prime
+        hash = hash >>> 0; // Force unsigned 32-bit
+    }
+    return hash;
+}
+/**
+ * Deterministically decide whether a test ID should be a holdout test.
+ * Uses FNV-1a hash of the testId to select ~10% of tests as holdout.
+ *
+ * @param testId - Unique identifier for the test
+ * @param seed - Optional seed for the hash (default: 0)
+ * @returns true if this test should be flagged as holdout
+ */
+export function isHoldoutTest(testId, seed = 0) {
+    const hash = fnv1aHashU32(testId, seed);
+    // Select bottom 10% of the hash space (0 to 0xFFFFFFFF)
+    return (hash % 100) < 10;
+}
 const DEFAULT_CONFIG = {
     defaultFramework: 'vitest',
     maxTestsPerFile: 50,
@@ -280,6 +309,14 @@ Return a JSON array of test suggestions, each with: { "name": "test name", "desc
                     patternsUsed.push(...fileTests.value.patternsUsed);
                 }
             }
+            // ADR-062 Tier 2: Mark holdout tests when feature flag is enabled
+            if (process.env.AQE_HOLDOUT_TESTING_ENABLED === 'true') {
+                for (const test of tests) {
+                    if (isHoldoutTest(test.id)) {
+                        test.holdout = true;
+                    }
+                }
+            }
             const coverageEstimate = this.estimateCoverage(tests, coverageTarget);
             await this.storeGenerationMetadata(tests, patternsUsed);
             return ok({

package/dist/init/agents-installer.d.ts

@@ -44,9 +44,11 @@ export declare class AgentsInstaller {
     private sourceAgentsDir;
     constructor(options: AgentsInstallerOptions);
     /**
-     * Find the source agents directory
-     * Looks in multiple locations to support different installation scenarios
-     * PRIORITY: assets directory (has helpers) > root .claude (no helpers)
+     * Find the source agents directory.
+     *
+     * Uses findPackageRoot() to reliably locate the package root regardless
+     * of esbuild bundle depth (dist/init/, dist/cli/, dist/cli/chunks/, etc.).
+     * Prioritises assets/agents/v3/ (canonical npm source with helpers/) over .claude/agents/v3/.
      */
     private findSourceAgentsDir;
     /**

package/dist/init/agents-installer.js

@@ -6,11 +6,11 @@
  * Agents are copied from .claude/agents/v3/ to the project's .claude/agents/v3/.
  */
 import { existsSync, mkdirSync, readdirSync, statSync, readFileSync, writeFileSync, copyFileSync } from 'fs';
-import { join, dirname } from 'path';
-import { fileURLToPath } from 'url';
+import { join } from 'path';
 import { toErrorMessage } from '../shared/error-utils.js';
 import { loadOverlays, applyOverlayToContent } from '../agents/overlay-loader.js';
 import { validateFleetMcpDeps } from '../validation/steps/agent-mcp-validator.js';
+import { findPackageRoot } from './find-package-root.js';
 // ============================================================================
 // Helpers
 // ============================================================================
@@ -147,47 +147,22 @@ export class AgentsInstaller {
         this.sourceAgentsDir = this.findSourceAgentsDir();
     }
     /**
-     * Find the source agents directory
-     * Looks in multiple locations to support different installation scenarios
-     * PRIORITY: assets directory (has helpers) > root .claude (no helpers)
+     * Find the source agents directory.
+     *
+     * Uses findPackageRoot() to reliably locate the package root regardless
+     * of esbuild bundle depth (dist/init/, dist/cli/, dist/cli/chunks/, etc.).
+     * Prioritises assets/agents/v3/ (canonical npm source with helpers/) over .claude/agents/v3/.
      */
     findSourceAgentsDir() {
-        // Try relative to this module (development)
-        const moduleDir = dirname(fileURLToPath(import.meta.url));
-        // Possible locations for agents - PRIORITY ORDER MATTERS
-        // Assets directory is canonical source (contains helpers/)
-        const possiblePaths = [
-            // NPM package: assets directory at package root (dist/init -> dist -> package root)
-            // This is the canonical source with helpers/ directory
-            join(moduleDir, '../../assets/agents/v3'),
-            // Development: src/init/ or dist/init/ -> project root .claude/agents/v3
-            join(moduleDir, '../../.claude/agents/v3'),
-            // Local install: in node_modules
-            join(this.projectRoot, 'node_modules/agentic-qe/assets/agents/v3'),
-            join(this.projectRoot, 'node_modules/agentic-qe/assets/agents/v3'),
-        ];
-        // For global npm installs, add common global node_modules paths
-        // Note: We use platform-based heuristics instead of npm prefix lookup
-        // to avoid dynamic require issues in ESM bundles
-        const homeDir = process.env.HOME || process.env.USERPROFILE || '';
-        const isWindows = process.platform === 'win32';
-        if (isWindows) {
-            // Windows: npm global is typically in AppData
-            const appData = process.env.APPDATA || join(homeDir, 'AppData', 'Roaming');
-            possiblePaths.push(join(appData, 'npm/node_modules/agentic-qe/assets/agents/v3'), join(appData, 'npm/node_modules/agentic-qe/.claude/agents/v3'));
-        }
-        else {
-            // Unix/Linux/macOS: common global prefixes
-            const globalPrefixes = [
-                '/usr/local',
-                '/usr',
-                join(homeDir, '.npm-global'),
-                join(homeDir, '.nvm/versions/node', process.version),
-            ];
-            for (const prefix of globalPrefixes) {
-                possiblePaths.push(join(prefix, 'lib/node_modules/agentic-qe/assets/agents/v3'), join(prefix, 'lib/node_modules/agentic-qe/.claude/agents/v3'), join(prefix, 'node_modules/agentic-qe/assets/agents/v3'), join(prefix, 'node_modules/agentic-qe/.claude/agents/v3'));
-            }
+        const pkgRoot = findPackageRoot(import.meta.url);
+        const possiblePaths = [];
+        if (pkgRoot) {
+            // Canonical npm source — assets/ contains helpers/ directory
+            possiblePaths.push(join(pkgRoot, 'assets/agents/v3'));
+            possiblePaths.push(join(pkgRoot, '.claude/agents/v3'));
         }
+        // Local install: in node_modules
+        possiblePaths.push(join(this.projectRoot, 'node_modules/agentic-qe/assets/agents/v3'));
         for (const agentsPath of possiblePaths) {
             if (existsSync(agentsPath)) {
                 return agentsPath;
@@ -209,10 +184,9 @@ export class AgentsInstaller {
         const exampleDest = join(overridesDir, '_example.yaml');
         if (!existsSync(exampleDest)) {
             try {
-                const moduleDir = dirname(fileURLToPath(import.meta.url));
+                const pkgRoot = findPackageRoot(import.meta.url);
                 const templateSources = [
-                    join(moduleDir, '..', '..', 'assets', 'templates', 'agent-override-example.yaml'),
-                    join(moduleDir, '..', 'assets', 'templates', 'agent-override-example.yaml'),
+                    ...(pkgRoot ? [join(pkgRoot, 'assets', 'templates', 'agent-override-example.yaml')] : []),
                     join(this.projectRoot, 'node_modules', 'agentic-qe', 'assets', 'templates', 'agent-override-example.yaml'),
                 ];
                 for (const src of templateSources) {

package/dist/init/find-package-root.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Shared utility: find the agentic-qe package root directory.
+ *
+ * When esbuild bundles the CLI with code-splitting, `import.meta.url`
+ * resolves to `dist/cli/chunks/chunk-XXX.js` (3+ levels deep) instead
+ * of the expected `dist/init/skills-installer.js` (2 levels deep).
+ * Fixed `../../` traversals land at `dist/` instead of the package root,
+ * so skills/agents/helpers can't be found.
+ *
+ * This module walks up from the caller's directory until it finds a
+ * `package.json` with `name === "agentic-qe"`, which works regardless
+ * of how deep the bundle puts the calling file.
+ */
+/**
+ * Find the agentic-qe package root by walking up from `import.meta.url`.
+ *
+ * @param callerMetaUrl – pass `import.meta.url` from the calling module
+ * @param maxDepth      – how many parent directories to check (default 10)
+ * @returns absolute path to the package root, or null if not found
+ */
+export declare function findPackageRoot(callerMetaUrl: string, maxDepth?: number): string | null;
+//# sourceMappingURL=find-package-root.d.ts.map