@ai-sdlc/orchestrator 0.1.0

package/dist/process-escalation.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Process escalation — detects complexity band transitions and
+ * returns escalation actions to tighten or relax the pipeline.
+ *
+ * RFC reference: progressive process adaptation.
+ */
+import type { Gate } from '@ai-sdlc/reference';
+import type { ComplexityBand } from './defaults.js';
+export type EscalationActionType = 'add-gate' | 'remove-gate' | 'tighten-gate' | 'relax-gate' | 'require-review' | 'remove-review-requirement' | 'notify';
+export interface EscalationAction {
+    type: EscalationActionType;
+    gateName?: string;
+    reason: string;
+    fromBand: ComplexityBand;
+    toBand: ComplexityBand;
+    details?: Record<string, unknown>;
+}
+export interface EscalationResult {
+    escalated: boolean;
+    fromBand: ComplexityBand;
+    toBand: ComplexityBand;
+    actions: EscalationAction[];
+}
+/**
+ * Evaluate whether a complexity score change triggers process escalation.
+ * Returns a list of escalation actions when the band changes.
+ */
+export declare function evaluateProcessEscalation(prevScore: number, curScore: number, gates: Gate[]): EscalationResult;
+/**
+ * Check if a band transition represents a significant escalation
+ * (jumping 2+ bands).
+ */
+export declare function isSignificantEscalation(fromBand: ComplexityBand, toBand: ComplexityBand): boolean;
+/**
+ * Get escalation summary for logging/notification.
+ */
+export declare function formatEscalationSummary(result: EscalationResult): string;
+//# sourceMappingURL=process-escalation.d.ts.map

package/dist/process-escalation.js

@@ -0,0 +1,129 @@
+/**
+ * Process escalation — detects complexity band transitions and
+ * returns escalation actions to tighten or relax the pipeline.
+ *
+ * RFC reference: progressive process adaptation.
+ */
+import { getComplexityBand } from './progressive-gates.js';
+/**
+ * Band ordering for comparison.
+ */
+function bandOrd(band) {
+    switch (band) {
+        case 'trivial':
+            return 0;
+        case 'standard':
+            return 1;
+        case 'complex':
+            return 2;
+        case 'critical':
+            return 3;
+        default:
+            return 1;
+    }
+}
+/**
+ * Evaluate whether a complexity score change triggers process escalation.
+ * Returns a list of escalation actions when the band changes.
+ */
+export function evaluateProcessEscalation(prevScore, curScore, gates) {
+    const fromBand = getComplexityBand(prevScore);
+    const toBand = getComplexityBand(curScore);
+    if (fromBand === toBand) {
+        return { escalated: false, fromBand, toBand, actions: [] };
+    }
+    const fromOrd = bandOrd(fromBand);
+    const toOrd = bandOrd(toBand);
+    const escalating = toOrd > fromOrd;
+    const actions = [];
+    if (escalating) {
+        // Complexity increased — tighten process
+        actions.push({
+            type: 'notify',
+            reason: `Complexity band escalated from ${fromBand} to ${toBand}`,
+            fromBand,
+            toBand,
+        });
+        // Tighten all existing gates
+        for (const gate of gates) {
+            actions.push({
+                type: 'tighten-gate',
+                gateName: gate.name,
+                reason: `Gate enforcement tightened due to band change ${fromBand} -> ${toBand}`,
+                fromBand,
+                toBand,
+            });
+        }
+        // Add review requirement if moving to complex or critical
+        if (toOrd >= 2) {
+            actions.push({
+                type: 'require-review',
+                reason: `Review required for ${toBand} complexity band`,
+                fromBand,
+                toBand,
+            });
+        }
+        // Add security gate if moving to complex or critical and none exists
+        if (toOrd >= 2 && !gates.some((g) => g.name.toLowerCase().includes('security'))) {
+            actions.push({
+                type: 'add-gate',
+                gateName: 'security-scan',
+                reason: `Security scan required for ${toBand} complexity band`,
+                fromBand,
+                toBand,
+                details: { enforcement: 'hard-mandatory' },
+            });
+        }
+    }
+    else {
+        // Complexity decreased — relax process
+        actions.push({
+            type: 'notify',
+            reason: `Complexity band de-escalated from ${fromBand} to ${toBand}`,
+            fromBand,
+            toBand,
+        });
+        // Relax all existing gates
+        for (const gate of gates) {
+            actions.push({
+                type: 'relax-gate',
+                gateName: gate.name,
+                reason: `Gate enforcement relaxed due to band change ${fromBand} -> ${toBand}`,
+                fromBand,
+                toBand,
+            });
+        }
+        // Remove review requirement if moving to trivial
+        if (toOrd === 0) {
+            actions.push({
+                type: 'remove-review-requirement',
+                reason: 'Review not required for trivial complexity band',
+                fromBand,
+                toBand,
+            });
+        }
+    }
+    return { escalated: true, fromBand, toBand, actions };
+}
+/**
+ * Check if a band transition represents a significant escalation
+ * (jumping 2+ bands).
+ */
+export function isSignificantEscalation(fromBand, toBand) {
+    return Math.abs(bandOrd(toBand) - bandOrd(fromBand)) >= 2;
+}
+/**
+ * Get escalation summary for logging/notification.
+ */
+export function formatEscalationSummary(result) {
+    if (!result.escalated) {
+        return `No escalation: band remains ${result.fromBand}`;
+    }
+    const direction = bandOrd(result.toBand) > bandOrd(result.fromBand) ? 'escalated' : 'de-escalated';
+    const actionSummary = result.actions
+        .filter((a) => a.type !== 'notify')
+        .map((a) => `${a.type}${a.gateName ? ` (${a.gateName})` : ''}`)
+        .join(', ');
+    return `Process ${direction}: ${result.fromBand} -> ${result.toBand}. Actions: ${actionSummary || 'none'}`;
+}
+//# sourceMappingURL=process-escalation.js.map

package/dist/progressive-gates.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Progressive gate adjustment — adapts gate enforcement and thresholds
+ * based on codebase complexity score.
+ *
+ * RFC reference: Lines 217-228 (progressive gate matrix).
+ */
+import type { Gate, EnforcementLevel } from '@ai-sdlc/reference';
+import { type ComplexityBand, type GateProfile } from './defaults.js';
+import type { StateStore } from './state/store.js';
+import type { GateThresholdOverride } from './state/types.js';
+export interface AdjustedGate extends Gate {
+    originalEnforcement: EnforcementLevel;
+    complexityBand: ComplexityBand;
+    adjustedThresholds?: Record<string, unknown>;
+}
+export interface GateAdjustment {
+    gateName: string;
+    originalEnforcement: EnforcementLevel;
+    adjustedEnforcement: EnforcementLevel;
+    band: ComplexityBand;
+    thresholdChanges: Record<string, unknown>;
+}
+/**
+ * Determine the complexity band for a given score (1-10).
+ */
+export declare function getComplexityBand(score: number): ComplexityBand;
+/**
+ * Get the gate profile for a given complexity score.
+ */
+export declare function getGateProfile(score: number): GateProfile;
+/**
+ * Determine the adjusted enforcement level for a gate given a complexity band.
+ * Rules:
+ * - Trivial band: enforcement can be relaxed (hard-mandatory -> soft-mandatory, soft-mandatory -> advisory)
+ * - Standard band: no change
+ * - Complex/critical bands: enforcement is tightened (advisory -> soft-mandatory, soft-mandatory -> hard-mandatory)
+ */
+export declare function adjustEnforcement(original: EnforcementLevel, band: ComplexityBand): EnforcementLevel;
+/**
+ * Adjust a single gate for the given complexity score.
+ * Applies profile-based enforcement adjustment and threshold overrides.
+ */
+export declare function adjustGateForComplexity(score: number, gate: Gate, overrides?: GateThresholdOverride[]): AdjustedGate;
+/**
+ * Adjust all gates for the given complexity score.
+ * Optionally loads overrides from the state store.
+ */
+export declare function adjustGatesForComplexity(score: number, gates: Gate[], store?: StateStore): AdjustedGate[];
+/**
+ * Compute the set of adjustments that would be made to gates.
+ * Useful for reporting/logging without mutating.
+ */
+export declare function computeGateAdjustments(score: number, gates: Gate[]): GateAdjustment[];
+//# sourceMappingURL=progressive-gates.d.ts.map

package/dist/progressive-gates.js

@@ -0,0 +1,135 @@
+/**
+ * Progressive gate adjustment — adapts gate enforcement and thresholds
+ * based on codebase complexity score.
+ *
+ * RFC reference: Lines 217-228 (progressive gate matrix).
+ */
+import { PROGRESSIVE_GATE_PROFILES } from './defaults.js';
+/**
+ * Determine the complexity band for a given score (1-10).
+ */
+export function getComplexityBand(score) {
+    const clamped = Math.max(1, Math.min(10, Math.round(score)));
+    for (const profile of PROGRESSIVE_GATE_PROFILES) {
+        if (clamped >= profile.minScore && clamped <= profile.maxScore) {
+            return profile.band;
+        }
+    }
+    return 'standard';
+}
+/**
+ * Get the gate profile for a given complexity score.
+ */
+export function getGateProfile(score) {
+    const band = getComplexityBand(score);
+    return PROGRESSIVE_GATE_PROFILES.find((p) => p.band === band) ?? PROGRESSIVE_GATE_PROFILES[1];
+}
+/**
+ * Map an enforcement level string to an ordered numeric value for comparison.
+ */
+function enforcementOrd(level) {
+    switch (level) {
+        case 'advisory':
+            return 0;
+        case 'soft-mandatory':
+            return 1;
+        case 'hard-mandatory':
+            return 2;
+        default:
+            return 1;
+    }
+}
+/**
+ * Determine the adjusted enforcement level for a gate given a complexity band.
+ * Rules:
+ * - Trivial band: enforcement can be relaxed (hard-mandatory -> soft-mandatory, soft-mandatory -> advisory)
+ * - Standard band: no change
+ * - Complex/critical bands: enforcement is tightened (advisory -> soft-mandatory, soft-mandatory -> hard-mandatory)
+ */
+export function adjustEnforcement(original, band) {
+    const ord = enforcementOrd(original);
+    switch (band) {
+        case 'trivial': {
+            // Relax by one level, floor at advisory
+            const newOrd = Math.max(0, ord - 1);
+            return ['advisory', 'soft-mandatory', 'hard-mandatory'][newOrd];
+        }
+        case 'standard':
+            return original;
+        case 'complex':
+        case 'critical': {
+            // Tighten by one level, cap at hard-mandatory
+            const newOrd = Math.min(2, ord + 1);
+            return ['advisory', 'soft-mandatory', 'hard-mandatory'][newOrd];
+        }
+        default:
+            return original;
+    }
+}
+/**
+ * Build threshold adjustments for a gate based on the profile.
+ */
+function buildThresholdAdjustments(profile) {
+    return {
+        testCoverageThreshold: profile.testCoverageThreshold,
+        reviewRequired: profile.reviewRequired,
+        securityScanRequired: profile.securityScanRequired,
+        documentationRequired: profile.documentationRequired,
+    };
+}
+/**
+ * Adjust a single gate for the given complexity score.
+ * Applies profile-based enforcement adjustment and threshold overrides.
+ */
+export function adjustGateForComplexity(score, gate, overrides) {
+    const profile = getGateProfile(score);
+    const band = profile.band;
+    // Check for DB override first
+    const override = overrides?.find((o) => o.gateName === gate.name && o.complexityBand === band);
+    let adjustedEnforcement;
+    let adjustedThresholds;
+    if (override) {
+        adjustedEnforcement = override.enforcementLevel;
+        adjustedThresholds = override.thresholdOverrides
+            ? JSON.parse(override.thresholdOverrides)
+            : buildThresholdAdjustments(profile);
+    }
+    else {
+        adjustedEnforcement = adjustEnforcement(gate.enforcement, band);
+        adjustedThresholds = buildThresholdAdjustments(profile);
+    }
+    return {
+        ...gate,
+        enforcement: adjustedEnforcement,
+        originalEnforcement: gate.enforcement,
+        complexityBand: band,
+        adjustedThresholds,
+    };
+}
+/**
+ * Adjust all gates for the given complexity score.
+ * Optionally loads overrides from the state store.
+ */
+export function adjustGatesForComplexity(score, gates, store) {
+    const band = getComplexityBand(score);
+    const overrides = store?.getGateThresholdOverrides(undefined, band);
+    return gates.map((gate) => adjustGateForComplexity(score, gate, overrides));
+}
+/**
+ * Compute the set of adjustments that would be made to gates.
+ * Useful for reporting/logging without mutating.
+ */
+export function computeGateAdjustments(score, gates) {
+    const profile = getGateProfile(score);
+    return gates.map((gate) => {
+        const adjusted = adjustEnforcement(gate.enforcement, profile.band);
+        return {
+            gateName: gate.name,
+            originalEnforcement: gate.enforcement,
+            adjustedEnforcement: adjusted,
+            band: profile.band,
+            thresholdChanges: buildThresholdAdjustments(profile),
+        };
+    });
+}
+//# sourceMappingURL=progressive-gates.js.map

package/dist/provenance.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Provenance tracking module — creates, validates, and serializes
+ * provenance records for AI-generated changes (PRD Section 14.3).
+ */
+import { provenanceToAnnotations, provenanceFromAnnotations, PROVENANCE_ANNOTATION_PREFIX, type ProvenanceRecord, type ReviewDecision, type CostReceipt } from '@ai-sdlc/reference';
+/**
+ * Create a provenance record for a pipeline execution.
+ */
+export declare function createPipelineProvenance(opts: {
+    model?: string;
+    tool?: string;
+    promptText?: string;
+    humanReviewer?: string;
+    cost?: CostReceipt;
+}): ProvenanceRecord;
+/**
+ * Generate a provenance block for inclusion in PR descriptions.
+ */
+export declare function attachProvenanceToPR(provenance: ProvenanceRecord): string;
+/**
+ * Validate a provenance record for completeness.
+ */
+export declare function validatePipelineProvenance(provenance: Partial<ProvenanceRecord>): {
+    valid: boolean;
+    missing: string[];
+};
+export { provenanceToAnnotations, provenanceFromAnnotations, PROVENANCE_ANNOTATION_PREFIX };
+export type { ProvenanceRecord, ReviewDecision };
+//# sourceMappingURL=provenance.d.ts.map

package/dist/provenance.js

@@ -0,0 +1,61 @@
+/**
+ * Provenance tracking module — creates, validates, and serializes
+ * provenance records for AI-generated changes (PRD Section 14.3).
+ */
+import { createProvenance, provenanceToAnnotations, provenanceFromAnnotations, validateProvenance, PROVENANCE_ANNOTATION_PREFIX, } from '@ai-sdlc/reference';
+import { createHash } from 'node:crypto';
+import { DEFAULT_MODEL } from './defaults.js';
+/**
+ * Create a provenance record for a pipeline execution.
+ */
+export function createPipelineProvenance(opts) {
+    const promptHash = opts.promptText
+        ? createHash('sha256').update(opts.promptText).digest('hex').slice(0, 16)
+        : 'no-prompt';
+    return createProvenance({
+        model: opts.model ?? DEFAULT_MODEL,
+        tool: opts.tool ?? 'claude-code',
+        promptHash,
+        humanReviewer: opts.humanReviewer,
+        cost: opts.cost,
+    });
+}
+/**
+ * Generate a provenance block for inclusion in PR descriptions.
+ */
+export function attachProvenanceToPR(provenance) {
+    const annotations = provenanceToAnnotations(provenance);
+    const lines = [
+        '## Provenance',
+        '',
+        `- **Model**: ${provenance.model}`,
+        `- **Tool**: ${provenance.tool}`,
+        `- **Prompt Hash**: \`${provenance.promptHash}\``,
+        `- **Timestamp**: ${provenance.timestamp}`,
+        `- **Review Status**: ${provenance.reviewDecision}`,
+    ];
+    if (provenance.humanReviewer) {
+        lines.push(`- **Reviewer**: ${provenance.humanReviewer}`);
+    }
+    if (provenance.cost) {
+        const exec = provenance.cost.execution;
+        const costLine = exec
+            ? `- **Cost**: $${provenance.cost.totalCost.toFixed(4)} (${exec.inputTokens.toLocaleString()} in / ${exec.outputTokens.toLocaleString()} out)`
+            : `- **Cost**: $${provenance.cost.totalCost.toFixed(4)}`;
+        lines.push(costLine);
+    }
+    lines.push('', '<!-- provenance-annotations');
+    for (const [key, value] of Object.entries(annotations)) {
+        lines.push(`${key}: ${value}`);
+    }
+    lines.push('-->');
+    return lines.join('\n');
+}
+/**
+ * Validate a provenance record for completeness.
+ */
+export function validatePipelineProvenance(provenance) {
+    return validateProvenance(provenance);
+}
+export { provenanceToAnnotations, provenanceFromAnnotations, PROVENANCE_ANNOTATION_PREFIX };
+//# sourceMappingURL=provenance.js.map

package/dist/reconcilers.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Specialized reconciler integration — wraps pipeline/gate/autonomy reconcilers
+ * and diff utilities for smarter reconciliation in watch mode.
+ */
+import { createPipelineReconciler as _createPipelineReconciler, createGateReconciler as _createGateReconciler, createAutonomyReconciler as _createAutonomyReconciler, resourceFingerprint, hasSpecChanged, calculateBackoff, reconcileOnce, createResourceCache, DEFAULT_RECONCILER_CONFIG, type ReconcilerFn, type ReconcilerConfig, type ReconcileResult, type ResourceCache, type AnyResource, type Pipeline, type QualityGate, type AutonomyPolicy, type PipelineReconcilerDeps, type GateReconcilerDeps, type AutonomyReconcilerDeps } from '@ai-sdlc/reference';
+/**
+ * Create a pipeline reconciler that watches for pipeline resource changes.
+ */
+export declare function createPipelineReconciler(deps: PipelineReconcilerDeps): ReconcilerFn<Pipeline>;
+/**
+ * Create a gate reconciler that re-evaluates quality gates when they change.
+ */
+export declare function createGateReconciler(deps: GateReconcilerDeps): ReconcilerFn<QualityGate>;
+/**
+ * Create an autonomy reconciler that checks for promotion/demotion.
+ */
+export declare function createAutonomyReconciler(deps: AutonomyReconcilerDeps): ReconcilerFn<AutonomyPolicy>;
+/**
+ * Check if a resource's spec has changed since a previous version.
+ */
+export declare function hasResourceChanged(previous: AnyResource, current: AnyResource): boolean;
+/**
+ * Generate a fingerprint for a resource (used for change detection).
+ */
+export declare function fingerprintResource(resource: AnyResource): string;
+export { _createPipelineReconciler as createRefPipelineReconciler, _createGateReconciler as createRefGateReconciler, _createAutonomyReconciler as createRefAutonomyReconciler, resourceFingerprint, hasSpecChanged, calculateBackoff, reconcileOnce, createResourceCache, DEFAULT_RECONCILER_CONFIG, };
+export type { ReconcilerFn, ReconcilerConfig, ReconcileResult, ResourceCache, PipelineReconcilerDeps, GateReconcilerDeps, AutonomyReconcilerDeps, };
+//# sourceMappingURL=reconcilers.d.ts.map

package/dist/reconcilers.js

@@ -0,0 +1,37 @@
+/**
+ * Specialized reconciler integration — wraps pipeline/gate/autonomy reconcilers
+ * and diff utilities for smarter reconciliation in watch mode.
+ */
+import { createPipelineReconciler as _createPipelineReconciler, createGateReconciler as _createGateReconciler, createAutonomyReconciler as _createAutonomyReconciler, resourceFingerprint, hasSpecChanged, calculateBackoff, reconcileOnce, createResourceCache, DEFAULT_RECONCILER_CONFIG, } from '@ai-sdlc/reference';
+/**
+ * Create a pipeline reconciler that watches for pipeline resource changes.
+ */
+export function createPipelineReconciler(deps) {
+    return _createPipelineReconciler(deps);
+}
+/**
+ * Create a gate reconciler that re-evaluates quality gates when they change.
+ */
+export function createGateReconciler(deps) {
+    return _createGateReconciler(deps);
+}
+/**
+ * Create an autonomy reconciler that checks for promotion/demotion.
+ */
+export function createAutonomyReconciler(deps) {
+    return _createAutonomyReconciler(deps);
+}
+/**
+ * Check if a resource's spec has changed since a previous version.
+ */
+export function hasResourceChanged(previous, current) {
+    return hasSpecChanged(previous, current);
+}
+/**
+ * Generate a fingerprint for a resource (used for change detection).
+ */
+export function fingerprintResource(resource) {
+    return resourceFingerprint(resource);
+}
+export { _createPipelineReconciler as createRefPipelineReconciler, _createGateReconciler as createRefGateReconciler, _createAutonomyReconciler as createRefAutonomyReconciler, resourceFingerprint, hasSpecChanged, calculateBackoff, reconcileOnce, createResourceCache, DEFAULT_RECONCILER_CONFIG, };
+//# sourceMappingURL=reconcilers.js.map

package/dist/runners/claude-code.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Claude Code runner — invokes Claude Code CLI in --print mode
+ * and collects the result via git diff.
+ */
+import type { AgentRunner, AgentContext, AgentResult, TokenUsage } from './types.js';
+export declare function buildPrompt(ctx: AgentContext): string;
+/**
+ * Parse token usage from Claude CLI stderr output.
+ * Claude Code CLI outputs token info to stderr in various formats.
+ */
+export declare function parseTokenUsage(stderr: string, model: string): TokenUsage | undefined;
+export declare class ClaudeCodeRunner implements AgentRunner {
+    run(ctx: AgentContext): Promise<AgentResult>;
+}
+/** @deprecated Use ClaudeCodeRunner instead */
+export declare const GitHubActionsRunner: typeof ClaudeCodeRunner;
+//# sourceMappingURL=claude-code.d.ts.map