@poetic-ai/poetic 1.42.0

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

@@ -0,0 +1,601 @@
+/**
+ * BB wire schemas for the closed sprint-composition vocabulary (BPAU-03).
+ *
+ * Five mutations and two read-only projections. Every request object is
+ * `.strict()`, so a caller cannot smuggle `--split`, `--splitter`, `--provider`,
+ * `--model`, `--hint`, `--force`, `--no-sync`, `--dry-run`, retry controls,
+ * argv, cwd, env, an executable, or a filesystem path into a spawn. Sprint
+ * lifecycle (`complete`/`close`/`tidy`/`unlock`/`prune-missing`/`run`/`apply`)
+ * and custom task creation are absent by construction: they have no action name,
+ * no argv entry, and no schema member here.
+ *
+ * `--json` is never a caller-controlled field. It is appended by the lane only
+ * on the two BPAU-00B identity commands and on the already-JSON reads.
+ *
+ * Schemas live in this lane-owned file so tests can load them without
+ * `@bb/plugin-sdk` and without importing any BPAU-07A-reserved module.
+ */
+
+import { z } from 'zod';
+import { planningWorkspaceProjectionSchema } from './planning-workspace-schema.js';
+import { repositorySchema } from './repository-schema.js';
+import { getTaskDetailOutputSchema } from './task-detail-schema.js';
+
+export const SPRINT_COMPOSITION_OUTCOME_VERSION = '1.0.0' as const;
+
+/**
+ * Closed sprint-composition vocabulary. Product names, not CLI subcommand
+ * names: `addSprintWorkFromBacklog` creates a new task from an existing backlog
+ * item and attaches it, and is never an "attach existing task" action.
+ */
+export const SPRINT_COMPOSITION_VOCABULARY = [
+  'createSprint',
+  'renameSprint',
+  'addSprintWorkFromBacklog',
+  'removeSprintTask',
+  'migrateSprintTask',
+] as const;
+
+export type SprintCompositionAction = (typeof SPRINT_COMPOSITION_VOCABULARY)[number];
+
+/** Actions that mint a new Poetic-minted identity. */
+export const SPRINT_COMPOSITION_NEW_IDENTITY_ACTIONS = [
+  'createSprint',
+  'addSprintWorkFromBacklog',
+] as const;
+
+/** Actions that change sprint membership. */
+export const SPRINT_COMPOSITION_MEMBERSHIP_ACTIONS = [
+  'addSprintWorkFromBacklog',
+  'removeSprintTask',
+  'migrateSprintTask',
+] as const;
+
+/**
+ * A managed planning id addresses one file under a managed bucket, so it must be
+ * a single safe path component: no separators, no traversal, and no leading dot
+ * or dash that could read as a hidden file or a CLI flag.
+ */
+export const managedPlanningIdSchema = z
+  .string()
+  .min(1)
+  .max(200)
+  .regex(
+    /^[A-Za-z0-9][A-Za-z0-9._-]*$/,
+    'A managed planning id must be a single safe path component.'
+  );
+
+/**
+ * Free text carried in a single `--flag=value` token. The exact value `-` is
+ * rejected because Poetic reads it as the stdin sentinel.
+ */
+const flagTextSchema = z
+  .string()
+  .trim()
+  .min(1)
+  .max(4_000)
+  .refine((value) => value !== '-', 'Free text must not be the stdin sentinel "-".');
+
+/**
+ * Free text bound to a positional argument. A positional cannot use the
+ * `--flag=value` form, so a leading dash could be parsed as another option and
+ * is rejected in the schema instead of being escaped with `--`.
+ */
+const positionalTextSchema = flagTextSchema.refine(
+  (value) => !value.startsWith('-'),
+  'Positional text must not begin with "-".'
+);
+
+const isoDateSchema = z
+  .string()
+  .regex(/^\d{4}-\d{2}-\d{2}$/, 'A sprint date must be an ISO calendar date (YYYY-MM-DD).');
+
+const prioritySchema = z.enum(['P0', 'P1', 'P2', 'P3']);
+
+/** Estimate hours: Poetic refuses a non-positive estimate, so BB never sends one. */
+const estimateHoursSchema = z.number().finite().positive().max(10_000);
+
+const capacityHoursSchema = z.number().finite().positive().max(100_000);
+
+const runtimeMinutesSchema = z.number().int().positive().max(1_000_000);
+
+/**
+ * Consent every sprint-composition mutation must acknowledge. Each field is a
+ * required `true` literal inside a strict object, so partial or false consent
+ * fails schema validation rather than degrading into a silent default.
+ *
+ * This lane declares its own copy on purpose (frozen contract §5): BPAU-01,
+ * BPAU-02, and BPAU-03 must not share a consent module, and BPAU-07A must not
+ * consolidate them inside BPAU.
+ */
+export const sprintCompositionConsentSchema = z
+  .object({
+    hostExecution: z.literal(true),
+    managedPlanningMutation: z.literal(true),
+    automaticCommitAndPush: z.literal(true),
+    selectedRepositoryAndBranch: z.literal(true),
+  })
+  .strict();
+
+/** Additive consent for actions that mint a new Poetic id. */
+export const sprintCompositionNewIdentityConsentSchema = sprintCompositionConsentSchema
+  .extend({ newIdentityCreation: z.literal(true) })
+  .strict();
+
+/** Additive consent for actions that move sprint membership. */
+export const sprintCompositionMembershipConsentSchema = sprintCompositionConsentSchema
+  .extend({ sprintMembershipChange: z.literal(true) })
+  .strict();
+
+/** `addSprintWorkFromBacklog` both mints a task id and changes membership. */
+export const sprintCompositionNewMembershipConsentSchema = sprintCompositionConsentSchema
+  .extend({
+    newIdentityCreation: z.literal(true),
+    sprintMembershipChange: z.literal(true),
+  })
+  .strict();
+
+/**
+ * What the caller believed when it built the request. The service re-checks all
+ * of it against fresh canonical evidence immediately before spawning, so a moved
+ * checkout, a switched branch, or drifted membership is refused rather than
+ * mutated blind. There is no `cwd`, `env`, `executable`, or `argv` field: the
+ * repository path here is compared, never spawned into.
+ */
+export const sprintCompositionExpectedSchema = z
+  .object({
+    repositoryPath: z.string().min(1),
+    branch: z.string().min(1).nullable(),
+    entityIds: z.array(managedPlanningIdSchema).max(16),
+    /** Sprint membership as last read, or an empty list when not observed. */
+    observedMembership: z.array(managedPlanningIdSchema).max(2_000),
+  })
+  .strict();
+
+const requestTargetFields = {
+  projectId: z.string().min(1),
+  sourceId: z.string().min(1),
+  expected: sprintCompositionExpectedSchema,
+} as const;
+
+/**
+ * Closed discriminated `applySprintComposition` request.
+ *
+ * `createSprint` has no `--dry-run`/`--verbose` field; `addSprintWorkFromBacklog`
+ * requires an explicit estimate rather than relying on Poetic's 4h default and
+ * has no splitting, provider, model, or hint field; `migrateSprintTask` names its
+ * source sprint so consent, admission, and the reread can all be explicit even
+ * though the CLI argv does not carry it.
+ */
+export const applySprintCompositionInputSchema = z.discriminatedUnion('action', [
+  z
+    .object({
+      ...requestTargetFields,
+      action: z.literal('createSprint'),
+      input: z
+        .object({
+          name: flagTextSchema,
+          start: isoDateSchema,
+          end: isoDateSchema,
+          goal: flagTextSchema.optional(),
+          hours: capacityHoursSchema.optional(),
+        })
+        .strict(),
+      consent: sprintCompositionNewIdentityConsentSchema,
+    })
+    .strict(),
+  z
+    .object({
+      ...requestTargetFields,
+      action: z.literal('renameSprint'),
+      input: z
+        .object({
+          sprintId: managedPlanningIdSchema,
+          name: positionalTextSchema,
+        })
+        .strict(),
+      consent: sprintCompositionConsentSchema,
+    })
+    .strict(),
+  z
+    .object({
+      ...requestTargetFields,
+      action: z.literal('addSprintWorkFromBacklog'),
+      input: z
+        .object({
+          sprintId: managedPlanningIdSchema,
+          backlogItemId: managedPlanningIdSchema,
+          estimate: estimateHoursSchema,
+          expectedRuntimeMinutes: runtimeMinutesSchema.optional(),
+          priority: prioritySchema.optional(),
+        })
+        .strict(),
+      consent: sprintCompositionNewMembershipConsentSchema,
+    })
+    .strict(),
+  z
+    .object({
+      ...requestTargetFields,
+      action: z.literal('removeSprintTask'),
+      input: z
+        .object({
+          sprintId: managedPlanningIdSchema,
+          taskId: managedPlanningIdSchema,
+        })
+        .strict(),
+      consent: sprintCompositionMembershipConsentSchema,
+    })
+    .strict(),
+  z
+    .object({
+      ...requestTargetFields,
+      action: z.literal('migrateSprintTask'),
+      input: z
+        .object({
+          taskId: managedPlanningIdSchema,
+          sourceSprintId: managedPlanningIdSchema,
+          targetSprintId: managedPlanningIdSchema,
+        })
+        .strict(),
+      consent: sprintCompositionMembershipConsentSchema,
+    })
+    .strict(),
+]);
+
+export type ApplySprintCompositionInput = z.infer<typeof applySprintCompositionInputSchema>;
+
+/**
+ * Lane disclosure. Every field is a literal so the type system, not prose,
+ * states that sprint composition never launches Fusion, never starts tracked
+ * backlog execution, never opens a pull request, never cancels a run, and never
+ * reaches the task lifecycle vocabulary.
+ */
+export const sprintCompositionDisclosureSchema = z
+  .object({
+    fullTrust: z.literal(true),
+    hostEquivalentExecution: z.literal(true),
+    providerAuth: z.literal('native'),
+    planningSync: z.literal(true),
+    gitCommits: z.literal(true),
+    gitPush: z.literal(true),
+    managedPlanningMutation: z.literal(true),
+    pullRequestCreation: z.literal(false),
+    fusionLaunch: z.literal(false),
+    trackedBacklogExecution: z.literal(false),
+    runCancellation: z.literal(false),
+    taskLifecycleTransition: z.literal(false),
+    summary: z.string(),
+  })
+  .strict();
+
+/** BPAU-00B `sprintCreateV1` identity envelope. */
+export const sprintCreateEnvelopeSchema = z
+  .object({
+    schemaVersion: z.string().min(1),
+    state: z.enum(['created', 'overlap-conflict', 'refused-invalid']),
+    sprintId: z.string().min(1).nullable(),
+    name: z.string(),
+    startDate: z.string(),
+    endDate: z.string(),
+    capacity: z.object({ totalHours: z.number().nullable() }).strict(),
+    fileCreated: z.boolean(),
+    sync: z.literal('refused-branch').optional(),
+    conflictingSprintId: z.string().min(1).optional(),
+    recoveryText: z.string().optional(),
+  })
+  .strict();
+
+/** BPAU-00B `sprintAddTaskV1` identity envelope (non-split only). */
+export const sprintAddTaskEnvelopeSchema = z
+  .object({
+    schemaVersion: z.string().min(1),
+    state: z.enum([
+      'added',
+      'refused-unfilled-markers',
+      'refused-duplicate-backlog',
+      'refused-capacity',
+      'refused-invalid',
+      'failed-after-partial-effect',
+      'unknown-after-timeout',
+    ]),
+    taskId: z.string().min(1).nullable(),
+    sprintId: z.string().min(1),
+    backlogItemId: z.string().min(1),
+    estimatedHours: z.number(),
+    estimateSource: z.enum(['flag', 'default-4h']),
+    fileCreated: z.boolean(),
+    sync: z.literal('refused-branch').optional(),
+    membershipApplied: z.boolean(),
+    capacity: z
+      .object({
+        allocatedHours: z.number().nullable(),
+        totalHours: z.number().nullable(),
+      })
+      .strict(),
+    capacityWarningLevel: z.union([z.null(), z.literal('warning')]),
+  })
+  .strict();
+
+/**
+ * Structured identity evidence, or null for the three actions that mint nothing.
+ * A missing, malformed, or inconsistent envelope is never replaced by the newest
+ * list row: the service reports `ambiguous` instead.
+ */
+export const sprintCompositionIdentityOutcomeSchema = z
+  .discriminatedUnion('kind', [
+    z.object({ kind: z.literal('sprintCreateV1'), value: sprintCreateEnvelopeSchema }).strict(),
+    z.object({ kind: z.literal('sprintAddTaskV1'), value: sprintAddTaskEnvelopeSchema }).strict(),
+  ])
+  .nullable();
+
+/** One sprint row from `plan sprint list --json`, carried verbatim. */
+export const sprintSummarySchema = z
+  .object({
+    id: z.string().min(1),
+    name: z.string(),
+    status: z.string(),
+    startDate: z.string(),
+    endDate: z.string(),
+    taskCount: z.number().int().nonnegative(),
+    capacity: z
+      .object({
+        allocatedHours: z.number(),
+        totalHours: z.number(),
+        utilizationPercent: z.number(),
+      })
+      .strict(),
+  })
+  .strict();
+
+export const sprintListScopeSchema = z.enum(['all', 'current', 'archived']);
+
+/** `plan sprint list [--current|--archived] --json` payload. */
+export const sprintListEnvelopeSchema = z
+  .object({
+    scope: sprintListScopeSchema,
+    total: z.number().int().nonnegative(),
+    sprints: z.array(sprintSummarySchema),
+  })
+  .strict();
+
+/**
+ * `plan sprint status <sprint-id> --json` payload: Poetic-computed membership,
+ * capacity, readiness, and integrity. None of it is recomputed in BB.
+ */
+export const sprintStatusEnvelopeSchema = z
+  .object({
+    sprintId: z.string().min(1),
+    name: z.string(),
+    status: z.string(),
+    archived: z.boolean(),
+    startDate: z.string().optional(),
+    endDate: z.string().optional(),
+    goal: z.string().optional(),
+    capacity: z
+      .object({
+        allocatedHours: z.number(),
+        totalHours: z.number(),
+        utilizationPercent: z.number(),
+      })
+      .strict(),
+    completedCapacity: z
+      .object({
+        activeDoneHours: z.number(),
+        archivedDoneHours: z.number(),
+        totalDoneHours: z.number(),
+        archivedTaskCount: z.number().int().nonnegative(),
+      })
+      .strict(),
+    progress: z
+      .object({
+        todo: z.number().int().nonnegative(),
+        in_progress: z.number().int().nonnegative(),
+        review: z.number().int().nonnegative(),
+        done: z.number().int().nonnegative(),
+        blocked: z.number().int().nonnegative(),
+        cancelled: z.number().int().nonnegative(),
+        total: z.number().int().nonnegative(),
+        allDone: z.boolean(),
+        allTerminal: z.boolean(),
+        integrityClean: z.boolean(),
+        closable: z.boolean(),
+      })
+      .strict(),
+    tasks: z.array(
+      z
+        .object({
+          id: z.string().min(1),
+          title: z.string(),
+          status: z.string(),
+          estimatedHours: z.number(),
+          expectedRuntimeMinutes: z.number().optional(),
+          resultArtifactPath: z.string().optional(),
+        })
+        .strict()
+    ),
+    missingTaskIds: z.array(z.string()),
+  })
+  .strict();
+
+/** Minimal backlog identity confirmation from `plan backlog show <id> --json`. */
+export const backlogIdentityEnvelopeSchema = z.object({ id: z.string().min(1) });
+
+/** Available-or-unavailable evidence; an unavailable member never reads as healthy. */
+export function sprintCompositionEvidenceSchema<T extends z.ZodType>(value: T) {
+  return z.discriminatedUnion('state', [
+    z.object({ state: z.literal('available'), value }).strict(),
+    z.object({ state: z.literal('unavailable'), reason: z.string().min(1) }).strict(),
+  ]);
+}
+
+export type SprintCompositionEvidence<T> =
+  | { state: 'available'; value: T }
+  | { state: 'unavailable'; reason: string };
+
+/**
+ * The authoritative reread set (frozen contract §6). Only the members the action
+ * actually rereads are present; a failed reread is an `unavailable` member and
+ * never converts an applied mutation into a failure.
+ */
+export const sprintCompositionRereadsSchema = z
+  .object({
+    sprints: sprintCompositionEvidenceSchema(sprintListEnvelopeSchema).optional(),
+    sprint: sprintCompositionEvidenceSchema(sprintStatusEnvelopeSchema).optional(),
+    sourceSprint: sprintCompositionEvidenceSchema(sprintStatusEnvelopeSchema).optional(),
+    targetSprint: sprintCompositionEvidenceSchema(sprintStatusEnvelopeSchema).optional(),
+    task: sprintCompositionEvidenceSchema(getTaskDetailOutputSchema).optional(),
+    backlogItem: sprintCompositionEvidenceSchema(backlogIdentityEnvelopeSchema).optional(),
+  })
+  .strict();
+
+/**
+ * Evidence about the single invocation only.
+ *
+ * `state` gains `timed_out` and `ambiguous` over the shipped task-action
+ * evidence because an `add-task` attach failure is genuinely undetermined
+ * without the structured envelope and must render as neither success nor
+ * "nothing happened". `attempts` is a literal 1: nothing is retried.
+ * `remoteSyncConfirmedByExitCode` is a literal false, so exit 0 can never be
+ * rendered as confirmed remote synchronization.
+ */
+export const sprintCompositionCommandEvidenceSchema = z
+  .object({
+    state: z.enum(['succeeded', 'failed', 'timed_out', 'ambiguous']),
+    attempts: z.literal(1),
+    argv: z.array(z.string().min(1)),
+    exitCode: z.number().int().nullable(),
+    diagnostics: z.string().nullable(),
+    remoteSyncConfirmedByExitCode: z.literal(false),
+  })
+  .strict();
+
+/**
+ * Explicit effect phase. It is reported, never inferred by a consumer from an
+ * exit code, and `overlap-conflict` stays a distinct outcome rather than a
+ * generic failure.
+ */
+export const sprintCompositionEffectPhaseSchema = z.enum([
+  'refused-before-launch',
+  'refused-before-effect',
+  'applied',
+  'applied-incomplete',
+  'failed-after-partial-effect',
+  'overlap-conflict',
+  'unknown-after-timeout',
+]);
+
+/**
+ * Sync state as reported, never as proven. Poetic's managed sync commits and
+ * pushes; BB derives this only from a fresh planning-workspace reread. This lane
+ * never emits `skipped_incomplete` (that is the backlog-create shape in
+ * BPAU-01); the vocabulary is shared and frozen.
+ */
+export const sprintCompositionSyncStateSchema = z.enum([
+  'not_attempted',
+  'skipped_incomplete',
+  'remote_verified',
+  'local_commit_only',
+  'failed',
+  'unknown',
+]);
+
+export const applySprintCompositionOutputSchema = z
+  .object({
+    outcomeVersion: z.literal(SPRINT_COMPOSITION_OUTCOME_VERSION),
+    repository: repositorySchema,
+    disclosure: sprintCompositionDisclosureSchema,
+    action: z.enum(SPRINT_COMPOSITION_VOCABULARY),
+    requestedIdentities: z.array(z.string().min(1)),
+    command: sprintCompositionCommandEvidenceSchema,
+    identityOutcome: sprintCompositionIdentityOutcomeSchema,
+    effect: z
+      .object({
+        phase: sprintCompositionEffectPhaseSchema,
+        createdIdentities: z.array(z.string().min(1)),
+        affectedIdentities: z.array(z.string().min(1)),
+      })
+      .strict(),
+    sync: z
+      .object({
+        state: sprintCompositionSyncStateSchema,
+        detail: z.string().nullable(),
+      })
+      .strict(),
+    syncWarnings: z.array(z.string()),
+    integrityNotes: z.array(z.string()),
+    canonicalRereads: sprintCompositionRereadsSchema,
+    workspace: sprintCompositionEvidenceSchema(planningWorkspaceProjectionSchema),
+  })
+  .strict();
+
+export type ApplySprintCompositionOutput = z.infer<typeof applySprintCompositionOutputSchema>;
+
+/** Read-only multi-sprint enumeration request. Carries no consent. */
+export const listSprintsInputSchema = z
+  .object({
+    projectId: z.string().min(1),
+    sourceId: z.string().min(1),
+    scope: sprintListScopeSchema.optional(),
+  })
+  .strict();
+
+/** Read-only single-sprint projection request. Always names an explicit id. */
+export const getSprintInputSchema = z
+  .object({
+    projectId: z.string().min(1),
+    sourceId: z.string().min(1),
+    sprintId: managedPlanningIdSchema,
+  })
+  .strict();
+
+export const listSprintsOutputSchema = z
+  .object({
+    repository: repositorySchema,
+    scope: sprintListScopeSchema,
+    sprints: sprintCompositionEvidenceSchema(sprintListEnvelopeSchema),
+  })
+  .strict();
+
+export const getSprintOutputSchema = z
+  .object({
+    repository: repositorySchema,
+    sprintId: managedPlanningIdSchema,
+    sprint: sprintCompositionEvidenceSchema(sprintStatusEnvelopeSchema),
+    integrityNotes: z.array(z.string()),
+  })
+  .strict();
+
+export type ListSprintsInput = z.infer<typeof listSprintsInputSchema>;
+export type ListSprintsOutput = z.infer<typeof listSprintsOutputSchema>;
+export type GetSprintInput = z.infer<typeof getSprintInputSchema>;
+export type GetSprintOutput = z.infer<typeof getSprintOutputSchema>;
+export type SprintListEnvelope = z.infer<typeof sprintListEnvelopeSchema>;
+export type SprintStatusEnvelope = z.infer<typeof sprintStatusEnvelopeSchema>;
+export type SprintCreateEnvelope = z.infer<typeof sprintCreateEnvelopeSchema>;
+export type SprintAddTaskEnvelope = z.infer<typeof sprintAddTaskEnvelopeSchema>;
+export type SprintCompositionIdentityOutcome = z.infer<
+  typeof sprintCompositionIdentityOutcomeSchema
+>;
+export type SprintCompositionRereads = z.infer<typeof sprintCompositionRereadsSchema>;
+export type SprintCompositionEffectPhase = z.infer<typeof sprintCompositionEffectPhaseSchema>;
+export type SprintCompositionSyncState = z.infer<typeof sprintCompositionSyncStateSchema>;
+
+/**
+ * Frozen method surfaces for the BPAU-07A registration delta. Declaring them
+ * here keeps the request/outcome contract in this lane; 07A reads the live
+ * `LIVE_POETIC_RPC_METHODS` and registers these names.
+ */
+export const applySprintCompositionMethod = {
+  input: applySprintCompositionInputSchema,
+  output: applySprintCompositionOutputSchema,
+} as const;
+
+export const listSprintsMethod = {
+  input: listSprintsInputSchema,
+  output: listSprintsOutputSchema,
+} as const;
+
+export const getSprintMethod = {
+  input: getSprintInputSchema,
+  output: getSprintOutputSchema,
+} as const;