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

package/dist/index.d.ts

@@ -1,24 +1,7 @@
-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';
+import { TaskStatus as TaskStatus$1, TaskPriority as TaskPriority$1, EffortSize as EffortSize$1, TaskComplexity as TaskComplexity$1, TaskType as TaskType$1, ReviewStage as ReviewStage$1, ReviewVerdict as ReviewVerdict$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;
@@ -27,27 +10,71 @@ interface Phase {
     description: string;
     status: PhaseStatus;
     order: number;
+    /** The stage this phase belongs to (AD-14 hierarchy). */
+    stageId?: string;
 }
-/** 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. */
+/**
+ * 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;
+    slug: string;
+    label: string;
+    description?: string;
+    status: HorizonStatus;
+    sortOrder: number;
+    projectId: string;
+    createdAt: string;
+    updatedAt: string;
+}
+/** 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;
+    slug: string;
+    label: string;
+    description?: string;
+    status: StageStatus;
+    sortOrder: number;
+    horizonId: string;
+    projectId: string;
+    exitCriteria?: string[];
+    createdAt: string;
+    updatedAt: string;
+}
+/** Cycle lifecycle status (renamed from CycleStatus per AD-14). */
+type CycleStatus = 'planning' | 'active' | 'complete';
+/** Per-section SHA-256 hashes for context diff optimisation between cycles. */
 interface ContextHashes {
     productBrief?: string;
     activeDecisions?: string;
     reviews?: string;
     [key: string]: string | undefined;
 }
-interface Sprint {
+/** A cycle entity — the methodology loop (renamed from Cycle per AD-14). */
+interface Cycle {
     id: string;
     number: number;
-    status: SprintStatus;
+    status: CycleStatus;
     startDate: string;
     endDate?: string;
     goals: string[];
     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;
@@ -63,7 +90,7 @@ 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 1 (Cycle-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
  */
@@ -78,22 +105,41 @@ 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;
     decisionId: string;
     eventType: DecisionEventType;
-    sprint: number;
+    cycle: number;
     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. */
 interface DecisionScore {
     id: string;
     decisionId: string;
-    sprint: number;
+    cycle: number;
     effort: number;
     risk: number;
     reversibility: number;
@@ -103,15 +149,17 @@ interface DecisionScore {
     rationale?: string;
     createdAt: string;
 }
-/** Sprint health metadata from PLANNING_LOG.md header. */
-interface SprintHealth {
-    totalSprints: number;
-    latestSprintStatus?: string;
-    sprintsSinceLastStrategyReview: number;
+/** Cycle health metadata from PLANNING_LOG.md header. */
+interface CycleHealth {
+    totalCycles: number;
+    latestCycleStatus?: string;
+    cyclesSinceLastStrategyReview: number;
     strategyReviewDue: string;
     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 {
@@ -122,46 +170,128 @@ interface ActiveDecision {
     confidence: Confidence;
     superseded: boolean;
     supersededBy?: string;
-    createdSprint?: number;
-    modifiedSprint?: number;
+    createdCycle?: number;
+    modifiedCycle?: number;
     body: string;
+    outcome?: 'pending' | 'confirmed' | 'validated' | 'revised' | 'resolved' | 'abandoned' | 'superseded';
+    revisionCount?: number;
 }
-/** A single sprint entry in the planning log. */
-interface SprintLogEntry {
+/** A single cycle entry in the planning log. */
+interface CycleLogEntry {
     uuid: string;
-    sprintNumber: number;
+    cycleNumber: number;
     title: string;
     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 {
-    sprintNumber: number;
-    sprintRange?: string;
+    cycleNumber: number;
+    cycleRange?: string;
     title: string;
     content: string;
     notes?: string;
     boardHealth?: string;
     strategicDirection?: string;
     recommendations?: unknown;
+    fullAnalysis?: string;
+    velocityAssessment?: string;
+    /** 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 {
+    id?: string;
+    projectId?: string;
+    cycleNumber: number;
+    category: 'friction' | 'methodology' | 'signal' | 'commercial';
+    content: string;
+    sourceTool?: string;
+    sourceRef?: string;
+    status?: 'observed' | 'backlog-created' | 'resolved' | 'actioned' | 'dismissed';
+    linkedTaskId?: string;
     createdAt?: string;
 }
 /** Full parsed contents of PLANNING_LOG.md. */
 interface PlanningLog {
-    sprintHealth: SprintHealth;
+    cycleHealth: CycleHealth;
     northStar: string;
     activeDecisions: ActiveDecision[];
     deferred: string[];
-    sprintLog: SprintLogEntry[];
+    cycleLog: CycleLogEntry[];
 }
 /** 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 {
+/** 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;
     displayId: string;
@@ -170,12 +300,15 @@ interface SprintTask {
     priority: TaskPriority;
     complexity: TaskComplexity;
     module: string;
-    epic: string;
+    /** @deprecated (AD-14): Use phase + stageId instead. Will be removed after taxonomy migration. */
+    epic?: string;
     phase: string;
+    /** Stage FK for AD-14 hierarchy (Horizon → Stage → Phase → Task). */
+    stageId?: string;
     owner: string;
     reviewed: boolean;
-    sprint?: number;
-    createdSprint?: number;
+    cycle?: number;
+    createdCycle?: number;
     createdAt?: string;
     why?: string;
     dependsOn?: string;
@@ -186,6 +319,63 @@ interface SprintTask {
     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 {
+    scopeMatch: boolean;
+    filesMatch: 'exact' | 'partial' | 'missed';
+    effortMatch: boolean;
+    notes?: string;
+}
+/** Brief implications from a build — discovery learnings that feed back into planning. */
+interface BriefImplication {
+    canvasSection: 'landscape' | 'journeys' | 'mvpBoundary' | 'assumptions' | 'successSignals';
+    type: 'confirm' | 'contradict' | 'new';
+    detail: string;
 }
 /** A build report entry from BUILD_REPORTS.md. */
 interface BuildReport {
@@ -195,7 +385,7 @@ interface BuildReport {
     taskId: string;
     taskName: string;
     date: string;
-    sprint: number;
+    cycle: number;
     completed: 'Yes' | 'No' | 'Partial';
     actualEffort: EffortSize;
     estimatedEffort: EffortSize;
@@ -205,7 +395,139 @@ 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 {
+    type: string;
+    total: number;
+    actioned: number;
+    dismissed: number;
+    pending: number;
+    acceptanceRate: string;
+    avgCyclesToAction: string | null;
+}
+/** Aggregated estimation calibration row from v_estimation_accuracy. */
+interface EstimationCalibrationRow {
+    estimatedEffort: string;
+    actualEffort: string;
+    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 {
@@ -216,12 +538,21 @@ interface ToolCallMetric {
     outputTokens?: number;
     estimatedCostUsd?: number;
     model?: string;
-    /** Sprint number when this metric was recorded. Absent on legacy rows. */
-    sprintNumber?: number;
+    /** Cycle number when this metric was recorded. Absent on legacy rows. */
+    cycleNumber?: 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;
+    /** 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 {
@@ -241,8 +572,32 @@ interface CostSummary {
     avgCostPerCall: number;
 }
 /** A cost snapshot persisted in the Cost Summary section of METRICS.md. */
+/** Discovery canvas — progressive discovery sections on product brief. */
+interface DiscoveryCanvas {
+    landscapeReferences?: {
+        name: string;
+        url?: string;
+        notes?: string;
+    }[];
+    userJourneys?: {
+        persona: string;
+        journey: string;
+        priority?: string;
+    }[];
+    mvpBoundary?: string;
+    assumptionsOpenQuestions?: {
+        text: string;
+        status: string;
+        evidence?: string;
+    }[];
+    successSignals?: {
+        signal: string;
+        metric?: string;
+        target?: string;
+    }[];
+}
 interface CostSnapshot {
-    sprint: number;
+    cycle: number;
     date: string;
     totalCostUsd: number;
     totalInputTokens: number;
@@ -268,7 +623,7 @@ type TextClusterer = (entries: ClusterEntry[]) => Promise<ClusterResult[]>;
 interface RecurringSurprise {
     text: string;
     count: number;
-    sprints: number[];
+    cycles: number[];
 }
 /** Build pattern detection results from analyzing recent build reports. */
 interface BuildPatterns {
@@ -278,28 +633,28 @@ interface BuildPatterns {
     scopeAccuracyBreakdown: Record<string, number>;
     untriagedIssues: string[];
 }
-/** Per-sprint estimation accuracy stats. */
-interface SprintEstimationAccuracy {
-    sprint: number;
+/** Per-cycle estimation accuracy stats. */
+interface CycleEstimationAccuracy {
+    cycle: number;
     reports: number;
     matchRate: number;
     mae: number;
     bias: number;
 }
-/** Per-sprint velocity stats. */
-interface SprintVelocity {
-    sprint: number;
+/** Per-cycle velocity stats. */
+interface CycleVelocity {
+    cycle: number;
     completed: number;
     partial: number;
     failed: number;
     effortPoints: number;
 }
-/** A sprint methodology metrics snapshot stored in SPRINT_METRICS.md. */
-interface SprintMetricsSnapshot {
-    sprint: number;
+/** A cycle methodology metrics snapshot stored in CYCLE_METRICS.md. */
+interface CycleMetricsSnapshot {
+    cycle: number;
     date: string;
-    accuracy: SprintEstimationAccuracy[];
-    velocity: SprintVelocity[];
+    accuracy: CycleEstimationAccuracy[];
+    velocity: CycleVelocity[];
 }
 /** A recurring feedback theme detected across human reviews. */
 interface RecurringFeedback {
@@ -313,6 +668,21 @@ interface ReviewPatterns {
     verdictBreakdown: Record<string, number>;
     requestChangesRate: number;
 }
+/** Auto-review verdict from automated code review. */
+type AutoReviewVerdict = 'pass' | 'warn' | 'fail';
+/** A single finding from an automated code review. */
+interface AutoReviewFinding {
+    severity: 'error' | 'warning' | 'info';
+    file?: string;
+    line?: number;
+    message: string;
+}
+/** Automated code review results — supplements human review. */
+interface AutoReview {
+    verdict: AutoReviewVerdict;
+    findings: AutoReviewFinding[];
+    summary: string;
+}
 /** A human review entry stored in REVIEWS.md. */
 interface HumanReview {
     uuid: string;
@@ -321,11 +691,13 @@ interface HumanReview {
     stage: ReviewStage;
     reviewer: string;
     verdict: ReviewVerdict;
-    sprint: number;
+    cycle: number;
     date: string;
     comments: string;
     handoffRevision?: number;
     buildCommitSha?: string;
+    /** Optional automated code review results attached to this review. */
+    autoReview?: AutoReview;
 }
 /** A structured BUILD HANDOFF parsed from the markdown handoff block. */
 interface BuildHandoff {
@@ -334,7 +706,7 @@ interface BuildHandoff {
     createdAt?: string;
     taskId: string;
     taskTitle: string;
-    sprint: number;
+    cycle: number;
     whyNow: string;
     scope: string[];
     scopeBoundary: string[];
@@ -342,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. */
@@ -358,8 +745,25 @@ interface StrategyRecommendation {
     type: RecommendationType;
     status: RecommendationStatus;
     content: string;
-    createdSprint: number;
-    actionedSprint?: number;
+    createdCycle: number;
+    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 {
@@ -368,22 +772,30 @@ interface EntityReference {
     entityId: string;
     referenceContext: 'plan_input' | 'plan_output' | 'strategy_input' | 'strategy_output';
     toolName: string;
-    sprintNumber: number;
+    cycleNumber: number;
     createdAt: string;
 }
+/** Per-tool context utilisation summary from v_context_utilisation. */
+interface ContextUtilisationSummary {
+    tool: string;
+    cycleNumber: number;
+    callCount: number;
+    avgUtilisation: number;
+    avgContextBytes: number;
+}
 /** Per-AD usage summary returned by getDecisionUsage. */
 interface DecisionUsageSummary {
     decisionId: string;
     referenceCount: number;
-    lastReferencedSprint: number;
-    sprintsSinceLastReference: number;
+    lastReferencedCycle: number;
+    cyclesSinceLastReference: 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. */
+/** Filter options for querying the cycle board. */
 interface BoardQueryOptions {
     status?: TaskStatus[];
     priority?: TaskPriority[];
@@ -391,31 +803,183 @@ interface BoardQueryOptions {
     reviewed?: boolean;
     module?: string;
     epic?: string;
-    /** Filter by context tier (1=sprint-eligible, 2=plannable, 3=pre-triage). */
+    /** Filter by context tier (1=cycle-eligible, 2=plannable, 3=pre-triage). */
     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>;
-    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>;
+    getCycleHealth(): Promise<CycleHealth>;
+    /**
+     * 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, 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[]>;
-    getBuildReportsSince(sprintNumber: number): Promise<BuildReport[]>;
+    getBuildReportCountForTask(taskId: string): Promise<number>;
+    getBuildReportsSince(cycleNumber: number): Promise<BuildReport[]>;
     getRecentReviews(count?: number): Promise<HumanReview[]>;
     writeReview(review: HumanReview): Promise<void>;
-    compressSprintLog(threshold: number, summary: string): Promise<void>;
+    compressCycleLog(threshold: number, summary: string): Promise<void>;
     compressBuildReports(threshold: number, summary: string): Promise<void>;
     archiveTasks(phases: string[], statuses?: string[]): Promise<{
         archivedCount: number;
@@ -423,38 +987,210 @@ interface PapiAdapter {
     }>;
     readProductBrief(): Promise<string>;
     updateProductBrief(content: string): Promise<void>;
+    /** Read discovery canvas sections from product brief. */
+    readDiscoveryCanvas(): Promise<DiscoveryCanvas>;
+    /** Update discovery canvas sections on product brief. */
+    updateDiscoveryCanvas(canvas: Partial<DiscoveryCanvas>): 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>;
+    /** Read all horizons for the project (AD-14 hierarchy). */
+    readHorizons?(): Promise<Horizon[]>;
+    /** Read all stages for the project, optionally filtered by horizon (AD-14 hierarchy). */
+    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. */
+    createHorizon?(horizon: {
+        slug: string;
+        label: string;
+        description?: string;
+        status: HorizonStatus;
+        sortOrder: number;
+    }): Promise<string>;
+    /** Create a new stage (AD-14 hierarchy). Returns the created stage's ID. */
+    createStage?(stage: {
+        slug: string;
+        label: string;
+        description?: string;
+        status: StageStatus;
+        sortOrder: number;
+        horizonId: string;
+    }): Promise<string>;
+    /** Link phases to a stage by setting their stage_id. */
+    linkPhasesToStage?(stageId: string): Promise<void>;
     appendToolMetric(metric: ToolCallMetric): Promise<void>;
     readToolMetrics(): Promise<ToolCallMetric[]>;
-    getCostSummary(sprintNumber?: number): Promise<CostSummary>;
-    writeCostSnapshot(snapshot: CostSnapshot): Promise<void>;
+    /** 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>;
     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>;
+    appendCycleMetrics(snapshot: CycleMetricsSnapshot): Promise<void>;
+    readCycleMetrics(): Promise<CycleMetricsSnapshot[]>;
+    readCycles(): Promise<Cycle[]>;
+    createCycle(cycle: Cycle): Promise<void>;
+    getContextHashes?(cycleNumber: 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>;
+    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(sprint: number): Promise<DecisionEvent[]>;
+    getDecisionEventsSince(cycle: 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[]>;
+    getDecisionUsage(currentCycle: number): Promise<DecisionUsageSummary[]>;
+    /** Get context utilisation summary from v_context_utilisation view. Optional — pg adapter only. */
+    getContextUtilisation?(): Promise<ContextUtilisationSummary[]>;
     writeStrategyReview(review: StrategyReviewEntry): Promise<void>;
-    getLastStrategyReviewSprint(): Promise<number>;
-    getStrategyReviews(limit?: number): Promise<StrategyReviewEntry[]>;
+    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
+     * on the North Star embedded in PLANNING_LOG.md (which may be stale).
+     */
+    getCurrentNorthStar?(): Promise<string | null>;
+    /**
+     * Optional: return the cycle number when the current North Star was set.
+     * Used for drift detection — flags when North Star hasn't been validated in 10+ cycles.
+     */
+    getNorthStarSetCycle?(): Promise<number | null>;
+    /**
+     * Optional: return both cycle number and set_at date for the current North Star.
+     * Used for hybrid drift detection — warns only when both cycle gap AND time gap exceed thresholds.
+     */
+    getNorthStarStaleness?(): Promise<{
+        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.
@@ -465,6 +1201,11 @@ interface PapiAdapter {
         content: string;
         createdAt: string;
     }[]>;
+    /**
+     * Optional: return recommendation effectiveness data from v_recommendation_effectiveness.
+     * Used by strategy review to assess whether past recommendations were followed.
+     */
+    getRecommendationEffectiveness?(): Promise<RecommendationEffectivenessRow[]>;
     /**
      * Optional: return a lean pre-formatted plan context summary.
      * When implemented (e.g. by pg adapter with SQL aggregates), assembleContext
@@ -472,6 +1213,163 @@ interface PapiAdapter {
      * Return undefined to fall back to the default assembly path.
      */
     getPlanContextSummary?(): Promise<PlanContextSummary | undefined>;
+    /**
+     * Optional: check if the project exists in the data store.
+     * Returns true if the project is found, false otherwise.
+     * 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 {
@@ -479,25 +1377,25 @@ interface PlanContextSummary {
     board: string;
     /** Pre-computed build intelligence: accuracy %, velocity trend, top surprises. */
     buildIntelligence: string;
-    /** Last 3 sprint entries with carry-forward. */
-    sprintLog: string;
+    /** Last 3 cycle entries with carry-forward. */
+    cycleLog: 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;
+    /** The NEW cycle number (current + 1). */
+    cycleNumber: number;
+    /** Cycle log entry to upsert. */
+    cycleLog: CycleLogEntry;
     /** Health updates: boardHealth, strategicDirection, etc. */
-    healthUpdates: Partial<SprintHealth>;
+    healthUpdates: Partial<CycleHealth>;
     /** New tasks to create (already deduplicated by plan service). */
-    newTasks: Array<Omit<SprintTask, 'id' | 'uuid' | 'displayId'>>;
+    newTasks: Array<Omit<CycleTask, 'id' | 'uuid' | 'displayId'>>;
     /** Board corrections: taskId + partial updates. */
     boardCorrections: Array<{
         taskId: string;
-        updates: Partial<Omit<SprintTask, 'id'>>;
+        updates: Partial<Omit<CycleTask, 'id'>>;
     }>;
     /** Phases parsed from product brief update. Empty array = no phase changes. */
     phases: Phase[];
@@ -513,10 +1411,8 @@ interface PlanWriteBackPayload {
         taskId: string;
         handoff: BuildHandoff;
     }>;
-    /** Sprint entity to create. */
-    sprint: Sprint;
-    /** Whether to run feature sync from phases. */
-    featureSync: boolean;
+    /** Cycle entity to create. */
+    cycle: Cycle;
     /** IDs of tasks whose reviewed status should be checked before allowing priority changes. */
     reviewedTaskIds: string[];
 }
@@ -540,33 +1436,40 @@ declare class MdFileAdapter implements PapiAdapter {
     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). */
+    /** Parse the full planning context into structured sections (reads from PLANNING_LOG.md + ACTIVE_DECISIONS.md + CYCLE_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. */
+    /** Read the Cycle Health table from PLANNING_LOG.md. */
+    getCycleHealth(): Promise<CycleHealth>;
+    /**
+     * 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[]>;
+    /** Merge partial updates into the Cycle Health table and write back. */
+    setCycleHealth(updates: Partial<CycleHealth>): Promise<void>;
+    /** Prepend a new cycle log entry at the top of the Cycle Log section. */
+    writeCycleLogEntry(entry: CycleLogEntry): Promise<void>;
+    /** Write a strategy review — for md adapter, delegates to cycle 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[]>;
+    /** Get the cycle number of the last strategy review. */
+    getLastStrategyReviewCycle(): Promise<number>;
+    /** 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, sprintNumber?: number): Promise<void>;
-    /** Query the sprint board, optionally filtering by status/priority/phase/etc. */
-    queryBoard(options?: BoardQueryOptions): Promise<SprintTask[]>;
+    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. */
-    getTask(id: string): Promise<SprintTask | null>;
+    getTask(id: string): Promise<CycleTask | null>;
     /** Look up multiple tasks by ID in a single board read. */
-    getTasks(ids: string[]): Promise<SprintTask[]>;
+    getTasks(ids: string[]): Promise<CycleTask[]>;
     /** 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. */
@@ -574,32 +1477,61 @@ declare class MdFileAdapter implements PapiAdapter {
     /** 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>;
+    createTask(task: Omit<CycleTask, 'id'>): Promise<CycleTask>;
     /** 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>;
+    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 all build reports from sprints >= {@link sprintNumber}. */
-    getBuildReportsSince(sprintNumber: 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}. */
     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 cycle log entries below {@link threshold} into a summary block. */
+    compressCycleLog(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. */
+    /** Append tasks to ARCHIVE_CYCLE_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. */
+    /** Archive tasks matching phases and/or statuses to ARCHIVE_CYCLE_BOARD.md and remove them from active board. */
     archiveTasks(phases: string[], statuses?: string[]): Promise<{
         archivedCount: number;
         taskIds: string[];
@@ -608,38 +1540,29 @@ declare class MdFileAdapter implements PapiAdapter {
     readProductBrief(): Promise<string>;
     /** Overwrite PRODUCT_BRIEF.md with new content. */
     updateProductBrief(content: string): Promise<void>;
+    readDiscoveryCanvas(): Promise<DiscoveryCanvas>;
+    updateDiscoveryCanvas(_canvas: Partial<DiscoveryCanvas>): 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>;
+    hasToolMilestone(name: string): Promise<boolean>;
+    /** Aggregate tool call metrics into a cost summary, optionally filtered by cycle. */
+    getCostSummary(cycleNumber?: number): Promise<CostSummary>;
     /** 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>;
+    /** Append a cycle metrics snapshot to CYCLE_METRICS.md. */
+    appendCycleMetrics(snapshot: CycleMetricsSnapshot): Promise<void>;
+    /** Read all cycle metrics snapshots from CYCLE_METRICS.md. */
+    readCycleMetrics(): Promise<CycleMetricsSnapshot[]>;
+    /** Read all Cycle entities from CYCLES.md (newest first). */
+    readCycles(): Promise<Cycle[]>;
+    /** Write a new Cycle entity to CYCLES.md. */
+    createCycle(cycle: Cycle): Promise<void>;
     /** Read module and epic registries from REGISTRIES.md. */
     readRegistries(): Promise<Registries>;
     /** Overwrite REGISTRIES.md with updated registries. */
@@ -652,17 +1575,31 @@ declare class MdFileAdapter implements PapiAdapter {
     /** Read all pending (unactioned) strategy recommendations. */
     getPendingRecommendations(): Promise<StrategyRecommendation[]>;
     /** Mark a recommendation as actioned. */
-    actionRecommendation(id: string, sprintNumber: number): Promise<void>;
+    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(sprint: number): Promise<DecisionEvent[]>;
+    getDecisionEventsSince(cycle: 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[]>;
+    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. */
@@ -674,12 +1611,12 @@ 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 sprint metrics from build reports. */
-declare function calculateSprintMetrics(reports: BuildReport[], currentSprint: number, window?: number): {
-    accuracy: SprintEstimationAccuracy[];
-    velocity: SprintVelocity[];
+/** Calculate Tier 1 cycle metrics from build reports. */
+declare function calculateCycleMetrics(reports: BuildReport[], currentCycle: number, window?: number): {
+    accuracy: CycleEstimationAccuracy[];
+    velocity: CycleVelocity[];
 };
 /**
  * Detect recurring patterns across build reports.
@@ -687,7 +1624,7 @@ declare function calculateSprintMetrics(reports: BuildReport[], currentSprint: n
  * 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>;
+declare function detectBuildPatterns(reports: BuildReport[], currentCycle: number, window?: number, clusterer?: TextClusterer): Promise<BuildPatterns>;
 /** Returns true if the patterns contain any actionable findings. */
 declare function hasBuildPatterns(patterns: BuildPatterns): boolean;
 
@@ -704,7 +1641,7 @@ declare function prependReview(review: HumanReview, content: string): string;
  * 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>;
+declare function detectReviewPatterns(reviews: HumanReview[], currentCycle: number, window?: number, clusterer?: TextClusterer): Promise<ReviewPatterns>;
 /** Returns true if the patterns contain any actionable findings. */
 declare function hasReviewPatterns(patterns: ReviewPatterns): boolean;
 
@@ -714,8 +1651,8 @@ declare function parseToolMetrics(content: string): ToolCallMetric[];
 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;
+/** Aggregate tool call metrics into a cost summary, optionally filtered by cycle. */
+declare function aggregateCostSummary(metrics: ToolCallMetric[], cycleNumber?: number): CostSummary;
 
 /** Parse the PHASES YAML section from PRODUCT_BRIEF.md content. */
 declare function parsePhases(content: string): Phase[];
@@ -724,21 +1661,14 @@ 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 CYCLES.md content into an array of Cycle objects (newest first). */
+declare function parseCycles(content: string): Cycle[];
+/** Serialize cycles to a complete CYCLES.md file content. */
+declare function serializeCycles(cycles: Cycle[], content: string): string;
+/** Serialize a single Cycle to a YAML string (for display/export). */
+declare function serializeCycle(cycle: Cycle): string;
+/** Add a new cycle to CYCLES.md (prepended to the array so newest is first). */
+declare function prependCycle(cycle: Cycle, content: string): string;
 
 /** Parse REGISTRIES.md content into a Registries object. */
 declare function parseRegistries(content: string): Registries;
@@ -782,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;
 }
@@ -901,4 +1834,4 @@ interface ConflictAlert {
     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 };
+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 };