@papi-ai/adapter-md 0.1.1-alpha → 0.2.0

package/dist/index.d.ts

@@ -13,8 +13,12 @@ interface Phase {
     /** The stage this phase belongs to (AD-14 hierarchy). */
     stageId?: string;
 }
-/** Horizon status in the project hierarchy (AD-14). */
-type HorizonStatus = 'active' | 'completed' | 'deferred';
+/**
+ * Horizon status in the project hierarchy (AD-14). Shares the PhaseStatus
+ * vocabulary — the DB constraint + all live rows use 'Not Started'/'In Progress'/
+ * 'Done'/'Deferred', NOT the legacy 'active'/'completed'/'deferred' (task-2136).
+ */
+type HorizonStatus = PhaseStatus;
 /** A horizon — the highest level of the project hierarchy (AD-14: Horizon → Stage → Phase → Task). */
 interface Horizon {
     id: string;
@@ -27,8 +31,8 @@ interface Horizon {
     createdAt: string;
     updatedAt: string;
 }
-/** Stage status in the project hierarchy (AD-14). */
-type StageStatus = 'active' | 'completed' | 'deferred';
+/** Stage status in the project hierarchy (AD-14). Shares the PhaseStatus vocabulary (task-2136 — see HorizonStatus). */
+type StageStatus = PhaseStatus;
 /** A stage — sits between Horizon and Phase in the hierarchy (AD-14: Horizon → Stage → Phase → Task). */
 interface Stage {
     id: string;
@@ -39,6 +43,7 @@ interface Stage {
     sortOrder: number;
     horizonId: string;
     projectId: string;
+    exitCriteria?: string[];
     createdAt: string;
     updatedAt: string;
 }
@@ -62,6 +67,14 @@ interface Cycle {
     boardHealth: string;
     taskIds: string[];
     contextHashes?: ContextHashes;
+    /**
+     * task-2071 (C293, MU-3): the member who owns this cycle. Each member runs
+     * their own cycle into the shared repo; the DB enforces one active cycle per
+     * (project_id, user_id). createCycle stamps this from the calling identity;
+     * the C293 migration backfilled existing active cycles to the project owner so
+     * solo/owner-operated projects are unchanged. NULL = legacy/unowned.
+     */
+    userId?: string;
 }
 
 type TaskStatus = TaskStatus$1;
@@ -92,6 +105,17 @@ type Confidence = 'HIGH' | 'MEDIUM' | 'LOW';
 type DecisionEventType = 'created' | 'confidence_changed' | 'modified' | 'superseded' | 'validated' | 'invalidated' | 'scored';
 /** Source of a decision event. */
 type DecisionEventSource = 'strategy_review' | 'build_complete' | 'strategy_change' | 'manual';
+/**
+ * Structured before->after movement of a single metric, captured on a
+ * deliberate decision event (task-2168). Consumes cycle_metrics_snapshots.
+ */
+interface MetricDelta {
+    /** Metric name — ideally a real metric from cycle_metrics_snapshots. */
+    metric: string;
+    before?: number;
+    after?: number;
+    delta?: number;
+}
 /** An append-only event in a decision's lifecycle. */
 interface DecisionEvent {
     id: string;
@@ -101,6 +125,14 @@ interface DecisionEvent {
     source: DecisionEventSource;
     sourceRef?: string;
     detail?: string;
+    /**
+     * Pointer to supporting evidence (doc path / build-report id / metric name).
+     * Captured on deliberate events (validated / invalidated / modified) at
+     * strategy_review / strategy_change. Optional — writer fails open (task-2168).
+     */
+    evidenceRef?: string;
+    /** Which metric moved + before->after for this decision (task-2168). */
+    metricDelta?: MetricDelta | null;
     createdAt: string;
 }
 /** Dimensional scores for an Active Decision at a point in time. */
@@ -126,6 +158,8 @@ interface CycleHealth {
     boardHealth: string;
     strategicDirection: string;
     lastFullMode: number;
+    /** Number of auth.users rows with no matching user_profiles row. Non-zero = trigger gap. pg adapter only. */
+    orphanAuthUsers?: number;
 }
 /** An Active Decision (AD) tracked in the planning log. */
 interface ActiveDecision {
@@ -139,7 +173,7 @@ interface ActiveDecision {
     createdCycle?: number;
     modifiedCycle?: number;
     body: string;
-    outcome?: 'pending' | 'validated' | 'revised' | 'abandoned' | 'superseded';
+    outcome?: 'pending' | 'confirmed' | 'validated' | 'revised' | 'resolved' | 'abandoned' | 'superseded';
     revisionCount?: number;
 }
 /** A single cycle entry in the planning log. */
@@ -150,6 +184,16 @@ interface CycleLogEntry {
     content: string;
     carryForward?: string;
     notes?: string;
+    /** Number of tasks in this cycle (structured — no prose parsing needed). */
+    taskCount?: number;
+    /** Total effort points for this cycle (XS=1, S=2, M=3, L=5, XL=8). */
+    effortPoints?: number;
+    /**
+     * ISO timestamp for when this cycle log entry was last written (plan or
+     * release). Optional — historical entries may not have it. Surfaced from
+     * planning_log_entries.updated_at in the pg adapter.
+     */
+    date?: string;
 }
 /** A strategy review entry stored in its own table (not planning_log_entries). */
 interface StrategyReviewEntry {
@@ -166,6 +210,49 @@ interface StrategyReviewEntry {
     /** Full ReviewStructuredOutput from the strategy review LLM, stored as JSONB for dashboard querying */
     structuredData?: Record<string, unknown>;
     createdAt?: string;
+    /** Sequential review number per project (1, 2, 3...) */
+    reviewNumber?: number;
+    /** Review type: 'scheduled' (every 5 cycles), 'ad-hoc' (user-triggered), 'triggered' (by event) */
+    reviewType?: string;
+}
+/**
+ * A single entry in a project's harness inventory (task-1896).
+ * Captures what skills / sub-agents / hooks / MCP tools a project is running,
+ * scanned from the local filesystem by the MCP server and persisted so the
+ * dashboard (which has no filesystem access) can surface it per project.
+ */
+interface HarnessInventoryEntry {
+    id?: string;
+    projectId?: string;
+    /** What kind of harness artifact this row describes. */
+    kind: 'skill' | 'agent' | 'hook' | 'mcp_tool';
+    /** Human-readable name (skill/agent/hook filename stem, or MCP tool name). */
+    name: string;
+    /** One-line description where available (frontmatter / tool description). */
+    description?: string;
+    /** Version of the artifact, where known (skills, from the @papi-ai/skills manifest). */
+    version?: string;
+    /** Content checksum, where known (skills — used to detect stale forks). */
+    checksum?: string;
+    /**
+     * Status signal surfaced in the dashboard:
+     * - 'ok': present and current
+     * - 'stale_fork': a local skill that has drifted from the pinned registry version
+     * - 'missing': a recommended hook that is not installed in the project
+     */
+    status: 'ok' | 'stale_fork' | 'missing';
+    /** Project-relative path, where applicable (never absolute, never file contents). */
+    path?: string;
+    syncedAt?: string;
+}
+/**
+ * Change-detection marker for the harness inventory (task-1896).
+ * A cheap fingerprint of the project's harness layout; the sync writer only
+ * does the full scan + DB write when this fingerprint changes.
+ */
+interface HarnessState {
+    fingerprint: string;
+    syncedAt?: string;
 }
 /** A dogfood observation captured during strategy reviews or releases. */
 interface DogfoodEntry {
@@ -175,7 +262,8 @@ interface DogfoodEntry {
     category: 'friction' | 'methodology' | 'signal' | 'commercial';
     content: string;
     sourceTool?: string;
-    status?: 'observed' | 'backlog-created' | 'resolved';
+    sourceRef?: string;
+    status?: 'observed' | 'backlog-created' | 'resolved' | 'actioned' | 'dismissed';
     linkedTaskId?: string;
     createdAt?: string;
 }
@@ -192,7 +280,17 @@ interface StateTransition {
     status: TaskStatus;
     timestamp: string;
 }
+/** AD-29: scope_class distinguishes directly-buildable tasks from brief-class items needing decomposition. */
+type ScopeClass = 'task' | 'brief';
 /** A task on the board (parsed from CYCLE_BOARD.md YAML). */
+/** A sibling project's in-flight task, surfaced for the plan duplicate-risk check (task-2139). */
+interface SiblingRepoTask {
+    displayId: string;
+    title: string;
+    epic?: string;
+    status: string;
+    sourceProjectName: string;
+}
 interface CycleTask {
     uuid: string;
     id: string;
@@ -221,6 +319,50 @@ interface CycleTask {
     buildReport?: string;
     taskType?: TaskType;
     maturity?: TaskMaturity;
+    /** Path to a reference document (e.g. docs/research/foo.md). */
+    docRef?: string;
+    /** Provenance: where this task originated (owner, llm, strategy_review, etc.). */
+    source?: string;
+    /** What user problem does this solve? Used by planner for opportunity-based clustering. */
+    opportunity?: string;
+    /** AD-29: 'task' = directly buildable; 'brief' = needs scope_brief decomposition first. Default 'task'. */
+    scopeClass?: ScopeClass;
+    /** task-1699 (C255): audit who initiated a cancellation. Set when status transitions to 'Cancelled'.
+     *  'planner' = planner proposed + user confirmed; 'user' = direct user action; 'system' = automated. */
+    cancelledBy?: 'planner' | 'user' | 'system';
+    /**
+     * Visibility tier (task-2013). Inherited from the source doc when a task is born
+     * from `idea`/`plan` with a doc_ref; defaults to 'public'. Read-only after creation —
+     * build_execute/review_submit must NOT mutate it.
+     */
+    visibility?: DocVisibility;
+    /** Owner lock (task-2013) — set on private/contributors rows so a project_id reassignment cannot expose them. */
+    ownerUserId?: string;
+    /**
+     * task-1763 (C293): claim assignee — the user who has claimed this task from the
+     * shared pool. NULL/undefined = unclaimed. Set only via the atomic claimTask CAS
+     * (bearer-derived identity, never client input). Consumed by MU-3 (task-2071).
+     */
+    assigneeId?: string;
+    /**
+     * task-2071 (C293, MU-3): how this task entered a personal backlog. 'pool' =
+     * claimed from the shared org pool via task_claim; 'self_generated' = created
+     * already attributed to a user. NULL/undefined = legacy/unattributed. The
+     * pooled-task invariant is `assigneeId == null && cycle == null`.
+     */
+    claimSource?: 'pool' | 'self_generated';
+    /**
+     * task-2071 (C293): reviewer slot for MU-4/5 (cross-user review, task-2072).
+     * Schema-only this task — no code reads it yet.
+     */
+    reviewerId?: string;
+    /**
+     * task-2180 (C295): ISO timestamp the task's branch was successfully merged to the
+     * base branch (review_submit accept or release). NULL/undefined = not yet merged.
+     * Write-only audit tie between Done status and git reality — set on a successful
+     * merge so a Done task is provably backed by a real merge; no reader yet.
+     */
+    mergedAt?: string;
 }
 /** Structured handoff accuracy — replaces coarse scope_accuracy text. */
 interface HandoffAccuracy {
@@ -253,11 +395,113 @@ interface BuildReport {
     scopeAccuracy: 'accurate' | 'over-scoped' | 'under-scoped' | 'missed-context';
     commitSha?: string;
     filesChanged?: string[];
+    /**
+     * task-1523 (C242): scope drift signal.
+     * Populated when filesChanged diverges materially from the handoff's filesLikelyTouched
+     * (e.g. >50% of changed files unpredicted, or >5 unexpected files). Format is a single
+     * human-readable line surfaced under "Scope drift signal" in the build report. Does NOT block.
+     */
+    scopeDriftSignal?: string;
     relatedDecisions?: string[];
     handoffAccuracy?: HandoffAccuracy;
     correctionsCount?: number;
     briefImplications?: BriefImplication[];
     deadEnds?: string;
+    /** Number of build iterations for this task (1 = first attempt, 2+ = rework after pushback). */
+    iterationCount?: number;
+    /** ISO 8601 timestamp when build_execute (start) was called. */
+    startedAt?: string;
+    /** ISO 8601 timestamp when build_execute (complete) was called. */
+    completedAt?: string;
+    /** Number of tool calls recorded during this build session. */
+    toolCallCount?: number;
+    /**
+     * task-1853 deploy-verification record. Populated when the task's diff hit a
+     * trigger surface (TRIGGER_SURFACE_GLOBS) and the builder verified the live deploy.
+     * Required by `completeBuild` for trigger-surface tasks; gates `review_submit` accept.
+     */
+    productionVerification?: {
+        urls: string[];
+        curl_command: string;
+        http_status: number;
+        response_excerpt: string;
+        verified_at: string;
+    };
+}
+/** A registered document in the doc registry. */
+/**
+ * Doc visibility tier (task-1977, C283).
+ * - public: shipped with PAPI, readable cross-project by any user.
+ * - contributors: "team member" tier — readable by the project's contributor cohort.
+ * - private: owner-only (default — safety bias).
+ * User-facing label for `contributors` is "team member".
+ */
+type DocVisibility = 'public' | 'contributors' | 'private';
+interface DocRegistryEntry {
+    id: string;
+    title: string;
+    type: string;
+    path: string;
+    status: string;
+    summary: string;
+    tags: string[];
+    cycleCreated: number;
+    cycleUpdated?: number;
+    supersededBy?: string;
+    actions?: Array<{
+        description: string;
+        status: string;
+        linkedTaskId?: string;
+    }>;
+    /** Visibility tier (task-1977). Defaults to 'private' at write time when omitted. */
+    visibility?: DocVisibility;
+    /** Owner lock — the user_id that owns this doc; set on register so a project_id reassignment cannot expose private rows. */
+    ownerUserId?: string;
+    createdAt?: string;
+    updatedAt?: string;
+}
+/** A structured learning entry from a build report. */
+interface CycleLearning {
+    id?: string;
+    projectId?: string;
+    taskId: string;
+    cycleNumber: number;
+    category: 'surprise' | 'issue' | 'dead_end' | 'architecture' | 'estimation_miss' | 'doc_closure' | 'observability';
+    severity?: 'P0' | 'P1' | 'P2' | 'P3';
+    summary: string;
+    detail?: string;
+    tags: string[];
+    relatedDecision?: string;
+    actionTaken?: 'idea_submitted' | 'task_created' | 'ad_updated' | 'none';
+    actionRef?: string;
+    createdAt?: string;
+    /** When the underlying issue was marked resolved. null/undefined = still open. (task-1541) */
+    resolvedAt?: string;
+    /** Identifier of the agent/user that resolved the issue (task-1541). */
+    resolvedBy?: string;
+}
+/** A cross-cycle pattern detected from learning tags. */
+interface CycleLearningPattern {
+    tag: string;
+    cycles: number[];
+    frequency: number;
+}
+/** Input for doc_search queries. */
+interface DocSearchInput {
+    type?: string;
+    status?: string;
+    tags?: string[];
+    keyword?: string;
+    hasPendingActions?: boolean;
+    sinceCycle?: number;
+    limit?: number;
+    /**
+     * Visibility scoping (task-1977). The user_id of the requester. When set and the
+     * requester is NOT the project owner, results are filtered to public docs plus
+     * contributors-tier docs the requester is a cohort member of (private excluded —
+     * fail-closed). When omitted (local owner/CLI context), all rows are returned.
+     */
+    requesterUserId?: string;
 }
 /** Aggregated recommendation effectiveness row from v_recommendation_effectiveness. */
 interface RecommendationEffectivenessRow {
@@ -276,6 +520,15 @@ interface EstimationCalibrationRow {
     accuracyLabel: string;
     count: number;
 }
+/** Per-module estimation stats — builds joined with task module via cycle_tasks. */
+interface ModuleEstimationRow {
+    module: string;
+    total: number;
+    /** % of tasks where estimated effort matched actual effort. */
+    accuracyPct: number;
+    /** % of tasks where scope_accuracy was 'accurate'. */
+    scopeAccuratePct: number;
+}
 /** A single tool call metric entry from METRICS.md. */
 interface ToolCallMetric {
     timestamp: string;
@@ -291,6 +544,15 @@ interface ToolCallMetric {
     contextBytes?: number;
     /** Context utilisation ratio (0.0–1.0). Fraction of input entities referenced in output. */
     contextUtilisation?: number;
+    /** Whether the tool call succeeded (no error prefix in response). */
+    success?: boolean;
+    /**
+     * MCP client `Implementation.name` advertised at initialize time.
+     * Captured verbatim (Claude Code = "claude-code"; Codex advertises a
+     * different string). Used to split activation/feature funnels by CLI.
+     * Absent on legacy rows + non-MCP code paths. (task-1680)
+     */
+    clientName?: string;
 }
 /** Per-command cost aggregation. */
 interface CommandCost {
@@ -452,12 +714,27 @@ interface BuildHandoff {
     securityConsiderations: string;
     filesLikelyTouched: string[];
     effort: EffortSize;
+    /** Files the builder should check before implementing to verify the feature doesn't already exist. */
+    verificationFiles?: string[];
 }
 /** Module and epic registries loaded from REGISTRIES.md. */
 interface Registries {
     modules: string[];
     epics: string[];
 }
+/** Lifecycle status for a queued strategy review agenda topic. */
+type AgendaTopicStatus = 'pending' | 'addressed' | 'dismissed';
+/** A topic queued for the next strategy review. */
+interface AgendaTopic {
+    id: string;
+    topic: string;
+    source: string;
+    sourceCycle?: number;
+    status: AgendaTopicStatus;
+    createdAt: string;
+    addressedAt?: string;
+    addressedInReview?: number;
+}
 /** 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. */
@@ -472,6 +749,22 @@ interface StrategyRecommendation {
     actionedCycle?: number;
     target?: string;
 }
+/** Upstream submission (bug or idea) sent to PAPI for cross-project visibility. */
+interface BugReport {
+    id: string;
+    projectId: string;
+    userId?: string;
+    /** Kind of submission. Defaults to 'bug' for back-compat with the legacy `bug report=true` flow (task-2174, C296). */
+    type?: 'bug' | 'idea';
+    description: string;
+    diagnostics: Record<string, unknown>;
+    status: 'open' | 'resolved' | 'dismissed';
+    /** Submitter opted in to be notified when this is resolved (friction-moment opt-in). */
+    notifyRequested?: boolean;
+    /** Submitter consented to the PAPI team reaching out about this submission. */
+    contactOk?: boolean;
+    createdAt: string;
+}
 /** Entity reference — tracks which decisions/entities are used in tool calls. */
 interface EntityReference {
     id: string;
@@ -514,31 +807,175 @@ interface BoardQueryOptions {
     contextTier?: ContextTier;
     /** Filter to tasks assigned to this cycle or later (cycle >= N). */
     cycleSince?: number;
+    /** Exclude heavy JSONB columns (build_handoff, build_report, state_history) to reduce DB transfer. */
+    compact?: boolean;
+    /**
+     * Visibility scoping (task-2013). The user_id of the requester. When set and the
+     * requester is NOT the project owner, results are filtered to public tasks plus
+     * contributors-tier tasks the requester is a cohort member of (private excluded —
+     * fail-closed). When omitted (local owner/CLI context), all rows are returned.
+     * Mirrors DocSearchInput.requesterUserId exactly.
+     */
+    requesterUserId?: string;
+    /**
+     * task-2071 (C293, MU-3): filter to tasks claimed by this user (assignee_id =
+     * value). Used by plan's per-user "draw from my personal backlog" path. Does
+     * NOT widen visibility — it narrows an already-authorised result set.
+     */
+    assigneeId?: string;
+}
+interface OwnerActionInput {
+    name: string;
+    project_ids?: string[];
+    category?: string | null;
+    status?: 'todo' | 'waiting' | 'done';
+    dependency?: string | null;
+    docs_link?: string | null;
+    unlocks_task_id?: string | null;
+}
+interface OwnerActionRow extends OwnerActionInput {
+    id: string;
+    user_id: string;
+    project_ids: string[];
+    status: 'todo' | 'waiting' | 'done';
+    completed_at: string | null;
+    created_at: string;
+    updated_at: string;
 }
 /** Core adapter interface for reading/writing .papi/ markdown files. */
 interface PapiAdapter {
     readPlanningLog(): Promise<PlanningLog>;
     getCycleHealth(): Promise<CycleHealth>;
-    getActiveDecisions(): Promise<ActiveDecision[]>;
+    /**
+     * Read Active Decisions for this project.
+     *
+     * Default behaviour (no options or `{ includeRetired: false }`) excludes ADs that
+     * are no longer steering the project: outcome ∈ ('abandoned', 'superseded', 'resolved')
+     * OR superseded = true. This is the correct signal for context-injection surfaces
+     * (orient, build_execute handoffs, plan context, strategy housekeeping displays).
+     *
+     * Pass `{ includeRetired: true }` for management/triage surfaces that need to see
+     * retired ADs explicitly — e.g. strategy_review (so retired ADs can be re-validated
+     * or restored), and any code that needs the full ID space (next-AD-number computation,
+     * dedupe against existing IDs, lifecycle counts).
+     *
+     * task-1546 (C242 hot-fix): closes the bug where retired ADs (e.g. AD-26, abandoned
+     * in C241) continued to appear in build/plan/orient context as "active" because
+     * consumers only filtered the `superseded` boolean and ignored the `outcome` lifecycle.
+     */
+    getActiveDecisions(options?: {
+        includeRetired?: boolean;
+    }): Promise<ActiveDecision[]>;
+    /** Query ADs from sibling project IDs in the same Supabase instance. pg adapter only. */
+    getSiblingAds?(projectIds: string[]): Promise<Array<ActiveDecision & {
+        sourceProjectId: string;
+    }>>;
+    /**
+     * task-2139: in-flight tasks from OTHER projects that share THIS project's
+     * repo_url. Surfaced in plan prepare context so the planner does not
+     * re-schedule work already underway on the shared repo (the C292 duplicate
+     * incident). Scoped to repo_url siblings (never the whole DB); returns only
+     * the fields the dup-check needs. pg adapter only — md/proxy omit it and the
+     * caller feature-checks.
+     */
+    getSiblingRepoTasks?(): Promise<SiblingRepoTask[]>;
     getCycleLog(limit?: number): Promise<CycleLogEntry[]>;
     getCycleLogSince(cycleNumber: number): Promise<CycleLogEntry[]>;
     setCycleHealth(updates: Partial<CycleHealth>): Promise<void>;
     writeCycleLogEntry(entry: CycleLogEntry): Promise<void>;
-    updateActiveDecision(id: string, body: string, cycleNumber?: number): Promise<void>;
+    updateActiveDecision(id: string, body: string, cycleNumber?: number, action?: 'confidence_change' | 'modify' | 'resolve' | 'supersede' | 'new' | 'delete'): Promise<void>;
     /** Upsert an AD — creates if display_id doesn't exist, updates if it does. */
     upsertActiveDecision?(id: string, body: string, title: string, confidence: string, cycleNumber: number): Promise<void>;
     /** Delete an AD permanently by display_id. */
     deleteActiveDecision?(id: string): Promise<void>;
+    /** After a strategy review, mark all still-pending ADs as confirmed (reviewed, no changes). */
+    confirmPendingActiveDecisions?(cycleNumber: number): Promise<void>;
     queryBoard(options?: BoardQueryOptions): Promise<CycleTask[]>;
     getTask(id: string): Promise<CycleTask | null>;
     getTasks(ids: string[]): Promise<CycleTask[]>;
     createTask(task: Omit<CycleTask, 'id'>): Promise<CycleTask>;
+    /**
+     * task-1917 (C280): Owner Action Queue support.
+     * Optional — only adapters backed by a database that has the owner_actions
+     * table need to implement these. Callers must feature-check before use:
+     *   if (adapter.createOwnerAction) { ... }
+     */
+    createOwnerAction?(userId: string, input: OwnerActionInput): Promise<OwnerActionRow>;
+    /**
+     * Count rows in owner_actions for the given user that are not yet
+     * completed. Used by orient to surface "N actions waiting on you".
+     * task-2041 (C284): optional projectId scopes to one project (untagged actions
+     * count as global). Omit it for the cross-project /hub aggregate.
+     */
+    countOpenOwnerActions?(userId: string, projectId?: string): Promise<number>;
+    /**
+     * Count open owner_actions a delegate has nudged the owner about (task-2018).
+     * Surfaced by orient separately from the open-count. Optional — md adapter and
+     * pre-v2 deployments simply skip the line. task-2041: optional projectId scope.
+     */
+    countNudgedOwnerActions?(userId: string, projectId?: string): Promise<number>;
+    /** task-2041 (C284): the project this adapter is scoped to (pg adapter only). */
+    getProjectId?(): string;
+    /**
+     * task-2051 (C284): count the user's OPEN owner actions whose unlocks_task_id
+     * points at a build task currently 'Blocked'. Surfaced by orient as a
+     * "complete these to unblock build work" nudge. Optional — md adapter and
+     * pre-status deployments skip the line.
+     */
+    countOwnerActionsBlockingTasks?(userId: string): Promise<number>;
+    /**
+     * Team Ops v4: count the user's OPEN owner actions by due date — dueToday
+     * (due_date = today) and overdue (due_date < today). Folded into orient's
+     * "N actions waiting on you" line. Optional — md adapter and pre-v4
+     * deployments skip the suffix. Optional projectId scope as countOpenOwnerActions.
+     */
+    countDueOwnerActions?(userId: string, projectId?: string): Promise<{
+        dueToday: number;
+        overdue: number;
+    }>;
     updateTask(id: string, updates: Partial<Omit<CycleTask, 'id'>>, options?: UpdateTaskOptions): Promise<void>;
     updateTaskStatus(id: string, status: TaskStatus): Promise<void>;
+    /**
+     * task-2182: correct a mis-recorded estimate/actual on the LATEST build report
+     * for a task. pg-only (project_id-scoped UPDATE on the MAX(created_at) row); md
+     * is legacy and omits it. Carried by board_edit's estimated_effort/actual_effort.
+     */
+    correctLatestBuildReportEffort?(taskId: string, fields: {
+        estimatedEffort?: string;
+        actualEffort?: string;
+    }): Promise<void>;
+    /**
+     * task-1763 (C293): atomic compare-and-swap task claim. Sets assignee_id ONLY if
+     * the task is currently unclaimed (assignee_id IS NULL) — first-claim-wins, no
+     * queueing. Returns the claimed task on success, or null if it was already claimed
+     * (or does not exist). assigneeId must be the bearer-derived identity, never client
+     * input; the implementation scopes by project_id so a claim can never cross tenant.
+     * Optional: the primitive layer for MU-3 (task-2071); proxy/edge wiring lands with
+     * the task_claim tool in task-2071.
+     */
+    claimTask?(taskId: string, assigneeId: string): Promise<CycleTask | null>;
+    /**
+     * task-2071 (C293, MU-3): atomic claimer-only release. Clears assignee_id (and
+     * claim_source) ONLY if the task is currently assigned to `assigneeId` AND has
+     * not yet entered review (status NOT IN 'In Review','Done'). Returns the
+     * unclaimed task on success, or null if the caller is not the claimer, the task
+     * has progressed past claim, or it does not exist. Scoped by project_id.
+     */
+    unclaimTask?(taskId: string, assigneeId: string): Promise<CycleTask | null>;
+    /**
+     * task-2072 (C293, MU-4): atomic compare-and-swap REVIEW claim — the cross-user
+     * review queue primitive. Sets reviewer_id ONLY if the task is currently In
+     * Review and unclaimed-for-review (reviewer_id IS NULL). Returns the claimed
+     * task on success, or null if another reviewer already claimed it, it is not In
+     * Review, or it does not exist. reviewerId is bearer-derived, never client
+     * input; scoped by project_id. First-claim-wins (no double-review race).
+     */
+    claimReview?(taskId: string, reviewerId: string): Promise<CycleTask | null>;
     /** Record a task status transition for audit trail. */
     recordTransition(taskId: string, fromStatus: string, toStatus: string, changedBy?: string): Promise<void>;
     appendBuildReport(report: BuildReport): Promise<void>;
     getRecentBuildReports(count: number): Promise<BuildReport[]>;
+    getBuildReportCountForTask(taskId: string): Promise<number>;
     getBuildReportsSince(cycleNumber: number): Promise<BuildReport[]>;
     getRecentReviews(count?: number): Promise<HumanReview[]>;
     writeReview(review: HumanReview): Promise<void>;
@@ -562,8 +999,11 @@ interface PapiAdapter {
     readStages?(horizonId?: string): Promise<Stage[]>;
     /** Update a stage's status (e.g. 'Active' → 'Complete'). */
     updateStageStatus?(stageId: string, status: string): Promise<void>;
+    updateStageExitCriteria?(stageId: string, exitCriteria: string[]): Promise<void>;
     /** Update a horizon's status (e.g. 'Active' → 'Complete'). */
     updateHorizonStatus?(horizonId: string, status: string): Promise<void>;
+    /** Update a phase's status (e.g. 'Active' → 'Complete'). */
+    updatePhaseStatus?(phaseId: string, status: string): Promise<void>;
     /** Get the currently active stage for the project. */
     getActiveStage?(): Promise<Stage | undefined>;
     /** Create a new horizon (AD-14 hierarchy). Returns the created horizon's ID. */
@@ -587,8 +1027,16 @@ interface PapiAdapter {
     linkPhasesToStage?(stageId: string): Promise<void>;
     appendToolMetric(metric: ToolCallMetric): Promise<void>;
     readToolMetrics(): Promise<ToolCallMetric[]>;
+    /** Count tool calls recorded between two ISO timestamps. Optional — pg only. */
+    getToolCallCount?(startedAt: string, completedAt: string): Promise<number>;
+    /**
+     * Cheap existence check for a single milestone tool name. Returns true when
+     * any tool_call_metrics row matches `tool = name`. Replaces full-table reads
+     * for one-shot orient checks (skill scan, TTFV) which previously pulled up
+     * to 5000 rows just to test for one milestone.
+     */
+    hasToolMilestone?(name: string): Promise<boolean>;
     getCostSummary(cycleNumber?: number): Promise<CostSummary>;
-    writeCostSnapshot(snapshot: CostSnapshot): Promise<void>;
     getCostSnapshots(): Promise<CostSnapshot[]>;
     appendCycleMetrics(snapshot: CycleMetricsSnapshot): Promise<void>;
     readCycleMetrics(): Promise<CycleMetricsSnapshot[]>;
@@ -600,6 +1048,20 @@ interface PapiAdapter {
     writeRecommendation(rec: Omit<StrategyRecommendation, 'id'>): Promise<StrategyRecommendation>;
     getPendingRecommendations(): Promise<StrategyRecommendation[]>;
     actionRecommendation(id: string, cycleNumber: number): Promise<void>;
+    dismissRecommendation?(id: string, reason: string): Promise<void>;
+    /**
+     * Append a topic to the strategy review agenda queue.
+     * Topics surface at the next strategy_review prepare phase and are marked addressed after apply.
+     */
+    addAgendaTopic?(topic: {
+        topic: string;
+        source: string;
+        sourceCycle?: number;
+    }): Promise<AgendaTopic>;
+    /** List pending (unaddressed) agenda topics for the current project. */
+    getPendingAgendaTopics?(): Promise<AgendaTopic[]>;
+    /** Mark a set of agenda topics as addressed in the given review cycle. */
+    markAgendaTopicsAddressed?(ids: string[], cycleNumber: number): Promise<void>;
     appendDecisionEvent(event: Omit<DecisionEvent, 'id' | 'createdAt'>): Promise<DecisionEvent>;
     getDecisionEvents(decisionId: string, limit?: number): Promise<DecisionEvent[]>;
     getDecisionEventsSince(cycle: number): Promise<DecisionEvent[]>;
@@ -613,10 +1075,88 @@ interface PapiAdapter {
     writeStrategyReview(review: StrategyReviewEntry): Promise<void>;
     getLastStrategyReviewCycle(): Promise<number>;
     getStrategyReviews(limit?: number, includeFullAnalysis?: boolean): Promise<StrategyReviewEntry[]>;
+    /** Save a strategy review LLM response that failed write-back, for retry next session. */
+    savePendingReviewResponse?(cycleNumber: number, rawResponse: string): Promise<void>;
+    /** Get the pending review response, if any. Returns null if none. */
+    getPendingReviewResponse?(): Promise<{
+        cycleNumber: number;
+        rawResponse: string;
+    } | null>;
+    /** Clear the pending review response after successful retry. */
+    clearPendingReviewResponse?(): Promise<void>;
+    /** Register a document in the doc registry. */
+    registerDoc?(entry: Omit<DocRegistryEntry, 'id' | 'createdAt' | 'updatedAt'>): Promise<DocRegistryEntry>;
+    /** Search documents by filters. */
+    searchDocs?(input: DocSearchInput): Promise<DocRegistryEntry[]>;
+    /** Get a single doc by ID or path. */
+    getDoc?(idOrPath: string): Promise<DocRegistryEntry | null>;
+    /** Update a doc's status (e.g. supersede, archive). */
+    updateDocStatus?(id: string, status: string, supersededBy?: string): Promise<void>;
+    /**
+     * Update a single action on a doc — used by `doc_action_promote` to mark an action
+     * as resolved and link it to the Backlog task that now owns the work.
+     * `actionIndex` is the 0-based index in the doc's `actions` array.
+     */
+    updateDocAction?(docId: string, actionIndex: number, update: {
+        status?: 'pending' | 'resolved';
+        linkedTaskId?: string;
+    }): Promise<void>;
+    /**
+     * Find every (doc, action) pair whose action references the given task and is still pending.
+     * Used by `submitReview` accept-path to auto-resolve doc actions when their owning task ships
+     * (task-1719). Bounded to 50 results per task — anything beyond is bug-shaped.
+     */
+    findPendingDocActionsForTask?(taskDisplayId: string): Promise<Array<{
+        docId: string;
+        actionIndex: number;
+        description: string;
+    }>>;
     writeDogfoodEntries?(entries: DogfoodEntry[]): Promise<void>;
     getDogfoodLog?(limit?: number): Promise<DogfoodEntry[]>;
     getUnactionedDogfoodEntries?(limit?: number): Promise<DogfoodEntry[]>;
     updateDogfoodEntryStatus?(id: string, status: DogfoodEntry['status'], linkedTaskId?: string): Promise<void>;
+    /**
+     * Harness inventory (task-1896). Persists per-project skills/agents/hooks/MCP
+     * tools so the dashboard can surface them. All scoped to the adapter's project.
+     * Optional — the md adapter does not implement these; the sync writer is a
+     * no-op when they are absent.
+     */
+    getHarnessInventory?(): Promise<HarnessInventoryEntry[]>;
+    /** Replace the entire inventory for this project in one atomic operation. */
+    replaceHarnessInventory?(entries: HarnessInventoryEntry[]): Promise<void>;
+    /** Read the stored change-detection fingerprint, or null if never synced. */
+    getHarnessState?(): Promise<HarnessState | null>;
+    /** Persist the change-detection fingerprint after a successful sync. */
+    setHarnessState?(fingerprint: string): Promise<void>;
+    /** Append structured cycle learning entries. */
+    appendCycleLearnings?(learnings: CycleLearning[]): Promise<void>;
+    /**
+     * Get cycle learnings, optionally filtered by cycle and/or category.
+     * `includeResolved` defaults to false — resolved discovered-issues (resolved_at IS NOT NULL)
+     * are excluded by default so planner / orient reads stay focused on still-open work (task-1541).
+     */
+    getCycleLearnings?(opts?: {
+        cycleNumber?: number;
+        category?: string;
+        limit?: number;
+        includeResolved?: boolean;
+    }): Promise<CycleLearning[]>;
+    /** Get cross-cycle patterns from learning tags (tags appearing in 2+ cycles). */
+    getCycleLearningPatterns?(): Promise<CycleLearningPattern[]>;
+    /** Set action_ref on a cycle learning to link it to the task that acted on it. */
+    updateCycleLearningActionRef?(learningId: string, taskDisplayId: string): Promise<void>;
+    /**
+     * Mark a cycle learning resolved. Sets resolved_at = NOW() and (optionally) resolved_by.
+     * Pg-only — md / proxy adapters can leave this unimplemented. (task-1541)
+     */
+    markCycleLearningResolved?(learningId: string, resolvedBy?: string): Promise<void>;
+    /**
+     * Auto-resolve discovered-issues (category='issue') whose linked task is Done/Cancelled,
+     * draining the stale-issue clog so orient/planner reads stay clean (task-2079, C291).
+     * Pass a task display_id to resolve only that task's issues (task→Done transition path);
+     * omit for a full sweep. Restricted to category='issue'. Pg-only; returns rows resolved.
+     */
+    resolveLearningsForDoneTasks?(taskDisplayId?: string): Promise<number>;
     /**
      * Optional: return the current (unsuperseded) North Star statement.
      * When implemented, plan and strategy_review use this instead of relying
@@ -636,11 +1176,21 @@ interface PapiAdapter {
         setCycle: number;
         setAt: string;
     } | null>;
+    /**
+     * Optional: persist a new North Star statement, superseding the previous active one.
+     * Called by strategy_review apply and strategy_change apply when the LLM outputs a northStar field.
+     */
+    upsertNorthStar?(statement: string, cycleNumber: number): Promise<void>;
     /**
      * Optional: return aggregated estimation calibration data from v_estimation_accuracy.
      * Used by the planner to adjust effort estimates based on historical patterns.
      */
     getEstimationCalibration?(): Promise<EstimationCalibrationRow[]>;
+    /**
+     * Optional: return per-module estimation accuracy stats from the last 20 cycles.
+     * Joins build_reports with cycle_tasks on task_id. pg adapter only.
+     */
+    getModuleEstimationStats?(): Promise<ModuleEstimationRow[]>;
     /**
      * Optional: return recent task comments for plan context.
      * Returns up to `limit` comments across all active tasks, newest first.
@@ -669,6 +1219,157 @@ interface PapiAdapter {
      * When not implemented, defaults to true (assumes project exists).
      */
     projectExists?(): Promise<boolean>;
+    /**
+     * Optional: fetch the project name, slug, papi_dir, and repo_url for connection + path-identity verification.
+     * `papi_dir` is the absolute path of the project's `.papi/` directory as stored in the database.
+     * Used by the path-identity guardrail to detect cwd↔stored-path mismatches.
+     * `repo_url` (task-1979, C279) is the GitHub URL the project is associated with, used by the
+     * release tool's remote-project guard. Optional in the result so adapters that don't expose it
+     * can return null without breaking legacy callers.
+     */
+    getProjectInfo?(): Promise<{
+        name: string;
+        slug: string;
+        papi_dir?: string | null;
+        repo_url?: string | null;
+    } | null>;
+    /**
+     * Optional: persist a new value for the project's papi_dir column. Used by the path-identity
+     * guardrail when backfilling legacy null values or applying PAPI_ALLOW_PATH_MIGRATE updates.
+     */
+    setProjectPapiDir?(papiDir: string): Promise<void>;
+    /**
+     * Optional: resolve the user_id that owns the currently-bound project.
+     * Returns null for legacy pre-multi-user projects whose row was created before the
+     * user_id column existed. Used by verifyProject's detect-only legacy-project probe
+     * (task-1621). pg-only — md/proxy adapters can leave it unimplemented.
+     */
+    getProjectOwnerUserId?(): Promise<string | null>;
+    /**
+     * Optional (task-2052, C288): resolve BOTH sides of the owner-gate identity in
+     * one call — who is calling, and who owns the project. On the proxy adapter the
+     * edge function derives callerUserId from the bearer token server-side, so a
+     * hosted/proxy owner is recognised without needing PAPI_USER_ID configured
+     * locally (and a non-owner cannot claim ownership by setting it). Adapters that
+     * cannot resolve the caller (pg/md, where identity comes from local config)
+     * leave this unimplemented and the gate falls back to
+     * getProjectOwnerUserId + config.userId. Consumed by resolveOwnerGate in
+     * packages/server/src/lib/owner-identity.ts.
+     */
+    getOwnerIdentity?(): Promise<OwnerIdentity>;
+    /**
+     * task-2029 (C288): contributor cohort management on the project_contributors
+     * table (MVP slice — current schema, no roles/invites; that's MU-2/task-2070).
+     * Email resolution happens adapter-side (pg: user_profiles join; proxy: edge
+     * function) so the tool layer never touches identity tables directly. The
+     * OWNER-ONLY rule is enforced in the tool layer via resolveOwnerGate AND
+     * (proxy) server-side in the edge function — defence in depth, because the
+     * npm server runs on the user's machine. pg/proxy only; md leaves these
+     * unimplemented (no cohort concept in local single-user mode).
+     */
+    listContributors?(): Promise<ContributorEntry[]>;
+    addContributorByEmail?(email: string): Promise<ContributorEntry>;
+    removeContributorByEmail?(email: string): Promise<boolean>;
+    /**
+     * Optional (task-1888 / 1885-C): list all projects the authenticated user owns.
+     * Scopes to the auth user (proxy: bearer; pg: the bound project's user_id). Used by the
+     * project_list MCP tool so a user on one API key across many folders can see and select
+     * the right project from the LLM.
+     */
+    listUserProjects?(): Promise<ProjectSummary[]>;
+    /**
+     * Optional (task-1888 / 1885-C): create a project for the authenticated user, idempotent on
+     * papi_dir then name — re-running in the same workspace (or with the same name) returns the
+     * EXISTING project instead of creating a duplicate (fixes the SUP-2026-013 duplicate-project
+     * bug). NO auto-plan / NO seeded backlog — an empty project only. `papiDir` is omitted on the
+     * stateless remote transport (no real workspace there).
+     */
+    createUserProject?(input: {
+        name: string;
+        papiDir?: string;
+        repoUrl?: string;
+    }): Promise<ProjectLifecycleResult>;
+    /**
+     * Optional (task-1888 / 1885-C): resolve a project the user owns by id or slug and (when a
+     * workspace signal is available) stamp it as the papi_dir for the current folder. Callable from
+     * the LLM ("switch to golf"). Fails closed if the identifier does not resolve to a project the
+     * auth user owns.
+     */
+    switchUserProject?(identifier: string, papiDir?: string): Promise<ProjectLifecycleResult>;
+    /**
+     * Optional (task-2119): return a view of this adapter scoped to a DIFFERENT
+     * project for a single call, without rebinding the session adapter (unlike
+     * switchUserProject) and without persisting anything. Callers MUST validate
+     * the target project belongs to the auth user first (listUserProjects) —
+     * this method does not gate ownership itself.
+     */
+    withProject?(projectId: string): PapiAdapter;
+    /** Optional: insert a plan run record for telemetry. Non-blocking — callers should catch errors. */
+    insertPlanRun?(entry: PlanRunEntry): Promise<void>;
+    /** Submit a bug report with diagnostics for cross-project visibility. */
+    submitBugReport?(report: Omit<BugReport, 'id' | 'createdAt'>): Promise<BugReport>;
+    /**
+     * Optional (task-2061): the authenticated user's tier + metered tool-call
+     * count for the current month. Only the proxy adapter implements this —
+     * its identity is server-derived from the bearer. Local adapters (pg/md)
+     * deliberately omit it, so local sessions are never metered or blocked.
+     */
+    getMeteredUsage?(): Promise<{
+        tier: string;
+        monthlyToolCalls: number;
+    }>;
+}
+/** A project the auth user owns — returned by listUserProjects (task-1888 / 1885-C). */
+/**
+ * task-2052 (C288): both sides of the owner-gate identity. callerUserId is the
+ * authenticated caller (proxy: bearer-derived server-side; null when the
+ * transport cannot resolve a caller); ownerUserId is the project's owner row.
+ */
+interface OwnerIdentity {
+    callerUserId: string | null;
+    ownerUserId: string | null;
+}
+/**
+ * task-2029 (C288): one row of a project's contributor cohort
+ * (project_contributors joined to user_profiles for the human-readable bits).
+ */
+interface ContributorEntry {
+    userId: string;
+    email: string | null;
+    displayName: string | null;
+    role: string;
+    createdAt: string;
+}
+interface ProjectSummary {
+    id: string;
+    name: string;
+    slug: string;
+    papi_dir?: string | null;
+}
+/** Result of project_create / project_switch (task-1888 / 1885-C). */
+interface ProjectLifecycleResult {
+    projectId: string;
+    name: string;
+    slug: string;
+    papiDir?: string | null;
+    /** True when a new project row was created; false when an existing one was returned (idempotent). */
+    created: boolean;
+}
+/** Plan quality telemetry — one row per plan apply. */
+interface PlanRunEntry {
+    cycleNumber: number;
+    contextBytes?: number;
+    durationMs?: number;
+    taskCountIn?: number;
+    taskCountOut?: number;
+    backlogDepth?: number;
+    notes?: string;
+    /** Context utilisation ratio (0-1) and other token metrics captured at apply time. */
+    tokenUsage?: {
+        utilisation?: number;
+    };
+    /** Origin of this plan run: "mcp-server" (default) or "dashboard". */
+    source?: string;
 }
 /** Lean plan context returned by adapters that support SQL aggregation. */
 interface PlanContextSummary {
@@ -739,8 +1440,15 @@ declare class MdFileAdapter implements PapiAdapter {
     readPlanningLog(): Promise<PlanningLog>;
     /** Read the Cycle Health table from PLANNING_LOG.md. */
     getCycleHealth(): Promise<CycleHealth>;
-    /** Read all Active Decisions from ACTIVE_DECISIONS.md. */
-    getActiveDecisions(): Promise<ActiveDecision[]>;
+    /**
+     * Read Active Decisions from ACTIVE_DECISIONS.md.
+     *
+     * Default filters out retired ADs (outcome ∈ abandoned/superseded/resolved or superseded=true).
+     * Pass { includeRetired: true } for management/triage surfaces. See PapiAdapter docstring.
+     */
+    getActiveDecisions(options?: {
+        includeRetired?: boolean;
+    }): Promise<ActiveDecision[]>;
     /** Read cycle log entries (newest first), optionally limited to {@link limit} entries. */
     getCycleLog(limit?: number): Promise<CycleLogEntry[]>;
     getCycleLogSince(cycleNumber: number): Promise<CycleLogEntry[]>;
@@ -755,7 +1463,7 @@ declare class MdFileAdapter implements PapiAdapter {
     /** Get strategy reviews — md adapter returns empty (reviews live in cycle log). */
     getStrategyReviews(_limit?: number, _includeFullAnalysis?: boolean): Promise<StrategyReviewEntry[]>;
     /** Update or insert an Active Decision block by ID. */
-    updateActiveDecision(id: string, body: string, cycleNumber?: number): Promise<void>;
+    updateActiveDecision(id: string, body: string, cycleNumber?: number, _action?: string): Promise<void>;
     /** Query the cycle board, optionally filtering by status/priority/phase/etc. */
     queryBoard(options?: BoardQueryOptions): Promise<CycleTask[]>;
     /** Look up a single task by ID, returning null if not found. */
@@ -774,11 +1482,39 @@ declare class MdFileAdapter implements PapiAdapter {
     updateTask(id: string, updates: Partial<Omit<CycleTask, 'id'>>, options?: UpdateTaskOptions): Promise<void>;
     /** Shorthand to update only the status field of a task. */
     updateTaskStatus(id: string, status: TaskStatus): Promise<void>;
+    /**
+     * task-1763 (C293): atomic compare-and-swap task claim. First-claim-wins —
+     * sets assigneeId only if the task is currently unclaimed. The markdown adapter
+     * is single-process, so the read-check-write is trivially atomic here; the real
+     * concurrency guarantee lives in the pg adapter's RETURNING CAS. Returns the
+     * claimed task, or null if it was already claimed or does not exist.
+     *
+     * task-2071 (MU-3): the pooled-task invariant is `assigneeId == null && cycle
+     * == null` — a task already pulled into someone's cycle is NOT in the pool and
+     * cannot be claimed. Sets claimSource='pool' on success.
+     */
+    claimTask(taskId: string, assigneeId: string): Promise<CycleTask | null>;
+    /**
+     * task-2071 (C293, MU-3): claimer-only release. Clears assigneeId + claimSource
+     * only if the task is currently assigned to `assigneeId` and has not entered
+     * review. Returns the unclaimed task, or null if the caller is not the claimer,
+     * the task has progressed, or it does not exist.
+     */
+    unclaimTask(taskId: string, assigneeId: string): Promise<CycleTask | null>;
+    /**
+     * task-2072 (C293, MU-4): atomic review claim. Sets reviewerId only if the task
+     * is In Review and not yet claimed for review (reviewerId == null). First-claim-
+     * wins. Returns the claimed task, or null if already review-claimed / not In
+     * Review / missing.
+     */
+    claimReview(taskId: string, reviewerId: string): Promise<CycleTask | null>;
     recordTransition(_taskId: string, _fromStatus: string, _toStatus: string, _changedBy?: string): 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 the number of build reports for a specific task. */
+    getBuildReportCountForTask(taskId: string): Promise<number>;
     /** Return all build reports from cycles >= {@link cycleNumber}. */
     getBuildReportsSince(cycleNumber: number): Promise<BuildReport[]>;
     /** Return recent human reviews from REVIEWS.md (newest first), optionally limited to {@link count}. */
@@ -814,10 +1550,9 @@ declare class MdFileAdapter implements PapiAdapter {
     appendToolMetric(metric: ToolCallMetric): Promise<void>;
     /** Read all tool call metrics from METRICS.md. */
     readToolMetrics(): Promise<ToolCallMetric[]>;
+    hasToolMilestone(name: string): Promise<boolean>;
     /** Aggregate tool call metrics into a cost summary, optionally filtered by cycle. */
     getCostSummary(cycleNumber?: 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 cycle metrics snapshot to CYCLE_METRICS.md. */
@@ -841,6 +1576,13 @@ declare class MdFileAdapter implements PapiAdapter {
     getPendingRecommendations(): Promise<StrategyRecommendation[]>;
     /** Mark a recommendation as actioned. */
     actionRecommendation(id: string, cycleNumber: number): Promise<void>;
+    addAgendaTopic(input: {
+        topic: string;
+        source: string;
+        sourceCycle?: number;
+    }): Promise<AgendaTopic>;
+    getPendingAgendaTopics(): Promise<AgendaTopic[]>;
+    markAgendaTopicsAddressed(ids: string[], cycleNumber: number): Promise<void>;
     appendDecisionEvent(event: Omit<DecisionEvent, 'id' | 'createdAt'>): Promise<DecisionEvent>;
     getDecisionEvents(decisionId: string, limit?: number): Promise<DecisionEvent[]>;
     getDecisionEventsSince(cycle: number): Promise<DecisionEvent[]>;
@@ -851,6 +1593,13 @@ declare class MdFileAdapter implements PapiAdapter {
     private parseDecisionScores;
     logEntityReferences(_refs: Omit<EntityReference, 'id' | 'createdAt'>[]): Promise<void>;
     getDecisionUsage(_currentCycle: number): Promise<DecisionUsageSummary[]>;
+    getCurrentNorthStar(): Promise<string | null>;
+    getNorthStarSetCycle(): Promise<number | null>;
+    getNorthStarStaleness(): Promise<{
+        setCycle: number;
+        setAt: string;
+    } | null>;
+    upsertNorthStar(statement: string, _cycleNumber: number): Promise<void>;
 }
 
 /** Validate and normalise an effort string to EffortSize. Returns the value or undefined if invalid. */
@@ -862,7 +1611,7 @@ declare function parseEffortSize(value: string): EffortSize | undefined;
  */
 declare function parseBuildHandoff(markdown: string): BuildHandoff | null;
 /** Serialize a BuildHandoff object back into the standard markdown format. */
-declare function serializeBuildHandoff(handoff: BuildHandoff): string;
+declare function serializeBuildHandoff(raw: BuildHandoff | string): string;
 
 /** Calculate Tier 1 cycle metrics from build reports. */
 declare function calculateCycleMetrics(reports: BuildReport[], currentCycle: number, window?: number): {
@@ -963,6 +1712,9 @@ interface Project {
     name: string;
     repo_url?: string;
     papi_dir?: string;
+    user_id?: string;
+    root_commit_hash?: string;
+    resolution_method?: string;
     created_at: string;
     updated_at: string;
 }
@@ -1082,4 +1834,4 @@ interface ConflictAlert {
     resolved_at?: string;
 }
 
-export { type Acknowledgement, type AcknowledgementStatus, type ActiveDecision, type AutoReview, type AutoReviewFinding, type AutoReviewVerdict, type BoardQueryOptions, type BriefImplication, 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 ContextUtilisationSummary, type CostSnapshot, type CostSummary, type Cycle, type CycleEstimationAccuracy, type CycleHealth, type CycleLogEntry, type CycleMetricsSnapshot, type CycleStatus, type CycleTask, type CycleVelocity, type DecisionEvent, type DecisionEventSource, type DecisionEventType, type DecisionScore, type DecisionUsageSummary, type DiscoveryCanvas, type DogfoodEntry, type EffortSize, type EntityReference, type EstimationCalibrationRow, type Horizon, type HorizonStatus, 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 RecommendationEffectivenessRow, 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 Stage, type StageStatus, 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, calculateCycleMetrics, detectBuildPatterns, detectReviewPatterns, hasBuildPatterns, hasReviewPatterns, isValidStatus, isValidTransition, parseBuildHandoff, parseCycles, parseEffortSize, parsePhases, parseRegistries, parseReviews, parseToolMetrics, prependCycle, prependReview, serializeBuildHandoff, serializeCycle, serializeCycles, serializePhases, serializeRegistries, serializeReview, serializeToolMetric, validateTransition, writePhasesToContent };
+export { type Acknowledgement, type AcknowledgementStatus, type ActiveDecision, type AgendaTopic, type AgendaTopicStatus, type AutoReview, type AutoReviewFinding, type AutoReviewVerdict, type BoardQueryOptions, type BriefImplication, type BugReport, 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 ContextUtilisationSummary, type ContributorEntry, type CostSnapshot, type CostSummary, type Cycle, type CycleEstimationAccuracy, type CycleHealth, type CycleLearning, type CycleLearningPattern, type CycleLogEntry, type CycleMetricsSnapshot, type CycleStatus, type CycleTask, type CycleVelocity, type DecisionEvent, type DecisionEventSource, type DecisionEventType, type DecisionScore, type DecisionUsageSummary, type DiscoveryCanvas, type DocRegistryEntry, type DocSearchInput, type DocVisibility, type DogfoodEntry, type EffortSize, type EntityReference, type EstimationCalibrationRow, type HarnessInventoryEntry, type HarnessState, type Horizon, type HorizonStatus, type HumanReview, MdFileAdapter, type MetricDelta, type MilestoneDependency, type ModuleEstimationRow, type NorthStar, type OwnerActionInput, type OwnerActionRow, type OwnerIdentity, type PapiAdapter, type Phase, type PhaseStatus, type PlanContextSummary, type PlanRunEntry, type PlanWriteBackPayload, type PlanWriteBackResult, type PlanningLog, type Project, type ProjectContribution, type ProjectContributionStatus, type ProjectLifecycleResult, type ProjectSummary, type RecommendationEffectivenessRow, 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 SiblingRepoTask, type Stage, type StageStatus, 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, calculateCycleMetrics, detectBuildPatterns, detectReviewPatterns, hasBuildPatterns, hasReviewPatterns, isValidStatus, isValidTransition, parseBuildHandoff, parseCycles, parseEffortSize, parsePhases, parseRegistries, parseReviews, parseToolMetrics, prependCycle, prependReview, serializeBuildHandoff, serializeCycle, serializeCycles, serializePhases, serializeRegistries, serializeReview, serializeToolMetric, validateTransition, writePhasesToContent };