@harness-engineering/intelligence 0.6.0 → 0.7.0

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import * as _harness_engineering_types from '@harness-engineering/types';
-import { Issue, ConcernSignal, ScopeTier, EscalationConfig, ComplexityLevel, ComplexityVerdict, CapabilityTier, RoutingRisk, RoutingPolicy } from '@harness-engineering/types';
+import { Issue, ConcernSignal, ScopeTier, EscalationConfig, ComplexityLevel, ComplexityVerdict, CapabilityTier, RoutingRisk, RoutingPolicy, RoutingTaskText } from '@harness-engineering/types';
 import { z } from 'zod';
 import { GraphStore } from '@harness-engineering/graph';
 
@@ -1491,4 +1491,623 @@ declare function deriveRequiredTier(complexity: ComplexityVerdict, risk: Routing
 /** Flatten signals into the ComplexityVerdict.signals map, dropping undefined fields. */
 declare function serializeSignals(s: ComplexitySignals): Record<string, number | boolean | string>;
 
-export { ACCEPTANCE_EVAL_SYSTEM_PROMPT, type AcceptanceEvalInput, AcceptanceEvaluator, type AcceptanceEvaluatorOptions, type AcceptanceVerdict, type AffectedSystem, type AnalysisProvider, type AnalysisRequest, type AnalysisResponse, AnthropicAnalysisProvider, type Authority, type BlastRadius, type BlindSpot, type CanaryAdapter, type CanaryDegradeReason, type CanaryExec, type CanaryFinding, type CanaryProbe, type ClassifyInput, ClaudeCliAnalysisProvider, type ComplexityScore, type ComplexitySignals, type Confidence, DEFAULT_DEGRADE_AT_PCT, type EnrichedSpec, type ExecutionOutcome, ExecutionOutcomeConnector, type ExpertiseLevel, type Finding, type FrameworkRecommendation, type GitHubIssue, GraphValidator, IntelligencePipeline, type JiraIssue, type JudgedAgainst, type LinearIssue, type LlmAcceptanceVerdict, type LlmVerdict, type ManualInput, type Measurability, OUTCOME_EVAL_SYSTEM_PROMPT, OpenAICompatibleAnalysisProvider, type OutcomeEvalInput, OutcomeEvaluator, type OutcomeEvaluatorOptions, type OutcomeIngestResult, type OutcomeVerdict, type PersonaEffectivenessScore, type PersonaRecommendation, PeslSimulator, type Phase, type PreprocessResult, type ProfileStore, RANK_TIER, type RawWorkItem, type ResolvedSection, SENSITIVE_BLAST_THRESHOLD, STATIC_WEIGHTS, type SimulationResult, type SpecializationEntry, type SpecializationProfile, type SpecializationScore, type StaticVerdict, TIER_RANK, type TaskType, type TemporalConfig, type TiebreakResult, type Verdict, type WeightedRecommendation, acceptanceVerdictSchema, applyBudgetClamp, baseTier, blastRadiusVeto, buildUserPrompt as buildAcceptanceUserPrompt, buildSpecializationProfile, buildUserPrompt$1 as buildUserPrompt, classify, computeExpertiseLevel, computeHistoricalComplexity, computePersonaEffectiveness, computeSemanticComplexity, computeSpecialization, computeStructuralComplexity, createCanaryAdapter, decayWeight, deriveAcceptanceAuthority, deriveAuthority, deriveRequiredTier, detectBlindSpots, enrich, findingSchema, githubToRawWorkItem, jiraToRawWorkItem, linearToRawWorkItem, llmTiebreak, loadProfiles, manualToRawWorkItem, recommendPersona, refreshProfiles, resolveSection, runGraphOnlyChecks, runLlmSimulation, runStaticPass, saveProfiles, score as scoreCML, scoreToConcernSignals, serializeSignals, temporalSuccessRate, toRawWorkItem, verdictSchema, weightedRecommendPersona };
+/**
+ * Escalation category for a triaged item — the reason a non-dispatched item was
+ * held (SC-F2's closed set) or the routing bucket a dispatched item fell into.
+ * Part of the `shapeKey` so precedent base-rates aggregate like-for-like work.
+ */
+type EscalationCategory = 'not-in-band' | 'unresolved-scope' | 'open-decision' | 'halted-fork' | 'precedent-contradicts' | 'error' | 'dispatchable';
+/** Autonomy-ratchet stage in effect at dispatch (D14). 1 = human before execution. */
+type RatchetStage = 1 | 2 | 3 | 4;
+/**
+ * The pre-diff prediction, written by Phase 3 at dispatch. It is the confidence-capped
+ * (S3-001) claim the post-diff retrospective later grades against ground truth.
+ */
+interface TriagePrediction {
+    /** The pre-diff prediction being made (level + confidence-capped verdict). */
+    verdict: ComplexityVerdict;
+    /**
+     * An OPAQUE DIAGNOSTIC SNAPSHOT of the probe's signals at dispatch (today: the
+     * verdict's static `signals` map) — kept for human forensics, NOT a grading input.
+     * It is deliberately NOT the typed Phase-1 `ProbeLevers`: the Phase-4 retrospective
+     * comparator grades on `verdict.level` + `scopeEstimate` ONLY (see
+     * `retrospective.ts`) and never reads this field, so its shape can vary without
+     * affecting the grade. Threading the full typed `ProbeLevers` end-to-end was
+     * rejected as unneeded coupling (the marker's `ReadyCandidate` has no consumer for
+     * it). If a future lever genuinely needs to inform grading, promote it to a typed
+     * field here rather than smuggling it through this untyped bag.
+     */
+    levers: Record<string, unknown>;
+    /** Predicted blast radius (estimated post-diff scope from the scope lever). */
+    scopeEstimate: number;
+    /** Ratchet stage in effect when this item was dispatched. */
+    ratchetStage: RatchetStage;
+}
+/**
+ * The post-diff outcome, written by Phase 4 at the retrospective. This is the only
+ * gate that sees ground truth; its verdict is what feeds the precedent lever (D13).
+ */
+interface TriageOutcome {
+    /** Full-strength post-diff verdict on the ACTUAL diff (confidence may reach high). */
+    actual: ComplexityVerdict;
+    /** 0 = matched the prediction; >0 = mispredict magnitude (over-scope). */
+    exceededBy: number;
+    /** True when the actual diff stayed within the predicted band. */
+    matched: boolean;
+}
+/**
+ * The accreting triage record for one roadmap item. `prediction`/`outcome` are
+ * absent until the owning phase writes its slice; a record with a populated
+ * `outcome` is a graded, precedent-eligible record.
+ */
+interface TriageRecord {
+    /** Stable item key (roadmap `External-ID`). */
+    externalId: string;
+    /** Bucketing key for precedent/ratchet aggregation (see {@link shapeKey}). */
+    shapeKey: string;
+    /** Written by Phase 3 at dispatch. */
+    prediction?: TriagePrediction;
+    /** Written by Phase 4 at the retrospective. */
+    outcome?: TriageOutcome;
+    /** ISO timestamp stamped by the writer (not by shapeKey). */
+    ts: string;
+}
+/**
+ * The precedent lever (P1 injects this; P4 implements the real one). A pure read over
+ * records sharing a `shapeKey` with a populated `outcome`: success rate = matched / total.
+ * Absent history ⇒ `unknown` (the P1 degrade-empty path), which is simply "no records
+ * for this shape yet" — never a block on emptiness.
+ */
+interface PrecedentLookup {
+    /**
+     * Measured autonomous-success rate for the given shape, or `unknown` when no
+     * outcome-bearing records exist for it (cold-start).
+     */
+    rateForShape(shapeKey: string): PrecedentRate;
+}
+/**
+ * The precedent lever's result: a measured base-rate over recorded outcomes, or
+ * `unknown` on cold-start (no outcome-bearing records for the shape yet).
+ */
+type PrecedentRate = {
+    readonly kind: 'unknown';
+} | {
+    readonly kind: 'rate';
+    readonly matched: number;
+    readonly total: number;
+    readonly rate: number;
+};
+/**
+ * The bucketing key for precedent/ratchet aggregation:
+ *   `sortedLabels + '|' + escalationCategory + '|' + predictedLevel`.
+ *
+ * Deterministic and label-order-independent: labels are de-duplicated, trimmed of
+ * empties, and sorted before joining, so `['a','b']` and `['b','a']` (and
+ * `['b','a','a']`) all bucket identically. This is the quiet linchpin — too coarse
+ * lumps unlike work (unsafe base-rates), too fine leaves every item its own bucket
+ * (precedent perpetually `unknown`). Phase 4 calibration revisits this granularity
+ * first; the definition lives here so P1 and P4 never disagree.
+ */
+declare function shapeKey(labels: readonly string[], category: EscalationCategory, level: ComplexityLevel): string;
+/**
+ * The `dispatchable`-bucket shapeKey — the ONE convention prediction and outcome must agree on.
+ *
+ * A dispatched/approved item is (by definition) dispatchable, so its precedent/ratchet bucket is
+ * `shapeKey(labels, 'dispatchable', level)`. That spelling was previously re-typed at three sites
+ * (the probe's precedent lookup, the CLI approve gate, the orchestrator marker); if any drifted —
+ * or keyed off a different `level` source — the PREDICTION and the OUTCOME would bucket into
+ * DIFFERENT shapes and silently break precedent aggregation. Centralizing it here makes that
+ * divergence impossible: all three call this with the SAME level (the probe's `verdict.level`).
+ */
+declare function dispatchableShapeKey(labels: readonly string[], level: ComplexityLevel): string;
+
+/**
+ * Base-rate for a single shape over the supplied records. Counts only outcome-bearing
+ * records matching `shapeKey`; returns `unknown` when there are none (cold-start).
+ */
+declare function aggregatePrecedent(records: readonly TriageRecord[], shapeKey: string): PrecedentRate;
+/**
+ * Build a {@link PrecedentLookup} backed by a fixed record set — the real precedent
+ * lever Phase 4 injects once outcomes exist. With no outcome-bearing records for a
+ * shape it returns `unknown`, so an empty set yields the Phase-1 cold-start behavior
+ * for every shape.
+ */
+declare function precedentLookupFromRecords(records: readonly TriageRecord[]): PrecedentLookup;
+
+/**
+ * Extract candidate entity mentions (symbol/path names) from roadmap-row text.
+ *
+ * Pure and deterministic: returns de-duplicated candidates in first-seen order across
+ * the four strategies. Returns an EMPTY array when the text carries none of the
+ * structured shapes — the explicit "no entities found" signal P1 relies on (it becomes
+ * `unresolved-scope`, never a fallback). Non-string / empty input ⇒ `[]`.
+ */
+declare function extractEntities(text: string): string[];
+
+/**
+ * One lever's result. Every lever either produces a concrete value or degrades to the
+ * literal `'unknown'` (never throwing out of the probe), carrying an optional `reason`
+ * that feeds the verdict's `rationale`. A degraded lever LOWERS corroboration; it never
+ * forces a pass (proposal §"any lever that returns 'unknown' lowers the corroboration
+ * score rather than forcing a pass").
+ */
+interface LeverResult<T> {
+    /** The lever's value, or the literal `'unknown'` when it could not be determined. */
+    value: T | 'unknown';
+    /** Human-legible note (why it degraded, or a one-line summary of the finding). */
+    reason?: string;
+}
+/** A single resolved-entity scope datum from the graph seam. */
+interface ResolvedEntity {
+    /** The raw candidate that resolved (as emitted by extractEntities). */
+    candidate: string;
+    /** The graph node id it resolved to. */
+    nodeId: string;
+    /** Estimated blast radius (affected-node count) from the graph for this entity. */
+    blastRadius: number;
+}
+/**
+ * The scope lever's value: the graph-grounded scope estimate. `resolved` is the subset
+ * of candidates that ACTUALLY resolved in the graph — extractEntities over-generates
+ * (it emits `e.g`/`i.e` noise and other non-symbols), so a non-empty extraction is NOT
+ * itself "scope resolved" (follow-up S3). Only resolved candidates count. When `resolved`
+ * is empty the scope is unresolved and the item is not dispatchable (`unresolved-scope`).
+ */
+interface ScopeEstimate {
+    /** Candidates emitted by the extractor (pre-resolution). */
+    candidates: readonly string[];
+    /** The subset that resolved against the graph (empty ⇒ unresolved scope). */
+    resolved: readonly ResolvedEntity[];
+    /** Aggregate estimated blast radius across resolved entities (max, the worst case). */
+    blastRadius: number;
+    /** Distinct architectural layers the resolved entities touch (feeds ComplexitySignals). */
+    layersTouched: number;
+    /** Count of resolved entities (proxy for filesTouched into the static pass). */
+    filesTouched: number;
+}
+/**
+ * The injected graph-resolution seam. The pure probe NEVER touches a GraphStore — it is
+ * handed this. It maps a candidate entity string to a resolved node + blast radius, or
+ * `null` when the candidate does not resolve (vague/non-symbol candidate). The wiring
+ * layer (orchestrator/CLI) implements it over GraphStore + CascadeSimulator; tests stub
+ * it. This is the S3 seam: raw-string resolution is NOT cleanly exposed by the graph
+ * package, so it lives behind this injected boundary rather than inside the probe.
+ */
+interface GraphScope {
+    /**
+     * Resolve a candidate entity mention to a graph node + blast radius, or `null` if it
+     * does not resolve. May be sync or async; the probe awaits it. MUST NOT throw — but
+     * the probe still guards it (any throw degrades the scope lever to `unknown`).
+     */
+    resolve(candidate: string): ResolvedEntity | null | Promise<ResolvedEntity | null>;
+}
+/**
+ * The open-decisions self-assessment the semantic-read lever surfaces: the human/agent
+ * boundary. Any open decision requiring human judgment (API shape, product tradeoff,
+ * irreversible/outward action) → not dispatchable, regardless of complexity band.
+ */
+interface OpenDecision {
+    /** Short description of the choice requiring human judgment. */
+    question: string;
+}
+/** The closed set of reasons a non-dispatchable item was held (mirrors EscalationCategory). */
+type HoldReason$1 = 'not-in-band' | 'unresolved-scope' | 'open-decision' | 'read-incomplete' | 'precedent-contradicts' | 'error';
+/**
+ * Input to the pure probe for one roadmap item. Built from an `Issue` in the wiring
+ * layer (reusing `buildTaskText`) — the probe stays orchestrator-free and unit-testable.
+ */
+interface ProbeInput {
+    /** Stable item identity (roadmap External-ID). Absent ⇒ not dispatch-eligible. */
+    externalId: string;
+    /** Pre-diff text-only signals (title+description length, spec/acceptance hints, prompt). */
+    taskText: RoutingTaskText;
+    /** Candidate entity mentions from the item text (from `extractEntities`) — pre-resolution. */
+    entityCandidates: readonly string[];
+    /** Item labels (for shapeKey bucketing / precedent lookup). */
+    labels: readonly string[];
+    /** Whether the item's risk band is high (drives the classifier's standard-tier tie-break). */
+    riskHigh?: boolean;
+}
+/** The per-lever bundle carried on every verdict (SC-O1 traceability). */
+interface ProbeLevers {
+    /** Scope lever: graph-grounded scope estimate (or `unknown` on degrade). */
+    scope: LeverResult<ScopeEstimate>;
+    /** Semantic-read lever: the local-model complexity read (or `unknown`). */
+    semanticRead: LeverResult<ComplexityVerdict>;
+    /** Open-decisions lever: surfaced human-judgment choices (or `unknown`). */
+    openDecisions: LeverResult<readonly OpenDecision[]>;
+    /** Precedent lever: measured base-rate for this shape (or `unknown` at cold-start). */
+    precedent: LeverResult<PrecedentRate>;
+}
+/**
+ * The probe's output for one item. `dispatchable` is TRUE only when scope is bounded AND
+ * the semantic read agrees trivial|simple (the eligible band) AND confidence ≥ medium AND
+ * there are no open decisions AND precedent does not contradict. Any shortfall or lever
+ * error fails safe to `dispatchable:false` with a legible `holdReason` + `rationale`.
+ */
+interface TriageVerdict {
+    /** The item this verdict is for. */
+    externalId: string;
+    /** The corroborated complexity verdict (from the semantic read, or a conservative degrade). */
+    verdict: ComplexityVerdict;
+    /** Authorization decision: only true when all levers corroborate (see the gate above). */
+    dispatchable: boolean;
+    /** The single legible reason it was held (absent when `dispatchable`). SC-F2 closed set. */
+    holdReason?: HoldReason$1;
+    /** All four levers' results (SC-O1 traceability). */
+    levers: ProbeLevers;
+    /** Human-legible corroboration narrative (per-lever notes joined). */
+    rationale: string;
+}
+
+/** Tunable gate seeds (a subset of the Phase-0 `roadmap.autoTriage.thresholds`). */
+interface ProbeConfig {
+    /** Blast-radius ceiling for a "bounded" scope (seed). */
+    boundedScopeMax: number;
+    /** Minimum semantic-read confidence to clear the gate (the S3-001 pre-diff bar). */
+    dispatchConfidence: 'low' | 'medium' | 'high';
+    /**
+     * Precedent block bar: a MEASURED rate at-or-below this contradicts and holds the item.
+     * Default 0 — only a shape that has NEVER succeeded autonomously blocks; `unknown`
+     * (cold-start) never blocks. Conservative-by-construction (proposal §precedent lever).
+     */
+    precedentBlockRate?: number;
+    /** Minimum recorded sample before a precedent rate is trusted to block (seed). Default 1. */
+    precedentMinSample?: number;
+}
+/** Injected dependencies for the pure probe. All optional — absent ⇒ that lever degrades. */
+interface ProbeDeps {
+    /** The SEL analysis provider for the semantic-read + open-decisions levers. Absent ⇒ offline. */
+    provider?: AnalysisProvider;
+    /** The graph-resolution seam for the scope lever. Absent ⇒ scope degrades to unknown. */
+    graph?: GraphScope;
+    /** The precedent lever. Absent ⇒ `unknown` (cold-start), which never blocks. */
+    precedent?: PrecedentLookup;
+    /** Gate seeds. Absent fields fall back to conservative defaults. */
+    config?: Partial<ProbeConfig>;
+    /** Optional model overrides threaded to the classifier tie-break. */
+    models?: {
+        fast?: string;
+        standard?: string;
+    };
+}
+/**
+ * Run the pure four-lever scoping probe for one roadmap item. Never throws.
+ */
+declare function runScopingProbe(input: ProbeInput, deps?: ProbeDeps): Promise<TriageVerdict>;
+
+/** A candidate to rank: its identity plus the three pilot-score inputs. */
+interface RankableCandidate {
+    /** Stable item identity (roadmap External-ID) — the final deterministic tiebreak. */
+    externalId: string;
+    /** Business impact (higher = more valuable). Also the secondary sort key (D4). */
+    impact: number;
+    /** Confidence in the estimate (higher = surer). */
+    confidence: number;
+    /** Estimated effort (higher = costlier). Guarded against divide-by-zero. */
+    effort: number;
+}
+/**
+ * The roadmap-pilot score: `(impact × confidence) ÷ effort`. Total — an effort of 0 (or
+ * negative) is clamped to a small positive so the score is finite rather than Infinity/NaN,
+ * keeping the sort deterministic.
+ */
+declare function pilotScore(c: Pick<RankableCandidate, 'impact' | 'confidence' | 'effort'>): number;
+/**
+ * Rank candidates by pilot score descending, breaking ties by IMPACT descending (SC7),
+ * then by `externalId` ascending for a fully deterministic total order. Pure: returns a
+ * new array; the input is never mutated.
+ */
+declare function rankTriageCandidates<T extends RankableCandidate>(candidates: readonly T[]): T[];
+
+/** Self-assessed confidence in a fork recommendation. Mirrors the AMR tie-break enum. */
+type ForkConfidence = 'high' | 'medium' | 'low';
+/**
+ * One decision fork the brainstorm surfaces: a design choice with mutually-exclusive
+ * options. The runner asks the generator to recommend a default for each; a fork it can't
+ * confidently recommend is the no-go trigger (SC2). `id` orders forks deterministically.
+ */
+interface Fork {
+    /** Stable fork identity within a brainstorm (e.g. 'storage-backend'). Orders the loop. */
+    id: string;
+    /** The question this fork decides (human-legible; carried into a halt handoff). */
+    question: string;
+    /** The mutually-exclusive options considered (at least one; usually 2–3). */
+    options: readonly string[];
+}
+/**
+ * The generator's decision on a single fork: which option it recommends, how confident it
+ * is (AFTER any self-consistency downgrade), and why. Mirrors `tiebreak.ts` structured
+ * output `{ recommendation, confidence, rationale }` — the schema the SEL provider fills.
+ */
+interface ForkDecision {
+    /** The fork this decision answers. */
+    fork: Fork;
+    /** The recommended option (should be one of `fork.options`). */
+    recommendation: string;
+    /**
+     * Self-assessed confidence — the gate input. `high` is the ONLY value that auto-accepts;
+     * `medium`/`low` halt (SC2). The generator MUST force this to `low` when self-consistency
+     * sampling shows the recommendation flipped across samples (overconfidence hardening).
+     */
+    confidence: ForkConfidence;
+    /** Why this option, in one or two sentences (carried into the spec draft / halt handoff). */
+    rationale: string;
+}
+/**
+ * The injected seam that generates + decides one fork at a time. The pure runner calls this
+ * `depth.maxForks` times (or until it returns `null`, signalling "no more forks — done").
+ *
+ * `index` is the 0-based position in the brainstorm (the runner tracks depth). Returning
+ * `null` means the brainstorm has enumerated every fork it needs — the runner then COMPLETES.
+ * A thrown error is caught by the runner and mapped to `halted{ reason: 'error' }` (SC5):
+ * the generator is allowed to throw; the runner is total.
+ *
+ * Overconfidence hardening (self-consistency) is the GENERATOR's contract: it samples the
+ * underlying model N times per fork and, if the recommendation flips, returns the decision
+ * with `confidence: 'low'`. Keeping it in the generator (behind this seam) makes it testable
+ * with a stub that reports a flip → the pure runner still just reads the enum and halts.
+ */
+interface ForkGenerator {
+    /**
+     * Produce the next fork's decision, or `null` when there are no more forks. May be async.
+     * MAY throw — the runner catches it and halts with `reason: 'error'`.
+     */
+    next(index: number, priorDecisions: readonly ForkDecision[]): ForkDecision | null | Promise<ForkDecision | null>;
+}
+/**
+ * The depth budget: how many forks the brainstorm may explore, scaled by the Phase-1
+ * complexity estimate (SC3). A `trivial` item runs a shallow pass; `simple` a fuller one.
+ * Bounded so a typo never gets the full 4-phase treatment. The runner NEVER exceeds
+ * `maxForks` — if the generator keeps producing forks past the budget, the loop stops and
+ * completes with what it has (the budget is a ceiling, not a required count).
+ */
+interface DepthBudget {
+    /** Hard ceiling on forks explored. Bounded (e.g. trivial→2, simple→4). Always ≥ 1. */
+    maxForks: number;
+}
+/** Map a Phase-1 complexity level to a bounded brainstorm depth (SC3). */
+declare const DEPTH_BY_LEVEL: Record<ComplexityLevel, DepthBudget>;
+/** Resolve the bounded depth budget for a complexity level (SC3 depth-scaling). */
+declare function depthForLevel(level: ComplexityLevel): DepthBudget;
+/**
+ * A proposal-shaped spec draft accumulated from the accepted fork decisions on clean
+ * completion. Intentionally lightweight (the wiring layer renders it to a proposal.md);
+ * the pure core only accumulates the resolved decisions + a title/summary.
+ */
+interface SpecDraft {
+    /** The item this spec is for (roadmap External-ID / identifier). */
+    externalId: string;
+    /** A short title (from the item). */
+    title: string;
+    /** One-line summary of the item. */
+    summary: string;
+    /** Every fork the brainstorm resolved, in order — the spec's decision record. */
+    decisions: readonly ForkDecision[];
+}
+/**
+ * The input to one brainstorm run: the item identity + text the generator reasons over,
+ * plus the Phase-1 complexity level that scales the depth. Pure — no provider, no IO.
+ */
+interface BrainstormInput {
+    /** Stable item identity (roadmap External-ID / identifier). */
+    externalId: string;
+    /** Short title (carried into the spec draft). */
+    title: string;
+    /** One-line summary / description (carried into the spec draft + fed to the generator). */
+    summary: string;
+    /** The Phase-1 complexity level — scales the depth budget (SC3). */
+    level: ComplexityLevel;
+}
+/** Why a brainstorm halted — the closed no-go set handed to a human. */
+type HaltReason = 'low-confidence' | 'error';
+/**
+ * The single outcome of a brainstorm run (SC1): either a clean COMPLETION carrying the spec
+ * draft, or a HALT carrying the fork it stopped at + the reason. Exactly one of the two.
+ * A halt is a REAL handoff — never a rubber-stamped stub (proposal §"a halt is a real
+ * handoff, not a rubber stamp").
+ */
+type BrainstormOutcome = {
+    kind: 'completed';
+    spec: SpecDraft;
+} | {
+    kind: 'halted';
+    fork: Fork;
+    reason: HaltReason;
+    detail: string;
+};
+
+/**
+ * Drive an autonomous brainstorm for one item. Returns exactly one `BrainstormOutcome`
+ * (SC1): `completed{ spec }` when every explored fork was confidently recommended, or
+ * `halted{ fork, reason }` at the first fork it couldn't. NEVER throws (SC5).
+ *
+ * @param input     the item identity + text + Phase-1 level
+ * @param generator the injected fork-decision seam (the thing that calls the model)
+ * @param depth     the bounded fork budget (SC3 — scaled from the complexity level upstream)
+ */
+declare function runAutoBrainstorm(input: BrainstormInput, generator: ForkGenerator, depth: DepthBudget): Promise<BrainstormOutcome>;
+
+/** Ordinal rank of each complexity band; a positive delta = the diff came in harder. */
+declare const LEVEL_RANK: Record<ComplexityLevel, number>;
+/**
+ * Blast-radius overrun tolerance. The actual blast radius may exceed the predicted
+ * scope estimate by up to `BLAST_TOLERANCE_FACTOR×` PLUS `BLAST_TOLERANCE_ABS` before
+ * it counts as over-scope. The additive floor keeps a tiny predicted scope (e.g. 1–2)
+ * from tripping on ordinary noise; the factor bounds the overrun on larger estimates.
+ * Conservative on purpose (plan §Concerns: bias `exceededBy` toward flagging).
+ */
+declare const BLAST_TOLERANCE_FACTOR = 1.5;
+declare const BLAST_TOLERANCE_ABS = 2;
+/** The comparator's verdict for one graded item. */
+interface RetrospectiveComparison {
+    /** True iff the actual diff stayed WITHIN the predicted band + scope (SC2). */
+    matched: boolean;
+    /**
+     * Mispredict magnitude. `0` when matched. When over-scope it is the level-band
+     * delta (≥ 1) when the level exceeded, else `1` for a blast-only overrun — always
+     * a positive integer so a graded outcome carries a legible severity.
+     */
+    exceededBy: number;
+    /** `verify` on a match (surface for human verify per stage); `block-escalate` on a mismatch/error. */
+    action: 'verify' | 'block-escalate';
+}
+/** Tunable comparator thresholds (wired from `roadmap.autoTriage.thresholds`, SC2). */
+interface RetrospectiveConfig {
+    /**
+     * The level-band delta that counts as a mispredict. Default 1 (any band over the
+     * prediction blocks). Raising it tolerates a wider band drift before escalating —
+     * conservative default keeps the honesty check tight (plan §Concerns).
+     */
+    exceededByBands: number;
+}
+/** The default comparator config: any band over the prediction is a mispredict. */
+declare const DEFAULT_RETROSPECTIVE_CONFIG: RetrospectiveConfig;
+/**
+ * Compare the stored pre-diff prediction to the full-strength post-diff verdict.
+ *
+ * Returns `{ matched, exceededBy, action }`. Match ⇒ `verify`; mismatch ⇒
+ * `block-escalate`. A missing/garbled/invalid prediction OR actual fails safe to
+ * `block-escalate` (SC7) — absence is never a pass.
+ */
+declare function compareToPrediction(prediction: TriagePrediction | undefined | null, postDiffVerdict: ComplexityVerdict | undefined | null, config?: RetrospectiveConfig): RetrospectiveComparison;
+
+/** The autonomy-ratchet stages v1 can resolve. 3/4 are deferred post-v1 (SC4). */
+type V1Stage = 1 | 2;
+/** v1's ceiling: the resolver never returns above this (SC4 — stages 3/4 deferred). */
+declare const V1_MAX_STAGE: 2;
+/** One graded outcome for a shape. `matched` is the grade; `ts` fixes chronology. */
+interface RatchetOutcome {
+    /** True iff the post-diff verdict stayed within the prediction (the comparator's `matched`). */
+    matched: boolean;
+    /**
+     * ISO timestamp the outcome was graded (FOLLOW-UP 1 / safety). The mispredict-reset keys on the
+     * CHRONOLOGICALLY-latest outcome, so `resolveStage` sorts by `ts` first. Optional for
+     * back-compat: the sort is a stable no-op when `ts` is absent (already-chronological callers).
+     */
+    ts?: string;
+}
+/** Advancement rules. Conservative defaults; the caller may override per policy. */
+interface RatchetConfig {
+    /** Minimum trailing-window success-rate required to advance from stage 1 → 2 (SC6). */
+    threshold: number;
+    /** Minimum number of graded outcomes in the window before advancement is even considered. */
+    minSample: number;
+    /** Trailing-window size: only the most recent `window` outcomes count (recency ⇒ a mispredict resets). */
+    window: number;
+}
+/**
+ * Conservative default policy: a shape must show ≥ 90% matches over its most recent
+ * 10 graded outcomes (at least `minSample` of them) before it earns stage 2. A single
+ * recent mispredict inside a 10-wide window is 90% → still at the edge; two drop it below.
+ */
+declare const DEFAULT_RATCHET_CONFIG: RatchetConfig;
+/**
+ * Resolve the autonomy stage a shape has EARNED from its graded history.
+ *
+ * Returns stage 1 (the safe default) at cold-start, below `minSample`, or whenever
+ * the trailing-window success-rate is under `threshold` (a recent mispredict resets).
+ * Returns stage 2 once the evidence clears the bar. NEVER returns above
+ * {@link V1_MAX_STAGE} (SC4) — the value is clamped as a belt-and-suspenders guard so
+ * a future config change can't accidentally leak a deferred stage.
+ */
+declare function resolveStage(history: readonly RatchetOutcome[], config?: RatchetConfig): V1Stage;
+
+/**
+ * The escalation categories that may auto-execute (mirror of the orchestrator's
+ * `EscalationConfig.autoExecute` default — proposal §"Dispatch path" reuses the
+ * shipped escalation categories rather than inventing a parallel taxonomy). An
+ * item whose category is NOT in this set stays human even after a human go (SC3):
+ * `guided-change` is signal-gated and `full-exploration` is always-human.
+ *
+ * Defined as a frozen set here (not imported from orchestrator) to keep this gate
+ * in the intelligence layer; the orchestrator's escalation default is the source of
+ * truth for the VALUES, and the T3 wiring is where the two are reconciled against
+ * the live `config.agent.escalation.autoExecute`.
+ */
+declare const AUTO_EXECUTE_CATEGORIES: ReadonlySet<ScopeTier>;
+/**
+ * One ready candidate presented to the go/no-go gate. Built in the wiring layer from
+ * a Phase-2 spec-bearing, re-scored-dispatchable item; the gate reads only the three
+ * fields that decide authorization.
+ */
+interface GoNoGoCandidate {
+    /** Stable item key (roadmap External-ID). */
+    externalId: string;
+    /** The item's escalation category (the routing bucket it fell into). */
+    category: ScopeTier;
+    /**
+     * Whether a human has EXPLICITLY approved this item in the batched go/no-go. The
+     * quiet linchpin of stage 1: absent this flag no item is ever approved — the gate
+     * never manufactures a go. Set by the `triage approve` command (Phase 3 T4).
+     */
+    humanApproved: boolean;
+}
+/** Why a candidate was held rather than approved. A closed, legible set (SC-F2 style). */
+type HoldReason = 
+/** The candidate's EFFECTIVE stage is deferred post-v1 (3-4); v1 caps at stage 2. */
+'ratchet-stage-unsupported'
+/** The item's category is not auto-executable (guided-change / full-exploration). */
+ | 'not-auto-executable'
+/** Auto-executable, but no human has given the go yet (stage-1 default hold). */
+ | 'awaiting-human-go';
+/** A held candidate: the item plus the single legible reason it did not pass. */
+interface HeldCandidate {
+    externalId: string;
+    category: ScopeTier;
+    reason: HoldReason;
+}
+/** An approved candidate carrying the EVIDENCE-DERIVED stage its shape earned (SC6). */
+interface ApprovedCandidate extends GoNoGoCandidate {
+    /**
+     * The effective autonomy stage this candidate's SHAPE earned from its recorded history
+     * (`min(resolveStage(history), configuredCeiling, 2)`). 1 = human-before-execution (the
+     * cold-start default); 2 = auto-execute + required human-verify (v1's ceiling). This governs
+     * only DOWNSTREAM match-handling/advancement — NOT the authorization above (which is stage-
+     * independent: humanApproved AND auto-executable). The marker stamps it onto the prediction.
+     */
+    effectiveStage: 1 | 2;
+}
+/** The gate's output: the partition of the ready set into approved vs held. */
+interface GoNoGoDecision {
+    /** Items cleared for the marker: human-approved AND auto-executable, with the earned stage. */
+    approved: ApprovedCandidate[];
+    /** Everything else, each carrying the reason it was held to a human. */
+    held: HeldCandidate[];
+}
+/**
+ * One ready candidate presented to the PER-SHAPE go/no-go gate: the base candidate plus the
+ * effective autonomy stage its shape earned from recorded evidence. The caller resolves the
+ * stage per-shape (via the pure `resolveStage` over that shape's history) so the ratchet
+ * advances INDEPENDENTLY per shape (SC6), never as one batch stage.
+ */
+interface StagedGoNoGoCandidate extends GoNoGoCandidate {
+    /** `min(resolveStage(historyForShape), configuredCeiling, 2)`. Cold-start ⇒ 1. */
+    effectiveStage: RatchetStage;
+}
+/**
+ * Pure go/no-go partition with a PER-CANDIDATE evidence-derived stage (SC6).
+ *
+ * The AUTHORIZATION rule is stage-INDEPENDENT and unchanged from Phase 3: an item is
+ * `approved` iff its category is in {@link AUTO_EXECUTE_CATEGORIES} AND a human explicitly
+ * approved it. The stage does NOT relax this — the human-go requirement holds at every stage.
+ * The stage only rides ALONG on an approved item (`effectiveStage`) to govern downstream
+ * match-handling/advancement; a candidate whose earned stage is deferred post-v1 (3-4) is
+ * refused as `ratchet-stage-unsupported` (a fail-safe belt: the caller already clamps to ≤ 2,
+ * so this should be unreachable, but a mis-set stage must never loosen the gate).
+ *
+ * Ordering of the hold reasons is deliberate and matches Phase 3: the stage guard is checked
+ * first (a deferred stage refuses regardless), then the category gate (structural), then the
+ * human-go gate — so an approved non-autoExecute item still reads `not-auto-executable`.
+ */
+declare function resolveGoNoGoStaged(candidates: readonly StagedGoNoGoCandidate[]): GoNoGoDecision;
+/**
+ * Pure go/no-go partition for a UNIFORM ratchet stage (Phase 3 shape, retained for callers
+ * that have not yet resolved per-shape evidence). Delegates to {@link resolveGoNoGoStaged} by
+ * stamping the SAME `stage` on every candidate — so the authorization + hold-reason ordering
+ * is defined in exactly one place. Passing a deferred stage (3-4) refuses the whole batch, and
+ * stage 1 reproduces Phase-3 behavior byte-for-byte.
+ */
+declare function resolveGoNoGo(candidates: readonly GoNoGoCandidate[], stage: RatchetStage): GoNoGoDecision;
+
+export { ACCEPTANCE_EVAL_SYSTEM_PROMPT, AUTO_EXECUTE_CATEGORIES, type AcceptanceEvalInput, AcceptanceEvaluator, type AcceptanceEvaluatorOptions, type AcceptanceVerdict, type AffectedSystem, type AnalysisProvider, type AnalysisRequest, type AnalysisResponse, AnthropicAnalysisProvider, type ApprovedCandidate, type Authority, BLAST_TOLERANCE_ABS, BLAST_TOLERANCE_FACTOR, type BlastRadius, type BlindSpot, type BrainstormInput, type BrainstormOutcome, type CanaryAdapter, type CanaryDegradeReason, type CanaryExec, type CanaryFinding, type CanaryProbe, type ClassifyInput, ClaudeCliAnalysisProvider, type ComplexityScore, type ComplexitySignals, type Confidence, DEFAULT_DEGRADE_AT_PCT, DEFAULT_RATCHET_CONFIG, DEFAULT_RETROSPECTIVE_CONFIG, DEPTH_BY_LEVEL, type DepthBudget, type EnrichedSpec, type EscalationCategory, type ExecutionOutcome, ExecutionOutcomeConnector, type ExpertiseLevel, type Finding, type Fork, type ForkConfidence, type ForkDecision, type ForkGenerator, type FrameworkRecommendation, type GitHubIssue, type GoNoGoCandidate, type GoNoGoDecision, type HoldReason as GoNoGoHoldReason, type GraphScope, GraphValidator, type HaltReason, type HeldCandidate, type HoldReason$1 as HoldReason, IntelligencePipeline, type JiraIssue, type JudgedAgainst, LEVEL_RANK, type LeverResult, type LinearIssue, type LlmAcceptanceVerdict, type LlmVerdict, type ManualInput, type Measurability, OUTCOME_EVAL_SYSTEM_PROMPT, OpenAICompatibleAnalysisProvider, type OpenDecision, type OutcomeEvalInput, OutcomeEvaluator, type OutcomeEvaluatorOptions, type OutcomeIngestResult, type OutcomeVerdict, type PersonaEffectivenessScore, type PersonaRecommendation, PeslSimulator, type Phase, type PrecedentLookup, type PrecedentRate, type PreprocessResult, type ProbeConfig, type ProbeDeps, type ProbeInput, type ProbeLevers, type ProfileStore, RANK_TIER, type RankableCandidate, type RatchetConfig, type RatchetOutcome, type RatchetStage, type RawWorkItem, type ResolvedEntity, type ResolvedSection, type RetrospectiveComparison, type RetrospectiveConfig, SENSITIVE_BLAST_THRESHOLD, STATIC_WEIGHTS, type ScopeEstimate, type SimulationResult, type SpecDraft, type SpecializationEntry, type SpecializationProfile, type SpecializationScore, type StagedGoNoGoCandidate, type StaticVerdict, TIER_RANK, type TaskType, type TemporalConfig, type TiebreakResult, type TriageOutcome, type TriagePrediction, type TriageRecord, type TriageVerdict, type V1Stage, V1_MAX_STAGE, type Verdict, type WeightedRecommendation, acceptanceVerdictSchema, aggregatePrecedent, applyBudgetClamp, baseTier, blastRadiusVeto, buildUserPrompt as buildAcceptanceUserPrompt, buildSpecializationProfile, buildUserPrompt$1 as buildUserPrompt, classify, compareToPrediction, computeExpertiseLevel, computeHistoricalComplexity, computePersonaEffectiveness, computeSemanticComplexity, computeSpecialization, computeStructuralComplexity, createCanaryAdapter, decayWeight, depthForLevel, deriveAcceptanceAuthority, deriveAuthority, deriveRequiredTier, detectBlindSpots, dispatchableShapeKey, enrich, extractEntities, findingSchema, githubToRawWorkItem, jiraToRawWorkItem, linearToRawWorkItem, llmTiebreak, loadProfiles, manualToRawWorkItem, pilotScore, precedentLookupFromRecords, rankTriageCandidates, recommendPersona, refreshProfiles, resolveGoNoGo, resolveGoNoGoStaged, resolveSection, resolveStage, runAutoBrainstorm, runGraphOnlyChecks, runLlmSimulation, runScopingProbe, runStaticPass, saveProfiles, score as scoreCML, scoreToConcernSignals, serializeSignals, shapeKey, temporalSuccessRate, toRawWorkItem, verdictSchema, weightedRecommendPersona };