@ai-sdlc/orchestrator 0.10.0 → 0.14.0

package/dist/journey-sa2-router.js

@@ -0,0 +1,308 @@
+/**
+ * RFC-0018 Phase 2 — In-Soul Journey Pattern admission scorer composition.
+ *
+ * Implements the journey-scope routing algorithm described in RFC-0018 §5.4
+ * and §10.1 (OQ-4 resolution):
+ *
+ *   resolveTargetedJourneys(w) = set of (soulId, [variantId,] journeyId) triples
+ *     declared on the work item via `targetedJourneys[]` (URI shapes
+ *     `<soul-id>/<journey-id>` or `<soul-id>/<variant-id>/<journey-id>`).
+ *
+ *   If no `targetedJourneys` declared:
+ *     Scoring proceeds at soul/variant scope (backward-compatible — unchanged
+ *     from RFC-0009 + RFC-0017 baseline).
+ *
+ *   Else if |targeted| == 1 (single-journey):
+ *     Sα₂(w) = scoreSα₂(journey.designImperatives UNION variant's UNION soul's;
+ *              most-specific wins: journey > variant > soul)
+ *     Cκ(w)  = boosted when journey.successMetrics.completion-rate < alertBelow
+ *     Eρ₅(w) = elevated when journey.accessibility.wcagLevel > soul/variant default
+ *
+ *   Else (multi-journey):
+ *     Per-journey scores aggregated via `crossJourneyAggregation` config
+ *     (default `min` per RFC-0018 §5.4 + RFC-0017 OQ-4 cross-variant pattern).
+ *
+ * ### Completion-criteria closed enum (OQ-4 resolution)
+ *
+ * v1 allows only: `terminal-success-state` | `all-states-reached`
+ * `custom-predicate` is rejected at schema validation time.
+ * Future activation via `Decision: journey-custom-predicate-activation-request`
+ * (Stage A counter, auto-promote at ≥2 distinct adopter requests).
+ * Future language: CEL (Google Common Expression Language) per OQ-4 resolution.
+ *
+ * ### Backward compatibility
+ *
+ * Work items without `targetedJourneys` score against soul / variant (existing
+ * RFC-0017 behavior preserved). Soul DIDs without `journeys[]` behave identically.
+ *
+ * @see spec/rfcs/RFC-0018-in-soul-journey-pattern.md §5.4 + §10 + §10.1
+ * @see orchestrator/src/variant-admission.ts — sibling RFC-0017 Phase 2 router
+ * @see orchestrator/src/compliance-clearance.ts — Eρ₅ base scorer
+ */
+/**
+ * The set of valid v1 completion-criteria kind values.
+ * Used by `validateCompletionCriteriaKind` for closed-enum rejection.
+ */
+export const COMPLETION_CRITERIA_V1_KINDS = new Set([
+    'terminal-success-state',
+    'all-states-reached',
+]);
+/**
+ * Decision kind for the `custom-predicate` activation request counter.
+ * Stage A counter per RFC-0035 G0 non-blocking contract.
+ * Auto-promotes at ≥2 distinct adopter requests (RFC-0018 OQ-4 resolution).
+ */
+export const JOURNEY_CUSTOM_PREDICATE_DECISION_KIND = 'journey-custom-predicate-activation-request';
+/**
+ * Validate a completion-criteria `kind` value against the v1 closed enum.
+ *
+ * Returns `{ valid: true }` for `terminal-success-state` and `all-states-reached`.
+ * Returns `{ valid: false, rejectedKind, decisionKind }` for `custom-predicate`
+ * (or any other unrecognized value). The caller is responsible for emitting the
+ * Decision event to the RFC-0035 catalog.
+ */
+export function validateCompletionCriteriaKind(kind) {
+    if (COMPLETION_CRITERIA_V1_KINDS.has(kind)) {
+        return { valid: true };
+    }
+    const result = {
+        valid: false,
+        rejectedKind: kind,
+    };
+    // Wire the Decision counter for custom-predicate specifically (OQ-4 auto-promote mechanism)
+    if (kind === 'custom-predicate') {
+        result.decisionKind = JOURNEY_CUSTOM_PREDICATE_DECISION_KIND;
+    }
+    return result;
+}
+/**
+ * Increment the Stage A counter for a `journey-custom-predicate-activation-request`.
+ *
+ * @param counter    - The counter to increment (mutated in-place).
+ * @param adopterId  - Adopter ID submitting the request (for deduplication).
+ *                     Use `'__unknown__'` when adopter identity is unavailable.
+ */
+export function incrementDecisionCounter(counter, adopterId) {
+    counter.totalRequests++;
+    counter.distinctAdopterIds.add(adopterId);
+    counter.shouldAutoPromote = counter.distinctAdopterIds.size >= 2;
+}
+/**
+ * Create a fresh Stage A counter for `journey-custom-predicate-activation-request`.
+ */
+export function createCustomPredicateDecisionCounter() {
+    return {
+        decisionKind: JOURNEY_CUSTOM_PREDICATE_DECISION_KIND,
+        distinctAdopterIds: new Set(),
+        totalRequests: 0,
+        shouldAutoPromote: false,
+    };
+}
+/**
+ * Ordinal index for WCAG levels — higher = stricter.
+ * `A` < `AA` < `AAA`.
+ */
+const WCAG_LEVEL_ORDER = {
+    A: 0,
+    AA: 1,
+    AAA: 2,
+};
+/**
+ * Returns true when `journeyLevel` is strictly ABOVE `soulDefault`.
+ * Journeys MAY raise the WCAG level above the parent; they MAY NOT lower it.
+ */
+export function isWcagElevated(journeyLevel, soulDefault) {
+    return WCAG_LEVEL_ORDER[journeyLevel] > WCAG_LEVEL_ORDER[soulDefault];
+}
+// ── URI parsing ──────────────────────────────────────────────────────────
+const SLUG_RE = /^[a-z][a-z0-9-]*$/;
+/**
+ * Parse a targeted-journey reference.
+ *
+ * Accepts two URI forms per RFC-0018 §6.1:
+ *
+ *   1. `<soul-id>/<journey-id>` — soul-scoped journey
+ *   2. `<soul-id>/<variant-id>/<journey-id>` — variant-scoped journey
+ *
+ * All slug segments must match `^[a-z][a-z0-9-]*$`.
+ * Returns `undefined` for malformed input (silent skip; schema-side validator
+ * is Phase 1's concern per RFC-0018 §6.1 pattern).
+ */
+export function parseTargetedJourneyRef(raw) {
+    const parts = raw.split('/');
+    if (parts.length === 2) {
+        const [soulId, journeyId] = parts;
+        if (SLUG_RE.test(soulId) && SLUG_RE.test(journeyId)) {
+            return { soulId, journeyId, raw };
+        }
+    }
+    else if (parts.length === 3) {
+        const [soulId, variantId, journeyId] = parts;
+        if (SLUG_RE.test(soulId) && SLUG_RE.test(variantId) && SLUG_RE.test(journeyId)) {
+            return { soulId, variantId, journeyId, raw };
+        }
+    }
+    return undefined;
+}
+// ── resolveTargetedJourneys ──────────────────────────────────────────────
+/**
+ * Resolve the set of targeted (soulId, [variantId,] journeyId) triples for a work item.
+ *
+ * Algorithm:
+ * 1. Find the work item by case-insensitive ID match in `workItemTargeting`.
+ * 2. Parse each entry of `targetedJourneys[]` via `parseTargetedJourneyRef`.
+ * 3. Filter parsed refs against `journeysBySoul` — a (soulId, journeyId) pair
+ *    only survives if the soul exists AND the journeyId is declared on it.
+ * 4. Return the validated intersection (empty = backward-compat soul/variant scope).
+ */
+export function resolveTargetedJourneys(workItemId, journeyCtx) {
+    if (!journeyCtx || !journeyCtx.workItemTargeting || journeyCtx.workItemTargeting.length === 0) {
+        return [];
+    }
+    const normalizedId = workItemId.toLowerCase();
+    const entry = journeyCtx.workItemTargeting.find((e) => e.id.toLowerCase() === normalizedId);
+    if (!entry || !entry.targetedJourneys || entry.targetedJourneys.length === 0) {
+        return [];
+    }
+    const out = [];
+    for (const raw of entry.targetedJourneys) {
+        const parsed = parseTargetedJourneyRef(raw);
+        if (!parsed)
+            continue;
+        const journeys = journeyCtx.journeysBySoul[parsed.soulId];
+        if (!journeys)
+            continue;
+        if (!journeys.some((j) => j.id === parsed.journeyId))
+            continue;
+        out.push(parsed);
+    }
+    return out;
+}
+// ── Cross-journey aggregation ────────────────────────────────────────────
+/**
+ * Apply a per-Soul `crossJourneyAggregation` rule over per-journey scores.
+ * Mirrors `applyCrossVariantRule` in `variant-admission.ts` but for journey scope.
+ *
+ * @param values   - Per-journey score samples (one per targeted journey).
+ * @param rule     - The aggregation rule (defaults to `min` per RFC-0018 §5.4 + OQ-4).
+ * @param fallback - Returned when `values` is empty.
+ */
+export function applyCrossJourneyRule(values, rule, fallback = 0.5) {
+    if (values.length === 0)
+        return fallback;
+    switch (rule ?? 'min') {
+        case 'min':
+            return Math.min(...values);
+        case 'max':
+            return Math.max(...values);
+        case 'mean':
+            return values.reduce((sum, v) => sum + v, 0) / values.length;
+    }
+}
+/**
+ * Compute the journey-scope-refined Sα₂ + Cκ + Eρ₅ for a work item.
+ *
+ * This runs AFTER variant-scope resolution: the caller has already routed the
+ * work item to its target Soul(s)/Variant(s) and obtained the soul/variant
+ * Sα₂ (the `fallbackSa2` argument) and Cκ (the `fallbackCk` argument).
+ * Journey routing refines those values when the work item declares
+ * `targetedJourneys` of one of the affected Souls (RFC-0018 §5.4).
+ *
+ * **Sα₂ Vibe Coherence** — journey's `designImperatives` UNION variant's UNION
+ * soul's; conflict resolution: most-specific wins (journey > variant > soul).
+ * The pre-computed `JourneyScores.sa2` in the context encodes this resolution.
+ *
+ * **Cκ Capability Coverage** — boosted when `completion-rate < alertBelow`.
+ * The pre-computed `JourneyScores.ck` encodes the boost; callers supply live
+ * metric snapshots to the loader that builds `journeyScores`.
+ *
+ * **Eρ₅ Compliance Clearance** — elevated when journey WCAG > soul-default.
+ * The pre-computed `JourneyScores.er5Elevated` flag captures this; the caller
+ * applies Eρ₅ gating at the journey's elevated level when `er5Elevated = true`.
+ *
+ * **Cross-journey aggregation** (work touches multiple journeys) — same `min`
+ * as RFC-0018 §5.4 / RFC-0009 §7.2 / RFC-0017 OQ-4 by default. Per-Soul
+ * override via `journeyConfig.crossJourneyAggregation`.
+ *
+ * @param workItemId   - The canonical work item ID.
+ * @param fallbackSa2  - Soul/variant Sα₂ to use when no journey routing applies.
+ * @param fallbackCk   - Soul/variant Cκ to use when no journey routing applies.
+ * @param fallbackEr5Elevated - Soul/variant Eρ₅ elevation flag (usually false).
+ * @param journeyCtx   - Journey-scope context; undefined → backward-compat passthrough.
+ */
+export function computeJourneyScopedScores(workItemId, fallbackSa2, fallbackCk, fallbackEr5Elevated, journeyCtx) {
+    const targetedJourneys = resolveTargetedJourneys(workItemId, journeyCtx);
+    // ── Backward-compat: no targeted journeys → soul/variant scope passthrough ──
+    if (targetedJourneys.length === 0 || !journeyCtx) {
+        return {
+            sa2: fallbackSa2,
+            ck: fallbackCk,
+            er5Elevated: fallbackEr5Elevated,
+            routingPath: 'no-journey-routing',
+            targetedJourneys: [],
+        };
+    }
+    // ── Single-journey fast path ──
+    if (targetedJourneys.length === 1) {
+        const ref = targetedJourneys[0];
+        const scores = journeyCtx.journeyScores[ref.soulId]?.[ref.journeyId];
+        return {
+            sa2: scores?.sa2 ?? fallbackSa2,
+            ck: scores?.ck ?? fallbackCk,
+            er5Elevated: scores?.er5Elevated ?? fallbackEr5Elevated,
+            routingPath: 'single-journey',
+            targetedJourneys,
+        };
+    }
+    // ── Multi-journey: aggregate per-Soul, then aggregate cross-Soul ──
+    // Per-Soul aggregation uses the Soul's `crossJourneyAggregation` config
+    // (default `min`). When journeys span multiple souls (rare), the cross-Soul
+    // layer also uses `min` as the safest default (RFC-0009 §7.2).
+    const bySoul = new Map();
+    for (const ref of targetedJourneys) {
+        const bucket = bySoul.get(ref.soulId);
+        if (bucket)
+            bucket.push(ref);
+        else
+            bySoul.set(ref.soulId, [ref]);
+    }
+    const perSoulSa2 = [];
+    const perSoulCk = [];
+    const perSoulEr5Elevated = [];
+    let firstAggregationRule;
+    for (const [soulId, refs] of bySoul) {
+        const cfg = journeyCtx.configBySoul?.[soulId];
+        const rule = cfg?.crossJourneyAggregation ?? 'min';
+        if (firstAggregationRule === undefined)
+            firstAggregationRule = rule;
+        const sa2Samples = [];
+        const ckSamples = [];
+        const er5Samples = [];
+        for (const ref of refs) {
+            const scores = journeyCtx.journeyScores[soulId]?.[ref.journeyId];
+            sa2Samples.push(scores?.sa2 ?? fallbackSa2);
+            ckSamples.push(scores?.ck ?? fallbackCk);
+            er5Samples.push(scores?.er5Elevated ?? fallbackEr5Elevated);
+        }
+        perSoulSa2.push(applyCrossJourneyRule(sa2Samples, rule, fallbackSa2));
+        perSoulCk.push(applyCrossJourneyRule(ckSamples, rule, fallbackCk));
+        // Eρ₅ elevation: `true` wins if ANY journey requires elevation
+        // (conservative — if at least one journey has elevated WCAG, the
+        // work item is evaluated at that stricter level).
+        perSoulEr5Elevated.push(er5Samples.some(Boolean));
+    }
+    // Cross-Soul layering: `min` between Souls for numeric scores (RFC-0009 §7.2).
+    // Eρ₅ elevation: `true` if any Soul has elevated WCAG (conservative/safe).
+    const sa2 = perSoulSa2.length === 1 ? perSoulSa2[0] : Math.min(...perSoulSa2);
+    const ck = perSoulCk.length === 1 ? perSoulCk[0] : Math.min(...perSoulCk);
+    const er5Elevated = perSoulEr5Elevated.some(Boolean);
+    return {
+        sa2,
+        ck,
+        er5Elevated,
+        routingPath: 'multi-journey',
+        targetedJourneys,
+        aggregationRule: firstAggregationRule ?? 'min',
+    };
+}
+//# sourceMappingURL=journey-sa2-router.js.map

package/dist/otel-exporter.js

@@ -87,13 +87,10 @@ export function createOTelBridge(metricStore, options) {
                 [ATTRIBUTE_KEYS.RUN_ID]: runId,
                 [ATTRIBUTE_KEYS.PIPELINE]: pipelineType,
             };
-            // Use withSpan to create a span (fire-and-forget style)
-            let endFn;
             // Since withSpan is async, we track spans manually
             const handle = {
                 end(_status) {
                     activeSpans.delete(runId);
-                    endFn?.();
                 },
                 setAttribute(key, value) {
                     attributes[key] = value;

package/dist/runners/claude-code.js

@@ -47,7 +47,7 @@ export function buildPrompt(ctx) {
         const ciVerify = buildVerificationSteps(step, lintCmd, fmtCmd, typecheckCmd);
         lines.push(...ciVerify.lines);
         step = ciVerify.nextStep;
-        lines.push(`${++step}. Write or update tests if needed to cover your fix.`, `${++step}. NEVER modify files matching the blocked paths below — violations will be automatically detected and the change will be rejected.`, `${++step}. Keep your changes to at most ${ctx.constraints.maxFilesPerChange} files.`);
+        lines.push(`${++step}. Write or update tests if needed to cover your fix.`, `${++step}. NEVER modify files matching the blocked paths below — violations will be automatically detected and the change will be rejected.`, `${step + 1}. Keep your changes to at most ${ctx.constraints.maxFilesPerChange} files.`);
     }
     else if (ctx.reviewFindings) {
         let step = 0;
@@ -55,7 +55,7 @@ export function buildPrompt(ctx) {
         const reviewVerify = buildVerificationSteps(step, lintCmd, fmtCmd, typecheckCmd);
         lines.push(...reviewVerify.lines);
         step = reviewVerify.nextStep;
-        lines.push(`${++step}. NEVER modify files matching the blocked paths below — violations will be automatically detected and the change will be rejected.`, `${++step}. Keep your changes to at most ${ctx.constraints.maxFilesPerChange} files.`);
+        lines.push(`${++step}. NEVER modify files matching the blocked paths below — violations will be automatically detected and the change will be rejected.`, `${step + 1}. Keep your changes to at most ${ctx.constraints.maxFilesPerChange} files.`);
     }
     else {
         let step = 0;
@@ -63,7 +63,7 @@ export function buildPrompt(ctx) {
         const defaultVerify = buildVerificationSteps(step, lintCmd, fmtCmd, typecheckCmd);
         lines.push(...defaultVerify.lines);
         step = defaultVerify.nextStep;
-        lines.push(`${++step}. NEVER modify files matching the blocked paths below — violations will be automatically detected and the change will be rejected.`, `${++step}. Keep your changes to at most ${ctx.constraints.maxFilesPerChange} files.`);
+        lines.push(`${++step}. NEVER modify files matching the blocked paths below — violations will be automatically detected and the change will be rejected.`, `${step + 1}. Keep your changes to at most ${ctx.constraints.maxFilesPerChange} files.`);
     }
     lines.push('', '## Constraints (enforced — violations will be automatically rejected)', `- Maximum files to change: ${ctx.constraints.maxFilesPerChange}`, `- Tests required: ${ctx.constraints.requireTests}`, `- Blocked paths (NEVER modify — changes will be rejected): ${ctx.constraints.blockedPaths.join(', ') || 'none'}`);
     // Append relevant episodic memory if available

package/dist/runners/review-agent.js

@@ -291,8 +291,12 @@ export class ReviewAgentRunner {
         }
     }
     parseVerdict(text) {
-        // Strip markdown fences if the model wraps the JSON
-        const cleaned = text.replace(/^```(?:json)?\s*/m, '').replace(/\s*```$/m, '');
+        // Strip markdown fences if the model wraps the JSON. Horizontal-whitespace
+        // classes ([ \t\r]) instead of \s so the trailing-whitespace group can't
+        // overlap the \n the anchors already consume — avoids polynomial
+        // backtracking on adversarial model output (CodeQL js/polynomial-redos).
+        // JSON.parse tolerates the leading/trailing newline left behind.
+        const cleaned = text.replace(/^```(?:json)?[ \t\r]*/m, '').replace(/[ \t\r]*```$/m, '');
         try {
             const parsed = JSON.parse(cleaned);
             const rawFindings = Array.isArray(parsed.findings)

package/dist/runners/runner-registry.d.ts

@@ -38,6 +38,17 @@ export declare class RunnerRegistry {
      * Check if a runner is registered and available.
      */
     has(name: string): boolean;
+    /**
+     * Load and register a runner from an external plugin module.
+     *
+     * The module must export a default export or a named `runner` export that
+     * satisfies the `AgentRunner` interface (i.e. has a `run(ctx)` method).
+     *
+     * @param pluginPath - Absolute or resolvable path to the plugin module (e.g. `/path/to/runner.mjs`).
+     * @param name - Registry name for the loaded runner (defaults to the basename of the path).
+     * @throws Error when the module cannot be imported or does not export a valid AgentRunner.
+     */
+    loadFromPlugin(pluginPath: string, name?: string): Promise<string>;
     /**
      * Auto-discover runners from environment variables and register them.
      */
@@ -47,4 +58,29 @@ export declare class RunnerRegistry {
  * Create a runner registry with auto-discovery.
  */
 export declare function createRunnerRegistry(env?: Record<string, string | undefined>): RunnerRegistry;
+/**
+ * Resolve the agent runner to use, applying the full precedence chain:
+ *
+ *   1. `injectedRunner` — programmatic override (options.runner from caller / tests)
+ *   2. `runnerName` — explicit `--runner <name>` flag (must already be registered after discoverFromEnv)
+ *   3. `AI_SDLC_RUNNER_PLUGIN` env — path to a dynamic plugin module (loaded + registered)
+ *   4. ClaudeCodeRunner (hard-coded default)
+ *
+ * IMPORTANT — env-discovered runners do NOT auto-win (AISDLC-529 code review). They are
+ * registered by `discoverFromEnv()` so they are *selectable by name* via `--runner <name>`,
+ * but the mere PRESENCE of an ambient env var (ANTHROPIC_API_KEY, OPENAI_API_KEY, GH_TOKEN,
+ * etc. — commonly set for unrelated tools) must NOT silently switch the runner. Before this
+ * seam existed the orchestrator always used ClaudeCodeRunner; preserving that as the default
+ * (absent an explicit selector) avoids a breaking, surprising change for existing adopters.
+ *
+ * This function is async because step 3 may dynamically import a module.
+ *
+ * @throws Error when `runnerName` is provided but not registered in the registry.
+ * @throws Error when `AI_SDLC_RUNNER_PLUGIN` points to an invalid module.
+ */
+export declare function resolveRunner(registry: RunnerRegistry, opts?: {
+    injectedRunner?: AgentRunner;
+    runnerName?: string;
+    env?: Record<string, string | undefined>;
+}): Promise<AgentRunner>;
 //# sourceMappingURL=runner-registry.d.ts.map

package/dist/runners/runner-registry.js

@@ -58,6 +58,45 @@ export class RunnerRegistry {
         const entry = this.runners.get(name);
         return entry?.available ?? false;
     }
+    /**
+     * Load and register a runner from an external plugin module.
+     *
+     * The module must export a default export or a named `runner` export that
+     * satisfies the `AgentRunner` interface (i.e. has a `run(ctx)` method).
+     *
+     * @param pluginPath - Absolute or resolvable path to the plugin module (e.g. `/path/to/runner.mjs`).
+     * @param name - Registry name for the loaded runner (defaults to the basename of the path).
+     * @throws Error when the module cannot be imported or does not export a valid AgentRunner.
+     */
+    async loadFromPlugin(pluginPath, name) {
+        let mod;
+        try {
+            mod = await import(pluginPath);
+        }
+        catch (err) {
+            throw new Error(`AI_SDLC_RUNNER_PLUGIN: failed to import plugin module "${pluginPath}": ${err instanceof Error ? err.message : String(err)}.\n` +
+                `Ensure the path is correct and the module is a valid ESM/CJS module.`, { cause: err });
+        }
+        // Accept default export or named 'runner' export
+        const exported = mod.default ?? mod.runner;
+        if (!exported || typeof exported.run !== 'function') {
+            throw new Error(`AI_SDLC_RUNNER_PLUGIN: plugin module "${pluginPath}" does not export a valid AgentRunner.\n` +
+                `Expected a default export (or named 'runner' export) with a \`run(ctx: AgentContext): Promise<AgentResult>\` method.\n` +
+                `Got: ${JSON.stringify(Object.keys(mod))}`);
+        }
+        const runnerName = name ??
+            pluginPath
+                .split('/')
+                .pop()
+                .replace(/\.(m|c)?[jt]s$/, '');
+        this.runners.set(runnerName, {
+            name: runnerName,
+            runner: exported,
+            available: true,
+            source: 'manual',
+        });
+        return runnerName;
+    }
     /**
      * Auto-discover runners from environment variables and register them.
      */
@@ -163,4 +202,55 @@ export function createRunnerRegistry(env) {
     registry.discoverFromEnv(env);
     return registry;
 }
+/**
+ * Resolve the agent runner to use, applying the full precedence chain:
+ *
+ *   1. `injectedRunner` — programmatic override (options.runner from caller / tests)
+ *   2. `runnerName` — explicit `--runner <name>` flag (must already be registered after discoverFromEnv)
+ *   3. `AI_SDLC_RUNNER_PLUGIN` env — path to a dynamic plugin module (loaded + registered)
+ *   4. ClaudeCodeRunner (hard-coded default)
+ *
+ * IMPORTANT — env-discovered runners do NOT auto-win (AISDLC-529 code review). They are
+ * registered by `discoverFromEnv()` so they are *selectable by name* via `--runner <name>`,
+ * but the mere PRESENCE of an ambient env var (ANTHROPIC_API_KEY, OPENAI_API_KEY, GH_TOKEN,
+ * etc. — commonly set for unrelated tools) must NOT silently switch the runner. Before this
+ * seam existed the orchestrator always used ClaudeCodeRunner; preserving that as the default
+ * (absent an explicit selector) avoids a breaking, surprising change for existing adopters.
+ *
+ * This function is async because step 3 may dynamically import a module.
+ *
+ * @throws Error when `runnerName` is provided but not registered in the registry.
+ * @throws Error when `AI_SDLC_RUNNER_PLUGIN` points to an invalid module.
+ */
+export async function resolveRunner(registry, opts = {}) {
+    const env = opts.env ?? process.env;
+    // 1. Programmatic injection (options.runner / test override) — always wins
+    if (opts.injectedRunner) {
+        return opts.injectedRunner;
+    }
+    // 2. Explicit --runner <name> flag
+    if (opts.runnerName) {
+        const named = registry.get(opts.runnerName);
+        if (!named) {
+            const available = registry.listAvailable().map((r) => r.name);
+            throw new Error(`--runner "${opts.runnerName}" is not registered. ` +
+                `Available runners: ${available.length > 0 ? available.join(', ') : '(none)'}.\n` +
+                `Tip: set AI_SDLC_RUNNER_PLUGIN=/path/to/runner.mjs to load a custom runner first.`);
+        }
+        return named;
+    }
+    // 3. AI_SDLC_RUNNER_PLUGIN env — dynamically load + register, then return
+    const pluginPath = env.AI_SDLC_RUNNER_PLUGIN;
+    if (pluginPath) {
+        const registeredName = await registry.loadFromPlugin(pluginPath);
+        const pluginRunner = registry.get(registeredName);
+        // loadFromPlugin throws on invalid module, so pluginRunner is guaranteed to exist here
+        return pluginRunner;
+    }
+    // 4. ClaudeCodeRunner default (always in registry after discoverFromEnv).
+    // Env-discovered runners are intentionally NOT auto-selected here — the mere presence
+    // of an ambient API-key env var must not silently override the default (AISDLC-529 code
+    // review). An adopter selects an env-discovered runner explicitly via `--runner <name>`.
+    return registry.get('claude-code') ?? new (await import('./claude-code.js')).ClaudeCodeRunner();
+}
 //# sourceMappingURL=runner-registry.js.map