@poetic-ai/poetic 1.42.0

package/integrations/bb-plugin-poetic/src/sprint-composition-view.ts

@@ -0,0 +1,1221 @@
+/**
+ * Pure BB presentation for the BPAU-03 sprint-composition lane.
+ *
+ * This module is presentation only. It maps already-canonical BPAU-03 evidence
+ * to bounded, plain-language rows and controls, and it converts a form draft into
+ * exactly one typed BPAU-03 request. It holds the same authority boundary as the
+ * rest of this plugin:
+ *
+ *   - Poetic is authoritative. No capacity, readiness, integrity, membership, or
+ *     resulting status is computed, merged, re-sorted, or defaulted here: every
+ *     rendered number and state comes from a BPAU-03 projection, a BPAU-00B
+ *     identity envelope, or an authoritative reread.
+ *   - Absent evidence renders as an explicit `unavailable` with Poetic's own
+ *     reason. A missing value is never replaced by a guess or an empty success.
+ *   - The vocabulary is the closed BPAU-03 vocabulary. Sprint execution,
+ *     complete/close/tidy/unlock/prune-missing, custom task creation, splitting,
+ *     provider/model selection, bulk scheduling, and force/dry-run/no-sync have
+ *     no control here and are refused with an explicit notice.
+ *   - `addSprintWorkFromBacklog` is labelled "Add from backlog". It is never
+ *     described as attaching an existing task.
+ *   - A submission changes nothing on screen until Poetic's reread arrives: the
+ *     awaiting phase renders the pre-submission evidence unchanged.
+ *
+ * Nothing here spawns a process, reads a file, or touches the network, and this
+ * module wires no shared application file: it is loadable on its own.
+ */
+
+import {
+  requiresMembershipConsent,
+  requiresNewIdentityConsent,
+  SPRINT_COMPOSITION_DISCLOSURE,
+  SPRINT_COMPOSITION_EFFECT_COPY,
+  SPRINT_COMPOSITION_LABELS,
+  type SprintCompositionConsentState,
+  sprintCompositionConsentPayload,
+  sprintCompositionRequestedIdentities,
+} from './sprint-composition-model.js';
+import { sprintMembershipIds, sprintMembershipState } from './sprint-composition-readback.js';
+import {
+  type ApplySprintCompositionInput,
+  type ApplySprintCompositionOutput,
+  applySprintCompositionInputSchema,
+  type GetSprintOutput,
+  type ListSprintsOutput,
+  SPRINT_COMPOSITION_OUTCOME_VERSION,
+  SPRINT_COMPOSITION_VOCABULARY,
+  type SprintCompositionAction,
+  type SprintCompositionEvidence,
+  type SprintStatusEnvelope,
+} from './sprint-composition-schema.js';
+import type { GetTaskDetailOutput } from './task-detail-schema.js';
+
+export type { SprintCompositionConsentState };
+
+export const SPRINT_COMPOSITION_VIEW_VERSION = '1.0.0' as const;
+
+/** Bound on any single emitted line. */
+export const SPRINT_COMPOSITION_MAX_LINE_CHARS = 240;
+
+/** Bound on how many identities one row lists. */
+export const SPRINT_COMPOSITION_LIST_LIMIT = 12;
+
+/** Plain label for evidence Poetic did not publish. */
+const UNAVAILABLE = 'unavailable';
+
+export interface SprintCompositionRow {
+  /** Stable row id, usable as a render key. */
+  id: string;
+  label: string;
+  value: string;
+}
+
+function truncateLine(text: string): string {
+  const normalized = text.replace(/\s+/g, ' ').trim();
+  if (normalized.length <= SPRINT_COMPOSITION_MAX_LINE_CHARS) return normalized;
+  return `${normalized.slice(0, SPRINT_COMPOSITION_MAX_LINE_CHARS - 3)}...`;
+}
+
+function row(id: string, label: string, value: string): SprintCompositionRow {
+  return { id, label, value: truncateLine(value) };
+}
+
+/** Render a list of identities. An empty list is a published "none". */
+function formatIdentities(values: readonly string[]): string {
+  if (values.length === 0) return 'none';
+  const shown = values.slice(0, SPRINT_COMPOSITION_LIST_LIMIT);
+  const remaining = values.length - shown.length;
+  return remaining > 0 ? `${shown.join(', ')} (+${remaining} more)` : shown.join(', ');
+}
+
+function formatOptional(value: string | null | undefined): string {
+  const trimmed = value?.trim() ?? '';
+  return trimmed.length > 0 ? trimmed : UNAVAILABLE;
+}
+
+/**
+ * Capacity exactly as Poetic published it. The three numbers are carried
+ * verbatim; utilization is never recomputed from the other two.
+ */
+function formatCapacity(capacity: {
+  allocatedHours: number;
+  totalHours: number;
+  utilizationPercent: number;
+}): string {
+  return `${capacity.allocatedHours}h allocated of ${capacity.totalHours}h, ${capacity.utilizationPercent}% utilization (Poetic-computed)`;
+}
+
+/* ------------------------------------------------------------------ *
+ * Read-only projections: sprint list and single-sprint composition
+ * ------------------------------------------------------------------ */
+
+export interface SprintCompositionListView {
+  state: 'available' | 'unavailable';
+  scope: ListSprintsOutput['scope'];
+  headline: string;
+  rows: readonly SprintCompositionRow[];
+  /** Sprint ids Poetic published, in Poetic's own order. */
+  sprintIds: readonly string[];
+  notes: readonly string[];
+}
+
+/**
+ * Render Poetic's sprint list. Order, totals, and per-sprint capacity are
+ * carried verbatim; an unavailable list is never an empty sprint list.
+ */
+export function buildSprintListView(output: ListSprintsOutput): SprintCompositionListView {
+  if (output.sprints.state !== 'available') {
+    return {
+      state: 'unavailable',
+      scope: output.scope,
+      headline: 'Sprint list unavailable',
+      rows: [],
+      sprintIds: [],
+      notes: [truncateLine(output.sprints.reason)],
+    };
+  }
+  const envelope = output.sprints.value;
+  return {
+    state: 'available',
+    scope: output.scope,
+    headline: `Sprints (${output.scope}): ${envelope.total}`,
+    rows: envelope.sprints.map((sprint) =>
+      row(
+        `sprint-${sprint.id}`,
+        `${sprint.name} (${sprint.id})`,
+        `${sprint.status}, ${sprint.startDate} to ${sprint.endDate}, ${sprint.taskCount} task(s), ${formatCapacity(sprint.capacity)}`
+      )
+    ),
+    sprintIds: envelope.sprints.map((sprint) => sprint.id),
+    notes: [],
+  };
+}
+
+export interface SprintCompositionSprintView {
+  state: 'available' | 'unavailable';
+  sprintId: string;
+  headline: string;
+  rows: readonly SprintCompositionRow[];
+  /** Task ids Poetic lists as members, in Poetic's own order. */
+  membership: readonly string[];
+  /** Task ids the sprint references with no resolvable task file. */
+  missingTaskIds: readonly string[];
+  /** Integrity notes as Poetic reported them. BB reports, never repairs. */
+  integrityNotes: readonly string[];
+  notes: readonly string[];
+}
+
+function unavailableSprintView(
+  sprintId: string,
+  reason: string,
+  integrityNotes: readonly string[] = []
+): SprintCompositionSprintView {
+  return {
+    state: 'unavailable',
+    sprintId,
+    headline: `Sprint ${sprintId} composition unavailable`,
+    rows: [],
+    membership: [],
+    missingTaskIds: [],
+    integrityNotes: integrityNotes.map(truncateLine),
+    notes: [truncateLine(reason)],
+  };
+}
+
+/**
+ * Render one sprint's composition from Poetic's status projection. Capacity,
+ * readiness, membership, and integrity are all Poetic-computed; the only thing
+ * added here is labelling.
+ */
+export function buildSprintCompositionSprintView(
+  sprintId: string,
+  sprint: SprintCompositionEvidence<SprintStatusEnvelope>,
+  integrityNotes: readonly string[] = []
+): SprintCompositionSprintView {
+  if (sprint.state !== 'available') {
+    return unavailableSprintView(sprintId, sprint.reason, integrityNotes);
+  }
+  const value = sprint.value;
+  const progress = value.progress;
+  return {
+    state: 'available',
+    sprintId: value.sprintId,
+    headline: `Sprint ${value.name} (${value.sprintId}): ${value.status}`,
+    rows: [
+      row('sprint-id', 'Sprint', `${value.name} (${value.sprintId})`),
+      row('sprint-status', 'Status', `${value.status}${value.archived ? ', archived' : ''}`),
+      row(
+        'sprint-dates',
+        'Dates',
+        `${formatOptional(value.startDate)} to ${formatOptional(value.endDate)}`
+      ),
+      row('sprint-goal', 'Goal', formatOptional(value.goal)),
+      row('sprint-capacity', 'Capacity', formatCapacity(value.capacity)),
+      row(
+        'sprint-completed-capacity',
+        'Completed capacity',
+        `${value.completedCapacity.totalDoneHours}h done (${value.completedCapacity.activeDoneHours}h active, ${value.completedCapacity.archivedDoneHours}h archived across ${value.completedCapacity.archivedTaskCount} archived task(s))`
+      ),
+      row(
+        'sprint-progress',
+        'Progress',
+        `${progress.done} done, ${progress.in_progress} in progress, ${progress.review} in review, ${progress.todo} to do, ${progress.blocked} blocked, ${progress.cancelled} cancelled of ${progress.total}`
+      ),
+      row(
+        'sprint-readiness',
+        'Readiness',
+        `all done ${progress.allDone ? 'yes' : 'no'}, all terminal ${progress.allTerminal ? 'yes' : 'no'}, closable ${progress.closable ? 'yes' : 'no'} (Poetic-computed)`
+      ),
+      row(
+        'sprint-integrity',
+        'Integrity',
+        progress.integrityClean ? 'clean' : 'not clean (Poetic-reported)'
+      ),
+      row('sprint-membership', 'Members', formatIdentities(sprintMembershipIds(value))),
+      row(
+        'sprint-missing-references',
+        'Missing task references',
+        formatIdentities(value.missingTaskIds)
+      ),
+    ],
+    membership: sprintMembershipIds(value),
+    missingTaskIds: value.missingTaskIds,
+    integrityNotes: integrityNotes.map(truncateLine),
+    notes: [],
+  };
+}
+
+/** Render a `getSprint` projection, carrying its integrity notes through. */
+export function buildSprintCompositionSprintViewFromOutput(
+  output: GetSprintOutput
+): SprintCompositionSprintView {
+  return buildSprintCompositionSprintView(output.sprintId, output.sprint, output.integrityNotes);
+}
+
+/* ------------------------------------------------------------------ *
+ * Form: explicit identities, proportionate consent, one typed request
+ * ------------------------------------------------------------------ */
+
+/**
+ * Which identity a field names. Every action selects its identities explicitly:
+ * there is no implicit "current sprint", "next sprint", or "selected task".
+ */
+export type SprintCompositionFieldKind =
+  | 'sprint-id'
+  | 'source-sprint-id'
+  | 'target-sprint-id'
+  | 'backlog-item-id'
+  | 'task-id'
+  | 'text'
+  | 'date'
+  | 'hours'
+  | 'minutes'
+  | 'priority';
+
+export interface SprintCompositionFormField {
+  id: string;
+  label: string;
+  kind: SprintCompositionFieldKind;
+  required: boolean;
+}
+
+const SPRINT_COMPOSITION_FIELDS: Readonly<
+  Record<SprintCompositionAction, readonly SprintCompositionFormField[]>
+> = {
+  createSprint: [
+    { id: 'name', label: 'Sprint name', kind: 'text', required: true },
+    { id: 'start', label: 'Start date', kind: 'date', required: true },
+    { id: 'end', label: 'End date', kind: 'date', required: true },
+    { id: 'goal', label: 'Goal', kind: 'text', required: false },
+    { id: 'hours', label: 'Capacity hours', kind: 'hours', required: false },
+  ],
+  renameSprint: [
+    { id: 'sprintId', label: 'Sprint', kind: 'sprint-id', required: true },
+    { id: 'name', label: 'New sprint name', kind: 'text', required: true },
+  ],
+  addSprintWorkFromBacklog: [
+    { id: 'sprintId', label: 'Sprint', kind: 'sprint-id', required: true },
+    { id: 'backlogItemId', label: 'Backlog item', kind: 'backlog-item-id', required: true },
+    { id: 'estimate', label: 'Estimate hours', kind: 'hours', required: true },
+    {
+      id: 'expectedRuntimeMinutes',
+      label: 'Expected runtime minutes',
+      kind: 'minutes',
+      required: false,
+    },
+    { id: 'priority', label: 'Priority', kind: 'priority', required: false },
+  ],
+  removeSprintTask: [
+    { id: 'sprintId', label: 'Sprint', kind: 'sprint-id', required: true },
+    { id: 'taskId', label: 'Task', kind: 'task-id', required: true },
+  ],
+  migrateSprintTask: [
+    { id: 'taskId', label: 'Task', kind: 'task-id', required: true },
+    { id: 'sourceSprintId', label: 'Source sprint', kind: 'source-sprint-id', required: true },
+    { id: 'targetSprintId', label: 'Target sprint', kind: 'target-sprint-id', required: true },
+  ],
+};
+
+export function sprintCompositionFormFields(
+  action: SprintCompositionAction
+): readonly SprintCompositionFormField[] {
+  return SPRINT_COMPOSITION_FIELDS[action];
+}
+
+export const SPRINT_COMPOSITION_CONSENT_LABELS: Readonly<
+  Record<keyof SprintCompositionConsentState, string>
+> = {
+  hostExecution: 'Poetic runs as my host user in the repository shown above.',
+  managedPlanningMutation: 'This mutates managed planning state that Poetic owns.',
+  automaticCommitAndPush:
+    "Poetic's built-in managed sync commits and pushes these planning changes.",
+  selectedRepositoryAndBranch: 'I mean this repository path and this branch.',
+  newIdentityCreation: 'A new Poetic-minted id will exist after this action.',
+  sprintMembershipChange: 'This changes which sprint holds the task.',
+};
+
+/** The consent lines an action requires; nothing more is asked for. */
+export function sprintCompositionRequiredConsentKeys(
+  action: SprintCompositionAction
+): Array<keyof SprintCompositionConsentState> {
+  const keys: Array<keyof SprintCompositionConsentState> = [
+    'hostExecution',
+    'managedPlanningMutation',
+    'automaticCommitAndPush',
+    'selectedRepositoryAndBranch',
+  ];
+  if (requiresNewIdentityConsent(action)) keys.push('newIdentityCreation');
+  if (requiresMembershipConsent(action)) keys.push('sprintMembershipChange');
+  return keys;
+}
+
+export interface SprintCompositionConfirmation {
+  action: SprintCompositionAction;
+  /** The product label. Never "attach existing task". */
+  title: string;
+  /** What the command is asked to do, from BPAU-03's effect copy. */
+  effect: string;
+  /** Extra disclosures, present only where the effect earns them. */
+  disclosures: readonly string[];
+  requiredConsentKeys: ReadonlyArray<keyof SprintCompositionConsentState>;
+  /** True when the action changes which sprint holds a task. */
+  crossSprint: boolean;
+}
+
+const CROSS_SPRINT_DISCLOSURES: Readonly<Partial<Record<SprintCompositionAction, string[]>>> = {
+  removeSprintTask: [
+    'The task leaves this sprint. It stops counting toward this sprint capacity and is scheduled in no sprint until you add it to one.',
+    'Poetic keeps the task file. BB cannot read the sprint id recorded inside the task file, so a stale reference there would not be visible here.',
+  ],
+  migrateSprintTask: [
+    'The task leaves the source sprint and joins the target sprint. Both sprint capacities change, and Poetic resets the task status to todo.',
+    'A mid-flight failure can leave the task listed by both sprints. BB reports what the sprint rereads say and repairs nothing.',
+  ],
+  addSprintWorkFromBacklog: [
+    'Poetic creates a new task from the backlog item and attaches it to the sprint you named. The backlog item itself is not moved.',
+    'Poetic creates the task file before attaching it and has no rollback, so a created-but-unattached task is possible and is reported as such.',
+  ],
+};
+
+/**
+ * Build the confirmation for one action. Create and rename stay proportionate:
+ * they carry the effect copy and nothing more, because neither changes which
+ * sprint holds a task.
+ */
+export function buildSprintCompositionConfirmation(
+  action: SprintCompositionAction
+): SprintCompositionConfirmation {
+  return {
+    action,
+    title: SPRINT_COMPOSITION_LABELS[action],
+    effect: SPRINT_COMPOSITION_EFFECT_COPY[action],
+    disclosures: (CROSS_SPRINT_DISCLOSURES[action] ?? []).map(truncateLine),
+    requiredConsentKeys: sprintCompositionRequiredConsentKeys(action),
+    crossSprint: requiresMembershipConsent(action),
+  };
+}
+
+/** The repository and project identity the request is bound to. */
+export interface SprintCompositionSelection {
+  projectId: string;
+  sourceId: string;
+  repositoryPath: string;
+  branch: string | null;
+}
+
+/**
+ * Form values as the operator left them. Every value is the raw string the
+ * control holds; an empty optional string is omitted from the request rather
+ * than sent as a default.
+ */
+export type SprintCompositionDraft =
+  | {
+      action: 'createSprint';
+      name: string;
+      start: string;
+      end: string;
+      goal: string;
+      hours: string;
+    }
+  | { action: 'renameSprint'; sprintId: string; name: string }
+  | {
+      action: 'addSprintWorkFromBacklog';
+      sprintId: string;
+      backlogItemId: string;
+      estimate: string;
+      expectedRuntimeMinutes: string;
+      priority: string;
+    }
+  | { action: 'removeSprintTask'; sprintId: string; taskId: string }
+  | {
+      action: 'migrateSprintTask';
+      taskId: string;
+      sourceSprintId: string;
+      targetSprintId: string;
+    };
+
+/**
+ * Canonical evidence the form reads. Nothing here is optional-with-a-default:
+ * a missing projection makes the affected control refuse rather than guess.
+ */
+export interface SprintCompositionCanonicalEvidence {
+  sprints: ListSprintsOutput;
+  /** The sprint the action names; the target sprint for a migration. */
+  sprint: GetSprintOutput | null;
+  /** The source sprint for a migration. */
+  sourceSprint: GetSprintOutput | null;
+}
+
+export type SprintCompositionDraftRefusalReason =
+  | 'incomplete'
+  | 'incomplete-consent'
+  | 'invalid-value'
+  | 'ambiguous-target'
+  | 'stale-membership';
+
+export type SprintCompositionRequestDraft =
+  | { state: 'ready'; request: ApplySprintCompositionInput }
+  | {
+      state: 'refused';
+      reason: SprintCompositionDraftRefusalReason;
+      message: string;
+      /** Field ids the operator still has to resolve, when applicable. */
+      fieldIds: readonly string[];
+    };
+
+type SprintCompositionDraftValues = Readonly<Record<string, string>>;
+
+function trimmedDraftValues(draft: SprintCompositionDraft): SprintCompositionDraftValues {
+  const values: Record<string, string> = {};
+  for (const [key, value] of Object.entries(draft)) {
+    if (key === 'action') continue;
+    values[key] = typeof value === 'string' ? value.trim() : '';
+  }
+  return values;
+}
+
+/** An absent field reads as empty text, never as `undefined`. */
+function draftValue(values: SprintCompositionDraftValues, fieldId: string): string {
+  return values[fieldId] ?? '';
+}
+
+function missingRequiredFieldIds(draft: SprintCompositionDraft): string[] {
+  const values = trimmedDraftValues(draft);
+  return sprintCompositionFormFields(draft.action)
+    .filter((field) => field.required && draftValue(values, field.id).length === 0)
+    .map((field) => field.id);
+}
+
+/** Optional numeric fields: an empty value is omitted, a bad value is refused. */
+function optionalNumber(value: string): number | undefined | 'invalid' {
+  if (value.length === 0) return undefined;
+  const parsed = Number(value);
+  return Number.isFinite(parsed) ? parsed : 'invalid';
+}
+
+function draftInput(
+  draft: SprintCompositionDraft
+): { input: Record<string, unknown> } | { invalidFieldIds: string[] } {
+  const values = trimmedDraftValues(draft);
+  const invalidFieldIds: string[] = [];
+  const optional = (fieldId: string): number | undefined => {
+    const parsed = optionalNumber(draftValue(values, fieldId));
+    if (parsed === 'invalid') {
+      invalidFieldIds.push(fieldId);
+      return undefined;
+    }
+    return parsed;
+  };
+
+  let input: Record<string, unknown>;
+  switch (draft.action) {
+    case 'createSprint': {
+      const hours = optional('hours');
+      const goal = draftValue(values, 'goal');
+      input = {
+        name: draftValue(values, 'name'),
+        start: draftValue(values, 'start'),
+        end: draftValue(values, 'end'),
+        ...(goal.length > 0 ? { goal } : {}),
+        ...(hours === undefined ? {} : { hours }),
+      };
+      break;
+    }
+    case 'renameSprint':
+      input = { sprintId: draftValue(values, 'sprintId'), name: draftValue(values, 'name') };
+      break;
+    case 'addSprintWorkFromBacklog': {
+      const estimate = Number(draftValue(values, 'estimate'));
+      if (!Number.isFinite(estimate)) invalidFieldIds.push('estimate');
+      const runtime = optional('expectedRuntimeMinutes');
+      const priority = draftValue(values, 'priority');
+      input = {
+        sprintId: draftValue(values, 'sprintId'),
+        backlogItemId: draftValue(values, 'backlogItemId'),
+        estimate,
+        ...(runtime === undefined ? {} : { expectedRuntimeMinutes: runtime }),
+        ...(priority.length > 0 ? { priority } : {}),
+      };
+      break;
+    }
+    case 'removeSprintTask':
+      input = { sprintId: draftValue(values, 'sprintId'), taskId: draftValue(values, 'taskId') };
+      break;
+    case 'migrateSprintTask':
+      input = {
+        taskId: draftValue(values, 'taskId'),
+        sourceSprintId: draftValue(values, 'sourceSprintId'),
+        targetSprintId: draftValue(values, 'targetSprintId'),
+      };
+      break;
+  }
+  return invalidFieldIds.length > 0 ? { invalidFieldIds } : { input };
+}
+
+function membershipEvidence(
+  sprint: GetSprintOutput | null,
+  sprintId: string
+): SprintCompositionEvidence<SprintStatusEnvelope> | null {
+  if (sprint === null || sprint.sprintId !== sprintId) return null;
+  return sprint.sprint;
+}
+
+/**
+ * Refuse a target BB cannot pin to canonical evidence, and a membership
+ * observation that no longer matches Poetic's own membership.
+ *
+ * A sprint id absent from the published sprint list is ambiguous, not simply
+ * wrong: BB will not submit a mutation against an identity Poetic has not
+ * confirmed. An unavailable list is ambiguous for the same reason.
+ */
+function targetRefusal(
+  draft: SprintCompositionDraft,
+  evidence: SprintCompositionCanonicalEvidence
+): { reason: SprintCompositionDraftRefusalReason; message: string; fieldIds: string[] } | null {
+  const values = trimmedDraftValues(draft);
+  const list = evidence.sprints.sprints;
+  const knownSprintIds = list.state === 'available' ? list.value.sprints.map((s) => s.id) : null;
+
+  const sprintFields = sprintCompositionFormFields(draft.action).filter(
+    (field) =>
+      field.kind === 'sprint-id' ||
+      field.kind === 'source-sprint-id' ||
+      field.kind === 'target-sprint-id'
+  );
+  for (const field of sprintFields) {
+    const sprintId = draftValue(values, field.id);
+    if (knownSprintIds === null) {
+      return {
+        reason: 'ambiguous-target',
+        message: `Poetic did not publish a sprint list (${list.state === 'unavailable' ? list.reason : UNAVAILABLE}), so BB cannot confirm sprint ${sprintId} and will not submit.`,
+        fieldIds: [field.id],
+      };
+    }
+    if (!knownSprintIds.includes(sprintId)) {
+      return {
+        reason: 'ambiguous-target',
+        message: `Poetic does not list sprint ${sprintId}, so the ${field.label.toLowerCase()} is ambiguous and BB will not submit.`,
+        fieldIds: [field.id],
+      };
+    }
+  }
+
+  if (
+    draft.action === 'migrateSprintTask' &&
+    draftValue(values, 'sourceSprintId') === draftValue(values, 'targetSprintId')
+  ) {
+    return {
+      reason: 'ambiguous-target',
+      message:
+        'The source sprint and the target sprint are the same sprint, so there is no migration to perform.',
+      fieldIds: ['sourceSprintId', 'targetSprintId'],
+    };
+  }
+
+  if (draft.action === 'removeSprintTask' || draft.action === 'migrateSprintTask') {
+    const isRemove = draft.action === 'removeSprintTask';
+    const sprintId = draftValue(values, isRemove ? 'sprintId' : 'sourceSprintId');
+    const taskId = draftValue(values, 'taskId');
+    const sprint = isRemove
+      ? membershipEvidence(evidence.sprint, sprintId)
+      : membershipEvidence(evidence.sourceSprint, sprintId);
+    const fieldIds = isRemove ? ['taskId'] : ['taskId', 'sourceSprintId'];
+    if (sprint === null || sprint.state !== 'available') {
+      return {
+        reason: 'stale-membership',
+        message: `BB has no canonical membership for sprint ${sprintId}${sprint !== null && sprint.state === 'unavailable' ? ` (${sprint.reason})` : ''}, so it will not submit a membership change it cannot confirm.`,
+        fieldIds,
+      };
+    }
+    const state = sprintMembershipState(sprint.value, taskId);
+    if (state !== 'present') {
+      return {
+        reason: 'stale-membership',
+        message:
+          state === 'missing-reference'
+            ? `Sprint ${sprintId} references task ${taskId} as a task id with no resolvable task file, so BB will not submit.`
+            : `Poetic does not list task ${taskId} as a member of sprint ${sprintId}, so the membership you are looking at is stale.`,
+        fieldIds,
+      };
+    }
+  }
+  return null;
+}
+
+/** Membership as last read, so BPAU-03 can refuse a drifted submission. */
+function observedMembership(
+  draft: SprintCompositionDraft,
+  evidence: SprintCompositionCanonicalEvidence
+): string[] {
+  const values = trimmedDraftValues(draft);
+  if (draft.action === 'removeSprintTask') {
+    const sprint = membershipEvidence(evidence.sprint, draftValue(values, 'sprintId'));
+    return sprint !== null && sprint.state === 'available' ? sprintMembershipIds(sprint.value) : [];
+  }
+  if (draft.action === 'migrateSprintTask') {
+    const sprint = membershipEvidence(evidence.sourceSprint, draftValue(values, 'sourceSprintId'));
+    return sprint !== null && sprint.state === 'available' ? sprintMembershipIds(sprint.value) : [];
+  }
+  return [];
+}
+
+/**
+ * Convert a confirmed draft into exactly one typed BPAU-03 request.
+ *
+ * The request is produced by the BPAU-03 schema itself, so this cannot smuggle a
+ * field the lane does not accept, and a value Poetic would refuse is refused
+ * here instead of being sent. Consent conversion is BPAU-03's, so a disabled
+ * submit control and a refused submission always agree.
+ */
+export function buildSprintCompositionRequest(input: {
+  draft: SprintCompositionDraft;
+  consent: SprintCompositionConsentState;
+  selection: SprintCompositionSelection;
+  evidence: SprintCompositionCanonicalEvidence;
+}): SprintCompositionRequestDraft {
+  const { draft, consent, selection, evidence } = input;
+
+  const missing = missingRequiredFieldIds(draft);
+  if (missing.length > 0) {
+    return {
+      state: 'refused',
+      reason: 'incomplete',
+      message: 'Every required identity and value must be selected explicitly before submitting.',
+      fieldIds: missing,
+    };
+  }
+
+  const built = draftInput(draft);
+  if ('invalidFieldIds' in built) {
+    return {
+      state: 'refused',
+      reason: 'invalid-value',
+      message: 'A numeric field does not hold a number, so BB will not submit it.',
+      fieldIds: built.invalidFieldIds,
+    };
+  }
+
+  const ambiguity = targetRefusal(draft, evidence);
+  if (ambiguity !== null) {
+    return {
+      state: 'refused',
+      reason: ambiguity.reason,
+      message: truncateLine(ambiguity.message),
+      fieldIds: ambiguity.fieldIds,
+    };
+  }
+
+  const consentPayload = sprintCompositionConsentPayload(draft.action, consent);
+  if (consentPayload === null) {
+    return {
+      state: 'refused',
+      reason: 'incomplete-consent',
+      message: 'Every consent line this action requires must be acknowledged before submitting.',
+      fieldIds: [],
+    };
+  }
+
+  const candidate = {
+    projectId: selection.projectId,
+    sourceId: selection.sourceId,
+    action: draft.action,
+    input: built.input,
+    consent: consentPayload,
+    expected: {
+      repositoryPath: selection.repositoryPath,
+      branch: selection.branch,
+      entityIds: [] as string[],
+      observedMembership: observedMembership(draft, evidence),
+    },
+  };
+
+  const parsed = applySprintCompositionInputSchema.safeParse(candidate);
+  if (!parsed.success) {
+    return {
+      state: 'refused',
+      reason: 'invalid-value',
+      message: `Poetic's sprint-composition contract refused this input: ${parsed.error.issues[0]?.message ?? 'invalid request'}`,
+      fieldIds: parsed.error.issues.flatMap((issue) =>
+        issue.path.length > 0 ? [String(issue.path[issue.path.length - 1])] : []
+      ),
+    };
+  }
+
+  // The declared identities come from BPAU-03's own derivation, so consent and
+  // the request always name the same entities.
+  const identities = [...new Set(sprintCompositionRequestedIdentities(parsed.data))];
+  const withIdentities = applySprintCompositionInputSchema.safeParse({
+    ...candidate,
+    expected: { ...candidate.expected, entityIds: identities },
+  });
+  if (!withIdentities.success) {
+    return {
+      state: 'refused',
+      reason: 'invalid-value',
+      message: 'The declared identities did not satisfy the sprint-composition contract.',
+      fieldIds: [],
+    };
+  }
+  return { state: 'ready', request: withIdentities.data };
+}
+
+/* ------------------------------------------------------------------ *
+ * Prohibited actions
+ * ------------------------------------------------------------------ */
+
+/**
+ * Controls this lane deliberately does not offer. They are named so a refusal
+ * is explicit rather than a control that silently does nothing.
+ */
+export const SPRINT_COMPOSITION_PROHIBITED_ACTIONS = [
+  'createCustomTask',
+  'completeSprint',
+  'closeSprint',
+  'tidySprint',
+  'unlockSprint',
+  'pruneMissingTasks',
+  'runSprint',
+  'applySprint',
+  'splitTask',
+  'selectProvider',
+  'selectModel',
+  'bulkSchedule',
+  'dragAndDropSchedule',
+  'forceMutation',
+  'dryRun',
+  'suppressSync',
+] as const;
+
+export type SprintCompositionProhibitedAction =
+  (typeof SPRINT_COMPOSITION_PROHIBITED_ACTIONS)[number];
+
+const PROHIBITED_NOTICES: Readonly<Record<SprintCompositionProhibitedAction, string>> = {
+  createCustomTask:
+    'Creating a custom task is a different product and is not offered here. "Add from backlog" creates a task from an existing backlog item.',
+  completeSprint: 'Completing a sprint is not offered here.',
+  closeSprint: 'Closing a sprint is not offered here.',
+  tidySprint: 'Tidying a sprint is not offered here.',
+  unlockSprint: 'Unlocking a sprint is not offered here.',
+  pruneMissingTasks:
+    'Repairing sprint integrity is not offered here. BB reports missing task references and does not prune them.',
+  runSprint: 'Sprint execution is not offered here. This surface only composes sprints.',
+  applySprint: 'Applying sprint results is not offered here.',
+  splitTask: 'Splitting work is not offered here.',
+  selectProvider: 'Provider selection is not offered here.',
+  selectModel: 'Model selection is not offered here.',
+  bulkSchedule:
+    'Bulk scheduling is not offered here. Each action names its own sprint, task, and backlog identities.',
+  dragAndDropSchedule:
+    'Drag-and-drop scheduling is not offered here: presentation never changes before Poetic confirms the change.',
+  forceMutation: 'BB never passes --force.',
+  dryRun: 'BB never passes --dry-run.',
+  suppressSync: "BB never passes --no-sync: Poetic's managed sync always runs.",
+};
+
+export function isSprintCompositionAction(value: string): value is SprintCompositionAction {
+  return (SPRINT_COMPOSITION_VOCABULARY as readonly string[]).includes(value);
+}
+
+/**
+ * Explicit refusal for anything outside the closed vocabulary. A named excluded
+ * control gets its own reason; anything else is refused as out of vocabulary.
+ */
+export function sprintCompositionProhibitedRefusal(
+  requestedAction: string
+): { action: string; message: string } | null {
+  if (isSprintCompositionAction(requestedAction)) return null;
+  const known = (SPRINT_COMPOSITION_PROHIBITED_ACTIONS as readonly string[]).includes(
+    requestedAction
+  );
+  return {
+    action: requestedAction,
+    message: truncateLine(
+      known
+        ? PROHIBITED_NOTICES[requestedAction as SprintCompositionProhibitedAction]
+        : `"${requestedAction}" is not a sprint-composition action, so BB will not submit it.`
+    ),
+  };
+}
+
+/** Every excluded control, as notices for the surface to render. */
+export function sprintCompositionProhibitedNotices(): readonly string[] {
+  return SPRINT_COMPOSITION_PROHIBITED_ACTIONS.map((action) =>
+    truncateLine(PROHIBITED_NOTICES[action])
+  );
+}
+
+/* ------------------------------------------------------------------ *
+ * Outcome presentation
+ * ------------------------------------------------------------------ */
+
+export type SprintCompositionOutcomeState =
+  | 'applied'
+  | 'applied-incomplete'
+  | 'overlap-conflict'
+  | 'refused'
+  | 'partial-effect'
+  | 'unknown';
+
+/**
+ * Overlap recovery as Poetic published it. Recovery is a Poetic CLI action, so
+ * this carries guidance only and offers no BB control.
+ */
+export interface SprintCompositionOverlapRecovery {
+  conflictingSprintId: string | null;
+  guidance: string;
+  /** Recovery is never a BB control. */
+  control: null;
+}
+
+export interface SprintCompositionOutcomeView {
+  action: SprintCompositionAction;
+  actionLabel: string;
+  state: SprintCompositionOutcomeState;
+  headline: string;
+  rows: readonly SprintCompositionRow[];
+  notes: readonly string[];
+  /** Present only for a create that Poetic refused as an overlap. */
+  recovery: SprintCompositionOverlapRecovery | null;
+  /** True when the reported effect is not a clean applied outcome. */
+  degraded: boolean;
+}
+
+const OUTCOME_STATES: Readonly<
+  Record<ApplySprintCompositionOutput['effect']['phase'], SprintCompositionOutcomeState>
+> = {
+  applied: 'applied',
+  'applied-incomplete': 'applied-incomplete',
+  'overlap-conflict': 'overlap-conflict',
+  'refused-before-launch': 'refused',
+  'refused-before-effect': 'refused',
+  'failed-after-partial-effect': 'partial-effect',
+  'unknown-after-timeout': 'unknown',
+};
+
+const OUTCOME_HEADLINES: Readonly<Record<SprintCompositionOutcomeState, string>> = {
+  applied: 'applied',
+  'applied-incomplete': 'applied, with unconfirmed effects',
+  'overlap-conflict': 'refused: sprint dates overlap an existing sprint',
+  refused: 'refused; nothing changed',
+  'partial-effect': 'failed after a partial effect',
+  unknown: 'outcome unknown',
+};
+
+/**
+ * Resulting task status from the authoritative reread only. A status BB could not
+ * reread is unavailable; it is never predicted from the action that just ran.
+ */
+function taskStatusRowValue(
+  evidence: SprintCompositionEvidence<GetTaskDetailOutput> | undefined
+): string {
+  if (evidence === undefined) return UNAVAILABLE;
+  if (evidence.state !== 'available') return `${UNAVAILABLE}: ${evidence.reason}`;
+  const task = evidence.value.task;
+  if (task.state === 'missing') return 'missing';
+  if (task.state === 'unavailable') return `${UNAVAILABLE}: ${task.reason}`;
+  return formatOptional(task.value.status);
+}
+
+function overlapRecovery(
+  outcome: ApplySprintCompositionOutput
+): SprintCompositionOverlapRecovery | null {
+  const identity = outcome.identityOutcome;
+  if (identity === null || identity.kind !== 'sprintCreateV1') return null;
+  if (identity.value.state !== 'overlap-conflict') return null;
+  return {
+    conflictingSprintId: identity.value.conflictingSprintId ?? null,
+    guidance: truncateLine(
+      identity.value.recoveryText ??
+        'Poetic published no recovery text for this overlap. Choose dates that do not overlap the conflicting sprint, or resolve the overlap with the Poetic CLI.'
+    ),
+    control: null,
+  };
+}
+
+function commandNotes(outcome: ApplySprintCompositionOutput): string[] {
+  const notes: string[] = [];
+  switch (outcome.command.state) {
+    case 'timed_out':
+      notes.push(
+        'Poetic did not answer before this action timed out. Nothing was retried, and whether the change applied is unknown until you reread the sprint.'
+      );
+      break;
+    case 'failed':
+      notes.push(
+        `Poetic reported a failure${outcome.command.exitCode === null ? '' : ` (exit ${outcome.command.exitCode})`}${outcome.command.diagnostics === null ? '.' : `: ${outcome.command.diagnostics}`}`
+      );
+      break;
+    case 'ambiguous':
+      notes.push(
+        "Poetic's answer was ambiguous: BB could not establish what changed and reports neither success nor failure."
+      );
+      break;
+    default:
+      break;
+  }
+  // Only the two identity-minting actions publish a BPAU-00B envelope, so a
+  // missing envelope is a gap for those and expected for the other three.
+  if (
+    outcome.identityOutcome === null &&
+    requiresNewIdentityConsent(outcome.action) &&
+    outcome.command.state !== 'failed'
+  ) {
+    notes.push(
+      'Poetic published no structured identity evidence for this action, so BB reports the effect as unconfirmed rather than substituting the newest sprint it can see.'
+    );
+  }
+  if (outcome.sync.state !== 'remote_verified') {
+    notes.push(
+      'A zero exit code is not proof of a remote push. The sync state above is what Poetic reported on a fresh reread.'
+    );
+  }
+  return notes;
+}
+
+/**
+ * Render one BPAU-03 outcome. Every value comes from the outcome record: the
+ * effect phase is reported, never inferred from the exit code, and the resulting
+ * status comes from the authoritative reread rather than from a prediction.
+ */
+export function buildSprintCompositionOutcomeView(
+  outcome: ApplySprintCompositionOutput
+): SprintCompositionOutcomeView {
+  const state = OUTCOME_STATES[outcome.effect.phase];
+  const label = SPRINT_COMPOSITION_LABELS[outcome.action];
+  const rows: SprintCompositionRow[] = [
+    row('outcome-action', 'Action', label),
+    row('outcome-phase', 'Effect', outcome.effect.phase),
+    row(
+      'outcome-created',
+      'Created identities',
+      formatIdentities(outcome.effect.createdIdentities)
+    ),
+    row(
+      'outcome-affected',
+      'Affected identities',
+      formatIdentities(outcome.effect.affectedIdentities)
+    ),
+    row('outcome-requested', 'Requested identities', formatIdentities(outcome.requestedIdentities)),
+    row(
+      'outcome-command',
+      'Poetic command',
+      `${outcome.command.state}, exit ${outcome.command.exitCode === null ? UNAVAILABLE : outcome.command.exitCode}, ${outcome.command.attempts} attempt`
+    ),
+    row(
+      'outcome-sync',
+      'Planning sync',
+      `${outcome.sync.state}${outcome.sync.detail === null ? '' : `: ${outcome.sync.detail}`}`
+    ),
+    row(
+      'outcome-task-status',
+      'Task status (canonical reread)',
+      taskStatusRowValue(outcome.canonicalRereads.task)
+    ),
+  ];
+
+  const identity = outcome.identityOutcome;
+  if (identity !== null && identity.kind === 'sprintAddTaskV1') {
+    rows.push(
+      row(
+        'outcome-add-capacity',
+        'Sprint capacity after add',
+        `${identity.value.capacity.allocatedHours ?? UNAVAILABLE} of ${identity.value.capacity.totalHours ?? UNAVAILABLE} hours (Poetic-reported)`
+      ),
+      row(
+        'outcome-add-estimate',
+        'Estimate applied',
+        `${identity.value.estimatedHours} hours from ${identity.value.estimateSource}`
+      )
+    );
+  }
+
+  const recovery = overlapRecovery(outcome);
+  if (recovery !== null) {
+    rows.push(
+      row(
+        'outcome-conflicting-sprint',
+        'Conflicting sprint',
+        recovery.conflictingSprintId ?? UNAVAILABLE
+      ),
+      row('outcome-recovery', 'Recovery', recovery.guidance)
+    );
+  }
+
+  return {
+    action: outcome.action,
+    actionLabel: label,
+    state,
+    headline: truncateLine(`${label} ${OUTCOME_HEADLINES[state]}`),
+    rows,
+    notes: [...outcome.integrityNotes, ...outcome.syncWarnings, ...commandNotes(outcome)].map(
+      truncateLine
+    ),
+    recovery,
+    degraded: state !== 'applied',
+  };
+}
+
+/* ------------------------------------------------------------------ *
+ * Composed view
+ * ------------------------------------------------------------------ */
+
+/**
+ * Presentation phase.
+ *
+ * `awaiting-poetic` renders the pre-submission evidence unchanged: BB shows no
+ * optimistic membership, capacity, or status while a submission is in flight.
+ */
+export type SprintCompositionPhase =
+  | { kind: 'idle' }
+  | { kind: 'awaiting-poetic'; request: ApplySprintCompositionInput }
+  | { kind: 'settled'; outcome: ApplySprintCompositionOutput };
+
+export interface SprintCompositionSubmitControl {
+  id: 'submit';
+  label: string;
+  enabled: boolean;
+  /** Null only when the control is enabled. */
+  disabledReason: string | null;
+}
+
+export interface SprintCompositionView {
+  viewVersion: typeof SPRINT_COMPOSITION_VIEW_VERSION;
+  outcomeVersion: typeof SPRINT_COMPOSITION_OUTCOME_VERSION;
+  phase: SprintCompositionPhase['kind'];
+  action: SprintCompositionAction;
+  actionLabel: string;
+  headline: string;
+  /** Poetic's own lane disclosure, carried verbatim. */
+  disclosure: typeof SPRINT_COMPOSITION_DISCLOSURE;
+  fields: readonly SprintCompositionFormField[];
+  confirmation: SprintCompositionConfirmation;
+  submit: SprintCompositionSubmitControl;
+  /** The single typed request a confirmed draft would emit; null otherwise. */
+  request: ApplySprintCompositionInput | null;
+  /** Why the draft cannot be submitted, when it cannot. */
+  refusal: Extract<SprintCompositionRequestDraft, { state: 'refused' }> | null;
+  sprints: SprintCompositionListView;
+  sprint: SprintCompositionSprintView | null;
+  sourceSprint: SprintCompositionSprintView | null;
+  outcome: SprintCompositionOutcomeView | null;
+  /** True while BB is waiting for Poetic's reread. */
+  awaitingCanonicalReread: boolean;
+  notes: readonly string[];
+  prohibited: readonly string[];
+}
+
+export interface SprintCompositionViewInput {
+  phase: SprintCompositionPhase;
+  selection: SprintCompositionSelection;
+  draft: SprintCompositionDraft;
+  consent: SprintCompositionConsentState;
+  evidence: SprintCompositionCanonicalEvidence;
+  /** True when a submission for this scope is already in flight. */
+  submissionInFlight?: boolean;
+}
+
+function sprintViewFor(output: GetSprintOutput | null): SprintCompositionSprintView | null {
+  return output === null ? null : buildSprintCompositionSprintViewFromOutput(output);
+}
+
+/**
+ * Sprint views after a settled submission come from the outcome's own rereads,
+ * which are the authority for the resulting composition. A member the reread
+ * could not supply stays explicitly unavailable.
+ */
+function settledSprintViews(outcome: ApplySprintCompositionOutput): {
+  sprint: SprintCompositionSprintView | null;
+  sourceSprint: SprintCompositionSprintView | null;
+} {
+  const rereads = outcome.canonicalRereads;
+  const primary = rereads.targetSprint ?? rereads.sprint;
+  const primaryId =
+    primary !== undefined && primary.state === 'available' ? primary.value.sprintId : UNAVAILABLE;
+  const sourceId =
+    rereads.sourceSprint !== undefined && rereads.sourceSprint.state === 'available'
+      ? rereads.sourceSprint.value.sprintId
+      : UNAVAILABLE;
+  return {
+    sprint: primary === undefined ? null : buildSprintCompositionSprintView(primaryId, primary),
+    sourceSprint:
+      rereads.sourceSprint === undefined
+        ? null
+        : buildSprintCompositionSprintView(sourceId, rereads.sourceSprint),
+  };
+}
+
+/**
+ * Build the whole sprint-composition surface for one phase.
+ *
+ * Deterministic in its inputs: the same evidence and draft always render the
+ * same view, and no field is derived from anything other than those inputs.
+ */
+export function buildSprintCompositionView(
+  input: SprintCompositionViewInput
+): SprintCompositionView {
+  const { phase, draft, consent, selection, evidence } = input;
+  const action = draft.action;
+  const label = SPRINT_COMPOSITION_LABELS[action];
+  const inFlight = input.submissionInFlight === true || phase.kind === 'awaiting-poetic';
+
+  const draftResult = buildSprintCompositionRequest({ draft, consent, selection, evidence });
+  const refusal = draftResult.state === 'refused' ? draftResult : null;
+
+  const disabledReason = inFlight
+    ? 'A sprint-composition submission is already in flight for this action. BB submits it once and waits for Poetic.'
+    : (refusal?.message ?? null);
+
+  const listView = buildSprintListView(evidence.sprints);
+  const settled = phase.kind === 'settled' ? settledSprintViews(phase.outcome) : null;
+  const outcomeView =
+    phase.kind === 'settled' ? buildSprintCompositionOutcomeView(phase.outcome) : null;
+
+  const notes: string[] = [];
+  if (phase.kind === 'awaiting-poetic') {
+    notes.push(
+      'Waiting for Poetic. The composition shown below is the evidence read before this submission; nothing changes until Poetic answers and BB rereads.'
+    );
+  }
+  if (settled !== null) {
+    notes.push(
+      'The composition shown below comes from the reread Poetic answered with after this action.'
+    );
+    if (settled.sprint === null && settled.sourceSprint === null) {
+      notes.push(
+        'Poetic supplied no sprint reread for this action, so the resulting composition is unavailable.'
+      );
+    }
+  }
+
+  return {
+    viewVersion: SPRINT_COMPOSITION_VIEW_VERSION,
+    outcomeVersion: SPRINT_COMPOSITION_OUTCOME_VERSION,
+    phase: phase.kind,
+    action,
+    actionLabel: label,
+    headline:
+      outcomeView !== null
+        ? outcomeView.headline
+        : phase.kind === 'awaiting-poetic'
+          ? `${label}: waiting for Poetic`
+          : `${label}: review and confirm`,
+    disclosure: SPRINT_COMPOSITION_DISCLOSURE,
+    fields: sprintCompositionFormFields(action),
+    confirmation: buildSprintCompositionConfirmation(action),
+    submit: {
+      id: 'submit',
+      label,
+      enabled: disabledReason === null,
+      disabledReason,
+    },
+    request: phase.kind === 'idle' && draftResult.state === 'ready' ? draftResult.request : null,
+    refusal,
+    sprints: listView,
+    sprint: settled === null ? sprintViewFor(evidence.sprint) : settled.sprint,
+    sourceSprint: settled === null ? sprintViewFor(evidence.sourceSprint) : settled.sourceSprint,
+    outcome: outcomeView,
+    awaitingCanonicalReread: phase.kind === 'awaiting-poetic',
+    notes: notes.map(truncateLine),
+    prohibited: sprintCompositionProhibitedNotices(),
+  };
+}