@substrate-ai/sdlc 0.19.54

package/dist/handlers/types.js

@@ -0,0 +1,10 @@
+/**
+ * Type definitions for the SDLC handler module.
+ * Story 43-2.
+ *
+ * All types are defined locally — structurally compatible with monolith types
+ * but not compile-time coupled to the monolith or @substrate-ai/factory.
+ * See ADR-003: sdlc must NOT import from @substrate-ai/factory.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/handlers/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/handlers/types.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG"}

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export * from './events.js';
+export * from './handlers/index.js';
+export * from './orchestrator/graph-orchestrator.js';
+export * from './verification/index.js';
+export * from './run-model/index.js';
+export * from './learning/index.js';
+export * from './gating/index.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,cAAc,aAAa,CAAA;AAC3B,cAAc,qBAAqB,CAAA;AAEnC,cAAc,sCAAsC,CAAA;AAEpD,cAAc,yBAAyB,CAAA;AAEvC,cAAc,sBAAsB,CAAA;AAEpC,cAAc,qBAAqB,CAAA;AAEnC,cAAc,mBAAmB,CAAA"}

package/dist/index.js

@@ -0,0 +1,14 @@
+// @substrate-ai/sdlc — public API (populated in stories 40-3 through 40-8)
+export * from './events.js';
+export * from './handlers/index.js';
+// Story 43-7/43-8: graph-based orchestrator and config mapping
+export * from './orchestrator/graph-orchestrator.js';
+// Story 51-1: Verification pipeline framework
+export * from './verification/index.js';
+// Story 52-1: RunManifest — atomic file-backed run state
+export * from './run-model/index.js';
+// Story 53-5: Learning loop — root cause taxonomy and failure classification
+export * from './learning/index.js';
+// Story 53-9: Dispatch pre-condition gating
+export * from './gating/index.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,2EAA2E;AAC3E,cAAc,aAAa,CAAA;AAC3B,cAAc,qBAAqB,CAAA;AACnC,+DAA+D;AAC/D,cAAc,sCAAsC,CAAA;AACpD,8CAA8C;AAC9C,cAAc,yBAAyB,CAAA;AACvC,yDAAyD;AACzD,cAAc,sBAAsB,CAAA;AACpC,6EAA6E;AAC7E,cAAc,qBAAqB,CAAA;AACnC,4CAA4C;AAC5C,cAAc,mBAAmB,CAAA"}

package/dist/learning/failure-classifier.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Learning loop — deterministic failure classifier.
+ *
+ * Story 53-5: Root Cause Taxonomy and Failure Classification
+ *
+ * classifyFailure applies a rule chain in strict priority order (§3.4).
+ * buildFinding constructs a validated Finding from a classification result.
+ */
+import type { Finding, RootCauseCategory, StoryFailureContext } from './types.js';
+/**
+ * Deterministic, synchronous rule chain that maps a StoryFailureContext to a
+ * RootCauseCategory. Rules are evaluated in order; the first match wins.
+ */
+export declare function classifyFailure(ctx: StoryFailureContext): RootCauseCategory;
+/**
+ * Construct a validated Finding from a StoryFailureContext and classification result.
+ *
+ * - confidence: 'low' for 'unclassified', 'high' for all other categories
+ * - description: raw ctx.error for 'unclassified'; human-readable text otherwise
+ * - expires_after_runs: 5 (default)
+ */
+export declare function buildFinding(ctx: StoryFailureContext, rootCause: RootCauseCategory, runId: string): Finding;
+//# sourceMappingURL=failure-classifier.d.ts.map

package/dist/learning/failure-classifier.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"failure-classifier.d.ts","sourceRoot":"","sources":["../../src/learning/failure-classifier.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,KAAK,EAAE,OAAO,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAA;AAMjF;;;GAGG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,mBAAmB,GAAG,iBAAiB,CAS3E;AAsBD;;;;;;GAMG;AACH,wBAAgB,YAAY,CAC1B,GAAG,EAAE,mBAAmB,EACxB,SAAS,EAAE,iBAAiB,EAC5B,KAAK,EAAE,MAAM,GACZ,OAAO,CAmBT"}

package/dist/learning/failure-classifier.js

@@ -0,0 +1,75 @@
+/**
+ * Learning loop — deterministic failure classifier.
+ *
+ * Story 53-5: Root Cause Taxonomy and Failure Classification
+ *
+ * classifyFailure applies a rule chain in strict priority order (§3.4).
+ * buildFinding constructs a validated Finding from a classification result.
+ */
+import { FindingSchema } from './types.js';
+// ---------------------------------------------------------------------------
+// Classification rule chain — canonical priority order, do not reorder
+// ---------------------------------------------------------------------------
+/**
+ * Deterministic, synchronous rule chain that maps a StoryFailureContext to a
+ * RootCauseCategory. Rules are evaluated in order; the first match wins.
+ */
+export function classifyFailure(ctx) {
+    if (ctx.error?.includes('already exists'))
+        return 'namespace-collision';
+    if (ctx.error?.includes('depends on') || ctx.error?.includes('not found'))
+        return 'dependency-ordering';
+    if ((ctx.outputTokens ?? Infinity) < 100)
+        return 'resource-exhaustion';
+    if (ctx.buildFailed === true)
+        return 'build-failure';
+    if (ctx.testsFailed === true)
+        return 'test-failure';
+    if (ctx.adapterError === true)
+        return 'adapter-format';
+    if (/heap out of memory|ENOSPC|EACCES|SIGKILL/.test(ctx.error ?? ''))
+        return 'infrastructure';
+    return 'unclassified';
+}
+// ---------------------------------------------------------------------------
+// Human-readable descriptions per category
+// ---------------------------------------------------------------------------
+const CATEGORY_DESCRIPTIONS = {
+    'namespace-collision': 'Identifier or namespace collision detected during story dispatch',
+    'dependency-ordering': 'Story depends on a missing or not-yet-available dependency',
+    'spec-staleness': 'Story spec references outdated or stale interface definitions',
+    'adapter-format': 'Adapter output format was not recognized or could not be parsed',
+    'build-failure': 'Build failed after story dispatch',
+    'test-failure': 'Tests failed after story implementation',
+    'resource-exhaustion': 'Story produced fewer than 100 output tokens (resource exhaustion suspected)',
+    'infrastructure': 'System-level infrastructure error (OOM, disk, permissions, or SIGKILL)',
+    'unclassified': 'No error text available', // overridden in buildFinding with raw ctx.error when present
+};
+// ---------------------------------------------------------------------------
+// Finding builder
+// ---------------------------------------------------------------------------
+/**
+ * Construct a validated Finding from a StoryFailureContext and classification result.
+ *
+ * - confidence: 'low' for 'unclassified', 'high' for all other categories
+ * - description: raw ctx.error for 'unclassified'; human-readable text otherwise
+ * - expires_after_runs: 5 (default)
+ */
+export function buildFinding(ctx, rootCause, runId) {
+    const confidence = rootCause === 'unclassified' ? 'low' : 'high';
+    const description = rootCause === 'unclassified'
+        ? (ctx.error ?? 'No error text available')
+        : CATEGORY_DESCRIPTIONS[rootCause];
+    return FindingSchema.parse({
+        id: crypto.randomUUID(),
+        run_id: runId,
+        story_key: ctx.storyKey,
+        root_cause: rootCause,
+        affected_files: ctx.affectedFiles ?? [],
+        description,
+        confidence,
+        created_at: new Date().toISOString(),
+        expires_after_runs: 5,
+    });
+}
+//# sourceMappingURL=failure-classifier.js.map

package/dist/learning/failure-classifier.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"failure-classifier.js","sourceRoot":"","sources":["../../src/learning/failure-classifier.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAA;AAG1C,8EAA8E;AAC9E,uEAAuE;AACvE,8EAA8E;AAE9E;;;GAGG;AACH,MAAM,UAAU,eAAe,CAAC,GAAwB;IACtD,IAAI,GAAG,CAAC,KAAK,EAAE,QAAQ,CAAC,gBAAgB,CAAC;QAAE,OAAO,qBAAqB,CAAA;IACvE,IAAI,GAAG,CAAC,KAAK,EAAE,QAAQ,CAAC,YAAY,CAAC,IAAI,GAAG,CAAC,KAAK,EAAE,QAAQ,CAAC,WAAW,CAAC;QAAE,OAAO,qBAAqB,CAAA;IACvG,IAAI,CAAC,GAAG,CAAC,YAAY,IAAI,QAAQ,CAAC,GAAG,GAAG;QAAE,OAAO,qBAAqB,CAAA;IACtE,IAAI,GAAG,CAAC,WAAW,KAAK,IAAI;QAAE,OAAO,eAAe,CAAA;IACpD,IAAI,GAAG,CAAC,WAAW,KAAK,IAAI;QAAE,OAAO,cAAc,CAAA;IACnD,IAAI,GAAG,CAAC,YAAY,KAAK,IAAI;QAAE,OAAO,gBAAgB,CAAA;IACtD,IAAI,0CAA0C,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,IAAI,EAAE,CAAC;QAAE,OAAO,gBAAgB,CAAA;IAC7F,OAAO,cAAc,CAAA;AACvB,CAAC;AAED,8EAA8E;AAC9E,2CAA2C;AAC3C,8EAA8E;AAE9E,MAAM,qBAAqB,GAAsC;IAC/D,qBAAqB,EAAE,kEAAkE;IACzF,qBAAqB,EAAE,4DAA4D;IACnF,gBAAgB,EAAE,+DAA+D;IACjF,gBAAgB,EAAE,iEAAiE;IACnF,eAAe,EAAE,mCAAmC;IACpD,cAAc,EAAE,yCAAyC;IACzD,qBAAqB,EAAE,6EAA6E;IACpG,gBAAgB,EAAE,wEAAwE;IAC1F,cAAc,EAAE,yBAAyB,EAAE,6DAA6D;CACzG,CAAA;AAED,8EAA8E;AAC9E,kBAAkB;AAClB,8EAA8E;AAE9E;;;;;;GAMG;AACH,MAAM,UAAU,YAAY,CAC1B,GAAwB,EACxB,SAA4B,EAC5B,KAAa;IAEb,MAAM,UAAU,GAAG,SAAS,KAAK,cAAc,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,CAAA;IAEhE,MAAM,WAAW,GACf,SAAS,KAAK,cAAc;QAC1B,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,IAAI,yBAAyB,CAAC;QAC1C,CAAC,CAAC,qBAAqB,CAAC,SAAS,CAAC,CAAA;IAEtC,OAAO,aAAa,CAAC,KAAK,CAAC;QACzB,EAAE,EAAE,MAAM,CAAC,UAAU,EAAE;QACvB,MAAM,EAAE,KAAK;QACb,SAAS,EAAE,GAAG,CAAC,QAAQ;QACvB,UAAU,EAAE,SAAS;QACrB,cAAc,EAAE,GAAG,CAAC,aAAa,IAAI,EAAE;QACvC,WAAW;QACX,UAAU;QACV,UAAU,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;QACpC,kBAAkB,EAAE,CAAC;KACtB,CAAC,CAAA;AACJ,CAAC"}

package/dist/learning/finding-classifier.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Learning loop — top-level classify-and-persist orchestrator.
+ *
+ * Story 53-5: Root Cause Taxonomy and Failure Classification
+ *
+ * classifyAndPersist is the primary entry point for the learning loop:
+ * it classifies a story failure, constructs a Finding, and persists it to
+ * Dolt — all non-fatally (persistence errors are swallowed so the in-memory
+ * result is always returned to the caller).
+ */
+import type { DatabaseAdapter } from '@substrate-ai/core';
+import type { Finding, StoryFailureContext } from './types.js';
+/**
+ * Classify a story failure, build a Finding, and attempt to persist it.
+ *
+ * Persistence is non-fatal: if `db` is null or the persist call rejects,
+ * the Finding is still returned. This ensures that Dolt unavailability
+ * never blocks the learning loop from producing an in-memory classification.
+ *
+ * @param ctx - Contextual failure information from the orchestrator
+ * @param db - DatabaseAdapter to persist to, or null if unavailable
+ * @returns A validated Finding with root_cause, confidence, and metadata
+ */
+export declare function classifyAndPersist(ctx: StoryFailureContext, db: DatabaseAdapter | null): Promise<Finding>;
+//# sourceMappingURL=finding-classifier.d.ts.map

package/dist/learning/finding-classifier.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"finding-classifier.d.ts","sourceRoot":"","sources":["../../src/learning/finding-classifier.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAA;AAGzD,OAAO,KAAK,EAAE,OAAO,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAA;AAM9D;;;;;;;;;;GAUG;AACH,wBAAsB,kBAAkB,CACtC,GAAG,EAAE,mBAAmB,EACxB,EAAE,EAAE,eAAe,GAAG,IAAI,GACzB,OAAO,CAAC,OAAO,CAAC,CAWlB"}

package/dist/learning/finding-classifier.js

@@ -0,0 +1,37 @@
+/**
+ * Learning loop — top-level classify-and-persist orchestrator.
+ *
+ * Story 53-5: Root Cause Taxonomy and Failure Classification
+ *
+ * classifyAndPersist is the primary entry point for the learning loop:
+ * it classifies a story failure, constructs a Finding, and persists it to
+ * Dolt — all non-fatally (persistence errors are swallowed so the in-memory
+ * result is always returned to the caller).
+ */
+import { classifyFailure, buildFinding } from './failure-classifier.js';
+import { persistFinding } from './finding-store.js';
+// ---------------------------------------------------------------------------
+// Classify and persist a story failure
+// ---------------------------------------------------------------------------
+/**
+ * Classify a story failure, build a Finding, and attempt to persist it.
+ *
+ * Persistence is non-fatal: if `db` is null or the persist call rejects,
+ * the Finding is still returned. This ensures that Dolt unavailability
+ * never blocks the learning loop from producing an in-memory classification.
+ *
+ * @param ctx - Contextual failure information from the orchestrator
+ * @param db - DatabaseAdapter to persist to, or null if unavailable
+ * @returns A validated Finding with root_cause, confidence, and metadata
+ */
+export async function classifyAndPersist(ctx, db) {
+    const rootCause = classifyFailure(ctx);
+    const finding = buildFinding(ctx, rootCause, ctx.runId);
+    if (db !== null) {
+        persistFinding(finding, db).catch(() => {
+            // Non-fatal: Dolt may be unavailable; in-memory finding is always returned
+        });
+    }
+    return finding;
+}
+//# sourceMappingURL=finding-classifier.js.map

package/dist/learning/finding-classifier.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"finding-classifier.js","sourceRoot":"","sources":["../../src/learning/finding-classifier.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAA;AACvE,OAAO,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAA;AAGnD,8EAA8E;AAC9E,uCAAuC;AACvC,8EAA8E;AAE9E;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACtC,GAAwB,EACxB,EAA0B;IAE1B,MAAM,SAAS,GAAG,eAAe,CAAC,GAAG,CAAC,CAAA;IACtC,MAAM,OAAO,GAAG,YAAY,CAAC,GAAG,EAAE,SAAS,EAAE,GAAG,CAAC,KAAK,CAAC,CAAA;IAEvD,IAAI,EAAE,KAAK,IAAI,EAAE,CAAC;QAChB,cAAc,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE;YACrC,2EAA2E;QAC7E,CAAC,CAAC,CAAA;IACJ,CAAC;IAED,OAAO,OAAO,CAAA;AAChB,CAAC"}

package/dist/learning/finding-lifecycle.d.ts

@@ -0,0 +1,69 @@
+/**
+ * FindingLifecycleManager — validation, deduplication, expiry, and retirement
+ * for learning loop findings.
+ *
+ * Story 53-7: Finding Validation, Deduplication, and Expiry
+ */
+import type { DatabaseAdapter } from '@substrate-ai/core';
+import type { Finding } from './types.js';
+/** Context supplied when a story completes successfully. */
+export interface SuccessContext {
+    modifiedFiles: string[];
+    runId: string;
+}
+export declare class FindingLifecycleManager {
+    /**
+     * Validate file existence for a finding's affected_files.
+     *
+     * - Returns finding unchanged if affected_files is empty or all files exist.
+     * - Returns finding with confidence: 'low' if some files are missing.
+     * - Returns finding with confidence: 'low' + contradicted_by: 'all-files-deleted'
+     *   if ALL files are missing.
+     *
+     * AC1: pure synchronous function — no I/O beyond fs.existsSync
+     */
+    static validateFiles(finding: Finding, projectRoot: string): Finding;
+    /**
+     * Deduplicate findings by fingerprint: `${root_cause}:${affected_files.sort().join(',')}`.
+     *
+     * For each group of duplicates, only the most recently created finding
+     * (highest created_at lexicographically) is retained.
+     *
+     * AC2: pure synchronous function — no I/O
+     */
+    static deduplicate(findings: Finding[]): Finding[];
+    /**
+     * Count the number of distinct pipeline runs since this finding was created.
+     *
+     * Returns 0 on any DB error (non-fatal — never marks as expired on error).
+     *
+     * AC3: async — interacts with the DB
+     */
+    static countRunsSinceCreation(finding: Finding, db: DatabaseAdapter): Promise<number>;
+    /**
+     * Check if a finding has expired based on the run count since its creation.
+     *
+     * AC3: pure synchronous function — no I/O
+     */
+    static isExpired(finding: Finding, runCount: number): boolean;
+    /**
+     * Archive a finding by persisting a tombstone record in the decisions table.
+     *
+     * Non-fatal — any DB error is swallowed silently.
+     *
+     * AC4: async — interacts with the DB
+     */
+    static archiveFinding(finding: Finding, currentRunId: string, db: DatabaseAdapter): Promise<void>;
+    /**
+     * Retire findings that are contradicted by a successful story run.
+     *
+     * Loads all findings from Dolt, checks each for file overlap with the
+     * success context, and persists a tombstone for overlapping findings.
+     *
+     * Entirely non-fatal — DB errors and parse failures are swallowed silently.
+     *
+     * AC5: async — interacts with the DB
+     */
+    static retireContradictedFindings(successContext: SuccessContext, db: DatabaseAdapter): Promise<void>;
+}
+//# sourceMappingURL=finding-lifecycle.d.ts.map

package/dist/learning/finding-lifecycle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"finding-lifecycle.d.ts","sourceRoot":"","sources":["../../src/learning/finding-lifecycle.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAA;AAEzD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,YAAY,CAAA;AAOzC,4DAA4D;AAC5D,MAAM,WAAW,cAAc;IAC7B,aAAa,EAAE,MAAM,EAAE,CAAA;IACvB,KAAK,EAAE,MAAM,CAAA;CACd;AAMD,qBAAa,uBAAuB;IAClC;;;;;;;;;OASG;IACH,MAAM,CAAC,aAAa,CAAC,OAAO,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO;IAkBpE;;;;;;;OAOG;IACH,MAAM,CAAC,WAAW,CAAC,QAAQ,EAAE,OAAO,EAAE,GAAG,OAAO,EAAE;IAuBlD;;;;;;OAMG;WACU,sBAAsB,CAAC,OAAO,EAAE,OAAO,EAAE,EAAE,EAAE,eAAe,GAAG,OAAO,CAAC,MAAM,CAAC;IAc3F;;;;OAIG;IACH,MAAM,CAAC,SAAS,CAAC,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO;IAI7D;;;;;;OAMG;WACU,cAAc,CAAC,OAAO,EAAE,OAAO,EAAE,YAAY,EAAE,MAAM,EAAE,EAAE,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC;IAcvG;;;;;;;;;OASG;WACU,0BAA0B,CAAC,cAAc,EAAE,cAAc,EAAE,EAAE,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC;CAuC5G"}

package/dist/learning/finding-lifecycle.js

@@ -0,0 +1,162 @@
+/**
+ * FindingLifecycleManager — validation, deduplication, expiry, and retirement
+ * for learning loop findings.
+ *
+ * Story 53-7: Finding Validation, Deduplication, and Expiry
+ */
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { createDecision, getDecisionsByCategory, LEARNING_FINDING } from '@substrate-ai/core';
+import { FindingSchema } from './types.js';
+// ---------------------------------------------------------------------------
+// FindingLifecycleManager
+// ---------------------------------------------------------------------------
+export class FindingLifecycleManager {
+    /**
+     * Validate file existence for a finding's affected_files.
+     *
+     * - Returns finding unchanged if affected_files is empty or all files exist.
+     * - Returns finding with confidence: 'low' if some files are missing.
+     * - Returns finding with confidence: 'low' + contradicted_by: 'all-files-deleted'
+     *   if ALL files are missing.
+     *
+     * AC1: pure synchronous function — no I/O beyond fs.existsSync
+     */
+    static validateFiles(finding, projectRoot) {
+        if (finding.affected_files.length === 0) {
+            return finding;
+        }
+        const existingCount = finding.affected_files.filter((f) => existsSync(join(projectRoot, f))).length;
+        if (existingCount === 0) {
+            return { ...finding, confidence: 'low', contradicted_by: 'all-files-deleted' };
+        }
+        if (existingCount < finding.affected_files.length) {
+            return { ...finding, confidence: 'low' };
+        }
+        return finding;
+    }
+    /**
+     * Deduplicate findings by fingerprint: `${root_cause}:${affected_files.sort().join(',')}`.
+     *
+     * For each group of duplicates, only the most recently created finding
+     * (highest created_at lexicographically) is retained.
+     *
+     * AC2: pure synchronous function — no I/O
+     */
+    static deduplicate(findings) {
+        const groups = new Map();
+        for (const finding of findings) {
+            const fingerprint = `${finding.root_cause}:${[...finding.affected_files].sort().join(',')}`;
+            const group = groups.get(fingerprint);
+            if (group === undefined) {
+                groups.set(fingerprint, [finding]);
+            }
+            else {
+                group.push(finding);
+            }
+        }
+        const result = [];
+        for (const group of groups.values()) {
+            // Keep the finding with the highest created_at (ISO strings compare correctly lexicographically)
+            const best = group.reduce((a, b) => (a.created_at >= b.created_at ? a : b));
+            result.push(best);
+        }
+        return result;
+    }
+    /**
+     * Count the number of distinct pipeline runs since this finding was created.
+     *
+     * Returns 0 on any DB error (non-fatal — never marks as expired on error).
+     *
+     * AC3: async — interacts with the DB
+     */
+    static async countRunsSinceCreation(finding, db) {
+        try {
+            const result = await db.query(`SELECT COUNT(DISTINCT pipeline_run_id) AS cnt
+         FROM decisions
+         WHERE created_at > ? AND pipeline_run_id != ?`, [finding.created_at, finding.run_id]);
+            return Number(result[0]?.cnt ?? 0);
+        }
+        catch {
+            return 0;
+        }
+    }
+    /**
+     * Check if a finding has expired based on the run count since its creation.
+     *
+     * AC3: pure synchronous function — no I/O
+     */
+    static isExpired(finding, runCount) {
+        return runCount >= finding.expires_after_runs;
+    }
+    /**
+     * Archive a finding by persisting a tombstone record in the decisions table.
+     *
+     * Non-fatal — any DB error is swallowed silently.
+     *
+     * AC4: async — interacts with the DB
+     */
+    static async archiveFinding(finding, currentRunId, db) {
+        try {
+            await createDecision(db, {
+                category: LEARNING_FINDING,
+                key: `${finding.id}:archived`,
+                pipeline_run_id: currentRunId,
+                phase: 'implementation',
+                value: JSON.stringify({ ...finding, contradicted_by: 'expired' }),
+            });
+        }
+        catch {
+            // Non-fatal: swallow DB errors per AC4
+        }
+    }
+    /**
+     * Retire findings that are contradicted by a successful story run.
+     *
+     * Loads all findings from Dolt, checks each for file overlap with the
+     * success context, and persists a tombstone for overlapping findings.
+     *
+     * Entirely non-fatal — DB errors and parse failures are swallowed silently.
+     *
+     * AC5: async — interacts with the DB
+     */
+    static async retireContradictedFindings(successContext, db) {
+        try {
+            const rows = await getDecisionsByCategory(db, LEARNING_FINDING);
+            for (const row of rows) {
+                try {
+                    const parsed = JSON.parse(row.value);
+                    const result = FindingSchema.safeParse(parsed);
+                    if (!result.success)
+                        continue;
+                    const finding = result.data;
+                    // Only retire findings that have not yet been contradicted/archived
+                    // AND have at least one file overlapping the success context
+                    const hasOverlap = finding.contradicted_by === undefined &&
+                        finding.affected_files.some((f) => successContext.modifiedFiles.includes(f));
+                    if (!hasOverlap)
+                        continue;
+                    try {
+                        await createDecision(db, {
+                            category: LEARNING_FINDING,
+                            key: `${finding.id}:archived`,
+                            pipeline_run_id: successContext.runId,
+                            phase: 'implementation',
+                            value: JSON.stringify({ ...finding, contradicted_by: successContext.runId }),
+                        });
+                    }
+                    catch {
+                        // Non-fatal: swallow individual write errors per AC5
+                    }
+                }
+                catch {
+                    // Non-fatal: swallow parse failures per AC5
+                }
+            }
+        }
+        catch {
+            // Non-fatal: swallow outer DB/load errors per AC5
+        }
+    }
+}
+//# sourceMappingURL=finding-lifecycle.js.map

package/dist/learning/finding-lifecycle.js.map

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

package/dist/learning/finding-store.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Learning loop — finding persistence to the Dolt decisions table.
+ *
+ * Story 53-5: Root Cause Taxonomy and Failure Classification
+ */
+import type { DatabaseAdapter } from '@substrate-ai/core';
+import type { Finding } from './types.js';
+/**
+ * Persist a classified Finding to the decisions table using the LEARNING_FINDING
+ * category. Key format: '{story_key}:{run_id}'.
+ *
+ * @param finding - The Finding to persist (from buildFinding)
+ * @param db - A live DatabaseAdapter (Dolt or InMemory)
+ */
+export declare function persistFinding(finding: Finding, db: DatabaseAdapter): Promise<void>;
+//# sourceMappingURL=finding-store.d.ts.map

package/dist/learning/finding-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"finding-store.d.ts","sourceRoot":"","sources":["../../src/learning/finding-store.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAA;AACzD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,YAAY,CAAA;AAMzC;;;;;;GAMG;AACH,wBAAsB,cAAc,CAAC,OAAO,EAAE,OAAO,EAAE,EAAE,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC,CAQzF"}

package/dist/learning/finding-store.js

@@ -0,0 +1,26 @@
+/**
+ * Learning loop — finding persistence to the Dolt decisions table.
+ *
+ * Story 53-5: Root Cause Taxonomy and Failure Classification
+ */
+import { createDecision, LEARNING_FINDING } from '@substrate-ai/core';
+// ---------------------------------------------------------------------------
+// Persist a Finding to the decisions table
+// ---------------------------------------------------------------------------
+/**
+ * Persist a classified Finding to the decisions table using the LEARNING_FINDING
+ * category. Key format: '{story_key}:{run_id}'.
+ *
+ * @param finding - The Finding to persist (from buildFinding)
+ * @param db - A live DatabaseAdapter (Dolt or InMemory)
+ */
+export async function persistFinding(finding, db) {
+    await createDecision(db, {
+        category: LEARNING_FINDING,
+        key: `${finding.story_key}:${finding.run_id}`,
+        phase: 'implementation',
+        pipeline_run_id: finding.run_id,
+        value: JSON.stringify(finding),
+    });
+}
+//# sourceMappingURL=finding-store.js.map

package/dist/learning/finding-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"finding-store.js","sourceRoot":"","sources":["../../src/learning/finding-store.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAA;AAIrE,8EAA8E;AAC9E,2CAA2C;AAC3C,8EAA8E;AAE9E;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,OAAgB,EAAE,EAAmB;IACxE,MAAM,cAAc,CAAC,EAAE,EAAE;QACvB,QAAQ,EAAE,gBAAgB;QAC1B,GAAG,EAAE,GAAG,OAAO,CAAC,SAAS,IAAI,OAAO,CAAC,MAAM,EAAE;QAC7C,KAAK,EAAE,gBAAgB;QACvB,eAAe,EAAE,OAAO,CAAC,MAAM;QAC/B,KAAK,EAAE,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC;KAC/B,CAAC,CAAA;AACJ,CAAC"}

package/dist/learning/findings-injector.d.ts

@@ -0,0 +1,34 @@
+/**
+ * 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 type { DatabaseAdapter } from '@substrate-ai/core';
+import type { InjectionContext } from './relevance-scorer.js';
+export interface FindingsInjectorConfig {
+    threshold?: number;
+    maxChars?: number;
+    saturationLimit?: number;
+}
+export declare 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 inject(db: DatabaseAdapter, context: InjectionContext, config?: FindingsInjectorConfig): Promise<string>;
+}
+/**
+ * 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 declare function extractTargetFilesFromStoryContent(storyContent: string): string[];
+//# sourceMappingURL=findings-injector.d.ts.map

package/dist/learning/findings-injector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"findings-injector.d.ts","sourceRoot":"","sources":["../../src/learning/findings-injector.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAA;AAIzD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAA;AAQ7D,MAAM,WAAW,sBAAsB;IACrC,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,eAAe,CAAC,EAAE,MAAM,CAAA;CACzB;AAMD,qBAAa,gBAAgB;IAC3B;;;;;OAKG;WACU,MAAM,CACjB,EAAE,EAAE,eAAe,EACnB,OAAO,EAAE,gBAAgB,EACzB,MAAM,CAAC,EAAE,sBAAsB,GAC9B,OAAO,CAAC,MAAM,CAAC;CAsGnB;AAMD;;;;;;GAMG;AACH,wBAAgB,kCAAkC,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,EAAE,CAMjF"}