@cat-factory/app 0.215.2 → 0.217.1

package/README.md

@@ -18,6 +18,9 @@ The SPA source lives under `app/` (the Nuxt srcDir).
 - [Interface modes (basic / advanced)](#interface-modes-basic--advanced)
 - [Agent tiers (basic / intermediate / advanced)](#agent-tiers-basic--intermediate--advanced)
 - [In-app tutorial tours](#in-app-tutorial-tours)
+- [Real-time store coherence](#real-time-store-coherence-avoid-the-full-refresh-clobber)
+- [Internationalization (i18n) authoring](#internationalization-i18n-authoring)
+- [Extending the layer (consumer modules)](#extending-the-layer-consumer-modules)
 - [Key UI surfaces](#key-ui-surfaces)
 - [Develop & test](#develop--test)
 
@@ -76,6 +79,29 @@ earlier than before takes the entire SPA down at boot, and the unit suite cannot
 (nothing there installs the plugin). Every e2e spec does, because every one of them boots
 the app.
 
+### A backend-DECLARED form renders through `DescriptorFields.vue`
+
+When the backend declares the fields and the SPA only collects them, render them with the shared
+`components/common/DescriptorFields.vue` over the contracts vocabulary
+(`contracts/src/form-fields.ts`), and never hand-roll a second renderer for the same shapes. Two
+surfaces use it: an initiative preset's create form and a reusable operation's per-case form on a
+custom task type (`AddTaskModal`). Adding a third is a `:fields` binding, not a component.
+
+Four rules travel with it. **Validate with the shared `validateDescriptorFields`** so the submit
+button reflects exactly what the server will refuse, and **submit the shared
+`sanitizeDescriptorFields` result** so a stale answer on a since-hidden `showWhen` field never
+reaches the wire. **The labels are deployment-authored English rendered verbatim**: only the chrome
+around them (a path-invalid message, section captions) is i18n, so no descriptor string enters a
+locale catalog. And **the value-bag rules live in `utils/descriptorFields.ts`, not in the SFC**
+(`defaultDescriptorValues` for the initial values, `setDescriptorValue` / `setDescriptorCheckbox` /
+`toggleDescriptorGroupValue` for one edit): what an edit freezes on an entity is what a unit test
+must be able to reach, and a rule inside a component is only reachable by mounting one.
+
+Mirroring the server's check leaves one refusal still reachable, deliberately: the deployment can
+re-register the descriptor while the dialog sits open, so a create can come back `422` with
+`details.reason: 'task_type_fields_invalid'`. Map it to translated copy like any other reason
+(`AddTaskModal`'s `createRefusalMessage`) rather than showing the server's field-key prose.
+
 ### Always import a layer component explicitly
 
 **Import a component under `components/` by path before using it in a template.** Do not lean on Nuxt's auto-registration. This layer sets no `components` config, so the default `pathPrefix: true` applies and a component is registered under its path-prefixed name: `components/panels/StepEffortReport.vue` becomes `PanelsStepEffortReport`, and a bare `<StepEffortReport>` matches nothing.
@@ -132,7 +158,7 @@ hoc where it can be avoided:
     and the deployment-wide operator + reports rollups).
 
   Sole-route items stay in basic when the delivery loop runs on them: the pipeline builder,
-  add-from-repo, the fragment library, the infrastructure/PREnv windows, and the workspace /
+  add-from-repo, the fragment library, the infrastructure/ephemeral-env windows, and the workspace /
   model configuration a run actually reads. `nav-contributions.spec.ts` pins the advanced set
   against a table naming each item's kind and reason, so promoting one forces that claim to be
   written down rather than assumed.
@@ -329,7 +355,7 @@ is SUPPRESSED rather than unmounted, because it holds the running tour's resolve
 remount would re-resolve it against gates that may have flipped since the tour started.
 
 The decisions behind this surface, and why each alternative was rejected, are recorded in
-[ADR 0033](../../backend/docs/adr/0033-in-app-tutorials.md). This section is the authority on how
+[ADR 0036](../../backend/docs/adr/0036-in-app-tutorials.md). This section is the authority on how
 the thing WORKS.
 
 A tour is **data, not components**: an ordered list of steps, each pointing at an on-screen
@@ -511,6 +537,111 @@ guard scans the layer for both ways an id is named: written onto an element, or
 `testId` field on a data contribution (the whole `nav-*` family reaches the DOM that way). It
 is scoped to the built-in catalog, since a consumer's tours anchor on its own layer.
 
+## Real-time store coherence: avoid the full-refresh CLOBBER
+
+The recurring product bug behind most e2e flakes: a stale full-snapshot refresh clobbering newer
+live state. The SPA has two delivery shapes and mixing them wrong drops live-added state with NO
+event left to restore it.
+
+- **Know how your entity is delivered.** A `board` event is COARSE: no payload, only a debounced
+  full `workspace.refresh()`, and `hydrate` REPLACES whole lists. A spawned task/module block
+  reaches the browser ONLY this way. Targeted events (`execution`/`bootstrap`/`initiative`) carry
+  the entity and `upsert` it, so they don't clobber. Prefer a targeted upsert for anything that
+  must appear reliably.
+- **Full refreshes MUST be monotonic.** Two `refresh()` calls can be in flight; a staler one
+  resolving later overwrites the newer. `workspace.refresh()` guards this with a sequence. Do not
+  reintroduce an unguarded `hydrate(await fetch())`, and apply the guard to any new coalesced
+  refresh path.
+- **Never gate readiness on a snapshot a later resync can undo.** The on-connect resync flips
+  `connected` only after it settles (which is why e2e gates on `data-connected`).
+- **A REPLACE-style `hydrate` must never silently drop live-only state.** Either fold that state
+  into the snapshot or reconcile rather than replace.
+- **An action's OPTIMISTIC ECHO is a clobber too, and it bypasses both guards above.** A store
+  that awaits a mutation and then assigns the returned sub-state onto the cached run
+  (`step.forkDecision`, `step.prReview`, `step.judge`, `step.followUps`) is writing straight past
+  `upsert`'s `rev` check. Where the mutation WAKES THE DRIVER, the driver's next emit routinely
+  beats the HTTP response, so the echo puts the run back; if the run then parks, nothing emits
+  again and the newer state is gone for good (the fork-chat reply that vanished, leaving a
+  "thinking…" bubble spinning). Every echo therefore goes through
+  `execution.echoAfter(executionId, send, apply)`, which captures the run's `rev` before the
+  request and drops the echo if anything advanced it. Never hand-roll the await-then-assign.
+- **Pin it with a store-level unit test** (`stores/workspace.spec.ts` for refreshes,
+  `stores/execution.spec.ts` for echoes): drive the two orderings and assert the fresher one
+  wins.
+
+## Internationalization (i18n) authoring
+
+All user-facing SPA copy goes through `@nuxtjs/i18n`; never hard-code a display string. This
+layer ships the base `en` locale, and a downstream deployment overrides by dropping its own files
+(the per-layer deep-merge is the override seam, consumer wins key by key). Migration status:
+[`docs/localization.md`](../../docs/localization.md).
+
+- `i18n/locales/<locale>.json`: the catalogs (the v9+ `i18n/` convention, NOT `app/locales/`).
+- `i18n/i18n.config.ts`: runtime vue-i18n behaviour only (fallback locale, the named
+  `numberFormats`/`datetimeFormats`). Messages are deliberately NOT here so the module can
+  deep-merge across the `extends` chain. Referenced as the BARE filename
+  `vueI18n: 'i18n.config.ts'`, never `layerDir`-anchored.
+- `package.json` `files` MUST include `"i18n"`. Release-blocking.
+
+**Adding a string**: add the key to `en.json` under the feature namespace, resolve with
+`t('feature.area.key')`, and format numbers/dates through `$n`/`$d` (the named formats), never
+raw `Intl`.
+
+**Key conventions**: one namespace per feature; **leaf keys mirror the enum/code value verbatim**
+so a dynamic lookup is total; **no cross-key concatenation** (a full sentence is ONE key with
+`{named}` placeholders, plurals use the pipe form).
+
+**Component mechanics that bite:**
+
+- `useI18n` is auto-imported; destructure in `<script setup>` and use those fns in the template
+  so the typed-key check sees literal keys. Never `import` it.
+- Plural + interpolation: `t(key, { vendor, count }, count)`, where the THIRD arg is the choice.
+- **Code/format-example placeholders stay INLINE**, not in the catalog; required when they
+  contain `{`/`}` (vue-i18n metacharacters). Only prose placeholders get a key. Same for brand
+  names.
+- **No HTML in message bodies**: drop mid-sentence `<strong>`, or use `<i18n-t>` with slots.
+- For a vendor/enum-keyed set, build an array of STATIC literal `t()` keys, one per member.
+  Reserve the runtime-assembled key + exhaustive `Record` guard for lookups genuinely unknown
+  until runtime.
+- Straight quotes, no em-dashes in new entries.
+
+**Translator descriptions (`@<key>` siblings): default to NONE.** They live only in `en.json` and
+are notes to a translator, never runtime data. Add one ONLY when a competent translator seeing
+the English and the key path could plausibly get it wrong: homograph / part-of-speech ambiguity
+(`@close`), proper nouns that must NOT be translated (`@kaizen`), umbrella strings hiding cases
+the text doesn't show, placeholder/format constraints, or plural-form requirements beyond
+English's two.
+
+**Presenting a backend failure**: raw backend prose is DETAIL, never the description. Even with
+no `reason` to key off, a failure is described from its STATUS CLASS through an exhaustive
+`Record<ApiErrorCode, …>` of translated copy, and the untranslated `message` (plus a validation
+400's `issues` and the envelope's `requestId`) is reached through a "Show details" disclosure
+that reveals it in place. So a non-English user is never handed English as the primary
+explanation, and the elaborate operator remedies the backend does write stay one click away
+rather than being dropped. A new failure-presenting surface copies that split (the
+`usePipelineErrorToast.ts` pattern; the wire vocabulary comes from `@cat-factory/contracts`).
+
+**Drift guards** (oxlint has no `no-raw-text` rule, so these replace it):
+
+1. **Typed message keys** make a statically written unknown `t('literal.key')` a typecheck
+   failure. This does NOT cover a runtime-assembled key.
+2. For enum→key lookups, guard with an **exhaustive `Record<TheEnum, string>`** keyed off the
+   contracts union, plus a runtime `te()` fallback. Never rely on tier 1 alone for a
+   reason/status-keyed lookup.
+3. `pnpm --filter @cat-factory/app run i18n:check` hard-fails on MISSING keys and reports unused
+   ones as non-blocking warnings (the catalog legitimately seeds keys ahead of use).
+4. **Locale parity**: `i18n-locale-parity.mjs --since origin/<base>` requires a PR that adds,
+   changes, or removes an `en.json` key to make the SAME change in every other locale. It is
+   change-coupling against the merge-base, NOT full key parity.
+
+**Translate for real: NEVER ship an English string as a non-`en` value.** The parity gate checks
+only that the key exists, so it will pass a verbatim English copy, and that copy is a bug. The
+only values that may legitimately match `en` are proper nouns identical across languages
+(`DeepSeek`, `AWS Bedrock`). If you genuinely cannot produce a translation, say so in the PR
+rather than committing a placeholder that reads as done.
+
+Migration is incremental: when you touch a component, lift its visible copy into the catalog.
+
 ## Extending the layer (consumer modules)
 
 A deployment can contribute its own components (result windows, nav entries, inspector

package/app/components/board/AddTaskModal.vue

@@ -15,6 +15,7 @@
 // (see useContextLinking) — the same context the agents see for every step of the run.
 import type {
   CreateTaskType,
+  DescriptorFieldValues,
   DocKind,
   DocKindFieldKey,
   TaskSourceKind,
@@ -25,11 +26,14 @@ import { resolveComponentRegistry } from '@modular-vue/core'
 import { useReactiveSlots } from '@modular-vue/runtime'
 import type { AppSlots, ResultViewContribution } from '~/modular/slots'
 import ContextAttachmentFields from '~/components/context/ContextAttachmentFields.vue'
+import DescriptorFields from '~/components/common/DescriptorFields.vue'
 import FragmentSelector from '~/components/fragments/FragmentSelector.vue'
 import RiskPolicyPicker from '~/components/riskPolicy/RiskPolicyPicker.vue'
 import { parseConflict } from '~/composables/usePipelineErrorToast'
 import { apiErrorEnvelope } from '~/composables/api/errors'
 import type { ReviewTargetReason } from '@cat-factory/contracts'
+import { sanitizeDescriptorFields, validateDescriptorFields } from '@cat-factory/contracts'
+import { defaultDescriptorValues } from '~/utils/descriptorFields'
 import { pipelineAllowedForManualStart } from '~/utils/pipeline'
 
 const ui = useUiStore()
@@ -155,8 +159,9 @@ const selectedCustomType = computed(() =>
   customTaskTypes.value.find((tt) => tt.taskType === taskType.value),
 )
 // Descriptor-field values for a selected custom type (or a bespoke form panel's own bag), folded
-// into `taskTypeFields.custom` on submit. Cleared when the type changes / the modal reopens.
-const customFieldValues = ref<Record<string, string | number>>({})
+// into `taskTypeFields.custom` on submit. Re-seeded to the descriptor's own defaults when the type
+// changes / the modal reopens (its fields differ per type, so a carried-over bag would be foreign).
+const customFieldValues = ref<DescriptorFieldValues>({})
 // A bespoke create-form section paired to the custom type's `formPanel` id via the
 // `taskTypeFormPanels` slot; shown INSTEAD of the descriptor fields. Unpaired ⇒ descriptor fields
 // (degrade, never crash) — the same pairing shape as the result-view windows.
@@ -168,19 +173,15 @@ const customFormPanel = computed(() => {
   const id = selectedCustomType.value?.formPanel
   return id ? (formPanelRegistry.value.get(id) ?? null) : null
 })
-// Whether every REQUIRED descriptor field of the selected custom type has a value. Only the
-// descriptor path is enforced up front — a bespoke `formPanel` owns its own validation, so we
-// don't block on it (nor can we read its required semantics). No custom type selected (or none
-// of its fields are required) ⇒ trivially satisfied. Folded into `canAdd` so the required marker
-// the form renders is actually honoured before submit.
-const customRequiredFieldsFilled = computed(() => {
+// Client-side mirror of the server's creation check (the SAME shared function `BoardService` runs),
+// so the submit button reflects an invalid form: a missing required answer, a value outside its
+// declared options, an over-long string. Only the descriptor path is checked up front, since a
+// bespoke `formPanel` owns its own validation and the platform cannot read its required semantics.
+// The per-field path error is rendered inline by `DescriptorFields`.
+const customFieldProblems = computed(() => {
   const custom = selectedCustomType.value
-  if (!custom || customFormPanel.value) return true
-  return (custom.fields ?? []).every((field) => {
-    if (!field.required) return true
-    const raw = customFieldValues.value[field.key]
-    return raw !== undefined && String(raw).trim() !== ''
-  })
+  if (!custom || customFormPanel.value) return []
+  return validateDescriptorFields(custom.fields ?? [], customFieldValues.value)
 })
 // The type picker: the built-in choices (i18n labels) + the custom types (their wire presentation).
 const typeChoices = computed<{ value: TaskTypeChoice; label: string; icon: string }[]>(() => [
@@ -258,28 +259,21 @@ const DOC_FIELD_PLACEHOLDER_KEYS: Record<DocKindFieldKey, string> = {
 const SEVERITIES = ['low', 'medium', 'high', 'critical'] as const
 
 // A CUSTOM (deployment-registered) task type: fold the collected values into the sparse
-// `taskTypeFields.custom` bag. A bespoke form panel owns the whole bag (taken verbatim); the
-// descriptor path reads only the declared fields, coercing a `number` descriptor's string input.
+// `taskTypeFields.custom` bag. A bespoke form panel owns the whole bag (taken verbatim, minus blank
+// entries); the descriptor path sends the SANITIZED subset (declared, currently-visible fields), so
+// a stale answer on a since-hidden `showWhen` field never reaches the wire. The renderer already
+// keeps each value in its contract shape, so nothing needs coercing here.
 function buildCustomTypeFields(): TaskTypeFields | undefined {
   const custom = selectedCustomType.value
   if (!custom) return undefined
-  const bag: Record<string, string | number> = {}
+  let bag: DescriptorFieldValues
   if (customFormPanel.value) {
+    bag = {}
     for (const [key, value] of Object.entries(customFieldValues.value)) {
       if (value !== undefined && value !== '') bag[key] = value
     }
   } else {
-    for (const field of custom.fields ?? []) {
-      const raw = customFieldValues.value[field.key]
-      if (raw === undefined || raw === '') continue
-      if (field.type === 'number') {
-        // Skip a non-numeric value rather than sending NaN (which serialises to null on the wire).
-        const n = Number(raw)
-        if (Number.isFinite(n)) bag[field.key] = n
-      } else {
-        bag[field.key] = raw
-      }
-    }
+    bag = sanitizeDescriptorFields(custom.fields ?? [], customFieldValues.value)
   }
   return Object.keys(bag).length ? { custom: bag } : undefined
 }
@@ -416,12 +410,13 @@ const DEFAULT_PIPELINE_FOR_TYPE: Partial<Record<TaskTypeChoice, string>> = {
   review: 'pl_review',
 }
 watch(taskType, (next) => {
-  // A custom type owns a fresh field bag on every switch (its descriptors differ per type).
-  customFieldValues.value = {}
+  const custom = customTaskTypes.value.find((tt) => tt.taskType === next)
+  // A custom type owns a fresh field bag on every switch (its descriptors differ per type), seeded
+  // to whatever defaults the new type declares.
+  customFieldValues.value = defaultDescriptorValues(custom?.fields ?? [])
   // Pre-select the type's default pipeline: a custom type's registered `defaultPipelineId`, else
   // the built-in map. (For a custom type with no default, `BoardService` applies the registry
   // default at creation, so leaving the picker unset is fine.)
-  const custom = customTaskTypes.value.find((tt) => tt.taskType === next)
   const preset = custom?.defaultPipelineId ?? DEFAULT_PIPELINE_FOR_TYPE[next]
   if (!preset) return
   const match = pipelines.pipelines.find((p) => p.id === preset)
@@ -526,6 +521,9 @@ watch(open, (isOpen) => {
   docOutlineHints.value = ''
   reviewPrRef.value = ''
   reviewFocus.value = ''
+  // Empty rather than default-seeded: `taskType` was just reset to a BUILT-IN above, which
+  // declares no descriptor fields. Picking a custom type from here runs the `taskType` watcher,
+  // and that is the one place the new type's declared defaults are seeded.
   customFieldValues.value = {}
   // Pre-seed the best-practice fragments from the enclosing service's standards, so a new task
   // ships with its service's fragments already selected (and freely add/removable here). The task
@@ -610,8 +608,8 @@ const canAdd = computed(() => {
     configValue(RALPH_VALIDATION_COMMAND_ID, '').trim().length === 0
   )
     return false
-  // A custom type's required descriptor fields must be filled (its form renders them as required).
-  if (!customRequiredFieldsFilled.value) return false
+  // A custom type's collected form must satisfy its descriptor (the same rule the server enforces).
+  if (customFieldProblems.value.length > 0) return false
   return true
 })
 
@@ -684,7 +682,7 @@ async function submitCreate(acknowledgeReviewDebt: boolean) {
     }
     toast.add({
       title: t('board.addTask.addFailedTitle'),
-      description: reviewTargetMessage(e) ?? (e instanceof Error ? e.message : String(e)),
+      description: createRefusalMessage(e) ?? (e instanceof Error ? e.message : String(e)),
       icon: 'i-lucide-triangle-alert',
       color: 'error',
     })
@@ -714,10 +712,22 @@ const REVIEW_TARGET_MESSAGES: Record<
       : null,
 }
 
-function reviewTargetMessage(error: unknown): string | null {
+/**
+ * Translated copy for a machine-readable creation refusal, or null to fall back to the server's
+ * own English prose. Two reasons are recognised: a review task's unresolvable target PR, and a
+ * custom type's collected values contradicting its descriptor.
+ *
+ * The second one is reachable here even though `canAdd` mirrors the same check client-side, and
+ * that is the whole point of the server-side check: the descriptor can be re-registered while this
+ * dialog sits open, so the form the user filled is not the form the server now validates against.
+ * The individual problems stay out of the copy: they are backend English naming field keys, so
+ * what the user is told is the ONE thing they can act on (reopen the dialog).
+ */
+function createRefusalMessage(error: unknown): string | null {
   const details = (apiErrorEnvelope(error)?.details ?? {}) as Record<string, unknown>
   const reason = details.reason
   if (typeof reason !== 'string') return null
+  if (reason === 'task_type_fields_invalid') return t('board.addTask.customFieldsInvalid')
   return REVIEW_TARGET_MESSAGES[reason as ReviewTargetReason]?.(details) ?? null
 }
 
@@ -1045,8 +1055,9 @@ function openReviewFrictionDialog(conflict: NonNullable<ReturnType<typeof parseC
 
           <!-- A CUSTOM (deployment-registered) task type: a bespoke create-form section when its
                `formPanel` is paired to the `taskTypeFormPanels` slot, else the descriptor-driven
-               `fields` the type declares. None of the built-in `v-if` branches above match a
-               namespaced custom type, so this renders on its own. -->
+               `fields` the type declares, rendered by the SHARED renderer the initiative-preset form
+               uses. None of the built-in `v-if` branches above match a namespaced custom type, so
+               this renders on its own. -->
           <div v-if="selectedCustomType" class="space-y-3" data-testid="custom-task-fields">
             <component
               :is="customFormPanel"
@@ -1055,47 +1066,12 @@ function openReviewFrictionDialog(conflict: NonNullable<ReturnType<typeof parseC
               :model-value="customFieldValues"
               @update:model-value="customFieldValues = $event"
             />
-            <template v-else>
-              <UFormField
-                v-for="field in selectedCustomType.fields ?? []"
-                :key="field.key"
-                :label="field.label"
-                :help="field.help"
-                :required="field.required"
-              >
-                <div v-if="field.type === 'select'" class="flex flex-wrap gap-1">
-                  <UButton
-                    v-for="opt in field.options ?? []"
-                    :key="opt.value"
-                    :color="customFieldValues[field.key] === opt.value ? 'primary' : 'neutral'"
-                    :variant="customFieldValues[field.key] === opt.value ? 'soft' : 'ghost'"
-                    size="xs"
-                    :data-testid="`custom-field-${field.key}-${opt.value}`"
-                    @click="() => (customFieldValues[field.key] = opt.value)"
-                  >
-                    {{ opt.label }}
-                  </UButton>
-                </div>
-                <UTextarea
-                  v-else-if="field.type === 'textarea'"
-                  v-model="customFieldValues[field.key]"
-                  :rows="2"
-                  :maxlength="field.maxLength"
-                  :placeholder="field.placeholder"
-                  :data-testid="`custom-field-${field.key}`"
-                  class="w-full"
-                />
-                <UInput
-                  v-else
-                  v-model="customFieldValues[field.key]"
-                  :type="field.type === 'number' ? 'number' : 'text'"
-                  :maxlength="field.maxLength"
-                  :placeholder="field.placeholder"
-                  :data-testid="`custom-field-${field.key}`"
-                  class="w-full"
-                />
-              </UFormField>
-            </template>
+            <DescriptorFields
+              v-else
+              v-model="customFieldValues"
+              :fields="selectedCustomType.fields ?? []"
+              testid-prefix="custom-field"
+            />
           </div>
 
           <!-- One column in basic mode, where the pipeline picker is the only survivor and a

package/app/components/board/CreateInitiativeModal.vue

@@ -6,7 +6,8 @@
 // sanitized) preset inputs on the entity. Nothing is planned here: the user then runs the preset's
 // planning pipeline on the block from the inspector.
 //
-// The preset form is rendered GENERICALLY from `descriptor.fields` (InitiativePresetFields) — zero
+// The preset form is rendered GENERICALLY from `descriptor.fields` by the shared
+// `DescriptorFields` renderer (the same one a custom task type's per-case form uses): zero
 // per-preset frontend code. A preset with a repo-detection probe prefills its form from the frame's
 // repo on selection (best-effort; failures fall back to descriptor defaults and never block create).
 //
@@ -20,9 +21,9 @@ import {
   validateInitiativePresetInputs,
 } from '@cat-factory/contracts'
 import type { InitiativePresetInputs, InitiativePresetInputValue } from '~/types/domain'
-import { defaultPresetInputs } from '~/utils/initiative'
+import { defaultDescriptorValues } from '~/utils/descriptorFields'
 import { GENERIC_PRESET_ID } from '~/stores/initiative'
-import InitiativePresetFields from '~/components/board/InitiativePresetFields.vue'
+import DescriptorFields from '~/components/common/DescriptorFields.vue'
 import ContextAttachmentFields from '~/components/context/ContextAttachmentFields.vue'
 import type { PendingContext } from '~/composables/useContextLinking'
 
@@ -62,7 +63,7 @@ let probeSeq = 0
 /** Seed the form to the selected preset's descriptor defaults, then fire its detection probe. */
 function applyPreset(): void {
   const descriptor = selectedPreset.value
-  inputs.value = descriptor ? defaultPresetInputs(descriptor) : {}
+  inputs.value = descriptor ? defaultDescriptorValues(descriptor.fields) : {}
   void runProbe()
 }
 
@@ -227,10 +228,11 @@ async function create() {
         </UFormField>
 
         <!-- The preset's descriptor-driven form (renders nothing for the fieldless generic preset). -->
-        <InitiativePresetFields
+        <DescriptorFields
           v-if="selectedPreset"
           v-model="inputs"
-          :descriptor="selectedPreset"
+          :fields="selectedPreset.fields"
+          testid-prefix="initiative-preset-field"
         />
 
         <!-- Attached requirements / issues, staged here and linked once the block exists. The

package/app/components/{board/InitiativePresetFields.vue → common/DescriptorFields.vue}

@@ -1,68 +1,68 @@
 <script setup lang="ts">
-// Generic, descriptor-driven renderer for an initiative preset's create-time FORM. Extends the
-// `ProviderConnectionTab.vue` flat-field pattern with the three shapes a preset form adds:
-// `checkbox-group` (multi-select → `string[]`), `path` (a repo-relative dir with inline
-// safety validation), and single-condition `showWhen` visibility. Every preset renders through
-// THIS component with zero per-preset frontend code — the backend descriptor supplies the fields
-// (labels/help/options are backend-supplied English, per the `describeConfig` convention). The
-// model is the typed `InitiativePresetInputs` map (scalars stay strings, `number` a number,
-// `checkbox` a boolean, `checkbox-group` a `string[]`) so it round-trips the wire contract and the
-// shared `validateInitiativePresetInputs` unchanged.
+// Generic, descriptor-driven form renderer: ONE component behind every surface where the BACKEND
+// declares the fields and the SPA only collects them. Two use it today, and they used to carry
+// near-duplicate renderers of the same vocabulary:
+//
+//   - an initiative PRESET's create-time form (`CreateInitiativeModal`)
+//   - a reusable OPERATION's per-case brief on a custom task type (`AddTaskModal`)
+//
+// It extends `ProviderConnectionTab.vue`'s flat-field pattern with the shapes a declared form needs:
+// `checkbox-group` (multi-select whose value is `string[]`), `path` (a repo-relative dir with inline
+// safety validation), and single-condition `showWhen` visibility. Labels/help/option captions are
+// backend-supplied English (the `describeConfig` convention); only the chrome is i18n.
+//
+// The model is the typed `DescriptorFieldValues` map (scalars stay strings, `number` a number,
+// `checkbox` a boolean, `checkbox-group` a `string[]`), so it round-trips the wire contract and the
+// shared `validateDescriptorFields` / `sanitizeDescriptorFields` rules unchanged.
 import { computed } from 'vue'
-import { isPresetFieldVisible, isSafeRepoDirPath } from '@cat-factory/contracts'
-import type {
-  InitiativePresetDescriptor,
-  InitiativePresetField,
-  InitiativePresetInputs,
-  InitiativePresetInputValue,
-} from '~/types/domain'
+import { isDescriptorFieldVisible, isSafeRepoDirPath } from '@cat-factory/contracts'
+import type { DescriptorField, DescriptorFieldValue, DescriptorFieldValues } from '~/types/domain'
+import {
+  descriptorGroupValue,
+  setDescriptorCheckbox,
+  setDescriptorValue,
+  toggleDescriptorGroupValue,
+} from '~/utils/descriptorFields'
 
-const props = defineProps<{ descriptor: InitiativePresetDescriptor }>()
-const model = defineModel<InitiativePresetInputs>({ required: true })
+const props = withDefaults(
+  defineProps<{
+    /** The fields to render, in declaration order (a preset's `fields`, a task type's `fields`). */
+    fields: readonly DescriptorField[]
+    /**
+     * Prefix for each field's `data-testid`, so a spec targets a field by the SURFACE it is on
+     * (`custom-field-entity`) rather than by which component happens to render it.
+     */
+    testidPrefix?: string
+  }>(),
+  { testidPrefix: 'descriptor-field' },
+)
+const model = defineModel<DescriptorFieldValues>({ required: true })
 const { t } = useI18n()
 
 // Only fields whose `showWhen` holds against the current values are shown; a hidden field's stale
 // value is kept in the model (so re-showing restores it) but the server + client both drop it at
 // sanitize/validate time, so it can never freeze an unvalidated value.
 const visibleFields = computed(() =>
-  props.descriptor.fields.filter((f) => isPresetFieldVisible(f, model.value)),
+  props.fields.filter((f) => isDescriptorFieldVisible(f, model.value)),
 )
 
-/**
- * An "empty" value that must stay ABSENT from the model rather than freeze on the entity: an
- * unchecked (`false`) checkbox, a blank string, or an empty multi-select. A numeric `0` is a real
- * value and is kept (strict `=== false`/`=== ''` never match it).
- */
-function isEmptyValue(value: InitiativePresetInputValue): boolean {
-  return value === false || value === '' || (Array.isArray(value) && value.length === 0)
+// The value-mutation rules live in `utils/descriptorFields.ts` as pure functions over the bag (what
+// an edit does to it, including the drop-when-empty rule that keeps an unset answer from freezing),
+// so they are unit-tested without mounting this component. Here they are only bound to the model.
+function set(key: string, value: DescriptorFieldValue | undefined): void {
+  model.value = setDescriptorValue(model.value, key, value)
+}
+
+function setCheckbox(field: DescriptorField, checked: boolean): void {
+  model.value = setDescriptorCheckbox(model.value, field, checked)
 }
 
-/**
- * Immutably set one field's value on the model, DROPPING empty values so a cleared field never
- * freezes an empty `''`/`[]`/`false` (mirrors `ProviderConnectionTab`'s delete-when-blank and what
- * the shared `validate`/`sanitize` treat as unset — an unchecked box / blank field stays absent).
- */
-function set(key: string, value: InitiativePresetInputValue | undefined): void {
-  const next = { ...model.value }
-  if (value === undefined || isEmptyValue(value)) delete next[key]
-  else next[key] = value
-  model.value = next
+function toggleGroup(key: string, option: string, checked: boolean): void {
+  model.value = toggleDescriptorGroupValue(model.value, key, option, checked)
 }
 
-/**
- * Set a checkbox value. A checkbox whose descriptor default is ON (`default: 'true'`) must be able
- * to persist an explicit `false`: {@link set} otherwise drops a `false` (an off box "stays unset"),
- * which for a default-ON field is indistinguishable from "untouched, still on" — so a consumer that
- * reads the opt-out as `humanReview !== false` (e.g. `seedMigrationPlan`) could never observe the
- * unchecked state and the toggle would be dead. A default-OFF checkbox keeps the drop-when-false
- * behaviour (absent === unchecked), so it never freezes a redundant `false`.
- */
-function setCheckbox(field: InitiativePresetField, checked: boolean): void {
-  if (!checked && field.default === 'true') {
-    model.value = { ...model.value, [field.key]: false }
-    return
-  }
-  set(field.key, checked)
+function groupValue(key: string): string[] {
+  return descriptorGroupValue(model.value, key)
 }
 
 function stringValue(key: string): string {
@@ -76,24 +76,15 @@ function numberStr(key: string): string {
   const v = model.value[key]
   return typeof v === 'number' ? String(v) : ''
 }
-function groupValue(key: string): string[] {
-  const v = model.value[key]
-  return Array.isArray(v) ? v : []
-}
-
-function toggleGroup(key: string, option: string, checked: boolean): void {
-  const current = groupValue(key)
-  set(key, checked ? [...new Set([...current, option])] : current.filter((o) => o !== option))
-}
 
 /** A `path` field is flagged only when non-empty AND unsafe (empty is handled by `required`). */
-function pathInvalid(field: InitiativePresetField): boolean {
+function pathInvalid(field: DescriptorField): boolean {
   if (field.type !== 'path') return false
   const value = stringValue(field.key)
   return value.trim().length > 0 && !isSafeRepoDirPath(value)
 }
 
-function selectItems(field: InitiativePresetField) {
+function selectItems(field: DescriptorField) {
   return (field.options ?? []).map((o) => ({ label: o.label, value: o.value }))
 }
 </script>
@@ -106,8 +97,8 @@ function selectItems(field: InitiativePresetField) {
       :label="field.label"
       :help="field.help"
       :required="field.required"
-      :error="pathInvalid(field) ? t('initiative.create.pathInvalid') : undefined"
-      :data-testid="`initiative-preset-field-${field.key}`"
+      :error="pathInvalid(field) ? t('common.pathInvalid') : undefined"
+      :data-testid="`${testidPrefix}-${field.key}`"
     >
       <!-- checkbox-group: a vertical list of toggles whose value is the checked option set. -->
       <div v-if="field.type === 'checkbox-group'" class="space-y-1.5">
@@ -116,6 +107,7 @@ function selectItems(field: InitiativePresetField) {
           :key="opt.value"
           :model-value="groupValue(field.key).includes(opt.value)"
           :label="opt.label"
+          :data-testid="`${testidPrefix}-${field.key}-${opt.value}`"
           @update:model-value="
             (v: boolean | 'indeterminate') => toggleGroup(field.key, opt.value, v === true)
           "
@@ -143,6 +135,7 @@ function selectItems(field: InitiativePresetField) {
         :rows="3"
         autoresize
         class="w-full"
+        :maxlength="field.maxLength"
         :placeholder="field.placeholder"
         @update:model-value="(v: string) => set(field.key, v)"
       />
@@ -163,6 +156,7 @@ function selectItems(field: InitiativePresetField) {
         :type="field.type === 'password' ? 'password' : 'text'"
         class="w-full"
         :class="{ 'font-mono': field.type === 'path' }"
+        :maxlength="field.maxLength"
         :placeholder="field.placeholder"
         @update:model-value="(v: string) => set(field.key, v)"
       />