@ebrindley/build 0.0.0-stage → 1.42.1-rc28

package/integrations/bb-plugin-build/src/sprint-composition-service.ts

@@ -0,0 +1,773 @@
+/**
+ * Isolated sprint-composition service (BPAU-03).
+ *
+ * BPAU-07A owns executable resolution, live RPC registration, and rendering.
+ * This module accepts only an injected runner and always sends one fixed argv
+ * with a false shell flag: callers cannot supply argv, env, cwd, paths, URLs, or
+ * an executable, and no caller-controlled `--json`, `--force`, `--no-sync`,
+ * `--dry-run`, `--split`, `--splitter`, `--provider`, `--model`, or `--hint`
+ * token can reach the child process.
+ *
+ * Authority order is fixed for every mutation: the BPAU-00B structured outcome
+ * outranks the fresh canonical reread, which outranks the exit code. An exit code
+ * is evidence of what Build reported, never evidence of what changed. Nothing is
+ * retried (`attempts: 1`). Build's managed sync stays on, so
+ * `remoteSyncConfirmedByExitCode` is a literal false.
+ */
+
+import type { z } from 'zod';
+import { parsePlanningWorkspaceV1 } from './planning-readback.js';
+import type { PlanningWorkspaceProjection } from './planning-service.js';
+import { mapPlanningWorkspace } from './planning-service.js';
+import { repositorySchema } from './repository-schema.js';
+import {
+  decideAddSprintWorkEffect,
+  decideCreateSprintEffect,
+  decideMigrateSprintTaskEffect,
+  decideRemoveSprintTaskEffect,
+  decideRenameSprintEffect,
+  membershipDrifted,
+  ProcessLocalSprintCompositionAdmission,
+  SPRINT_COMPOSITION_DISCLOSURE,
+  SPRINT_COMPOSITION_MAX_OUTPUT_BYTES,
+  SPRINT_COMPOSITION_MUTATION_TIMEOUT_MS,
+  SPRINT_COMPOSITION_READ_TIMEOUT_MS,
+  type SprintCompositionEffectDecision,
+  type SprintCompositionInvocationFacts,
+  sprintCompositionAdmissionIdentity,
+  sprintCompositionArgv,
+  sprintCompositionRequestedIdentities,
+  sprintCompositionSyncEvidence,
+  sprintCompositionSyncWarnings,
+  truncateDiagnostics,
+} from './sprint-composition-model.js';
+import {
+  parseBacklogIdentity,
+  parseSprintAddTaskIdentity,
+  parseSprintCompositionJson,
+  parseSprintCreateIdentity,
+  parseSprintList,
+  parseSprintStatus,
+  parseTaskDetailEnvelope,
+  type SprintMembershipState,
+  sprintIntegrityNotes,
+  sprintMembershipIds,
+  sprintMembershipState,
+} from './sprint-composition-readback.js';
+import {
+  type ApplySprintCompositionInput,
+  type ApplySprintCompositionOutput,
+  applySprintCompositionInputSchema,
+  type GetSprintOutput,
+  getSprintInputSchema,
+  type ListSprintsOutput,
+  listSprintsInputSchema,
+  SPRINT_COMPOSITION_OUTCOME_VERSION,
+  type SprintCompositionEvidence,
+  type SprintCompositionIdentityOutcome,
+  type SprintCompositionRereads,
+  type SprintListEnvelope,
+  type SprintStatusEnvelope,
+} from './sprint-composition-schema.js';
+import type { GetTaskDetailOutput } from './task-detail-schema.js';
+
+type Repository = z.infer<typeof repositorySchema>;
+
+export interface SprintCompositionCommand {
+  file: 'build';
+  args: readonly string[];
+  cwd: string;
+  timeoutMs:
+    | typeof SPRINT_COMPOSITION_READ_TIMEOUT_MS
+    | typeof SPRINT_COMPOSITION_MUTATION_TIMEOUT_MS;
+  shell: false;
+}
+
+export interface SprintCompositionCommandResult {
+  stdout: string;
+  stderr: string;
+  exitCode: number;
+}
+
+export type SprintCompositionRunner = (
+  command: SprintCompositionCommand
+) => Promise<SprintCompositionCommandResult>;
+
+/**
+ * A request that cannot become an outcome: it names no accepted action, so there
+ * is nothing to report an effect phase about. Thrown before any spawn exists.
+ */
+export class SprintCompositionRequestError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'SprintCompositionRequestError';
+  }
+}
+
+function unavailable<T>(reason: string): SprintCompositionEvidence<T> {
+  return { state: 'unavailable', reason };
+}
+
+function timedOutError(error: unknown): boolean {
+  if (!error || typeof error !== 'object') return false;
+  const value = error as { code?: unknown; name?: unknown; timedOut?: unknown };
+  return value.timedOut === true || value.code === 'ETIMEDOUT' || value.name === 'TimeoutError';
+}
+
+/** Cap captured output per invocation before anything parses or reports it. */
+function capOutput(value: string): string {
+  if (Buffer.byteLength(value, 'utf8') <= SPRINT_COMPOSITION_MAX_OUTPUT_BYTES) return value;
+  return Buffer.from(value, 'utf8')
+    .subarray(0, SPRINT_COMPOSITION_MAX_OUTPUT_BYTES)
+    .toString('utf8');
+}
+
+function membershipOf(
+  sprint: SprintCompositionEvidence<SprintStatusEnvelope>,
+  taskId: string
+): SprintMembershipState | null {
+  return sprint.state === 'available' ? sprintMembershipState(sprint.value, taskId) : null;
+}
+
+function notesOf(sprint: SprintCompositionEvidence<SprintStatusEnvelope>): string[] {
+  return sprint.state === 'available' ? sprintIntegrityNotes(sprint.value) : [];
+}
+
+export class SprintCompositionService {
+  constructor(
+    private readonly run: SprintCompositionRunner,
+    private readonly admission = new ProcessLocalSprintCompositionAdmission()
+  ) {}
+
+  /**
+   * Read-only multi-sprint enumeration. Current and archived sprint identities
+   * come from Build's own list payload; nothing is merged, re-sorted, or
+   * recomputed here.
+   */
+  async listSprints(repositoryValue: unknown, inputValue: unknown): Promise<ListSprintsOutput> {
+    const repository = repositorySchema.parse(repositoryValue);
+    const input = listSprintsInputSchema.safeParse(inputValue);
+    if (!input.success) {
+      throw new SprintCompositionRequestError('Invalid sprint list request.');
+    }
+    const scope = input.data.scope ?? 'all';
+    if (!this.identifiesRepository(repository, input.data)) {
+      return {
+        repository,
+        scope,
+        sprints: unavailable('The request does not identify the selected repository.'),
+      };
+    }
+    const args = ['plan', 'sprint', 'list'];
+    if (scope === 'current') args.push('--current');
+    if (scope === 'archived') args.push('--archived');
+    args.push('--json');
+
+    const json = await this.read(repository, args);
+    if (json.state !== 'available') return { repository, scope, sprints: json };
+    const parsed = parseSprintList(json.value);
+    if (parsed.state === 'available' && parsed.value.scope !== scope) {
+      return {
+        repository,
+        scope,
+        sprints: unavailable('Build returned a sprint list for a different scope.'),
+      };
+    }
+    return { repository, scope, sprints: parsed };
+  }
+
+  /**
+   * Read-only single-sprint projection, always with an explicit sprint id.
+   * Membership, capacity, readiness, and integrity are carried verbatim; there is
+   * no capacity command here because `sprint capacity` has no `--json` and
+   * parsing human output is forbidden.
+   */
+  async getSprint(repositoryValue: unknown, inputValue: unknown): Promise<GetSprintOutput> {
+    const repository = repositorySchema.parse(repositoryValue);
+    const input = getSprintInputSchema.safeParse(inputValue);
+    if (!input.success) {
+      throw new SprintCompositionRequestError('Invalid sprint status request.');
+    }
+    if (!this.identifiesRepository(repository, input.data)) {
+      return {
+        repository,
+        sprintId: input.data.sprintId,
+        sprint: unavailable('The request does not identify the selected repository.'),
+        integrityNotes: [],
+      };
+    }
+    const sprint = await this.readSprintStatus(repository, input.data.sprintId);
+    return {
+      repository,
+      sprintId: input.data.sprintId,
+      sprint,
+      integrityNotes: notesOf(sprint),
+    };
+  }
+
+  /**
+   * Run one sprint-composition mutation exactly once and report the authoritative
+   * outcome. Every terminal path releases process-local admission, including
+   * refusal and reread failure.
+   */
+  async apply(
+    repositoryValue: unknown,
+    requestValue: unknown
+  ): Promise<ApplySprintCompositionOutput> {
+    const repository = repositorySchema.parse(repositoryValue);
+    const parsedRequest = applySprintCompositionInputSchema.safeParse(requestValue);
+    if (!parsedRequest.success) {
+      throw new SprintCompositionRequestError(
+        'Invalid sprint composition request: only the closed sprint-composition vocabulary and its declared fields are accepted.'
+      );
+    }
+    const request = parsedRequest.data;
+
+    const targetRefusal = this.repositoryRefusal(repository, request);
+    if (targetRefusal !== null) {
+      return this.refusedBeforeLaunch(repository, request, targetRefusal);
+    }
+
+    let release: () => void;
+    try {
+      release = this.admission.claim({
+        repositoryPath: repository.path,
+        identity: sprintCompositionAdmissionIdentity(request),
+        family: 'sprint-composition',
+      });
+    } catch (error) {
+      return this.refusedBeforeLaunch(
+        repository,
+        request,
+        error instanceof Error ? error.message : String(error)
+      );
+    }
+
+    try {
+      const admission = await this.admissionEvidence(repository, request);
+      if (admission.refusal !== null) {
+        return this.refusedBeforeLaunch(repository, request, admission.refusal);
+      }
+      return await this.launchAndReread(repository, request);
+    } finally {
+      release();
+    }
+  }
+
+  private identifiesRepository(
+    repository: Repository,
+    input: { projectId: string; sourceId: string }
+  ): boolean {
+    return input.projectId === repository.projectId && input.sourceId === repository.sourceId;
+  }
+
+  /**
+   * Fresh repository identity gate, re-checked immediately before spawn so a
+   * moved checkout or switched branch is refused rather than mutated blind.
+   * Build remains the authority for whether its command is valid on that branch.
+   */
+  private repositoryRefusal(
+    repository: Repository,
+    request: ApplySprintCompositionInput
+  ): string | null {
+    if (!this.identifiesRepository(repository, request)) {
+      return 'The request does not identify the selected repository.';
+    }
+    if (request.expected.repositoryPath !== repository.path) {
+      return 'The selected repository path changed since this request was built, so no command ran.';
+    }
+    if (request.expected.branch !== repository.branch) {
+      return 'The selected branch changed since this request was built, so no command ran.';
+    }
+    if (repository.state === 'blocked') {
+      return 'Build reports the selected repository as blocked, so no command ran.';
+    }
+    return null;
+  }
+
+  /**
+   * Revalidate entity identity against fresh canonical evidence before spawning.
+   *
+   * For migrate this is the load-bearing admission gate: `migrateToNextSprint`
+   * does not enforce non-terminal status and would reset a done task to todo, so
+   * BB admits the migration only when a fresh task read shows a live,
+   * non-archived task whose status is neither done nor cancelled and whose
+   * membership in the declared source sprint is confirmed.
+   */
+  private async admissionEvidence(
+    repository: Repository,
+    request: ApplySprintCompositionInput
+  ): Promise<{ refusal: string | null }> {
+    switch (request.action) {
+      case 'createSprint':
+        return { refusal: null };
+      case 'renameSprint':
+      case 'addSprintWorkFromBacklog': {
+        const sprint = await this.readSprintStatus(repository, request.input.sprintId);
+        if (sprint.state !== 'available') {
+          return {
+            refusal: `Build could not describe sprint ${request.input.sprintId}, so no command ran: ${sprint.reason}`,
+          };
+        }
+        if (sprint.value.status === 'completed' || sprint.value.archived) {
+          return {
+            refusal: `Build reports sprint ${request.input.sprintId} as ${sprint.value.archived ? 'archived' : 'completed'} and read-only, so no command ran.`,
+          };
+        }
+        return { refusal: null };
+      }
+      case 'removeSprintTask': {
+        const sprint = await this.readSprintStatus(repository, request.input.sprintId);
+        if (sprint.state !== 'available') {
+          return {
+            refusal: `Build could not describe sprint ${request.input.sprintId}, so no command ran: ${sprint.reason}`,
+          };
+        }
+        if (sprint.value.status === 'completed' || sprint.value.archived) {
+          return {
+            refusal: `Build reports sprint ${request.input.sprintId} as ${sprint.value.archived ? 'archived' : 'completed'} and read-only, so no command ran.`,
+          };
+        }
+        const membership = sprintMembershipState(sprint.value, request.input.taskId);
+        if (membership !== 'present') {
+          return {
+            refusal:
+              membership === 'missing-reference'
+                ? `Sprint ${request.input.sprintId} references task ${request.input.taskId} as a task id with no resolvable task file, so no command ran.`
+                : `Build does not list task ${request.input.taskId} as a member of sprint ${request.input.sprintId}, so no command ran.`,
+          };
+        }
+        if (
+          membershipDrifted(request.expected.observedMembership, sprintMembershipIds(sprint.value))
+        ) {
+          return {
+            refusal: `Sprint ${request.input.sprintId} membership changed since this request was built, so no command ran.`,
+          };
+        }
+        return { refusal: null };
+      }
+      case 'migrateSprintTask': {
+        const [task, source, target] = await Promise.all([
+          this.readTaskDetail(repository, request.input.taskId),
+          this.readSprintStatus(repository, request.input.sourceSprintId),
+          this.readSprintStatus(repository, request.input.targetSprintId),
+        ]);
+        if (task.task.state !== 'available') {
+          return {
+            refusal:
+              task.task.state === 'missing'
+                ? `Build reports no managed task ${request.input.taskId}, so no command ran.`
+                : `Build could not describe task ${request.input.taskId}, so no command ran.`,
+          };
+        }
+        const facts = task.task.value;
+        if (facts.location === 'archive' || facts.archived !== null) {
+          return {
+            refusal: `Build reports task ${request.input.taskId} as archived, so no command ran.`,
+          };
+        }
+        if (facts.status === 'done' || facts.status === 'cancelled') {
+          return {
+            refusal: `Build reports task ${request.input.taskId} as ${facts.status}. Migration would reset it to todo, so no command ran.`,
+          };
+        }
+        if (source.state !== 'available') {
+          return {
+            refusal: `Build could not describe source sprint ${request.input.sourceSprintId}, so no command ran: ${source.reason}`,
+          };
+        }
+        if (target.state !== 'available') {
+          return {
+            refusal: `Build could not describe target sprint ${request.input.targetSprintId}, so no command ran: ${target.reason}`,
+          };
+        }
+        if (target.value.status === 'completed' || target.value.archived) {
+          return {
+            refusal: `Build reports target sprint ${request.input.targetSprintId} as ${target.value.archived ? 'archived' : 'completed'} and read-only, so no command ran.`,
+          };
+        }
+        if (sprintMembershipState(source.value, request.input.taskId) !== 'present') {
+          return {
+            refusal: `Build does not list task ${request.input.taskId} as a member of the declared source sprint ${request.input.sourceSprintId}, so no command ran.`,
+          };
+        }
+        if (
+          membershipDrifted(request.expected.observedMembership, sprintMembershipIds(source.value))
+        ) {
+          return {
+            refusal: `Source sprint ${request.input.sourceSprintId} membership changed since this request was built, so no command ran.`,
+          };
+        }
+        return { refusal: null };
+      }
+    }
+  }
+
+  /** Spawn the fixed argv once, then perform the action's authoritative rereads. */
+  private async launchAndReread(
+    repository: Repository,
+    request: ApplySprintCompositionInput
+  ): Promise<ApplySprintCompositionOutput> {
+    const argv = sprintCompositionArgv(request);
+    let stdout = '';
+    let diagnostics: string | null = null;
+    let exitCode: number | null = null;
+    let timedOut = false;
+    try {
+      const result = await this.run({
+        file: 'build',
+        args: argv,
+        cwd: repository.path,
+        timeoutMs: SPRINT_COMPOSITION_MUTATION_TIMEOUT_MS,
+        shell: false,
+      });
+      stdout = capOutput(result.stdout);
+      diagnostics = truncateDiagnostics(capOutput(result.stderr));
+      exitCode = result.exitCode;
+    } catch (error) {
+      timedOut = timedOutError(error);
+      diagnostics = truncateDiagnostics(error instanceof Error ? error.message : String(error));
+    }
+    const facts: SprintCompositionInvocationFacts = { timedOut, exitCode };
+
+    const { identityOutcome, ambiguous, identityNotes } = this.identityEvidence(
+      request,
+      stdout,
+      facts
+    );
+    const { rereads, decision } = await this.rereadAndDecide(
+      repository,
+      request,
+      facts,
+      identityOutcome
+    );
+
+    const workspace = await this.readWorkspace(repository);
+    const commandState = timedOut
+      ? 'timed_out'
+      : ambiguous
+        ? 'ambiguous'
+        : exitCode === 0
+          ? 'succeeded'
+          : 'failed';
+
+    return {
+      outcomeVersion: SPRINT_COMPOSITION_OUTCOME_VERSION,
+      repository,
+      disclosure: SPRINT_COMPOSITION_DISCLOSURE,
+      action: request.action,
+      requestedIdentities: sprintCompositionRequestedIdentities(request),
+      command: {
+        state: commandState,
+        attempts: 1,
+        argv,
+        exitCode,
+        diagnostics,
+        remoteSyncConfirmedByExitCode: false,
+      },
+      identityOutcome,
+      effect: {
+        phase: decision.phase,
+        createdIdentities: decision.createdIdentities,
+        affectedIdentities: decision.affectedIdentities,
+      },
+      sync: sprintCompositionSyncEvidence(true, workspace),
+      syncWarnings: sprintCompositionSyncWarnings(workspace),
+      integrityNotes: [
+        ...new Set([...identityNotes, ...decision.integrityNotes, ...this.rereadNotes(rereads)]),
+      ],
+      canonicalRereads: rereads,
+      workspace,
+    };
+  }
+
+  /**
+   * Validate the BPAU-00B identity envelope for the two minting actions.
+   *
+   * A missing, malformed, or internally inconsistent envelope is refused and the
+   * invocation is reported as `ambiguous`: the newest list row is never
+   * substituted for a returned id.
+   */
+  private identityEvidence(
+    request: ApplySprintCompositionInput,
+    stdout: string,
+    facts: SprintCompositionInvocationFacts
+  ): {
+    identityOutcome: SprintCompositionIdentityOutcome;
+    ambiguous: boolean;
+    identityNotes: string[];
+  } {
+    if (request.action !== 'createSprint' && request.action !== 'addSprintWorkFromBacklog') {
+      return { identityOutcome: null, ambiguous: false, identityNotes: [] };
+    }
+    if (facts.timedOut) {
+      return {
+        identityOutcome: null,
+        ambiguous: false,
+        identityNotes: ['Build produced no identity evidence before the timeout.'],
+      };
+    }
+    const json = parseSprintCompositionJson(stdout);
+    if (json.state !== 'available') {
+      return { identityOutcome: null, ambiguous: true, identityNotes: [json.reason] };
+    }
+    if (request.action === 'createSprint') {
+      const identity = parseSprintCreateIdentity(json.value, {
+        name: request.input.name,
+        start: request.input.start,
+        end: request.input.end,
+      });
+      return identity.state === 'available'
+        ? {
+            identityOutcome: { kind: 'sprintCreateV1', value: identity.value },
+            ambiguous: false,
+            identityNotes: [],
+          }
+        : { identityOutcome: null, ambiguous: true, identityNotes: [identity.reason] };
+    }
+    const identity = parseSprintAddTaskIdentity(json.value, {
+      sprintId: request.input.sprintId,
+      backlogItemId: request.input.backlogItemId,
+    });
+    return identity.state === 'available'
+      ? {
+          identityOutcome: { kind: 'sprintAddTaskV1', value: identity.value },
+          ambiguous: false,
+          identityNotes: [],
+        }
+      : { identityOutcome: null, ambiguous: true, identityNotes: [identity.reason] };
+  }
+
+  /** Perform the action's frozen reread set, then decide the effect phase. */
+  private async rereadAndDecide(
+    repository: Repository,
+    request: ApplySprintCompositionInput,
+    facts: SprintCompositionInvocationFacts,
+    identityOutcome: SprintCompositionIdentityOutcome
+  ): Promise<{ rereads: SprintCompositionRereads; decision: SprintCompositionEffectDecision }> {
+    switch (request.action) {
+      case 'createSprint': {
+        const created =
+          identityOutcome?.kind === 'sprintCreateV1' ? identityOutcome.value.sprintId : null;
+        const sprints = await this.readSprintList(repository);
+        const sprint =
+          created === null ? undefined : await this.readSprintStatus(repository, created);
+        return {
+          rereads: sprint === undefined ? { sprints } : { sprints, sprint },
+          decision: decideCreateSprintEffect(
+            identityOutcome?.kind === 'sprintCreateV1' ? identityOutcome.value : null,
+            facts
+          ),
+        };
+      }
+      case 'renameSprint': {
+        const [sprints, sprint] = await Promise.all([
+          this.readSprintList(repository),
+          this.readSprintStatus(repository, request.input.sprintId),
+        ]);
+        const renamed =
+          sprint.state === 'available' ? sprint.value.name === request.input.name : null;
+        return {
+          rereads: { sprints, sprint },
+          decision: decideRenameSprintEffect(request.input.sprintId, facts, renamed),
+        };
+      }
+      case 'addSprintWorkFromBacklog': {
+        const identity = identityOutcome?.kind === 'sprintAddTaskV1' ? identityOutcome.value : null;
+        const [sprint, backlogItem] = await Promise.all([
+          this.readSprintStatus(repository, request.input.sprintId),
+          this.readBacklogItem(repository, request.input.backlogItemId),
+        ]);
+        const newTaskId = identity?.taskId ?? null;
+        const task =
+          newTaskId === null ? undefined : await this.readTaskEvidence(repository, newTaskId);
+        const membership = newTaskId === null ? null : membershipOf(sprint, newTaskId);
+        return {
+          rereads: task === undefined ? { sprint, backlogItem } : { sprint, task, backlogItem },
+          decision: decideAddSprintWorkEffect(identity, facts, membership),
+        };
+      }
+      case 'removeSprintTask': {
+        const [sprint, task] = await Promise.all([
+          this.readSprintStatus(repository, request.input.sprintId),
+          this.readTaskEvidence(repository, request.input.taskId),
+        ]);
+        return {
+          rereads: { sprint, task },
+          decision: decideRemoveSprintTaskEffect(
+            request.input.sprintId,
+            request.input.taskId,
+            facts,
+            membershipOf(sprint, request.input.taskId)
+          ),
+        };
+      }
+      case 'migrateSprintTask': {
+        const [sourceSprint, targetSprint, task] = await Promise.all([
+          this.readSprintStatus(repository, request.input.sourceSprintId),
+          this.readSprintStatus(repository, request.input.targetSprintId),
+          this.readTaskEvidence(repository, request.input.taskId),
+        ]);
+        return {
+          rereads: { sourceSprint, targetSprint, task },
+          decision: decideMigrateSprintTaskEffect(
+            {
+              taskId: request.input.taskId,
+              sourceSprintId: request.input.sourceSprintId,
+              targetSprintId: request.input.targetSprintId,
+            },
+            facts,
+            {
+              source: membershipOf(sourceSprint, request.input.taskId),
+              target: membershipOf(targetSprint, request.input.taskId),
+            }
+          ),
+        };
+      }
+    }
+  }
+
+  /** Build-reported integrity notes from whichever sprints this action reread. */
+  private rereadNotes(rereads: SprintCompositionRereads): string[] {
+    const notes: string[] = [];
+    for (const sprint of [rereads.sprint, rereads.sourceSprint, rereads.targetSprint]) {
+      if (sprint !== undefined) notes.push(...notesOf(sprint));
+    }
+    return notes;
+  }
+
+  private refusedBeforeLaunch(
+    repository: Repository,
+    request: ApplySprintCompositionInput,
+    reason: string
+  ): ApplySprintCompositionOutput {
+    const workspace = unavailable<PlanningWorkspaceProjection>(
+      'No Build command ran, so BB did not reread the planning workspace.'
+    );
+    return {
+      outcomeVersion: SPRINT_COMPOSITION_OUTCOME_VERSION,
+      repository,
+      disclosure: SPRINT_COMPOSITION_DISCLOSURE,
+      action: request.action,
+      requestedIdentities: sprintCompositionRequestedIdentities(request),
+      command: {
+        state: 'failed',
+        attempts: 1,
+        argv: [],
+        exitCode: null,
+        diagnostics: reason,
+        remoteSyncConfirmedByExitCode: false,
+      },
+      identityOutcome: null,
+      effect: { phase: 'refused-before-launch', createdIdentities: [], affectedIdentities: [] },
+      sync: sprintCompositionSyncEvidence(false, workspace),
+      syncWarnings: [],
+      integrityNotes: [reason],
+      canonicalRereads: {},
+      workspace,
+    };
+  }
+
+  /** One fixed read. A nonzero exit or unparseable stdout is unavailable evidence. */
+  private async read(
+    repository: Repository,
+    args: readonly string[]
+  ): Promise<SprintCompositionEvidence<unknown>> {
+    let result: SprintCompositionCommandResult;
+    try {
+      result = await this.run({
+        file: 'build',
+        args,
+        cwd: repository.path,
+        timeoutMs: SPRINT_COMPOSITION_READ_TIMEOUT_MS,
+        shell: false,
+      });
+    } catch (error) {
+      return unavailable(
+        timedOutError(error) ? 'Build read timed out.' : 'Build read failed to run.'
+      );
+    }
+    if (result.exitCode !== 0) {
+      return unavailable('Build reported a failed read.');
+    }
+    return parseSprintCompositionJson(capOutput(result.stdout));
+  }
+
+  private async readSprintList(
+    repository: Repository
+  ): Promise<SprintCompositionEvidence<SprintListEnvelope>> {
+    const json = await this.read(repository, ['plan', 'sprint', 'list', '--json']);
+    return json.state === 'available' ? parseSprintList(json.value) : json;
+  }
+
+  private async readSprintStatus(
+    repository: Repository,
+    sprintId: string
+  ): Promise<SprintCompositionEvidence<SprintStatusEnvelope>> {
+    const json = await this.read(repository, ['plan', 'sprint', 'status', sprintId, '--json']);
+    return json.state === 'available' ? parseSprintStatus(json.value, sprintId) : json;
+  }
+
+  private async readBacklogItem(
+    repository: Repository,
+    backlogItemId: string
+  ): Promise<SprintCompositionEvidence<{ id: string }>> {
+    const json = await this.read(repository, ['plan', 'backlog', 'show', backlogItemId, '--json']);
+    return json.state === 'available' ? parseBacklogIdentity(json.value, backlogItemId) : json;
+  }
+
+  private async readTaskDetail(
+    repository: Repository,
+    taskId: string
+  ): Promise<GetTaskDetailOutput> {
+    const json = await this.read(repository, [
+      'plan',
+      'task',
+      'status',
+      taskId,
+      '--json',
+      '--detail',
+    ]);
+    return json.state === 'available'
+      ? parseTaskDetailEnvelope(json.value)
+      : { schemaVersion: null, task: { state: 'unavailable' as const, reason: json.reason } };
+  }
+
+  /** The task reread as it appears in `canonicalRereads`. */
+  private async readTaskEvidence(
+    repository: Repository,
+    taskId: string
+  ): Promise<SprintCompositionEvidence<GetTaskDetailOutput>> {
+    const detail = await this.readTaskDetail(repository, taskId);
+    if (detail.task.state === 'available') {
+      return { state: 'available', value: detail };
+    }
+    return unavailable(
+      detail.task.state === 'missing'
+        ? `Build reports no managed task ${taskId}.`
+        : detail.task.reason
+    );
+  }
+
+  /**
+   * The planning workspace projection: the only source of sync health, taken from
+   * the bare `plan sprint status --json` form that injects `planningWorkspaceV1`.
+   */
+  private async readWorkspace(
+    repository: Repository
+  ): Promise<SprintCompositionEvidence<PlanningWorkspaceProjection>> {
+    const json = await this.read(repository, ['plan', 'sprint', 'status', '--json']);
+    if (json.state !== 'available') return json;
+    if (
+      json.value === null ||
+      typeof json.value !== 'object' ||
+      !('planningWorkspaceV1' in json.value)
+    ) {
+      return unavailable('Build returned no planning workspace projection.');
+    }
+    const readback = parsePlanningWorkspaceV1(
+      (json.value as { planningWorkspaceV1: unknown }).planningWorkspaceV1
+    );
+    return { state: 'available', value: mapPlanningWorkspace(readback) };
+  }
+}