/**
 * Research commands and manifest operations.
 *
 * @packageDocumentation
 * @task T4465
 * @epic T4454
 */
import type { DataAccessor } from '../store/data-accessor.js';
/** Research entry attached to a task. */
export interface ResearchEntry {
    /** Unique research entry identifier. */
    id: string;
    /** Task ID this research is linked to. */
    taskId: string;
    /** Research topic or question. */
    topic: string;
    /** Accumulated research findings. */
    findings: string[];
    /** Source URLs or references. */
    sources: string[];
    /** Current research status. */
    status: 'pending' | 'complete' | 'partial';
    /** ISO timestamp of creation. */
    createdAt: string;
    /** ISO timestamp of last update. */
    updatedAt: string;
}
/** Manifest entry (JSONL line). */
export interface ManifestEntry {
    /** Unique manifest entry identifier. */
    id: string;
    /** Output file path for this entry. */
    file: string;
    /** Human-readable title of the research output. */
    title: string;
    /** ISO date string when the entry was created. */
    date: string;
    /** Completion status of the research. */
    status: 'completed' | 'partial' | 'blocked';
    /** Type of agent that produced this entry. */
    agent_type: string;
    /** Topic tags associated with the entry. */
    topics: string[];
    /** Key findings from the research. */
    key_findings: string[];
    /** Whether the findings are actionable. */
    actionable: boolean;
    /** Items that need follow-up investigation. */
    needs_followup: string[];
    /** Task IDs linked to this manifest entry. */
    linked_tasks: string[];
}
/** Options for adding research. */
export interface AddResearchOptions {
    /** Task ID to attach the research to. */
    taskId: string;
    /** Research topic or question. */
    topic: string;
    /** Initial findings (if any). */
    findings?: string[];
    /** Source URLs or references. */
    sources?: string[];
}
/** Options for listing research. */
export interface ListResearchOptions {
    /** Filter by linked task ID. */
    taskId?: string;
    /** Filter by research status. */
    status?: 'pending' | 'complete' | 'partial';
}
/** Manifest query options. */
export interface ManifestQueryOptions {
    /** Filter by completion status. */
    status?: string;
    /** Filter by agent type. */
    agentType?: string;
    /** Filter by topic tag. */
    topic?: string;
    /** Filter by linked task ID. */
    taskId?: string;
    /** Maximum entries to return. */
    limit?: number;
}
/**
 * Add a research entry.
 *
 * @param options - Research entry data including taskId and topic
 * @param cwd - Optional working directory for path resolution
 * @param accessor - Data accessor for task validation
 * @returns The created ResearchEntry
 *
 * @remarks
 * Validates the linked task exists, generates a unique ID, and persists
 * the entry to research.json. Logs the operation to the audit log.
 *
 * @example
 * ```typescript
 * const entry = await addResearch({ taskId: 'T042', topic: 'Auth patterns' }, '/project', accessor);
 * ```
 *
 * @task T4465
 */
export declare function addResearch(options: AddResearchOptions, cwd?: string, accessor?: DataAccessor): Promise<ResearchEntry>;
/**
 * Show a specific research entry.
 *
 * @param researchId - The research entry ID to look up
 * @param cwd - Optional working directory for path resolution
 * @returns The matching ResearchEntry
 *
 * @remarks
 * Throws a CleoError with NOT_FOUND if the entry does not exist.
 *
 * @example
 * ```typescript
 * const entry = await showResearch('Rlk1abc2', '/project');
 * ```
 *
 * @task T4465
 */
export declare function showResearch(researchId: string, cwd?: string): Promise<ResearchEntry>;
/**
 * List research entries with optional filtering.
 *
 * @param options - Optional filters for taskId and status
 * @param cwd - Optional working directory for path resolution
 * @returns Filtered array of ResearchEntry records
 *
 * @remarks
 * Returns all entries when no filters are provided.
 *
 * @example
 * ```typescript
 * const entries = await listResearch({ status: 'pending' }, '/project');
 * ```
 *
 * @task T4465
 */
export declare function listResearch(options?: ListResearchOptions, cwd?: string): Promise<ResearchEntry[]>;
/**
 * List pending research entries.
 *
 * @param cwd - Optional working directory for path resolution
 * @returns Array of research entries with status "pending"
 *
 * @remarks
 * Convenience wrapper around listResearch with status filter pre-set.
 *
 * @example
 * ```typescript
 * const pending = await pendingResearch('/project');
 * ```
 *
 * @task T4465
 */
export declare function pendingResearch(cwd?: string): Promise<ResearchEntry[]>;
/**
 * Link a research entry to a task.
 *
 * @param researchId - The research entry ID to link
 * @param taskId - The target task ID
 * @param cwd - Optional working directory for path resolution
 * @param accessor - Data accessor for task validation
 * @returns Confirmation with researchId and taskId
 *
 * @remarks
 * Updates the research entry's taskId field and persists the change.
 * Validates both the research entry and target task exist.
 *
 * @example
 * ```typescript
 * await linkResearch('Rlk1abc2', 'T050', '/project', accessor);
 * ```
 *
 * @task T4465
 */
export declare function linkResearch(researchId: string, taskId: string, cwd?: string, accessor?: DataAccessor): Promise<{
    researchId: string;
    taskId: string;
}>;
/**
 * Update research findings.
 *
 * @param researchId - The research entry ID to update
 * @param updates - Fields to update (findings, sources, and/or status)
 * @param cwd - Optional working directory for path resolution
 * @returns The updated ResearchEntry
 *
 * @remarks
 * Only provided fields are updated; others are left unchanged.
 * Updates the `updatedAt` timestamp automatically.
 *
 * @example
 * ```typescript
 * const entry = await updateResearch('Rlk1abc2', { status: 'complete', findings: ['JWT is used'] });
 * ```
 *
 * @task T4465
 */
export declare function updateResearch(researchId: string, updates: {
    findings?: string[];
    sources?: string[];
    status?: 'pending' | 'complete' | 'partial';
}, cwd?: string): Promise<ResearchEntry>;
/**
 * Get research statistics.
 *
 * @param cwd - Optional working directory for path resolution
 * @returns Total count and breakdowns by status and topic
 *
 * @remarks
 * Aggregates all research entries into status and topic distributions.
 *
 * @example
 * ```typescript
 * const stats = await statsResearch('/project');
 * console.log(`${stats.total} entries, ${stats.byStatus.pending ?? 0} pending`);
 * ```
 *
 * @task T4474
 */
export declare function statsResearch(cwd?: string): Promise<{
    total: number;
    byStatus: Record<string, number>;
    byTopic: Record<string, number>;
}>;
/**
 * Get research entries linked to a specific task.
 *
 * @param taskId - The task ID to find linked research for
 * @param cwd - Optional working directory for path resolution
 * @returns Array of research entries linked to the given task
 *
 * @remarks
 * Filters research entries by taskId. Throws if taskId is empty.
 *
 * @example
 * ```typescript
 * const linked = await linksResearch('T042', '/project');
 * ```
 *
 * @task T4474
 */
export declare function linksResearch(taskId: string, cwd?: string): Promise<ResearchEntry[]>;
/**
 * Archive old research entries by status.
 * Moves 'complete' entries to an archive and keeps non-complete ones.
 *
 * @param cwd - Optional working directory for path resolution
 * @returns Summary with count of archived and remaining entries
 *
 * @remarks
 * Removes all "complete" entries from the active research file and reports
 * how many were archived vs. retained.
 *
 * @example
 * ```typescript
 * const result = await archiveResearch('/project');
 * console.log(`Archived ${result.entriesArchived} entries`);
 * ```
 *
 * @task T4474
 */
export declare function archiveResearch(cwd?: string): Promise<{
    action: string;
    entriesArchived: number;
    entriesRemaining: number;
}>;
/**
 * Read manifest entries from MANIFEST.jsonl.
 *
 * @param cwd - Optional working directory for path resolution
 * @returns Array of parsed ManifestEntry records from the JSONL file
 *
 * @remarks
 * Reads the file line by line, skipping blank and malformed lines.
 * Returns an empty array if the file does not exist.
 *
 * @example
 * ```typescript
 * const entries = await readManifest('/project');
 * ```
 *
 * @task T4465
 */
export declare function readManifest(cwd?: string): Promise<ManifestEntry[]>;
/**
 * Append a manifest entry.
 *
 * @param entry - The ManifestEntry to append
 * @param cwd - Optional working directory for path resolution
 *
 * @remarks
 * Appends a single JSON line to the MANIFEST.jsonl file.
 *
 * @example
 * ```typescript
 * await appendManifest({ id: 'M001', file: 'report.md', ... }, '/project');
 * ```
 *
 * @task T4465
 */
export declare function appendManifest(entry: ManifestEntry, cwd?: string): Promise<void>;
/**
 * Query manifest entries with filtering.
 *
 * @param options - Filter criteria (status, agentType, topic, taskId, limit)
 * @param cwd - Optional working directory for path resolution
 * @returns Filtered array of ManifestEntry records
 *
 * @remarks
 * Applies filters sequentially: status, agentType, topic, taskId, then limit.
 * Returns all entries when no filters are provided.
 *
 * @example
 * ```typescript
 * const entries = await queryManifest({ status: 'completed', limit: 5 }, '/project');
 * ```
 *
 * @task T4465
 */
export declare function queryManifest(options?: ManifestQueryOptions, cwd?: string): Promise<ManifestEntry[]>;
/** Extended manifest entry with optional fields used by the engine. */
export interface ExtendedManifestEntry extends ManifestEntry {
    /** Confidence score for the research findings. */
    confidence?: number;
    /** SHA checksum of the output file. */
    file_checksum?: string;
    /** Duration of the research in seconds. */
    duration_seconds?: number;
}
/** Research filter criteria used by the engine. */
export interface ResearchFilter {
    /** Filter by linked task ID. */
    taskId?: string;
    /** Filter by completion status. */
    status?: string;
    /** Filter by agent type. */
    agent_type?: string;
    /** Filter by topic tag. */
    topic?: string;
    /** Maximum entries to return. */
    limit?: number;
    /** Number of entries to skip before applying limit. */
    offset?: number;
    /** Filter by actionable flag. */
    actionable?: boolean;
    /** Filter entries created after this ISO date. */
    dateAfter?: string;
    /** Filter entries created before this ISO date. */
    dateBefore?: string;
}
/**
 * Read all manifest entries as extended entries.
 *
 * @param cwd - Optional working directory for path resolution
 * @returns Array of parsed ExtendedManifestEntry records
 *
 * @remarks
 * Same as readManifest but typed as ExtendedManifestEntry to include
 * optional engine fields (confidence, file_checksum, duration_seconds).
 *
 * @example
 * ```typescript
 * const entries = await readExtendedManifest('/project');
 * ```
 *
 * @task T4787
 */
export declare function readExtendedManifest(cwd?: string): Promise<ExtendedManifestEntry[]>;
/**
 * Filter manifest entries by criteria.
 *
 * @param entries - Array of manifest entries to filter
 * @param filter - Filter criteria to apply
 * @returns Filtered subset of entries
 *
 * @remarks
 * Applies filters in order: taskId, status, agent_type, topic, actionable,
 * dateAfter, dateBefore, offset, then limit.
 *
 * @example
 * ```typescript
 * const filtered = filterManifestEntries(entries, { status: 'completed', limit: 10 });
 * ```
 *
 * @task T4787
 */
export declare function filterManifestEntries(entries: ExtendedManifestEntry[], filter: ResearchFilter): ExtendedManifestEntry[];
/**
 * Show a manifest entry by ID with optional file content.
 *
 * @param researchId - The manifest entry ID to look up
 * @param cwd - Optional working directory for path resolution
 * @returns The manifest entry with file content and existence flag
 *
 * @remarks
 * Reads the output file referenced by the entry if it exists on disk.
 * Throws CleoError NOT_FOUND if the entry ID is not found.
 *
 * @example
 * ```typescript
 * const entry = await showManifestEntry('T042-auth-research', '/project');
 * if (entry.fileExists) console.log(entry.fileContent);
 * ```
 *
 * @task T4787
 */
export declare function showManifestEntry(researchId: string, cwd?: string): Promise<ExtendedManifestEntry & {
    fileContent: string | null;
    fileExists: boolean;
}>;
/**
 * Search manifest entries by text with relevance scoring.
 *
 * @param query - Text query to match against titles, topics, and findings
 * @param options - Optional confidence threshold and limit
 * @param cwd - Optional working directory for path resolution
 * @returns Manifest entries with relevance scores, sorted by relevance descending
 *
 * @remarks
 * Scores entries by matching against title (0.5), topics (0.3), key findings (0.2),
 * and ID (0.1). Filters by minimum confidence threshold (default 0.1).
 *
 * @example
 * ```typescript
 * const results = await searchManifest('authentication', { limit: 5 }, '/project');
 * ```
 *
 * @task T4787
 */
export declare function searchManifest(query: string, options?: {
    confidence?: number;
    limit?: number;
}, cwd?: string): Promise<Array<ExtendedManifestEntry & {
    relevanceScore: number;
}>>;
/**
 * Get pending manifest entries (partial, blocked, or needing followup).
 *
 * @param epicId - Optional epic ID to scope results
 * @param cwd - Optional working directory for path resolution
 * @returns Pending entries with total count and status breakdown
 *
 * @remarks
 * Includes entries with status "partial", "blocked", or any non-empty
 * needs_followup array. Optionally scopes to entries linked to an epic.
 *
 * @example
 * ```typescript
 * const { entries, total } = await pendingManifestEntries('T001', '/project');
 * ```
 *
 * @task T4787
 */
export declare function pendingManifestEntries(epicId?: string, cwd?: string): Promise<{
    entries: ExtendedManifestEntry[];
    total: number;
    byStatus: {
        partial: number;
        blocked: number;
        needsFollowup: number;
    };
}>;
/**
 * Get manifest-based research statistics.
 *
 * @param epicId - Optional epic ID to scope statistics
 * @param cwd - Optional working directory for path resolution
 * @returns Totals, status/type distributions, actionable count, and average findings
 *
 * @remarks
 * Aggregates manifest entries by status, agent type, and actionability.
 * Calculates average key findings per entry.
 *
 * @example
 * ```typescript
 * const stats = await manifestStats(undefined, '/project');
 * console.log(`${stats.total} entries, ${stats.actionable} actionable`);
 * ```
 *
 * @task T4787
 */
export declare function manifestStats(epicId?: string, cwd?: string): Promise<{
    total: number;
    byStatus: Record<string, number>;
    byType: Record<string, number>;
    actionable: number;
    needsFollowup: number;
    averageFindings: number;
}>;
/**
 * Link a manifest entry to a task (adds taskId to linked_tasks array).
 *
 * @param taskId - The task ID to link
 * @param researchId - The manifest entry ID to link to
 * @param cwd - Optional working directory for path resolution
 * @returns Confirmation with link details and whether it was already linked
 *
 * @remarks
 * Appends the taskId to the entry's linked_tasks array if not already present.
 * Rewrites the entire MANIFEST.jsonl file after modification.
 *
 * @example
 * ```typescript
 * const result = await linkManifestEntry('T042', 'M001', '/project');
 * ```
 *
 * @task T4787
 */
export declare function linkManifestEntry(taskId: string, researchId: string, cwd?: string): Promise<{
    taskId: string;
    researchId: string;
    alreadyLinked: boolean;
}>;
/**
 * Append an extended manifest entry.
 * Validates required fields before appending.
 *
 * @param entry - The ExtendedManifestEntry to append
 * @param cwd - Optional working directory for path resolution
 * @returns Confirmation with the entry ID and manifest file path
 *
 * @remarks
 * Validates that all required fields (id, file, title, date, status, agent_type,
 * topics, actionable) are present before writing.
 *
 * @example
 * ```typescript
 * const result = await appendExtendedManifest({ id: 'M002', ... }, '/project');
 * ```
 *
 * @task T4787
 */
export declare function appendExtendedManifest(entry: ExtendedManifestEntry, cwd?: string): Promise<{
    entryId: string;
    file: string;
}>;
/**
 * Archive manifest entries older than a date.
 *
 * @param beforeDate - ISO date string; entries older than this are archived
 * @param cwd - Optional working directory for path resolution
 * @returns Counts of archived and remaining entries, and the archive file path
 *
 * @remarks
 * Moves entries with a date before the threshold to MANIFEST.archive.jsonl
 * and rewrites the main MANIFEST.jsonl with the remaining entries.
 *
 * @example
 * ```typescript
 * const result = await archiveManifestEntries('2026-01-01', '/project');
 * console.log(`Archived ${result.archived} entries`);
 * ```
 *
 * @task T4787
 */
export declare function archiveManifestEntries(beforeDate: string, cwd?: string): Promise<{
    archived: number;
    remaining: number;
    archiveFile: string;
}>;
/** Contradiction detail between two manifest entries. */
export interface ContradictionDetail {
    /** First conflicting entry. */
    entryA: ExtendedManifestEntry;
    /** Second conflicting entry. */
    entryB: ExtendedManifestEntry;
    /** Shared topic where the conflict was detected. */
    topic: string;
    /** Description of the conflicting findings. */
    conflictDetails: string;
}
/**
 * Find manifest entries with overlapping topics but conflicting key_findings.
 *
 * @param cwd - Optional working directory for path resolution
 * @param params - Optional filter by topic
 * @returns Array of contradiction details between conflicting entries
 *
 * @remarks
 * Groups entries by shared topics and compares key_findings for disagreements.
 * Only returns pairs where findings actually differ.
 *
 * @example
 * ```typescript
 * const contradictions = await findContradictions('/project', { topic: 'auth' });
 * ```
 *
 * @task T4787
 */
export declare function findContradictions(cwd?: string, params?: {
    topic?: string;
}): Promise<ContradictionDetail[]>;
/** Superseded entry detail. */
export interface SupersededDetail {
    old: ExtendedManifestEntry;
    replacement: ExtendedManifestEntry;
    topic: string;
}
/**
 * Identify research entries replaced by newer work on same topic.
 *
 * @param cwd - Optional working directory for path resolution
 * @param params - Optional filter by topic
 * @returns Array of superseded entry pairs with the replacement and obsoleted entries
 *
 * @remarks
 * Groups entries by shared topics and identifies older entries that have been
 * superseded by newer ones on the same subject.
 *
 * @example
 * ```typescript
 * const superseded = await findSuperseded('/project');
 * ```
 *
 * @task T4787
 */
export declare function findSuperseded(cwd?: string, params?: {
    topic?: string;
}): Promise<SupersededDetail[]>;
/**
 * Read protocol injection content for a given protocol type.
 *
 * @param protocolType - Protocol name (e.g. "consensus", "contribution")
 * @param params - Optional parameters for template resolution
 * @param cwd - Optional working directory for path resolution
 * @returns Protocol content, file path, and metadata
 *
 * @remarks
 * Reads protocol template files from the agent-outputs directory and
 * resolves variables like taskId within the content.
 *
 * @example
 * ```typescript
 * const result = await readProtocolInjection('consensus', { taskId: 'T042' }, '/project');
 * console.log(result.content);
 * ```
 *
 * @task T4787
 */
export declare function readProtocolInjection(protocolType: string, params?: {
    taskId?: string;
    variant?: string;
}, cwd?: string): Promise<{
    protocolType: string;
    content: string;
    path: string;
    contentLength: number;
    estimatedTokens: number;
    taskId: string | null;
    variant: string | null;
}>;
/**
 * Compact MANIFEST.jsonl by removing duplicate/stale entries.
 *
 * @param cwd - Optional working directory for path resolution
 * @returns Compaction summary with counts of removed entries
 *
 * @remarks
 * Removes malformed lines and deduplicates entries by ID (keeping the last
 * occurrence). Rewrites the file atomically.
 *
 * @example
 * ```typescript
 * const result = await compactManifest('/project');
 * console.log(`Removed ${result.duplicatesRemoved} duplicates`);
 * ```
 *
 * @task T4787
 */
export declare function compactManifest(cwd?: string): Promise<{
    compacted: boolean;
    originalLines: number;
    malformedRemoved: number;
    duplicatesRemoved: number;
    remainingEntries: number;
}>;
/**
 * Validate research entries for a task.
 *
 * @param taskId - The task ID to validate manifest entries for
 * @param cwd - Optional working directory for path resolution
 * @returns Validation result with issue details and severity counts
 *
 * @remarks
 * Checks linked manifest entries for missing output files, empty key findings,
 * and incomplete status. Reports issues at error or warning severity.
 *
 * @example
 * ```typescript
 * const result = await validateManifestEntries('T042', '/project');
 * if (!result.valid) console.log(result.issues);
 * ```
 *
 * @task T4787
 */
export declare function validateManifestEntries(taskId: string, cwd?: string): Promise<{
    taskId: string;
    valid: boolean;
    entriesFound: number;
    issues: Array<{
        entryId: string;
        issue: string;
        severity: 'error' | 'warning';
    }>;
    errorCount: number;
    warningCount: number;
}>;
export * from './brain-lifecycle.js';
export * from './brain-links.js';
export * from './brain-migration.js';
export * from './brain-retrieval.js';
export * from './brain-search.js';
export * from './decisions.js';
export * from './learnings.js';
export * from './patterns.js';
//# sourceMappingURL=index.d.ts.map