@ebrindley/build 0.0.0-stage → 1.42.1-rc28

package/integrations/bb-plugin-build/src/planning-service.ts

@@ -0,0 +1,647 @@
+/**
+ * Service adapter between Build's canonical planning projections and the
+ * read-only planning workspace panel.
+ *
+ * Build remains the planning authority. This module only re-shapes projection
+ * data the caller already read: it never writes or mutates planning state, never
+ * starts a poller, daemon, heartbeat, or timer, keeps no cache and no mirrored
+ * store, and holds no state between calls. Every read goes through the injected
+ * source on each invocation, exactly like the backlog reads in `adapter.ts`, so
+ * the existing request/refresh lifecycle stays the only cadence.
+ *
+ * Blockers, dependency satisfaction, ownership, next candidates, and sync
+ * evidence are taken as Build reported them. Where the panel's fixed
+ * presentation vocabulary cannot express a canonical value, the canonical value
+ * is disclosed verbatim as a structured note rather than being reinterpreted.
+ * Missing, unavailable, and observed states stay distinct, and sync health
+ * remains advisory.
+ *
+ * The input types below mirror Build's `src/planning` projection shapes
+ * structurally. This plugin is a separate package that does not import Build
+ * internals; `tests/unit/integrations/bb-planning-service.test.ts` pins the
+ * mirror by passing real projection values through these types.
+ */
+
+import type {
+  PlanningBlockerRecord,
+  PlanningDependencyRecord,
+  PlanningNextCandidateView,
+  PlanningSprintSummary,
+  PlanningSyncState,
+  PlanningTaskStatus,
+  PlanningTaskView,
+  PlanningWorkOwnership,
+  PlanningWorkspaceData,
+} from './planning-workspace.js';
+
+/** Mirror of Build's `ProjectionValue<T>`: missing is distinct from unavailable. */
+export type CanonicalProjectionValue<T> =
+  | { state: 'available'; value: T }
+  | { state: 'missing' }
+  | { state: 'unavailable'; reason: string };
+
+/** Mirror of Build's managed task status vocabulary. */
+export type CanonicalTaskStatus =
+  | 'todo'
+  | 'in_progress'
+  | 'review'
+  | 'done'
+  | 'blocked'
+  | 'cancelled';
+
+export interface CanonicalDependencyProjection {
+  id: string;
+  state: 'available' | 'recorded-complete' | 'missing';
+  status: CanonicalTaskStatus | null;
+  satisfied: boolean;
+}
+
+export interface CanonicalBlockerProjection {
+  kind: 'task-status' | 'dependency';
+  id: string;
+  reason: string | null;
+}
+
+/** Mirror of Build's `CanonicalWorkOwnership`. */
+export type CanonicalWorkOwnership = PlanningWorkOwnership;
+
+export interface CanonicalTaskProjection {
+  id: string;
+  state: 'available' | 'missing';
+  title: string | null;
+  status: CanonicalTaskStatus | null;
+  assignee: string | null;
+  /** Canonical owner; null when unassigned, a missing placeholder, or an older envelope. */
+  ownership: CanonicalWorkOwnership | null;
+  /** Canonical priority when published; null for missing placeholders or older envelopes. */
+  priority: string | null;
+  /** Lifecycle timestamps copied from Build; null when absent or task is missing. */
+  created: string | null;
+  updated: string | null;
+  started: string | null;
+  completed: string | null;
+  archived: string | null;
+  cancelled: string | null;
+  /** Active/archive bucket location; null for missing placeholders. */
+  location: 'active' | 'archive' | null;
+  estimates: { hours: number | null; runtimeMinutes: number | null };
+  dependencies: readonly CanonicalDependencyProjection[];
+  blockers: readonly CanonicalBlockerProjection[];
+  linkedBacklogItemId: string | null;
+}
+
+export interface CanonicalSprintProjection {
+  id: string;
+  name: string;
+  status: string;
+  goal: string | null;
+  startDate: string;
+  endDate: string;
+}
+
+export interface CanonicalNextCandidateProjection {
+  id: string;
+  kind: 'backlog' | 'task' | 'finding' | 'issue' | 'debt' | 'parking';
+  title: string;
+  status: string;
+  priority: string | null;
+  whyIncluded: string;
+}
+
+export interface CanonicalPlanningProjectionInput {
+  activeSprint: CanonicalProjectionValue<CanonicalSprintProjection>;
+  tasks: CanonicalProjectionValue<readonly CanonicalTaskProjection[]>;
+  nextCandidates: CanonicalProjectionValue<readonly CanonicalNextCandidateProjection[]>;
+}
+
+/** Mirror of Build's `VisibilityEvidence<T>`. */
+export type TeamVisibilityEvidence<T> =
+  | { status: 'available'; value: T }
+  | { status: 'unavailable'; reason: string };
+
+export interface TeamVisibilityWorkBlocker {
+  kind: 'task-status' | 'dependency' | 'provenance';
+  id: string;
+  reason: string | null;
+}
+
+export interface TeamVisibilityWorkRun {
+  status: string;
+  workflowId: string | null;
+  executingPid: number | null;
+  lastCompletedStep: string | null;
+}
+
+export interface TeamVisibilityWorkItem {
+  id: string;
+  title: string;
+  status: 'in_progress';
+  assignee: TeamVisibilityEvidence<string>;
+  /** Additive: older team-visibility envelopes omit canonical ownership. */
+  ownership?: TeamVisibilityEvidence<CanonicalWorkOwnership>;
+  /** Additive: older envelopes omit blockers and run/worktree/commit/PR evidence. */
+  blockers?: TeamVisibilityEvidence<readonly TeamVisibilityWorkBlocker[]>;
+  run?: TeamVisibilityEvidence<TeamVisibilityWorkRun>;
+  branch: TeamVisibilityEvidence<string>;
+  worktree?: TeamVisibilityEvidence<string>;
+  commit?: TeamVisibilityEvidence<string>;
+  pr?: TeamVisibilityEvidence<number>;
+  updatedAt: string;
+  updateAgeMs: TeamVisibilityEvidence<number>;
+}
+
+export interface TeamVisibilitySyncFailure {
+  message: string;
+  observedAt?: string;
+}
+
+export interface TeamVisibilitySyncHealth {
+  advisory: true;
+  deferSyncActive: boolean;
+  unpushedPlanningCommits: TeamVisibilityEvidence<number>;
+  lastSyncFailure: TeamVisibilityEvidence<TeamVisibilitySyncFailure>;
+}
+
+export interface TeamVisibilityProjectionInput {
+  observedAt: string;
+  work: readonly TeamVisibilityWorkItem[];
+  syncHealth: TeamVisibilitySyncHealth;
+}
+
+/**
+ * Evidence as this adapter passes it on: available or unavailable-with-reason.
+ * An unavailable value never renders as a healthy one.
+ */
+export type PlanningEvidence<T> =
+  | { state: 'available'; value: T }
+  | { state: 'unavailable'; reason: string };
+
+/**
+ * One disclosure the panel's fixed presentation shape cannot carry on its own.
+ * Notes never change a rendered value; they explain it.
+ */
+export interface PlanningWorkspaceNote {
+  scope: 'sprint' | 'tasks' | 'task' | 'next-candidates' | 'active-work' | 'sync-health';
+  kind: 'missing' | 'unavailable' | 'unmapped-status' | 'blocked' | 'sync-failure';
+  /** Canonical id the note is about, or null for a whole surface. */
+  id: string | null;
+  detail: string;
+}
+
+/** In-progress work exactly as Build's team-visibility projection reported it. */
+export interface PlanningActiveWorkView {
+  id: string;
+  title: string;
+  assignee: PlanningEvidence<string>;
+  /** Additive: omitted when the team-visibility envelope had no ownership evidence. */
+  ownership?: PlanningEvidence<CanonicalWorkOwnership>;
+  blockers?: PlanningEvidence<readonly TeamVisibilityWorkBlocker[]>;
+  run?: PlanningEvidence<TeamVisibilityWorkRun>;
+  branch: PlanningEvidence<string>;
+  worktree?: PlanningEvidence<string>;
+  commit?: PlanningEvidence<string>;
+  pr?: PlanningEvidence<number>;
+  updatedAt: string;
+  updateAgeMs: PlanningEvidence<number>;
+}
+
+export interface PlanningWorkspaceProjection {
+  /** The panel's rendered input. */
+  data: PlanningWorkspaceData;
+  activeWork: PlanningEvidence<readonly PlanningActiveWorkView[]>;
+  /** When the team-visibility evidence was observed, or null when unavailable. */
+  observedAt: string | null;
+  notes: readonly PlanningWorkspaceNote[];
+}
+
+/**
+ * Read-only sources for one refresh. Both are read fresh on every call; this
+ * adapter adds no caching, batching, or scheduling of its own.
+ */
+export interface PlanningWorkspaceSource {
+  readCanonicalPlanning(): Promise<CanonicalPlanningProjectionInput>;
+  readTeamVisibility(): Promise<TeamVisibilityProjectionInput>;
+}
+
+/**
+ * Preserve every canonical status in a distinct queue. `unknown` is reserved
+ * for missing tasks or a canonical task whose status is absent.
+ */
+export const PRESENTED_TASK_STATUS: Readonly<Record<CanonicalTaskStatus, PlanningTaskStatus>> = {
+  todo: 'todo',
+  in_progress: 'in-progress',
+  review: 'review',
+  done: 'done',
+  blocked: 'blocked',
+  cancelled: 'cancelled',
+};
+
+function reasonFrom(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+function evidenceFrom<T>(evidence: TeamVisibilityEvidence<T>): PlanningEvidence<T> {
+  return evidence.status === 'available'
+    ? { state: 'available', value: evidence.value }
+    : { state: 'unavailable', reason: evidence.reason };
+}
+
+function mapSprint(
+  activeSprint: CanonicalPlanningProjectionInput['activeSprint'],
+  notes: PlanningWorkspaceNote[]
+): PlanningSprintSummary | null {
+  if (activeSprint.state === 'unavailable') {
+    notes.push({
+      scope: 'sprint',
+      kind: 'unavailable',
+      id: null,
+      detail: activeSprint.reason,
+    });
+    return null;
+  }
+  if (activeSprint.state === 'missing') {
+    notes.push({
+      scope: 'sprint',
+      kind: 'missing',
+      id: null,
+      detail: 'Build reports no active sprint.',
+    });
+    return null;
+  }
+  const sprint = activeSprint.value;
+  return {
+    id: sprint.id,
+    title: sprint.name,
+    status: sprint.status,
+    startedAt: sprint.startDate,
+    targetDate: sprint.endDate,
+  };
+}
+
+/**
+ * Copy structured dependencies as Build classified them. Satisfaction is never
+ * re-derived here; available, recorded-complete, missing, and the satisfied flag
+ * all pass through.
+ */
+function mapDependencies(
+  dependencies: readonly CanonicalDependencyProjection[]
+): PlanningDependencyRecord[] {
+  return dependencies.map((dependency) => ({
+    id: dependency.id,
+    state: dependency.state,
+    status: dependency.status,
+    satisfied: dependency.satisfied,
+  }));
+}
+
+function mapBlockers(blockers: readonly CanonicalBlockerProjection[]): PlanningBlockerRecord[] {
+  return blockers.map((blocker) => ({
+    kind: blocker.kind,
+    id: blocker.id,
+    reason: blocker.reason,
+  }));
+}
+
+/**
+ * Unsatisfied dependency ids only — derived solely from Build's `satisfied`
+ * flag so presentation can list blockers without re-deciding readiness.
+ */
+function unsatisfiedDependencyIds(task: CanonicalTaskProjection): string[] {
+  return task.dependencies
+    .filter((dependency) => !dependency.satisfied)
+    .map((dependency) => dependency.id);
+}
+
+/** Copy navigation metadata as Build published it; never recompute timestamps or location. */
+function mapTaskNavigation(
+  task: CanonicalTaskProjection
+): Pick<
+  PlanningTaskView,
+  | 'priority'
+  | 'created'
+  | 'updated'
+  | 'started'
+  | 'completed'
+  | 'archived'
+  | 'cancelled'
+  | 'location'
+> {
+  return {
+    priority: task.priority,
+    created: task.created,
+    updated: task.updated,
+    started: task.started,
+    completed: task.completed,
+    archived: task.archived,
+    cancelled: task.cancelled,
+    location: task.location,
+  };
+}
+
+function mapTask(task: CanonicalTaskProjection, notes: PlanningWorkspaceNote[]): PlanningTaskView {
+  if (task.state === 'missing') {
+    notes.push({
+      scope: 'task',
+      kind: 'missing',
+      id: task.id,
+      detail: 'The sprint references this task, but Build could not load it.',
+    });
+    return {
+      id: task.id,
+      title: task.id,
+      status: 'unknown',
+      ...mapTaskNavigation(task),
+      owner: null,
+      ownership: task.ownership,
+      estimates: task.estimates,
+      dependsOn: [],
+      linkedBacklogItemId: task.linkedBacklogItemId,
+      dependencies: mapDependencies(task.dependencies),
+      blockers: mapBlockers(task.blockers),
+    };
+  }
+
+  const status = task.status;
+  if (status === null) {
+    notes.push({
+      scope: 'task',
+      kind: 'unavailable',
+      id: task.id,
+      detail: 'Build reported no status for this task.',
+    });
+  }
+
+  for (const blocker of task.blockers) {
+    notes.push({
+      scope: 'task',
+      kind: 'blocked',
+      id: task.id,
+      detail:
+        blocker.reason ??
+        (blocker.kind === 'dependency'
+          ? `Build reports dependency ${blocker.id} as blocking with no recorded reason.`
+          : 'Build reports this task as blocked with no recorded reason.'),
+    });
+  }
+
+  return {
+    id: task.id,
+    title: task.title ?? task.id,
+    status: status === null ? 'unknown' : PRESENTED_TASK_STATUS[status],
+    ...mapTaskNavigation(task),
+    owner: task.assignee,
+    ownership: task.ownership,
+    estimates: task.estimates,
+    dependsOn: unsatisfiedDependencyIds(task),
+    linkedBacklogItemId: task.linkedBacklogItemId,
+    dependencies: mapDependencies(task.dependencies),
+    blockers: mapBlockers(task.blockers),
+  };
+}
+
+function mapTasks(
+  tasks: CanonicalPlanningProjectionInput['tasks'],
+  notes: PlanningWorkspaceNote[]
+): PlanningTaskView[] {
+  if (tasks.state === 'unavailable') {
+    notes.push({ scope: 'tasks', kind: 'unavailable', id: null, detail: tasks.reason });
+    return [];
+  }
+  if (tasks.state === 'missing') {
+    notes.push({
+      scope: 'tasks',
+      kind: 'missing',
+      id: null,
+      detail: 'Build reports no sprint task set.',
+    });
+    return [];
+  }
+  return tasks.value.map((task) => mapTask(task, notes));
+}
+
+/**
+ * Pass next candidates through in Build order with whyIncluded. Empty list when
+ * missing/unavailable; those states are disclosed as notes, never re-ranked.
+ */
+function mapNextCandidates(
+  nextCandidates: CanonicalPlanningProjectionInput['nextCandidates'],
+  notes: PlanningWorkspaceNote[]
+): PlanningNextCandidateView[] {
+  if (nextCandidates.state === 'unavailable') {
+    notes.push({
+      scope: 'next-candidates',
+      kind: 'unavailable',
+      id: null,
+      detail: nextCandidates.reason,
+    });
+    return [];
+  }
+  if (nextCandidates.state === 'missing') {
+    notes.push({
+      scope: 'next-candidates',
+      kind: 'missing',
+      id: null,
+      detail: 'Build reports no next-candidates evidence.',
+    });
+    return [];
+  }
+  // Preserve order exactly; do not sort or re-rank.
+  return nextCandidates.value.map((candidate) => ({
+    id: candidate.id,
+    kind: candidate.kind,
+    title: candidate.title,
+    status: candidate.status,
+    priority: candidate.priority,
+    whyIncluded: candidate.whyIncluded,
+  }));
+}
+
+/**
+ * Advisory synchronization health, derived only from evidence Build published.
+ *
+ * Unreadable commit evidence is `unavailable`, unpushed commits are `ahead`, and
+ * zero unpushed commits are `in-sync`. A reported failure is disclosed as
+ * evidence but does not establish current staleness because the read model does
+ * not report whether that failure remains unresolved. This value never gates
+ * anything.
+ */
+function mapSyncHealth(
+  syncHealth: TeamVisibilitySyncHealth,
+  observedAt: string,
+  notes: PlanningWorkspaceNote[]
+): PlanningWorkspaceData['syncHealth'] {
+  const commits = syncHealth.unpushedPlanningCommits;
+  const failure = syncHealth.lastSyncFailure;
+  const details: string[] = [];
+
+  let state: PlanningSyncState;
+  if (failure.status === 'available') {
+    details.push(
+      failure.value.observedAt
+        ? `Build reported a planning sync failure at ${failure.value.observedAt}: ${failure.value.message}.`
+        : `Build reported a planning sync failure: ${failure.value.message}.`
+    );
+    notes.push({
+      scope: 'sync-health',
+      kind: 'sync-failure',
+      id: null,
+      detail: failure.value.message,
+    });
+  }
+  if (commits.status === 'unavailable') {
+    state = 'unavailable';
+  } else {
+    state = commits.value > 0 ? 'ahead' : 'in-sync';
+  }
+
+  if (commits.status === 'available') {
+    details.push(
+      commits.value === 1
+        ? '1 unpushed planning commit.'
+        : `${commits.value} unpushed planning commits.`
+    );
+  } else {
+    details.push(commits.reason);
+    notes.push({ scope: 'sync-health', kind: 'unavailable', id: null, detail: commits.reason });
+  }
+  if (syncHealth.deferSyncActive) {
+    details.push('Planning sync is deferred by configuration.');
+  }
+
+  return {
+    state,
+    detail: details.length > 0 ? details.join(' ') : null,
+    observedAt,
+  };
+}
+
+function mapActiveWork(
+  work: readonly TeamVisibilityWorkItem[],
+  notes: PlanningWorkspaceNote[]
+): PlanningActiveWorkView[] {
+  return work.map((item) => {
+    if (item.updateAgeMs.status === 'unavailable') {
+      notes.push({
+        scope: 'active-work',
+        kind: 'unavailable',
+        id: item.id,
+        detail: item.updateAgeMs.reason,
+      });
+    }
+    const optionalEvidence = [item.blockers, item.run, item.worktree, item.commit, item.pr];
+    for (const evidence of optionalEvidence) {
+      if (evidence?.status === 'unavailable') {
+        notes.push({
+          scope: 'active-work',
+          kind: 'unavailable',
+          id: item.id,
+          detail: evidence.reason,
+        });
+      }
+    }
+    return {
+      id: item.id,
+      title: item.title,
+      assignee: evidenceFrom(item.assignee),
+      ...(item.ownership !== undefined ? { ownership: evidenceFrom(item.ownership) } : {}),
+      ...(item.blockers !== undefined ? { blockers: evidenceFrom(item.blockers) } : {}),
+      ...(item.run !== undefined ? { run: evidenceFrom(item.run) } : {}),
+      branch: evidenceFrom(item.branch),
+      ...(item.worktree !== undefined ? { worktree: evidenceFrom(item.worktree) } : {}),
+      ...(item.commit !== undefined ? { commit: evidenceFrom(item.commit) } : {}),
+      ...(item.pr !== undefined ? { pr: evidenceFrom(item.pr) } : {}),
+      updatedAt: item.updatedAt,
+      updateAgeMs: evidenceFrom(item.updateAgeMs),
+    };
+  });
+}
+
+/**
+ * Pure mapping from already-read projections to the panel's input. The same
+ * input always yields the same projection, and neither input is mutated.
+ */
+export function mapPlanningWorkspace(inputs: {
+  canonical: CanonicalProjectionValue<CanonicalPlanningProjectionInput>;
+  teamVisibility: CanonicalProjectionValue<TeamVisibilityProjectionInput>;
+}): PlanningWorkspaceProjection {
+  const notes: PlanningWorkspaceNote[] = [];
+
+  let sprint: PlanningSprintSummary | null = null;
+  let tasks: PlanningTaskView[] = [];
+  let nextCandidates: PlanningNextCandidateView[] = [];
+  if (inputs.canonical.state === 'available') {
+    sprint = mapSprint(inputs.canonical.value.activeSprint, notes);
+    tasks = mapTasks(inputs.canonical.value.tasks, notes);
+    nextCandidates = mapNextCandidates(inputs.canonical.value.nextCandidates, notes);
+  } else {
+    const detail =
+      inputs.canonical.state === 'unavailable'
+        ? inputs.canonical.reason
+        : 'Build reported no canonical planning projection.';
+    const kind = inputs.canonical.state === 'unavailable' ? 'unavailable' : 'missing';
+    notes.push({ scope: 'sprint', kind, id: null, detail });
+    notes.push({ scope: 'tasks', kind, id: null, detail });
+    notes.push({ scope: 'next-candidates', kind, id: null, detail });
+  }
+
+  if (inputs.teamVisibility.state !== 'available') {
+    const detail =
+      inputs.teamVisibility.state === 'unavailable'
+        ? inputs.teamVisibility.reason
+        : 'Build reported no team-visibility projection.';
+    notes.push({
+      scope: 'sync-health',
+      kind: inputs.teamVisibility.state === 'unavailable' ? 'unavailable' : 'missing',
+      id: null,
+      detail,
+    });
+    return {
+      data: {
+        sprint,
+        tasks,
+        nextCandidates,
+        // Unobserved synchronization is unavailable, never a healthy or stale claim.
+        syncHealth: { state: 'unavailable', detail, observedAt: null },
+      },
+      activeWork: { state: 'unavailable', reason: detail },
+      observedAt: null,
+      notes,
+    };
+  }
+
+  const visibility = inputs.teamVisibility.value;
+  const activeWork = mapActiveWork(visibility.work, notes);
+  const syncHealth = mapSyncHealth(visibility.syncHealth, visibility.observedAt, notes);
+  return {
+    data: { sprint, tasks, nextCandidates, syncHealth },
+    activeWork: { state: 'available', value: activeWork },
+    observedAt: visibility.observedAt,
+    notes,
+  };
+}
+
+/**
+ * Read both projections once and map them.
+ *
+ * Each source is read on every call and each failure is reported as structured
+ * unavailable evidence for that surface only, so one unreadable source never
+ * hides the other and never presents itself as healthy planning state.
+ */
+export async function queryPlanningWorkspace(
+  source: PlanningWorkspaceSource
+): Promise<PlanningWorkspaceProjection> {
+  const [canonicalResult, visibilityResult] = await Promise.allSettled([
+    source.readCanonicalPlanning(),
+    source.readTeamVisibility(),
+  ]);
+  return mapPlanningWorkspace({
+    canonical:
+      canonicalResult.status === 'fulfilled'
+        ? { state: 'available', value: canonicalResult.value }
+        : { state: 'unavailable', reason: reasonFrom(canonicalResult.reason) },
+    teamVisibility:
+      visibilityResult.status === 'fulfilled'
+        ? { state: 'available', value: visibilityResult.value }
+        : { state: 'unavailable', reason: reasonFrom(visibilityResult.reason) },
+  });
+}

package/integrations/bb-plugin-build/src/planning-sync-evidence.ts

@@ -0,0 +1,37 @@
+import type { PlanningEvidence, PlanningWorkspaceProjection } from './planning-service.js';
+import { unprovenPublicationDetail } from './planning-workspace-schema.js';
+
+export function planningSyncWarnings(workspace: PlanningWorkspaceProjection): string[] {
+  const warnings: string[] = [];
+  const health = workspace.data.syncHealth;
+  if (health.state !== 'in-sync') {
+    warnings.push(health.detail ?? `Build reports planning sync state ${health.state}.`);
+  }
+  for (const note of workspace.notes) {
+    if (note.scope === 'sync-health') warnings.push(note.detail);
+  }
+  return [...new Set(warnings)];
+}
+
+/** Workspace health without an action-specific publication receipt. */
+export function planningWorkspaceSyncState(
+  workspace: PlanningEvidence<PlanningWorkspaceProjection>
+): { state: 'unknown' | 'local_commit_only' | 'failed'; detail: string | null } {
+  if (workspace.state === 'unavailable') {
+    return { state: 'unknown', detail: workspace.reason };
+  }
+  const health = workspace.value.data.syncHealth;
+  const state =
+    health.state === 'in-sync'
+      ? 'unknown'
+      : health.state === 'ahead'
+        ? 'local_commit_only'
+        : health.state === 'unavailable'
+          ? 'unknown'
+          : 'failed';
+  const detail =
+    state === 'unknown' && health.state === 'in-sync'
+      ? unprovenPublicationDetail(health.detail)
+      : health.detail;
+  return { state, detail };
+}