@poetic-ai/poetic 1.42.0

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

@@ -0,0 +1,594 @@
+/**
+ * Service adapter between Poetic's canonical planning projections and the
+ * read-only planning workspace panel.
+ *
+ * Poetic 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 Poetic 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 Poetic's `src/planning` projection shapes
+ * structurally. This plugin is a separate package that does not import Poetic
+ * 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,
+  PlanningWorkspaceData,
+} from './planning-workspace.js';
+
+/** Mirror of Poetic's `ProjectionValue<T>`: missing is distinct from unavailable. */
+export type CanonicalProjectionValue<T> =
+  | { state: 'available'; value: T }
+  | { state: 'missing' }
+  | { state: 'unavailable'; reason: string };
+
+/** Mirror of Poetic'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;
+}
+
+export interface CanonicalTaskProjection {
+  id: string;
+  state: 'available' | 'missing';
+  title: string | null;
+  status: CanonicalTaskStatus | null;
+  assignee: string | null;
+  /** Canonical priority when published; null for missing placeholders or older envelopes. */
+  priority: string | null;
+  /** Lifecycle timestamps copied from Poetic; 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 Poetic's `VisibilityEvidence<T>`. */
+export type TeamVisibilityEvidence<T> =
+  | { status: 'available'; value: T }
+  | { status: 'unavailable'; reason: string };
+
+export interface TeamVisibilityWorkItem {
+  id: string;
+  title: string;
+  status: 'in_progress';
+  assignee: TeamVisibilityEvidence<string>;
+  branch: TeamVisibilityEvidence<string>;
+  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 Poetic's team-visibility projection reported it. */
+export interface PlanningActiveWorkView {
+  id: string;
+  title: string;
+  assignee: PlanningEvidence<string>;
+  branch: PlanningEvidence<string>;
+  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: 'Poetic 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 Poetic 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 Poetic'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 Poetic 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 Poetic could not load it.',
+    });
+    return {
+      id: task.id,
+      title: task.id,
+      status: 'unknown',
+      ...mapTaskNavigation(task),
+      owner: null,
+      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: 'Poetic 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'
+          ? `Poetic reports dependency ${blocker.id} as blocking with no recorded reason.`
+          : 'Poetic 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,
+    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: 'Poetic reports no sprint task set.',
+    });
+    return [];
+  }
+  return tasks.value.map((task) => mapTask(task, notes));
+}
+
+/**
+ * Pass next candidates through in Poetic 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: 'Poetic 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 Poetic 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
+        ? `Poetic reported a planning sync failure at ${failure.value.observedAt}: ${failure.value.message}.`
+        : `Poetic 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,
+      });
+    }
+    return {
+      id: item.id,
+      title: item.title,
+      assignee: evidenceFrom(item.assignee),
+      branch: evidenceFrom(item.branch),
+      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
+        : 'Poetic 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
+        : 'Poetic 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-poetic/src/planning-workspace-schema.ts

@@ -0,0 +1,95 @@
+import { z } from 'zod';
+
+const evidenceSchema = <T extends z.ZodType>(value: T) =>
+  z.discriminatedUnion('state', [
+    z.object({ state: z.literal('available'), value }),
+    z.object({ state: z.literal('unavailable'), reason: z.string() }),
+  ]);
+
+const dependencyRecordSchema = z.object({
+  id: z.string(),
+  state: z.enum(['available', 'recorded-complete', 'missing']),
+  status: z.string().nullable(),
+  satisfied: z.boolean(),
+});
+
+const blockerRecordSchema = z.object({
+  kind: z.enum(['task-status', 'dependency']),
+  id: z.string(),
+  reason: z.string().nullable(),
+});
+
+const taskSchema = z.object({
+  id: z.string(),
+  title: z.string(),
+  status: z.enum(['todo', 'in-progress', 'review', 'blocked', 'done', 'cancelled', 'unknown']),
+  priority: z.string().nullable(),
+  created: z.string().nullable(),
+  updated: z.string().nullable(),
+  started: z.string().nullable(),
+  completed: z.string().nullable(),
+  archived: z.string().nullable(),
+  cancelled: z.string().nullable(),
+  location: z.enum(['active', 'archive']).nullable(),
+  owner: z.string().nullable(),
+  estimates: z.object({ hours: z.number().nullable(), runtimeMinutes: z.number().nullable() }),
+  dependsOn: z.array(z.string()).readonly(),
+  linkedBacklogItemId: z.string().nullable(),
+  dependencies: z.array(dependencyRecordSchema).readonly(),
+  blockers: z.array(blockerRecordSchema).readonly(),
+});
+
+const nextCandidateSchema = z.object({
+  id: z.string(),
+  kind: z.string(),
+  title: z.string(),
+  status: z.string(),
+  priority: z.string().nullable(),
+  whyIncluded: z.string(),
+});
+
+export const planningWorkspaceProjectionSchema = z.object({
+  data: z.object({
+    sprint: z
+      .object({
+        id: z.string(),
+        title: z.string(),
+        status: z.string(),
+        startedAt: z.string().nullable(),
+        targetDate: z.string().nullable(),
+      })
+      .nullable(),
+    tasks: z.array(taskSchema).readonly(),
+    nextCandidates: z.array(nextCandidateSchema).readonly(),
+    syncHealth: z.object({
+      state: z.enum(['in-sync', 'ahead', 'stale', 'unavailable']),
+      detail: z.string().nullable(),
+      observedAt: z.string().nullable(),
+    }),
+  }),
+  activeWork: evidenceSchema(
+    z
+      .array(
+        z.object({
+          id: z.string(),
+          title: z.string(),
+          assignee: evidenceSchema(z.string()),
+          branch: evidenceSchema(z.string()),
+          updatedAt: z.string(),
+          updateAgeMs: evidenceSchema(z.number()),
+        })
+      )
+      .readonly()
+  ),
+  observedAt: z.string().nullable(),
+  notes: z
+    .array(
+      z.object({
+        scope: z.enum(['sprint', 'tasks', 'task', 'next-candidates', 'active-work', 'sync-health']),
+        kind: z.enum(['missing', 'unavailable', 'unmapped-status', 'blocked', 'sync-failure']),
+        id: z.string().nullable(),
+        detail: z.string(),
+      })
+    )
+    .readonly(),
+});