@ai-sdlc/orchestrator 0.13.0 → 0.15.0

package/dist/journey/metric-snapshot.js

@@ -0,0 +1,370 @@
+/**
+ * RFC-0018 Phase 4 — MetricSnapshot resource read API (OQ-5 resolution).
+ *
+ * Implements:
+ *   AC #1: MetricSnapshot schema (spec/schemas/metric-snapshot.v1.schema.json)
+ *   AC #2: MetricSnapshot read API — `getLatestMetricSnapshot(journey, metricId)`
+ *   AC #3: Stale-metric detection (default 30d; per-Soul configurable) with
+ *          `Decision: journey-metric-stale` + warn-and-unknown Cκ behavior
+ *   AC #4: Graduated Eρ₅ degradation (0-30/30-60/60-90/90+ thresholds + Decisions)
+ *   AC #5: Per-Soul `accessibility.auditOverdueGracePolicy` modes
+ *   AC #6: RFC-0022 multi-posture composition (strictest cadence applies)
+ *
+ * ### OQ-5 design summary
+ *
+ * Operators supply MetricSnapshot resources from their analytics pipeline
+ * (Mixpanel, Amplitude, Heap, internal-pipeline). The framework reads
+ * `completion-rate` and other journey-success values; it does NOT compute
+ * them from an analytics backend.
+ *
+ * Staleness: when `recordedAt` is older than `thresholdDays` (default 30),
+ * the scorer treats the metric as an unknown input (warn-and-unknown, NOT
+ * fail-closed). A `Decision: journey-metric-stale` is emitted for operator
+ * batch review.
+ *
+ * ### OQ-6 design summary
+ *
+ * When a journey's accessibility audit is overdue, Eρ₅ degrades on this
+ * graduated schedule (per-Soul policy `auditOverdueGracePolicy`):
+ *
+ *   Policy `graduated` (default):
+ *     0–30d past cadence  → warn only  (`journey-audit-overdue-warn`)
+ *     30–60d              → Eρ₅ -25%   (`journey-audit-overdue-graduated`)
+ *     60–90d              → Eρ₅ -50%   (`journey-audit-overdue-graduated`)
+ *     90d+                → effective block (`journey-audit-overdue-blocking`)
+ *
+ *   Policy `binary-30d`:
+ *     0–30d → no impact (SOC2/HIPAA early-warning model)
+ *     30d+  → immediate Eρ₅ fail
+ *
+ *   Policy `hard-block`:
+ *     Immediate Eρ₅ fail at cadence+0d (strictest, no grace)
+ *
+ * ### RFC-0022 multi-posture composition (AC #6)
+ *
+ * When the RFC-0022 compliance posture declares a stricter cadence than
+ * the soul-default, the strictest constraint wins. This mirrors the
+ * RFC-0030 OQ-13.3 UNION precedent for multi-posture composition.
+ *
+ * ### Decision-routing must-consume contract
+ *
+ * `getLatestMetricSnapshot` emits `decision: 'journey-metric-stale'` when a
+ * snapshot is present but older than `thresholdDays`. Callers MUST inspect
+ * `result.decision` and route it — typically to the RFC-0035 G0 batch-review
+ * queue — before using `result.snapshot.spec.value` for Cκ scoring. Silently
+ * dropping `result.decision` defeats the operator-visibility guarantee that
+ * makes warn-and-unknown safe (non-fail-closed). A typed must-consume pattern:
+ *
+ *   ```ts
+ *   const result = getLatestMetricSnapshot(journey, metricId, opts);
+ *   if (result.decision) emitDecision(result.decision); // required
+ *   if (result.freshness === 'fresh') useValue(result.snapshot!.spec.value);
+ *   ```
+ *
+ * @see spec/rfcs/RFC-0018-in-soul-journey-pattern.md §10.1 OQ-5 + OQ-6
+ * @see spec/schemas/metric-snapshot.v1.schema.json
+ */
+/** Default staleness threshold per OQ-5 resolution (30 days). */
+export const DEFAULT_STALENESS_THRESHOLD_DAYS = 30;
+/**
+ * Retrieve the **latest** MetricSnapshot for the given journey + metricId pair
+ * and classify it as fresh, stale, or missing.
+ *
+ * Selection: when multiple snapshots match, the one with the most recent
+ * `spec.recordedAt` is returned (latest-wins). This covers the case where
+ * the operator's pipeline emits snapshots on a periodic schedule.
+ *
+ * Staleness: `ageInDays = (now - recordedAt) / (1000 * 60 * 60 * 24)`.
+ * When `ageInDays > thresholdDays`, the result carries:
+ *   - `freshness: 'stale'`
+ *   - `decision: 'journey-metric-stale'`
+ *
+ * This Decision routes through RFC-0035 G0 (non-blocking batch review):
+ * the Cκ scorer treats a stale metric as an unknown input (same behavior as
+ * `freshness: 'missing'`), NOT as a hard fail. The pipeline continues.
+ *
+ * @param journey   Path-style journey URI (e.g. 'spry-engage/onboarding')
+ * @param metricId  Metric identifier (e.g. 'completion-rate')
+ * @param options   Snapshot collection + optional per-Soul config
+ */
+export function getLatestMetricSnapshot(journey, metricId, options) {
+    const { snapshots, stalenessConfig, now } = options;
+    const thresholdDays = stalenessConfig?.thresholdDays ?? DEFAULT_STALENESS_THRESHOLD_DAYS;
+    const nowMs = now ? new Date(now).getTime() : Date.now();
+    // Filter to snapshots matching this journey + metricId pair.
+    const matching = snapshots.filter((s) => s.metadata.journey === journey && s.metadata.metricId === metricId);
+    if (matching.length === 0) {
+        return {
+            journey,
+            metricId,
+            freshness: 'missing',
+            thresholdDays,
+        };
+    }
+    // Select the most recent by recordedAt (latest-wins).
+    const latest = matching.reduce((best, candidate) => {
+        const bestMs = new Date(best.spec.recordedAt).getTime();
+        const candidateMs = new Date(candidate.spec.recordedAt).getTime();
+        return candidateMs > bestMs ? candidate : best;
+    });
+    const recordedAtMs = new Date(latest.spec.recordedAt).getTime();
+    // Guard: a future-dated recordedAt (recordedAt > now) would yield a negative
+    // ageInDays, making the metric appear perpetually fresh and suppressing the
+    // journey-metric-stale Decision. Clamp negative ages to stale so a
+    // misconfigured analytics pipeline cannot silently defeat staleness checks.
+    const rawAgeInDays = (nowMs - recordedAtMs) / (1000 * 60 * 60 * 24);
+    const ageInDays = rawAgeInDays < 0 ? thresholdDays + 1 : rawAgeInDays;
+    if (ageInDays > thresholdDays) {
+        return {
+            journey,
+            metricId,
+            freshness: 'stale',
+            snapshot: latest,
+            decision: 'journey-metric-stale',
+            ageInDays,
+            thresholdDays,
+        };
+    }
+    return {
+        journey,
+        metricId,
+        freshness: 'fresh',
+        snapshot: latest,
+        ageInDays,
+        thresholdDays,
+    };
+}
+/** Eρ₅ multiplier for each impact tier. */
+export const ERHO5_MULTIPLIERS = {
+    warn: 1.0,
+    'reduced-25': 0.75,
+    'reduced-50': 0.5,
+    'effective-block': 0.0,
+};
+/** Default graduated thresholds per OQ-6 resolution. */
+export const DEFAULT_GRADUATED_THRESHOLDS = {
+    warnAt: 0,
+    reduced25At: 30,
+    reduced50At: 60,
+    effectiveBlockAt: 90,
+};
+/**
+ * Compute the Eρ₅ impact and Decision for an overdue accessibility audit.
+ *
+ * Implements RFC-0018 §10.1 OQ-6 graduated Eρ₅ degradation:
+ *
+ * Policy `graduated` (default):
+ *   - 0 ≤ daysOverdue < 30  → `warn`           (multiplier 1.0)
+ *   - 30 ≤ daysOverdue < 60 → `reduced-25`     (multiplier 0.75)
+ *   - 60 ≤ daysOverdue < 90 → `reduced-50`     (multiplier 0.50)
+ *   - daysOverdue ≥ 90      → `effective-block` (multiplier 0.0)
+ *
+ * Policy `binary-30d` (SOC2/HIPAA strict):
+ *   - daysOverdue < 30  → no impact (multiplier 1.0, no Decision)
+ *   - daysOverdue ≥ 30  → `effective-block` (multiplier 0.0)
+ *
+ * Policy `hard-block` (HIPAA/PCI-DSS ultra-strict):
+ *   - daysOverdue < 0   → no impact (multiplier 1.0, no Decision; not yet due)
+ *   - daysOverdue ≥ 0   → `effective-block` (multiplier 0.0) — cadence+0d, no grace
+ *
+ * When `daysOverdue < 0`, returns multiplier 1.0 and `decision: null`
+ * regardless of policy (audit is not yet due). At daysOverdue ≥ 0 each policy
+ * emits its Decision (no implicit grace day).
+ */
+export function computeAuditOverdueErho5(options) {
+    const { soulId, journeyId, daysOverdue, policy = 'graduated', graduatedThresholds } = options;
+    // Strictly negative daysOverdue means the audit is not yet due — no impact
+    // regardless of policy. Note: daysOverdue === 0 means "exactly at cadence
+    // boundary (cadence+0d)" and is intentionally NOT caught here so the
+    // policy-specific logic below can apply. In particular, `hard-block`
+    // specifies "no grace at cadence+0d", meaning it must fire at daysOverdue=0.
+    if (daysOverdue < 0) {
+        return {
+            soulId,
+            journeyId,
+            daysOverdue,
+            policy,
+            impact: 'warn',
+            erho5Multiplier: 1.0,
+            decision: null,
+        };
+    }
+    if (policy === 'hard-block') {
+        return {
+            soulId,
+            journeyId,
+            daysOverdue,
+            policy,
+            impact: 'effective-block',
+            erho5Multiplier: ERHO5_MULTIPLIERS['effective-block'],
+            decision: 'journey-audit-overdue-blocking',
+        };
+    }
+    if (policy === 'binary-30d') {
+        const threshold = 30;
+        if (daysOverdue < threshold) {
+            // SOC2/HIPAA grace window: warn only, no Eρ₅ impact.
+            return {
+                soulId,
+                journeyId,
+                daysOverdue,
+                policy,
+                impact: 'warn',
+                erho5Multiplier: 1.0,
+                decision: 'journey-audit-overdue-warn',
+            };
+        }
+        return {
+            soulId,
+            journeyId,
+            daysOverdue,
+            policy,
+            impact: 'effective-block',
+            erho5Multiplier: ERHO5_MULTIPLIERS['effective-block'],
+            decision: 'journey-audit-overdue-blocking',
+        };
+    }
+    // policy === 'graduated' (default)
+    // Guard: NaN daysOverdue (e.g. from a division by zero or bad caller) must
+    // not fall through to the warn/1.0 return at the bottom of the graduated
+    // path, producing a fail-open result. Treat non-finite values as
+    // effective-block (conservative) so the pipeline aborts rather than silently
+    // continuing with an unknown overdue duration.
+    if (!Number.isFinite(daysOverdue)) {
+        return {
+            soulId,
+            journeyId,
+            daysOverdue,
+            policy,
+            impact: 'effective-block',
+            erho5Multiplier: ERHO5_MULTIPLIERS['effective-block'],
+            decision: 'journey-audit-overdue-blocking',
+        };
+    }
+    const thresholds = {
+        warnAt: graduatedThresholds?.warnAt ?? DEFAULT_GRADUATED_THRESHOLDS.warnAt,
+        reduced25At: graduatedThresholds?.reduced25At ?? DEFAULT_GRADUATED_THRESHOLDS.reduced25At,
+        reduced50At: graduatedThresholds?.reduced50At ?? DEFAULT_GRADUATED_THRESHOLDS.reduced50At,
+        effectiveBlockAt: graduatedThresholds?.effectiveBlockAt ?? DEFAULT_GRADUATED_THRESHOLDS.effectiveBlockAt,
+    };
+    if (daysOverdue >= thresholds.effectiveBlockAt) {
+        return {
+            soulId,
+            journeyId,
+            daysOverdue,
+            policy,
+            impact: 'effective-block',
+            erho5Multiplier: ERHO5_MULTIPLIERS['effective-block'],
+            decision: 'journey-audit-overdue-blocking',
+        };
+    }
+    if (daysOverdue >= thresholds.reduced50At) {
+        return {
+            soulId,
+            journeyId,
+            daysOverdue,
+            policy,
+            impact: 'reduced-50',
+            erho5Multiplier: ERHO5_MULTIPLIERS['reduced-50'],
+            decision: 'journey-audit-overdue-graduated',
+        };
+    }
+    if (daysOverdue >= thresholds.reduced25At) {
+        return {
+            soulId,
+            journeyId,
+            daysOverdue,
+            policy,
+            impact: 'reduced-25',
+            erho5Multiplier: ERHO5_MULTIPLIERS['reduced-25'],
+            decision: 'journey-audit-overdue-graduated',
+        };
+    }
+    // daysOverdue >= warnAt (default 0) but below reduced25At
+    return {
+        soulId,
+        journeyId,
+        daysOverdue,
+        policy,
+        impact: 'warn',
+        erho5Multiplier: 1.0,
+        decision: 'journey-audit-overdue-warn',
+    };
+}
+/**
+ * Numeric strictness order for cadence values.
+ * Higher = stricter (shorter audit interval).
+ * Used by `resolveStrictestCadence` to pick the UNION result.
+ */
+export const AUDIT_CADENCE_STRICTNESS = {
+    continuous: 4,
+    'release-gated': 3,
+    quarterly: 2,
+    annually: 1,
+};
+/**
+ * Resolve the effective audit cadence by applying the strictest constraint
+ * from the journey declaration and all active RFC-0022 compliance postures.
+ *
+ * This implements RFC-0018 AC #6 + RFC-0030 OQ-13.3 UNION precedent:
+ * the strictest constraint among all active postures and the journey's own
+ * declaration wins.
+ *
+ * @example
+ * // Journey declares 'annually', but SOC2 posture requires 'quarterly'
+ * resolveStrictestCadence({
+ *   journeyCadence: 'annually',
+ *   postureCadences: ['quarterly'],
+ * })
+ * // → 'quarterly' (posture wins — stricter)
+ *
+ * @example
+ * // Journey declares 'continuous' (strictest possible)
+ * resolveStrictestCadence({
+ *   journeyCadence: 'continuous',
+ *   postureCadences: ['quarterly', 'annually'],
+ * })
+ * // → 'continuous' (journey wins — already strictest)
+ */
+export function resolveStrictestCadence(options) {
+    const { journeyCadence, postureCadences } = options;
+    const all = [journeyCadence, ...postureCadences];
+    // UNION = strictest (highest strictness number wins).
+    return all.reduce((strictest, candidate) => {
+        const currentOrder = AUDIT_CADENCE_STRICTNESS[strictest] ?? 0;
+        const candidateOrder = AUDIT_CADENCE_STRICTNESS[candidate] ?? 0;
+        return candidateOrder > currentOrder ? candidate : strictest;
+    });
+}
+/**
+ * Policy strictness order (higher = stricter).
+ */
+export const GRACE_POLICY_STRICTNESS = {
+    graduated: 1,
+    'binary-30d': 2,
+    'hard-block': 3,
+};
+/**
+ * Resolve the effective grace policy by picking the STRICTEST among the
+ * soul-level policy and all active RFC-0022 compliance posture policies.
+ *
+ * RFC-0022 + RFC-0018 AC #6: multi-posture UNION → strictest applies.
+ *
+ * @example
+ * // Soul defaults to 'graduated'; SOC2 posture requires 'binary-30d'
+ * resolveStrictestGracePolicy({
+ *   soulPolicy: 'graduated',
+ *   posturesPolicies: ['binary-30d'],
+ * })
+ * // → 'binary-30d' (posture wins — stricter)
+ */
+export function resolveStrictestGracePolicy(options) {
+    const { soulPolicy = 'graduated', posturesPolicies } = options;
+    const all = [soulPolicy, ...posturesPolicies];
+    return all.reduce((strictest, candidate) => {
+        const currentOrder = GRACE_POLICY_STRICTNESS[strictest] ?? 0;
+        const candidateOrder = GRACE_POLICY_STRICTNESS[candidate] ?? 0;
+        return candidateOrder > currentOrder ? candidate : strictest;
+    });
+}
+//# sourceMappingURL=metric-snapshot.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/runner-registry.js

@@ -75,7 +75,7 @@ export class RunnerRegistry {
         }
         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.`);
+                `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;

package/dist/runtime/attestations.js

@@ -554,7 +554,9 @@ export function collectChangedFileEntriesForV5(repoRoot, baseRef = 'origin/main'
     }
     catch (err) {
         const msg = err instanceof Error ? err.message : String(err);
-        throw new Error(`collectChangedFileEntriesForV5: git merge-base failed: ${msg}`);
+        throw new Error(`collectChangedFileEntriesForV5: git merge-base failed: ${msg}`, {
+            cause: err,
+        });
     }
     if (!/^[0-9a-f]{40}$/i.test(signedMergeBase)) {
         throw new Error(`collectChangedFileEntriesForV5: git merge-base returned non-SHA output: ${JSON.stringify(signedMergeBase)}`);
@@ -577,7 +579,9 @@ export function collectChangedFileEntriesForV5(repoRoot, baseRef = 'origin/main'
     }
     catch (err) {
         const msg = err instanceof Error ? err.message : String(err);
-        throw new Error(`collectChangedFileEntriesForV5: git diff --name-only failed: ${msg}`);
+        throw new Error(`collectChangedFileEntriesForV5: git diff --name-only failed: ${msg}`, {
+            cause: err,
+        });
     }
     const paths = nameOnly.split('\n').filter((p) => p.length > 0);
     const entries = [];
@@ -722,7 +726,9 @@ export function collectChangedFileEntries(baseRef, headRef, repoRoot, options =
     }
     catch (err) {
         const msg = err instanceof Error ? err.message : String(err);
-        throw new Error(`collectChangedFileEntries: git diff --name-only failed: ${msg}`);
+        throw new Error(`collectChangedFileEntries: git diff --name-only failed: ${msg}`, {
+            cause: err,
+        });
     }
     const paths = nameOnly.split('\n').filter((p) => p.length > 0);
     const entries = [];
@@ -929,7 +935,9 @@ export function collectChangedFileDeltaEntries(baseRef, headRef, repoRoot, optio
     }
     catch (err) {
         const msg = err instanceof Error ? err.message : String(err);
-        throw new Error(`collectChangedFileDeltaEntries: git merge-base failed: ${msg}`);
+        throw new Error(`collectChangedFileDeltaEntries: git merge-base failed: ${msg}`, {
+            cause: err,
+        });
     }
     if (!/^[0-9a-f]{40}$/.test(mergeBase)) {
         throw new Error(`collectChangedFileDeltaEntries: git merge-base returned non-SHA output: ${JSON.stringify(mergeBase)}`);
@@ -947,7 +955,9 @@ export function collectChangedFileDeltaEntries(baseRef, headRef, repoRoot, optio
     }
     catch (err) {
         const msg = err instanceof Error ? err.message : String(err);
-        throw new Error(`collectChangedFileDeltaEntries: git diff --name-only failed: ${msg}`);
+        throw new Error(`collectChangedFileDeltaEntries: git diff --name-only failed: ${msg}`, {
+            cause: err,
+        });
     }
     const paths = nameOnly.split('\n').filter((p) => p.length > 0);
     const entries = [];

package/dist/sa-scoring/exemplar-bank.js

@@ -29,7 +29,9 @@ export function loadExemplarBank(filePath) {
         doc = parseYaml(raw);
     }
     catch (err) {
-        throw new Error(`Failed to parse SA exemplar bank at ${filePath}: ${err.message}`);
+        throw new Error(`Failed to parse SA exemplar bank at ${filePath}: ${err.message}`, {
+            cause: err,
+        });
     }
     if (!doc || typeof doc !== 'object' || !('exemplars' in doc)) {
         throw new Error(`SA exemplar bank ${filePath} must contain a top-level "exemplars" array`);

package/dist/shared.d.ts

@@ -28,8 +28,36 @@ export declare function slugify(input: string, maxLen?: number): string;
 /**
  * Interpolate a branch name pattern by replacing `{key}` placeholders.
  * Falls back to `ai-sdlc/issue-{issueNumber}` when no pattern is provided.
+ *
+ * **Security advisory — `{issueTitle}` is unsafe in custom branch patterns.**
+ * Issue titles are user-supplied and may contain characters outside the safe
+ * git ref charset `[A-Za-z0-9/_.-]` (e.g. spaces, colons, parentheses, Unicode).
+ * When those characters are interpolated into a custom `branchPattern`, the
+ * resulting branch name fails `validateBranchName()` and the pipeline aborts.
+ * Use `{slug}` instead — it is the output of `slugify(issueTitle)` and is
+ * guaranteed to consist only of lowercase alphanumerics and hyphens.
+ *
+ * @example
+ * // SAFE:
+ * 'ai-sdlc/{issueIdLower}-{slug}'   // slug is pre-sanitized
+ *
+ * // UNSAFE (may throw validateBranchName):
+ * 'ai-sdlc/{issueIdLower}-{issueTitle}'  // issueTitle is raw user input
  */
 export declare function interpolateBranchPattern(pattern: string | undefined, vars: Record<string, string>): string;
+/**
+ * Validate that a computed branch name is safe to pass to `git` as a
+ * positional argument (defense against second-order command injection,
+ * CodeQL js/second-order-command-line-injection, alert #167).
+ *
+ * Git ref names MUST:
+ *   - Not start with `-` (would be parsed as a flag, e.g. `--upload-pack=cmd`)
+ *   - Contain only safe characters: alphanumerics, `/`, `-`, `_`, `.`
+ *
+ * Throws `Error` when the name fails validation so the pipeline aborts
+ * before any `git fetch/checkout/push` call uses the tainted value.
+ */
+export declare function validateBranchName(name: string): void;
 /**
  * Interpolate a PR title template by replacing `{key}` placeholders.
  * Falls back to `fix: {issueTitle} (#{issueNumber})` when no template is provided.

package/dist/shared.js

@@ -59,10 +59,47 @@ export function slugify(input, maxLen = 40) {
 /**
  * Interpolate a branch name pattern by replacing `{key}` placeholders.
  * Falls back to `ai-sdlc/issue-{issueNumber}` when no pattern is provided.
+ *
+ * **Security advisory — `{issueTitle}` is unsafe in custom branch patterns.**
+ * Issue titles are user-supplied and may contain characters outside the safe
+ * git ref charset `[A-Za-z0-9/_.-]` (e.g. spaces, colons, parentheses, Unicode).
+ * When those characters are interpolated into a custom `branchPattern`, the
+ * resulting branch name fails `validateBranchName()` and the pipeline aborts.
+ * Use `{slug}` instead — it is the output of `slugify(issueTitle)` and is
+ * guaranteed to consist only of lowercase alphanumerics and hyphens.
+ *
+ * @example
+ * // SAFE:
+ * 'ai-sdlc/{issueIdLower}-{slug}'   // slug is pre-sanitized
+ *
+ * // UNSAFE (may throw validateBranchName):
+ * 'ai-sdlc/{issueIdLower}-{issueTitle}'  // issueTitle is raw user input
  */
 export function interpolateBranchPattern(pattern, vars) {
     return interpolate(pattern ?? DEFAULT_BRANCH_TEMPLATE, vars);
 }
+/**
+ * Validate that a computed branch name is safe to pass to `git` as a
+ * positional argument (defense against second-order command injection,
+ * CodeQL js/second-order-command-line-injection, alert #167).
+ *
+ * Git ref names MUST:
+ *   - Not start with `-` (would be parsed as a flag, e.g. `--upload-pack=cmd`)
+ *   - Contain only safe characters: alphanumerics, `/`, `-`, `_`, `.`
+ *
+ * Throws `Error` when the name fails validation so the pipeline aborts
+ * before any `git fetch/checkout/push` call uses the tainted value.
+ */
+export function validateBranchName(name) {
+    if (name.startsWith('-')) {
+        throw new Error(`[security] Computed branch name starts with '-' and would be interpreted as a git flag: ${JSON.stringify(name)}`);
+    }
+    // Allow the chars that appear in all supported branch name templates:
+    // alphanumerics, forward-slash (namespace separator), hyphen, underscore, dot.
+    if (!/^[A-Za-z0-9/_.-]+$/.test(name)) {
+        throw new Error(`[security] Computed branch name contains characters outside the safe ref charset [A-Za-z0-9/_.-]: ${JSON.stringify(name)}`);
+    }
+}
 /**
  * Interpolate a PR title template by replacing `{key}` placeholders.
  * Falls back to `fix: {issueTitle} (#{issueNumber})` when no template is provided.

package/dist/webhook-manager.js

@@ -6,7 +6,13 @@ import { createWebhookServer, createWebhookBridge, createGitHubWebhookProvider,
 // ── Implementation ───────────────────────────────────────────────────
 export function createWebhookManager(config) {
     const server = createWebhookServer({ port: config.port, host: config.host });
-    // Create unified bridges
+    // Create unified bridges.
+    // The `: unknown` annotations below are explicit (matching the
+    // `WebhookTransformer<T> = (payload: unknown) => T | null` contract) to guard
+    // against a fresh-worktree implicit-any (TS7006): when `@ai-sdlc/reference`
+    // dist is absent, TS resolves its types as `any` and the inferred callback
+    // param becomes implicitly `any`. Do not remove these as "redundant" — that
+    // re-introduces the build-order-sensitive typecheck failure (AISDLC-517).
     const issueBridge = createWebhookBridge((payload) => {
         // Try each transformer in order
         return (transformIssueEvent(payload) ??

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-sdlc/orchestrator",
-  "version": "0.13.0",
+  "version": "0.15.0",
   "description": "AI-SDLC Orchestrator — long-running runtime that drives issues through the complete SDLC with AI agents",
   "license": "Apache-2.0",
   "repository": {
@@ -37,26 +37,31 @@
       "types": "./dist/state/index.d.ts",
       "import": "./dist/state/index.js"
     },
+    "./runtime": {
+      "types": "./dist/runtime/index.d.ts",
+      "import": "./dist/runtime/index.js"
+    },
     "./cli": {
       "types": "./dist/cli/index.d.ts",
       "import": "./dist/cli/index.js"
     }
   },
   "dependencies": {
-    "@inquirer/prompts": "^7.0.0",
-    "better-sqlite3": "^11.0.0",
+    "@inquirer/prompts": "^8.5.2",
+    "better-sqlite3": "^12.11.1",
     "commander": "^15.0.0",
     "franc": "^6.2.0",
     "yaml": "^2.9.0",
-    "@ai-sdlc/reference": "0.13.0"
+    "@ai-sdlc/reference": "0.15.0"
   },
   "devDependencies": {
     "@types/better-sqlite3": "^7.6.0",
-    "@types/node": "^25.9.2",
-    "@vitest/coverage-v8": "^3.2.4",
+    "@types/node": "^25.9.3",
+    "@vitest/coverage-v8": "^4.1.9",
     "tsx": "^4.22.4",
     "typescript": "^6.0.3",
-    "vitest": "^3.0.0"
+    "vite": "^6.0.0",
+    "vitest": "^4.1.9"
   },
   "scripts": {
     "build": "tsc",