@poetic-ai/poetic 1.42.0

package/integrations/bb-plugin-poetic/src/task-detail-readback.ts

@@ -0,0 +1,56 @@
+/**
+ * Validate Poetic's versioned task-detail projection as untrusted process output.
+ *
+ * Fail closed: incompatible major versions, missing envelopes, and malformed
+ * payloads become unavailable — never an invented healthy task.
+ */
+
+import {
+  type GetTaskDetailOutput,
+  taskDetailEnvelopeSchema,
+  taskDetailResultSchema,
+} from './task-detail-schema.js';
+
+const SUPPORTED_PROJECTION_MAJOR = '1';
+
+function unavailable(reason: string, schemaVersion: string | null = null): GetTaskDetailOutput {
+  return {
+    schemaVersion,
+    task: { state: 'unavailable', reason },
+  };
+}
+
+/**
+ * Parse one taskDetailV1 envelope from Poetic task status --json.
+ * Does not read files, env, argv, or cwd; only the supplied JSON value.
+ */
+export function parseTaskDetailV1(value: unknown): GetTaskDetailOutput {
+  const envelope = taskDetailEnvelopeSchema.safeParse(value);
+  if (!envelope.success) {
+    return unavailable('Poetic returned a malformed task-detail projection.');
+  }
+
+  const schemaVersion = envelope.data.schemaVersion;
+  if (schemaVersion.split('.')[0] !== SUPPORTED_PROJECTION_MAJOR) {
+    return unavailable(
+      'Poetic returned an unsupported task-detail projection major version.',
+      schemaVersion
+    );
+  }
+
+  const task = taskDetailResultSchema.safeParse(envelope.data.task);
+  if (!task.success) {
+    return unavailable('Poetic returned malformed task-detail evidence.', schemaVersion);
+  }
+
+  // Available facts must carry the requested identity shape; state inside value
+  // is always available when the outer envelope state is available.
+  if (task.data.state === 'available' && task.data.value.state !== 'available') {
+    return unavailable('Poetic returned inconsistent task-detail availability.', schemaVersion);
+  }
+
+  return {
+    schemaVersion,
+    task: task.data,
+  };
+}

package/integrations/bb-plugin-poetic/src/task-detail-schema.ts

@@ -0,0 +1,144 @@
+/**
+ * BB wire schemas for Poetic's versioned single-task detail projection.
+ *
+ * Strict shapes only: no arbitrary file paths, argv, cwd, env, or invented
+ * execution/PR/run evidence. Linked backlog id is the v1 provenance path.
+ * Schemas live here so unit tests can load them without @bb/plugin-sdk.
+ */
+
+import { z } from 'zod';
+import { repositorySchema } from './repository-schema.js';
+
+/**
+ * Managed task id: single safe path component. No separators, traversal, or
+ * leading dash/dot that could be read as a hidden file or CLI flag.
+ */
+export const getTaskIdSchema = z
+  .string()
+  .min(1)
+  .max(200)
+  .regex(/^[A-Za-z0-9][A-Za-z0-9._-]*$/, 'A task id must be a single safe path component.');
+
+/** Validated repository + task identity for getTask. No free-form surfaces. */
+export const getTaskInputSchema = z
+  .object({
+    projectId: z.string().min(1),
+    sourceId: z.string().min(1),
+    taskId: getTaskIdSchema,
+  })
+  .strict();
+
+const taskStatusSchema = z.enum(['todo', 'in_progress', 'review', 'done', 'blocked', 'cancelled']);
+
+const dependencySchema = z
+  .object({
+    id: z.string(),
+    state: z.enum(['available', 'recorded-complete', 'missing']),
+    status: taskStatusSchema.nullable(),
+    satisfied: z.boolean(),
+  })
+  .strict();
+
+const blockerSchema = z
+  .object({
+    kind: z.enum(['task-status', 'dependency']),
+    id: z.string(),
+    reason: z.string().nullable(),
+  })
+  .strict();
+
+/**
+ * Canonical task facts when Poetic published an available detail projection.
+ * Mirrors PlanningTaskProjection; state is always available inside this value.
+ */
+export const taskDetailFactsSchema = z
+  .object({
+    id: z.string(),
+    state: z.literal('available'),
+    title: z.string().nullable(),
+    status: taskStatusSchema.nullable(),
+    assignee: z.string().nullable(),
+    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(),
+    estimates: z
+      .object({
+        hours: z.number().nullable(),
+        runtimeMinutes: z.number().nullable(),
+      })
+      .strict(),
+    dependencies: z.array(dependencySchema),
+    blockers: z.array(blockerSchema),
+    linkedBacklogItemId: z.string().nullable(),
+  })
+  .strict();
+
+const unavailableSchema = z
+  .object({
+    state: z.literal('unavailable'),
+    reason: z.string().min(1),
+  })
+  .strict();
+
+const missingSchema = z.object({ state: z.literal('missing') }).strict();
+
+const availableSchema = z
+  .object({
+    state: z.literal('available'),
+    value: taskDetailFactsSchema,
+  })
+  .strict();
+
+/**
+ * One task-detail result: active/archived live under available+location;
+ * missing and unavailable are top-level states.
+ */
+export const taskDetailResultSchema = z.discriminatedUnion('state', [
+  availableSchema,
+  missingSchema,
+  unavailableSchema,
+]);
+
+/**
+ * Versioned Poetic envelope. BB validates major version before mapping.
+ */
+export const taskDetailEnvelopeSchema = z
+  .object({
+    schemaVersion: z.string().min(1),
+    task: z.unknown(),
+  })
+  .strict();
+
+/**
+ * Adapter-level detail body before the repository field is attached.
+ */
+export const getTaskDetailOutputSchema = z
+  .object({
+    schemaVersion: z.string().nullable(),
+    task: taskDetailResultSchema,
+  })
+  .strict();
+
+/** Full getTask RPC output including repository binding. */
+export const getTaskOutputSchema = z
+  .object({
+    repository: repositorySchema,
+    schemaVersion: z.string().nullable(),
+    task: taskDetailResultSchema,
+  })
+  .strict();
+
+/** Frozen method surface for host contract / tests (mirrors applyTaskActionMethod). */
+export const getTaskMethod = {
+  input: getTaskInputSchema,
+  output: getTaskOutputSchema,
+} as const;
+
+export type TaskDetailFacts = z.infer<typeof taskDetailFactsSchema>;
+export type TaskDetailResult = z.infer<typeof taskDetailResultSchema>;
+export type GetTaskDetailOutput = z.infer<typeof getTaskDetailOutputSchema>;

package/integrations/bb-plugin-poetic/src/task-navigation.ts

@@ -0,0 +1,446 @@
+/**
+ * Pure presentation and navigation helpers for the read-only task surfaces of
+ * the existing Planning Workspace.
+ *
+ * Every value here comes from data the caller already read from Poetic. Nothing
+ * in this module reads Poetic internals, managed planning files, Git, the
+ * filesystem, or the network, and nothing mutates planning state: Poetic remains
+ * the planning authority.
+ *
+ * Dependency classification, blocker reasons, and next-candidate order are
+ * rendered exactly as Poetic published them. This module never recomputes
+ * dependency satisfaction, re-ranks candidates, or invents a status. Empty,
+ * missing, unavailable, archived, and diverged states stay separate and are
+ * never collapsed into one another.
+ *
+ * The navigation targets below address only Poetic's existing single-task detail
+ * read and the existing backlog-detail read. No second workspace, poller, task
+ * mirror, or competition/judge action is introduced here.
+ */
+
+import type { CanonicalTaskStatus } from './planning-service.js';
+import { PRESENTED_TASK_STATUS } from './planning-service.js';
+import type {
+  PlanningBlockerRecord,
+  PlanningDependencyRecord,
+  PlanningNextCandidateView,
+  PlanningQueueView,
+  PlanningTaskStatus,
+  PlanningTaskView,
+} from './planning-workspace.js';
+import { PLANNING_QUEUE_LABELS } from './planning-workspace.js';
+import type { TaskDetailFacts, TaskDetailResult } from './task-detail-schema.js';
+
+/**
+ * Where a read-only navigation action goes. Only surfaces that already exist are
+ * addressable: one canonical task detail read, or the existing backlog detail.
+ */
+export type PlanningNavigationTarget =
+  | { kind: 'task'; taskId: string }
+  | { kind: 'backlog'; backlogItemId: string };
+
+export type PlanningTaskNavigationTarget = Extract<PlanningNavigationTarget, { kind: 'task' }>;
+
+export type PlanningBacklogNavigationTarget = Extract<
+  PlanningNavigationTarget,
+  { kind: 'backlog' }
+>;
+
+function taskTarget(taskId: string): PlanningTaskNavigationTarget {
+  return { kind: 'task', taskId };
+}
+
+function backlogTarget(backlogItemId: string): PlanningBacklogNavigationTarget {
+  return { kind: 'backlog', backlogItemId };
+}
+
+/** One selectable task row inside a queue. */
+export interface PlanningTaskRowView {
+  /** The queue task exactly as the workspace view reported it. */
+  task: PlanningTaskView;
+  /** Queue this row belongs to; every queue yields selectable rows. */
+  queue: PlanningTaskStatus;
+  selected: boolean;
+  /** Selecting a row reads fresh canonical detail for this task id. */
+  target: PlanningTaskNavigationTarget;
+  /** Existing backlog-detail target; null when Poetic published no link. */
+  linkedBacklog: PlanningBacklogNavigationTarget | null;
+}
+
+export interface PlanningTaskQueueRowsView {
+  status: PlanningTaskStatus;
+  label: string;
+  rows: readonly PlanningTaskRowView[];
+}
+
+/**
+ * Make every queue's tasks selectable, preserving the queue order and the task
+ * order the workspace view already produced.
+ */
+export function buildTaskQueueRows(
+  queues: readonly PlanningQueueView[],
+  selectedTaskId: string | null
+): readonly PlanningTaskQueueRowsView[] {
+  return queues.map((queue) => ({
+    status: queue.status,
+    label: queue.label,
+    rows: queue.tasks.map((task) => ({
+      task,
+      queue: queue.status,
+      selected: selectedTaskId !== null && task.id === selectedTaskId,
+      target: taskTarget(task.id),
+      linkedBacklog:
+        task.linkedBacklogItemId === null ? null : backlogTarget(task.linkedBacklogItemId),
+    })),
+  }));
+}
+
+/**
+ * Find one selectable row by task id. Returns null when the id is not in this
+ * projection, which stays distinct from a task that is present but unselected.
+ */
+export function findTaskRow(
+  queues: readonly PlanningTaskQueueRowsView[],
+  taskId: string
+): PlanningTaskRowView | null {
+  for (const queue of queues) {
+    const row = queue.rows.find((entry) => entry.task.id === taskId);
+    if (row) return row;
+  }
+  return null;
+}
+
+export interface PlanningNextCandidateNavigationView {
+  /** Poetic's candidate, including its reasoning, passed through verbatim. */
+  candidate: PlanningNextCandidateView;
+  /** Poetic's published position (1-based), kept so the order stays auditable. */
+  order: number;
+  /** Null when Poetic's kind has no read-only detail surface in this panel. */
+  target: PlanningNavigationTarget | null;
+  /** Why no navigation is offered; null when a target exists. */
+  unnavigableReason: string | null;
+}
+
+/**
+ * Attach a navigation target to each next candidate in Poetic's order. Tasks go
+ * to canonical task detail and backlog items to the existing backlog detail;
+ * any other kind Poetic reports is disclosed rather than guessed at. This helper
+ * never sorts or re-ranks the list.
+ */
+export function buildNextCandidateNavigation(
+  candidates: readonly PlanningNextCandidateView[]
+): readonly PlanningNextCandidateNavigationView[] {
+  return candidates.map((candidate, index) => {
+    const order = index + 1;
+    if (candidate.kind === 'task') {
+      return { candidate, order, target: taskTarget(candidate.id), unnavigableReason: null };
+    }
+    if (candidate.kind === 'backlog') {
+      return { candidate, order, target: backlogTarget(candidate.id), unnavigableReason: null };
+    }
+    return {
+      candidate,
+      order,
+      target: null,
+      unnavigableReason: `Poetic reports this candidate as kind "${candidate.kind}", which has no read-only detail surface in this panel.`,
+    };
+  });
+}
+
+const TASK_STATUS_LABELS: Readonly<Record<CanonicalTaskStatus, string>> = {
+  todo: 'To do',
+  in_progress: 'In progress',
+  review: 'Review',
+  done: 'Done',
+  blocked: 'Blocked',
+  cancelled: 'Cancelled',
+};
+
+const TASK_LOCATION_LABELS: Readonly<Record<'active' | 'archive', string>> = {
+  active: 'Active',
+  archive: 'Archived',
+};
+
+/**
+ * Poetic's dependency classification in words. `recorded-complete` keeps its own
+ * label so it is never read as a loaded task file or as a missing dependency.
+ */
+const DEPENDENCY_STATE_LABELS: Readonly<Record<PlanningDependencyRecord['state'], string>> = {
+  available: 'Dependency task is present in managed planning',
+  'recorded-complete': 'Recorded complete on the sprint; the task file is not present',
+  missing: 'Dependency task is not present in managed planning',
+};
+
+const BLOCKER_KIND_LABELS: Readonly<Record<PlanningBlockerRecord['kind'], string>> = {
+  'task-status': "This task's own recorded status",
+  dependency: 'Dependency',
+};
+
+export const UNREPORTED_TASK_STATUS_LABEL = 'Status not reported';
+export const UNREPORTED_TASK_LOCATION_LABEL = 'Location not reported';
+export const UNREPORTED_DEPENDENCY_STATUS_LABEL = 'Dependency status not reported';
+export const UNREPORTED_BLOCKER_REASON_LABEL = 'Poetic recorded no reason for this blocker';
+export const UNREPORTED_TASK_TITLE_LABEL = 'Title not reported';
+export const NO_DEPENDENCIES_LABEL = 'Poetic reports no dependencies for this task.';
+export const NO_BLOCKERS_LABEL = 'Poetic reports no blockers for this task.';
+export const NO_LINKED_BACKLOG_LABEL = 'Poetic reports no linked backlog item.';
+export const ARCHIVED_TASK_NOTICE =
+  'Poetic reports this task in the archive bucket, not in active planning.';
+
+function taskStatusLabel(status: CanonicalTaskStatus | null): string {
+  return status === null ? UNREPORTED_TASK_STATUS_LABEL : TASK_STATUS_LABELS[status];
+}
+
+export interface TaskDetailTimestampView {
+  label: string;
+  /** Poetic's timestamp verbatim; null when Poetic reported none. */
+  value: string | null;
+}
+
+export interface TaskDetailDependencyRowView {
+  id: string;
+  state: PlanningDependencyRecord['state'];
+  status: CanonicalTaskStatus | null;
+  satisfied: boolean;
+  stateLabel: string;
+  statusLabel: string;
+  satisfactionLabel: string;
+  /**
+   * A missing dependency stays navigable: the canonical read reports missing
+   * explicitly, which is more honest than hiding the id.
+   */
+  target: PlanningTaskNavigationTarget;
+}
+
+export interface TaskDetailBlockerRowView {
+  kind: PlanningBlockerRecord['kind'];
+  id: string;
+  kindLabel: string;
+  /** Poetic's reason, or an explicit label when Poetic recorded none. */
+  reason: string;
+  /**
+   * Null for a `task-status` blocker: it is this task's own status, so there is
+   * nowhere else to navigate.
+   */
+  target: PlanningTaskNavigationTarget | null;
+}
+
+export interface TaskDetailAvailableView {
+  state: 'available';
+  id: string;
+  title: string;
+  status: CanonicalTaskStatus | null;
+  statusLabel: string;
+  locationLabel: string;
+  /** True only when Poetic reported the archive bucket. */
+  archived: boolean;
+  archivedNotice: string | null;
+  assigneeLabel: string;
+  priorityLabel: string;
+  estimateLine: string;
+  /** All lifecycle timestamps, so an absent one is visible rather than omitted. */
+  timestamps: readonly TaskDetailTimestampView[];
+  dependencies: readonly TaskDetailDependencyRowView[];
+  dependenciesEmptyLabel: string;
+  blockers: readonly TaskDetailBlockerRowView[];
+  blockersEmptyLabel: string;
+  linkedBacklog: PlanningBacklogNavigationTarget | null;
+  linkedBacklogEmptyLabel: string;
+  /** Poetic's projection version, or null when it reported none. */
+  schemaVersion: string | null;
+}
+
+export interface TaskDetailAbsentView {
+  state: 'missing' | 'unavailable';
+  taskId: string;
+  headline: string;
+  detail: string;
+  schemaVersion: string | null;
+}
+
+export type TaskDetailView = TaskDetailAvailableView | TaskDetailAbsentView;
+
+/** One canonical task-detail reply as the panel received it. */
+export interface TaskDetailInput {
+  /** The task id BB asked for, used for missing and unavailable headlines. */
+  taskId: string;
+  schemaVersion: string | null;
+  task: TaskDetailResult;
+}
+
+function estimateLine(estimates: TaskDetailFacts['estimates']): string {
+  const hours = estimates.hours === null ? 'unavailable' : String(estimates.hours);
+  const runtime =
+    estimates.runtimeMinutes === null ? 'unavailable' : String(estimates.runtimeMinutes);
+  return `estimate ${hours}h / ${runtime}m runtime`;
+}
+
+function timestampViews(facts: TaskDetailFacts): TaskDetailTimestampView[] {
+  return [
+    { label: 'Created', value: facts.created },
+    { label: 'Updated', value: facts.updated },
+    { label: 'Started', value: facts.started },
+    { label: 'Completed', value: facts.completed },
+    { label: 'Archived', value: facts.archived },
+    { label: 'Cancelled', value: facts.cancelled },
+  ];
+}
+
+function dependencyRows(facts: TaskDetailFacts): TaskDetailDependencyRowView[] {
+  // Poetic's order and classification pass through; satisfaction is never re-decided.
+  return facts.dependencies.map((dependency) => ({
+    id: dependency.id,
+    state: dependency.state,
+    status: dependency.status,
+    satisfied: dependency.satisfied,
+    stateLabel: DEPENDENCY_STATE_LABELS[dependency.state],
+    statusLabel:
+      dependency.status === null
+        ? UNREPORTED_DEPENDENCY_STATUS_LABEL
+        : TASK_STATUS_LABELS[dependency.status],
+    satisfactionLabel: dependency.satisfied ? 'Satisfied' : 'Unsatisfied',
+    target: taskTarget(dependency.id),
+  }));
+}
+
+function blockerRows(facts: TaskDetailFacts): TaskDetailBlockerRowView[] {
+  return facts.blockers.map((blocker) => ({
+    kind: blocker.kind,
+    id: blocker.id,
+    kindLabel: BLOCKER_KIND_LABELS[blocker.kind],
+    reason: blocker.reason ?? UNREPORTED_BLOCKER_REASON_LABEL,
+    target: blocker.kind === 'dependency' ? taskTarget(blocker.id) : null,
+  }));
+}
+
+/**
+ * Project one canonical task-detail reply into the panel's rendered shape.
+ *
+ * Missing and unavailable keep separate states and are never rendered as a
+ * healthy task. Archived is disclosed on an otherwise available task rather than
+ * being treated as absence.
+ */
+export function buildTaskDetailView(input: TaskDetailInput): TaskDetailView {
+  if (input.task.state === 'missing') {
+    return {
+      state: 'missing',
+      taskId: input.taskId,
+      headline: 'Task not found',
+      detail: `Poetic reports no managed task with id ${input.taskId}.`,
+      schemaVersion: input.schemaVersion,
+    };
+  }
+  if (input.task.state === 'unavailable') {
+    return {
+      state: 'unavailable',
+      taskId: input.taskId,
+      headline: 'Task detail unavailable',
+      detail: input.task.reason,
+      schemaVersion: input.schemaVersion,
+    };
+  }
+
+  const facts = input.task.value;
+  const archived = facts.location === 'archive';
+  return {
+    state: 'available',
+    id: facts.id,
+    title: facts.title ?? UNREPORTED_TASK_TITLE_LABEL,
+    status: facts.status,
+    statusLabel: taskStatusLabel(facts.status),
+    locationLabel:
+      facts.location === null
+        ? UNREPORTED_TASK_LOCATION_LABEL
+        : TASK_LOCATION_LABELS[facts.location],
+    archived,
+    archivedNotice: archived ? ARCHIVED_TASK_NOTICE : null,
+    assigneeLabel: facts.assignee ?? 'Unassigned',
+    priorityLabel: facts.priority ?? 'No priority reported',
+    estimateLine: estimateLine(facts.estimates),
+    timestamps: timestampViews(facts),
+    dependencies: dependencyRows(facts),
+    dependenciesEmptyLabel: NO_DEPENDENCIES_LABEL,
+    blockers: blockerRows(facts),
+    blockersEmptyLabel: NO_BLOCKERS_LABEL,
+    linkedBacklog:
+      facts.linkedBacklogItemId === null ? null : backlogTarget(facts.linkedBacklogItemId),
+    linkedBacklogEmptyLabel: NO_LINKED_BACKLOG_LABEL,
+    schemaVersion: input.schemaVersion,
+  };
+}
+
+/**
+ * Whether the selected queue row still agrees with the freshly read canonical
+ * detail. `unknown` means the two cannot be compared at all, which stays
+ * distinct from an observed divergence.
+ */
+export interface TaskDetailFreshnessView {
+  state: 'consistent' | 'diverged' | 'unknown';
+  label: string;
+}
+
+/**
+ * Compare the selected queue row with canonical detail on the one field both
+ * publish: task status. This is an equality check over two values Poetic already
+ * reported, not a recomputed planning decision, and the canonical detail always
+ * remains authoritative.
+ */
+export function buildTaskDetailFreshnessView(
+  row: PlanningTaskRowView | null,
+  detail: TaskDetailView
+): TaskDetailFreshnessView {
+  if (detail.state !== 'available') {
+    return {
+      state: 'unknown',
+      label: 'Canonical task detail is not available, so the queue row cannot be compared with it.',
+    };
+  }
+  if (!row) {
+    return {
+      state: 'unknown',
+      label:
+        'This task is not in the current workspace projection; the canonical detail above is authoritative.',
+    };
+  }
+  if (detail.status === null) {
+    return {
+      state: 'unknown',
+      label:
+        'Poetic reported no status on the canonical detail, so the queue row cannot be compared with it.',
+    };
+  }
+  const canonicalQueue = PRESENTED_TASK_STATUS[detail.status];
+  if (canonicalQueue === row.task.status) {
+    return { state: 'consistent', label: 'The queue row matches the canonical task detail.' };
+  }
+  return {
+    state: 'diverged',
+    label: `The queue row shows ${PLANNING_QUEUE_LABELS[row.task.status]} and the canonical detail reports ${PLANNING_QUEUE_LABELS[canonicalQueue]}; the workspace projection is stale.`,
+  };
+}
+
+/**
+ * Identity of one task-detail read. `requestId` is monotonic per panel so two
+ * selections of the same task id stay distinguishable when their replies arrive
+ * out of order. Repository generation remains a separate guard.
+ */
+export interface TaskDetailRequestIdentity {
+  taskId: string;
+  requestId: number;
+}
+
+/** Allocate the next monotonic task-detail request id. */
+export function nextTaskDetailRequestId(previousRequestId: number): number {
+  return previousRequestId + 1;
+}
+
+/**
+ * Whether a task-detail reply still belongs to the newest request. Compared by
+ * request id so a same-id reselection discards an older in-flight reply.
+ */
+export function isCurrentTaskDetailRequest(
+  latest: TaskDetailRequestIdentity | null,
+  reply: TaskDetailRequestIdentity
+): boolean {
+  return latest !== null && latest.requestId === reply.requestId;
+}