@ai-sdlc/orchestrator 0.1.0

package/dist/validate-agent-output.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Post-agent output validation — enforces guardrails before push.
+ *
+ * Pure validation module with no side effects (fully testable).
+ */
+export interface ValidationContext {
+    filesChanged: string[];
+    workDir: string;
+    constraints: {
+        maxFilesPerChange: number;
+        requireTests: boolean;
+        blockedPaths: string[];
+    };
+    guardrails: {
+        maxLinesPerPR?: number;
+    };
+}
+export interface ValidationViolation {
+    rule: string;
+    message: string;
+}
+export interface ValidationResult {
+    passed: boolean;
+    violations: ValidationViolation[];
+}
+/**
+ * Validate agent output against guardrails and constraints.
+ */
+export declare function validateAgentOutput(ctx: ValidationContext): Promise<ValidationResult>;
+//# sourceMappingURL=validate-agent-output.d.ts.map

package/dist/validate-agent-output.js

@@ -0,0 +1,81 @@
+/**
+ * Post-agent output validation — enforces guardrails before push.
+ *
+ * Pure validation module with no side effects (fully testable).
+ */
+import { execFile } from 'node:child_process';
+/**
+ * Match a file path against a blocked-path pattern.
+ * Supports simple glob suffixes: `foo/**` matches anything under `foo/`.
+ */
+function matchesBlockedPath(filePath, pattern) {
+    const base = pattern.replace(/\/?\*\*$/, '');
+    return filePath === base || filePath.startsWith(base.endsWith('/') ? base : `${base}/`);
+}
+/**
+ * Parse total changed lines from `git diff --stat` output.
+ * The last line looks like: ` 3 files changed, 40 insertions(+), 12 deletions(-)`
+ */
+function parseDiffStatLines(diffStat) {
+    const match = diffStat.match(/(\d+)\s+insertions?\(\+\)(?:,\s*(\d+)\s+deletions?\(-\))?/);
+    if (!match) {
+        // Try deletions-only format: `1 file changed, 5 deletions(-)`
+        const delOnly = diffStat.match(/(\d+)\s+deletions?\(-\)/);
+        return delOnly ? Number(delOnly[1]) : 0;
+    }
+    return Number(match[1]) + (match[2] ? Number(match[2]) : 0);
+}
+/**
+ * Validate agent output against guardrails and constraints.
+ */
+export async function validateAgentOutput(ctx) {
+    const violations = [];
+    // 1. Blocked paths
+    for (const file of ctx.filesChanged) {
+        for (const pattern of ctx.constraints.blockedPaths) {
+            if (matchesBlockedPath(file, pattern)) {
+                violations.push({
+                    rule: 'blocked-path',
+                    message: `File \`${file}\` matches blocked path \`${pattern}\``,
+                });
+            }
+        }
+    }
+    // 2. File count
+    if (ctx.filesChanged.length > ctx.constraints.maxFilesPerChange) {
+        violations.push({
+            rule: 'max-files',
+            message: `Changed ${ctx.filesChanged.length} files (max ${ctx.constraints.maxFilesPerChange})`,
+        });
+    }
+    // 3. Max lines per PR
+    if (ctx.guardrails.maxLinesPerPR !== undefined) {
+        const stdout = await new Promise((resolve, reject) => {
+            execFile('git', ['diff', '--stat', 'HEAD~1'], { cwd: ctx.workDir }, (err, out) => {
+                if (err)
+                    reject(err);
+                else
+                    resolve(out);
+            });
+        });
+        const totalLines = parseDiffStatLines(stdout);
+        if (totalLines > ctx.guardrails.maxLinesPerPR) {
+            violations.push({
+                rule: 'max-lines',
+                message: `Changed ${totalLines} lines (max ${ctx.guardrails.maxLinesPerPR})`,
+            });
+        }
+    }
+    // 4. Require tests
+    if (ctx.constraints.requireTests) {
+        const hasTestFile = ctx.filesChanged.some((f) => /\.test\./.test(f) || /\.spec\./.test(f));
+        if (!hasTestFile) {
+            violations.push({
+                rule: 'require-tests',
+                message: 'No test file found in changed files',
+            });
+        }
+    }
+    return { passed: violations.length === 0, violations };
+}
+//# sourceMappingURL=validate-agent-output.js.map

package/dist/validate-issue.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Validates a GitHub issue against quality gates using the reference
+ * implementation's enforcement engine, with optional expression and LLM
+ * evaluation extensions.
+ */
+import { enforce, type EnforcementResult, type QualityGate, type Issue, type ExpressionEvaluator, type LLMEvaluator } from '@ai-sdlc/reference';
+/**
+ * Validate an issue against the loaded QualityGate resource.
+ * An optional enforceFn can be provided (e.g. instrumented enforcement).
+ * Extra metrics (e.g. cost metrics) are merged into the evaluation context.
+ */
+export declare function validateIssue(issue: Issue, qualityGate: QualityGate, enforceFn?: typeof enforce, extraMetrics?: Record<string, number>): EnforcementResult;
+/**
+ * Extended validation that also evaluates expression and LLM gate rules.
+ */
+export declare function validateIssueWithExtensions(issue: Issue, qualityGate: QualityGate, options?: {
+    expressionEvaluator?: ExpressionEvaluator;
+    llmEvaluator?: LLMEvaluator;
+}): Promise<EnforcementResult>;
+/**
+ * Parse complexity from issue body (GitHub issue template format).
+ * Returns 0 if not found.
+ */
+export declare function parseComplexity(issueBody: string | undefined): number;
+//# sourceMappingURL=validate-issue.d.ts.map

package/dist/validate-issue.js

@@ -0,0 +1,102 @@
+/**
+ * Validates a GitHub issue against quality gates using the reference
+ * implementation's enforcement engine, with optional expression and LLM
+ * evaluation extensions.
+ */
+import { enforce, evaluateExpressionRule, evaluateLLMRule, } from '@ai-sdlc/reference';
+import { DEFAULT_GITHUB_REPOSITORY } from './defaults.js';
+/**
+ * Build an EvaluationContext from an issue, mapping issue metadata
+ * to the metrics expected by the quality gate rules.
+ */
+function buildEvaluationContext(issue) {
+    const hasDescription = issue.description ? issue.description.trim().length : 0;
+    const hasAcceptanceCriteria = issue.description
+        ? /## Acceptance Criteria/i.test(issue.description)
+            ? 1
+            : 0
+        : 0;
+    const complexityMatch = issue.description?.match(/### Complexity\s*\n+\s*(\d+)/i);
+    const complexity = complexityMatch ? Number(complexityMatch[1]) : 0;
+    return {
+        authorType: 'ai-agent',
+        repository: DEFAULT_GITHUB_REPOSITORY,
+        metrics: {
+            'description-length': hasDescription,
+            'has-acceptance-criteria': hasAcceptanceCriteria,
+            complexity,
+        },
+    };
+}
+/**
+ * Validate an issue against the loaded QualityGate resource.
+ * An optional enforceFn can be provided (e.g. instrumented enforcement).
+ * Extra metrics (e.g. cost metrics) are merged into the evaluation context.
+ */
+export function validateIssue(issue, qualityGate, enforceFn, extraMetrics) {
+    const ctx = buildEvaluationContext(issue);
+    if (extraMetrics) {
+        Object.assign(ctx.metrics, extraMetrics);
+    }
+    return (enforceFn ?? enforce)(qualityGate, ctx);
+}
+/**
+ * Extended validation that also evaluates expression and LLM gate rules.
+ */
+export async function validateIssueWithExtensions(issue, qualityGate, options) {
+    // Start with standard enforcement
+    const result = validateIssue(issue, qualityGate);
+    // Evaluate expression rules from quality gates
+    if (options?.expressionEvaluator) {
+        const ctx = buildEvaluationContext(issue);
+        for (const gate of qualityGate.spec.gates) {
+            if ('expression' in gate.rule) {
+                const verdict = evaluateExpressionRule(gate.rule, { ctx }, options.expressionEvaluator);
+                if (!verdict.passed) {
+                    result.allowed = false;
+                    result.results.push({
+                        gate: gate.name,
+                        verdict: 'fail',
+                        enforcement: gate.enforcement,
+                        message: verdict.message ??
+                            `Expression rule failed: ${gate.rule.expression}`,
+                    });
+                }
+            }
+        }
+    }
+    // Evaluate LLM rules on issue description
+    if (options?.llmEvaluator && issue.description) {
+        for (const gate of qualityGate.spec.gates) {
+            // Check for LLM evaluation rule pattern (has dimensions and thresholds)
+            const rule = gate.rule;
+            if ('dimensions' in rule && 'thresholds' in rule) {
+                const llmVerdict = await evaluateLLMRule(rule, issue.description, options.llmEvaluator);
+                if (!llmVerdict.passed) {
+                    result.allowed = false;
+                    const failureDetails = llmVerdict.failures
+                        .map((f) => `${f.dimension}: ${f.score.toFixed(2)} < ${f.threshold}`)
+                        .join(', ');
+                    result.results.push({
+                        gate: gate.name,
+                        verdict: 'fail',
+                        enforcement: gate.enforcement,
+                        message: `LLM evaluation failed: ${failureDetails}`,
+                    });
+                }
+            }
+        }
+    }
+    return result;
+}
+/**
+ * Parse complexity from issue body (GitHub issue template format).
+ * Returns 0 if not found.
+ */
+export function parseComplexity(issueBody) {
+    if (!issueBody)
+        return 0;
+    const match = issueBody.match(/### Complexity\s*\n+\s*(\d+)/i);
+    return match ? Number(match[1]) : 0;
+}
+//# sourceMappingURL=validate-issue.js.map

package/dist/watch.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Reconciler watch mode — wraps executePipeline in a continuous reconciliation loop.
+ *
+ * Uses ReconcilerLoop + createResourceCache from the reference implementation
+ * for level-triggered, idempotent reconciliation with backoff.
+ */
+import { type ReconcilerConfig, type ReconcileResult, type Pipeline, type QualityGate, type AutonomyPolicy, type AgentRole, type MetricStore } from '@ai-sdlc/reference';
+import { type ExecuteOptions } from './execute.js';
+export interface WatchOptions {
+    /** Override the reconciler config (poll interval, concurrency, backoff). */
+    reconcilerConfig?: Partial<ReconcilerConfig>;
+    /** Pipeline execution options passed through to executePipeline. */
+    executeOptions?: Omit<ExecuteOptions, 'configDir' | 'workDir'>;
+    /** Callback invoked when a pipeline reconciliation completes. */
+    onReconcile?: (pipelineName: string, result: ReconcileResult) => void;
+    /** Optional metric store to instrument reconciliation cycles. */
+    metricStore?: MetricStore;
+    /** Optional agent roles for pipeline reconciler agent resolution. */
+    agents?: Map<string, AgentRole>;
+    /** Optional quality gates for gate reconciler evaluation context. */
+    qualityGates?: QualityGate[];
+    /** Optional autonomy policies for autonomy reconciler evaluation. */
+    autonomyPolicies?: AutonomyPolicy[];
+}
+export interface WatchHandle {
+    /** Enqueue a pipeline resource for reconciliation. */
+    enqueue(pipeline: Pipeline, issueNumber: number): void;
+    /** Enqueue a quality gate resource for reconciliation. */
+    enqueueGate(gate: QualityGate): void;
+    /** Enqueue an autonomy policy resource for reconciliation. */
+    enqueueAutonomy(policy: AutonomyPolicy): void;
+    /** Stop the reconciliation loop. */
+    stop(): void;
+    /** Number of items in the queue. */
+    readonly queueSize: number;
+    /** Number of actively reconciling items. */
+    readonly activeCount: number;
+}
+/**
+ * Start a reconciler watch loop that continuously processes pipeline resources.
+ */
+export declare function startWatch(options?: WatchOptions): WatchHandle;
+//# sourceMappingURL=watch.d.ts.map

package/dist/watch.js

@@ -0,0 +1,99 @@
+/**
+ * Reconciler watch mode — wraps executePipeline in a continuous reconciliation loop.
+ *
+ * Uses ReconcilerLoop + createResourceCache from the reference implementation
+ * for level-triggered, idempotent reconciliation with backoff.
+ */
+import { ReconcilerLoop, createResourceCache, instrumentReconciler, } from '@ai-sdlc/reference';
+import { executePipeline } from './execute.js';
+import { createPipelineReconciler, createGateReconciler, createAutonomyReconciler, } from './reconcilers.js';
+/**
+ * Start a reconciler watch loop that continuously processes pipeline resources.
+ */
+export function startWatch(options = {}) {
+    const cache = createResourceCache();
+    const issueMap = new Map();
+    // H2: Build specialized reconcilers for each resource kind
+    const _pipelineReconciler = createPipelineReconciler({
+        resolveAgent: (name) => options.agents?.get(name),
+        taskFn: async () => ({}),
+    });
+    const gateReconciler = createGateReconciler({
+        getContext: (_gate) => ({ metrics: {}, repository: '', authorType: 'ai-agent' }),
+    });
+    const autonomyReconciler = createAutonomyReconciler({
+        getAgentMetrics: () => undefined,
+        getActiveTriggers: () => [],
+    });
+    // Composite reconciler dispatches by resource kind
+    let reconcileFn = async (resource) => {
+        switch (resource.kind) {
+            case 'Pipeline': {
+                const pipeline = resource;
+                const issueNumber = issueMap.get(pipeline.metadata.name);
+                if (!issueNumber) {
+                    return {
+                        type: 'error',
+                        error: new Error(`No issue number for pipeline ${pipeline.metadata.name}`),
+                    };
+                }
+                try {
+                    await executePipeline(issueNumber, {
+                        ...options.executeOptions,
+                    });
+                    const result = { type: 'success' };
+                    options.onReconcile?.(pipeline.metadata.name, result);
+                    return result;
+                }
+                catch (err) {
+                    const result = {
+                        type: 'error',
+                        error: err instanceof Error ? err : new Error(String(err)),
+                    };
+                    options.onReconcile?.(pipeline.metadata.name, result);
+                    return result;
+                }
+            }
+            case 'QualityGate':
+                return gateReconciler(resource);
+            case 'AutonomyPolicy':
+                return autonomyReconciler(resource);
+            default:
+                return { type: 'success' };
+        }
+    };
+    // Wrap with instrumentation if metric store is provided
+    if (options.metricStore) {
+        reconcileFn = instrumentReconciler(reconcileFn, { metricStore: options.metricStore });
+    }
+    const loop = new ReconcilerLoop(reconcileFn, options.reconcilerConfig);
+    loop.start();
+    return {
+        enqueue(pipeline, issueNumber) {
+            issueMap.set(pipeline.metadata.name, issueNumber);
+            if (cache.shouldReconcile(pipeline)) {
+                loop.enqueue(pipeline);
+            }
+        },
+        enqueueGate(gate) {
+            if (cache.shouldReconcile(gate)) {
+                loop.enqueue(gate);
+            }
+        },
+        enqueueAutonomy(policy) {
+            if (cache.shouldReconcile(policy)) {
+                loop.enqueue(policy);
+            }
+        },
+        stop() {
+            loop.stop();
+        },
+        get queueSize() {
+            return loop.queueSize;
+        },
+        get activeCount() {
+            return loop.activeCount;
+        },
+    };
+}
+//# sourceMappingURL=watch.js.map

package/dist/webhook-manager.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Webhook manager — creates and manages the webhook server,
+ * registers providers based on config, and handles lifecycle.
+ */
+import { type WebhookServer, type WebhookBridge, type IssueEvent, type PREvent, type BuildEvent } from '@ai-sdlc/reference';
+export interface WebhookManagerConfig {
+    /** Port to listen on for webhooks. */
+    port: number;
+    /** Host to bind to (defaults to '0.0.0.0'). */
+    host?: string;
+    /** GitHub webhook secret. */
+    githubSecret?: string;
+    /** GitLab webhook secret token. */
+    gitlabSecretToken?: string;
+    /** Jira webhook secret. */
+    jiraSecret?: string;
+    /** Linear webhook signing secret. */
+    linearSigningSecret?: string;
+}
+export interface WebhookBridges {
+    issues: WebhookBridge<IssueEvent>;
+    pullRequests: WebhookBridge<PREvent>;
+    builds: WebhookBridge<BuildEvent>;
+}
+export interface WebhookManager {
+    /** Start the webhook server. */
+    start(): Promise<void>;
+    /** Stop the webhook server. */
+    stop(): Promise<void>;
+    /** Get the configured bridges for event consumption. */
+    readonly bridges: WebhookBridges;
+    /** Get the underlying server. */
+    readonly server: WebhookServer;
+    /** Number of registered providers. */
+    readonly providerCount: number;
+}
+export declare function createWebhookManager(config: WebhookManagerConfig): WebhookManager;
+//# sourceMappingURL=webhook-manager.d.ts.map

package/dist/webhook-manager.js

@@ -0,0 +1,66 @@
+/**
+ * Webhook manager — creates and manages the webhook server,
+ * registers providers based on config, and handles lifecycle.
+ */
+import { createWebhookServer, createWebhookBridge, createGitHubWebhookProvider, createGitLabWebhookProvider, createJiraWebhookProvider, createLinearWebhookProvider, transformIssueEvent, transformPREvent, transformBuildEvent, transformGitLabIssueEvent, transformGitLabMREvent, transformGitLabPipelineEvent, transformJiraIssueEvent, transformLinearIssueEvent, } from '@ai-sdlc/reference';
+// ── Implementation ───────────────────────────────────────────────────
+export function createWebhookManager(config) {
+    const server = createWebhookServer({ port: config.port, host: config.host });
+    // Create unified bridges
+    const issueBridge = createWebhookBridge((payload) => {
+        // Try each transformer in order
+        return (transformIssueEvent(payload) ??
+            transformGitLabIssueEvent(payload) ??
+            transformJiraIssueEvent(payload) ??
+            transformLinearIssueEvent(payload));
+    });
+    const prBridge = createWebhookBridge((payload) => {
+        return transformPREvent(payload) ?? transformGitLabMREvent(payload);
+    });
+    const buildBridge = createWebhookBridge((payload) => {
+        return transformBuildEvent(payload) ?? transformGitLabPipelineEvent(payload);
+    });
+    const bridges = {
+        issues: issueBridge,
+        pullRequests: prBridge,
+        builds: buildBridge,
+    };
+    // Register providers based on config
+    if (config.githubSecret) {
+        const provider = createGitHubWebhookProvider({ secret: config.githubSecret }, { issues: issueBridge, pullRequests: prBridge, builds: buildBridge });
+        server.registerProvider(provider);
+    }
+    if (config.gitlabSecretToken) {
+        const provider = createGitLabWebhookProvider({ secretToken: config.gitlabSecretToken }, { issues: issueBridge, mergeRequests: prBridge, pipelines: buildBridge });
+        server.registerProvider(provider);
+    }
+    if (config.jiraSecret) {
+        const provider = createJiraWebhookProvider({ secret: config.jiraSecret }, { issues: issueBridge });
+        server.registerProvider(provider);
+    }
+    if (config.linearSigningSecret) {
+        const provider = createLinearWebhookProvider({ signingSecret: config.linearSigningSecret }, { issues: issueBridge });
+        server.registerProvider(provider);
+    }
+    return {
+        async start() {
+            await server.start();
+        },
+        async stop() {
+            issueBridge.close();
+            prBridge.close();
+            buildBridge.close();
+            await server.stop();
+        },
+        get bridges() {
+            return bridges;
+        },
+        get server() {
+            return server;
+        },
+        get providerCount() {
+            return server.providerCount;
+        },
+    };
+}
+//# sourceMappingURL=webhook-manager.js.map

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@ai-sdlc/orchestrator",
+  "version": "0.1.0",
+  "description": "AI-SDLC Orchestrator — long-running runtime that drives issues through the complete SDLC with AI agents",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ai-sdlc-framework/ai-sdlc.git",
+    "directory": "orchestrator"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "files": ["dist", "!dist/**/*.test.*", "!dist/**/*.map"],
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "ai-sdlc": "dist/cli/index.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./runners": {
+      "types": "./dist/runners/index.d.ts",
+      "import": "./dist/runners/index.js"
+    },
+    "./state": {
+      "types": "./dist/state/index.d.ts",
+      "import": "./dist/state/index.js"
+    },
+    "./cli": {
+      "types": "./dist/cli/index.d.ts",
+      "import": "./dist/cli/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "clean": "rm -rf dist *.tsbuildinfo",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "dependencies": {
+    "@ai-sdlc/reference": "workspace:*",
+    "better-sqlite3": "^11.0.0",
+    "commander": "^12.0.0",
+    "yaml": "^2.7.0"
+  },
+  "devDependencies": {
+    "@types/better-sqlite3": "^7.6.0",
+    "@types/node": "^22.0.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.7.0",
+    "vitest": "^3.0.0"
+  }
+}