@ai-sdlc/orchestrator 0.4.0 → 0.6.0

package/dist/priority.js

@@ -0,0 +1,230 @@
+/**
+ * Product Priority Algorithm (PPA) — composite scoring module.
+ *
+ * Implements the PPA priority function:
+ *   P(w) = Sα(w) × Dπ(w) × Mφ(w) × Eρ(w) × (1 − Eτ) × (1 + HC(w)) × Cκ(w)
+ *
+ * Each dimension maps real-world product signals into a bounded numeric
+ * range and the multiplicative composite lets any single zero-score
+ * dimension veto the work item.
+ *
+ * RFC reference: PPA section (priority scoring).
+ */
+// ── Constants ───────────────────────────────────────────────────────
+/** Default value used when an input signal is not provided. */
+const DEFAULT_SIGNAL = 0.5;
+/** Market force bounds — tighter than the paper's [0.025, 45]. */
+const MARKET_FORCE_MIN = 0.5;
+const MARKET_FORCE_MAX = 3.0;
+/** Calibration coefficient bounds. */
+const CALIBRATION_MIN = 0.7;
+const CALIBRATION_MAX = 1.3;
+/** Default weights for human curve sub-components. */
+const DEFAULT_HC_WEIGHTS = { explicit: 0.5, consensus: 0.3, decision: 0.2 };
+/**
+ * Total number of optional input fields that contribute to confidence.
+ * When all are provided confidence = 1; when none are provided confidence
+ * equals the ratio of zero provided over this count.
+ */
+const SCORABLE_FIELDS = [
+    'soulAlignment',
+    'customerRequestCount',
+    'demandSignal',
+    'bugSeverity',
+    'builderConviction',
+    'techInflection',
+    'competitivePressure',
+    'regulatoryUrgency',
+    'complexity',
+    'budgetUtilization',
+    'dependencyClearance',
+    'competitiveDrift',
+    'marketDivergence',
+    'explicitPriority',
+    'teamConsensus',
+    'meetingDecision',
+];
+// ── Helpers ─────────────────────────────────────────────────────────
+/** Clamp a value to [min, max]. */
+function clamp(value, min, max) {
+    return Math.min(max, Math.max(min, value));
+}
+// ── Dimension Computations ──────────────────────────────────────────
+/**
+ * Sα — Soul Alignment [0, 1].
+ * How well the work item aligns with the product's core mission.
+ */
+function computeSoulAlignment(input) {
+    return clamp(input.soulAlignment ?? DEFAULT_SIGNAL, 0, 1);
+}
+/**
+ * Dπ — Demand Pressure [0, 1.5].
+ * Blends customer requests, recency-weighted demand, bug severity, and
+ * builder conviction into a single demand signal.
+ */
+function computeDemandPressure(input) {
+    const requestSignal = input.customerRequestCount !== undefined
+        ? Math.min(1, input.customerRequestCount / 10)
+        : DEFAULT_SIGNAL;
+    const demandSignal = input.demandSignal ?? DEFAULT_SIGNAL;
+    const severitySignal = input.bugSeverity !== undefined ? input.bugSeverity / 5 : 0; // no bug severity means no bug boost
+    const conviction = input.builderConviction ?? DEFAULT_SIGNAL;
+    // Weighted blend, scaled to [0, 1.5]
+    const raw = requestSignal * 0.3 + demandSignal * 0.3 + severitySignal * 0.2 + conviction * 0.2;
+    return clamp(raw * 1.5, 0, 1.5);
+}
+/**
+ * Mφ — Market Force [0.5, 3.0].
+ * Captures technology inflection, competitive pressure, and regulatory
+ * urgency as a multiplicative amplifier.
+ */
+function computeMarketForce(input) {
+    const tech = input.techInflection ?? DEFAULT_SIGNAL;
+    const competitive = input.competitivePressure ?? DEFAULT_SIGNAL;
+    const regulatory = input.regulatoryUrgency ?? DEFAULT_SIGNAL;
+    // Average of the three signals, scaled to the bounded range
+    const avg = (tech + competitive + regulatory) / 3;
+    const scaled = MARKET_FORCE_MIN + avg * (MARKET_FORCE_MAX - MARKET_FORCE_MIN);
+    return clamp(scaled, MARKET_FORCE_MIN, MARKET_FORCE_MAX);
+}
+/**
+ * Eρ — Execution Reality [0, 1].
+ * Factors in complexity (inverse), budget headroom, and dependency
+ * clearance to express how feasible execution is right now.
+ */
+function computeExecutionReality(input) {
+    // Complexity 1-10 → inverse feasibility (1 = easy, 10 = very hard)
+    const complexityFeasibility = input.complexity !== undefined ? 1 - (input.complexity - 1) / 9 : DEFAULT_SIGNAL;
+    // Budget utilization: higher usage → less headroom → lower score
+    const budgetHeadroom = input.budgetUtilization !== undefined
+        ? 1 - clamp(input.budgetUtilization / 100, 0, 1)
+        : DEFAULT_SIGNAL;
+    const depClearance = input.dependencyClearance ?? DEFAULT_SIGNAL;
+    const raw = complexityFeasibility * 0.4 + budgetHeadroom * 0.3 + depClearance * 0.3;
+    return clamp(raw, 0, 1);
+}
+/**
+ * Eτ — Entropy Tax [0, 1].
+ * Captures competitive drift and market divergence. Higher entropy means
+ * the work item is becoming less relevant over time.
+ */
+function computeEntropyTax(input) {
+    const drift = input.competitiveDrift ?? 0; // default: no drift
+    const divergence = input.marketDivergence ?? 0; // default: no divergence
+    const raw = (drift + divergence) / 2;
+    return clamp(raw, 0, 1);
+}
+/**
+ * HC — Human Curve [-1, 1].
+ * Blends explicit priority, team consensus, and meeting decisions through
+ * tanh to produce a bounded human signal.
+ */
+function computeHumanCurve(input, weights) {
+    const explicit = input.explicitPriority ?? DEFAULT_SIGNAL;
+    const consensus = input.teamConsensus ?? DEFAULT_SIGNAL;
+    const decision = input.meetingDecision ?? DEFAULT_SIGNAL;
+    // Center around 0.5 so default inputs produce ~0 HC
+    const centered = (explicit - 0.5) * weights.explicit +
+        (consensus - 0.5) * weights.consensus +
+        (decision - 0.5) * weights.decision;
+    // Scale up so full-range inputs can reach [-1, 1] through tanh
+    return Math.tanh(centered * 2);
+}
+/**
+ * Cκ — Calibration Coefficient [0.7, 1.3].
+ * A tuning knob that lets operators scale the final score up or down.
+ */
+function computeCalibration(config) {
+    const coeff = config?.calibrationCoefficient ?? 1.0;
+    return clamp(coeff, CALIBRATION_MIN, CALIBRATION_MAX);
+}
+// ── Confidence ──────────────────────────────────────────────────────
+/**
+ * Compute a confidence score [0, 1] based on the fraction of optional
+ * input fields that were explicitly provided (not defaulted).
+ */
+function computeConfidence(input) {
+    let provided = 0;
+    for (const field of SCORABLE_FIELDS) {
+        if (input[field] !== undefined) {
+            provided++;
+        }
+    }
+    return provided / SCORABLE_FIELDS.length;
+}
+// ── Public API ──────────────────────────────────────────────────────
+/**
+ * Compute the PPA composite priority score for a single work item.
+ *
+ * P(w) = Sα × Dπ × Mφ × Eρ × (1 − Eτ) × (1 + HC) × Cκ
+ */
+export function computePriority(input, config) {
+    const timestamp = new Date().toISOString();
+    // ── Override path ──────────────────────────────────────────────
+    if (input.override) {
+        return {
+            composite: Infinity,
+            dimensions: {
+                soulAlignment: 1,
+                demandPressure: 1.5,
+                marketForce: MARKET_FORCE_MAX,
+                executionReality: 1,
+                entropyTax: 0,
+                humanCurve: 1,
+                calibration: 1,
+            },
+            confidence: 1,
+            timestamp,
+            override: {
+                reason: input.overrideReason ?? 'No reason provided',
+                expiry: input.overrideExpiry,
+            },
+        };
+    }
+    // ── Resolve HC weights ─────────────────────────────────────────
+    const hcWeights = {
+        explicit: config?.humanCurveWeights?.explicit ?? DEFAULT_HC_WEIGHTS.explicit,
+        consensus: config?.humanCurveWeights?.consensus ?? DEFAULT_HC_WEIGHTS.consensus,
+        decision: config?.humanCurveWeights?.decision ?? DEFAULT_HC_WEIGHTS.decision,
+    };
+    // ── Compute each dimension ────────────────────────────────────
+    const soulAlignment = computeSoulAlignment(input);
+    const demandPressure = computeDemandPressure(input);
+    const marketForce = computeMarketForce(input);
+    const executionReality = computeExecutionReality(input);
+    const entropyTax = computeEntropyTax(input);
+    const humanCurve = computeHumanCurve(input, hcWeights);
+    const calibration = computeCalibration(config);
+    // ── Composite ─────────────────────────────────────────────────
+    const composite = soulAlignment *
+        demandPressure *
+        marketForce *
+        executionReality *
+        (1 - entropyTax) *
+        (1 + humanCurve) *
+        calibration;
+    return {
+        composite,
+        dimensions: {
+            soulAlignment,
+            demandPressure,
+            marketForce,
+            executionReality,
+            entropyTax,
+            humanCurve,
+            calibration,
+        },
+        confidence: computeConfidence(input),
+        timestamp,
+    };
+}
+/**
+ * Score and rank multiple work items by descending composite priority.
+ * Override items (composite = Infinity) always sort first.
+ */
+export function rankWorkItems(items, config) {
+    return items
+        .map((item) => ({ ...item, score: computePriority(item, config) }))
+        .sort((a, b) => b.score.composite - a.score.composite);
+}
+//# sourceMappingURL=priority.js.map

package/dist/review.d.ts

@@ -0,0 +1,31 @@
+/**
+ * PR Review orchestrator — thin wrapper around ReviewAgentRunner
+ * that handles context assembly and verdict extraction.
+ */
+import { ReviewAgentRunner, type ReviewType, type ReviewVerdict, type ReviewAgentConfig } from './runners/review-agent.js';
+import type { Logger } from './logger.js';
+export interface ReviewContext {
+    issueTitle: string;
+    issueBody: string;
+    acceptanceCriteria?: string;
+}
+export interface ReviewOptions {
+    /** Anthropic API config overrides. */
+    apiConfig?: Omit<ReviewAgentConfig, 'reviewType'>;
+    /** Logger for diagnostic output. */
+    logger?: Logger;
+    /** Inject runner for testing. */
+    runner?: ReviewAgentRunner;
+}
+/**
+ * Execute a single review agent against a PR diff.
+ *
+ * @param prNumber - PR number (for logging/identification)
+ * @param diff - The full PR diff text
+ * @param reviewType - Which review perspective (testing, critic, security)
+ * @param context - Issue context for the review
+ * @param options - Optional configuration overrides
+ * @returns Review verdict with findings
+ */
+export declare function executeReview(prNumber: number, diff: string, reviewType: ReviewType, context: ReviewContext, options?: ReviewOptions): Promise<ReviewVerdict>;
+//# sourceMappingURL=review.d.ts.map

package/dist/review.js

@@ -0,0 +1,74 @@
+/**
+ * PR Review orchestrator — thin wrapper around ReviewAgentRunner
+ * that handles context assembly and verdict extraction.
+ */
+import { ReviewAgentRunner, } from './runners/review-agent.js';
+// ── Public API ───────────────────────────────────────────────────────
+/**
+ * Execute a single review agent against a PR diff.
+ *
+ * @param prNumber - PR number (for logging/identification)
+ * @param diff - The full PR diff text
+ * @param reviewType - Which review perspective (testing, critic, security)
+ * @param context - Issue context for the review
+ * @param options - Optional configuration overrides
+ * @returns Review verdict with findings
+ */
+export async function executeReview(prNumber, diff, reviewType, context, options) {
+    const logger = options?.logger;
+    logger?.info?.(`Starting ${reviewType} review for PR #${prNumber}`);
+    const runner = options?.runner ??
+        new ReviewAgentRunner({
+            ...options?.apiConfig,
+            reviewType,
+        });
+    const result = await runner.run({
+        issueId: `PR-${prNumber}`,
+        issueNumber: prNumber,
+        issueTitle: context.issueTitle,
+        issueBody: diff,
+        workDir: '',
+        branch: '',
+        constraints: {
+            maxFilesPerChange: 0,
+            requireTests: false,
+            blockedPaths: [],
+        },
+        // Reuse ciErrors field for acceptance criteria
+        ciErrors: context.acceptanceCriteria,
+    });
+    if (!result.success) {
+        logger?.error?.(`${reviewType} review failed: ${result.error}`);
+        return {
+            type: reviewType,
+            approved: false,
+            findings: [
+                {
+                    severity: 'critical',
+                    message: `Review agent failed: ${result.error ?? 'unknown error'}`,
+                },
+            ],
+            summary: `${reviewType} review could not be completed`,
+        };
+    }
+    try {
+        const verdict = JSON.parse(result.summary);
+        logger?.info?.(`${reviewType} review complete: ${verdict.approved ? 'APPROVED' : 'CHANGES REQUESTED'} (${verdict.findings.length} findings)`);
+        return { ...verdict, type: reviewType };
+    }
+    catch {
+        logger?.error?.(`Failed to parse ${reviewType} verdict from runner output`);
+        return {
+            type: reviewType,
+            approved: false,
+            findings: [
+                {
+                    severity: 'critical',
+                    message: 'Failed to parse review verdict from runner output',
+                },
+            ],
+            summary: `${reviewType} review verdict was not valid JSON`,
+        };
+    }
+}
+//# sourceMappingURL=review.js.map