@papi-ai/adapter-md 0.1.0-alpha

package/dist/index.d.ts

@@ -0,0 +1,904 @@
+import { TaskStatus as TaskStatus$1, TaskPriority as TaskPriority$1, EffortSize as EffortSize$1, ReviewStage as ReviewStage$1, ReviewVerdict as ReviewVerdict$1, TaskComplexity as TaskComplexity$1, TaskType as TaskType$1, isValidStatus as isValidStatus$1, isValidTransition as isValidTransition$1, validateTransition as validateTransition$1 } from '@papi-ai/shared';
+
+/** Valid phase statuses in the product brief. */
+type PhaseStatus = 'Not Started' | 'In Progress' | 'Done' | 'Deferred';
+/** Feature lifecycle status. */
+type FeatureStatus = 'Not Started' | 'In Progress' | 'Done' | 'Deferred';
+/** A workstream or capability being built. Replaces Phase as the primary planning construct (AD-23). */
+interface Feature {
+    id: string;
+    displayId: string;
+    slug: string;
+    name: string;
+    description: string;
+    status: FeatureStatus;
+    roadmapPosition: number;
+    createdAt: string;
+    completedAt?: string;
+    commitDate?: string;
+    createdSprint: number;
+    completedSprint?: number;
+}
+/** A development phase defined in the product brief. */
+interface Phase {
+    id: string;
+    slug: string;
+    label: string;
+    description: string;
+    status: PhaseStatus;
+    order: number;
+}
+/** Sprint lifecycle status. */
+type SprintStatus = 'planning' | 'active' | 'complete';
+/** A sprint entity giving sprints first-class identity. */
+/** Per-section SHA-256 hashes for context diff optimisation between sprints. */
+interface ContextHashes {
+    productBrief?: string;
+    activeDecisions?: string;
+    reviews?: string;
+    [key: string]: string | undefined;
+}
+interface Sprint {
+    id: string;
+    number: number;
+    status: SprintStatus;
+    startDate: string;
+    endDate?: string;
+    goals: string[];
+    boardHealth: string;
+    taskIds: string[];
+    contextHashes?: ContextHashes;
+}
+
+type TaskStatus = TaskStatus$1;
+type TaskPriority = TaskPriority$1;
+type TaskComplexity = TaskComplexity$1;
+type EffortSize = EffortSize$1;
+type TaskType = TaskType$1;
+type ReviewVerdict = ReviewVerdict$1;
+type ReviewStage = ReviewStage$1;
+declare const VALID_TRANSITIONS: Readonly<Record<TaskStatus, readonly TaskStatus[]>>;
+declare const isValidTransition: typeof isValidTransition$1;
+declare const validateTransition: typeof validateTransition$1;
+declare const isValidStatus: typeof isValidStatus$1;
+/**
+ * Context tiers control which tasks the planner sees:
+ *   Tier 1 (Sprint-eligible): Bug, Task — fed to planner for scheduling
+ *   Tier 2 (Plannable): Research — scheduled but output is knowledge not code
+ *   Tier 3 (Pre-triage): Idea, Feedback — invisible to planner until promoted
+ */
+type ContextTier = 1 | 2 | 3;
+/** Map task types to their context tier. */
+declare const TASK_TYPE_TIERS: Record<TaskType, ContextTier>;
+/** How scoped/ready a task is for scheduling. */
+type TaskMaturity = 'raw' | 'investigated' | 'ready';
+/** Active Decision confidence level. */
+type Confidence = 'HIGH' | 'MEDIUM' | 'LOW';
+/** Event types for the decision lifecycle log. */
+type DecisionEventType = 'created' | 'confidence_changed' | 'modified' | 'superseded' | 'validated' | 'invalidated' | 'scored';
+/** Source of a decision event. */
+type DecisionEventSource = 'strategy_review' | 'build_complete' | 'strategy_change' | 'manual';
+/** An append-only event in a decision's lifecycle. */
+interface DecisionEvent {
+    id: string;
+    decisionId: string;
+    eventType: DecisionEventType;
+    sprint: number;
+    source: DecisionEventSource;
+    sourceRef?: string;
+    detail?: string;
+    createdAt: string;
+}
+/** Dimensional scores for an Active Decision at a point in time. */
+interface DecisionScore {
+    id: string;
+    decisionId: string;
+    sprint: number;
+    effort: number;
+    risk: number;
+    reversibility: number;
+    scaleCost: number;
+    lockIn: number;
+    totalScore: number;
+    rationale?: string;
+    createdAt: string;
+}
+/** Sprint health metadata from PLANNING_LOG.md header. */
+interface SprintHealth {
+    totalSprints: number;
+    latestSprintStatus?: string;
+    sprintsSinceLastStrategyReview: number;
+    strategyReviewDue: string;
+    boardHealth: string;
+    strategicDirection: string;
+    lastFullMode: number;
+}
+/** An Active Decision (AD) tracked in the planning log. */
+interface ActiveDecision {
+    uuid: string;
+    id: string;
+    displayId: string;
+    title: string;
+    confidence: Confidence;
+    superseded: boolean;
+    supersededBy?: string;
+    createdSprint?: number;
+    modifiedSprint?: number;
+    body: string;
+}
+/** A single sprint entry in the planning log. */
+interface SprintLogEntry {
+    uuid: string;
+    sprintNumber: number;
+    title: string;
+    content: string;
+    carryForward?: string;
+    notes?: string;
+}
+/** A strategy review entry stored in its own table (not planning_log_entries). */
+interface StrategyReviewEntry {
+    sprintNumber: number;
+    sprintRange?: string;
+    title: string;
+    content: string;
+    notes?: string;
+    boardHealth?: string;
+    strategicDirection?: string;
+    recommendations?: unknown;
+    createdAt?: string;
+}
+/** Full parsed contents of PLANNING_LOG.md. */
+interface PlanningLog {
+    sprintHealth: SprintHealth;
+    northStar: string;
+    activeDecisions: ActiveDecision[];
+    deferred: string[];
+    sprintLog: SprintLogEntry[];
+}
+/** A single state transition entry recording when a task changed status. */
+interface StateTransition {
+    status: TaskStatus;
+    timestamp: string;
+}
+/** A task on the sprint board (parsed from SPRINT_BOARD.md YAML). */
+interface SprintTask {
+    uuid: string;
+    id: string;
+    displayId: string;
+    title: string;
+    status: TaskStatus;
+    priority: TaskPriority;
+    complexity: TaskComplexity;
+    module: string;
+    epic: string;
+    phase: string;
+    owner: string;
+    reviewed: boolean;
+    sprint?: number;
+    createdSprint?: number;
+    createdAt?: string;
+    why?: string;
+    dependsOn?: string;
+    notes?: string;
+    closureReason?: string;
+    stateHistory?: StateTransition[];
+    buildHandoff?: BuildHandoff;
+    buildReport?: string;
+    taskType?: TaskType;
+    maturity?: TaskMaturity;
+}
+/** A build report entry from BUILD_REPORTS.md. */
+interface BuildReport {
+    uuid: string;
+    displayId?: string;
+    createdAt?: string;
+    taskId: string;
+    taskName: string;
+    date: string;
+    sprint: number;
+    completed: 'Yes' | 'No' | 'Partial';
+    actualEffort: EffortSize;
+    estimatedEffort: EffortSize;
+    surprises: string;
+    discoveredIssues: string;
+    architectureNotes: string;
+    scopeAccuracy: 'accurate' | 'over-scoped' | 'under-scoped' | 'missed-context';
+    commitSha?: string;
+    filesChanged?: string[];
+    relatedDecisions?: string[];
+}
+/** A single tool call metric entry from METRICS.md. */
+interface ToolCallMetric {
+    timestamp: string;
+    tool: string;
+    durationMs: number;
+    inputTokens?: number;
+    outputTokens?: number;
+    estimatedCostUsd?: number;
+    model?: string;
+    /** Sprint number when this metric was recorded. Absent on legacy rows. */
+    sprintNumber?: number;
+    /** Context size in bytes for plan tool calls. Absent on non-plan tools. */
+    contextBytes?: number;
+    /** Context utilisation ratio (0.0–1.0). Fraction of input entities referenced in output. */
+    contextUtilisation?: number;
+}
+/** Per-command cost aggregation. */
+interface CommandCost {
+    command: string;
+    totalCostUsd: number;
+    calls: number;
+    avgCostUsd: number;
+}
+/** Aggregated cost summary computed from tool call metrics. */
+interface CostSummary {
+    totalCostUsd: number;
+    totalInputTokens: number;
+    totalOutputTokens: number;
+    totalCalls: number;
+    costByCommand: CommandCost[];
+    mostExpensiveCommand: string | null;
+    avgCostPerCall: number;
+}
+/** A cost snapshot persisted in the Cost Summary section of METRICS.md. */
+interface CostSnapshot {
+    sprint: number;
+    date: string;
+    totalCostUsd: number;
+    totalInputTokens: number;
+    totalOutputTokens: number;
+    totalCalls: number;
+}
+/** An entry to be semantically clustered. */
+interface ClusterEntry {
+    text: string;
+    source: string;
+}
+/** A cluster of semantically similar text entries. */
+interface ClusterResult {
+    theme: string;
+    entries: ClusterEntry[];
+}
+/**
+ * Callback that groups text entries into semantic clusters.
+ * Used by pattern detection to optionally replace normalised string matching with LLM-based clustering.
+ */
+type TextClusterer = (entries: ClusterEntry[]) => Promise<ClusterResult[]>;
+/** A recurring surprise detected across build reports. */
+interface RecurringSurprise {
+    text: string;
+    count: number;
+    sprints: number[];
+}
+/** Build pattern detection results from analyzing recent build reports. */
+interface BuildPatterns {
+    recurringSurprises: RecurringSurprise[];
+    estimationBias: 'under' | 'over' | 'none';
+    estimationBiasRate: number;
+    scopeAccuracyBreakdown: Record<string, number>;
+    untriagedIssues: string[];
+}
+/** Per-sprint estimation accuracy stats. */
+interface SprintEstimationAccuracy {
+    sprint: number;
+    reports: number;
+    matchRate: number;
+    mae: number;
+    bias: number;
+}
+/** Per-sprint velocity stats. */
+interface SprintVelocity {
+    sprint: number;
+    completed: number;
+    partial: number;
+    failed: number;
+    effortPoints: number;
+}
+/** A sprint methodology metrics snapshot stored in SPRINT_METRICS.md. */
+interface SprintMetricsSnapshot {
+    sprint: number;
+    date: string;
+    accuracy: SprintEstimationAccuracy[];
+    velocity: SprintVelocity[];
+}
+/** A recurring feedback theme detected across human reviews. */
+interface RecurringFeedback {
+    text: string;
+    count: number;
+    taskIds: string[];
+}
+/** Review pattern detection results from analyzing recent human reviews. */
+interface ReviewPatterns {
+    recurringFeedback: RecurringFeedback[];
+    verdictBreakdown: Record<string, number>;
+    requestChangesRate: number;
+}
+/** A human review entry stored in REVIEWS.md. */
+interface HumanReview {
+    uuid: string;
+    displayId?: string;
+    taskId: string;
+    stage: ReviewStage;
+    reviewer: string;
+    verdict: ReviewVerdict;
+    sprint: number;
+    date: string;
+    comments: string;
+    handoffRevision?: number;
+    buildCommitSha?: string;
+}
+/** A structured BUILD HANDOFF parsed from the markdown handoff block. */
+interface BuildHandoff {
+    uuid: string;
+    displayId?: string;
+    createdAt?: string;
+    taskId: string;
+    taskTitle: string;
+    sprint: number;
+    whyNow: string;
+    scope: string[];
+    scopeBoundary: string[];
+    acceptanceCriteria: string[];
+    securityConsiderations: string;
+    filesLikelyTouched: string[];
+    effort: EffortSize;
+}
+/** Module and epic registries loaded from REGISTRIES.md. */
+interface Registries {
+    modules: string[];
+    epics: string[];
+}
+/** Recommendation types written by strategy_review, consumed by plan. */
+type RecommendationType = 'priority_change' | 'new_task' | 'ad_update' | 'phase_transition' | 'process_improvement' | 'infrastructure' | 'velocity_observation';
+/** Recommendation lifecycle status. */
+type RecommendationStatus = 'pending' | 'actioned' | 'dismissed';
+/** A structured strategy recommendation. */
+interface StrategyRecommendation {
+    id: string;
+    type: RecommendationType;
+    status: RecommendationStatus;
+    content: string;
+    createdSprint: number;
+    actionedSprint?: number;
+}
+/** Entity reference — tracks which decisions/entities are used in tool calls. */
+interface EntityReference {
+    id: string;
+    entityType: 'active_decision';
+    entityId: string;
+    referenceContext: 'plan_input' | 'plan_output' | 'strategy_input' | 'strategy_output';
+    toolName: string;
+    sprintNumber: number;
+    createdAt: string;
+}
+/** Per-AD usage summary returned by getDecisionUsage. */
+interface DecisionUsageSummary {
+    decisionId: string;
+    referenceCount: number;
+    lastReferencedSprint: number;
+    sprintsSinceLastReference: number;
+}
+/** Options for updateTask to control validation behaviour. */
+interface UpdateTaskOptions {
+    /** Skip state-machine transition validation when true. */
+    force?: boolean;
+}
+/** Filter options for querying the sprint board. */
+interface BoardQueryOptions {
+    status?: TaskStatus[];
+    priority?: TaskPriority[];
+    phase?: string;
+    reviewed?: boolean;
+    module?: string;
+    epic?: string;
+    /** Filter by context tier (1=sprint-eligible, 2=plannable, 3=pre-triage). */
+    contextTier?: ContextTier;
+}
+/** Core adapter interface for reading/writing .papi/ markdown files. */
+interface PapiAdapter {
+    readPlanningLog(): Promise<PlanningLog>;
+    getSprintHealth(): Promise<SprintHealth>;
+    getActiveDecisions(): Promise<ActiveDecision[]>;
+    getSprintLog(limit?: number): Promise<SprintLogEntry[]>;
+    getSprintLogSince(sprintNumber: number): Promise<SprintLogEntry[]>;
+    setSprintHealth(updates: Partial<SprintHealth>): Promise<void>;
+    writeSprintLogEntry(entry: SprintLogEntry): Promise<void>;
+    updateActiveDecision(id: string, body: string, sprintNumber?: number): Promise<void>;
+    queryBoard(options?: BoardQueryOptions): Promise<SprintTask[]>;
+    getTask(id: string): Promise<SprintTask | null>;
+    getTasks(ids: string[]): Promise<SprintTask[]>;
+    createTask(task: Omit<SprintTask, 'id'>): Promise<SprintTask>;
+    updateTask(id: string, updates: Partial<Omit<SprintTask, 'id'>>, options?: UpdateTaskOptions): Promise<void>;
+    updateTaskStatus(id: string, status: TaskStatus): Promise<void>;
+    appendBuildReport(report: BuildReport): Promise<void>;
+    getRecentBuildReports(count: number): Promise<BuildReport[]>;
+    getBuildReportsSince(sprintNumber: number): Promise<BuildReport[]>;
+    getRecentReviews(count?: number): Promise<HumanReview[]>;
+    writeReview(review: HumanReview): Promise<void>;
+    compressSprintLog(threshold: number, summary: string): Promise<void>;
+    compressBuildReports(threshold: number, summary: string): Promise<void>;
+    archiveTasks(phases: string[], statuses?: string[]): Promise<{
+        archivedCount: number;
+        taskIds: string[];
+    }>;
+    readProductBrief(): Promise<string>;
+    updateProductBrief(content: string): Promise<void>;
+    readPhases(): Promise<Phase[]>;
+    writePhases(phases: Phase[]): Promise<void>;
+    readFeatures(): Promise<Feature[]>;
+    getFeature(id: string): Promise<Feature | null>;
+    createFeature(feature: Omit<Feature, 'id'>): Promise<Feature>;
+    updateFeature(id: string, updates: Partial<Omit<Feature, 'id'>>): Promise<void>;
+    appendToolMetric(metric: ToolCallMetric): Promise<void>;
+    readToolMetrics(): Promise<ToolCallMetric[]>;
+    getCostSummary(sprintNumber?: number): Promise<CostSummary>;
+    writeCostSnapshot(snapshot: CostSnapshot): Promise<void>;
+    getCostSnapshots(): Promise<CostSnapshot[]>;
+    appendSprintMetrics(snapshot: SprintMetricsSnapshot): Promise<void>;
+    readSprintMetrics(): Promise<SprintMetricsSnapshot[]>;
+    readSprints(): Promise<Sprint[]>;
+    createSprint(sprint: Sprint): Promise<void>;
+    getContextHashes?(sprintNumber: number): Promise<Record<string, string> | null>;
+    readRegistries(): Promise<Registries>;
+    updateRegistries(registries: Registries): Promise<void>;
+    writeRecommendation(rec: Omit<StrategyRecommendation, 'id'>): Promise<StrategyRecommendation>;
+    getPendingRecommendations(): Promise<StrategyRecommendation[]>;
+    actionRecommendation(id: string, sprintNumber: number): Promise<void>;
+    appendDecisionEvent(event: Omit<DecisionEvent, 'id' | 'createdAt'>): Promise<DecisionEvent>;
+    getDecisionEvents(decisionId: string, limit?: number): Promise<DecisionEvent[]>;
+    getDecisionEventsSince(sprint: number): Promise<DecisionEvent[]>;
+    writeDecisionScore(score: Omit<DecisionScore, 'id' | 'createdAt' | 'totalScore'>): Promise<DecisionScore>;
+    getDecisionScores(decisionId: string): Promise<DecisionScore[]>;
+    getLatestDecisionScores(): Promise<DecisionScore[]>;
+    logEntityReferences(refs: Omit<EntityReference, 'id' | 'createdAt'>[]): Promise<void>;
+    getDecisionUsage(currentSprint: number): Promise<DecisionUsageSummary[]>;
+    writeStrategyReview(review: StrategyReviewEntry): Promise<void>;
+    getLastStrategyReviewSprint(): Promise<number>;
+    getStrategyReviews(limit?: number): Promise<StrategyReviewEntry[]>;
+    /**
+     * Optional: return recent task comments for plan context.
+     * Returns up to `limit` comments across all active tasks, newest first.
+     */
+    getRecentTaskComments?(limit?: number): Promise<{
+        taskId: string;
+        author: string;
+        content: string;
+        createdAt: string;
+    }[]>;
+    /**
+     * Optional: return a lean pre-formatted plan context summary.
+     * When implemented (e.g. by pg adapter with SQL aggregates), assembleContext
+     * uses this instead of fetching full objects and formatting them.
+     * Return undefined to fall back to the default assembly path.
+     */
+    getPlanContextSummary?(): Promise<PlanContextSummary | undefined>;
+}
+/** Lean plan context returned by adapters that support SQL aggregation. */
+interface PlanContextSummary {
+    /** Compact board: id, title, status, priority, complexity, module — no handoffs/reports. */
+    board: string;
+    /** Pre-computed build intelligence: accuracy %, velocity trend, top surprises. */
+    buildIntelligence: string;
+    /** Last 3 sprint entries with carry-forward. */
+    sprintLog: string;
+    /** One-liner per active decision: id, title, confidence. */
+    activeDecisions: string;
+}
+/** Everything the plan write-back needs to persist in a single transaction. */
+interface PlanWriteBackPayload {
+    /** The NEW sprint number (current + 1). */
+    sprintNumber: number;
+    /** Sprint log entry to upsert. */
+    sprintLog: SprintLogEntry;
+    /** Health updates: boardHealth, strategicDirection, etc. */
+    healthUpdates: Partial<SprintHealth>;
+    /** New tasks to create (already deduplicated by plan service). */
+    newTasks: Array<Omit<SprintTask, 'id' | 'uuid' | 'displayId'>>;
+    /** Board corrections: taskId + partial updates. */
+    boardCorrections: Array<{
+        taskId: string;
+        updates: Partial<Omit<SprintTask, 'id'>>;
+    }>;
+    /** Phases parsed from product brief update. Empty array = no phase changes. */
+    phases: Phase[];
+    /** Active Decision updates: id + new body text. */
+    activeDecisions: Array<{
+        id: string;
+        body: string;
+    }>;
+    /** IDs of pending strategy recommendations to mark as actioned. */
+    pendingRecommendationIds: string[];
+    /** Handoffs to write: taskId (may be "new-N" placeholder) + parsed handoff. */
+    handoffs: Array<{
+        taskId: string;
+        handoff: BuildHandoff;
+    }>;
+    /** Sprint entity to create. */
+    sprint: Sprint;
+    /** Whether to run feature sync from phases. */
+    featureSync: boolean;
+    /** IDs of tasks whose reviewed status should be checked before allowing priority changes. */
+    reviewedTaskIds: string[];
+}
+/** Result of a transactional plan write-back. */
+interface PlanWriteBackResult {
+    /** Maps placeholder IDs ("new-1", "new-2") to real task IDs ("task-456"). */
+    newTaskIdMap: Map<string, string>;
+    /** Notes about priority changes blocked by review lock. */
+    priorityLockNotes: string[];
+    /** Non-fatal warnings (e.g. post-write verification discrepancies). */
+    warnings: string[];
+}
+
+/** Markdown file adapter — reads/writes .papi/ directory files as structured data. */
+declare class MdFileAdapter implements PapiAdapter {
+    private readonly dir;
+    constructor(projectDir: string);
+    /** Resolve a filename to an absolute path within the .papi/ directory. */
+    private path;
+    /** Read a .papi/ file as UTF-8 text. Throws a clear error if the file is missing. */
+    private read;
+    /** Write UTF-8 text to a .papi/ file. */
+    private write;
+    /** Parse the full planning context into structured sections (reads from PLANNING_LOG.md + ACTIVE_DECISIONS.md + SPRINT_LOG.md). */
+    readPlanningLog(): Promise<PlanningLog>;
+    /** Read the Sprint Health table from PLANNING_LOG.md. */
+    getSprintHealth(): Promise<SprintHealth>;
+    /** Read all Active Decisions from ACTIVE_DECISIONS.md. */
+    getActiveDecisions(): Promise<ActiveDecision[]>;
+    /** Read sprint log entries (newest first), optionally limited to {@link limit} entries. */
+    getSprintLog(limit?: number): Promise<SprintLogEntry[]>;
+    getSprintLogSince(sprintNumber: number): Promise<SprintLogEntry[]>;
+    /** Merge partial updates into the Sprint Health table and write back. */
+    setSprintHealth(updates: Partial<SprintHealth>): Promise<void>;
+    /** Prepend a new sprint log entry at the top of the Sprint Log section. */
+    writeSprintLogEntry(entry: SprintLogEntry): Promise<void>;
+    /** Write a strategy review — for md adapter, delegates to sprint log. */
+    writeStrategyReview(review: StrategyReviewEntry): Promise<void>;
+    /** Get the sprint number of the last strategy review. */
+    getLastStrategyReviewSprint(): Promise<number>;
+    /** Get strategy reviews — md adapter returns empty (reviews live in sprint log). */
+    getStrategyReviews(_limit?: number): Promise<StrategyReviewEntry[]>;
+    /** Update or insert an Active Decision block by ID. */
+    updateActiveDecision(id: string, body: string, sprintNumber?: number): Promise<void>;
+    /** Query the sprint board, optionally filtering by status/priority/phase/etc. */
+    queryBoard(options?: BoardQueryOptions): Promise<SprintTask[]>;
+    /** Look up a single task by ID, returning null if not found. */
+    getTask(id: string): Promise<SprintTask | null>;
+    /** Look up multiple tasks by ID in a single board read. */
+    getTasks(ids: string[]): Promise<SprintTask[]>;
+    /** Warn if a phase name doesn't match any known phase label from PRODUCT_BRIEF.md. */
+    private warnInvalidPhase;
+    /** Warn if a module name doesn't match any registered module in REGISTRIES.md. */
+    private warnInvalidModule;
+    /** Warn if an epic name doesn't match any registered epic in REGISTRIES.md. */
+    private warnInvalidEpic;
+    /** Create a new task on the board with an auto-generated sequential ID. */
+    createTask(task: Omit<SprintTask, 'id'>): Promise<SprintTask>;
+    /** Update one or more fields on an existing task. Throws if the task ID is not found. */
+    updateTask(id: string, updates: Partial<Omit<SprintTask, 'id'>>, options?: UpdateTaskOptions): Promise<void>;
+    /** Shorthand to update only the status field of a task. */
+    updateTaskStatus(id: string, status: TaskStatus): Promise<void>;
+    /** Insert a new build report at the top of BUILD_REPORTS.md. */
+    appendBuildReport(report: BuildReport): Promise<void>;
+    /** Return the most recent {@link count} build reports. */
+    getRecentBuildReports(count: number): Promise<BuildReport[]>;
+    /** Return all build reports from sprints >= {@link sprintNumber}. */
+    getBuildReportsSince(sprintNumber: number): Promise<BuildReport[]>;
+    /** Return recent human reviews from REVIEWS.md (newest first), optionally limited to {@link count}. */
+    getRecentReviews(count?: number): Promise<HumanReview[]>;
+    /** Write a new human review to REVIEWS.md. */
+    writeReview(review: HumanReview): Promise<void>;
+    /** Compress old sprint log entries below {@link threshold} into a summary block. */
+    compressSprintLog(threshold: number, summary: string): Promise<void>;
+    /** Compress old build reports below {@link threshold} into a summary block. */
+    compressBuildReports(threshold: number, summary: string): Promise<void>;
+    /** Read a .papi/ file, returning empty string if it doesn't exist. */
+    private readOptional;
+    /** Strip build_handoff and build_report from a task before archiving — these are already in BUILD_REPORTS.md. */
+    private stripHeavyFields;
+    /** Append tasks to ARCHIVE_SPRINT_BOARD.md, stripping heavy fields and deduplicating by ID. */
+    private appendToArchive;
+    /** Archive tasks matching phases and/or statuses to ARCHIVE_SPRINT_BOARD.md and remove them from active board. */
+    archiveTasks(phases: string[], statuses?: string[]): Promise<{
+        archivedCount: number;
+        taskIds: string[];
+    }>;
+    /** Read the raw PRODUCT_BRIEF.md content. */
+    readProductBrief(): Promise<string>;
+    /** Overwrite PRODUCT_BRIEF.md with new content. */
+    updateProductBrief(content: string): Promise<void>;
+    /** Read all phases from PHASES.md (falls back to PRODUCT_BRIEF.md for migration). */
+    readPhases(): Promise<Phase[]>;
+    /** Write phases to PHASES.md. */
+    writePhases(phases: Phase[]): Promise<void>;
+    /** Read all features from FEATURES.md. */
+    readFeatures(): Promise<Feature[]>;
+    /** Get a single feature by UUID. */
+    getFeature(id: string): Promise<Feature | null>;
+    /** Create a new feature and append it to FEATURES.md. */
+    createFeature(feature: Omit<Feature, 'id'>): Promise<Feature>;
+    /** Update an existing feature by UUID. */
+    updateFeature(id: string, updates: Partial<Omit<Feature, 'id'>>): Promise<void>;
+    /** Write all features to FEATURES.md. */
+    private writeFeatures;
+    /** Append a tool call metric entry to METRICS.md. */
+    appendToolMetric(metric: ToolCallMetric): Promise<void>;
+    /** Read all tool call metrics from METRICS.md. */
+    readToolMetrics(): Promise<ToolCallMetric[]>;
+    /** Aggregate tool call metrics into a cost summary, optionally filtered by sprint. */
+    getCostSummary(sprintNumber?: number): Promise<CostSummary>;
+    /** Write a cost snapshot to the Cost Summary section of METRICS.md. */
+    writeCostSnapshot(snapshot: CostSnapshot): Promise<void>;
+    /** Read all cost snapshots from the Cost Summary section of METRICS.md. */
+    getCostSnapshots(): Promise<CostSnapshot[]>;
+    /** Append a sprint metrics snapshot to SPRINT_METRICS.md. */
+    appendSprintMetrics(snapshot: SprintMetricsSnapshot): Promise<void>;
+    /** Read all sprint metrics snapshots from SPRINT_METRICS.md. */
+    readSprintMetrics(): Promise<SprintMetricsSnapshot[]>;
+    /** Read all Sprint entities from SPRINTS.md (newest first). */
+    readSprints(): Promise<Sprint[]>;
+    /** Write a new Sprint entity to SPRINTS.md. */
+    createSprint(sprint: Sprint): Promise<void>;
+    /** Read module and epic registries from REGISTRIES.md. */
+    readRegistries(): Promise<Registries>;
+    /** Overwrite REGISTRIES.md with updated registries. */
+    updateRegistries(registries: Registries): Promise<void>;
+    /**
+     * Write a new strategy recommendation to STRATEGY_RECOMMENDATIONS.md.
+     * File-based implementation stores as YAML entries.
+     */
+    writeRecommendation(rec: Omit<StrategyRecommendation, 'id'>): Promise<StrategyRecommendation>;
+    /** Read all pending (unactioned) strategy recommendations. */
+    getPendingRecommendations(): Promise<StrategyRecommendation[]>;
+    /** Mark a recommendation as actioned. */
+    actionRecommendation(id: string, sprintNumber: number): Promise<void>;
+    appendDecisionEvent(event: Omit<DecisionEvent, 'id' | 'createdAt'>): Promise<DecisionEvent>;
+    getDecisionEvents(decisionId: string, limit?: number): Promise<DecisionEvent[]>;
+    getDecisionEventsSince(sprint: number): Promise<DecisionEvent[]>;
+    private parseDecisionEvents;
+    writeDecisionScore(score: Omit<DecisionScore, 'id' | 'createdAt' | 'totalScore'>): Promise<DecisionScore>;
+    getDecisionScores(decisionId: string): Promise<DecisionScore[]>;
+    getLatestDecisionScores(): Promise<DecisionScore[]>;
+    private parseDecisionScores;
+    logEntityReferences(_refs: Omit<EntityReference, 'id' | 'createdAt'>[]): Promise<void>;
+    getDecisionUsage(_currentSprint: number): Promise<DecisionUsageSummary[]>;
+}
+
+/** Validate and normalise an effort string to EffortSize. Returns the value or undefined if invalid. */
+declare function parseEffortSize(value: string): EffortSize | undefined;
+
+/**
+ * Parse a BUILD HANDOFF markdown string into a structured BuildHandoff object.
+ * Returns null if the string is not a recognisable handoff block.
+ */
+declare function parseBuildHandoff(markdown: string): BuildHandoff | null;
+/** Serialize a BuildHandoff object back into the standard markdown format. */
+declare function serializeBuildHandoff(handoff: BuildHandoff): string;
+
+/** Calculate Tier 1 sprint metrics from build reports. */
+declare function calculateSprintMetrics(reports: BuildReport[], currentSprint: number, window?: number): {
+    accuracy: SprintEstimationAccuracy[];
+    velocity: SprintVelocity[];
+};
+/**
+ * Detect recurring patterns across build reports.
+ * Analyzes surprises, estimation bias, scope accuracy, and untriaged discovered issues.
+ * When a TextClusterer is provided, uses LLM-based semantic clustering for surprises
+ * instead of normalised string matching.
+ */
+declare function detectBuildPatterns(reports: BuildReport[], currentSprint: number, window?: number, clusterer?: TextClusterer): Promise<BuildPatterns>;
+/** Returns true if the patterns contain any actionable findings. */
+declare function hasBuildPatterns(patterns: BuildPatterns): boolean;
+
+/** Parse REVIEWS.md content into an array of HumanReview objects (newest first). */
+declare function parseReviews(content: string): HumanReview[];
+/** Serialize a single HumanReview to a markdown block. */
+declare function serializeReview(review: HumanReview): string;
+/** Insert a new review at the top of REVIEWS.md (after the header). */
+declare function prependReview(review: HumanReview, content: string): string;
+
+/**
+ * Detect recurring patterns across human reviews.
+ * Analyzes comments for recurring feedback themes, verdict breakdown, and request-changes rate.
+ * When a TextClusterer is provided, uses LLM-based semantic clustering for feedback
+ * instead of normalised string matching.
+ */
+declare function detectReviewPatterns(reviews: HumanReview[], currentSprint: number, window?: number, clusterer?: TextClusterer): Promise<ReviewPatterns>;
+/** Returns true if the patterns contain any actionable findings. */
+declare function hasReviewPatterns(patterns: ReviewPatterns): boolean;
+
+/** Parse METRICS.md tool call metrics table into ToolCallMetric objects. */
+declare function parseToolMetrics(content: string): ToolCallMetric[];
+/** Serialize a ToolCallMetric to a markdown table row. */
+declare function serializeToolMetric(metric: ToolCallMetric): string;
+/** Append a tool metric row to METRICS.md content. Creates the file template if content is empty. */
+declare function appendToolMetricToContent(metric: ToolCallMetric, content: string): string;
+/** Aggregate tool call metrics into a cost summary, optionally filtered by sprint. */
+declare function aggregateCostSummary(metrics: ToolCallMetric[], sprintNumber?: number): CostSummary;
+
+/** Parse the PHASES YAML section from PRODUCT_BRIEF.md content. */
+declare function parsePhases(content: string): Phase[];
+/** Serialize an array of phases to a YAML block. */
+declare function serializePhases(phases: Phase[]): string;
+/** Serialize phases and write them into the PHASES section of PRODUCT_BRIEF.md content. */
+declare function writePhasesToContent(phases: Phase[], content: string): string;
+
+/** Parse the FEATURES YAML section from FEATURES.md content. */
+declare function parseFeatures(content: string): Feature[];
+/** Serialize an array of features to a YAML block. */
+declare function serializeFeatures(features: Feature[]): string;
+/** Serialize features and write them into the FEATURES section of FEATURES.md content. */
+declare function writeFeaturesToContent(features: Feature[], content: string): string;
+
+/** Parse SPRINTS.md content into an array of Sprint objects (newest first). */
+declare function parseSprints(content: string): Sprint[];
+/** Serialize sprints to a complete SPRINTS.md file content. */
+declare function serializeSprints(sprints: Sprint[], content: string): string;
+/** Serialize a single Sprint to a YAML string (for display/export). */
+declare function serializeSprint(sprint: Sprint): string;
+/** Add a new sprint to SPRINTS.md (prepended to the array so newest is first). */
+declare function prependSprint(sprint: Sprint, content: string): string;
+
+/** Parse REGISTRIES.md content into a Registries object. */
+declare function parseRegistries(content: string): Registries;
+/** Serialize registries back into REGISTRIES.md content, preserving surrounding text. */
+declare function serializeRegistries(registries: Registries, content: string): string;
+
+/**
+ * Shared entity interfaces for the cross-project layer.
+ *
+ * These types model the shared memory domain described in domain-model.md
+ * (Section: Shared Entities). Both the current MdFileAdapter and a future
+ * PgAdapter implement these same interfaces.
+ *
+ * @see docs/domain-model.md — Shared Entities
+ */
+/** Confidence level for shared decisions. @see domain-model.md — SharedDecision */
+type SharedDecisionConfidence = 'low' | 'medium' | 'high';
+/** Lifecycle status of a shared decision. @see domain-model.md — SharedDecision */
+type SharedDecisionStatus = 'proposed' | 'accepted' | 'superseded';
+/** Acknowledgement response status. @see domain-model.md — Acknowledgement */
+type AcknowledgementStatus = 'pending' | 'accepted' | 'rejected';
+/** Shared milestone lifecycle status. @see domain-model.md — SharedMilestone */
+type SharedMilestoneStatus = 'not_started' | 'in_progress' | 'complete';
+/** Project contribution status toward a milestone. @see domain-model.md — ProjectContribution */
+type ProjectContributionStatus = 'blocked' | 'in_progress' | 'delivered';
+/** Classification of a detected conflict. @see domain-model.md — ConflictAlert */
+type ConflictType = 'direct_contradiction' | 'assumption_mismatch' | 'north_star_drift' | 'staleness';
+/** How a conflict alert was raised. @see domain-model.md — ConflictAlert */
+type ConflictRaisedBy = 'heuristic' | 'llm' | 'human';
+/** Conflict alert lifecycle status. @see domain-model.md — ConflictAlert */
+type ConflictAlertStatus = 'open' | 'acknowledged' | 'resolved';
+/**
+ * A project registered in the shared layer.
+ * Every shared entity references a project — this is the anchor table.
+ *
+ * @see domain-model.md — Project Registry
+ */
+interface Project {
+    id: string;
+    slug: string;
+    name: string;
+    repo_url?: string;
+    papi_dir?: string;
+    created_at: string;
+    updated_at: string;
+}
+/**
+ * A cross-project decision that requires explicit acknowledgement from each project.
+ *
+ * @see domain-model.md — SharedDecision
+ */
+interface SharedDecision {
+    id: string;
+    display_id: string;
+    title: string;
+    decision: string;
+    confidence: SharedDecisionConfidence;
+    status: SharedDecisionStatus;
+    origin_project_id: string;
+    evidence: string;
+    superseded_by_id?: string;
+    created_at: string;
+    updated_at: string;
+    archived_at?: string;
+}
+/**
+ * Join between SharedDecision and Project.
+ * Each project must explicitly respond to a shared decision.
+ *
+ * @see domain-model.md — Acknowledgement
+ */
+interface Acknowledgement {
+    id: string;
+    decision_id: string;
+    project_id: string;
+    status: AcknowledgementStatus;
+    comments?: string;
+    responded_at?: string;
+    created_at: string;
+    updated_at: string;
+}
+/**
+ * A cross-project milestone that tracks what each project owes.
+ *
+ * @see domain-model.md — SharedMilestone
+ */
+interface SharedMilestone {
+    id: string;
+    title: string;
+    description: string;
+    status: SharedMilestoneStatus;
+    target_date?: string;
+    completed_at?: string;
+    created_at: string;
+    updated_at: string;
+    archived_at?: string;
+}
+/**
+ * Self-referencing join for milestone ordering.
+ * Records that one milestone must complete before another can proceed.
+ *
+ * @see domain-model.md — MilestoneDependency
+ */
+interface MilestoneDependency {
+    id: string;
+    milestone_id: string;
+    depends_on_id: string;
+}
+/**
+ * Join between SharedMilestone and Project.
+ * Tracks what each project owes to a milestone.
+ *
+ * @see domain-model.md — ProjectContribution
+ */
+interface ProjectContribution {
+    id: string;
+    milestone_id: string;
+    project_id: string;
+    status: ProjectContributionStatus;
+    required_phases: string[];
+    notes?: string;
+    delivered_at?: string;
+    created_at: string;
+    updated_at: string;
+}
+/**
+ * A project's North Star statement, tracked over time.
+ * Enables drift detection when strategy reviews reveal unrecorded shifts.
+ *
+ * @see domain-model.md — NorthStar
+ */
+interface NorthStar {
+    id: string;
+    project_id: string;
+    statement: string;
+    set_at: string;
+    superseded_by_id?: string;
+    superseded_at?: string;
+    created_at: string;
+}
+/**
+ * A detected conflict or drift between projects.
+ * Can be raised by heuristic rules, LLM reasoning, or human observation.
+ *
+ * @see domain-model.md — ConflictAlert
+ */
+interface ConflictAlert {
+    id: string;
+    conflict_type: ConflictType;
+    title: string;
+    description: string;
+    status: ConflictAlertStatus;
+    decision_a_id?: string;
+    decision_b_id?: string;
+    north_star_id?: string;
+    resolution_decision_id?: string;
+    raised_by: ConflictRaisedBy;
+    created_at: string;
+    updated_at: string;
+    resolved_at?: string;
+}
+
+export { type Acknowledgement, type AcknowledgementStatus, type ActiveDecision, type BoardQueryOptions, type BuildHandoff, type BuildPatterns, type BuildReport, type ClusterEntry, type ClusterResult, type CommandCost, type Confidence, type ConflictAlert, type ConflictAlertStatus, type ConflictRaisedBy, type ConflictType, type ContextHashes, type ContextTier, type CostSnapshot, type CostSummary, type DecisionEvent, type DecisionEventSource, type DecisionEventType, type DecisionScore, type DecisionUsageSummary, type EffortSize, type EntityReference, type Feature, type FeatureStatus, type HumanReview, MdFileAdapter, type MilestoneDependency, type NorthStar, type PapiAdapter, type Phase, type PhaseStatus, type PlanContextSummary, type PlanWriteBackPayload, type PlanWriteBackResult, type PlanningLog, type Project, type ProjectContribution, type ProjectContributionStatus, type RecommendationStatus, type RecommendationType, type RecurringFeedback, type RecurringSurprise, type Registries, type ReviewPatterns, type ReviewStage, type ReviewVerdict, type SharedDecision, type SharedDecisionConfidence, type SharedDecisionStatus, type SharedMilestone, type SharedMilestoneStatus, type Sprint, type SprintEstimationAccuracy, type SprintHealth, type SprintLogEntry, type SprintMetricsSnapshot, type SprintStatus, type SprintTask, type SprintVelocity, type StateTransition, type StrategyRecommendation, type StrategyReviewEntry, TASK_TYPE_TIERS, type TaskComplexity, type TaskMaturity, type TaskPriority, type TaskStatus, type TaskType, type TextClusterer, type ToolCallMetric, type UpdateTaskOptions, VALID_TRANSITIONS, aggregateCostSummary, appendToolMetricToContent, calculateSprintMetrics, detectBuildPatterns, detectReviewPatterns, hasBuildPatterns, hasReviewPatterns, isValidStatus, isValidTransition, parseBuildHandoff, parseEffortSize, parseFeatures, parsePhases, parseRegistries, parseReviews, parseSprints, parseToolMetrics, prependReview, prependSprint, serializeBuildHandoff, serializeFeatures, serializePhases, serializeRegistries, serializeReview, serializeSprint, serializeSprints, serializeToolMetric, validateTransition, writeFeaturesToContent, writePhasesToContent };