@ai-sdlc/orchestrator 0.9.0 → 0.13.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/models/classifier.d.ts

@@ -51,7 +51,9 @@ export interface DiffSummary {
  * Apply the default classifier ruleset from RFC §12.3 to a diff summary. Used as the
  * fallback when no LLM classifier is configured, and as the seed prompt for LLM-based
  * classifiers. Always returns confident: true with confidence: 1.0 because these are
- * deterministic rules.
+ * deterministic rules. AISDLC-145 added the docs denylist + widened
+ * auth/lockfile/CI predicates to close downgrade vectors flagged by the
+ * AISDLC-141 security reviewer.
  */
 export declare function defaultRulesetDecision(diff: DiffSummary): ClassifierOutput;
 export interface CalibrationLogEntry {

package/dist/models/classifier.js

@@ -146,11 +146,52 @@ export function validateClassifierOutput(value) {
     }
     return { ok: true, value: obj };
 }
+// ── AISDLC-145 path-classification helpers ─────────────────────────────────────────────
+//
+// These predicates are duplicated verbatim in the pipeline-cli copy
+// (`pipeline-cli/src/classifier/classifier.ts`). Keep them in sync — drift
+// here silently shifts which reviewers fire between callers. A future
+// consolidation task should extract a single `@ai-sdlc/classifier-ruleset`
+// package both sides import; tracked as a follow-up to AISDLC-145.
+/** Renderable-docs / image extensions allowed in the docs-only branch. */
+const DOCS_EXTENSIONS_RE = /\.(md|rst|txt|png|jpe?g|svg|gif|ico|pdf)$/i;
+/**
+ * Filenames that look secret-y or executable-y and must NEVER be classified
+ * as docs even if they sit under `docs/`. Hits include `.env`, `.env.local`,
+ * `private-key.pem`, `signing.key`, `install.sh`, `Dockerfile`, `Dockerfile.prod`,
+ * `package-lock.json`, etc. Anchored on the basename so path-prefix doesn't
+ * matter.
+ */
+const DOCS_DENYLIST_RE = /(?:^|\/)(\.env(?:\..+)?|.+\.pem|.+\.key|.+\.sh|Dockerfile.*|.+\.lock)$/i;
+/** True iff the path is safe to treat as documentation-only (no security review). */
+function isDocsLikePath(p) {
+    if (DOCS_DENYLIST_RE.test(p))
+        return false;
+    return DOCS_EXTENSIONS_RE.test(p);
+}
+/** Auth-tier secret files (env vars, private keys) — treated as auth-touching. */
+function isSecretFilePath(p) {
+    return /(?:^|\/)(\.env(?:\..+)?|.+\.pem|.+\.key)$/i.test(p);
+}
+/** Supply-chain lockfile detection (widened in AISDLC-145). */
+function isLockfilePath(p) {
+    return /(?:^|\/)(package(-lock)?\.json|requirements\.txt|pnpm-lock\.yaml|yarn\.lock|Cargo\.lock|poetry\.lock|Pipfile\.lock|Gemfile\.lock|composer\.lock|go\.sum|bun\.lockb)$/i.test(p);
+}
+/** CI-config detection (widened beyond GitHub Actions in AISDLC-145). */
+function isCiPath(p) {
+    if (p.startsWith('.github/workflows/'))
+        return true;
+    if (p.startsWith('.circleci/'))
+        return true;
+    return /(?:^|\/)(\.gitlab-ci\.yml|Jenkinsfile|azure-pipelines\.yml)$/i.test(p);
+}
 /**
  * Apply the default classifier ruleset from RFC §12.3 to a diff summary. Used as the
  * fallback when no LLM classifier is configured, and as the seed prompt for LLM-based
  * classifiers. Always returns confident: true with confidence: 1.0 because these are
- * deterministic rules.
+ * deterministic rules. AISDLC-145 added the docs denylist + widened
+ * auth/lockfile/CI predicates to close downgrade vectors flagged by the
+ * AISDLC-141 security reviewer.
  */
 export function defaultRulesetDecision(diff) {
     if (diff.filesChanged === 0) {
@@ -161,7 +202,15 @@ export function defaultRulesetDecision(diff) {
             confidence: 1,
         };
     }
-    const allDocs = diff.paths.every((p) => /\.(md|rst|txt)$/i.test(p) || p.startsWith('docs/'));
+    // AISDLC-145 hardening: the docs branch is a security DOWNGRADE — it skips
+    // both `testing` and `security` reviewers. So the predicate must be
+    // conservative: a docs-like file is one whose extension is in the safe set
+    // (renderable docs / images) AND is NOT on the unconditional denylist of
+    // executable-or-secret-looking filenames. Pre-145 the rule was just
+    // `p.startsWith('docs/')`, which let `docs/install.sh`, `docs/.env`,
+    // `docs/private-key.pem`, `docs/Dockerfile`, etc. silently bypass the
+    // security reviewer. See the AISDLC-141 reviewer findings.
+    const allDocs = diff.paths.every((p) => isDocsLikePath(p));
     if (allDocs) {
         return {
             reviewers: ['critic'],
@@ -170,9 +219,16 @@ export function defaultRulesetDecision(diff) {
             confidence: 0.95,
         };
     }
-    const touchesAuth = diff.paths.some((p) => /(?:^|\/)(auth|crypto|secrets?)\b/i.test(p));
-    const touchesLockfiles = diff.paths.some((p) => /(?:^|\/)(package(-lock)?\.json|requirements\.txt|pnpm-lock\.yaml|yarn\.lock|Cargo\.lock|poetry\.lock|Pipfile\.lock)$/i.test(p));
-    const touchesCi = diff.paths.some((p) => p.startsWith('.github/workflows/'));
+    // AISDLC-145: widen auth/secret detection. The pre-145 regex
+    // `(auth|crypto|secrets?)` missed common identity/authn paths
+    // (`oauth/`, `iam/`, `jwt/`, `session/`, `login.ts`, `rbac/`, `tokens.ts`,
+    // `credentials.ts`, `password.ts`, `signin/`, `signup/`). Those still ran 3
+    // reviewers via the default branch but never got the opus model bump.
+    // Also: `.env*`, `*.pem`, `*.key` files are treated as auth-tier — they
+    // contain or directly grant credentials.
+    const touchesAuth = diff.paths.some((p) => /(?:^|\/)(auth|oauth|crypto|secrets?|iam|jwt|session|login|rbac|tokens?|credentials?|password|signin|signup)\b/i.test(p) || isSecretFilePath(p));
+    const touchesLockfiles = diff.paths.some((p) => isLockfilePath(p));
+    const touchesCi = diff.paths.some((p) => isCiPath(p));
     if (touchesAuth) {
         return {
             reviewers: ['testing', 'critic', 'security'],

package/dist/pillar-breakdown.d.ts

@@ -36,9 +36,31 @@ export interface SharedDimensions {
      * populates this once the SA-1/SA-2/SA-3 decomposition lands.
      */
     saAlpha3?: number;
-    /** Per-channel HC breakdown with the tanh composite for reference. */
+    /**
+     * Per-channel HC breakdown with the tanh composite for reference.
+     *
+     * `designAuthorityConfigured` (AISDLC-171) — diagnostic flag set when
+     * the resolved DSB declares any `stewardship.designAuthority.principals`
+     * entries, regardless of whether one of them participated in the issue.
+     * Lets operators distinguish three pillarBreakdown states for the design
+     * channel:
+     *   - `design = 0` and `configured === undefined` → no DSB resolved
+     *     (preDesignSystem). HC_design intentionally inert.
+     *   - `design = 0` and `configured === true`     → DSB declares design
+     *     authority but no principal participated as author/commenter.
+     *     HC_design intentionally 0 per RFC-0008 §14.2 (only principals
+     *     emit full-weight HC_design signals; non-principal opinions route
+     *     through HC_consensus, not HC_design).
+     *   - `design ≠ 0` and `configured === true`     → a principal
+     *     participated; signal weight reflects label-derived signalType.
+     *
+     * The `false` case (DSB exists but `principals` is empty) is also
+     * surfaced for completeness — a DSB without designAuthority principals
+     * cannot ever fire HC_design and operators should know.
+     */
     hcComposite: HcChannelBreakdown & {
         value: number;
+        designAuthorityConfigured?: boolean;
     };
 }
 export interface TensionFlag {

package/dist/pillar-breakdown.js

@@ -70,6 +70,15 @@ export function computePillarBreakdown(composite) {
             decision: b.humanCurve.hcDecision,
             design: b.humanCurve.hcDesign,
             value: b.humanCurve.hcComposite,
+            // AISDLC-171: only include the flag when the underlying signal
+            // populated it (i.e., a DSB was resolved). Leaving it `undefined`
+            // when no DSB was supplied keeps the preDesignSystem state
+            // distinct from the "configured but inactive" state at the API
+            // surface — operators inspecting `pillarBreakdown.shared` can
+            // tell the three states apart without reading the DSB themselves.
+            ...(b.humanCurve.designAuthorityConfigured !== undefined
+                ? { designAuthorityConfigured: b.humanCurve.designAuthorityConfigured }
+                : {}),
         },
     };
     const tensions = detectTensions({ product, design, engineering, shared, tensions: [] });

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.`);
+        }
+        // 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