ecoportal-api-graphql 1.3.13 → 1.3.16

data/.ai-assistance/code/workflow-command-guide.md

@@ -1,466 +0,0 @@
-# WorkflowCommand Porting Guide
-
-*For developers and Claude: porting old operations to the `executeWorkflowCommands` command bus.*
-
----
-
-## Why This Exists
-
-Most template and page structural mutations go through `executeWorkflowCommands`.
-This is a single GraphQL mutation that accepts an ordered array of
-`WorkflowCommandInput` objects. There are no individual mutations for "add a stage",
-"rename a field", "add a select option", etc. — they all route through this one endpoint.
-
-Old scripts that manipulated template structure via the APIv2 REST layer or direct
-back-end access need to be ported to this command bus.
-
----
-
-## The Command Bus Pattern
-
-One mutation. N commands per call. Commands execute in array order server-side.
-
-```ruby
-# Build individual commands
-cmd1 = Input::WorkflowCommand.build(:editPage,  name: 'Incident Report', icon: 'warning')
-cmd2 = Input::WorkflowCommand.build(:editStage, stageId: 's1_id', name: 'Initial Report')
-cmd3 = Input::WorkflowCommand.build(:editStage, stageId: 's2_id', name: 'Investigation')
-
-# Batch all three into one mutation call — more efficient than three separate calls
-payload = Mutation::Page::ExecuteWorkflowCommands.new(client).query(
-  id:        template_id,
-  patch_ver: template.patchVer,   # fetch before mutating
-  commands:  [cmd1, cmd2, cmd3]
-)
-
-raise "Commands failed: #{payload.body.inspect}" unless payload.success?
-puts "New patchVer: #{payload.patchVer}"
-```
-
-### patchVer requirement
-
-`ExecuteWorkflowCommandsInput` requires `patchVer: Int!` (non-null). Always fetch the
-current page or template before sending commands:
-
-```ruby
-page = graphql.currentOrganization.page(id: page_id) do
-  id; patchVer
-end
-# ... build commands ...
-payload = Mutation::Page::ExecuteWorkflowCommands.new(client).query(
-  id: page_id, patch_ver: page.patchVer, commands: cmds
-)
-```
-
-### Error handling
-
-```ruby
-payload = Mutation::Page::ExecuteWorkflowCommands.new(client).query(
-  id: page_id, patch_ver: page.patchVer, commands: cmds
-)
-
-if payload.success?
-  puts "Done. New patchVer: #{payload.patchVer}"
-else
-  # payload.body → raw errors array from the server
-  warn "Workflow command failed: #{payload.body.inspect}"
-end
-```
-
----
-
-## Complete Command Mapping Table
-
-Grouped by category. Every key listed here corresponds to one field in `WorkflowCommandInput`.
-All map to a Ruby sub-input module under `Input::WorkflowCommand::`.
-
-### Page-level
-
-| Goal | Command key | Required fields | Optional fields |
-|------|-------------|-----------------|-----------------|
-| Edit page metadata / settings | `editPage` | _(none required)_ | `name`, `icon`, `themeId`, `timeZone`, `counterEnabled`, `counterPrefix`, `counterPostfix`, `counter`, `showCreator`, `disableComments`, `enableDashboardImport`, `enableActionsOnFields`, `mobileEnabled`, `useSectionsOnMobile`, `showStrategyForRestrictedStages`, `showAssigneeNamesForRestrictedStages`, `showTaskDueDateForRestrictedStages`, `hideActivityStream`, `disableDirectPermissions`, `active`, `addLocationIds`, `removeLocationIds`, `addBaseTags`, `removeBaseTags`, `addOtherTags`, `removeOtherTags`, `addFolders`, `removeFolders`, `creatorEnabled`, `creatorEditable`, `creatorFlags` |
-| Edit page creator permissions | `editPageCreatorPermissions` | _(see schema)_ | various permission flags |
-
-### Stage structural
-
-| Goal | Command key | Required fields | Optional fields |
-|------|-------------|-----------------|-----------------|
-| Add a stage | `addStage` | `name`, `ordering` | `placeholderId` |
-| Remove a stage | `removeStage` | `stageId` | |
-| Rename / configure a stage | `editStage` | `stageId` | `name`, `description`, `lockAfterCompletion`, `disableDirectPermissions` |
-| Move a stage (reorder) | `moveStage` | `stageId`, `ordering` | |
-
-### Stage permissions
-
-| Goal | Command key | Required fields | Optional fields |
-|------|-------------|-----------------|-----------------|
-| Edit creator permissions (stage) | `editCreatorPermissions` | _(see schema)_ | |
-| Toggle restrict comment tagging | `editRestrictCommentTagging` | _(see schema)_ | |
-| Add user group to comment tagging | `addCommentTaggingUserGroup` | `userGroupId` | |
-| Remove user group from comment tagging | `removeCommentTaggingUserGroup` | `userGroupId` | |
-| Toggle restrict task assignment | `editRestrictTaskAssignment` | _(see schema)_ | |
-| Add user group to task assignment | `addTaskAssignmentUserGroup` | `userGroupId` | |
-| Remove user group from task assignment | `removeTaskAssignmentUserGroup` | `userGroupId` | |
-| Add a tag to a stage | `addStageTag` | `stageId`, `tag` | |
-| Remove a tag from a stage | `removeStageTag` | `stageId`, `tag` | |
-
-### Section
-
-| Goal | Command key | Required fields | Optional fields |
-|------|-------------|-----------------|-----------------|
-| Add a section (BasicPage / PhasedPage) | `addSection` | `layout` | `placeholderId` |
-| Remove a section (BasicPage) | `removeSection` | `sectionId` | |
-| Add a section to a stage | `addStageSection` | `stageId`, `layout` | `placeholderId` |
-| Remove a section from a stage | `removeStageSection` | `stageId`, `sectionId` | |
-| Edit section heading | `editSectionHeader` | `sectionId` | `header`, `leftHeader`, `rightHeader` |
-| Collapse section by default | `collapseSection` | `sectionId` | |
-| Expand section by default | `expandSection` | `sectionId` | |
-| Reorder sections | `reorderSection` | `sectionId`, `ordering` | |
-
-### Task
-
-| Goal | Command key | Required fields | Optional fields |
-|------|-------------|-----------------|-----------------|
-| Add a task to a stage | `addTask` | `stageId`, `taskType` | `placeholderId` |
-| Remove a task from a stage | `removeTask` | `stageId`, `taskId` | |
-| Set task due date config | `editTaskDue` | `stageId`, `taskId` | `dueInValue`, `dueInUnit`, `dueExcludeWeekends` |
-| Remove task due date config | `removeTaskDue` | `stageId`, `taskId` | |
-| Remove task priority level | `removeTaskPriorityLevel` | `stageId`, `taskId` | |
-| Edit required sign-offs | `editRequiredSignOffs` | `stageId`, `taskId` | `required`, `minimum` |
-| Edit reminder | `editReminder` | `stageId`, `taskId` | `enabled`, `value`, `unit` |
-
-### Strategy (default assignment)
-
-| Goal | Command key | Required fields | Optional fields |
-|------|-------------|-----------------|-----------------|
-| Add default assignment strategy | `addDefaultStrategy` | `stageId`, `taskId`, `strategy` | `placeholderId` |
-| Edit default strategy | `editDefaultStrategy` | `stageId`, `taskId`, `strategyId` | `strategy` |
-| Remove default strategy | `removeDefaultStrategy` | `stageId`, `taskId`, `strategyId` | |
-| Add user to direct default strategy | `addDefaultDirectStrategyUser` | `stageId`, `taskId`, `strategyId`, `userId` | |
-| Remove user from direct default strategy | `removeDefaultDirectStrategyUser` | `stageId`, `taskId`, `strategyId`, `userId` | |
-
-### Strategy (task assignment)
-
-| Goal | Command key | Required fields | Optional fields |
-|------|-------------|-----------------|-----------------|
-| Add task assignment strategy | `addStrategy` | `stageId`, `taskId`, `strategy` | `placeholderId` |
-| Edit task strategy | `editStrategy` | `stageId`, `taskId`, `strategyId` | `strategy` |
-| Remove task strategy | `removeStrategy` | `stageId`, `taskId`, `strategyId` | |
-| Add user to direct strategy | `addDirectStrategyUser` | `stageId`, `taskId`, `strategyId`, `userId` | |
-| Remove user from direct strategy | `removeDirectStrategyUser` | `stageId`, `taskId`, `strategyId`, `userId` | |
-
-### Strategy (operation)
-
-| Goal | Command key | Required fields | Optional fields |
-|------|-------------|-----------------|-----------------|
-| Add operation strategy | `addOperationStrategy` | `stageId`, `callbackId`, `operationId`, `strategy` | `taskId`, `placeholderId` |
-| Edit operation strategy | `editOperationStrategy` | `stageId`, `callbackId`, `operationId`, `strategyId` | `taskId`, `strategy` |
-| Remove operation strategy | `removeOperationStrategy` | `stageId`, `callbackId`, `operationId`, `strategyId` | `taskId` |
-| Add user to direct op strategy | `addOperationDirectStrategyUser` | `stageId`, `callbackId`, `operationId`, `strategyId`, `userId` | `taskId` |
-| Remove user from direct op strategy | `removeOperationDirectStrategyUser` | `stageId`, `callbackId`, `operationId`, `strategyId`, `userId` | `taskId` |
-
-### Callback + Operation
-
-| Goal | Command key | Required fields | Optional fields |
-|------|-------------|-----------------|-----------------|
-| Add a workflow callback | `addWorkflowCallback` | `stageId`, `triggerCondition` | `placeholderId`, `taskId`, `triggers`, `operations` |
-| Remove a callback | `removeCallback` | `stageId`, `callbackId` | `taskId` |
-| Edit callback trigger | `editTrigger` | `stageId`, `callbackId`, `triggers` | `taskId` |
-| Add an operation to a callback | `addOperation` | `stageId`, `callbackId`, `operation` | `taskId`, `placeholderId` |
-| Edit an operation | `editOperation` | `stageId`, `callbackId`, `operationId`, `operation` | `taskId` |
-| Remove an operation | `removeOperation` | `stageId`, `callbackId`, `operationId` | `taskId` |
-
-### Recipient (10 variants)
-
-| Goal | Command key | Required fields |
-|------|-------------|-----------------|
-| Add a specific user as recipient | `addRecipientUser` | `stageId`, `callbackId`, `operationId`, `userId` |
-| Remove a specific user | `removeRecipientUser` | `stageId`, `callbackId`, `operationId`, `userId` |
-| Add a people field as recipient source | `addRecipientPeopleField` | `stageId`, `callbackId`, `operationId`, `peopleFieldId` |
-| Remove a people field | `removeRecipientPeopleField` | `stageId`, `callbackId`, `operationId`, `peopleFieldId` |
-| Add a task config as recipient source | `addRecipientTaskConfig` | `stageId`, `callbackId`, `operationId`, `taskConfigId` |
-| Remove a task config | `removeRecipientTaskConfig` | `stageId`, `callbackId`, `operationId`, `taskConfigId` |
-| Add an action type as recipient source | `addRecipientActionType` | `stageId`, `callbackId`, `operationId`, `actionTypeId` |
-| Remove an action type | `removeRecipientActionType` | `stageId`, `callbackId`, `operationId`, `actionTypeId` |
-| Add a filter-based recipient | `addRecipientFilter` | `stageId`, `callbackId`, `operationId`, `filter` |
-| Remove a filter-based recipient | `removeRecipientFilter` | `stageId`, `callbackId`, `operationId`, `filter` |
-
-All 10 recipient commands also accept optional `taskId`.
-
-### Scheduled callbacks
-
-| Goal | Command key | Required fields | Optional fields |
-|------|-------------|-----------------|-----------------|
-| Add a scheduled callback | `addScheduledCallback` | `stageId`, `taskId` | `placeholderId`, `dueInValue`, `dueInUnit`, `dueExcludeWeekends`, `recurs`, `recursInValue`, `recursInUnit`, `recursExcludeWeekends`, `actions` |
-| Edit a scheduled callback | `editScheduledCallback` | `stageId`, `taskId`, `scheduledCallbackId` | `dueInValue`, `dueInUnit`, `recurs`, etc. |
-| Remove a scheduled callback | `removeScheduledCallback` | `stageId`, `taskId`, `scheduledCallbackId` | |
-| Add action to scheduled callback | `addScheduledCallbackAction` | `stageId`, `taskId`, `scheduledCallbackId`, `action` | |
-| Add action tag | `addActionTag` | `stageId`, `taskId`, `scheduledCallbackId`, `tag` | |
-| Remove action tag | `removeActionTag` | `stageId`, `taskId`, `scheduledCallbackId`, `tag` | |
-
-### Field structural
-
-| Goal | Command key | Required fields | Optional fields |
-|------|-------------|-----------------|-----------------|
-| Add a field to a stage section | `addField` | `fieldType`, `stageId`, `sectionId` | `placeholderId`, `label`, `column` |
-| Move a field to another section/position | `moveField` | `dataFieldId`, `sectionId` | `column`, `ordering` |
-| Remove a field | `removeField` | `dataFieldId` | |
-
-### Field configuration (12 type variants)
-
-All field configuration changes go through a single command key with a nested `byType` dispatcher:
-
-```ruby
-Input::WorkflowCommand.build(
-  :editFieldConfiguration,
-  data_field_id: 'FIELD_ID',
-  label:         'New Label',        # optional base-level
-  tooltip:       'Help text',        # optional base-level
-  description:   'Longer desc',     # optional base-level
-  hide_view:     false,              # optional base-level (snake_case → camelCase)
-  byType: {
-    people: {                        # one of the 12 type keys below
-      singular:       true,
-      personSchemaId: 'SCHEMA_ID'
-    }
-  }
-)
-```
-
-Base-level fields (all optional): `label`, `tooltip`, `description`, `hideView`,
-`hiddenOnMobile`, `enableActions`, `globalBinding`.
-
-The `byType` hash accepts exactly one of these keys:
-
-| `byType` key | Schema input | Configures |
-|---|---|---|
-| `plainText` | `WorkflowEditFieldConfigurationPlainTextInput` | `value`, `maxLength`, `embeddingEnabled`, `smartFillConfiguration` |
-| `richText` | `WorkflowEditFieldConfigurationRichTextInput` | `content`, `markdown`, `embeddingEnabled`, `smartFillConfiguration` |
-| `date` | `WorkflowEditFieldConfigurationDateInput` | `showTime`, `pastOnly`, `todayButton`, `smartFillConfiguration` |
-| `gauge` | `WorkflowEditFieldConfigurationGaugeInput` | `max` |
-| `select` | `WorkflowEditFieldConfigurationSelectInput` | `dataType`, `multiple`, `flat`, `other`, `otherDesc`, `smartFillConfiguration` |
-| `people` | `WorkflowEditFieldConfigurationPeopleInput` | `personSchemaId`, `singular`, `requiresNumber`, `attachMode`, `isMeButton`, `autoSelectMode`, `addViewableFields`, `removeViewableFields` |
-| `crossReference` | `WorkflowEditFieldConfigurationCrossReferenceInput` | `registerId`, `singleSelectMode`, `displayFields`, `hideCreate`, `hideAttach`, `hideDashboards` |
-| `imageGallery` | `WorkflowEditFieldConfigurationImageGalleryInput` | `layout`, `stretch`, `noPopup`, `hideOptions` |
-| `locationField` | `WorkflowEditFieldConfigurationLocationFieldInput` | `buttonText`, `minimumRequired`, `singleSelect`, `autoselectDefaultLocation`, `restrictByClassification`, `addAllowedClassifications`, `removeAllowedClassifications`, `addAllowedStructures`, `removeAllowedStructures` |
-| `contractorEntities` | `WorkflowEditFieldConfigurationContractorEntitiesInput` | `singular`, `requiresNumber`, `isMeButton`, `showApprovalStatus`, `grantPermissionsEnabled`, `adminAccess`, `regularAccess` |
-| `signature` | `WorkflowEditFieldConfigurationSignatureInput` | `color` |
-| `table` | `WorkflowEditFieldConfigurationTableInput` | `tableType`, `jurisdictionFieldRef`, various date/award fields |
-
-### Select options
-
-| Goal | Command key | Required fields | Optional fields |
-|------|-------------|-----------------|-----------------|
-| Add a select option | `addSelectFieldOption` | `dataFieldId`, `label` | `placeholderId`, `weight` |
-| Edit a select option | `editSelectFieldOption` | `dataFieldId`, `optionId` | `label`, `weight` |
-| Remove a select option | `removeSelectFieldOption` | `dataFieldId`, `optionId` | |
-
-### Gauge stops
-
-| Goal | Command key | Required fields | Optional fields |
-|------|-------------|-----------------|-----------------|
-| Add a gauge stop | `addGaugeFieldStop` | `dataFieldId`, `threshold`, `color` | `placeholderId` |
-| Edit a gauge stop | `editGaugeFieldStop` | `dataFieldId`, `stopId` | `threshold`, `color` |
-| Remove a gauge stop | `removeGaugeFieldStop` | `dataFieldId`, `stopId` | |
-
-### Linked fields
-
-| Goal | Command key | Required fields | Optional fields |
-|------|-------------|-----------------|-----------------|
-| Add a linked field config | `addLinkedFieldConfig` | `dataFieldId`, `sourceFieldKey`, `crossReferenceId` | `attachedMode` |
-| Edit a linked field config | `editLinkedFieldConfig` | `dataFieldId`, `linkedFieldConfigId` | `sourceFieldKey` |
-| Remove a linked field config | `removeLinkedFieldConfig` | `dataFieldId`, `linkedFieldConfigId` | |
-
-### Forces and bindings (advanced)
-
-| Goal | Command key | Required fields | Optional fields |
-|------|-------------|-----------------|-----------------|
-| Add a force | `addForce` | `name`, `script` | `placeholderId` |
-| Remove a force | `removeForce` | `forceId` | |
-| Edit a force | `editForce` | `forceId` | `name`, `script` |
-| Reorder forces | `reorderForces` | `forceIds` | |
-| Add a binding | `addBinding` | `forceId`, `fieldId`, `name` | `placeholderId` |
-| Edit a binding | `editBinding` | `forceId`, `bindingId` | `fieldId`, `name` |
-| Remove a binding | `removeBinding` | `forceId`, `bindingId` | |
-| Add linked helper | `addLinkedHelper` | _(see schema)_ | |
-| Edit linked helper | `editLinkedHelper` | _(see schema)_ | |
-| Remove linked helper | `removeLinkedHelper` | _(see schema)_ | |
-
----
-
-## Usage Examples
-
-### 1. Rename a stage
-
-```ruby
-page = graphql.currentOrganization.page(id: page_id) { id; patchVer }
-
-payload = Mutation::Page::ExecuteWorkflowCommands.new(client).query(
-  id:        page_id,
-  patch_ver: page.patchVer,
-  commands:  [
-    Input::WorkflowCommand.build(:editStage, stageId: stage_id, name: 'Investigation Phase')
-  ]
-)
-raise payload.body.inspect unless payload.success?
-```
-
-### 2. Add a workflow callback (send notification on stage submit)
-
-```ruby
-page = graphql.currentOrganization.page(id: page_id) { id; patchVer }
-
-payload = Mutation::Page::ExecuteWorkflowCommands.new(client).query(
-  id:        page_id,
-  patch_ver: page.patchVer,
-  commands:  [
-    Input::WorkflowCommand.build(
-      :addWorkflowCallback,
-      stageId:          stage_id,
-      triggerCondition: 'on_stage_complete'
-    )
-  ]
-)
-raise payload.body.inspect unless payload.success?
-```
-
-### 3. Edit page icon and counter format
-
-```ruby
-page = graphql.currentOrganization.page(id: page_id) { id; patchVer }
-
-payload = Mutation::Page::ExecuteWorkflowCommands.new(client).query(
-  id:        page_id,
-  patch_ver: page.patchVer,
-  commands:  [
-    Input::WorkflowCommand.build(
-      :editPage,
-      icon:           'clipboard',
-      counterEnabled: true,
-      counterPrefix:  'INC-',
-      counterPostfix: ''
-    )
-  ]
-)
-raise payload.body.inspect unless payload.success?
-```
-
-### 4. Edit a field label and tooltip
-
-```ruby
-page = graphql.currentOrganization.page(id: page_id) { id; patchVer }
-
-payload = Mutation::Page::ExecuteWorkflowCommands.new(client).query(
-  id:        page_id,
-  patch_ver: page.patchVer,
-  commands:  [
-    Input::WorkflowCommand.build(
-      :editFieldConfiguration,
-      data_field_id: field_id,
-      label:         'Incident Description',
-      tooltip:       'Describe what happened, where, and who was involved'
-    )
-  ]
-)
-raise payload.body.inspect unless payload.success?
-```
-
-### 5. Add a select field option
-
-```ruby
-page = graphql.currentOrganization.page(id: page_id) { id; patchVer }
-
-payload = Mutation::Page::ExecuteWorkflowCommands.new(client).query(
-  id:        page_id,
-  patch_ver: page.patchVer,
-  commands:  [
-    Input::WorkflowCommand.build(
-      :addSelectFieldOption,
-      dataFieldId: field_id,
-      label:       'Under Review',
-      weight:      50
-    )
-  ]
-)
-raise payload.body.inspect unless payload.success?
-```
-
-### 6. Configure a people field (singular, person schema)
-
-```ruby
-page = graphql.currentOrganization.page(id: page_id) { id; patchVer }
-
-payload = Mutation::Page::ExecuteWorkflowCommands.new(client).query(
-  id:        page_id,
-  patch_ver: page.patchVer,
-  commands:  [
-    Input::WorkflowCommand.build(
-      :editFieldConfiguration,
-      data_field_id: field_id,
-      byType: {
-        people: {
-          singular:       true,
-          personSchemaId: person_schema_id,
-          attachMode:     'ATTACH_ONLY'
-        }
-      }
-    )
-  ]
-)
-raise payload.body.inspect unless payload.success?
-```
-
-### Batching multiple commands (efficiency)
-
-Commands are ordered — the server executes them in sequence. Batch unrelated or
-sequential changes into a single mutation call to reduce round-trips and avoid
-intermediate patchVer staleness:
-
-```ruby
-page = graphql.currentOrganization.page(id: page_id) { id; patchVer }
-
-cmds = [
-  Input::WorkflowCommand.build(:editPage,  name: 'Safety Incident Report', icon: 'warning'),
-  Input::WorkflowCommand.build(:editStage, stageId: s1, name: 'Initial Report'),
-  Input::WorkflowCommand.build(:editStage, stageId: s2, name: 'Investigation'),
-  Input::WorkflowCommand.build(:editStage, stageId: s3, name: 'Close-out'),
-  Input::WorkflowCommand.build(:addSelectFieldOption, dataFieldId: severity_field, label: 'Critical', weight: 1),
-  Input::WorkflowCommand.build(:addSelectFieldOption, dataFieldId: severity_field, label: 'High',     weight: 2),
-]
-
-payload = Mutation::Page::ExecuteWorkflowCommands.new(client).query(
-  id:        page_id,
-  patch_ver: page.patchVer,
-  commands:  cmds
-)
-raise "Commands failed: #{payload.body.inspect}" unless payload.success?
-puts "Applied #{cmds.size} commands. New patchVer: #{payload.patchVer}"
-```
-
----
-
-## Schema realities — input-key gotchas (verified 2026-07-04 against the live introspection dump)
-
-These are the ways the command bus does **not** behave the way you'd expect. Verifying against the
-schema dump (`.ai-assistance/tmp/*_live_ep_graphql_schema.graphql.json`) before assuming a key exists
-saves a live round trip.
-
-- **`addField` (`WorkflowAddFieldInput`) keys = EXACTLY** `placeholderId, fieldType, label, stageId`
-  (NON_NULL), `sectionId` (NON_NULL), `column`. It does **not** accept `description` or `required`.
-- **A field's `description` is set via `editFieldConfiguration`** (`WorkflowEditFieldConfigurationInput`
-  has a top-level `description: String`), NOT via `addField`. To build a field *with* a description
-  (e.g. a CSV / hidden-field **identity token**), emit `addField` then a follow-up
-  `editFieldConfiguration(dataFieldId: <field>, description:)`. This is the seam `Diff::CommandSynthesizer`
-  and `Builder::TemplateBuilder` use (via `placeholderId`/`ref` when the field is created in the same batch).
-- **`required` cannot be set through the command bus at all.** There is **no `required` input key
-  anywhere** — not on `WorkflowAddFieldInput`, not on `WorkflowEditFieldConfigurationInput` (top-level),
-  not on any of its **12 `byType` sub-inputs**. Treat field-`required` as **read-only / out-of-band**:
-  read it from the template, don't try to mutate it. (ecoportal-qa `:skip`s `required`-readiness for
-  this reason; `VersionDiff`'s `BYTYPE_CONFIG` omits it.)
-- **Structural back-refs:** an added field's `addField` carries its parent `sectionId` + `stageId`;
-  an added **section** has no stage-id key, so wire it with a follow-up
-  `addStageSection(stageId:, sectionId:)`. `Diff::CommandSynthesizer` threads all of these via
-  `placeholderId`/`ref()` (parent placeholder when same-batch, else real id; omitted when unknown).
-
-**Rule of thumb:** before adding a key to a `WorkflowCommand` builder, confirm it exists on that input
-type in the schema dump. Absent keys are silently dropped (or rejected) — they do not error informatively.