@substrate-ai/sdlc 0.19.54

package/dist/learning/findings-injector.js

@@ -0,0 +1,140 @@
+/**
+ * FindingsInjector — relevance-scored learning findings injector.
+ *
+ * Story 53-6: Findings Injector with Relevance Scoring
+ *
+ * Queries structured findings from the decisions table, scores each finding
+ * against an injection context, applies threshold/saturation guards, and
+ * serializes the top-ranked findings with budget enforcement.
+ */
+import { getDecisionsByCategory, LEARNING_FINDING } from '@substrate-ai/core';
+import { FindingSchema } from './types.js';
+import { scoreRelevance } from './relevance-scorer.js';
+import { FindingLifecycleManager } from './finding-lifecycle.js';
+// ---------------------------------------------------------------------------
+// FindingsInjector
+// ---------------------------------------------------------------------------
+export class FindingsInjector {
+    /**
+     * Query relevance-scored findings from the decisions table and serialize
+     * them as a prompt-injection string within the given character budget.
+     *
+     * Returns '' if no findings survive filtering or on any DB error.
+     */
+    static async inject(db, context, config) {
+        // Resolve config defaults
+        const threshold = config?.threshold ?? 0.3;
+        const maxChars = config?.maxChars ?? 2000;
+        const saturationLimit = config?.saturationLimit ?? 10;
+        // Query decisions table for LEARNING_FINDING rows
+        let rows;
+        try {
+            rows = await getDecisionsByCategory(db, LEARNING_FINDING);
+        }
+        catch {
+            return '';
+        }
+        // Parse valid findings; skip malformed rows silently
+        const validFindings = [];
+        for (const row of rows) {
+            try {
+                const parsed = JSON.parse(row.value);
+                const result = FindingSchema.safeParse(parsed);
+                if (!result.success)
+                    continue;
+                validFindings.push(result.data);
+            }
+            catch {
+                // Malformed JSON — skip this row
+                continue;
+            }
+        }
+        // === Story 53-7: Lifecycle preprocessing ===
+        // Step 3a: Deduplicate by root_cause + files fingerprint
+        let candidates = FindingLifecycleManager.deduplicate(validFindings);
+        // Step 3b: Exclude tombstoned (contradicted/archived) findings
+        candidates = candidates.filter((f) => f.contradicted_by === undefined);
+        // Step 3c: File existence validation (demote if missing)
+        const projectRoot = process.cwd();
+        candidates = candidates.map((f) => {
+            try {
+                return FindingLifecycleManager.validateFiles(f, projectRoot);
+            }
+            catch {
+                return f;
+            }
+        });
+        // Step 3d: Expiry check — archive and exclude expired findings
+        const survivingCandidates = [];
+        for (const f of candidates) {
+            try {
+                const runCount = await FindingLifecycleManager.countRunsSinceCreation(f, db);
+                if (FindingLifecycleManager.isExpired(f, runCount)) {
+                    await FindingLifecycleManager.archiveFinding(f, context.runId, db);
+                    continue; // excluded from injection
+                }
+            }
+            catch {
+                // Non-fatal: include the finding
+            }
+            survivingCandidates.push(f);
+        }
+        const scoredInput = survivingCandidates;
+        // === End lifecycle preprocessing ===
+        // Score surviving candidates
+        const scored = scoredInput.map((f) => ({
+            finding: f,
+            score: scoreRelevance(f, context),
+        }));
+        // Initial threshold filter
+        let dynamicThreshold = threshold;
+        let filtered = scored.filter(({ score }) => score >= dynamicThreshold);
+        // Saturation guard: raise threshold in 0.1 increments until ≤ saturationLimit remain
+        while (filtered.length > saturationLimit && dynamicThreshold <= 1.0) {
+            dynamicThreshold = Math.round((dynamicThreshold + 0.1) * 10) / 10;
+            filtered = scored.filter(({ score }) => score >= dynamicThreshold);
+        }
+        // If still over limit after threshold > 1.0, take top saturationLimit by score
+        if (filtered.length > saturationLimit) {
+            filtered = filtered.sort((a, b) => b.score - a.score).slice(0, saturationLimit);
+        }
+        // Sort by score descending
+        filtered.sort((a, b) => b.score - a.score);
+        // Serialize with maxChars budget enforcement
+        const prefix = 'Prior run findings (most relevant first):\n\n';
+        const lines = [];
+        let usedChars = prefix.length;
+        for (const { finding } of filtered) {
+            const line = finding.confidence === 'high'
+                ? `[${finding.root_cause}] Directive: ${finding.description}`
+                : `[${finding.root_cause}] Note (low confidence): ${finding.description}`;
+            // Separator: '\n' between lines (not before the first)
+            const addedLen = lines.length === 0 ? line.length : 1 + line.length;
+            if (usedChars + addedLen > maxChars)
+                break;
+            lines.push(line);
+            usedChars += addedLen;
+        }
+        if (lines.length === 0)
+            return '';
+        return prefix + lines.join('\n');
+    }
+}
+// ---------------------------------------------------------------------------
+// extractTargetFilesFromStoryContent
+// ---------------------------------------------------------------------------
+/**
+ * Extract file paths referenced in a story document for use as targetFiles
+ * in relevance scoring.
+ *
+ * Matches paths starting with `packages/` or `src/` with common code extensions.
+ * Returns up to 30 unique paths.
+ */
+export function extractTargetFilesFromStoryContent(storyContent) {
+    // Note: 'json' must appear before 'js' to prevent '.js' from matching '.json' files
+    const pattern = /(?:packages\/|src\/)[\w/.~-]+\.(?:ts|json|js|md)/g;
+    const matches = storyContent.match(pattern) ?? [];
+    const unique = [...new Set(matches)];
+    return unique.slice(0, 30);
+}
+//# sourceMappingURL=findings-injector.js.map

package/dist/learning/findings-injector.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"findings-injector.js","sourceRoot":"","sources":["../../src/learning/findings-injector.ts"],"names":[],"mappings":"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"}

package/dist/learning/index.d.ts

@@ -0,0 +1,8 @@
+export * from './types.js';
+export * from './failure-classifier.js';
+export * from './finding-store.js';
+export * from './finding-classifier.js';
+export * from './relevance-scorer.js';
+export * from './findings-injector.js';
+export * from './finding-lifecycle.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/learning/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/learning/index.ts"],"names":[],"mappings":"AACA,cAAc,YAAY,CAAA;AAC1B,cAAc,yBAAyB,CAAA;AACvC,cAAc,oBAAoB,CAAA;AAClC,cAAc,yBAAyB,CAAA;AACvC,cAAc,uBAAuB,CAAA;AACrC,cAAc,wBAAwB,CAAA;AAEtC,cAAc,wBAAwB,CAAA"}

package/dist/learning/index.js

@@ -0,0 +1,10 @@
+// Story 53-5: Learning loop — root cause taxonomy and failure classification
+export * from './types.js';
+export * from './failure-classifier.js';
+export * from './finding-store.js';
+export * from './finding-classifier.js';
+export * from './relevance-scorer.js';
+export * from './findings-injector.js';
+// Story 53-7: Finding lifecycle — validation, deduplication, expiry, retirement
+export * from './finding-lifecycle.js';
+//# sourceMappingURL=index.js.map

package/dist/learning/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/learning/index.ts"],"names":[],"mappings":"AAAA,6EAA6E;AAC7E,cAAc,YAAY,CAAA;AAC1B,cAAc,yBAAyB,CAAA;AACvC,cAAc,oBAAoB,CAAA;AAClC,cAAc,yBAAyB,CAAA;AACvC,cAAc,uBAAuB,CAAA;AACrC,cAAc,wBAAwB,CAAA;AACtC,gFAAgF;AAChF,cAAc,wBAAwB,CAAA"}

package/dist/learning/relevance-scorer.d.ts

@@ -0,0 +1,25 @@
+/**
+ * RelevanceScorer — deterministic relevance scoring for learning findings.
+ *
+ * Story 53-6: Findings Injector with Relevance Scoring
+ *
+ * Computes a [0, 1] relevance score for a Finding relative to an injection
+ * context using a three-component weighted formula:
+ *   0.5 * jaccardFileOverlap + 0.3 * packageMatch + 0.2 * rootCauseMatch
+ */
+import type { Finding, RootCauseCategory } from './types.js';
+export interface InjectionContext {
+    storyKey: string;
+    runId: string;
+    targetFiles?: string[];
+    packageName?: string;
+    riskProfile?: RootCauseCategory[];
+}
+/**
+ * Score the relevance of a Finding to the given InjectionContext.
+ *
+ * @returns A number in [0, 1] computed as:
+ *   0.5 * jaccardFileOverlap + 0.3 * packageMatch + 0.2 * rootCauseMatch
+ */
+export declare function scoreRelevance(finding: Finding, context: InjectionContext): number;
+//# sourceMappingURL=relevance-scorer.d.ts.map

package/dist/learning/relevance-scorer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"relevance-scorer.d.ts","sourceRoot":"","sources":["../../src/learning/relevance-scorer.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAA;AAM5D,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,MAAM,CAAA;IAChB,KAAK,EAAE,MAAM,CAAA;IACb,WAAW,CAAC,EAAE,MAAM,EAAE,CAAA;IACtB,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,WAAW,CAAC,EAAE,iBAAiB,EAAE,CAAA;CAClC;AAMD;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,gBAAgB,GAAG,MAAM,CAmClF"}

package/dist/learning/relevance-scorer.js

@@ -0,0 +1,49 @@
+/**
+ * RelevanceScorer — deterministic relevance scoring for learning findings.
+ *
+ * Story 53-6: Findings Injector with Relevance Scoring
+ *
+ * Computes a [0, 1] relevance score for a Finding relative to an injection
+ * context using a three-component weighted formula:
+ *   0.5 * jaccardFileOverlap + 0.3 * packageMatch + 0.2 * rootCauseMatch
+ */
+// ---------------------------------------------------------------------------
+// scoreRelevance — pure synchronous relevance scoring
+// ---------------------------------------------------------------------------
+/**
+ * Score the relevance of a Finding to the given InjectionContext.
+ *
+ * @returns A number in [0, 1] computed as:
+ *   0.5 * jaccardFileOverlap + 0.3 * packageMatch + 0.2 * rootCauseMatch
+ */
+export function scoreRelevance(finding, context) {
+    // --- Jaccard file overlap ---
+    // Cap target files to the 20 shortest paths (sorted ascending by length)
+    const cappedTargets = (context.targetFiles ?? [])
+        .sort((a, b) => a.length - b.length)
+        .slice(0, 20);
+    const targetSet = new Set(cappedTargets);
+    const intersectionCount = finding.affected_files.filter((f) => targetSet.has(f)).length;
+    const jaccardFileOverlap = cappedTargets.length === 0 || finding.affected_files.length === 0
+        ? 0
+        : intersectionCount / Math.min(finding.affected_files.length, cappedTargets.length);
+    // --- Package match ---
+    // Extract package name from each path in affected_files via packages/<name>/
+    const pkgRegex = /packages\/([^/]+)\//;
+    const inferredPackages = finding.affected_files
+        .map((f) => pkgRegex.exec(f)?.[1])
+        .filter((p) => p !== undefined);
+    const packageMatch = context.packageName === undefined || inferredPackages.length === 0
+        ? 0.5
+        : inferredPackages.includes(context.packageName)
+            ? 1.0
+            : 0.0;
+    // --- Root cause match ---
+    const rootCauseMatch = !context.riskProfile || context.riskProfile.length === 0
+        ? 0.5
+        : context.riskProfile.includes(finding.root_cause)
+            ? 1.0
+            : 0.0;
+    return Math.min(1, Math.max(0, 0.5 * jaccardFileOverlap + 0.3 * packageMatch + 0.2 * rootCauseMatch));
+}
+//# sourceMappingURL=relevance-scorer.js.map

package/dist/learning/relevance-scorer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"relevance-scorer.js","sourceRoot":"","sources":["../../src/learning/relevance-scorer.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAgBH,8EAA8E;AAC9E,sDAAsD;AACtD,8EAA8E;AAE9E;;;;;GAKG;AACH,MAAM,UAAU,cAAc,CAAC,OAAgB,EAAE,OAAyB;IACxE,+BAA+B;IAC/B,yEAAyE;IACzE,MAAM,aAAa,GAAG,CAAC,OAAO,CAAC,WAAW,IAAI,EAAE,CAAC;SAC9C,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,MAAM,CAAC;SACnC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAA;IACf,MAAM,SAAS,GAAG,IAAI,GAAG,CAAC,aAAa,CAAC,CAAA;IACxC,MAAM,iBAAiB,GAAG,OAAO,CAAC,cAAc,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAA;IACvF,MAAM,kBAAkB,GACtB,aAAa,CAAC,MAAM,KAAK,CAAC,IAAI,OAAO,CAAC,cAAc,CAAC,MAAM,KAAK,CAAC;QAC/D,CAAC,CAAC,CAAC;QACH,CAAC,CAAC,iBAAiB,GAAG,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,cAAc,CAAC,MAAM,EAAE,aAAa,CAAC,MAAM,CAAC,CAAA;IAEvF,wBAAwB;IACxB,6EAA6E;IAC7E,MAAM,QAAQ,GAAG,qBAAqB,CAAA;IACtC,MAAM,gBAAgB,GAAG,OAAO,CAAC,cAAc;SAC5C,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;SACjC,MAAM,CAAC,CAAC,CAAC,EAAe,EAAE,CAAC,CAAC,KAAK,SAAS,CAAC,CAAA;IAC9C,MAAM,YAAY,GAChB,OAAO,CAAC,WAAW,KAAK,SAAS,IAAI,gBAAgB,CAAC,MAAM,KAAK,CAAC;QAChE,CAAC,CAAC,GAAG;QACL,CAAC,CAAC,gBAAgB,CAAC,QAAQ,CAAC,OAAO,CAAC,WAAW,CAAC;YAC9C,CAAC,CAAC,GAAG;YACL,CAAC,CAAC,GAAG,CAAA;IAEX,2BAA2B;IAC3B,MAAM,cAAc,GAClB,CAAC,OAAO,CAAC,WAAW,IAAI,OAAO,CAAC,WAAW,CAAC,MAAM,KAAK,CAAC;QACtD,CAAC,CAAC,GAAG;QACL,CAAC,CAAC,OAAO,CAAC,WAAW,CAAC,QAAQ,CAAC,OAAO,CAAC,UAAU,CAAC;YAChD,CAAC,CAAC,GAAG;YACL,CAAC,CAAC,GAAG,CAAA;IAEX,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,GAAG,GAAG,kBAAkB,GAAG,GAAG,GAAG,YAAY,GAAG,GAAG,GAAG,cAAc,CAAC,CAAC,CAAA;AACvG,CAAC"}

package/dist/learning/types.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Learning loop — root cause taxonomy types.
+ *
+ * Story 53-5: Root Cause Taxonomy and Failure Classification
+ */
+import { z } from 'zod';
+export declare const RootCauseCategorySchema: z.ZodEnum<{
+    "namespace-collision": "namespace-collision";
+    "dependency-ordering": "dependency-ordering";
+    "spec-staleness": "spec-staleness";
+    "adapter-format": "adapter-format";
+    "build-failure": "build-failure";
+    "test-failure": "test-failure";
+    "resource-exhaustion": "resource-exhaustion";
+    infrastructure: "infrastructure";
+    unclassified: "unclassified";
+}>;
+export type RootCauseCategory = z.infer<typeof RootCauseCategorySchema>;
+export declare const FindingSchema: z.ZodObject<{
+    id: z.ZodString;
+    run_id: z.ZodString;
+    story_key: z.ZodString;
+    root_cause: z.ZodEnum<{
+        "namespace-collision": "namespace-collision";
+        "dependency-ordering": "dependency-ordering";
+        "spec-staleness": "spec-staleness";
+        "adapter-format": "adapter-format";
+        "build-failure": "build-failure";
+        "test-failure": "test-failure";
+        "resource-exhaustion": "resource-exhaustion";
+        infrastructure: "infrastructure";
+        unclassified: "unclassified";
+    }>;
+    affected_files: z.ZodArray<z.ZodString>;
+    description: z.ZodString;
+    confidence: z.ZodEnum<{
+        high: "high";
+        low: "low";
+    }>;
+    created_at: z.ZodString;
+    expires_after_runs: z.ZodDefault<z.ZodNumber>;
+    contradicted_by: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type Finding = z.infer<typeof FindingSchema>;
+export interface StoryFailureContext {
+    storyKey: string;
+    runId: string;
+    error?: string;
+    outputTokens?: number;
+    buildFailed?: boolean;
+    testsFailed?: boolean;
+    adapterError?: boolean;
+    affectedFiles?: string[];
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/learning/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/learning/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAMvB,eAAO,MAAM,uBAAuB;;;;;;;;;;EAUlC,CAAA;AAEF,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAA;AAMvE,eAAO,MAAM,aAAa;;;;;;;;;;;;;;;;;;;;;;;;iBAWxB,CAAA;AAEF,MAAM,MAAM,OAAO,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,aAAa,CAAC,CAAA;AAOnD,MAAM,WAAW,mBAAmB;IAClC,QAAQ,EAAE,MAAM,CAAA;IAChB,KAAK,EAAE,MAAM,CAAA;IACb,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,WAAW,CAAC,EAAE,OAAO,CAAA;IACrB,WAAW,CAAC,EAAE,OAAO,CAAA;IACrB,YAAY,CAAC,EAAE,OAAO,CAAA;IACtB,aAAa,CAAC,EAAE,MAAM,EAAE,CAAA;CACzB"}

package/dist/learning/types.js

@@ -0,0 +1,36 @@
+/**
+ * Learning loop — root cause taxonomy types.
+ *
+ * Story 53-5: Root Cause Taxonomy and Failure Classification
+ */
+import { z } from 'zod';
+// ---------------------------------------------------------------------------
+// Root cause category enum
+// ---------------------------------------------------------------------------
+export const RootCauseCategorySchema = z.enum([
+    'namespace-collision',
+    'dependency-ordering',
+    'spec-staleness',
+    'adapter-format',
+    'build-failure',
+    'test-failure',
+    'resource-exhaustion',
+    'infrastructure',
+    'unclassified',
+]);
+// ---------------------------------------------------------------------------
+// Finding schema
+// ---------------------------------------------------------------------------
+export const FindingSchema = z.object({
+    id: z.string().uuid(),
+    run_id: z.string(),
+    story_key: z.string(),
+    root_cause: RootCauseCategorySchema,
+    affected_files: z.array(z.string()),
+    description: z.string(),
+    confidence: z.enum(['high', 'low']),
+    created_at: z.string(),
+    expires_after_runs: z.number().int().positive().default(5),
+    contradicted_by: z.string().optional(),
+});
+//# sourceMappingURL=types.js.map

package/dist/learning/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/learning/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAEvB,8EAA8E;AAC9E,2BAA2B;AAC3B,8EAA8E;AAE9E,MAAM,CAAC,MAAM,uBAAuB,GAAG,CAAC,CAAC,IAAI,CAAC;IAC5C,qBAAqB;IACrB,qBAAqB;IACrB,gBAAgB;IAChB,gBAAgB;IAChB,eAAe;IACf,cAAc;IACd,qBAAqB;IACrB,gBAAgB;IAChB,cAAc;CACf,CAAC,CAAA;AAIF,8EAA8E;AAC9E,iBAAiB;AACjB,8EAA8E;AAE9E,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,CAAC,MAAM,CAAC;IACpC,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE;IACrB,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE;IAClB,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE;IACrB,UAAU,EAAE,uBAAuB;IACnC,cAAc,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;IACnC,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE;IACvB,UAAU,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;IACnC,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE;IACtB,kBAAkB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE,CAAC,OAAO,CAAC,CAAC,CAAC;IAC1D,eAAe,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;CACvC,CAAC,CAAA"}

package/dist/orchestrator/graph-orchestrator.d.ts

@@ -0,0 +1,208 @@
+/**
+ * GraphOrchestrator — drives the SDLC pipeline as a factory graph.
+ *
+ * Story 43-7: GraphOrchestrator multi-story orchestration.
+ * Story 43-8: applyConfigToGraph config-to-graph mapping (duck-typed, ADR-003 compliant).
+ * Story 43-10: resolveGraphPath helper; eventBus/pipelineRunId/maxReviewCycles in config;
+ *              per-story outcome tracking in GraphRunSummary.
+ *
+ * ADR-003: NO imports from @substrate-ai/factory in this file.
+ * All factory-side types are accepted via locally-defined duck-typed
+ * interfaces injected through GraphOrchestratorConfig.
+ */
+/**
+ * Returns the absolute path to the bundled SDLC pipeline DOT file.
+ *
+ * Resolution order:
+ *   1. Relative to __dirname (works in source/unbundled: __dirname = packages/sdlc/src/orchestrator/)
+ *   2. Via createRequire to locate @substrate-ai/sdlc package.json, then graphs/ relative to it
+ *      (works when bundled: __dirname points to dist/ but createRequire finds the real package)
+ *
+ * @throws {Error} if the DOT file cannot be found by any method.
+ */
+export declare function resolveGraphPath(): string;
+/**
+ * Minimal structural interface for a factory graph object.
+ * Duck-typed from `@substrate-ai/factory`'s `Graph` — no direct import.
+ */
+export interface GraphShape {
+    nodes: Array<{
+        id: string;
+        type: string;
+        label: string;
+        prompt: string;
+    }>;
+    edges: Array<{
+        from: string;
+        to: string;
+        label?: string;
+    }>;
+}
+/**
+ * Configuration passed to the executor for a single graph run.
+ * Duck-typed from `@substrate-ai/factory`'s `GraphExecutorConfig`.
+ */
+export interface GraphRunConfig {
+    runId: string;
+    logsRoot: string;
+    handlerRegistry: unknown;
+    initialContext?: Record<string, unknown>;
+    eventBus?: unknown;
+}
+/**
+ * Result returned by the executor for a single graph run.
+ * Duck-typed from `@substrate-ai/factory`'s `Outcome`.
+ * Maps StageStatus: 'SUCCESS' | 'FAIL' | 'PARTIAL_SUCCESS' | 'RETRY' | 'SKIPPED'
+ */
+export interface GraphRunResult {
+    status: 'SUCCESS' | 'FAIL' | 'PARTIAL_SUCCESS' | 'RETRY' | 'SKIPPED' | string;
+    failureReason?: string;
+}
+/**
+ * Duck-typed executor contract — structurally compatible with `GraphExecutor` from factory.
+ */
+export interface IGraphExecutorLocal {
+    run(graph: GraphShape, config: GraphRunConfig): Promise<GraphRunResult>;
+}
+/**
+ * Batched conflict groups: outer = batches (sequential), middle = groups
+ * (sequential within batch), inner = story keys (sequential within group).
+ */
+export type ConflictGroupBatches = string[][][];
+/**
+ * Function that partitions story keys into ordered batches of conflict groups.
+ * Injected by the CLI composition root (story 43-10).
+ */
+export type ConflictGrouperFn = (storyKeys: string[]) => ConflictGroupBatches;
+/**
+ * Configuration for `createGraphOrchestrator`.
+ *
+ * All factory-side objects (`graph`, `executor`, `handlerRegistry`) are injected
+ * here — the orchestrator never imports `@substrate-ai/factory` directly (ADR-003).
+ */
+export interface GraphOrchestratorConfig {
+    /** Pre-parsed graph object (structurally compatible with factory's Graph). */
+    graph: GraphShape;
+    /** Executor that runs a single story graph instance. */
+    executor: IGraphExecutorLocal;
+    /** Handler registry passed through to executor config. */
+    handlerRegistry: unknown;
+    /** Absolute path to the project root. */
+    projectRoot: string;
+    /** Methodology pack identifier passed to each story graph instance. */
+    methodologyPack: string;
+    /** Maximum number of concurrent story graph executor instances. */
+    maxConcurrency: number;
+    /** Directory under which per-story run logs are written. */
+    logsRoot: string;
+    /** Unique identifier for this orchestration run. */
+    runId: string;
+    /**
+     * Optional conflict group partitioner. If omitted, each story runs in its own
+     * single-item group within a single batch (fully parallel up to maxConcurrency).
+     */
+    conflictGrouper?: ConflictGrouperFn;
+    /**
+     * Milliseconds to pause between stories within the same conflict group.
+     * Reduces memory pressure during long runs. Defaults to 2000.
+     */
+    gcPauseMs?: number;
+    /**
+     * Optional SDLC event bus that receives translated orchestrator events via the
+     * SDLC event bridge (story 43-9). When provided, graph executor lifecycle events
+     * are translated into `orchestrator:story-phase-*` events for downstream consumers.
+     * (story 43-10: wired by CLI composition root)
+     */
+    eventBus?: unknown;
+    /**
+     * Optional pipeline run ID forwarded to SDLC event bridge payloads.
+     * Included as `pipelineRunId` in `orchestrator:story-phase-start/complete` events.
+     * (story 43-10)
+     */
+    pipelineRunId?: string;
+    /**
+     * Maximum number of code-review + fix cycles per story.
+     * Forwarded to the graph via `applyConfigToGraph` before execution and
+     * stored here for observability / testing (AC7, story 43-10).
+     */
+    maxReviewCycles?: number;
+    /**
+     * Per-story maximum retry attempts before mandatory escalation (Story 53-4).
+     * Default: 2. Reserved for future graph-engine budget gate implementation.
+     */
+    retryBudget?: number;
+}
+/**
+ * Per-story outcome detail in `GraphRunSummary`.
+ * Story 43-10: added for normalisation by the CLI composition root.
+ */
+export interface GraphStoryOutcome {
+    outcome: 'SUCCESS' | 'FAILED' | 'ESCALATED';
+    error?: string;
+}
+/** Summary returned by `GraphOrchestrator.run()` after all stories complete. */
+export interface GraphRunSummary {
+    successCount: number;
+    failureCount: number;
+    totalStories: number;
+    /**
+     * Per-story outcome map.
+     * Key = story key passed to `run()`; value = outcome detail.
+     * Added in story 43-10 so the CLI composition root can map results to the
+     * linear orchestrator's `{ stories: Record<string, { phase: string }> }` shape.
+     */
+    stories: Record<string, GraphStoryOutcome>;
+}
+/** Multi-story graph orchestrator interface (story 43-7). */
+export interface GraphOrchestrator {
+    run(storyKeys: string[]): Promise<GraphRunSummary>;
+}
+/** Thrown by `createGraphOrchestrator` when the supplied graph is structurally invalid. */
+export declare class GraphOrchestratorInitError extends Error {
+    constructor(message: string);
+}
+/**
+ * Creates a `GraphOrchestrator` that runs one graph executor instance per
+ * concurrent story slot, with conflict-group serialization and bounded concurrency.
+ *
+ * When `config.eventBus` is provided, a per-story SDLC event bridge is created
+ * to translate factory `graph:*` events into `orchestrator:story-*` events (AC4,
+ * story 43-10).
+ *
+ * @throws {GraphOrchestratorInitError} if `config.graph` is missing `nodes` or `edges`.
+ */
+export declare function createGraphOrchestrator(config: GraphOrchestratorConfig): GraphOrchestrator;
+/**
+ * Duck-typed graph interface for config patching.
+ * Structurally compatible with `@substrate-ai/factory`'s `Graph` (Map-based nodes)
+ * without requiring a direct import (ADR-003 compliant).
+ */
+interface PatchableGraph {
+    nodes: {
+        get(id: string): {
+            maxRetries?: number;
+        } | undefined;
+    };
+    defaultMaxRetries?: number;
+}
+/**
+ * Options accepted by `applyConfigToGraph`.
+ */
+export interface ApplyConfigOptions {
+    maxReviewCycles: number;
+}
+/**
+ * Patches the loaded SDLC pipeline graph to reflect runtime configuration.
+ *
+ * Currently maps `maxReviewCycles` → `dev_story.maxRetries` (1:1 mapping).
+ * Both values represent the number of *additional* retry attempts (not total).
+ *
+ * Must be called after parseGraph() and before any story graph instance runs.
+ *
+ * @param graph  A factory Graph (Map-based nodes) duck-typed as PatchableGraph.
+ * @param options  Runtime configuration to apply.
+ * @throws {Error} if the graph does not contain a `dev_story` node.
+ */
+export declare function applyConfigToGraph(graph: PatchableGraph, options: ApplyConfigOptions): void;
+export {};
+//# sourceMappingURL=graph-orchestrator.d.ts.map

package/dist/orchestrator/graph-orchestrator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph-orchestrator.d.ts","sourceRoot":"","sources":["../../src/orchestrator/graph-orchestrator.ts"],"names":[],"mappings":"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"}