/**
 * Task completion logic.
 * @task T4461
 * @epic T4454
 */
import type { Task, TaskRecord, TaskRef } from '@cleocode/contracts';
import { type EngineResult } from '../engine-result.js';
import { type AutoCompleteWorktreeResult } from '../orchestrate/worktree-complete.js';
import type { DataAccessor, TransactionAccessor } from '../store/data-accessor.js';
/** Options for completing a task. */
export interface CompleteTaskOptions {
    taskId: string;
    notes?: string;
    changeset?: string;
    /** Reason for acknowledging CRITICAL impact risk (bypasses nexusImpact gate). */
    acknowledgeRisk?: string;
    /**
     * Reason for overriding the `E_EPIC_HAS_PENDING_CHILDREN` guard.
     *
     * When provided, `cleo complete <epicId>` is allowed even if the epic still
     * has pending or active children. The override is audited to
     * `.cleo/audit/premature-close.jsonl` (ADR-051 pattern).
     *
     * @task T1632
     */
    overrideReason?: string;
    /**
     * Comma-separated AC tokens (UUIDs or `AC<n>` aliases) that the caller
     * waives from the AC-coverage gate (T10509). Each token MUST resolve to
     * an AC row on the task. The {@link waiveReason} is mandatory whenever
     * this field is set; supplying `waiveAc` without `waiveReason` is rejected
     * with `E_AC_COVERAGE_INCOMPLETE`.
     *
     * Waivers are recorded to `.cleo/audit/ac-waiver.jsonl` for forensic
     * traceability per ADR-079-r4 §4.
     *
     * @task T10509
     * @saga T10377 (SG-IVTR-AC-BINDING)
     */
    waiveAc?: string;
    /**
     * Justification text for the {@link waiveAc} waiver. Mandatory whenever
     * `waiveAc` is non-empty. Captured verbatim in the audit row.
     *
     * @task T10509
     */
    waiveReason?: string;
    /**
     * Reason for waiving the `E_CANCELLED_CHILD_NO_WAIVER` gate (PM-Core V2
     * design-point 4). When a parent has `cancelled` children, completion is
     * blocked unless this waiver is supplied: a cancelled child represents work
     * that was NOT done, so it must not silently satisfy parent completion.
     *
     * When set, the waiver is audited to `.cleo/audit/cancelled-child-waiver.jsonl`.
     * Cite a replacement task id in the reason when the cancelled work was
     * superseded by other done work.
     *
     * @saga T10538 (PM-Core V2 agent-trust)
     */
    cancelledChildWaiverReason?: string;
    /**
     * Reason for waiving the `E_CLEO_DEPENDENCY` gate when this task's own work
     * is done but its `depends` edges point at not-yet-terminal tasks (a stale or
     * over-specified dependency). When set, completion proceeds despite the
     * unresolved depends edges and the decision is audited to
     * `.cleo/audit/depends-waiver.jsonl`.
     *
     * @task T11954 (DHQ-071)
     */
    waiveDependsReason?: string;
}
/**
 * Summary of the llmtxt ContributionReceipt emitted when wrapping
 * completion in an AgentSession (T947). The full receipt is persisted
 * to `.cleo/audit/receipts.jsonl`; here we surface only the
 * correlation fields the CLI needs for display.
 */
export interface TaskCompletionReceiptSummary {
    /** 128-bit unguessable session id from llmtxt. */
    receiptId: string;
    /** Ed25519 signature (present for RemoteBackend; stub until llmtxt T461). */
    signature?: string;
}
/** Result of completing a task. */
export interface CompleteTaskResult {
    task: Task;
    autoCompleted?: string[];
    unblockedTasks?: Array<Pick<TaskRef, 'id' | 'title'>>;
    /**
     * llmtxt ContributionReceipt correlation (T947). Absent when the
     * AgentSession adapter degraded to a no-op (peer deps missing) or
     * when running in VITEST with no audit layer.
     */
    receipt?: TaskCompletionReceiptSummary;
}
/**
 * Check whether an epic has sufficient evidence to complete.
 *
 * An epic satisfies the evidence requirement if ANY of the following is true:
 * 1. It has at least one direct evidence atom on any verification gate.
 * 2. All of its children (excluding cancelled) have `status='done'` AND
 *    `verification.passed=true`.
 *
 * Returns `true` when the epic may proceed; `false` when it must be rejected.
 *
 * @param task - The epic task to check.
 * @param acc - Data accessor used to load children.
 * @returns `true` when evidence is sufficient; `false` otherwise.
 * @task T1404
 */
export declare function verifyEpicHasEvidence(task: Task, acc: DataAccessor): Promise<boolean>;
/**
 * Execute the task-completion critical section under the tasks DB write lock.
 *
 * The concrete SQLite accessor backs `transaction()` with `BEGIN IMMEDIATE` at
 * the outermost boundary, so the AC completion gate and status/autoclose writes
 * run in one atomic write transaction instead of validating on a stale read
 * snapshot and flipping `status='done'` later.
 *
 * @task T10595
 */
export declare function withTaskWriteTransaction<T>(accessor: DataAccessor, fn: (tx: TransactionAccessor) => Promise<T>): Promise<T>;
/**
 * Complete a task by ID.
 * Handles dependency checking and optional auto-completion of epics.
 * @task T4461
 */
export declare function completeTask(options: CompleteTaskOptions, cwd?: string, accessor?: DataAccessor): Promise<CompleteTaskResult>;
interface CompleteEngineSuccess {
    task: TaskRecord;
    autoCompleted?: string[];
    unblockedTasks?: Array<{
        id: string;
        title: string;
    }>;
    /**
     * T9548 — Auto-invoke worktree-complete diagnostic envelope.
     *
     * Populated when `cleo complete <taskId>` runs and the auto-invoke hook
     * either runs the worktree-integration SDK or short-circuits (no worktree
     * exists, `CLEO_NO_AUTO_WORKTREE_COMPLETE=1`, or SDK threw). Absent when
     * task completion itself failed (no auto-merge is attempted on failure).
     *
     * @task T9548
     */
    worktreeAutoComplete?: AutoCompleteWorktreeResult;
}
type CompleteEngineResult = EngineResult<CompleteEngineSuccess>;
/**
 * Options forwarded through the EngineResult-returning wrappers.
 *
 * These mirror the fields in {@link CompleteTaskOptions} that need to flow
 * from CLI → dispatch domain → core. Adding them here keeps the two layers
 * in sync without requiring a breaking change to the public `CompleteTaskOptions`
 * interface.
 *
 * @task T1632
 */
export interface TaskCompleteEngineOptions {
    /** Completion notes. */
    notes?: string;
    /**
     * Reason for overriding the `E_EPIC_HAS_PENDING_CHILDREN` guard.
     * @see CompleteTaskOptions.overrideReason
     */
    overrideReason?: string;
    /** Reason for acknowledging CRITICAL nexus impact risk. */
    acknowledgeRisk?: string;
    /**
     * Comma-separated AC tokens (UUIDs or `AC<n>` aliases) waived from the
     * AC-coverage gate. {@link waiveReason} is mandatory whenever this is set.
     * @see CompleteTaskOptions.waiveAc
     * @task T10509
     */
    waiveAc?: string;
    /**
     * Justification text for the {@link waiveAc} waiver.
     * @see CompleteTaskOptions.waiveReason
     * @task T10509
     */
    waiveReason?: string;
    /**
     * Reason for waiving the `E_CANCELLED_CHILD_NO_WAIVER` gate.
     * @see CompleteTaskOptions.cancelledChildWaiverReason
     * @saga T10538 (PM-Core V2 agent-trust)
     */
    cancelledChildWaiverReason?: string;
    /**
     * Reason for waiving the `E_CLEO_DEPENDENCY` gate on stale/over-specified
     * depends edges.
     * @see CompleteTaskOptions.waiveDependsReason
     * @task T11954 (DHQ-071)
     */
    waiveDependsReason?: string;
}
/**
 * Complete a task (set status to done), wrapped in EngineResult.
 *
 * Stamps modified_by + session_id provenance on successful completion
 * (T1222 / CLEO-VALID-27).
 *
 * @param projectRoot - Absolute path to the project root
 * @param taskId - Task identifier to complete
 * @param notesOrOptions - Completion notes (string, legacy) OR an options object
 * @returns EngineResult with the completed task, auto-completed parents, and unblocked tasks
 *
 * @task T1568
 * @task T1632
 * @epic T1566
 */
export declare function taskComplete(projectRoot: string, taskId: string, notesOrOptions?: string | TaskCompleteEngineOptions): Promise<CompleteEngineResult>;
/**
 * Complete a task with strict IVTR + evidence-staleness enforcement.
 *
 * Enforcement path (T832 / ADR-051 Decision 3+8):
 * 1. Evidence staleness re-check: every verification.evidence record is re-validated.
 * 2. IVTR enforcement in strict mode: ivtr_state.currentPhase MUST be 'released'.
 * 3. Parent-epic lifecycle gate: child task completion is blocked while the parent
 *    epic is still in a planning stage.
 * 4. Verification_json null check.
 *
 * @param projectRoot - Absolute path to the project root
 * @param taskId - Task identifier to complete
 * @param notesOrOptions - Completion notes (string, legacy) OR an options object
 * @returns EngineResult with the completed task, auto-completed parents, and unblocked tasks
 *
 * @task T1568
 * @task T1632
 * @adr ADR-051
 * @epic T1566
 */
export declare function completeTaskStrict(projectRoot: string, taskId: string, notesOrOptions?: string | TaskCompleteEngineOptions): Promise<CompleteEngineResult>;
export {};
//# sourceMappingURL=complete.d.ts.map