@poetic-ai/poetic 1.42.0

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

@@ -0,0 +1,567 @@
+/**
+ * Pure model for BB custom task authoring: fixed argv, closed-vocabulary
+ * guards, consent conversion, process-local admission, and the evidence-only
+ * derivations the service reports.
+ *
+ * Nothing here reads Poetic internals, managed planning files, Git, the
+ * filesystem, or the network, and nothing spawns a process. Every function is
+ * deterministic in its inputs, and no function predicts a resulting status,
+ * capacity, membership, or identity: those come from Poetic's own structured
+ * outcome and its fresh rereads.
+ *
+ * The authoring vocabulary is disjoint from the shipped task lifecycle
+ * vocabulary by construction. No function here can emit a lifecycle subcommand,
+ * a status flag, `--body-file`, `--assignee`, `--allow-empty-results`,
+ * `--force`, or `--no-sync`.
+ */
+
+import type { z } from 'zod';
+import type { planningWorkspaceProjectionSchema } from './planning-workspace-schema.js';
+import {
+  type ApplyTaskAuthoringInput,
+  TASK_AUTHORING_DENIED_INPUT_KEYS,
+  TASK_AUTHORING_VOCABULARY,
+  TASK_LIFECYCLE_VOCABULARY_MIRROR,
+  type TaskAuthoringAction,
+  type TaskAuthoringConsent,
+  type TaskAuthoringCreateConsent,
+  type TaskAuthoringEffect,
+  type TaskAuthoringRefusalReason,
+  type TaskAuthoringSectionReplacementConsent,
+  type TaskAuthoringSync,
+  type TaskCreateIdentityEnvelope,
+} from './task-authoring-schema.js';
+
+type PlanningWorkspaceProjection = z.infer<typeof planningWorkspaceProjectionSchema>;
+
+/** Fixed argv prefix per action. Nothing is appended beyond the frozen flags. */
+const TASK_AUTHORING_COMMAND: Readonly<Record<TaskAuthoringAction, readonly string[]>> = {
+  createCustomTask: ['plan', 'task', 'create'],
+  updateCustomTask: ['plan', 'task', 'update'],
+  addTaskDependency: ['plan', 'task', 'depends'],
+  removeTaskDependency: ['plan', 'task', 'depends'],
+  linkTaskToBacklog: ['plan', 'task', 'link-backlog'],
+};
+
+export function isTaskAuthoringAction(value: unknown): value is TaskAuthoringAction {
+  return (
+    typeof value === 'string' && (TASK_AUTHORING_VOCABULARY as readonly string[]).includes(value)
+  );
+}
+
+/**
+ * True when no authoring action name collides with the shipped lifecycle
+ * vocabulary. It is asserted rather than assumed so a later rename cannot
+ * quietly reopen a lifecycle path through an authoring request.
+ */
+export function taskAuthoringVocabularyIsDisjoint(
+  lifecycleVocabulary: readonly string[] = TASK_LIFECYCLE_VOCABULARY_MIRROR
+): boolean {
+  return !TASK_AUTHORING_VOCABULARY.some((action) =>
+    (lifecycleVocabulary as readonly string[]).includes(action)
+  );
+}
+
+/**
+ * Names of any refused key present in a caller's raw `input` object. Strict
+ * schemas already reject unknown keys; this reports *which* excluded surface was
+ * attempted, so a status, lifecycle, execution, or filesystem field is refused
+ * with a legible reason before anything is spawned.
+ */
+export function taskAuthoringDeniedInputKeys(rawInput: unknown): string[] {
+  if (typeof rawInput !== 'object' || rawInput === null || Array.isArray(rawInput)) return [];
+  const present = new Set(Object.keys(rawInput));
+  return TASK_AUTHORING_DENIED_INPUT_KEYS.filter((key) => present.has(key));
+}
+
+/** The identities one request addresses, as the caller declared them. */
+export interface TaskAuthoringRequestedIdentities {
+  taskId: string | null;
+  sprintId: string | null;
+  dependencyTaskId: string | null;
+  backlogItemId: string | null;
+}
+
+export function taskAuthoringRequestedIdentities(
+  request: ApplyTaskAuthoringInput
+): TaskAuthoringRequestedIdentities {
+  const empty: TaskAuthoringRequestedIdentities = {
+    taskId: null,
+    sprintId: null,
+    dependencyTaskId: null,
+    backlogItemId: null,
+  };
+  switch (request.action) {
+    case 'createCustomTask':
+      return {
+        ...empty,
+        sprintId: request.input.sprintId,
+        backlogItemId: request.input.backlogItemId ?? null,
+      };
+    case 'updateCustomTask':
+      return { ...empty, taskId: request.input.taskId };
+    case 'addTaskDependency':
+      return { ...empty, taskId: request.input.taskId, dependencyTaskId: request.input.onTaskId };
+    case 'removeTaskDependency':
+      return {
+        ...empty,
+        taskId: request.input.taskId,
+        dependencyTaskId: request.input.removeTaskId,
+      };
+    case 'linkTaskToBacklog':
+      return {
+        ...empty,
+        taskId: request.input.taskId,
+        backlogItemId: request.input.backlogItemId,
+      };
+  }
+}
+
+/**
+ * Every identity a request declares, de-duplicated and sorted. The submitted
+ * `expected.entityIds` must match this set exactly, so a request cannot carry
+ * consent for one entity and mutate another.
+ */
+export function taskAuthoringDeclaredIdentities(request: ApplyTaskAuthoringInput): string[] {
+  const identities = taskAuthoringRequestedIdentities(request);
+  const declared = [
+    identities.taskId,
+    identities.sprintId,
+    identities.dependencyTaskId,
+    identities.backlogItemId,
+    ...(request.action === 'createCustomTask' ? (request.input.dependsOn ?? []) : []),
+  ].filter((value): value is string => value !== null);
+  return [...new Set(declared)].sort();
+}
+
+/**
+ * Build the fixed argv for one authoring action.
+ *
+ * Every optional value is a single `--flag=value` token, so a value beginning
+ * with a dash can never be parsed as another option, and the whole argv is
+ * spawned without a shell. `--json` is appended only to the create command,
+ * which is the one command publishing a `taskCreateV1` identity envelope; it is
+ * never a caller-controlled field.
+ */
+export function taskAuthoringArgv(request: ApplyTaskAuthoringInput): string[] {
+  const argv = [...TASK_AUTHORING_COMMAND[request.action]];
+  switch (request.action) {
+    case 'createCustomTask': {
+      const input = request.input;
+      argv.push(`--sprint=${input.sprintId}`, `--title=${input.title}`);
+      argv.push(`--estimate=${String(input.estimate)}`);
+      if (input.expectedRuntimeMinutes !== undefined) {
+        argv.push(`--expected-runtime=${String(input.expectedRuntimeMinutes)}`);
+      }
+      if (input.description !== undefined) argv.push(`--description=${input.description}`);
+      if (input.priority !== undefined) argv.push(`--priority=${input.priority}`);
+      for (const dependency of [...new Set(input.dependsOn ?? [])]) {
+        argv.push(`--depends-on=${dependency}`);
+      }
+      if (input.backlogItemId !== undefined) argv.push(`--backlog-id=${input.backlogItemId}`);
+      argv.push('--json');
+      return argv;
+    }
+    case 'updateCustomTask': {
+      const input = request.input;
+      argv.push(input.taskId);
+      if (input.title !== undefined) argv.push(`--title=${input.title}`);
+      if (input.description !== undefined) argv.push(`--description=${input.description}`);
+      if (input.priority !== undefined) argv.push(`--priority=${input.priority}`);
+      if (input.estimate !== undefined) argv.push(`--estimate=${String(input.estimate)}`);
+      if (input.expectedRuntimeMinutes !== undefined) {
+        argv.push(`--expected-runtime=${String(input.expectedRuntimeMinutes)}`);
+      }
+      return argv;
+    }
+    case 'addTaskDependency':
+      argv.push(request.input.taskId, `--on=${request.input.onTaskId}`);
+      return argv;
+    case 'removeTaskDependency':
+      argv.push(request.input.taskId, `--remove=${request.input.removeTaskId}`);
+      return argv;
+    case 'linkTaskToBacklog':
+      argv.push(request.input.taskId, request.input.backlogItemId);
+      return argv;
+  }
+}
+
+/**
+ * Control labels. Creating a custom task is named distinctly from adding
+ * existing backlog work to a sprint so the two products can never read as the
+ * same control.
+ */
+export const TASK_AUTHORING_LABELS: Readonly<Record<TaskAuthoringAction, string>> = {
+  createCustomTask: 'Create custom task',
+  updateCustomTask: 'Edit task details',
+  addTaskDependency: 'Add task dependency',
+  removeTaskDependency: 'Remove task dependency',
+  linkTaskToBacklog: 'Link task to backlog item',
+};
+
+/**
+ * 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 a lifecycle transition.
+ */
+export const TASK_AUTHORING_EFFECTS: Readonly<Record<TaskAuthoringAction, string>> = {
+  createCustomTask:
+    'Asks Poetic to create a new operator-authored task in the sprint you selected and to record it as a member of that sprint. Poetic mints the task id and reports the resulting capacity. This is not adding an existing backlog item to the sprint, and it never sets a status.',
+  updateCustomTask:
+    'Asks Poetic to update only the task fields you changed. It never changes status and never archives, completes, cancels, or reopens the task.',
+  addTaskDependency:
+    'Asks Poetic to record that this task depends on the task you named. It changes no status.',
+  removeTaskDependency:
+    'Asks Poetic to remove the dependency you named. Removing a dependency Poetic does not hold is a no-op, and it changes no status.',
+  linkTaskToBacklog:
+    'Asks Poetic to record the backlog item this task came from. It copies no backlog content and changes no status.',
+};
+
+/**
+ * The Description-replacement disclosure, stated once. The `--description`
+ * update replaces the `## Description` section and nothing else, so this copy
+ * must never claim it replaces the whole task: Subtasks, Checklist, Acceptance
+ * Criteria, Notes, and Activity are untouched. Whole-body replacement would
+ * require the excluded `--body-file` and is therefore not offered at all.
+ */
+export const TASK_AUTHORING_DESCRIPTION_REPLACEMENT_NOTICE =
+  'Saving replaces the entire Description section of this task with the text above. The rest of the task markdown — Subtasks, Checklist, Acceptance Criteria, Notes, and Activity — is left as Poetic has it. The text was prepopulated from the current canonical Description; BB will not submit a replacement it could not prepopulate.';
+
+/**
+ * Custom task creation is a different product from adding backlog work to a
+ * sprint, and the copy says so at the point of creation.
+ */
+export const TASK_AUTHORING_CREATE_DISTINCTION_NOTICE =
+  'This creates a new operator-authored task from the title, estimate, and description you enter. It is not "add from backlog": no backlog item is scheduled, and no backlog body is copied into the task. Linking a backlog item here records provenance only.';
+
+/** Consent checkboxes exactly as the operator left them; plain booleans. */
+export interface TaskAuthoringConsentState {
+  hostExecution: boolean;
+  managedPlanningMutation: boolean;
+  automaticCommitAndPush: boolean;
+  selectedRepositoryAndBranch: boolean;
+  /** Required for custom task creation only. */
+  newIdentityCreation: boolean;
+  /** Required when an update replaces the Description section. */
+  fullSectionReplacement: boolean;
+}
+
+export const EMPTY_TASK_AUTHORING_CONSENT: Readonly<TaskAuthoringConsentState> = {
+  hostExecution: false,
+  managedPlanningMutation: false,
+  automaticCommitAndPush: false,
+  selectedRepositoryAndBranch: false,
+  newIdentityCreation: false,
+  fullSectionReplacement: false,
+};
+
+export const TASK_AUTHORING_CONSENT_LABELS: Readonly<
+  Record<keyof TaskAuthoringConsentState, 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 task id will exist after this action.',
+  fullSectionReplacement: 'This replaces the entire Description section of the task.',
+};
+
+/** Which extra consent line an action requires, given the fields being sent. */
+export function taskAuthoringRequiredConsentKeys(
+  action: TaskAuthoringAction,
+  replacesDescription: boolean
+): Array<keyof TaskAuthoringConsentState> {
+  const base: Array<keyof TaskAuthoringConsentState> = [
+    'hostExecution',
+    'managedPlanningMutation',
+    'automaticCommitAndPush',
+    'selectedRepositoryAndBranch',
+  ];
+  if (action === 'createCustomTask') return [...base, 'newIdentityCreation'];
+  if (action === 'updateCustomTask' && replacesDescription) {
+    return [...base, 'fullSectionReplacement'];
+  }
+  return base;
+}
+
+/**
+ * Convert collected consent into the exact shape the request schema requires, or
+ * null when the acknowledgement is incomplete. Returning null is the enforcement
+ * point: a caller cannot build a request without proportionate consent, and an
+ * extra literal for an effect that is not happening is not added.
+ */
+export function taskAuthoringConsentPayload(
+  action: TaskAuthoringAction,
+  replacesDescription: boolean,
+  consent: TaskAuthoringConsentState
+):
+  | TaskAuthoringConsent
+  | TaskAuthoringCreateConsent
+  | TaskAuthoringSectionReplacementConsent
+  | null {
+  const required = taskAuthoringRequiredConsentKeys(action, replacesDescription);
+  if (required.some((key) => !consent[key])) return null;
+  const base: TaskAuthoringConsent = {
+    hostExecution: true,
+    managedPlanningMutation: true,
+    automaticCommitAndPush: true,
+    selectedRepositoryAndBranch: true,
+  };
+  if (action === 'createCustomTask') return { ...base, newIdentityCreation: true };
+  if (action === 'updateCustomTask' && replacesDescription) {
+    return { ...base, fullSectionReplacement: true };
+  }
+  return base;
+}
+
+/**
+ * Refuse a request whose consent is not proportionate to the fields it sends:
+ * a Description replacement without the replacement acknowledgement, or that
+ * acknowledgement attached to an update that changes no description.
+ */
+export function taskAuthoringConsentRefusal(
+  request: ApplyTaskAuthoringInput
+): { reason: TaskAuthoringRefusalReason; message: string } | null {
+  if (request.action !== 'updateCustomTask') return null;
+  const replacesDescription = request.input.description !== undefined;
+  const acknowledged = 'fullSectionReplacement' in request.consent;
+  if (replacesDescription && !acknowledged) {
+    return {
+      reason: 'invalid-request',
+      message:
+        'Replacing the Description section requires the section-replacement acknowledgement. No command was launched.',
+    };
+  }
+  if (!replacesDescription && acknowledged) {
+    return {
+      reason: 'invalid-request',
+      message:
+        'This update changes no description, so the section-replacement acknowledgement does not apply to it. No command was launched.',
+    };
+  }
+  return null;
+}
+
+/**
+ * Whether a Description replacement may be submitted at all.
+ *
+ * BB refuses a replacement it could not prepopulate from a fresh canonical read,
+ * because submitting an unprepopulated editor would silently discard whatever
+ * Poetic currently holds in that section.
+ */
+export type TaskAuthoringPrepopulation =
+  | { state: 'prepopulated'; description: string }
+  | { state: 'unavailable'; reason: string };
+
+export function taskAuthoringDescriptionPrepopulation(
+  taskId: string,
+  sibling:
+    | { state: 'available'; value: { taskId: string; description: string } }
+    | {
+        state: 'unavailable';
+        reason: string;
+      }
+): TaskAuthoringPrepopulation {
+  if (sibling.state === 'unavailable') {
+    return {
+      state: 'unavailable',
+      reason: `Poetic did not publish the canonical Description for task ${taskId} (${sibling.reason}), so BB will not replace it.`,
+    };
+  }
+  if (sibling.value.taskId !== taskId) {
+    return {
+      state: 'unavailable',
+      reason: `Poetic published a Description for ${sibling.value.taskId} while BB asked for ${taskId}, so BB will not replace it.`,
+    };
+  }
+  return { state: 'prepopulated', description: sibling.value.description };
+}
+
+/** Admission scope: one repository, one entity family, one identity. */
+export interface TaskAuthoringAdmissionScope {
+  repositoryPath: string;
+  /** `create` for a not-yet-minted identity, `task` for an existing one. */
+  kind: 'create' | 'task';
+  identity: string;
+}
+
+/**
+ * Process-local admission for authoring submissions. It refuses an overlapping
+ * submission for the same repository, entity family, and identity inside this
+ * plugin process only; it is not a file lock, and it claims no cross-process or
+ * Poetic-side exclusivity. Creation is scoped by kind because no identity exists
+ * yet.
+ */
+export class ProcessLocalTaskAuthoringAdmission {
+  private static readonly FAMILY = 'task-authoring';
+
+  private readonly claims = new Set<string>();
+
+  private scopeKey(scope: TaskAuthoringAdmissionScope): string {
+    return `${scope.repositoryPath}\u0000${scope.kind}:${scope.identity}\u0000${ProcessLocalTaskAuthoringAdmission.FAMILY}`;
+  }
+
+  /**
+   * Claim admission for one scope. Returns a release function that is safe to
+   * call more than once, and throws when the same scope is still claimed.
+   */
+  claim(scope: TaskAuthoringAdmissionScope): () => void {
+    const key = this.scopeKey(scope);
+    if (this.claims.has(key)) {
+      throw new Error(
+        `A BB task authoring action is already in progress for ${scope.kind} ${scope.identity} in this repository. Process-local admission refuses overlapping submissions; this is not cross-process ownership.`
+      );
+    }
+    this.claims.add(key);
+    let released = false;
+    return () => {
+      if (released) return;
+      released = true;
+      this.claims.delete(key);
+    };
+  }
+
+  isBusy(scope: TaskAuthoringAdmissionScope): boolean {
+    return this.claims.has(this.scopeKey(scope));
+  }
+}
+
+/** The admission scope one request occupies. */
+export function taskAuthoringAdmissionScope(
+  repositoryPath: string,
+  request: ApplyTaskAuthoringInput
+): TaskAuthoringAdmissionScope {
+  if (request.action === 'createCustomTask') {
+    return { repositoryPath, kind: 'create', identity: 'task' };
+  }
+  return { repositoryPath, kind: 'task', identity: request.input.taskId };
+}
+
+/**
+ * Surface Poetic's current planning-sync evidence from a fresh workspace
+ * reread. Everything here comes from what Poetic published, never from the
+ * command's exit code.
+ */
+export function taskAuthoringSyncWarnings(workspace: PlanningWorkspaceProjection): string[] {
+  const warnings: string[] = [];
+  const health = workspace.data.syncHealth;
+  if (health.state !== 'in-sync') {
+    warnings.push(health.detail ?? `Poetic reports planning sync state ${health.state}.`);
+  }
+  for (const note of workspace.notes) {
+    if (note.scope === 'sync-health') warnings.push(note.detail);
+  }
+  return [...new Set(warnings)];
+}
+
+/**
+ * Map Poetic's own sync health onto the reported sync state. `remote_verified`
+ * is only ever reported because Poetic itself said the planning state is in
+ * sync; it is never inferred from a zero exit.
+ */
+export function taskAuthoringSyncState(
+  workspace:
+    | { state: 'available'; value: PlanningWorkspaceProjection }
+    | {
+        state: 'unavailable';
+        reason: string;
+      }
+): TaskAuthoringSync {
+  if (workspace.state === 'unavailable') {
+    return {
+      state: 'unknown',
+      detail: `Poetic's planning workspace could not be reread after this action (${workspace.reason}), so its sync state is unknown.`,
+    };
+  }
+  const health = workspace.value.data.syncHealth;
+  switch (health.state) {
+    case 'in-sync':
+      return { state: 'remote_verified', detail: health.detail };
+    case 'ahead':
+      return {
+        state: 'local_commit_only',
+        detail: health.detail ?? 'Poetic reports unpushed planning commits.',
+      };
+    case 'stale':
+      return {
+        state: 'unknown',
+        detail: health.detail ?? 'Poetic reports the planning sync evidence is stale.',
+      };
+    default:
+      return {
+        state: 'unknown',
+        detail: health.detail ?? 'Poetic published no planning sync evidence.',
+      };
+  }
+}
+
+/**
+ * Effect and command state for a create, derived from Poetic's own
+ * `taskCreateV1` envelope rather than from the exit code.
+ *
+ * A missing, malformed, or internally inconsistent envelope is reported as
+ * ambiguous with an undetermined effect: BB never substitutes the newest task it
+ * can see for the identity Poetic failed to publish.
+ */
+export function taskAuthoringCreateEffect(identityOutcome: TaskCreateIdentityEnvelope | null): {
+  state: 'succeeded' | 'failed' | 'ambiguous';
+  effect: TaskAuthoringEffect;
+} {
+  if (identityOutcome === null) {
+    return {
+      state: 'ambiguous',
+      effect: { phase: 'unknown-after-timeout', createdIdentities: [], affectedIdentities: [] },
+    };
+  }
+  const sprintId = identityOutcome.sprintId;
+  const taskId = identityOutcome.taskId;
+  switch (identityOutcome.state) {
+    case 'created':
+      if (taskId === null) {
+        return {
+          state: 'ambiguous',
+          effect: {
+            phase: 'unknown-after-timeout',
+            createdIdentities: [],
+            affectedIdentities: [sprintId],
+          },
+        };
+      }
+      return {
+        state: 'succeeded',
+        effect: {
+          phase: identityOutcome.membershipApplied ? 'applied' : 'applied-incomplete',
+          createdIdentities: [taskId],
+          affectedIdentities: [sprintId],
+        },
+      };
+    case 'refused':
+      return {
+        state: 'failed',
+        effect: {
+          phase: 'refused-before-effect',
+          createdIdentities: [],
+          affectedIdentities: [],
+        },
+      };
+    case 'rolled-back':
+      return {
+        state: 'failed',
+        effect: {
+          phase: 'refused-before-effect',
+          createdIdentities: [],
+          affectedIdentities: [],
+        },
+      };
+    case 'failed-after-partial-effect':
+      return {
+        state: 'failed',
+        effect: {
+          phase: 'failed-after-partial-effect',
+          createdIdentities: taskId === null ? [] : [taskId],
+          affectedIdentities: [sprintId],
+        },
+      };
+  }
+}