import type { WorkflowHudSummary } from "../skill-state/active-state";
import { type RepositoryBinding } from "./repository-binding";
import { type CriticVerdict } from "./ultragoal-receipt-freshness";
export { CRITIC_GATE_HARD_STOP_EVENT, CRITIC_GATE_OVERRIDE_EVENT, CRITIC_VERDICT_EVENT, type CriticVerdict, computeUltragoalPlanGeneration, countTerminalCriticVerdicts, receiptRelevantGoals, TERMINAL_CRITIC_CEILING, terminalCriticCeilingReached, terminalCriticGateOverridden, } from "./ultragoal-receipt-freshness";
import { type UltragoalChangeSet } from "./ultragoal-change-set";
export { categorizeComputerChangePath, ciDevChangedPathRows, computeCheckpointChangeSet, computeUltragoalReviewSourceHash, mergeChangeSetPaths, normalizeChangeSetPath, normalizeRepoPath, parseGitNameStatus, parseGitUntrackedPaths, parseUnifiedDiffPaths, resolveGitBase, spawnText, type UltragoalChangeCategory, type UltragoalChangeSet, type UltragoalChangeSetPath, type UltragoalChangeStatus, } from "./ultragoal-change-set";
export { captureUltragoalRecoverySnapshot, parseStrictTerminalTranscript, persistUltragoalRecoveryDecision, planUltragoalOwnerLossRecovery, type UltragoalOwnerLossReceipt, type UltragoalRecoveryBinding, type UltragoalRecoveryDecision, type UltragoalRecoverySnapshot, validateOwnerLossBinding, validateRawUltragoalEvidence, validateRecoveryAdmission, validateRecoveryPath, } from "./ultragoal-owner-loss-recovery";
export type UltragoalGjcGoalMode = "aggregate" | "per-story";
export type UltragoalGoalStatus = "pending" | "active" | "complete" | "failed" | "blocked" | "review_blocked" | "superseded";
export interface UltragoalValidationBatchMetadata extends JsonObject {
    schemaVersion: 1;
    batchId: string;
    memberIds: string[];
    finalGoalId: string;
    mode: "aggregate-only";
    metadataHash: string;
}
export interface UltragoalValidationBatchInput {
    schemaVersion: 1;
    batchId: string;
    memberIds: string[];
    finalGoalId: string;
}
export interface UltragoalGoal {
    id: string;
    title: string;
    objective: string;
    status: UltragoalGoalStatus;
    createdAt: string;
    updatedAt: string;
    startedAt?: string;
    completedAt?: string;
    evidence?: string;
    steering?: Record<string, unknown>;
    completionVerification?: UltragoalCompletionVerification;
    validationBatch?: UltragoalValidationBatchMetadata;
}
export interface UltragoalPlan {
    version: 1;
    brief: string;
    gjcGoalMode: UltragoalGjcGoalMode;
    gjcObjective: string;
    gjcObjectiveAliases?: string[];
    goals: UltragoalGoal[];
    /** Authoritative repository identity for multi-repo fail-closed spawn (#2901). */
    repositoryBinding?: RepositoryBinding;
    createdAt: string;
    updatedAt: string;
    [key: string]: unknown;
}
export type UltragoalReceiptKind = "per-goal" | "final-aggregate";
export interface UltragoalCompletionVerification {
    schemaVersion: 1;
    receiptId: string;
    verifiedAt: string;
    goalId: string;
    receiptKind: UltragoalReceiptKind;
    goalStatusBeforeCheckpoint: UltragoalGoalStatus;
    gjcGoalMode: UltragoalGjcGoalMode;
    gjcObjective: string;
    qualityGateHash: string;
    planGeneration: string;
    basis: {
        planHashBeforeCheckpoint: string;
        latestRelevantLedgerEventIdBeforeCheckpoint: string | null;
        goalUpdatedAtBeforeCheckpoint: string;
        relevantGoalIdsBeforeCheckpoint: string[];
        requiredGoalSetHashBeforeCheckpoint: string;
    };
    checkpointLedgerEventId: string;
    validationBatch?: {
        schemaVersion: 1;
        role: "deferred-member";
        batchId: string;
        memberIds: string[];
        finalGoalId: string;
        metadataHash: string;
        changeSetHash: string;
    } | {
        schemaVersion: 1;
        role: "batch-close";
        batchId: string;
        memberIds: string[];
        finalGoalId: string;
        memberMetadataHashes: Record<string, string>;
        memberReceiptIds: Record<string, string>;
        memberCheckpointLedgerEventIds: Record<string, string>;
        memberChangeSetHashes: Record<string, string>;
        unionHash: string;
    };
}
export interface UltragoalLedgerEvent extends JsonObject {
    eventId?: string;
    event?: string;
    goalId?: string;
    timestamp?: string;
}
export type UltragoalNudgeSurface = "pause" | "drop" | "ask" | "premature_complete";
export type UltragoalNudgeTargetKind = "story" | "final_aggregate_receipt";
export interface UltragoalNudgeLedgerEvent extends UltragoalLedgerEvent {
    event: "nudge";
    goalId: string;
    targetKind: UltragoalNudgeTargetKind;
    surface: UltragoalNudgeSurface;
    attempt: number;
    budget: number;
    reason: string;
    currentGoalObjective?: string;
}
export interface UltragoalNudgeTarget {
    goalId: string;
    targetKind: UltragoalNudgeTargetKind;
}
export type UltragoalNudgeOutcome = {
    nudged: true;
    attempt: number;
    budget: number;
    goalId: string;
    targetKind: UltragoalNudgeTargetKind;
    event: UltragoalNudgeLedgerEvent;
} | {
    nudged: false;
    exhausted: true;
    count: number;
    budget: number;
    goalId: string;
    targetKind: UltragoalNudgeTargetKind;
} | {
    nudged: false;
    inactive: true;
    reason: string;
};
export interface UltragoalPaths {
    dir: string;
    briefPath: string;
    goalsPath: string;
    ledgerPath: string;
}
export interface UltragoalStatusSummary {
    exists: boolean;
    status: "missing" | "pending" | "active" | "complete" | "blocked" | "failed";
    paths: UltragoalPaths;
    gjcObjective?: string;
    currentGoal?: UltragoalGoal;
    counts: Record<UltragoalGoalStatus, number>;
    goals: UltragoalGoal[];
    nudgeBudget?: number;
    nudgeCount?: number;
    nudgeRemaining?: number;
    nudgeGoalId?: string;
    nudgeTargetKind?: UltragoalNudgeTargetKind;
}
export interface UltragoalCommandResult {
    reviewBlockerGoalIds?: string[];
    createdReviewPlan?: boolean;
    status: number;
    stdout?: string;
    stderr?: string;
    createdPlan?: boolean;
}
export interface JsonObject {
    [key: string]: unknown;
}
export declare function currentUltragoalSessionId(cwd: string): string;
export declare const PASSED_STATUS = "passed";
export declare function hashStructuredValue(value: unknown): string;
export declare function getUltragoalPaths(cwd: string, sessionId?: string | null): UltragoalPaths;
export declare function isEnoent(error: unknown): boolean;
export declare function appendLedger(cwd: string, event: JsonObject, sessionId?: string | null): Promise<UltragoalLedgerEvent>;
export declare function readUltragoalLedger(cwd: string, sessionId?: string | null): Promise<UltragoalLedgerEvent[]>;
export declare const DEFAULT_ULTRAGOAL_NUDGE_BUDGET = 10;
/** Pure: count ledger `nudge` rows for an exact goalId. */
export declare function countUltragoalNudges(ledger: readonly UltragoalLedgerEvent[], goalId: string): number;
/**
 * Resolve the per-story nudge budget through the shared five-layer resolver.
 * Ultragoal stays tolerant: an invalid optional settings file continues to the
 * next layer and finally to the built-in default (10).
 */
export declare function resolveUltragoalNudgeBudget(cwd: string, agentDir?: string): Promise<{
    budget: number;
    source: string;
}>;
/**
 * Pure canonical selector shared by guards and status so `nudgeGoalId` can never
 * diverge between what a guard consumes and what status displays. Prefers the active
 * current-goal objective, then active > pending > failed (matching `chooseNextGoal`),
 * then the aggregate final-receipt target when all stories are complete but the
 * aggregate run still needs a final receipt. Returns null for verified-complete or
 * absent/unrelated plans.
 */
export declare function selectUltragoalNudgeTarget(plan: UltragoalPlan, options?: {
    currentGoalObjective?: string;
    retryFailed?: boolean;
}): UltragoalNudgeTarget | null;
/**
 * Atomic consuming writer. Locks the ledger path, rereads + counts nudge rows for the
 * target story, and appends exactly one `nudge` row inside the same critical section
 * only while budget remains. Reuses the lockless `appendLedger` inside the lock (it
 * does not acquire a conflicting lock), so concurrent guarded attempts cannot both
 * observe `count = budget - 1` and overshoot the budget.
 */
export declare function recordUltragoalNudgeIfBudgetRemaining(input: {
    cwd: string;
    sessionId?: string | null;
    target: UltragoalNudgeTarget;
    surface: UltragoalNudgeSurface;
    budget: number;
    reason: string;
    currentGoalObjective?: string;
}): Promise<UltragoalNudgeOutcome>;
export declare function writePlan(cwd: string, plan: UltragoalPlan, sessionId?: string | null): Promise<void>;
export declare function nonEmptyString(value: unknown): string | null;
export declare function stringArray(value: unknown): string[] | null;
export declare function readUltragoalPlan(cwd: string, sessionId?: string | null): Promise<UltragoalPlan | null>;
export declare function getUltragoalStatus(cwd: string, sessionId?: string | null, agentDir?: string): Promise<UltragoalStatusSummary>;
export declare function buildUltragoalHudSummary(summary: UltragoalStatusSummary, latestLedger?: UltragoalLedgerEvent): WorkflowHudSummary;
export declare function createUltragoalPlan(input: {
    cwd: string;
    brief: string;
    gjcGoalMode?: UltragoalGjcGoalMode;
    sessionId?: string | null;
    validationBatches?: UltragoalValidationBatchInput[];
    validationBatchJson?: string;
}): Promise<UltragoalPlan>;
export interface UltragoalRunCompletionState {
    requiredGoals: UltragoalGoal[];
    incompleteGoals: UltragoalGoal[];
    nextGoal?: UltragoalGoal;
    allComplete: boolean;
    hasBlockers: boolean;
    needsFinalAggregateReceipt: boolean;
}
export declare function getUltragoalRunCompletionState(plan: UltragoalPlan, options?: {
    retryFailed?: boolean;
}): UltragoalRunCompletionState;
/**
 * Discriminated next-action for `complete-goals` handoff (#2903).
 * `none` is reserved for genuine completion; `execute-goal` always carries a goal.
 */
export type UltragoalCompleteNextActionKind = "none" | "execute-goal" | "retry-failed" | "resolve-blockers" | "final-aggregate-receipt";
export type UltragoalCompleteNextAction = {
    kind: UltragoalCompleteNextActionKind;
    goal?: UltragoalGoal;
    blockedGoals?: UltragoalGoal[];
    failedGoals?: UltragoalGoal[];
};
/**
 * Resolve the actionable next step after scheduling / complete-goals.
 * Blocked and review_blocked goals remain unschedulable; they surface as
 * `resolve-blockers` instead of a contradictory `execute-goal` without goal_id.
 */
export declare function resolveUltragoalCompleteNextAction(plan: UltragoalPlan, options?: {
    retryFailed?: boolean;
    selectedGoal?: UltragoalGoal;
}): UltragoalCompleteNextAction;
export declare function startNextUltragoalGoal(input: {
    cwd: string;
    retryFailed?: boolean;
    sessionId?: string | null;
}): Promise<{
    plan: UltragoalPlan;
    goal?: UltragoalGoal;
    allComplete: boolean;
    nextAction: UltragoalCompleteNextAction;
}>;
export declare function qualityGateObject(value: unknown): JsonObject | null;
export declare function nonEmptyStringArray(value: unknown): string[] | null;
export interface UltragoalQualityGateDiagnostic {
    path: string;
    code: string;
    message: string;
}
/**
 * Collects every quality-gate defect in one pass instead of throwing on the first.
 * Authoring a valid gate is otherwise an edit/retry loop at the most expensive phase
 * of a run (#3474). The aggregate error message keeps each individual message verbatim
 * so existing callers and assertions that match on a single message still work, and
 * `diagnostics` carries the machine-readable stable `path` + `code` pairs.
 */
export declare class UltragoalQualityGateError extends Error {
    readonly diagnostics: readonly UltragoalQualityGateDiagnostic[];
    constructor(diagnostics: readonly UltragoalQualityGateDiagnostic[]);
}
export declare function requireQualityGateObject(value: unknown, fieldName: string): JsonObject;
export declare function requireObjectArray(value: unknown, fieldName: string): JsonObject[];
export declare function requiredStringField(row: JsonObject, key: string, fieldName: string): string;
export declare function requireStringLinks(value: unknown, fieldName: string): string[];
export declare function requireResolvedLinks(ids: string[], map: Map<string, JsonObject>, fieldName: string): void;
export declare function normalizedEvidenceKind(row: JsonObject): string;
export declare function evidenceKindMatches(kind: string, words: string[]): boolean;
export type SurfaceFamily = "web" | "cli" | "native" | "api-package" | "algorithm-math" | "unknown";
export declare function normalizeSurfaceToken(value: string): string;
export declare function surfaceFamily(value: string): SurfaceFamily;
export declare function isLiveSurfaceFamily(family: SurfaceFamily): boolean;
export declare function isSubstantiveEvidence(value: unknown): boolean;
export declare function hasTypedVerifiedReceipt(value: unknown): boolean;
export declare function hasExistingNonEmptyArtifact(cwd: string, value: unknown): Promise<boolean>;
export declare function readArtifactBytes(cwd: string, row: JsonObject, fieldName: string): Promise<Buffer | null>;
import { resolveCliReplayCommand, validateArtifactProof, validateCliReplay, validateLiveSurfaceProofPresence, validateReplayExemptFallback, validateStructuralArtifact, validateSurfaceStructuralRequirement, waitForReplayProcessWithTimeout } from "./ultragoal-evidence";
export type { ReplayProcessHandle } from "./ultragoal-evidence";
export { resolveCliReplayCommand, validateArtifactProof, validateCliReplay, validateLiveSurfaceProofPresence, validateReplayExemptFallback, validateStructuralArtifact, validateSurfaceStructuralRequirement, waitForReplayProcessWithTimeout, };
export declare function validateExecutorQaRedTeamEvidenceForReview(cwd: string, executorQa: Record<string, unknown>, options?: {
    mode?: "review";
    changeSet?: UltragoalChangeSet;
}): Promise<void>;
/**
 * Scaffold a schema-shaped quality-gate template for selected surfaces (#3474).
 * The template is intentionally incomplete for live artifact proofs so `quality-gate
 * validate` can report remaining evidence gaps in one pass after the author fills paths.
 */
export declare function buildQualityGateInitTemplate(surfaces: readonly string[]): JsonObject;
/**
 * Read-only quality-gate validation (#3474). Applies exactly the same rules as
 * `checkpoint --status complete` — including deferred-vs-boundary gate selection and
 * artifact existence checks — but never touches `goals.json`, `ledger.jsonl`, or goal
 * state, and reports every diagnostic in one run instead of the first failure.
 */
export declare function validateUltragoalQualityGateReadOnly(input: {
    cwd: string;
    qualityGateJson: string;
    goalId?: string;
    sessionId?: string | null;
}): Promise<{
    valid: boolean;
    errors: readonly UltragoalQualityGateDiagnostic[];
}>;
export declare function checkpointUltragoalGoal(input: {
    cwd: string;
    goalId: string;
    status: UltragoalGoalStatus;
    evidence: string;
    qualityGateJson?: string;
}): Promise<UltragoalPlan>;
export interface UltragoalCheckpointContinuation {
    plan: UltragoalPlan;
    checkpointedGoal: UltragoalGoal;
    nextGoal?: UltragoalGoal;
    startedNext: boolean;
    allComplete: boolean;
    incompleteGoals: UltragoalGoal[];
}
export declare function checkpointAndContinueUltragoalGoal(input: {
    cwd: string;
    goalId: string;
    status: UltragoalGoalStatus;
    evidence: string;
    qualityGateJson?: string;
    advanceNext?: boolean;
    retryFailed?: boolean;
}): Promise<UltragoalCheckpointContinuation>;
export declare function addUltragoalSubgoal(input: {
    cwd: string;
    title: string;
    objective: string;
    evidence: string;
    rationale: string;
}): Promise<UltragoalPlan>;
export declare function recordUltragoalReviewBlockers(input: {
    cwd: string;
    goalId: string;
    title: string;
    objective: string;
    evidence: string;
}): Promise<{
    plan: UltragoalPlan;
    blockerGoalId: string;
}>;
export type UltragoalBlockerClassification = "human_blocked" | "resolvable";
/**
 * Record an audited blocker triage classification in the durable ledger. Pause
 * requires the latest `blocker_classified` event to be `human_blocked` and a
 * later clean pause terminal critic verdict bound to that classification; `resolvable`
 * is an audit note and never unblocks pause.
 */
export declare function recordUltragoalBlockerClassification(input: {
    cwd: string;
    classification: UltragoalBlockerClassification;
    evidence: string;
    goalId?: string;
}): Promise<UltragoalLedgerEvent>;
export declare function recordUltragoalCriticVerdict(input: {
    cwd: string;
    terminus: "completion" | "pause";
    verdict: CriticVerdict;
    evidence: string;
    blockers?: string[];
    goalId?: string;
    classificationEventId?: string;
}): Promise<UltragoalLedgerEvent>;
export declare function recordUltragoalCriticGateOverride(input: {
    cwd: string;
    evidence: string;
}): Promise<UltragoalLedgerEvent>;
type UltragoalReviewContractStrength = "strong" | "thin-derived";
interface UltragoalReviewFinding extends JsonObject {
    severity: "blocker";
    message: string;
}
interface UltragoalReviewResult extends JsonObject {
    verdict: "pass" | "fail" | "inconclusive: weak-contract";
    contractStrength: UltragoalReviewContractStrength;
    cleanPassEligible: boolean;
    source: JsonObject;
    findings: UltragoalReviewFinding[];
    artifactValidationSummary: JsonObject;
    weakContractCapApplied: boolean;
    blockerGoalIds?: string[];
}
/**
 * Typed terminal handoff thrown when {@link recordUltragoalReviewBlockers} would
 * exceed {@link MAX_REVIEW_BLOCKER_DESCENTS} unresolved review_blocker descents
 * off a single blocked goal (#3613). Never silently marks unresolved technical
 * findings complete; the operator/leader must pause and escalate.
 */
export declare class UltragoalReviewBlockerRecursionCapError extends Error {
    readonly code: "review_blocker_recursion_cap";
    readonly blockedGoalId: string;
    readonly unresolvedDescents: number;
    readonly cap: number;
    constructor(blockedGoalId: string, unresolvedDescents: number, cap?: number);
}
export declare function runUltragoalReview(cwd: string, args: readonly string[]): Promise<UltragoalReviewResult>;
export declare function runNativeUltragoalCommand(args: string[], cwd?: string, options?: {
    agentDir?: string;
}): Promise<UltragoalCommandResult>;