@poetic-ai/poetic 1.42.0

package/integrations/bb-plugin-poetic/src/task-authoring-service.ts

@@ -0,0 +1,842 @@
+/**
+ * Single-attempt service for BB custom task authoring and task relationships.
+ *
+ * Poetic is the only mutation and sync authority. This service:
+ *
+ *   - validates the request against the closed authoring vocabulary and refuses
+ *     any status, lifecycle, execution, or filesystem field before launch;
+ *   - revalidates entity identity against a fresh Poetic read immediately before
+ *     spawning, so a missing, archived, changed, or drifted entity is refused
+ *     rather than mutated blind;
+ *   - runs exactly one fixed argv, once, in the selected repository cwd, with
+ *     `shell: false` and managed sync left on. Nothing is ever retried;
+ *   - reads authority in one order — Poetic's structured outcome, then the fresh
+ *     canonical reread, then the exit code — and always rereads, including after
+ *     a nonzero exit or a timeout;
+ *   - never predicts identity, status, membership, capacity, or push success.
+ *
+ * The runner and the canonical reads are injected. This module builds no
+ * transport of its own, resolves no executable, registers no RPC method, and
+ * imports nothing from the shared adapter, model, contract, server, app, or
+ * route modules.
+ */
+
+import type { z } from 'zod';
+import type { planningWorkspaceProjectionSchema } from './planning-workspace-schema.js';
+import { repositorySchema } from './repository-schema.js';
+import {
+  ProcessLocalTaskAuthoringAdmission,
+  taskAuthoringAdmissionScope,
+  taskAuthoringArgv,
+  taskAuthoringConsentRefusal,
+  taskAuthoringCreateEffect,
+  taskAuthoringDeclaredIdentities,
+  taskAuthoringDeniedInputKeys,
+  taskAuthoringDescriptionPrepopulation,
+  taskAuthoringRequestedIdentities,
+  taskAuthoringSyncState,
+  taskAuthoringSyncWarnings,
+} from './task-authoring-model.js';
+import {
+  type ApplyTaskAuthoringInput,
+  type ApplyTaskAuthoringOutput,
+  applyTaskAuthoringInputSchema,
+  applyTaskAuthoringOutputSchema,
+  TASK_AUTHORING_DISCLOSURE,
+  TASK_AUTHORING_MAX_DIAGNOSTIC_CHARS,
+  TASK_AUTHORING_MAX_OUTPUT_BYTES,
+  TASK_AUTHORING_MUTATION_TIMEOUT_MS,
+  TASK_AUTHORING_OUTCOME_VERSION,
+  type TaskAuthoringAction,
+  type TaskAuthoringCommandEvidence,
+  type TaskAuthoringEffect,
+  type TaskAuthoringRefusal,
+  type TaskAuthoringRefusalReason,
+  type TaskAuthoringRereads,
+  type TaskAuthoringResult,
+  type TaskAuthoringSprintFacts,
+  type TaskCreateIdentityEnvelope,
+  taskCreateIdentityEnvelopeSchema,
+  taskDescriptionEnvelopeSchema,
+} from './task-authoring-schema.js';
+import type { GetTaskDetailOutput } from './task-detail-schema.js';
+
+type Repository = z.infer<typeof repositorySchema>;
+type PlanningWorkspaceProjection = z.infer<typeof planningWorkspaceProjectionSchema>;
+
+/**
+ * The one command shape this service may ask for: the Poetic executable, a fixed
+ * argv, the selected repository cwd, the mutation timeout, no shell, and a
+ * bounded capture. There is no field for env, executable path, or a shell
+ * string, so no caller value can become one.
+ */
+export interface TaskAuthoringCommand {
+  file: 'poetic';
+  args: readonly string[];
+  cwd: string;
+  timeoutMs: typeof TASK_AUTHORING_MUTATION_TIMEOUT_MS;
+  shell: false;
+  maxOutputBytes: typeof TASK_AUTHORING_MAX_OUTPUT_BYTES;
+}
+
+/**
+ * What the injected runner reports. `timedOut` is explicit because a timeout is
+ * an undetermined effect, not a failure, and `exitCode` is null when the process
+ * produced no status.
+ */
+export interface TaskAuthoringCommandResult {
+  exitCode: number | null;
+  stdout: string;
+  stderr: string;
+  timedOut: boolean;
+}
+
+export type TaskAuthoringRunner = (
+  command: TaskAuthoringCommand
+) => Promise<TaskAuthoringCommandResult>;
+
+/**
+ * A canonical task read: Poetic's versioned task-detail projection plus the
+ * `taskDescriptionV1` sibling when Poetic published one. The sibling is the only
+ * permitted prepopulation source for a Description replacement.
+ */
+export interface TaskAuthoringTaskReadValue {
+  detail: GetTaskDetailOutput;
+  description: { taskId: string; description: string } | null;
+}
+
+export type TaskAuthoringTaskRead = (
+  repository: Repository,
+  taskId: string
+) => Promise<TaskAuthoringTaskReadValue>;
+
+/** A canonical sprint read. `null` means Poetic reports no such sprint. */
+export type TaskAuthoringSprintRead = (
+  repository: Repository,
+  sprintId: string
+) => Promise<TaskAuthoringSprintFacts | null>;
+
+/** The planning workspace projection: the only source of sync evidence. */
+export type TaskAuthoringWorkspaceRead = (
+  repository: Repository
+) => Promise<PlanningWorkspaceProjection>;
+
+/**
+ * Last gate before a mutation: Git's own current root and branch must still be
+ * the selected repository identity. Optional because the owning surface may
+ * already hold that gate; when supplied it runs immediately before the spawn.
+ */
+export type TaskAuthoringRepositoryGate = (repository: Repository) => Promise<void>;
+
+export interface TaskAuthoringDependencies {
+  run: TaskAuthoringRunner;
+  readTask: TaskAuthoringTaskRead;
+  readSprint: TaskAuthoringSprintRead;
+  readWorkspace: TaskAuthoringWorkspaceRead;
+  requireFreshRepositoryIdentity?: TaskAuthoringRepositoryGate;
+  admission?: ProcessLocalTaskAuthoringAdmission;
+}
+
+type Unavailable = { state: 'unavailable'; reason: string };
+type Available<T> = { state: 'available'; value: T };
+
+function refused(
+  reason: TaskAuthoringRefusalReason,
+  message: string,
+  action: TaskAuthoringAction | null
+): TaskAuthoringRefusal {
+  return { state: 'refused', reason, message, action };
+}
+
+function errorReason(error: unknown): string {
+  if (error instanceof Error && error.message.length > 0) return error.message;
+  const text = String(error);
+  return text.length > 0 ? text : 'unknown error';
+}
+
+function timeoutError(error: unknown): boolean {
+  if (!error || typeof error !== 'object') return false;
+  const value = error as { code?: unknown; name?: unknown };
+  return value.code === 'ETIMEDOUT' || value.name === 'TimeoutError';
+}
+
+/**
+ * Bound one captured stream before it is parsed or disclosed. The runner owns
+ * the real capture ceiling; this is the second bound, so an oversized capture
+ * cannot be parsed or echoed in full.
+ */
+function boundedCapture(value: string): string {
+  return value.length > TASK_AUTHORING_MAX_OUTPUT_BYTES
+    ? value.slice(0, TASK_AUTHORING_MAX_OUTPUT_BYTES)
+    : value;
+}
+
+/** Diagnostics for the current invocation only, truncated for disclosure. */
+function currentInvocationDiagnostic(value: string): string | null {
+  const trimmed = value.trim();
+  if (trimmed.length === 0) return null;
+  return trimmed.slice(-TASK_AUTHORING_MAX_DIAGNOSTIC_CHARS);
+}
+
+/**
+ * Find Poetic's `taskCreateV1` envelope on stdout. Only whole JSON objects are
+ * considered, and a malformed line is skipped rather than guessed at; the CLI
+ * writes the envelope as one line.
+ */
+function findTaskCreateEnvelope(stdout: string): TaskCreateIdentityEnvelope | null {
+  for (const line of stdout.split('\n')) {
+    const candidate = line.trim();
+    if (!candidate.startsWith('{') || !candidate.includes('taskCreateV1')) continue;
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(candidate);
+    } catch {
+      continue;
+    }
+    if (typeof parsed !== 'object' || parsed === null || !('taskCreateV1' in parsed)) continue;
+    const envelope = taskCreateIdentityEnvelopeSchema.safeParse(
+      (parsed as { taskCreateV1: unknown }).taskCreateV1
+    );
+    if (!envelope.success) return null;
+    if (envelope.data.schemaVersion.split('.')[0] !== '1') return null;
+    return envelope.data;
+  }
+  return null;
+}
+
+export class TaskAuthoringService {
+  private readonly admission: ProcessLocalTaskAuthoringAdmission;
+
+  constructor(private readonly dependencies: TaskAuthoringDependencies) {
+    this.admission = dependencies.admission ?? new ProcessLocalTaskAuthoringAdmission();
+  }
+
+  /**
+   * Apply one authoring action.
+   *
+   * A request that never reached a process is returned as a refusal, which the
+   * registering surface may map to an RPC error. Once a process has run, the
+   * outcome envelope is always returned — including on a nonzero exit or a
+   * timeout — so partial-effect evidence is never discarded.
+   */
+  async apply(repositoryValue: unknown, requestValue: unknown): Promise<TaskAuthoringResult> {
+    const repository = repositorySchema.parse(repositoryValue);
+    const declaredAction =
+      typeof requestValue === 'object' &&
+      requestValue !== null &&
+      'action' in requestValue &&
+      typeof (requestValue as { action: unknown }).action === 'string'
+        ? ((requestValue as { action: string }).action as TaskAuthoringAction)
+        : null;
+
+    // Reported before schema validation so an attempt to reach a status,
+    // lifecycle, or excluded execution surface is named rather than reduced to a
+    // generic invalid-request.
+    const denied =
+      typeof requestValue === 'object' && requestValue !== null && 'input' in requestValue
+        ? taskAuthoringDeniedInputKeys((requestValue as { input: unknown }).input)
+        : [];
+    if (denied.length > 0) {
+      return refused(
+        'lifecycle-field',
+        `Task authoring does not accept ${denied.join(', ')}. Status and lifecycle transitions, time logging, task splitting, and generic execution or filesystem fields are not part of this vocabulary. No command was launched.`,
+        declaredAction
+      );
+    }
+
+    const parsed = applyTaskAuthoringInputSchema.safeParse(requestValue);
+    if (!parsed.success) {
+      return refused('invalid-request', 'Invalid task authoring request.', declaredAction);
+    }
+    const request = parsed.data;
+
+    if (repository.state === 'blocked') {
+      return refused(
+        'repository-not-ready',
+        `Poetic reports the selected repository is not ready: ${repository.messages.join(' ') || 'no detail reported'}. No command was launched.`,
+        request.action
+      );
+    }
+    if (
+      request.projectId !== repository.projectId ||
+      request.sourceId !== repository.sourceId ||
+      request.expected.repositoryPath !== repository.path ||
+      request.expected.branch !== repository.branch
+    ) {
+      return refused(
+        'repository-mismatch',
+        'The request does not identify the selected repository and branch. No command was launched.',
+        request.action
+      );
+    }
+
+    const declaredIdentities = taskAuthoringDeclaredIdentities(request);
+    const expectedIdentities = [...new Set(request.expected.entityIds)].sort();
+    if (
+      expectedIdentities.length !== declaredIdentities.length ||
+      expectedIdentities.some((id, index) => id !== declaredIdentities[index])
+    ) {
+      return refused(
+        'expected-identity-mismatch',
+        'The acknowledged entity ids do not match the entities this action would touch. No command was launched.',
+        request.action
+      );
+    }
+
+    const consentRefusal = taskAuthoringConsentRefusal(request);
+    if (consentRefusal !== null) {
+      return refused(consentRefusal.reason, consentRefusal.message, request.action);
+    }
+
+    const admissionScope = taskAuthoringAdmissionScope(repository.path, request);
+    let release: () => void;
+    try {
+      release = this.admission.claim(admissionScope);
+    } catch (error) {
+      return refused('already-in-flight', errorReason(error), request.action);
+    }
+
+    try {
+      const gate = await this.revalidate(repository, request);
+      if (gate.state === 'refused') return gate.refusal;
+
+      if (this.dependencies.requireFreshRepositoryIdentity) {
+        try {
+          await this.dependencies.requireFreshRepositoryIdentity(repository);
+        } catch (error) {
+          return refused(
+            'repository-moved',
+            `The selected repository or branch no longer matches what was acknowledged (${errorReason(error)}). No command was launched.`,
+            request.action
+          );
+        }
+      }
+
+      return {
+        state: 'completed',
+        outcome: await this.run(repository, request, gate.sprintIdForReread),
+      };
+    } finally {
+      // Released on every terminal path: refusal, command failure, reread
+      // failure, and success alike.
+      release();
+    }
+  }
+
+  /**
+   * Revalidate the entities this action addresses against a fresh Poetic read,
+   * immediately before launch. Every refusal here comes from Poetic's own
+   * evidence; BB never decides on its own that an entity moved.
+   */
+  private async revalidate(
+    repository: Repository,
+    request: ApplyTaskAuthoringInput
+  ): Promise<
+    | { state: 'refused'; refusal: TaskAuthoringRefusal }
+    | { state: 'admitted'; sprintIdForReread: string | null }
+  > {
+    if (request.action === 'createCustomTask') {
+      const sprintId = request.input.sprintId;
+      let sprint: TaskAuthoringSprintFacts | null;
+      try {
+        sprint = await this.dependencies.readSprint(repository, sprintId);
+      } catch (error) {
+        return {
+          state: 'refused',
+          refusal: refused(
+            'sprint-unavailable',
+            `Poetic could not describe sprint ${sprintId} (${errorReason(error)}), so no task was created.`,
+            request.action
+          ),
+        };
+      }
+      if (sprint === null) {
+        return {
+          state: 'refused',
+          refusal: refused(
+            'missing-identity',
+            `Poetic reports no sprint ${sprintId} in this repository, so no task was created.`,
+            request.action
+          ),
+        };
+      }
+      if (sprint.id !== sprintId) {
+        return {
+          state: 'refused',
+          refusal: refused(
+            'changed-identity',
+            `Poetic returned sprint ${sprint.id} while BB asked for ${sprintId}, so no task was created.`,
+            request.action
+          ),
+        };
+      }
+      const observedMembership = request.expected.observedSprintTaskIds;
+      if (observedMembership !== null && !sameMembership(observedMembership, sprint.taskIds)) {
+        return {
+          state: 'refused',
+          refusal: refused(
+            'membership-drift',
+            `Poetic's current membership for sprint ${sprintId} differs from the membership BB showed, so no task was created. Refresh the sprint and submit again.`,
+            request.action
+          ),
+        };
+      }
+      return { state: 'admitted', sprintIdForReread: sprintId };
+    }
+
+    const taskId = request.input.taskId;
+    let read: TaskAuthoringTaskReadValue;
+    try {
+      read = await this.dependencies.readTask(repository, taskId);
+    } catch (error) {
+      return {
+        state: 'refused',
+        refusal: refused(
+          'task-unavailable',
+          `Poetic could not describe task ${taskId} (${errorReason(error)}). No command was launched.`,
+          request.action
+        ),
+      };
+    }
+    const detail = read.detail.task;
+    if (detail.state === 'missing') {
+      return {
+        state: 'refused',
+        refusal: refused(
+          'missing-identity',
+          `Poetic reports no managed task ${taskId} in this repository. No command was launched.`,
+          request.action
+        ),
+      };
+    }
+    if (detail.state === 'unavailable') {
+      return {
+        state: 'refused',
+        refusal: refused(
+          'task-unavailable',
+          `Poetic could not describe task ${taskId} (${detail.reason}). No command was launched.`,
+          request.action
+        ),
+      };
+    }
+    if (detail.value.id !== taskId) {
+      return {
+        state: 'refused',
+        refusal: refused(
+          'changed-identity',
+          `Poetic returned task detail for ${detail.value.id} while BB asked for ${taskId}. No command was launched.`,
+          request.action
+        ),
+      };
+    }
+    if (detail.value.location === 'archive') {
+      return {
+        state: 'refused',
+        refusal: refused(
+          'archived-identity',
+          `Poetic reports task ${taskId} is archived. Authoring does not edit archived tasks, and it never reopens one. No command was launched.`,
+          request.action
+        ),
+      };
+    }
+    const observedUpdatedAt = request.expected.observedTaskUpdatedAt;
+    if (observedUpdatedAt !== null && detail.value.updated !== observedUpdatedAt) {
+      return {
+        state: 'refused',
+        refusal: refused(
+          'changed-identity',
+          `Poetic reports task ${taskId} changed after BB read it. Refresh the task and submit again; nothing was launched.`,
+          request.action
+        ),
+      };
+    }
+
+    if (request.action === 'updateCustomTask' && request.input.description !== undefined) {
+      const prepopulation = taskAuthoringDescriptionPrepopulation(
+        taskId,
+        read.description === null
+          ? {
+              state: 'unavailable',
+              reason: 'Poetic published no taskDescriptionV1 sibling for this task',
+            }
+          : { state: 'available', value: read.description }
+      );
+      if (prepopulation.state === 'unavailable') {
+        return {
+          state: 'refused',
+          refusal: refused(
+            'description-prepopulation-unavailable',
+            `${prepopulation.reason} No command was launched.`,
+            request.action
+          ),
+        };
+      }
+    }
+
+    if (request.action === 'addTaskDependency') {
+      const endpointId = request.input.onTaskId;
+      let endpoint: TaskAuthoringTaskReadValue;
+      try {
+        endpoint = await this.dependencies.readTask(repository, endpointId);
+      } catch (error) {
+        return {
+          state: 'refused',
+          refusal: refused(
+            'task-unavailable',
+            `Poetic could not describe dependency endpoint ${endpointId} (${errorReason(error)}). No command was launched.`,
+            request.action
+          ),
+        };
+      }
+      if (endpoint.detail.task.state === 'missing') {
+        return {
+          state: 'refused',
+          refusal: refused(
+            'missing-identity',
+            `Poetic reports no managed task ${endpointId} to depend on. No command was launched.`,
+            request.action
+          ),
+        };
+      }
+      if (endpoint.detail.task.state === 'unavailable') {
+        return {
+          state: 'refused',
+          refusal: refused(
+            'task-unavailable',
+            `Poetic could not describe dependency endpoint ${endpointId} (${endpoint.detail.task.reason}). No command was launched.`,
+            request.action
+          ),
+        };
+      }
+    }
+    // A removal endpoint is deliberately not required to exist: Poetic treats
+    // removing a dependency it does not hold as a no-op, so refusing here would
+    // block cleanup of a dependency whose task is already gone.
+
+    return { state: 'admitted', sprintIdForReread: request.expected.observedSprintId };
+  }
+
+  /** Run the single fixed attempt, then reread and report. */
+  private async run(
+    repository: Repository,
+    request: ApplyTaskAuthoringInput,
+    sprintIdForReread: string | null
+  ): Promise<ApplyTaskAuthoringOutput> {
+    const argv = taskAuthoringArgv(request);
+    const command: TaskAuthoringCommand = {
+      file: 'poetic',
+      args: argv,
+      cwd: repository.path,
+      timeoutMs: TASK_AUTHORING_MUTATION_TIMEOUT_MS,
+      shell: false,
+      maxOutputBytes: TASK_AUTHORING_MAX_OUTPUT_BYTES,
+    };
+
+    let result: TaskAuthoringCommandResult | null = null;
+    let spawnFailure: { timedOut: boolean; reason: string } | null = null;
+    try {
+      const raw = await this.dependencies.run(command);
+      result = {
+        exitCode: raw.exitCode,
+        stdout: boundedCapture(raw.stdout),
+        stderr: boundedCapture(raw.stderr),
+        timedOut: raw.timedOut,
+      };
+    } catch (error) {
+      // One attempt only: a failure, a timeout, or an ambiguous completion is
+      // reported verbatim and never retried, because a retry could re-apply a
+      // mutation Poetic may already have committed.
+      spawnFailure = { timedOut: timeoutError(error), reason: errorReason(error) };
+    }
+
+    const integrityNotes: string[] = [];
+    const identityOutcome =
+      request.action === 'createCustomTask' && result !== null && !result.timedOut
+        ? this.identityEvidence(request.input.sprintId, result.stdout, integrityNotes)
+        : null;
+
+    const classified = classify(
+      request.action,
+      request.action === 'createCustomTask' ? null : request.input.taskId,
+      result,
+      spawnFailure,
+      identityOutcome
+    );
+    const diagnostics =
+      result === null
+        ? currentInvocationDiagnostic(spawnFailure?.reason ?? '')
+        : currentInvocationDiagnostic(`${result.stdout}\n${result.stderr}`);
+
+    const command_: TaskAuthoringCommandEvidence = {
+      state: classified.state,
+      attempts: 1,
+      argv,
+      exitCode: result?.exitCode ?? null,
+      diagnostics,
+      remoteSyncConfirmedByExitCode: false,
+    };
+
+    const createdTaskId = classified.effect.createdIdentities[0] ?? null;
+    const rereadTaskId =
+      request.action === 'createCustomTask' ? createdTaskId : request.input.taskId;
+    const rereads = await this.reread(repository, request, rereadTaskId, sprintIdForReread);
+    const workspace = await this.rereadWorkspace(repository);
+
+    this.collectIntegrityNotes(request, rereads, workspace, createdTaskId, integrityNotes);
+
+    return applyTaskAuthoringOutputSchema.parse({
+      outcomeVersion: TASK_AUTHORING_OUTCOME_VERSION,
+      repository,
+      disclosure: TASK_AUTHORING_DISCLOSURE,
+      action: request.action,
+      requestedIdentities: taskAuthoringRequestedIdentities(request),
+      command: command_,
+      identityOutcome,
+      effect: classified.effect,
+      sync: taskAuthoringSyncState(workspace),
+      syncWarnings:
+        workspace.state === 'available' ? taskAuthoringSyncWarnings(workspace.value) : [],
+      integrityNotes: [...new Set(integrityNotes)],
+      canonicalRereads: rereads,
+      workspace,
+    } satisfies ApplyTaskAuthoringOutput);
+  }
+
+  /**
+   * Poetic's own identity evidence for a create. A missing, malformed, or
+   * internally inconsistent envelope is reported as no evidence at all: BB never
+   * substitutes the newest task it can see for the identity Poetic failed to
+   * publish.
+   */
+  private identityEvidence(
+    sprintId: string,
+    stdout: string,
+    integrityNotes: string[]
+  ): TaskCreateIdentityEnvelope | null {
+    const envelope = findTaskCreateEnvelope(stdout);
+    if (envelope === null) {
+      integrityNotes.push(
+        'Poetic published no usable taskCreateV1 identity envelope for this create, so whether a task was created is undetermined. BB did not infer an identity from any task list.'
+      );
+      return null;
+    }
+    if (envelope.sprintId !== sprintId) {
+      integrityNotes.push(
+        `Poetic's identity envelope names sprint ${envelope.sprintId} while BB asked for ${sprintId}, so the create is reported as undetermined.`
+      );
+      return null;
+    }
+    if (envelope.state === 'created' && envelope.taskId === null) {
+      integrityNotes.push(
+        'Poetic reported a created task without a task id, so the create is reported as undetermined.'
+      );
+      return null;
+    }
+    return envelope;
+  }
+
+  /** Perform this action's reread set. Failures are members, never exceptions. */
+  private async reread(
+    repository: Repository,
+    request: ApplyTaskAuthoringInput,
+    taskId: string | null,
+    sprintId: string | null
+  ): Promise<TaskAuthoringRereads> {
+    const task: Available<GetTaskDetailOutput> | Unavailable = await (async () => {
+      if (taskId === null) {
+        return {
+          state: 'unavailable' as const,
+          reason:
+            'Poetic published no task identity for this action, so BB had no id to reread. It did not guess one.',
+        };
+      }
+      try {
+        const read = await this.dependencies.readTask(repository, taskId);
+        return { state: 'available' as const, value: read.detail };
+      } catch (error) {
+        return { state: 'unavailable' as const, reason: errorReason(error) };
+      }
+    })();
+
+    const description =
+      request.action === 'updateCustomTask' && request.input.description !== undefined
+        ? await this.rereadDescription(repository, request.input.taskId)
+        : null;
+
+    const sprint =
+      sprintId === null
+        ? null
+        : await (async (): Promise<Available<TaskAuthoringSprintFacts> | Unavailable> => {
+            try {
+              const facts = await this.dependencies.readSprint(repository, sprintId);
+              if (facts === null) {
+                return {
+                  state: 'unavailable' as const,
+                  reason: `Poetic reports no sprint ${sprintId} after this action.`,
+                };
+              }
+              return { state: 'available' as const, value: facts };
+            } catch (error) {
+              return { state: 'unavailable' as const, reason: errorReason(error) };
+            }
+          })();
+
+    return { task, sprint, description };
+  }
+
+  private async rereadDescription(
+    repository: Repository,
+    taskId: string
+  ): Promise<Available<z.infer<typeof taskDescriptionEnvelopeSchema>> | Unavailable> {
+    try {
+      const read = await this.dependencies.readTask(repository, taskId);
+      if (read.description === null) {
+        return {
+          state: 'unavailable',
+          reason: `Poetic published no taskDescriptionV1 sibling for task ${taskId} after this action.`,
+        };
+      }
+      const envelope = taskDescriptionEnvelopeSchema.safeParse({
+        schemaVersion: '1.0.0',
+        taskId: read.description.taskId,
+        description: read.description.description,
+      });
+      if (!envelope.success) {
+        return {
+          state: 'unavailable',
+          reason: `Poetic published a malformed Description for task ${taskId} after this action.`,
+        };
+      }
+      return { state: 'available', value: envelope.data };
+    } catch (error) {
+      return { state: 'unavailable', reason: errorReason(error) };
+    }
+  }
+
+  private async rereadWorkspace(
+    repository: Repository
+  ): Promise<Available<PlanningWorkspaceProjection> | Unavailable> {
+    try {
+      return { state: 'available', value: await this.dependencies.readWorkspace(repository) };
+    } catch (error) {
+      return { state: 'unavailable', reason: errorReason(error) };
+    }
+  }
+
+  /**
+   * Integrity notes taken from the rereads. Each one reports what Poetic
+   * published; none of them repairs anything or asserts a status.
+   */
+  private collectIntegrityNotes(
+    request: ApplyTaskAuthoringInput,
+    rereads: TaskAuthoringRereads,
+    workspace: Available<PlanningWorkspaceProjection> | Unavailable,
+    createdTaskId: string | null,
+    notes: string[]
+  ): void {
+    if (rereads.task.state === 'unavailable') {
+      notes.push(`Poetic's task reread after this action was unavailable: ${rereads.task.reason}`);
+    } else if (rereads.task.value.task.state === 'missing') {
+      notes.push(
+        'Poetic reports no managed task at this id after the action. BB did not infer a completed, cancelled, or archived state.'
+      );
+    }
+    if (rereads.sprint?.state === 'unavailable') {
+      notes.push(
+        `Poetic's sprint reread after this action was unavailable: ${rereads.sprint.reason}`
+      );
+    }
+    if (rereads.description?.state === 'unavailable') {
+      notes.push(
+        `Poetic's Description reread after this action was unavailable: ${rereads.description.reason}`
+      );
+    }
+    if (workspace.state === 'unavailable') {
+      notes.push(`Poetic's planning workspace reread was unavailable: ${workspace.reason}`);
+    }
+    if (
+      createdTaskId !== null &&
+      rereads.sprint?.state === 'available' &&
+      !rereads.sprint.value.taskIds.includes(createdTaskId)
+    ) {
+      notes.push(
+        `Poetic created task ${createdTaskId} but its sprint reread does not list it as a member. BB reports this and repairs nothing.`
+      );
+    }
+    if (
+      request.action === 'addTaskDependency' &&
+      rereads.task.state === 'available' &&
+      rereads.task.value.task.state === 'available' &&
+      !rereads.task.value.task.value.dependencies.some(
+        (dependency) => dependency.id === request.input.onTaskId
+      )
+    ) {
+      notes.push(
+        `Poetic's task reread does not list ${request.input.onTaskId} among this task's dependencies.`
+      );
+    }
+  }
+}
+
+function sameMembership(observed: readonly string[], current: readonly string[]): boolean {
+  const left = [...new Set(observed)].sort();
+  const right = [...new Set(current)].sort();
+  return left.length === right.length && left.every((id, index) => id === right[index]);
+}
+
+/**
+ * Command state and effect phase for one attempt.
+ *
+ * Authority order is fixed: Poetic's structured identity outcome decides a
+ * create; otherwise the exit code is the only report available, and a nonzero
+ * exit is reported as possibly partial rather than as "nothing happened".
+ */
+function classify(
+  action: TaskAuthoringAction,
+  addressedTaskId: string | null,
+  result: TaskAuthoringCommandResult | null,
+  spawnFailure: { timedOut: boolean; reason: string } | null,
+  identityOutcome: TaskCreateIdentityEnvelope | null
+): { state: TaskAuthoringCommandEvidence['state']; effect: TaskAuthoringEffect } {
+  const affected = addressedTaskId === null ? [] : [addressedTaskId];
+  if (result === null) {
+    if (spawnFailure?.timedOut) {
+      return {
+        state: 'timed_out',
+        effect: { phase: 'unknown-after-timeout', createdIdentities: [], affectedIdentities: [] },
+      };
+    }
+    // The command never ran, so no managed state can have changed.
+    return {
+      state: 'failed',
+      effect: { phase: 'refused-before-effect', createdIdentities: [], affectedIdentities: [] },
+    };
+  }
+  if (result.timedOut) {
+    return {
+      state: 'timed_out',
+      effect: {
+        phase: 'unknown-after-timeout',
+        createdIdentities: [],
+        affectedIdentities: affected,
+      },
+    };
+  }
+  if (action === 'createCustomTask') return taskAuthoringCreateEffect(identityOutcome);
+  if (result.exitCode === 0) {
+    return {
+      state: 'succeeded',
+      effect: { phase: 'applied', createdIdentities: [], affectedIdentities: affected },
+    };
+  }
+  // A failed command may still have applied part of its change; nothing is
+  // retried, and the fresh reread is the only authority on what it did.
+  return {
+    state: 'failed',
+    effect: {
+      phase: 'failed-after-partial-effect',
+      createdIdentities: [],
+      affectedIdentities: affected,
+    },
+  };
+}