@poetic-ai/poetic 1.42.0

package/integrations/bb-plugin-poetic/src/backlog-authoring-view.ts

@@ -0,0 +1,1026 @@
+/**
+ * Pure BB presentation and interaction for backlog authoring over BPAU-01.
+ *
+ * This module is presentation only. It composes forms, proportionate
+ * confirmations, and one typed BPAU-01 request per confirmed submission, and it
+ * renders the outcome BPAU-01 returned. It holds the same authority boundary the
+ * rest of this plugin holds:
+ *
+ *   - Poetic is authoritative. Nothing here predicts a resulting status,
+ *     completeness score, identity, priority, or sync state, and nothing here
+ *     re-labels one Poetic published.
+ *   - Changed facts are displayed only from Poetic's own authoritative reread.
+ *     While that reread is unavailable the view reports `awaiting-reread`
+ *     instead of echoing the values BB submitted.
+ *   - Absent evidence renders as an explicit `unavailable`. A missing field is
+ *     never replaced by a default, a guess, or an empty success state.
+ *   - Nothing here runs a command, touches the filesystem, reads Git, or
+ *     mutates managed planning state. Every function is deterministic in its
+ *     inputs; the BPAU-01 service owns execution.
+ *
+ * Scope is create, whitelisted update, review, and prioritize only. There is no
+ * defer/parking, archive, execution, finalization, optimistic state, or retry
+ * here, and this module wires no application shell.
+ */
+
+import type {
+  BacklogAuthoringOutcome,
+  BacklogAuthoringResult,
+  BacklogDetailEvidence,
+  BacklogEvidence,
+} from './backlog-authoring-model.js';
+import {
+  type BacklogAuthoringRequest,
+  backlogAuthoringRequestSchema,
+} from './backlog-authoring-schema.js';
+
+export const BACKLOG_AUTHORING_VIEW_VERSION = '1.0.0' as const;
+
+/**
+ * Bound on any single emitted row value, mirroring the sibling view modules.
+ *
+ * Disclosures, notes, sync warnings, and Poetic's own diagnostics are never
+ * truncated: shortening a consent disclosure or a warning Poetic published would
+ * hide part of what the operator is being told.
+ */
+export const BACKLOG_AUTHORING_MAX_LINE_CHARS = 200;
+
+/** Plain label for evidence Poetic did not publish. */
+const UNAVAILABLE = 'unavailable';
+
+export type BacklogAuthoringAction = BacklogAuthoringRequest['action'];
+type BacklogAuthoringConsentPayload = BacklogAuthoringRequest['consent'];
+/** One request per action with its consent removed, distributed over the union. */
+type BacklogRequestDraft = BacklogAuthoringRequest extends infer Request
+  ? Request extends { consent: unknown }
+    ? Omit<Request, 'consent'>
+    : never
+  : never;
+type BacklogPriority = Extract<
+  BacklogAuthoringRequest,
+  { action: 'prioritizeBacklogItem' }
+>['input']['priority'];
+
+export interface BacklogAuthoringRow {
+  /** Stable row id, usable as a render key. */
+  id: string;
+  label: string;
+  value: string;
+}
+
+/** The repository and branch one form is bound to, as BB selected them. */
+export interface BacklogAuthoringTarget {
+  projectId: string;
+  sourceId: string;
+  repositoryPath: string;
+  /** Null when Poetic reports no named branch; authoring is then unavailable. */
+  branch: string | null;
+}
+
+function truncateLine(text: string): string {
+  const normalized = text.replace(/\s+/g, ' ').trim();
+  if (normalized.length <= BACKLOG_AUTHORING_MAX_LINE_CHARS) return normalized;
+  return `${normalized.slice(0, BACKLOG_AUTHORING_MAX_LINE_CHARS - 3)}...`;
+}
+
+function row(id: string, label: string, value: string): BacklogAuthoringRow {
+  return { id, label, value: truncateLine(value) };
+}
+
+function normalizeTags(tags: readonly string[] | undefined): string[] {
+  if (tags === undefined) return [];
+  const present = tags.map((tag) => tag.trim()).filter((tag) => tag.length > 0);
+  return [...new Set(present)];
+}
+
+/** Control labels. Each names the one product it submits. */
+export const BACKLOG_AUTHORING_LABELS: Readonly<Record<BacklogAuthoringAction, string>> = {
+  createBacklogItem: 'Capture backlog item',
+  updateBacklogItem: 'Edit backlog item',
+  reviewBacklogItem: 'Mark backlog item reviewed',
+  prioritizeBacklogItem: 'Set backlog item priority',
+};
+
+/**
+ * What each command is asked to do. These describe the request, never a
+ * predicted result, and each one names what it does not do so an authoring
+ * control can never read as execution or archival.
+ */
+export const BACKLOG_AUTHORING_EFFECTS: Readonly<Record<BacklogAuthoringAction, string>> = {
+  createBacklogItem:
+    'Asks Poetic to create a new backlog item from the sections you entered. Poetic mints the id and scores completeness. Nothing is executed, deferred, or archived.',
+  updateBacklogItem:
+    'Asks Poetic to update only the backlog fields you changed. It sets no status, and it never defers, archives, or executes the item.',
+  reviewBacklogItem:
+    'Asks Poetic to mark this backlog item reviewed. It changes no priority and executes nothing.',
+  prioritizeBacklogItem:
+    'Asks Poetic to set this backlog item priority. Poetic decides the resulting status; nothing is executed.',
+};
+
+/**
+ * Whole-body replacement disclosure, stated once. A backlog update sends
+ * `--body`, which replaces the entire item body rather than one section, so this
+ * copy must never read as a partial edit.
+ */
+export const BACKLOG_FULL_BODY_REPLACEMENT_NOTICE =
+  'Saving replaces the entire body of this backlog item with the text above, including any section Poetic itself added. The editor was prepopulated from the current canonical body; BB will not submit a replacement it could not prepopulate.';
+
+/**
+ * Prioritize can promote an inbox item, which is a launch-eligibility change and
+ * is disclosed as one before submission.
+ */
+export const BACKLOG_PRIORITIZE_LAUNCH_ELIGIBILITY_NOTICE =
+  'Setting a priority may also move an inbox item to reviewed, which can make it launch-eligible for execution. Poetic decides the resulting status; BB reports only what Poetic rereads afterwards.';
+
+export const BACKLOG_REVIEW_LAUNCH_ELIGIBILITY_NOTICE =
+  'Marking this item reviewed can make it launch-eligible for execution. Poetic decides the resulting status; BB reports only what Poetic rereads afterwards.';
+
+export const BACKLOG_CAPTURE_COMPLETENESS_NOTICE =
+  'Poetic scores completeness after creation. An incomplete item is still created; Poetic then reports what is missing and the refine command that finishes it.';
+
+/** Consent checkboxes exactly as the operator left them; plain booleans. */
+export interface BacklogAuthoringConsentState {
+  hostExecution: boolean;
+  managedPlanningMutation: boolean;
+  automaticCommitAndPush: boolean;
+  selectedRepositoryAndBranch: boolean;
+  /** Required for capture only. */
+  newIdentityCreation: boolean;
+  /** Required for review and prioritize only. */
+  launchEligibilityChange: boolean;
+  /** Required when an update replaces the whole body. */
+  fullSectionReplacement: boolean;
+}
+
+export const EMPTY_BACKLOG_AUTHORING_CONSENT: Readonly<BacklogAuthoringConsentState> = {
+  hostExecution: false,
+  managedPlanningMutation: false,
+  automaticCommitAndPush: false,
+  selectedRepositoryAndBranch: false,
+  newIdentityCreation: false,
+  launchEligibilityChange: false,
+  fullSectionReplacement: false,
+};
+
+export const BACKLOG_AUTHORING_CONSENT_LABELS: Readonly<
+  Record<keyof BacklogAuthoringConsentState, string>
+> = {
+  hostExecution: 'Poetic runs as my host user in the repository shown above.',
+  managedPlanningMutation: 'This mutates managed planning state that Poetic owns.',
+  automaticCommitAndPush:
+    "Poetic's built-in managed sync commits and pushes these planning changes.",
+  selectedRepositoryAndBranch: 'I mean this repository path and this branch.',
+  newIdentityCreation: 'A new Poetic-minted backlog id will exist after this action.',
+  launchEligibilityChange:
+    'This may change launch eligibility: the item can become reviewed and executable.',
+  fullSectionReplacement: 'This replaces the entire body of the backlog item.',
+};
+
+/**
+ * Which acknowledgement lines one action requires, given the fields being sent.
+ * Confirmation is proportionate: an action never collects an acknowledgement for
+ * an effect that is not happening.
+ */
+export function backlogAuthoringRequiredConsentKeys(
+  action: BacklogAuthoringAction,
+  replacesBody = false
+): Array<keyof BacklogAuthoringConsentState> {
+  const base: Array<keyof BacklogAuthoringConsentState> = [
+    'hostExecution',
+    'managedPlanningMutation',
+    'automaticCommitAndPush',
+    'selectedRepositoryAndBranch',
+  ];
+  switch (action) {
+    case 'createBacklogItem':
+      return [...base, 'newIdentityCreation'];
+    case 'updateBacklogItem':
+      return replacesBody ? [...base, 'fullSectionReplacement'] : base;
+    default:
+      return [...base, 'launchEligibilityChange'];
+  }
+}
+
+/**
+ * Convert collected consent into the exact shape the BPAU-01 schema requires, or
+ * null when the acknowledgement is incomplete. Returning null is the enforcement
+ * point: no request is emitted without proportionate consent, and no literal is
+ * added for an effect that is not happening.
+ */
+function backlogAuthoringConsentPayload(
+  action: BacklogAuthoringAction,
+  replacesBody: boolean,
+  consent: BacklogAuthoringConsentState
+): BacklogAuthoringConsentPayload | null {
+  if (backlogAuthoringRequiredConsentKeys(action, replacesBody).some((key) => !consent[key])) {
+    return null;
+  }
+  const base = {
+    hostExecution: true,
+    managedPlanningMutation: true,
+    automaticCommitAndPush: true,
+    selectedRepositoryAndBranch: true,
+  } as const;
+  switch (action) {
+    case 'createBacklogItem':
+      return { ...base, newIdentityCreation: true };
+    case 'updateBacklogItem':
+      return replacesBody ? { ...base, fullSectionReplacement: true } : base;
+    default:
+      return { ...base, launchEligibilityChange: true };
+  }
+}
+
+function outstandingConsentLabels(
+  action: BacklogAuthoringAction,
+  replacesBody: boolean,
+  consent: BacklogAuthoringConsentState
+): string[] {
+  return backlogAuthoringRequiredConsentKeys(action, replacesBody)
+    .filter((key) => !consent[key])
+    .map((key) => BACKLOG_AUTHORING_CONSENT_LABELS[key]);
+}
+
+/** The required inline sections of a complete backlog body. */
+export interface BacklogCaptureSectionSpec {
+  id: 'scope' | 'acceptance-criteria' | 'how-to-verify';
+  /** Heading Poetic's completeness check looks for, on its own line. */
+  heading: string;
+  label: string;
+  field: 'scope' | 'acceptanceCriteria' | 'howToVerify';
+}
+
+export const BACKLOG_CAPTURE_SECTIONS: readonly BacklogCaptureSectionSpec[] = [
+  {
+    id: 'scope',
+    heading: '## Scope / Surfaces Affected',
+    label: 'Scope / surfaces affected',
+    field: 'scope',
+  },
+  {
+    id: 'acceptance-criteria',
+    heading: '## Acceptance Criteria',
+    label: 'Acceptance criteria',
+    field: 'acceptanceCriteria',
+  },
+  {
+    id: 'how-to-verify',
+    heading: '## How to Verify',
+    label: 'How to verify',
+    field: 'howToVerify',
+  },
+];
+
+/** Capture form state exactly as the operator left it. */
+export interface BacklogCaptureDraft {
+  title: string;
+  summary: string;
+  scope: string;
+  acceptanceCriteria: string;
+  howToVerify: string;
+  priority?: BacklogPriority;
+  declaredType?: string;
+  tags?: readonly string[];
+  complexity?: number;
+  domain?: string;
+  expectedRuntimeMinutes?: number;
+}
+
+export const EMPTY_BACKLOG_CAPTURE_DRAFT: Readonly<BacklogCaptureDraft> = {
+  title: '',
+  summary: '',
+  scope: '',
+  acceptanceCriteria: '',
+  howToVerify: '',
+};
+
+/**
+ * Compose the complete inline markdown body from the collected sections. Every
+ * required heading is emitted on its own line so Poetic's own completeness check
+ * reads the body BB submitted; BB never scores completeness itself.
+ */
+export function composeBacklogCaptureBody(draft: BacklogCaptureDraft): string {
+  const blocks: string[] = [];
+  const summary = draft.summary.trim();
+  if (summary.length > 0) blocks.push(summary);
+  for (const section of BACKLOG_CAPTURE_SECTIONS) {
+    blocks.push(`${section.heading}\n\n${draft[section.field].trim()}`);
+  }
+  return blocks.join('\n\n');
+}
+
+function numberProblems(
+  complexity: number | undefined,
+  expectedRuntimeMinutes: number | undefined
+): string[] {
+  const problems: string[] = [];
+  if (
+    complexity !== undefined &&
+    (!Number.isFinite(complexity) || complexity < 0 || complexity > 1)
+  ) {
+    problems.push('Complexity must be a number between 0 and 1.');
+  }
+  if (
+    expectedRuntimeMinutes !== undefined &&
+    (!Number.isInteger(expectedRuntimeMinutes) || expectedRuntimeMinutes <= 0)
+  ) {
+    problems.push('Expected runtime must be a whole number of minutes above zero.');
+  }
+  return problems;
+}
+
+/**
+ * What the operator must still supply or correct before capture can be
+ * submitted. This is input validation only: it never scores completeness, which
+ * is Poetic's own result reported after creation.
+ */
+export function backlogCaptureMissingFields(draft: BacklogCaptureDraft): string[] {
+  const missing: string[] = [];
+  const title = draft.title.trim();
+  if (title.length === 0) missing.push('Title');
+  else if (title === '-' || title.startsWith('-')) {
+    missing.push('Title must not begin with a dash.');
+  }
+  for (const section of BACKLOG_CAPTURE_SECTIONS) {
+    if (draft[section.field].trim().length === 0) missing.push(section.label);
+  }
+  missing.push(...numberProblems(draft.complexity, draft.expectedRuntimeMinutes));
+  return missing;
+}
+
+/** Whitelisted update fields. Body replacement has its own prepopulated form. */
+export interface BacklogFieldUpdateDraft {
+  title?: string;
+  complexity?: number;
+  expectedRuntimeMinutes?: number;
+  domain?: string;
+  rationale?: string;
+  addTags?: readonly string[];
+  removeTags?: readonly string[];
+}
+
+/**
+ * Why a form cannot emit a request yet. `duplicate-submission` and
+ * `invalid-request` mirror BPAU-01 refusal reasons so the operator sees the same
+ * distinction before and after launch.
+ */
+export type BacklogAuthoringSubmissionBlock =
+  | 'target-not-ready'
+  | 'incomplete-input'
+  | 'acknowledgement-incomplete'
+  | 'prepopulation-unavailable'
+  | 'duplicate-submission'
+  | 'invalid-request';
+
+/** Proportionate confirmation shown before one mutation is submitted. */
+export interface BacklogAuthoringConfirmation {
+  /** Repository path and branch always appear in a mutation confirmation. */
+  repositoryPath: string;
+  branch: string;
+  /** What the command is asked to do, never a predicted result. */
+  effect: string;
+  /** Only the acknowledgements this effect actually requires. */
+  acknowledgements: readonly string[];
+  /** Required acknowledgements the operator has not given yet. */
+  outstanding: readonly string[];
+  disclosures: readonly string[];
+}
+
+export interface BacklogAuthoringFormView {
+  viewVersion: typeof BACKLOG_AUTHORING_VIEW_VERSION;
+  action: BacklogAuthoringAction;
+  state: 'blocked' | 'incomplete' | 'ready';
+  headline: string;
+  /** Plain `label: value` rows describing what will be sent. */
+  fields: readonly BacklogAuthoringRow[];
+  /** What the operator must still supply or correct. */
+  missing: readonly string[];
+  confirmation: BacklogAuthoringConfirmation | null;
+  notes: readonly string[];
+  /** Why this form cannot submit; null when it is ready. */
+  blockReason: BacklogAuthoringSubmissionBlock | null;
+  /** The typed BPAU-01 request this form would submit; null until ready. */
+  request: BacklogAuthoringRequest | null;
+}
+
+function blockedForm(
+  action: BacklogAuthoringAction,
+  blockReason: BacklogAuthoringSubmissionBlock,
+  headline: string,
+  notes: readonly string[]
+): BacklogAuthoringFormView {
+  return {
+    viewVersion: BACKLOG_AUTHORING_VIEW_VERSION,
+    action,
+    state: 'blocked',
+    headline,
+    fields: [],
+    missing: [],
+    confirmation: null,
+    notes,
+    blockReason,
+    request: null,
+  };
+}
+
+interface FormBuild {
+  action: BacklogAuthoringAction;
+  target: BacklogAuthoringTarget;
+  consent: BacklogAuthoringConsentState;
+  replacesBody: boolean;
+  fields: readonly BacklogAuthoringRow[];
+  missing: readonly string[];
+  disclosures: readonly string[];
+  notes: readonly string[];
+  /** Request body without consent; consent is attached only when complete. */
+  requestWithoutConsent: (branch: string) => BacklogRequestDraft;
+}
+
+/**
+ * Assemble one form view. The request is emitted only when the input is usable,
+ * the acknowledgements are proportionate and complete, and the resulting payload
+ * still validates against the BPAU-01 request schema, so an invalid request is
+ * never handed to the service.
+ */
+function buildForm(build: FormBuild): BacklogAuthoringFormView {
+  const branch = build.target.branch;
+  if (branch === null || branch.trim().length === 0 || build.target.repositoryPath.length === 0) {
+    return blockedForm(build.action, 'target-not-ready', 'Backlog authoring unavailable', [
+      'Poetic reports no selected repository on a named branch, so no backlog mutation can be confirmed.',
+    ]);
+  }
+
+  const outstanding = outstandingConsentLabels(build.action, build.replacesBody, build.consent);
+  const confirmation: BacklogAuthoringConfirmation = {
+    repositoryPath: build.target.repositoryPath,
+    branch,
+    effect: BACKLOG_AUTHORING_EFFECTS[build.action],
+    acknowledgements: backlogAuthoringRequiredConsentKeys(build.action, build.replacesBody).map(
+      (key) => BACKLOG_AUTHORING_CONSENT_LABELS[key]
+    ),
+    outstanding,
+    disclosures: build.disclosures,
+  };
+
+  const consentPayload = backlogAuthoringConsentPayload(
+    build.action,
+    build.replacesBody,
+    build.consent
+  );
+  let request: BacklogAuthoringRequest | null = null;
+  let blockReason: BacklogAuthoringSubmissionBlock | null = null;
+  if (build.missing.length > 0) blockReason = 'incomplete-input';
+  else if (consentPayload === null) blockReason = 'acknowledgement-incomplete';
+  else {
+    const parsed = backlogAuthoringRequestSchema.safeParse({
+      ...build.requestWithoutConsent(branch),
+      consent: consentPayload,
+    });
+    if (parsed.success) request = parsed.data;
+    else blockReason = 'invalid-request';
+  }
+
+  return {
+    viewVersion: BACKLOG_AUTHORING_VIEW_VERSION,
+    action: build.action,
+    state: request === null ? 'incomplete' : 'ready',
+    headline: BACKLOG_AUTHORING_LABELS[build.action],
+    fields: build.fields,
+    missing: build.missing,
+    confirmation,
+    notes: build.notes,
+    blockReason,
+    request,
+  };
+}
+
+/** Build the capture form for a new backlog item. */
+export function buildBacklogCaptureForm(
+  target: BacklogAuthoringTarget,
+  draft: BacklogCaptureDraft,
+  consent: BacklogAuthoringConsentState
+): BacklogAuthoringFormView {
+  const body = composeBacklogCaptureBody(draft);
+  const tags = normalizeTags(draft.tags);
+  const fields: BacklogAuthoringRow[] = [
+    row('title', 'Title', draft.title.trim().length === 0 ? UNAVAILABLE : draft.title.trim()),
+    row('priority', 'Priority', draft.priority ?? UNAVAILABLE),
+    row('declared-type', 'Type', draft.declaredType?.trim() || UNAVAILABLE),
+    row('tags', 'Tags', tags.length === 0 ? 'none' : tags.join(', ')),
+    row(
+      'complexity',
+      'Complexity',
+      draft.complexity === undefined ? UNAVAILABLE : String(draft.complexity)
+    ),
+    row('domain', 'Domain', draft.domain?.trim() || UNAVAILABLE),
+    row(
+      'expected-runtime',
+      'Expected runtime (minutes)',
+      draft.expectedRuntimeMinutes === undefined
+        ? UNAVAILABLE
+        : String(draft.expectedRuntimeMinutes)
+    ),
+  ];
+  for (const section of BACKLOG_CAPTURE_SECTIONS) {
+    const content = draft[section.field].trim();
+    fields.push(
+      row(`section-${section.id}`, section.label, content.length === 0 ? 'empty' : content)
+    );
+  }
+
+  return buildForm({
+    action: 'createBacklogItem',
+    target,
+    consent,
+    replacesBody: false,
+    fields,
+    missing: backlogCaptureMissingFields(draft),
+    disclosures: [BACKLOG_CAPTURE_COMPLETENESS_NOTICE],
+    notes: [BACKLOG_CAPTURE_COMPLETENESS_NOTICE],
+    requestWithoutConsent: (branch) => ({
+      projectId: target.projectId,
+      sourceId: target.sourceId,
+      action: 'createBacklogItem',
+      input: {
+        title: draft.title.trim(),
+        body,
+        ...(draft.priority === undefined ? {} : { priority: draft.priority }),
+        ...(draft.declaredType?.trim() ? { declaredType: draft.declaredType.trim() } : {}),
+        ...(tags.length === 0 ? {} : { tags }),
+        ...(draft.complexity === undefined ? {} : { complexity: draft.complexity }),
+        ...(draft.domain?.trim() ? { domain: draft.domain.trim() } : {}),
+        ...(draft.expectedRuntimeMinutes === undefined
+          ? {}
+          : { expectedRuntimeMinutes: draft.expectedRuntimeMinutes }),
+      },
+      expected: { repository: target.repositoryPath, branch },
+    }),
+  });
+}
+
+/**
+ * The body editor, prepopulated from Poetic's canonical detail.
+ *
+ * BB refuses a replacement it could not prepopulate: submitting an
+ * unprepopulated editor would silently discard whatever Poetic currently holds.
+ */
+export type BacklogBodyEditor =
+  | { state: 'prepopulated'; backlogItemId: string; canonicalBody: string; body: string }
+  | { state: 'unavailable'; backlogItemId: string; reason: string };
+
+export function buildBacklogBodyEditor(
+  backlogItemId: string,
+  detail: BacklogEvidence<BacklogDetailEvidence>
+): BacklogBodyEditor {
+  if (detail.state === 'unavailable') {
+    return {
+      state: 'unavailable',
+      backlogItemId,
+      reason: `Poetic did not publish the canonical body for backlog item ${backlogItemId} (${detail.reason}), so BB will not replace it.`,
+    };
+  }
+  if (detail.value.id !== backlogItemId) {
+    return {
+      state: 'unavailable',
+      backlogItemId,
+      reason: `Poetic published a body for ${detail.value.id} while BB asked for ${backlogItemId}, so BB will not replace it.`,
+    };
+  }
+  return {
+    state: 'prepopulated',
+    backlogItemId,
+    canonicalBody: detail.value.body,
+    body: detail.value.body,
+  };
+}
+
+/**
+ * Build the whole-body replacement form. `replacementBody` is the edited text;
+ * the canonical body the editor was prepopulated from is carried through as
+ * `expected.canonicalBody` so BPAU-01 can refuse a stale replacement.
+ */
+export function buildBacklogBodyReplacementForm(
+  target: BacklogAuthoringTarget,
+  editor: BacklogBodyEditor,
+  replacementBody: string,
+  consent: BacklogAuthoringConsentState
+): BacklogAuthoringFormView {
+  if (editor.state === 'unavailable') {
+    return blockedForm(
+      'updateBacklogItem',
+      'prepopulation-unavailable',
+      'Body replacement unavailable',
+      [editor.reason]
+    );
+  }
+  const missing = replacementBody.trim().length === 0 ? ['Body'] : [];
+  return buildForm({
+    action: 'updateBacklogItem',
+    target,
+    consent,
+    replacesBody: true,
+    fields: [
+      row('backlog-item', 'Backlog item', editor.backlogItemId),
+      row('body-length', 'Replacement length (characters)', String(replacementBody.length)),
+      row(
+        'body-changed',
+        'Differs from canonical body',
+        replacementBody === editor.canonicalBody ? 'no' : 'yes'
+      ),
+    ],
+    missing,
+    disclosures: [BACKLOG_FULL_BODY_REPLACEMENT_NOTICE],
+    notes: [BACKLOG_FULL_BODY_REPLACEMENT_NOTICE],
+    requestWithoutConsent: (branch) => ({
+      projectId: target.projectId,
+      sourceId: target.sourceId,
+      action: 'updateBacklogItem',
+      input: { backlogItemId: editor.backlogItemId, body: replacementBody },
+      expected: {
+        repository: target.repositoryPath,
+        branch,
+        canonicalBody: editor.canonicalBody,
+      },
+    }),
+  });
+}
+
+/** Build the whitelisted field-update form. No body, so no replacement consent. */
+export function buildBacklogFieldUpdateForm(
+  target: BacklogAuthoringTarget,
+  backlogItemId: string,
+  draft: BacklogFieldUpdateDraft,
+  consent: BacklogAuthoringConsentState
+): BacklogAuthoringFormView {
+  const title = draft.title?.trim();
+  const domain = draft.domain?.trim();
+  const rationale = draft.rationale?.trim();
+  const addTags = normalizeTags(draft.addTags);
+  const removeTags = normalizeTags(draft.removeTags);
+  const input = {
+    backlogItemId,
+    ...(title ? { title } : {}),
+    ...(draft.complexity === undefined ? {} : { complexity: draft.complexity }),
+    ...(draft.expectedRuntimeMinutes === undefined
+      ? {}
+      : { expectedRuntimeMinutes: draft.expectedRuntimeMinutes }),
+    ...(domain ? { domain } : {}),
+    ...(rationale ? { rationale } : {}),
+    ...(addTags.length === 0 ? {} : { addTags }),
+    ...(removeTags.length === 0 ? {} : { removeTags }),
+  };
+  const missing =
+    Object.keys(input).length === 1 ? ['At least one field to change'] : ([] as string[]);
+  missing.push(...numberProblems(draft.complexity, draft.expectedRuntimeMinutes));
+
+  return buildForm({
+    action: 'updateBacklogItem',
+    target,
+    consent,
+    replacesBody: false,
+    fields: [
+      row('backlog-item', 'Backlog item', backlogItemId),
+      row('title', 'Title', title || 'unchanged'),
+      row(
+        'complexity',
+        'Complexity',
+        draft.complexity === undefined ? 'unchanged' : String(draft.complexity)
+      ),
+      row(
+        'expected-runtime',
+        'Expected runtime (minutes)',
+        draft.expectedRuntimeMinutes === undefined
+          ? 'unchanged'
+          : String(draft.expectedRuntimeMinutes)
+      ),
+      row('domain', 'Domain', domain || 'unchanged'),
+      row('rationale', 'Rationale', rationale || 'unchanged'),
+      row('add-tags', 'Tags added', addTags.length === 0 ? 'none' : addTags.join(', ')),
+      row('remove-tags', 'Tags removed', removeTags.length === 0 ? 'none' : removeTags.join(', ')),
+    ],
+    missing,
+    disclosures: [
+      'This edit changes only the fields listed above. The item body is left as Poetic has it.',
+    ],
+    notes: [],
+    requestWithoutConsent: (branch) => ({
+      projectId: target.projectId,
+      sourceId: target.sourceId,
+      action: 'updateBacklogItem',
+      input,
+      expected: { repository: target.repositoryPath, branch },
+    }),
+  });
+}
+
+/** Build the review confirmation, disclosing the launch-eligibility change. */
+export function buildBacklogReviewForm(
+  target: BacklogAuthoringTarget,
+  backlogItemId: string,
+  consent: BacklogAuthoringConsentState
+): BacklogAuthoringFormView {
+  return buildForm({
+    action: 'reviewBacklogItem',
+    target,
+    consent,
+    replacesBody: false,
+    fields: [row('backlog-item', 'Backlog item', backlogItemId)],
+    missing: backlogItemId.trim().length === 0 ? ['Backlog item'] : [],
+    disclosures: [BACKLOG_REVIEW_LAUNCH_ELIGIBILITY_NOTICE],
+    notes: [BACKLOG_REVIEW_LAUNCH_ELIGIBILITY_NOTICE],
+    requestWithoutConsent: (branch) => ({
+      projectId: target.projectId,
+      sourceId: target.sourceId,
+      action: 'reviewBacklogItem',
+      input: { backlogItemId },
+      expected: { repository: target.repositoryPath, branch },
+    }),
+  });
+}
+
+/**
+ * Build the prioritize confirmation. It discloses that an inbox item may become
+ * reviewed and launch-eligible, without predicting the resulting status.
+ */
+export function buildBacklogPrioritizeForm(
+  target: BacklogAuthoringTarget,
+  backlogItemId: string,
+  priority: BacklogPriority,
+  consent: BacklogAuthoringConsentState,
+  currentStatus: string | null = null
+): BacklogAuthoringFormView {
+  return buildForm({
+    action: 'prioritizeBacklogItem',
+    target,
+    consent,
+    replacesBody: false,
+    fields: [
+      row('backlog-item', 'Backlog item', backlogItemId),
+      row('current-status', 'Current status', currentStatus?.trim() || UNAVAILABLE),
+      row('priority', 'Requested priority', priority),
+    ],
+    missing: backlogItemId.trim().length === 0 ? ['Backlog item'] : [],
+    disclosures: [BACKLOG_PRIORITIZE_LAUNCH_ELIGIBILITY_NOTICE],
+    notes: [BACKLOG_PRIORITIZE_LAUNCH_ELIGIBILITY_NOTICE],
+    requestWithoutConsent: (branch) => ({
+      projectId: target.projectId,
+      sourceId: target.sourceId,
+      action: 'prioritizeBacklogItem',
+      input: { backlogItemId, priority },
+      expected: { repository: target.repositoryPath, branch },
+    }),
+  });
+}
+
+export type BacklogAuthoringSubmission =
+  | { state: 'submitted'; request: BacklogAuthoringRequest }
+  | { state: 'blocked'; reason: BacklogAuthoringSubmissionBlock; problems: readonly string[] };
+
+/**
+ * Emit exactly one typed BPAU-01 request from a confirmed form.
+ *
+ * A submission already in flight is refused as a duplicate before anything else
+ * is considered, so a second confirmation never produces a second request. There
+ * is no retry here: a blocked submission reports why and stops.
+ */
+export function submitBacklogAuthoringForm(
+  form: BacklogAuthoringFormView,
+  options: { pending: boolean }
+): BacklogAuthoringSubmission {
+  if (options.pending) {
+    return {
+      state: 'blocked',
+      reason: 'duplicate-submission',
+      problems: [
+        'A backlog authoring submission is already in progress. BB waits for Poetic rather than sending it twice.',
+      ],
+    };
+  }
+  if (form.request !== null) return { state: 'submitted', request: form.request };
+  const reason: BacklogAuthoringSubmissionBlock = form.blockReason ?? 'incomplete-input';
+  const problems =
+    reason === 'acknowledgement-incomplete'
+      ? (form.confirmation?.outstanding ?? [])
+      : form.missing.length > 0
+        ? form.missing
+        : form.notes;
+  return { state: 'blocked', reason, problems };
+}
+
+/** Poetic's own completeness result for a created item, carried through as-is. */
+export interface BacklogCompletenessView {
+  complete: boolean;
+  missing: readonly string[];
+  /** Poetic's refine follow-up; null when Poetic published none. */
+  refineCommand: string | null;
+}
+
+/**
+ * Outcome states. They stay distinct so refusal before launch, a refused command,
+ * a partial effect, and an unknown result after a timeout never read alike.
+ */
+export type BacklogAuthoringOutcomeState =
+  | 'refused'
+  | 'applied'
+  | 'applied-incomplete'
+  | 'refused-before-effect'
+  | 'partial-effect'
+  | 'unknown-after-timeout';
+
+export interface BacklogAuthoringOutcomeView {
+  viewVersion: typeof BACKLOG_AUTHORING_VIEW_VERSION;
+  state: BacklogAuthoringOutcomeState;
+  /** One bounded plain-language summary line. */
+  headline: string;
+  /**
+   * `fresh` only when Poetic's authoritative reread is available. Until then no
+   * changed fact is displayed, and nothing BB submitted is echoed as a result.
+   */
+  facts: 'fresh' | 'awaiting-reread';
+  rows: readonly BacklogAuthoringRow[];
+  /** Poetic's completeness result for a creation; null for other actions. */
+  completeness: BacklogCompletenessView | null;
+  syncWarnings: readonly string[];
+  /** Poetic's own command diagnostics, kept separate from sync evidence. */
+  diagnostics: string | null;
+  notes: readonly string[];
+  degraded: boolean;
+}
+
+const REFUSAL_HEADLINES: Readonly<
+  Record<Extract<BacklogAuthoringResult, { state: 'refused' }>['reason'], string>
+> = {
+  'invalid-request': 'Refused before launch: the request was invalid',
+  'repository-mismatch': 'Refused before launch: the request named another repository',
+  'repository-not-ready': 'Refused before launch: the repository is not ready',
+  'stale-repository': 'Refused before launch: the repository or branch changed',
+  'missing-identity': 'Refused before launch: Poetic could not confirm the backlog item',
+  'canonical-prepopulation-mismatch':
+    'Refused before launch: the canonical body changed after prepopulation',
+  'duplicate-submission': 'Refused before launch: a submission is already in progress',
+};
+
+function outcomeState(outcome: BacklogAuthoringOutcome): BacklogAuthoringOutcomeState {
+  switch (outcome.effect.phase) {
+    case 'applied':
+      return 'applied';
+    case 'applied-incomplete':
+      return 'applied-incomplete';
+    case 'refused-before-launch':
+    case 'refused-before-effect':
+      return 'refused-before-effect';
+    case 'failed-after-partial-effect':
+      return 'partial-effect';
+    case 'unknown-after-timeout':
+      return 'unknown-after-timeout';
+  }
+}
+
+function outcomeHeadline(
+  outcome: BacklogAuthoringOutcome,
+  state: BacklogAuthoringOutcomeState
+): string {
+  const label = BACKLOG_AUTHORING_LABELS[outcome.action];
+  switch (state) {
+    case 'applied':
+      return `${label}: Poetic applied the change`;
+    case 'applied-incomplete':
+      return `${label}: Poetic created the item and reported it incomplete`;
+    case 'refused-before-effect':
+      return `${label}: Poetic refused the command; nothing was changed`;
+    case 'partial-effect':
+      return `${label}: Poetic failed after a partial effect`;
+    default:
+      return `${label}: the command timed out, so its effect is unknown`;
+  }
+}
+
+function changedFactRows(detail: BacklogEvidence<BacklogDetailEvidence>): BacklogAuthoringRow[] {
+  if (detail.state === 'unavailable') return [];
+  const value = detail.value;
+  return [
+    row('reread-id', 'Backlog id (reread)', value.id),
+    row('reread-title', 'Title (reread)', value.title),
+    row('reread-status', 'Status (reread)', value.status),
+    row('reread-priority', 'Priority (reread)', value.priority ?? UNAVAILABLE),
+    row(
+      'reread-complexity',
+      'Complexity (reread)',
+      value.complexity === null ? UNAVAILABLE : String(value.complexity)
+    ),
+    row('reread-path', 'File (reread)', value.filePath),
+  ];
+}
+
+function formatList(values: readonly string[]): string {
+  return values.length === 0 ? 'none' : values.join(', ');
+}
+
+/**
+ * Render one BPAU-01 result. Pure and deterministic: every field comes from the
+ * result itself, and no state, identity, or sync fact is re-derived here.
+ */
+export function buildBacklogAuthoringOutcomeView(
+  result: BacklogAuthoringResult
+): BacklogAuthoringOutcomeView {
+  if ('state' in result) {
+    return {
+      viewVersion: BACKLOG_AUTHORING_VIEW_VERSION,
+      state: 'refused',
+      headline: truncateLine(REFUSAL_HEADLINES[result.reason]),
+      facts: 'awaiting-reread',
+      rows: [row('refusal-reason', 'Refusal reason', result.reason)],
+      completeness: null,
+      syncWarnings: [],
+      diagnostics: null,
+      notes: [result.message, 'No command was launched, so nothing was changed.'],
+      degraded: false,
+    };
+  }
+
+  const state = outcomeState(result);
+  const detail = result.canonicalRereads.detail;
+  const facts = detail.state === 'available' ? 'fresh' : 'awaiting-reread';
+  const rows: BacklogAuthoringRow[] = [
+    row('repository', 'Repository', result.repository.path),
+    row('branch', 'Branch', result.repository.branch ?? UNAVAILABLE),
+    row('action', 'Action', BACKLOG_AUTHORING_LABELS[result.action]),
+    row(
+      'requested-item',
+      'Requested backlog item',
+      result.requestedIdentities.backlogItemId ?? 'new item'
+    ),
+    row('created-items', 'Created', formatList(result.effect.createdIdentities)),
+    row('affected-items', 'Affected', formatList(result.effect.affectedIdentities)),
+    row('command-state', 'Command', result.command.state),
+    row(
+      'command-exit',
+      'Exit code',
+      result.command.exitCode === null ? UNAVAILABLE : String(result.command.exitCode)
+    ),
+    row('sync-state', 'Planning sync', result.sync.state),
+    row('sync-detail', 'Sync detail', result.sync.detail ?? UNAVAILABLE),
+    ...changedFactRows(detail),
+  ];
+
+  const identity = result.identityOutcome;
+  const completeness: BacklogCompletenessView | null =
+    identity === null
+      ? null
+      : {
+          complete: identity.complete,
+          missing: identity.missing,
+          refineCommand: identity.refineCommand,
+        };
+
+  const notes: string[] = [];
+  if (detail.state === 'unavailable') {
+    notes.push(
+      `Poetic's authoritative reread is unavailable (${detail.reason}), so no changed backlog fact is shown here.`
+    );
+  }
+  if (state === 'unknown-after-timeout') {
+    notes.push(
+      'The command timed out and was not retried. Poetic may or may not have applied it; reread before acting.'
+    );
+  }
+  if (state === 'partial-effect') {
+    notes.push(
+      'Poetic reports a partial effect: part of this change may exist. Inspect the item in Poetic before resubmitting.'
+    );
+  }
+  if (completeness !== null && !completeness.complete) {
+    notes.push(
+      completeness.refineCommand === null
+        ? `Poetic reports the item incomplete (missing: ${formatList(completeness.missing)}) and published no refine command.`
+        : `Poetic reports the item incomplete (missing: ${formatList(completeness.missing)}). Finish it with: ${completeness.refineCommand}`
+    );
+  }
+  if (result.fullBodyReplacement) {
+    notes.push('This update replaced the entire body of the backlog item.');
+  }
+  if (result.prioritizeMayReviewAndBecomeLaunchEligible) {
+    notes.push(BACKLOG_PRIORITIZE_LAUNCH_ELIGIBILITY_NOTICE);
+  }
+  notes.push(...result.integrityNotes);
+  notes.push(
+    'A zero exit code is not remote sync confirmation; the planning sync state above comes from Poetic.'
+  );
+
+  return {
+    viewVersion: BACKLOG_AUTHORING_VIEW_VERSION,
+    state,
+    headline: truncateLine(outcomeHeadline(result, state)),
+    facts,
+    rows,
+    completeness,
+    syncWarnings: result.syncWarnings,
+    diagnostics: result.command.diagnostics,
+    notes,
+    degraded:
+      facts === 'awaiting-reread' ||
+      state !== 'applied' ||
+      result.syncWarnings.length > 0 ||
+      result.integrityNotes.length > 0,
+  };
+}