@ai-sdlc/orchestrator 0.13.0 → 0.14.0

package/dist/analysis/file-walker.js

@@ -28,7 +28,12 @@ const MODULE_MARKERS = ['index.ts', 'index.js', 'index.mjs', 'package.json'];
 function matchesGlob(filePath, patterns) {
     for (const pattern of patterns) {
         // Simple glob matching: supports ** and *
+        // Escape backslashes FIRST before any other replacement so that the
+        // subsequent `.replace(/\./g, '\\.')` doesn't produce `\\.` sequences
+        // that are themselves broken when the input contained a `\`
+        // (CodeQL js/incomplete-sanitization alert #67).
         const regex = pattern
+            .replace(/\\/g, '\\\\')
             .replace(/\./g, '\\.')
             .replace(/\*\*/g, '{{GLOBSTAR}}')
             .replace(/\*/g, '[^/]*')

package/dist/cli/commands/git-remote.js

@@ -29,7 +29,7 @@ export function parseRemoteUrl(url) {
         return { org: sshShort[1].split('/').slice(-1)[0], repo: sshShort[2], detected: true };
     }
     // SSH or HTTPS with a scheme
-    let parsed = null;
+    let parsed;
     try {
         parsed = new URL(trimmed);
     }

package/dist/cli/commands/init-features.js

@@ -195,6 +195,17 @@ export function describeOq11Trigger(kind) {
             return 'operator security review identified a risk RLS cannot mitigate (operator-declared)';
     }
 }
+/**
+ * Escape a string for safe embedding inside a YAML double-quoted scalar.
+ * YAML double-quoted strings treat `\` as an escape character, so backslashes
+ * must be escaped first, then double-quotes.  Escaping only `"` (without
+ * first escaping `\`) is an incomplete sanitization — a value like `foo\bar`
+ * would produce `"foo\bar"` where `\b` is a YAML escape sequence.
+ * (CodeQL js/incomplete-sanitization alerts #68, #69, #70.)
+ */
+function escapeYamlDoubleQuoted(value) {
+    return value.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+}
 /**
  * Build the .ai-sdlc/compliance.yaml content for a given compliance declaration.
  *
@@ -209,8 +220,10 @@ export function buildComplianceYaml(opts) {
     const { projectName, regimes, attestedBy, attestedAt, attestedNotes, derivedGates } = opts;
     // AISDLC-324 review fix: quote attestedBy/id/attestedAt so an operator
     // git config user.email containing ": " or other YAML-significant chars
-    // can't break the YAML structure. attestedNotes already quoted+escaped.
-    const quotedAttestedBy = `"${attestedBy.replace(/"/g, '\\"')}"`;
+    // can't break the YAML structure. Use escapeYamlDoubleQuoted() which
+    // escapes backslashes before quotes (incomplete-sanitization fix for
+    // CodeQL alerts #68/#69/#70).
+    const quotedAttestedBy = `"${escapeYamlDoubleQuoted(attestedBy)}"`;
     const regimeItems = regimes
         .map((id) => {
         // id is from hardcoded COMPLIANCE_REGIME_CHOICES (validated upstream)
@@ -218,10 +231,10 @@ export function buildComplianceYaml(opts) {
         const lines = [
             `    - id: ${id}`,
             `      attestedBy: ${quotedAttestedBy}`,
-            `      attestedAt: "${attestedAt}"`,
+            `      attestedAt: "${escapeYamlDoubleQuoted(attestedAt)}"`,
         ];
         if (attestedNotes) {
-            lines.push(`      attestedNotes: "${attestedNotes.replace(/"/g, '\\"')}"`);
+            lines.push(`      attestedNotes: "${escapeYamlDoubleQuoted(attestedNotes)}"`);
         }
         return lines.join('\n');
     })
@@ -244,7 +257,7 @@ export function buildComplianceYaml(opts) {
         `apiVersion: ai-sdlc.io/v1alpha1`,
         `kind: CompliancePosture`,
         `metadata:`,
-        `  name: "${projectName.replace(/"/g, '\\"')}"`,
+        `  name: "${escapeYamlDoubleQuoted(projectName)}"`,
         `spec:`,
         regimesSection,
         `  auditExports: []`,

package/dist/cycle-utils.js

@@ -6,9 +6,22 @@ import { NOTIFICATION_TITLES } from './defaults.js';
 /**
  * Sanitize template content to prevent markdown/HTML injection.
  * Strips HTML tags and limits length.
+ *
+ * A single-pass `<[^>]*>` strip is flagged by CodeQL as
+ * `js/incomplete-multi-character-sanitization` (alert #65) because a
+ * crafted string like `<scr<script>ipt>` leaves `<script>` after one pass.
+ * We iterate the replacement until stable so any re-introduced bad
+ * substring is eliminated on the next pass — making the sanitization
+ * demonstrably idempotent.
  */
 function sanitizeTemplate(text) {
-    return text.replace(/<[^>]*>/g, '').slice(0, 2000);
+    let prev;
+    let current = text;
+    do {
+        prev = current;
+        current = prev.replace(/<[^>]*>/g, '');
+    } while (current !== prev);
+    return current.slice(0, 2000);
 }
 /**
  * Check for pipeline cycles and post notification if detected.

package/dist/execute.js

@@ -12,7 +12,7 @@ import { validateAgentOutput } from './validate-agent-output.js';
 import { createLogger } from './logger.js';
 import { createStructuredConsoleLogger, createStructuredBufferLogger, } from './structured-logger.js';
 import { createRunnerRegistry, resolveRunner } from './runners/runner-registry.js';
-import { execFileAsync, getGitHubConfig, resolveRepoRoot, createDefaultAuditLog, resolveAutonomyLevel, resolveConstraints, isAutonomousStrategy, recordMetric, evaluatePipelineCompliance, authorizeFilesChanged, interpolateBranchPattern, interpolatePRTitle, issueIdToNumber, formatIssueRef, buildIssueTemplateVars, } from './shared.js';
+import { execFileAsync, getGitHubConfig, resolveRepoRoot, createDefaultAuditLog, resolveAutonomyLevel, resolveConstraints, isAutonomousStrategy, recordMetric, evaluatePipelineCompliance, authorizeFilesChanged, interpolateBranchPattern, interpolatePRTitle, issueIdToNumber, formatIssueRef, buildIssueTemplateVars, validateBranchName, } from './shared.js';
 import { cleanGitEnv } from './runtime/git-env.js';
 import { checkKillSwitch, issueAgentCredentials, revokeAgentCredentials, classifyAndSubmitApproval, createPipelineSecurity, } from './security.js';
 import { createPipelineOrchestration, executePipelineOrchestration, validatePipelineHandoffs, } from './orchestration.js';
@@ -307,7 +307,7 @@ export async function pushBranchWithRebase(workDir, branchName, log) {
             /* nothing to abort */
         }
         throw new Error(`Push rebase failed for branch ${branchName}: ${rebaseErr.message}. ` +
-            `Resolve conflicts manually and re-run the pipeline.`);
+            `Resolve conflicts manually and re-run the pipeline.`, { cause: rebaseErr });
     }
     await execFileAsync('git', ['push', 'origin', branchName], { cwd: workDir, env });
     return false;
@@ -453,6 +453,10 @@ async function executePipelineBody(issueId, issue, config, qualityGate, agentRol
     // 7. Create branch and checkout locally (read pattern from pipeline config)
     const branchVars = buildIssueTemplateVars(issueId, issue.title);
     const branchName = interpolateBranchPattern(config.pipeline?.spec.branching?.pattern, branchVars);
+    // Defense against second-order command injection: reject branch names that
+    // start with '-' (git flag injection) or contain chars outside the safe ref
+    // charset. CodeQL alert #167 (js/second-order-command-line-injection).
+    validateBranchName(branchName);
     await sc.createBranch({ name: branchName });
     // cleanGitEnv() prevents leaked GIT_DIR from corrupting these calls (AISDLC-72).
     // Guard: skip fetch when no 'origin' remote is configured (local-only repos).
@@ -1013,8 +1017,13 @@ async function executePipelineBody(issueId, issue, config, qualityGate, agentRol
         details: { averageCoverage: avgCoverage, frameworks: complianceReports.length },
     });
     // 16b. Extended diagnostics (non-blocking)
+    // Awaited so that every async operation started inside the diagnostics pass
+    // completes before executePipeline returns. Without the await, fire-and-forget
+    // promises (resolveAdapterFromGit, scanPipelineAdapters, loadAuditEntries) stay
+    // pending past the function boundary and can fire into a closed vitest worker
+    // MessagePort, producing ERR_IPC_CHANNEL_CLOSED (AISDLC-542).
     try {
-        runPipelineDiagnostics({
+        await runPipelineDiagnostics({
             config,
             qualityGate,
             agentRole,
@@ -1083,9 +1092,15 @@ async function executePipelineBody(issueId, issue, config, qualityGate, agentRol
 /**
  * Non-blocking diagnostics pass that exercises all previously unwired modules.
  * Runs after the main pipeline succeeds — failures are silently ignored.
+ *
+ * Returns a Promise so the caller can await all async work, preventing dangling
+ * promises from outliving the pipeline call and firing into a closed vitest
+ * worker MessagePort (AISDLC-542: ERR_IPC_CHANNEL_CLOSED teardown race).
  */
-function runPipelineDiagnostics(input) {
+async function runPipelineDiagnostics(input) {
     const { config, qualityGate, agentRole, autonomyPolicy, log } = input;
+    // Collect async operations; await all at the end so no promise escapes the function.
+    const asyncOps = [];
     // Policy evaluators: Rego, CEL, ABAC, gate evaluation, complexity scoring
     const _rego = createPipelineRegoEvaluator();
     const _cel = createPipelineCELEvaluator();
@@ -1110,9 +1125,10 @@ function runPipelineDiagnostics(input) {
     const adapterRegistry = createPipelineAdapterRegistry();
     log.info(`Adapter registry: ${adapterRegistry.list().length} adapters registered`);
     const _bridge = createPipelineWebhookBridge();
-    // resolveAdapterFromGit and scanPipelineAdapters are async — fire and forget
-    void resolveAdapterFromGit('github:ai-sdlc-framework/ai-sdlc').catch(() => { });
-    void scanPipelineAdapters({ basePath: `${input.workDir}/.ai-sdlc/adapters` }).catch(() => { });
+    // Collect async ops instead of fire-and-forget — awaited below via Promise.allSettled
+    // so no pending promise outlives this function (AISDLC-542).
+    asyncOps.push(resolveAdapterFromGit('github:ai-sdlc-framework/ai-sdlc').catch(() => { }));
+    asyncOps.push(scanPipelineAdapters({ basePath: `${input.workDir}/.ai-sdlc/adapters` }).catch(() => { }));
     // Extended compliance: per-framework checks, control catalog, mappings
     const controlIds = getControlCatalog();
     const frameworks = listSupportedFrameworks();
@@ -1167,10 +1183,15 @@ function runPipelineDiagnostics(input) {
             resource: 'pipeline',
             decision: 'allowed',
         });
-        void loadAuditEntries(auditPath).catch(() => { });
+        // Collected into asyncOps — awaited below so the promise doesn't escape (AISDLC-542).
+        asyncOps.push(loadAuditEntries(auditPath).catch(() => { }));
         // Note: rotateAuditLog intentionally omitted — it truncates the file,
         // which would empty it before artifact upload can capture the contents.
     }
+    // Await all async diagnostic operations so no promise outlives this function.
+    // allSettled keeps the best-effort semantic: individual failures are silently swallowed,
+    // but the caller can await the diagnostics without unhandled rejections leaking.
+    await Promise.allSettled(asyncOps);
 }
 // ── Gitignore helper ─────────────────────────────────────────────────
 const RUNTIME_GITIGNORE_PATHS = ['.ai-sdlc/state.db', '.ai-sdlc/state/', '.ai-sdlc/audit.jsonl'];

package/dist/fix-review.js

@@ -67,7 +67,7 @@ export async function fetchReviewFindings(prNumber, injectedFindings, _secretSto
         reviews = JSON.parse(stdout);
     }
     catch (err) {
-        throw new Error(`Failed to parse review data from gh CLI: ${err instanceof Error ? err.message : String(err)}`);
+        throw new Error(`Failed to parse review data from gh CLI: ${err instanceof Error ? err.message : String(err)}`, { cause: err });
     }
     const changesRequestedReviews = reviews.filter((r) => r.state === 'CHANGES_REQUESTED');
     if (changesRequestedReviews.length === 0) {

package/dist/journey/metric-snapshot.d.ts

@@ -0,0 +1,403 @@
+/**
+ * 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
+ */
+/**
+ * A single journey success-metric snapshot as supplied by the operator's
+ * analytics pipeline. Matches `spec/schemas/metric-snapshot.v1.schema.json`.
+ */
+export interface MetricSnapshot {
+    /** Always 'ai-sdlc.io/v1alpha1'. */
+    readonly apiVersion: 'ai-sdlc.io/v1alpha1';
+    /** Always 'MetricSnapshot'. */
+    readonly kind: 'MetricSnapshot';
+    readonly metadata: {
+        /**
+         * Path-style journey URI.
+         * Soul-scoped:    `<soul-id>/<journey-id>`
+         * Variant-scoped: `<soul-id>/<variant-id>/<journey-id>`
+         */
+        readonly journey: string;
+        /**
+         * Metric identifier (kebab-case). MUST match a `successMetrics[].id`
+         * on the parent journey declaration.
+         * Examples: 'completion-rate', 'median-time-to-first-task-done'
+         */
+        readonly metricId: string;
+        readonly labels?: Record<string, string>;
+        readonly annotations?: Record<string, string>;
+    };
+    readonly spec: {
+        /** Metric value. Unit convention shared between operator and framework. */
+        readonly value: number;
+        /**
+         * ISO 8601 timestamp when this metric was recorded / sampled.
+         * Used to compute staleness relative to `thresholdDays`.
+         */
+        readonly recordedAt: string;
+        /**
+         * Free-text analytics tool identifier.
+         * Examples: 'mixpanel', 'amplitude', 'heap', 'internal-pipeline'
+         */
+        readonly sourceTool: string;
+        /** Optional ISO 8601 window start (informational). */
+        readonly windowStart?: string;
+        /** Optional ISO 8601 window end (informational). */
+        readonly windowEnd?: string;
+    };
+}
+/**
+ * Staleness configuration for `journey.successMetrics.staleness`.
+ * Matches the corresponding block in `journey-config.v1.schema.json`.
+ */
+export interface MetricStalenessConfig {
+    /** Days after last MetricSnapshot before the metric is stale. Default 30. */
+    readonly thresholdDays?: number;
+}
+/** Default staleness threshold per OQ-5 resolution (30 days). */
+export declare const DEFAULT_STALENESS_THRESHOLD_DAYS = 30;
+/**
+ * Possible states for a metric lookup result.
+ *
+ * - `'fresh'`   — snapshot found AND within staleness threshold
+ * - `'stale'`   — snapshot found BUT older than threshold (warn-and-unknown)
+ * - `'missing'` — no snapshot found for the journey/metricId pair
+ */
+export type MetricFreshness = 'fresh' | 'stale' | 'missing';
+/**
+ * Result returned by `getLatestMetricSnapshot`.
+ *
+ * - When `freshness === 'fresh'`:  `snapshot` is populated; use `snapshot.spec.value`
+ * - When `freshness === 'stale'`:  `snapshot` is populated but `decision` is emitted
+ *   (warn-and-unknown — Cκ treats metric as unknown input, pipeline continues)
+ * - When `freshness === 'missing'`: no snapshot; Cκ scores as unknown input
+ */
+export interface MetricSnapshotResult {
+    /** Journey path URI (e.g. 'spry-engage/onboarding'). */
+    readonly journey: string;
+    /** Metric ID (e.g. 'completion-rate'). */
+    readonly metricId: string;
+    /** Freshness state. */
+    readonly freshness: MetricFreshness;
+    /** The matched snapshot (populated when freshness is 'fresh' or 'stale'). */
+    readonly snapshot?: MetricSnapshot;
+    /**
+     * Decision emitted when `freshness === 'stale'`.
+     * Value: `'journey-metric-stale'`.
+     * Routing: RFC-0035 G0 (non-blocking batch review — warn-and-unknown, not fail-closed).
+     */
+    readonly decision?: 'journey-metric-stale';
+    /** Days since `recordedAt` (populated when snapshot is present). */
+    readonly ageInDays?: number;
+    /** Staleness threshold in days that was applied. */
+    readonly thresholdDays: number;
+}
+/**
+ * Options for `getLatestMetricSnapshot`.
+ */
+export interface GetLatestMetricSnapshotOptions {
+    /**
+     * Collection of all MetricSnapshot records known to the framework.
+     * Callers are responsible for loading these from their persistence layer
+     * (filesystem, in-memory fixture, database) before calling.
+     */
+    readonly snapshots: readonly MetricSnapshot[];
+    /**
+     * Per-Soul staleness config (from the soul's `spec.journeyConfig.successMetrics.staleness`
+     * or the org-wide `.ai-sdlc/journey-config.yaml` default).
+     * When omitted, the default 30d threshold applies.
+     */
+    readonly stalenessConfig?: MetricStalenessConfig;
+    /**
+     * Reference "now" timestamp (ISO 8601). Defaults to `new Date().toISOString()`.
+     * Provided for deterministic testing.
+     */
+    readonly now?: string;
+}
+/**
+ * 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 declare function getLatestMetricSnapshot(journey: string, metricId: string, options: GetLatestMetricSnapshotOptions): MetricSnapshotResult;
+/**
+ * Per-Soul policy for Eρ₅ degradation when the accessibility audit is overdue.
+ * Matches `journey-config.v1.schema.json` `accessibility.auditOverdueGracePolicy`.
+ *
+ * - `'graduated'`  — default; progressive reduction matching Vanta/Drata/Secureframe pattern
+ * - `'binary-30d'` — SOC2/HIPAA strict: no impact within 30d, then fail-closed
+ * - `'hard-block'` — immediate fail at cadence+0d (no grace)
+ */
+export type AuditOverdueGracePolicy = 'graduated' | 'binary-30d' | 'hard-block';
+/**
+ * Eρ₅ impact tiers for graduated degradation.
+ *
+ * - `'warn'`           — Eρ₅ unchanged; Decision emitted for operator visibility
+ * - `'reduced-25'`     — Eρ₅ multiplied by 0.75 (−25%)
+ * - `'reduced-50'`     — Eρ₅ multiplied by 0.50 (−50%)
+ * - `'effective-block'`— Eρ₅ set to 0 (admission blocked)
+ */
+export type Erho5Impact = 'warn' | 'reduced-25' | 'reduced-50' | 'effective-block';
+/** Eρ₅ multiplier for each impact tier. */
+export declare const ERHO5_MULTIPLIERS: Record<Erho5Impact, number>;
+/**
+ * Graduated thresholds configuration (days past audit cadence).
+ * Matches `accessibility.graduatedThresholds` in `journey-config.v1.schema.json`.
+ */
+export interface GraduatedThresholds {
+    /** Days past cadence at which 'warn' Decision fires. Default 0. */
+    readonly warnAt?: number;
+    /** Days past cadence at which −25% reduction fires. Default 30. */
+    readonly reduced25At?: number;
+    /** Days past cadence at which −50% reduction fires. Default 60. */
+    readonly reduced50At?: number;
+    /** Days past cadence at which effective-block fires. Default 90. */
+    readonly effectiveBlockAt?: number;
+}
+/** Default graduated thresholds per OQ-6 resolution. */
+export declare const DEFAULT_GRADUATED_THRESHOLDS: Required<GraduatedThresholds>;
+/**
+ * Decision kinds emitted for accessibility audit overdue events.
+ * Routes through RFC-0035 G0 non-blocking pipeline contract.
+ */
+export type AuditOverdueDecision = 'journey-audit-overdue-warn' | 'journey-audit-overdue-graduated' | 'journey-audit-overdue-blocking';
+/**
+ * Result of the Eρ₅ degradation calculation for an overdue accessibility audit.
+ */
+export interface AuditOverdueResult {
+    /** Soul identifier for which the result was computed. */
+    readonly soulId: string;
+    /** Journey identifier. */
+    readonly journeyId: string;
+    /** Days the audit is past cadence (0 means exactly at cadence). */
+    readonly daysOverdue: number;
+    /** The grace policy that was applied. */
+    readonly policy: AuditOverdueGracePolicy;
+    /** Eρ₅ impact tier. */
+    readonly impact: Erho5Impact;
+    /**
+     * Eρ₅ multiplier to apply to the base Eρ₅ score.
+     * 1.0 = no impact; 0.75 = -25%; 0.50 = -50%; 0.0 = effective block.
+     */
+    readonly erho5Multiplier: number;
+    /**
+     * Decision to emit for this result.
+     * `null` only when daysOverdue < 0 (audit not yet due). At daysOverdue >= 0
+     * (cadence+0d — no grace) a Decision is emitted per the policy.
+     */
+    readonly decision: AuditOverdueDecision | null;
+}
+/**
+ * Options for `computeAuditOverdueErho5`.
+ */
+export interface ComputeAuditOverdueOptions {
+    /** Soul identifier for event attribution. */
+    readonly soulId: string;
+    /** Journey identifier for event attribution. */
+    readonly journeyId: string;
+    /**
+     * Days the journey's audit is past its declared cadence.
+     * 0 = exactly at cadence; positive = overdue; negative = not yet overdue.
+     */
+    readonly daysOverdue: number;
+    /**
+     * Per-Soul grace policy.
+     * Defaults to `'graduated'`.
+     */
+    readonly policy?: AuditOverdueGracePolicy;
+    /**
+     * Per-org graduated threshold configuration.
+     * Only used when `policy === 'graduated'`.
+     * Defaults to `DEFAULT_GRADUATED_THRESHOLDS`.
+     */
+    readonly graduatedThresholds?: GraduatedThresholds;
+}
+/**
+ * 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 declare function computeAuditOverdueErho5(options: ComputeAuditOverdueOptions): AuditOverdueResult;
+/**
+ * Audit cadence values from the journey declaration (RFC-0018 §5.2).
+ * Ordered strictest → least strict for UNION selection.
+ */
+export type AuditCadence = 'continuous' | 'release-gated' | 'quarterly' | 'annually';
+/**
+ * Numeric strictness order for cadence values.
+ * Higher = stricter (shorter audit interval).
+ * Used by `resolveStrictestCadence` to pick the UNION result.
+ */
+export declare const AUDIT_CADENCE_STRICTNESS: Record<AuditCadence, number>;
+/**
+ * Options for `resolveStrictestCadence`.
+ */
+export interface ResolveStrictestCadenceOptions {
+    /**
+     * Journey-level cadence declared in `accessibility.auditCadence`.
+     */
+    readonly journeyCadence: AuditCadence;
+    /**
+     * Cadences required by the active RFC-0022 compliance posture(s).
+     * An empty array means no posture constraint — journey cadence is used as-is.
+     * When multiple postures are active, all are included here.
+     */
+    readonly postureCadences: readonly AuditCadence[];
+}
+/**
+ * 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 declare function resolveStrictestCadence(options: ResolveStrictestCadenceOptions): AuditCadence;
+/**
+ * Options for `resolveStrictestGracePolicy`.
+ */
+export interface ResolveStrictestGracePolicyOptions {
+    /**
+     * Per-Soul grace policy from `accessibility.auditOverdueGracePolicy`.
+     * Defaults to `'graduated'`.
+     */
+    readonly soulPolicy?: AuditOverdueGracePolicy;
+    /**
+     * Grace policies required by the active RFC-0022 compliance postures.
+     * An empty array means no posture constraint — soul policy is used as-is.
+     * SOC2/HIPAA postures typically impose 'binary-30d' or 'hard-block'.
+     */
+    readonly posturesPolicies: readonly AuditOverdueGracePolicy[];
+}
+/**
+ * Policy strictness order (higher = stricter).
+ */
+export declare const GRACE_POLICY_STRICTNESS: Record<AuditOverdueGracePolicy, number>;
+/**
+ * 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 declare function resolveStrictestGracePolicy(options: ResolveStrictestGracePolicyOptions): AuditOverdueGracePolicy;
+//# sourceMappingURL=metric-snapshot.d.ts.map

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.14.0",
   "description": "AI-SDLC Orchestrator — long-running runtime that drives issues through the complete SDLC with AI agents",
   "license": "Apache-2.0",
   "repository": {
@@ -43,20 +43,21 @@
     }
   },
   "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.14.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",