@harness-engineering/intelligence 0.1.0

package/dist/index.d.mts

@@ -0,0 +1,901 @@
+import * as _harness_engineering_types from '@harness-engineering/types';
+import { Issue, ConcernSignal, ScopeTier, EscalationConfig } from '@harness-engineering/types';
+import { z } from 'zod';
+import { GraphStore } from '@harness-engineering/graph';
+
+/**
+ * Raw work item — generic input from any adapter (roadmap, JIRA, GitHub, etc.)
+ */
+interface RawWorkItem {
+    id: string;
+    title: string;
+    description: string | null;
+    labels: string[];
+    metadata: Record<string, unknown>;
+    linkedItems: string[];
+    comments: string[];
+    source: 'roadmap' | 'jira' | 'github' | 'linear' | 'manual';
+}
+/**
+ * A system identified by SEL as affected, validated against the knowledge graph.
+ */
+interface AffectedSystem {
+    /** Human name from LLM output */
+    name: string;
+    /** Graph node ID if found, null if not in graph */
+    graphNodeId: string | null;
+    /** Confidence of graph match (0 if not found) */
+    confidence: number;
+    /** Transitive dependency IDs from CascadeSimulator */
+    transitiveDeps: string[];
+    /** Number of test files covering this system */
+    testCoverage: number;
+    /** Owning team or individual, if known */
+    owner: string | null;
+}
+/**
+ * Enriched spec — output of the Spec Enrichment Layer (SEL).
+ */
+interface EnrichedSpec {
+    id: string;
+    title: string;
+    intent: string;
+    summary: string;
+    affectedSystems: AffectedSystem[];
+    functionalRequirements: string[];
+    nonFunctionalRequirements: string[];
+    apiChanges: string[];
+    dbChanges: string[];
+    integrationPoints: string[];
+    assumptions: string[];
+    unknowns: string[];
+    ambiguities: string[];
+    riskSignals: string[];
+    initialComplexityHints: {
+        textualComplexity: number;
+        structuralComplexity: number;
+    };
+}
+/**
+ * Blast radius estimate from CML.
+ */
+interface BlastRadius {
+    services: number;
+    modules: number;
+    filesEstimated: number;
+    testFilesAffected: number;
+}
+/**
+ * Complexity score — output of the Complexity Modeling Layer (CML).
+ */
+interface ComplexityScore {
+    overall: number;
+    confidence: number;
+    riskLevel: 'low' | 'medium' | 'high' | 'critical';
+    blastRadius: BlastRadius;
+    dimensions: {
+        structural: number;
+        semantic: number;
+        historical: number;
+    };
+    reasoning: string[];
+    recommendedRoute: 'local' | 'human' | 'simulation-required';
+}
+/**
+ * Simulation result — output of the Pre-Execution Simulation Layer (PESL).
+ */
+interface SimulationResult {
+    simulatedPlan: string[];
+    predictedFailures: string[];
+    riskHotspots: string[];
+    missingSteps: string[];
+    testGaps: string[];
+    executionConfidence: number;
+    recommendedChanges: string[];
+    abort: boolean;
+    tier: 'graph-only' | 'full-simulation';
+}
+
+/**
+ * Convert an orchestrator Issue into a generic RawWorkItem for the intelligence pipeline.
+ */
+declare function toRawWorkItem(issue: Issue): RawWorkItem;
+
+/**
+ * JIRA issue link reference.
+ */
+interface JiraIssueLink {
+    type: {
+        name: string;
+    };
+    inwardIssue?: {
+        id: string;
+        key: string;
+    };
+    outwardIssue?: {
+        id: string;
+        key: string;
+    };
+}
+/**
+ * JIRA comment entry.
+ */
+interface JiraComment {
+    body: string;
+    author: {
+        displayName: string;
+    };
+}
+/**
+ * Minimal JIRA issue shape accepted by the adapter.
+ * Represents pre-fetched data from the JIRA REST API.
+ */
+interface JiraIssue {
+    id: string;
+    key: string;
+    fields: {
+        summary: string;
+        description: string | null;
+        labels: string[];
+        priority: {
+            id: string;
+            name: string;
+        } | null;
+        status: {
+            id: string;
+            name: string;
+        };
+        issuetype: {
+            id: string;
+            name: string;
+        };
+        created: string;
+        updated: string;
+        issuelinks: JiraIssueLink[];
+        comment: {
+            comments: JiraComment[];
+        };
+    };
+}
+/**
+ * Convert a pre-fetched JIRA issue into a generic RawWorkItem.
+ */
+declare function jiraToRawWorkItem(issue: JiraIssue): RawWorkItem;
+
+/**
+ * GitHub label shape.
+ */
+interface GitHubLabel {
+    id: number;
+    name: string;
+}
+/**
+ * GitHub comment shape.
+ */
+interface GitHubComment {
+    body: string;
+    user: {
+        login: string;
+    };
+}
+/**
+ * Minimal GitHub issue/PR shape accepted by the adapter.
+ * Represents pre-fetched data from the GitHub REST or GraphQL API.
+ */
+interface GitHubIssue {
+    id: number;
+    number: number;
+    title: string;
+    body: string | null;
+    labels: GitHubLabel[];
+    state: string;
+    html_url: string;
+    created_at: string;
+    updated_at: string;
+    pull_request: {
+        url: string;
+    } | null;
+    milestone: {
+        id: number;
+        title: string;
+    } | null;
+    assignees: {
+        login: string;
+    }[];
+    comments_data: GitHubComment[];
+    linked_issues: number[];
+}
+/**
+ * Convert a pre-fetched GitHub issue or PR into a generic RawWorkItem.
+ */
+declare function githubToRawWorkItem(issue: GitHubIssue): RawWorkItem;
+
+/**
+ * Linear label shape.
+ */
+interface LinearLabel {
+    id: string;
+    name: string;
+}
+/**
+ * Linear comment shape.
+ */
+interface LinearComment {
+    body: string;
+    user: {
+        name: string;
+    };
+}
+/**
+ * Linear relation shape (blocking/blocked-by/related).
+ */
+interface LinearRelation {
+    type: string;
+    relatedIssue: {
+        id: string;
+        identifier: string;
+    };
+}
+/**
+ * Minimal Linear issue shape accepted by the adapter.
+ * Represents pre-fetched data from the Linear GraphQL API.
+ */
+interface LinearIssue {
+    id: string;
+    identifier: string;
+    title: string;
+    description: string | null;
+    priority: number;
+    state: {
+        id: string;
+        name: string;
+    };
+    labels: {
+        nodes: LinearLabel[];
+    };
+    createdAt: string;
+    updatedAt: string;
+    url: string;
+    branchName: string | null;
+    comments: {
+        nodes: LinearComment[];
+    };
+    relations: {
+        nodes: LinearRelation[];
+    };
+}
+/**
+ * Convert a pre-fetched Linear issue into a generic RawWorkItem.
+ */
+declare function linearToRawWorkItem(issue: LinearIssue): RawWorkItem;
+
+/**
+ * Manual input shape — accepts free-text with optional metadata.
+ */
+interface ManualInput {
+    title: string;
+    description?: string;
+    labels?: string[];
+}
+/**
+ * Convert a manual text input into a generic RawWorkItem.
+ * Generates a unique ID with a `manual-` prefix.
+ */
+declare function manualToRawWorkItem(input: ManualInput): RawWorkItem;
+
+interface AnalysisRequest {
+    prompt: string;
+    systemPrompt?: string;
+    responseSchema: z.ZodType;
+    model?: string;
+    maxTokens?: number;
+}
+interface AnalysisResponse<T> {
+    result: T;
+    tokenUsage: {
+        inputTokens: number;
+        outputTokens: number;
+        totalTokens: number;
+    };
+    model: string;
+    latencyMs: number;
+}
+interface AnalysisProvider {
+    analyze<T>(request: AnalysisRequest): Promise<AnalysisResponse<T>>;
+}
+
+interface AnthropicProviderOptions {
+    apiKey: string;
+    defaultModel?: string;
+}
+/**
+ * AnalysisProvider implementation backed by the Anthropic Messages API.
+ *
+ * Uses the tool_use pattern to extract structured JSON that conforms to
+ * a caller-supplied Zod schema.
+ */
+declare class AnthropicAnalysisProvider implements AnalysisProvider {
+    private readonly client;
+    private readonly defaultModel;
+    constructor(options: AnthropicProviderOptions);
+    analyze<T>(request: AnalysisRequest): Promise<AnalysisResponse<T>>;
+}
+
+interface OpenAICompatibleProviderOptions {
+    /** API key (some local servers accept any string, e.g., 'ollama'). */
+    apiKey: string;
+    /** Base URL for the OpenAI-compatible endpoint (e.g., http://localhost:11434/v1). */
+    baseUrl: string;
+    /** Default model name (e.g., 'deepseek-coder-v2'). */
+    defaultModel?: string;
+    /** Request timeout in ms (default: 90000). */
+    timeoutMs?: number;
+    /**
+     * String appended to user prompts for structured-output requests.
+     * Useful for disabling thinking/reasoning modes (e.g., '/no_think' for Qwen3).
+     */
+    promptSuffix?: string;
+    /**
+     * Whether to send `response_format: { type: 'json_schema' }` with the full
+     * schema to the server for grammar-constrained decoding. When false, relies
+     * on the system prompt alone to produce valid JSON. Default: true.
+     */
+    jsonMode?: boolean;
+}
+/**
+ * AnalysisProvider for OpenAI-compatible endpoints (Ollama, LM Studio, vLLM, etc.).
+ *
+ * Uses JSON mode with a system prompt instructing structured output.
+ * Falls back to parsing raw text as JSON if the model doesn't support
+ * response_format natively.
+ */
+declare class OpenAICompatibleAnalysisProvider implements AnalysisProvider {
+    private readonly client;
+    private readonly defaultModel;
+    private readonly promptSuffix;
+    private readonly jsonMode;
+    constructor(options: OpenAICompatibleProviderOptions);
+    analyze<T>(request: AnalysisRequest): Promise<AnalysisResponse<T>>;
+}
+
+interface ClaudeCliProviderOptions {
+    /** Path to the claude binary (default: 'claude') */
+    command?: string | undefined;
+    /** Model to use (default: let the CLI decide) */
+    defaultModel?: string | undefined;
+    /** Request timeout in ms (default: 180000) */
+    timeoutMs?: number | undefined;
+}
+/**
+ * AnalysisProvider that uses the Claude CLI for structured analysis.
+ *
+ * This avoids the need for an API key — the CLI manages its own
+ * authentication. Structured output is enforced via --json-schema.
+ */
+declare class ClaudeCliAnalysisProvider implements AnalysisProvider {
+    private readonly command;
+    private readonly defaultModel;
+    private readonly timeoutMs;
+    constructor(options?: ClaudeCliProviderOptions);
+    analyze<T>(request: AnalysisRequest): Promise<AnalysisResponse<T>>;
+    private runClaude;
+}
+
+/**
+ * Validates affected systems against the knowledge graph.
+ *
+ * For each system name from the LLM output, searches the graph for matching
+ * module or file nodes and enriches with transitive dependencies, test coverage,
+ * and ownership information.
+ */
+declare class GraphValidator {
+    private readonly store;
+    private cachedModuleNodes;
+    private cachedFileNodes;
+    constructor(store: GraphStore);
+    /**
+     * Validate and enrich a list of affected system names against the graph.
+     */
+    validate(systems: Array<{
+        name: string;
+    }>): AffectedSystem[];
+    private resolveSystem;
+    /**
+     * Simple fuzzy scoring: exact match = 1, contains = 0.7, substring overlap.
+     */
+    private fuzzyScore;
+    private resolveTransitiveDeps;
+    private resolveTestCoverage;
+    private resolveOwner;
+}
+
+/**
+ * Enrich a RawWorkItem into a full EnrichedSpec via LLM analysis and graph validation.
+ *
+ * 1. Calls the AnalysisProvider with SEL prompts and response schema
+ * 2. Parses the LLM response into a partial EnrichedSpec
+ * 3. Validates affected systems against the knowledge graph
+ * 4. Returns a fully populated EnrichedSpec
+ */
+declare function enrich(item: RawWorkItem, provider: AnalysisProvider, graphValidator: GraphValidator): Promise<EnrichedSpec>;
+
+/**
+ * Score an enriched spec using the Complexity Modeling Layer (CML).
+ *
+ * Combines structural (graph-based blast radius), semantic (SEL enrichment
+ * fields), and historical (past execution outcomes) dimensions into a single
+ * {@link ComplexityScore}.
+ */
+declare function score(spec: EnrichedSpec, store: GraphStore): ComplexityScore;
+
+interface StructuralResult {
+    score: number;
+    blastRadius: BlastRadius;
+}
+/**
+ * Compute structural complexity by running CascadeSimulator for every
+ * affected system that has a resolved graph node ID.
+ *
+ * The score is the probability-weighted sum of affected nodes across all
+ * systems, normalized against a ceiling of {@link NORMALIZATION_CEILING}.
+ */
+declare function computeStructuralComplexity(spec: EnrichedSpec, store: GraphStore): StructuralResult;
+
+/**
+ * Compute semantic complexity from the SEL enrichment fields.
+ *
+ * Each dimension uses a diminishing-returns curve `1 - exp(-count * 0.3)`
+ * so that the first few items have the biggest impact and marginal
+ * additions produce less incremental score.
+ *
+ * Returns a value in [0, 1].
+ */
+declare function computeSemanticComplexity(spec: EnrichedSpec): number;
+
+/**
+ * Convert a {@link ComplexityScore} into an array of {@link ConcernSignal}s
+ * that downstream routing logic can use for escalation decisions.
+ *
+ * Returns an empty array when the score is below all thresholds.
+ */
+declare function scoreToConcernSignals(score: ComplexityScore): ConcernSignal[];
+
+/**
+ * Run graph-only pre-execution simulation checks.
+ *
+ * Uses CascadeSimulator blast radius and impact grouping to produce a
+ * SimulationResult without any LLM calls. Intended for quick-fix and
+ * diagnostic tier issues where speed matters.
+ *
+ * Deterministic and fast (<2s for typical graphs).
+ */
+declare function runGraphOnlyChecks(spec: EnrichedSpec, score: ComplexityScore, store: GraphStore): SimulationResult;
+
+/**
+ * Run full LLM pre-execution simulation.
+ *
+ * Combines graph-only checks with LLM-driven plan expansion, failure
+ * injection, and test projection. Intended for guided-change and
+ * simulation-required tier issues.
+ */
+declare function runLlmSimulation(spec: EnrichedSpec, score: ComplexityScore, store: GraphStore, provider: AnalysisProvider, model?: string): Promise<SimulationResult>;
+
+interface PeslSimulatorOptions {
+    /** Override model for PESL LLM calls. */
+    model?: string;
+}
+/**
+ * Top-level PESL simulator that routes to graph-only or full LLM simulation
+ * based on scope tier and CML recommended route.
+ *
+ * Tiered behavior (per D5 in spec):
+ * - quick-fix / diagnostic: graph-only checks (CascadeSimulator + impact)
+ * - guided-change: full LLM simulation (plan expansion, failure injection, test projection)
+ * - simulation-required override: full LLM simulation regardless of tier
+ */
+declare class PeslSimulator {
+    private readonly provider;
+    private readonly store;
+    private readonly options;
+    constructor(provider: AnalysisProvider, store: GraphStore, options?: PeslSimulatorOptions);
+    /**
+     * Run pre-execution simulation for a spec.
+     *
+     * @param spec - Enriched spec from SEL
+     * @param score - Complexity score from CML
+     * @param tier - Scope tier of the issue
+     * @returns SimulationResult with tier, confidence, and abort recommendation
+     */
+    simulate(spec: EnrichedSpec, score: ComplexityScore, tier: ScopeTier): Promise<SimulationResult>;
+}
+
+/** Task type categorization for specialization tracking. */
+type TaskType = 'feature' | 'bugfix' | 'refactor' | 'docs' | 'test' | 'chore';
+/**
+ * Execution outcome -- result of a worker running an issue.
+ * Ingested into the graph as an 'execution_outcome' node.
+ */
+interface ExecutionOutcome {
+    /** Unique ID for this outcome (e.g., `outcome:<issueId>:<attempt>`) */
+    id: string;
+    /** ID of the issue that was executed */
+    issueId: string;
+    /** Human-readable identifier (e.g., 'PROJ-123') */
+    identifier: string;
+    /** Execution result */
+    result: 'success' | 'failure';
+    /** Number of retry attempts before this outcome */
+    retryCount: number;
+    /** Failure reasons (empty for success) */
+    failureReasons: string[];
+    /** Execution duration in milliseconds */
+    durationMs: number;
+    /** ID of the linked EnrichedSpec, if one was produced */
+    linkedSpecId: string | null;
+    /** Affected system graph node IDs from the enriched spec */
+    affectedSystemNodeIds: string[];
+    /** ISO timestamp of when the outcome was recorded */
+    timestamp: string;
+    /**
+     * Optional persona or agent identifier that produced this outcome
+     * (e.g. 'task-executor'). When present the ingestor records it in
+     * the graph node's metadata so effectiveness analytics can attribute
+     * successes and failures to the responsible agent.
+     */
+    agentPersona?: string;
+    /** Task type categorization (e.g., 'feature', 'bugfix', 'refactor', 'docs'). */
+    taskType?: TaskType;
+}
+
+interface OutcomeIngestResult {
+    nodesAdded: number;
+    edgesAdded: number;
+    errors: string[];
+}
+/**
+ * Ingests execution outcomes into the knowledge graph.
+ *
+ * Creates an 'execution_outcome' node for each outcome with metadata
+ * containing result, retry count, failure reasons, duration, and linked
+ * spec ID. Creates 'outcome_of' edges to each affected system node
+ * that exists in the graph.
+ */
+declare class ExecutionOutcomeConnector {
+    private readonly store;
+    constructor(store: GraphStore);
+    ingest(outcome: ExecutionOutcome): OutcomeIngestResult;
+}
+
+/**
+ * Compute historical complexity from past execution outcomes in the graph.
+ *
+ * For each affected system with a graph node ID, queries the graph for
+ * 'execution_outcome' nodes linked via 'outcome_of' edges. Computes
+ * a smoothed failure rate per system, then returns the maximum across
+ * all systems.
+ *
+ * Returns a value in [0, 1]. Returns 0 when no outcomes exist.
+ */
+declare function computeHistoricalComplexity(spec: EnrichedSpec, store: GraphStore): number;
+
+/**
+ * Result of preprocessing an issue through the intelligence pipeline.
+ */
+interface PreprocessResult {
+    /** Enriched spec from SEL, or null if SEL was skipped */
+    spec: EnrichedSpec | null;
+    /** Complexity score from CML, or null if CML was skipped */
+    score: ComplexityScore | null;
+    /** Concern signals derived from complexity score (empty if CML skipped) */
+    signals: ConcernSignal[];
+}
+/**
+ * Composes SEL, CML, and signal conversion into a single pipeline.
+ *
+ * Tier-based behavior:
+ * - `autoExecute` tiers: skip entirely (no LLM cost)
+ * - `alwaysHuman` tiers: run SEL for enrichment context, skip CML (routing already decided)
+ * - `signalGated` tiers: full pipeline (SEL → CML → signals)
+ */
+declare class IntelligencePipeline {
+    private readonly provider;
+    private readonly graphValidator;
+    private readonly store;
+    private readonly simulator;
+    private readonly outcomeConnector;
+    constructor(provider: AnalysisProvider, store: GraphStore, options?: {
+        peslModel?: string;
+    });
+    /**
+     * Enrich a raw work item into an EnrichedSpec via LLM + graph validation.
+     */
+    enrich(item: RawWorkItem): Promise<EnrichedSpec>;
+    /**
+     * Score an enriched spec using graph-based structural + semantic analysis.
+     * Synchronous — no LLM calls.
+     */
+    score(spec: EnrichedSpec): ComplexityScore;
+    /**
+     * Run pre-execution simulation for a spec.
+     */
+    simulate(spec: EnrichedSpec, score: ComplexityScore, tier?: ScopeTier): Promise<SimulationResult>;
+    /**
+     * Record an execution outcome in the knowledge graph.
+     * Called by the orchestrator after a worker exits.
+     */
+    recordOutcome(outcome: ExecutionOutcome): OutcomeIngestResult;
+    /**
+     * Preprocess an issue through the intelligence pipeline.
+     *
+     * Behavior depends on which escalation tier the issue's scope falls into:
+     * - `autoExecute`: returns immediately with null spec/score and empty signals
+     * - `alwaysHuman`: runs SEL for enrichment context (human gets pre-analyzed view),
+     *   skips CML, returns empty signals (routing stays needs-human)
+     * - `signalGated`: runs full SEL → CML → signals pipeline
+     */
+    preprocessIssue(issue: Issue, scopeTier: _harness_engineering_types.ScopeTier, escalationConfig: EscalationConfig): Promise<PreprocessResult>;
+}
+
+/**
+ * Agent Effectiveness Introspection types.
+ *
+ * Given a graph populated with `execution_outcome` nodes (each carrying an
+ * `agentPersona` tag and linked to affected systems via `outcome_of` edges),
+ * these structures describe per-persona accuracy, blind spots, and
+ * persona recommendations for new issues.
+ */
+/**
+ * Smoothed success rate for a single `(persona, systemNodeId)` pair.
+ *
+ * `successRate` uses Laplace smoothing with α = 1:
+ *   (successes + 1) / (successes + failures + 2)
+ *
+ * This matches the bias of `computeHistoricalComplexity` and prevents a
+ * single outcome from claiming 0% or 100% certainty.
+ */
+interface PersonaEffectivenessScore {
+    persona: string;
+    systemNodeId: string;
+    successes: number;
+    failures: number;
+    /** Laplace-smoothed success rate in [0, 1]. */
+    successRate: number;
+    /** Total observations (successes + failures). */
+    sampleSize: number;
+}
+/**
+ * A `(persona, system)` pair where the persona consistently fails.
+ *
+ * Uses the *raw* failure rate `failures / (failures + successes)` so the
+ * thresholds remain intuitive (e.g. "at least 50% failure with 2+ failures").
+ */
+interface BlindSpot {
+    persona: string;
+    systemNodeId: string;
+    failures: number;
+    successes: number;
+    /** Raw failure rate: failures / (failures + successes). */
+    failureRate: number;
+}
+/**
+ * Recommendation for which persona to route a new issue to, given the list
+ * of affected systems (graph node IDs) the issue will touch.
+ *
+ * `score` is the mean Laplace-smoothed success rate across the requested
+ * systems. Systems for which the persona has no history contribute the
+ * neutral prior 0.5, preventing over-confidence on partial data.
+ */
+interface PersonaRecommendation {
+    persona: string;
+    /** Mean smoothed success rate across the requested systems, in [0, 1]. */
+    score: number;
+    /** Number of requested systems with at least one observation for this persona. */
+    coveredSystems: number;
+    /** Number of requested systems with zero history for this persona. */
+    unknownSystems: number;
+    /** Total observations for this persona across the requested systems. */
+    totalSamples: number;
+}
+
+/**
+ * Per-`(persona, systemNodeId)` effectiveness scores.
+ *
+ * Results are sorted by `successRate` descending, then by `sampleSize`
+ * descending, for stable deterministic iteration.
+ */
+declare function computePersonaEffectiveness(store: GraphStore, opts?: {
+    persona?: string;
+    systemNodeId?: string;
+}): PersonaEffectivenessScore[];
+/**
+ * Blind spots: `(persona, system)` pairs where failures accumulate.
+ *
+ * Uses the *raw* failure rate (not smoothed) so thresholds stay intuitive.
+ * A pair must satisfy BOTH `failures >= minFailures` AND
+ * `rawFailureRate >= minFailureRate`.
+ *
+ * Results are sorted by `failureRate` descending, then by `failures` descending.
+ */
+declare function detectBlindSpots(store: GraphStore, opts?: {
+    persona?: string;
+    minFailures?: number;
+    minFailureRate?: number;
+}): BlindSpot[];
+/**
+ * Recommend personas to route a new issue to, given its affected systems.
+ *
+ * For each candidate persona, compute the mean Laplace-smoothed success rate
+ * across `systemNodeIds`. Systems with no observations for the candidate
+ * contribute the neutral prior 0.5.
+ *
+ * When `candidatePersonas` is omitted, the candidate set is the set of
+ * personas with at least one persona-attributed outcome in the graph.
+ * When none exist and no candidates are passed in, returns `[]`.
+ *
+ * Results are sorted by `score` descending, ties broken by `totalSamples`
+ * descending.
+ */
+declare function recommendPersona(store: GraphStore, opts: {
+    systemNodeIds: string[];
+    candidatePersonas?: string[];
+    minSamples?: number;
+}): PersonaRecommendation[];
+
+/**
+ * Persistent Agent Specialization types.
+ *
+ * Extends the effectiveness module with temporal awareness, task-type
+ * categorization, expertise levels, and dynamic persona weighting.
+ */
+
+/** Expertise tier derived from sample size and success rate. */
+type ExpertiseLevel = 'novice' | 'competent' | 'proficient' | 'expert';
+/**
+ * Composite specialization score for a (persona, system, taskType) tuple.
+ * All values are in [0, 1].
+ */
+interface SpecializationScore {
+    /** Temporally-weighted success rate (recent outcomes weighted higher). */
+    temporalSuccessRate: number;
+    /** Consistency score: 1 - stddev of rolling success windows. */
+    consistencyScore: number;
+    /** Volume bonus: log-scaled sample count, capped at 1.0. */
+    volumeBonus: number;
+    /** Composite score: weighted combination of the above. */
+    composite: number;
+}
+/** A single specialization entry for a (persona, system, taskType) bucket. */
+interface SpecializationEntry {
+    persona: string;
+    systemNodeId: string;
+    taskType: string;
+    score: SpecializationScore;
+    expertiseLevel: ExpertiseLevel;
+    sampleSize: number;
+    /** ISO timestamp of most recent outcome in this bucket. */
+    lastOutcome: string;
+}
+/** Full specialization profile for a persona across all systems/task-types. */
+interface SpecializationProfile {
+    persona: string;
+    /** Per-(system, taskType) specialization entries. */
+    entries: SpecializationEntry[];
+    /** Top areas of expertise (highest composite scores). */
+    strengths: SpecializationEntry[];
+    /** Areas of consistent failure. */
+    weaknesses: SpecializationEntry[];
+    /** Overall expertise level across all entries. */
+    overallLevel: ExpertiseLevel;
+    /** ISO timestamp when this profile was computed. */
+    computedAt: string;
+}
+/** Weighted persona recommendation incorporating specialization scores. */
+interface WeightedRecommendation {
+    persona: string;
+    /** Base score from existing recommendPersona(). */
+    baseScore: number;
+    /** Specialization multiplier [0.5, 1.5]. */
+    specializationMultiplier: number;
+    /** Final weighted score: baseScore * specializationMultiplier. */
+    weightedScore: number;
+    /** Expertise level for the requested systems/task-type. */
+    expertiseLevel: ExpertiseLevel;
+    /** Number of requested systems with specialization data. */
+    specializedSystems: number;
+}
+
+/**
+ * Temporal decay functions for specialization scoring.
+ *
+ * Uses exponential decay to weight recent outcomes more heavily than old ones.
+ * The decay formula: weight = e^(-ln(2) / halfLifeDays * ageDays)
+ */
+/** Configuration for temporal decay calculations. */
+interface TemporalConfig {
+    /** Half-life in days (default 30). After this many days, an outcome's weight is halved. */
+    halfLifeDays: number;
+    /** Reference timestamp for decay calculation (default: now). */
+    referenceTime?: string;
+}
+/**
+ * Compute exponential decay weight for an outcome at a given age.
+ * Returns 1.0 at age 0, 0.5 at halfLifeDays, 0.25 at 2*halfLifeDays, etc.
+ */
+declare function decayWeight(ageDays: number, halfLifeDays: number): number;
+/**
+ * Compute temporally-weighted success rate from timestamped outcomes.
+ *
+ * Returns 0.5 (neutral prior) when no outcomes are provided.
+ * Uses Laplace smoothing with decay-weighted pseudo-counts.
+ */
+declare function temporalSuccessRate(outcomes: ReadonlyArray<{
+    result: 'success' | 'failure';
+    timestamp: string;
+}>, config: TemporalConfig): number;
+
+/**
+ * Specialization scorer — computes expertise scores for (persona, system, taskType) tuples.
+ *
+ * Builds on the effectiveness module by adding temporal decay, task-type
+ * categorization, consistency scoring, and dynamic persona weighting.
+ */
+
+interface SpecializationOptions {
+    persona?: string;
+    systemNodeId?: string;
+    taskType?: TaskType;
+    temporal?: TemporalConfig;
+    minSamples?: number;
+}
+/**
+ * Classify expertise level from sample size and success rate.
+ */
+declare function computeExpertiseLevel(sampleSize: number, successRate: number): ExpertiseLevel;
+/**
+ * Compute specialization entries for (persona, system, taskType) tuples.
+ */
+declare function computeSpecialization(store: GraphStore, opts?: SpecializationOptions): SpecializationEntry[];
+/**
+ * Build a full specialization profile for a persona.
+ */
+declare function buildSpecializationProfile(store: GraphStore, persona: string, opts?: Omit<SpecializationOptions, 'persona'>): SpecializationProfile;
+/**
+ * Weighted persona recommendation incorporating specialization scores.
+ *
+ * Wraps the existing `recommendPersona()` and applies specialization
+ * multipliers to produce weighted scores.
+ */
+declare function weightedRecommendPersona(store: GraphStore, opts: {
+    systemNodeIds: string[];
+    taskType?: TaskType;
+    candidatePersonas?: string[];
+    minSamples?: number;
+    temporal?: TemporalConfig;
+}): WeightedRecommendation[];
+
+/**
+ * Profile persistence — load/save specialization profiles to disk.
+ *
+ * Profiles are stored at `.harness/specialization-profiles.json` and survive
+ * across sessions so agents retain their accumulated expertise.
+ */
+
+/** Persisted store of specialization profiles. */
+interface ProfileStore {
+    profiles: Record<string, SpecializationProfile>;
+    computedAt: string;
+    version: 1;
+}
+/** Load profiles from disk. Returns empty store if file doesn't exist. */
+declare function loadProfiles(projectRoot: string): ProfileStore;
+/** Save profiles to disk at .harness/specialization-profiles.json. */
+declare function saveProfiles(projectRoot: string, store: ProfileStore): void;
+/**
+ * Recompute and persist profiles for all personas with outcomes.
+ *
+ * Discovers all persona names from execution_outcome nodes in the graph,
+ * builds a specialization profile for each, and saves the result.
+ */
+declare function refreshProfiles(projectRoot: string, graphStore: GraphStore, opts?: Omit<SpecializationOptions, 'persona'>): ProfileStore;
+
+export { type AffectedSystem, type AnalysisProvider, type AnalysisRequest, type AnalysisResponse, AnthropicAnalysisProvider, type BlastRadius, type BlindSpot, ClaudeCliAnalysisProvider, type ComplexityScore, type EnrichedSpec, type ExecutionOutcome, ExecutionOutcomeConnector, type ExpertiseLevel, type GitHubIssue, GraphValidator, IntelligencePipeline, type JiraIssue, type LinearIssue, type ManualInput, OpenAICompatibleAnalysisProvider, type OutcomeIngestResult, type PersonaEffectivenessScore, type PersonaRecommendation, PeslSimulator, type PreprocessResult, type ProfileStore, type RawWorkItem, type SimulationResult, type SpecializationEntry, type SpecializationProfile, type SpecializationScore, type TaskType, type TemporalConfig, type WeightedRecommendation, buildSpecializationProfile, computeExpertiseLevel, computeHistoricalComplexity, computePersonaEffectiveness, computeSemanticComplexity, computeSpecialization, computeStructuralComplexity, decayWeight, detectBlindSpots, enrich, githubToRawWorkItem, jiraToRawWorkItem, linearToRawWorkItem, loadProfiles, manualToRawWorkItem, recommendPersona, refreshProfiles, runGraphOnlyChecks, runLlmSimulation, saveProfiles, score as scoreCML, scoreToConcernSignals, temporalSuccessRate, toRawWorkItem, weightedRecommendPersona };