@poetic-ai/poetic 1.42.0

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

@@ -0,0 +1,714 @@
+/**
+ * Pure sprint-composition semantics for BPAU-03: fixed argv, consent conversion,
+ * process-local admission, effect-phase decisions, and sync disclosure.
+ *
+ * Nothing here spawns a process, reads the filesystem, or touches the network.
+ * The service owns execution; this module owns the decisions so a disabled
+ * control and a refused submission always agree, and so effect phases are
+ * reported rather than inferred by a consumer from an exit code.
+ *
+ * No capacity, readiness, or membership number is ever recomputed here.
+ */
+
+import type { PlanningWorkspaceProjection } from './planning-service.js';
+import type { SprintMembershipState } from './sprint-composition-readback.js';
+import {
+  type ApplySprintCompositionInput,
+  SPRINT_COMPOSITION_MEMBERSHIP_ACTIONS,
+  SPRINT_COMPOSITION_NEW_IDENTITY_ACTIONS,
+  type SprintAddTaskEnvelope,
+  type SprintCompositionAction,
+  type SprintCompositionEffectPhase,
+  type SprintCompositionEvidence,
+  type SprintCompositionSyncState,
+  type SprintCreateEnvelope,
+} from './sprint-composition-schema.js';
+
+/** Mutation timeout, matching the shipped adapter's mutation budget. */
+export const SPRINT_COMPOSITION_MUTATION_TIMEOUT_MS = 120_000;
+
+/** Read timeout for the canonical sprint/task/backlog reads. */
+export const SPRINT_COMPOSITION_READ_TIMEOUT_MS = 15_000;
+
+/** Captured stdout/stderr cap per invocation. */
+export const SPRINT_COMPOSITION_MAX_OUTPUT_BYTES = 4 * 1024 * 1024;
+
+/** Diagnostics cap; diagnostics are scoped to the current invocation only. */
+export const SPRINT_COMPOSITION_MAX_DIAGNOSTICS_CHARS = 2_000;
+
+/**
+ * Lane disclosure. Sprint composition mutates managed planning state and lets
+ * Poetic's managed sync commit and push; it never launches Fusion, never starts
+ * tracked backlog execution, never opens a pull request, never cancels a run,
+ * and never performs a task lifecycle transition.
+ */
+export const SPRINT_COMPOSITION_DISCLOSURE = {
+  fullTrust: true,
+  hostEquivalentExecution: true,
+  providerAuth: 'native',
+  planningSync: true,
+  gitCommits: true,
+  gitPush: true,
+  managedPlanningMutation: true,
+  pullRequestCreation: false,
+  fusionLaunch: false,
+  trackedBacklogExecution: false,
+  runCancellation: false,
+  taskLifecycleTransition: false,
+  summary:
+    "Sprint composition runs the installed Poetic plan-sprint commands as your host user in the selected repository and branch. It mutates managed planning state, and Poetic's built-in managed sync commits and pushes those planning changes. Adding work from the backlog creates a new Poetic task from an existing backlog item; removing a task detaches it and does not delete it; migrating a task keeps the task id, moves membership, and resets the task status to todo. It does not create custom tasks, split work, choose providers or models, launch execution, complete or close sprints, or repair sprint integrity. BB never passes --no-sync, --force, or --dry-run.",
+} as const;
+
+/** Product labels. "Add from backlog" is never "attach existing task". */
+export const SPRINT_COMPOSITION_LABELS: Readonly<Record<SprintCompositionAction, string>> = {
+  createSprint: 'Create sprint',
+  renameSprint: 'Rename sprint',
+  addSprintWorkFromBacklog: 'Add from backlog',
+  removeSprintTask: 'Remove task from sprint',
+  migrateSprintTask: 'Move task to another sprint',
+};
+
+/**
+ * Effect copy the operator must see before consenting. Each line names the
+ * source task/sprint and target sprint explicitly where one exists.
+ */
+export const SPRINT_COMPOSITION_EFFECT_COPY: Readonly<Record<SprintCompositionAction, string>> = {
+  createSprint: 'Creates a new sprint with a new Poetic-minted sprint id.',
+  renameSprint:
+    'Changes the sprint name only. The sprint id does not change, so the visible label and the id diverge.',
+  addSprintWorkFromBacklog:
+    'Creates a new Poetic task from the named backlog item and attaches it to the named sprint. The task description is a copy of the backlog body; later backlog edits do not propagate.',
+  removeSprintTask:
+    'Detaches the named task from the named sprint. The task file is kept and is not deleted.',
+  migrateSprintTask:
+    'Moves the named task from the named source sprint to the named target sprint. The task id is kept and the task status is reset to todo.',
+};
+
+export function requiresNewIdentityConsent(action: SprintCompositionAction): boolean {
+  return (SPRINT_COMPOSITION_NEW_IDENTITY_ACTIONS as readonly SprintCompositionAction[]).includes(
+    action
+  );
+}
+
+export function requiresMembershipConsent(action: SprintCompositionAction): boolean {
+  return (SPRINT_COMPOSITION_MEMBERSHIP_ACTIONS as readonly SprintCompositionAction[]).includes(
+    action
+  );
+}
+
+/** Consent checkboxes exactly as the operator left them; plain booleans. */
+export interface SprintCompositionConsentState {
+  hostExecution: boolean;
+  managedPlanningMutation: boolean;
+  automaticCommitAndPush: boolean;
+  selectedRepositoryAndBranch: boolean;
+  /** Required for createSprint and addSprintWorkFromBacklog. */
+  newIdentityCreation: boolean;
+  /** Required for addSprintWorkFromBacklog, removeSprintTask, migrateSprintTask. */
+  sprintMembershipChange: boolean;
+}
+
+export const EMPTY_SPRINT_COMPOSITION_CONSENT: Readonly<SprintCompositionConsentState> = {
+  hostExecution: false,
+  managedPlanningMutation: false,
+  automaticCommitAndPush: false,
+  selectedRepositoryAndBranch: false,
+  newIdentityCreation: false,
+  sprintMembershipChange: false,
+};
+
+/**
+ * Convert collected consent into the exact literal shape the request schema
+ * requires, or null when the acknowledgement is incomplete. Returning null is the
+ * enforcement point: a caller cannot build a request without full consent.
+ */
+export function sprintCompositionConsentPayload(
+  action: SprintCompositionAction,
+  consent: SprintCompositionConsentState
+): ApplySprintCompositionInput['consent'] | null {
+  if (
+    !consent.hostExecution ||
+    !consent.managedPlanningMutation ||
+    !consent.automaticCommitAndPush ||
+    !consent.selectedRepositoryAndBranch
+  ) {
+    return null;
+  }
+  const base = {
+    hostExecution: true,
+    managedPlanningMutation: true,
+    automaticCommitAndPush: true,
+    selectedRepositoryAndBranch: true,
+  } as const;
+  const needsIdentity = requiresNewIdentityConsent(action);
+  const needsMembership = requiresMembershipConsent(action);
+  if (needsIdentity && !consent.newIdentityCreation) return null;
+  if (needsMembership && !consent.sprintMembershipChange) return null;
+  if (needsIdentity && needsMembership) {
+    return { ...base, newIdentityCreation: true, sprintMembershipChange: true };
+  }
+  if (needsIdentity) return { ...base, newIdentityCreation: true };
+  if (needsMembership) return { ...base, sprintMembershipChange: true };
+  return base;
+}
+
+/**
+ * Fixed argv per action. Every optional value uses the single-token
+ * `--flag=value` form, so a value beginning with a dash can never be parsed as
+ * another option and `--` is never needed. Nothing beyond the frozen tokens can
+ * reach the child process: no `--no-sync`, `--force`, `--dry-run`, `--verbose`,
+ * `--split`, `--splitter`, `--provider`, `--model`, or `--hint`.
+ *
+ * `--json` is appended only on the two BPAU-00B identity commands.
+ */
+export function sprintCompositionArgv(request: ApplySprintCompositionInput): string[] {
+  switch (request.action) {
+    case 'createSprint': {
+      const argv = [
+        'plan',
+        'sprint',
+        'create',
+        `--name=${request.input.name}`,
+        `--start=${request.input.start}`,
+        `--end=${request.input.end}`,
+      ];
+      if (request.input.goal !== undefined) argv.push(`--goal=${request.input.goal}`);
+      if (request.input.hours !== undefined) argv.push(`--hours=${request.input.hours}`);
+      argv.push('--json');
+      return argv;
+    }
+    case 'renameSprint':
+      return ['plan', 'sprint', 'rename', request.input.sprintId, request.input.name];
+    case 'addSprintWorkFromBacklog': {
+      const argv = [
+        'plan',
+        'sprint',
+        'add-task',
+        request.input.sprintId,
+        request.input.backlogItemId,
+        `--estimate=${request.input.estimate}`,
+      ];
+      if (request.input.expectedRuntimeMinutes !== undefined) {
+        argv.push(`--expected-runtime=${request.input.expectedRuntimeMinutes}`);
+      }
+      if (request.input.priority !== undefined) {
+        argv.push(`--priority=${request.input.priority}`);
+      }
+      argv.push('--json');
+      return argv;
+    }
+    case 'removeSprintTask':
+      return ['plan', 'sprint', 'remove-task', request.input.sprintId, request.input.taskId];
+    case 'migrateSprintTask':
+      // The source sprint is deliberately absent from argv: Poetic derives it.
+      // BB carries it for consent, admission, and the reread only.
+      return ['plan', 'sprint', 'migrate-task', request.input.taskId, request.input.targetSprintId];
+  }
+}
+
+/** Managed identities the request names, for `requestedIdentities`. */
+export function sprintCompositionRequestedIdentities(
+  request: ApplySprintCompositionInput
+): string[] {
+  switch (request.action) {
+    case 'createSprint':
+      return [];
+    case 'renameSprint':
+      return [request.input.sprintId];
+    case 'addSprintWorkFromBacklog':
+      return [request.input.sprintId, request.input.backlogItemId];
+    case 'removeSprintTask':
+      return [request.input.sprintId, request.input.taskId];
+    case 'migrateSprintTask':
+      return [request.input.taskId, request.input.sourceSprintId, request.input.targetSprintId];
+  }
+}
+
+export type SprintCompositionAdmissionScope = {
+  repositoryPath: string;
+  /** `create:sprint` for creates; otherwise the managed entity being changed. */
+  identity: string;
+  family: 'sprint-composition';
+};
+
+/**
+ * Process-local admission for sprint composition. Refuses overlapping
+ * submissions for the same repository path and identity inside this plugin
+ * process only. It is admission, not cross-process ownership, not a file lock,
+ * and not Poetic-side exclusivity.
+ */
+export class ProcessLocalSprintCompositionAdmission {
+  private readonly claims = new Set<string>();
+
+  private scopeKey(scope: SprintCompositionAdmissionScope): string {
+    return `${scope.repositoryPath}\0${scope.identity}\0${scope.family}`;
+  }
+
+  /**
+   * Claim exclusive process-local admission. Returns a release function that is
+   * safe to call more than once, and that the service calls on every terminal
+   * path including refusal and reread failure.
+   */
+  claim(scope: SprintCompositionAdmissionScope): () => void {
+    const key = this.scopeKey(scope);
+    if (this.claims.has(key)) {
+      throw new Error(
+        `A BB sprint-composition action is already in progress for ${scope.identity} in this repository. Process-local admission refuses overlapping submissions; this is not cross-process ownership.`
+      );
+    }
+    this.claims.add(key);
+    let released = false;
+    return () => {
+      if (released) return;
+      released = true;
+      this.claims.delete(key);
+    };
+  }
+
+  isBusy(scope: SprintCompositionAdmissionScope): boolean {
+    return this.claims.has(this.scopeKey(scope));
+  }
+}
+
+/** Admission identity: creates are scoped by kind, everything else by entity. */
+export function sprintCompositionAdmissionIdentity(request: ApplySprintCompositionInput): string {
+  switch (request.action) {
+    case 'createSprint':
+      return 'create:sprint';
+    case 'renameSprint':
+    case 'addSprintWorkFromBacklog':
+      return request.input.sprintId;
+    case 'removeSprintTask':
+    case 'migrateSprintTask':
+      return request.input.taskId;
+  }
+}
+
+/**
+ * True when the caller's observed membership no longer matches Poetic's fresh
+ * membership. An empty observation is "not observed" and never reads as drift.
+ */
+export function membershipDrifted(observed: readonly string[], fresh: readonly string[]): boolean {
+  if (observed.length === 0) return false;
+  if (observed.length !== fresh.length) return true;
+  const freshSet = new Set(fresh);
+  return observed.some((id) => !freshSet.has(id));
+}
+
+/** Facts about the single invocation the effect deciders need. */
+export interface SprintCompositionInvocationFacts {
+  timedOut: boolean;
+  exitCode: number | null;
+}
+
+export interface SprintCompositionEffectDecision {
+  phase: SprintCompositionEffectPhase;
+  createdIdentities: string[];
+  affectedIdentities: string[];
+  integrityNotes: string[];
+}
+
+/**
+ * Create: `overlap-conflict` stays a distinct phase carrying the conflicting
+ * sprint id and Poetic's recovery text, never a generic failure. Recovery is a
+ * CLI action, not a BB control.
+ */
+export function decideCreateSprintEffect(
+  identity: SprintCreateEnvelope | null,
+  facts: SprintCompositionInvocationFacts
+): SprintCompositionEffectDecision {
+  if (identity === null) {
+    // Without usable identity evidence BB cannot claim the sprint exists and
+    // cannot claim nothing happened: a zero exit stays explicitly incomplete.
+    return {
+      phase: facts.timedOut
+        ? 'unknown-after-timeout'
+        : facts.exitCode === 0
+          ? 'applied-incomplete'
+          : 'refused-before-effect',
+      createdIdentities: [],
+      affectedIdentities: [],
+      integrityNotes: [
+        facts.timedOut
+          ? 'Poetic did not answer before the sprint create timeout; whether a sprint exists is unknown.'
+          : 'Poetic returned no usable sprintCreateV1 identity evidence for this create.',
+      ],
+    };
+  }
+  switch (identity.state) {
+    case 'created':
+      return {
+        phase: 'applied',
+        createdIdentities: identity.sprintId === null ? [] : [identity.sprintId],
+        affectedIdentities: identity.sprintId === null ? [] : [identity.sprintId],
+        integrityNotes: [],
+      };
+    case 'overlap-conflict':
+      return {
+        phase: 'overlap-conflict',
+        createdIdentities: [],
+        affectedIdentities:
+          identity.conflictingSprintId === undefined ? [] : [identity.conflictingSprintId],
+        integrityNotes: [],
+      };
+    case 'refused-invalid':
+      return {
+        phase: 'refused-before-effect',
+        createdIdentities: [],
+        affectedIdentities: [],
+        integrityNotes: [],
+      };
+  }
+}
+
+/**
+ * Rename has no identity envelope from BPAU-00B, so exit evidence plus the
+ * sprint reread is all there is. A completed sprint is read-only, which Poetic
+ * reports as a nonzero exit.
+ */
+export function decideRenameSprintEffect(
+  sprintId: string,
+  facts: SprintCompositionInvocationFacts,
+  renamedInReread: boolean | null
+): SprintCompositionEffectDecision {
+  if (facts.timedOut) {
+    return {
+      phase: 'unknown-after-timeout',
+      createdIdentities: [],
+      affectedIdentities: [sprintId],
+      integrityNotes: [
+        `Poetic did not answer before the rename timeout; whether sprint ${sprintId} was renamed is unknown.`,
+      ],
+    };
+  }
+  if (facts.exitCode !== 0) {
+    return {
+      phase: 'refused-before-effect',
+      createdIdentities: [],
+      affectedIdentities: [],
+      integrityNotes: [],
+    };
+  }
+  const notes = [
+    `Poetic keeps sprint id ${sprintId} unchanged on rename, so the visible sprint name and the sprint id diverge.`,
+  ];
+  if (renamedInReread === false) {
+    return {
+      phase: 'applied-incomplete',
+      createdIdentities: [],
+      affectedIdentities: [sprintId],
+      integrityNotes: [
+        ...notes,
+        `Poetic reported the rename as successful but sprint ${sprintId} still reads with its previous name.`,
+      ],
+    };
+  }
+  return {
+    phase: 'applied',
+    createdIdentities: [],
+    affectedIdentities: [sprintId],
+    integrityNotes: notes,
+  };
+}
+
+/**
+ * Add work from backlog. Poetic creates the task file and then attaches it with
+ * no rollback, so a created-but-unattached task is a real partial effect and must
+ * render as neither success nor "nothing happened".
+ */
+export function decideAddSprintWorkEffect(
+  identity: SprintAddTaskEnvelope | null,
+  facts: SprintCompositionInvocationFacts,
+  membership: SprintMembershipState | null
+): SprintCompositionEffectDecision {
+  if (identity === null) {
+    // A created-but-unattached task is possible here, so a zero exit without
+    // identity evidence is incomplete rather than "nothing happened".
+    return {
+      phase: facts.timedOut
+        ? 'unknown-after-timeout'
+        : facts.exitCode === 0
+          ? 'applied-incomplete'
+          : 'refused-before-effect',
+      createdIdentities: [],
+      affectedIdentities: [],
+      integrityNotes: [
+        facts.timedOut
+          ? 'Poetic did not answer before the add-task timeout; whether a task was created or attached is unknown.'
+          : 'Poetic returned no usable sprintAddTaskV1 identity evidence for this add.',
+      ],
+    };
+  }
+  const taskIds = identity.taskId === null ? [] : [identity.taskId];
+  const affected = [identity.sprintId, ...taskIds];
+  const capacityNotes =
+    identity.capacityWarningLevel === 'warning'
+      ? [
+          `Poetic reports sprint ${identity.sprintId} at or above its capacity warning threshold; the add proceeded with that warning.`,
+        ]
+      : [];
+  switch (identity.state) {
+    case 'added': {
+      if (membership === 'present') {
+        return {
+          phase: 'applied',
+          createdIdentities: taskIds,
+          affectedIdentities: affected,
+          integrityNotes: capacityNotes,
+        };
+      }
+      return {
+        phase: 'applied-incomplete',
+        createdIdentities: taskIds,
+        affectedIdentities: affected,
+        integrityNotes: [
+          ...capacityNotes,
+          membership === null
+            ? `Poetic reported the task as added but BB could not reread sprint ${identity.sprintId} to confirm membership.`
+            : `Poetic reported the task as added but sprint ${identity.sprintId} does not list it as a member.`,
+        ],
+      };
+    }
+    case 'failed-after-partial-effect':
+      return {
+        phase: 'failed-after-partial-effect',
+        createdIdentities: identity.fileCreated ? taskIds : [],
+        affectedIdentities: affected,
+        integrityNotes: [
+          ...capacityNotes,
+          identity.fileCreated && !identity.membershipApplied
+            ? `Poetic created task ${identity.taskId ?? '(unnamed)'} but did not attach it to sprint ${identity.sprintId}, and add-task has no rollback. The task file may exist unattached.`
+            : `Poetic reported a partial effect while adding backlog work to sprint ${identity.sprintId}.`,
+        ],
+      };
+    case 'unknown-after-timeout':
+      return {
+        phase: 'unknown-after-timeout',
+        createdIdentities: [],
+        affectedIdentities: affected,
+        integrityNotes: [
+          ...capacityNotes,
+          `Poetic reported an unknown outcome after a timeout while adding backlog work to sprint ${identity.sprintId}; whether a task exists or is attached is unknown.`,
+        ],
+      };
+    case 'refused-unfilled-markers':
+    case 'refused-duplicate-backlog':
+    case 'refused-capacity':
+    case 'refused-invalid':
+      return {
+        phase: 'refused-before-effect',
+        createdIdentities: [],
+        affectedIdentities: [],
+        integrityNotes: capacityNotes,
+      };
+  }
+}
+
+/**
+ * Remove: idempotent detach. Poetic reports exit 0 with no change when the task
+ * was never a member, so the pre-launch membership check plus this reread is the
+ * only way a concurrent or no-op removal stays distinguishable from a real one.
+ */
+export function decideRemoveSprintTaskEffect(
+  sprintId: string,
+  taskId: string,
+  facts: SprintCompositionInvocationFacts,
+  membership: SprintMembershipState | null
+): SprintCompositionEffectDecision {
+  if (facts.timedOut) {
+    return {
+      phase: 'unknown-after-timeout',
+      createdIdentities: [],
+      affectedIdentities: [sprintId, taskId],
+      integrityNotes: [
+        `Poetic did not answer before the remove-task timeout; whether task ${taskId} is still a member of sprint ${sprintId} is unknown.`,
+      ],
+    };
+  }
+  if (membership === null) {
+    // A failed reread never converts the reported state into a failure.
+    return {
+      phase: facts.exitCode === 0 ? 'applied' : 'refused-before-effect',
+      createdIdentities: [],
+      affectedIdentities: facts.exitCode === 0 ? [sprintId, taskId] : [],
+      integrityNotes: [
+        `BB could not reread sprint ${sprintId} after the removal, so Poetic's reported outcome stands unconfirmed.`,
+      ],
+    };
+  }
+  if (membership === 'present') {
+    return {
+      phase: facts.exitCode === 0 ? 'applied-incomplete' : 'refused-before-effect',
+      createdIdentities: [],
+      affectedIdentities: facts.exitCode === 0 ? [sprintId, taskId] : [],
+      integrityNotes: [
+        facts.exitCode === 0
+          ? `Poetic reported success but sprint ${sprintId} still lists task ${taskId}. Membership changed concurrently or the removal was a no-op.`
+          : `Poetic refused the removal and task ${taskId} is still a member of sprint ${sprintId}.`,
+      ],
+    };
+  }
+  if (facts.exitCode !== 0) {
+    return {
+      phase: 'refused-before-effect',
+      createdIdentities: [],
+      affectedIdentities: [],
+      integrityNotes: [
+        `Poetic refused the removal, and sprint ${sprintId} does not list task ${taskId}. Membership may have changed concurrently.`,
+      ],
+    };
+  }
+  const notes = [
+    `Poetic keeps the task file on removal and does not delete it. BB cannot observe the task file's sprintId through a canonical read, so a stale sprintId on task ${taskId} would not be visible here; BB reports this and does not repair it.`,
+  ];
+  if (membership === 'missing-reference') {
+    notes.push(
+      `Sprint ${sprintId} still references task ${taskId} as a task id with no resolvable task file.`
+    );
+  }
+  return {
+    phase: 'applied',
+    createdIdentities: [],
+    affectedIdentities: [sprintId, taskId],
+    integrityNotes: notes,
+  };
+}
+
+/**
+ * Migrate: the task id is kept, membership moves, and Poetic forces the status to
+ * `todo`. A mid-flight failure can leave transient membership across two sprint
+ * files, so both sprint rereads decide the phase, not the exit code.
+ */
+export function decideMigrateSprintTaskEffect(
+  identities: { taskId: string; sourceSprintId: string; targetSprintId: string },
+  facts: SprintCompositionInvocationFacts,
+  membership: {
+    source: SprintMembershipState | null;
+    target: SprintMembershipState | null;
+  }
+): SprintCompositionEffectDecision {
+  const affected = [identities.taskId, identities.sourceSprintId, identities.targetSprintId];
+  if (facts.timedOut) {
+    return {
+      phase: 'unknown-after-timeout',
+      createdIdentities: [],
+      affectedIdentities: affected,
+      integrityNotes: [
+        `Poetic did not answer before the migrate-task timeout; which sprint currently lists task ${identities.taskId} is unknown.`,
+      ],
+    };
+  }
+  const inTarget = membership.target === 'present';
+  const inSource = membership.source === 'present';
+  if (membership.source === null || membership.target === null) {
+    return {
+      phase: facts.exitCode === 0 ? 'applied' : 'refused-before-effect',
+      createdIdentities: [],
+      affectedIdentities: facts.exitCode === 0 ? affected : [],
+      integrityNotes: [
+        `BB could not reread both sprints after the migration, so Poetic's reported outcome for task ${identities.taskId} stands unconfirmed.`,
+      ],
+    };
+  }
+  if (facts.exitCode !== 0) {
+    return {
+      phase: inTarget ? 'failed-after-partial-effect' : 'refused-before-effect',
+      createdIdentities: [],
+      affectedIdentities: inTarget ? affected : [],
+      integrityNotes: inTarget
+        ? [
+            `Poetic reported a failed migration but sprint ${identities.targetSprintId} lists task ${identities.taskId}${inSource ? `, and sprint ${identities.sourceSprintId} still lists it as well` : ''}. Poetic attempts rollback; the rereads above are authority.`,
+          ]
+        : [],
+    };
+  }
+  if (inTarget && !inSource) {
+    return {
+      phase: 'applied',
+      createdIdentities: [],
+      affectedIdentities: affected,
+      integrityNotes: [
+        `Poetic reset task ${identities.taskId} to status todo as part of the migration and kept its task id.`,
+      ],
+    };
+  }
+  return {
+    phase: 'applied-incomplete',
+    createdIdentities: [],
+    affectedIdentities: affected,
+    integrityNotes: [
+      inSource && inTarget
+        ? `Both sprint ${identities.sourceSprintId} and sprint ${identities.targetSprintId} list task ${identities.taskId}. Membership is transient across two sprint files.`
+        : `Neither sprint ${identities.targetSprintId} nor sprint ${identities.sourceSprintId} lists task ${identities.taskId} after a reported successful migration.`,
+    ],
+  };
+}
+
+/**
+ * Surface Poetic's current planning-sync evidence from a fresh workspace reread.
+ *
+ * Everything here comes from what Poetic published, never from the exit code, so
+ * a successful command with unpushed planning commits still reads as a local
+ * commit rather than as remote success.
+ */
+export function sprintCompositionSyncWarnings(
+  workspace: SprintCompositionEvidence<PlanningWorkspaceProjection>
+): string[] {
+  if (workspace.state !== 'available') return [workspace.reason];
+  const warnings: string[] = [];
+  const health = workspace.value.data.syncHealth;
+  if (health.state !== 'in-sync') {
+    warnings.push(health.detail ?? `Poetic reports planning sync state ${health.state}.`);
+  }
+  for (const note of workspace.value.notes) {
+    if (note.scope === 'sync-health') warnings.push(note.detail);
+  }
+  return [...new Set(warnings)];
+}
+
+/**
+ * Report, never prove, the synchronization state.
+ *
+ * `remote_verified` means Poetic itself reported zero unpushed planning commits
+ * on a fresh reread; it is never derived from a zero exit code.
+ */
+export function sprintCompositionSyncEvidence(
+  launched: boolean,
+  workspace: SprintCompositionEvidence<PlanningWorkspaceProjection>
+): { state: SprintCompositionSyncState; detail: string | null } {
+  if (!launched) {
+    return {
+      state: 'not_attempted',
+      detail: 'No Poetic command ran, so managed sync was never attempted.',
+    };
+  }
+  if (workspace.state !== 'available') {
+    return { state: 'unknown', detail: workspace.reason };
+  }
+  const health = workspace.value.data.syncHealth;
+  const failed = workspace.value.notes.some(
+    (note) => note.scope === 'sync-health' && note.kind === 'sync-failure'
+  );
+  if (failed) return { state: 'failed', detail: health.detail };
+  switch (health.state) {
+    case 'in-sync':
+      return { state: 'remote_verified', detail: health.detail };
+    case 'ahead':
+    case 'stale':
+      return { state: 'local_commit_only', detail: health.detail };
+    case 'unavailable':
+      return {
+        state: 'unknown',
+        detail: health.detail ?? 'Poetic reported no planning sync evidence.',
+      };
+  }
+}
+
+/** Truncate diagnostics to the current invocation's cap. */
+export function truncateDiagnostics(value: string): string | null {
+  const trimmed = value.trim();
+  if (trimmed.length === 0) return null;
+  return trimmed.length <= SPRINT_COMPOSITION_MAX_DIAGNOSTICS_CHARS
+    ? trimmed
+    : `${trimmed.slice(0, SPRINT_COMPOSITION_MAX_DIAGNOSTICS_CHARS)}…`;
+}