@cat-factory/app 0.195.1 → 0.195.2

package/app/components/board/nodes/BlockNode.vue

@@ -75,6 +75,21 @@ const FRAME_LABEL_KEYS: Record<BlockStatus, string> = {
   done: 'board.frame.status.done',
 }
 const statusLabel = computed(() => t(FRAME_LABEL_KEYS[frameStatus.value]))
+// The badge is a ROLLUP over the frame's children, not a status anybody set on the service, and
+// the label alone never says which child produced it — "Needs attention" names no task, and
+// "Live" reads as a health check rather than "caught up". So each status gets its own tooltip
+// naming what it is rolled up from. `pr_ready`/`done` are unreachable here (`frameStatus` caps
+// below `done`: a service is long-lived and never finishes) but the Record stays exhaustive over
+// `BlockStatus` for the same reason the label map does, and mirrors that map's aliasing.
+const FRAME_STATUS_HINT_KEYS: Record<BlockStatus, string> = {
+  planned: 'board.frame.statusHint.planned',
+  ready: 'board.frame.statusHint.ready',
+  in_progress: 'board.frame.statusHint.in_progress',
+  blocked: 'board.frame.statusHint.blocked',
+  pr_ready: 'board.frame.statusHint.pr_ready',
+  done: 'board.frame.statusHint.done',
+}
+const statusHint = computed(() => t(FRAME_STATUS_HINT_KEYS[frameStatus.value]))
 
 const selected = computed(() => ui.selectedBlockId === props.id)
 // Services are always expanded to their task canvas, at every zoom level: there is no
@@ -349,7 +364,7 @@ const ITEM_ICON: Record<string, string> = {
           </UBadge>
         </div>
         <div class="flex items-center justify-between">
-          <UBadge :color="statusMeta.chip as any" variant="subtle" size="sm">{{
+          <UBadge :color="statusMeta.chip as any" variant="subtle" size="sm" :title="statusHint">{{
             statusLabel
           }}</UBadge>
           <span class="text-[11px] text-slate-400">{{
@@ -474,9 +489,13 @@ const ITEM_ICON: Record<string, string> = {
               </div>
             </div>
             <div class="flex items-center gap-1">
-              <UBadge :color="statusMeta.chip as any" variant="subtle" size="sm">{{
-                statusLabel
-              }}</UBadge>
+              <UBadge
+                :color="statusMeta.chip as any"
+                variant="subtle"
+                size="sm"
+                :title="statusHint"
+                >{{ statusLabel }}</UBadge
+              >
               <!-- Board-authoring buttons (create task / from issue / recurring / initiative)
                    are `board.write` — hidden for a read-only viewer, who keeps the badge +
                    collapse toggle (view-only affordances). -->

package/app/components/judge/JudgeResultView.vue

@@ -151,7 +151,11 @@ async function act(choice: 'proceed' | 'bounce' | 'stop') {
           <span class="text-[13px] font-semibold text-slate-100">
             {{ score === null ? t('judge.notScored') : n(score, 'percent') }}
           </span>
-          <span v-if="threshold !== null" class="text-[12px] text-slate-400">
+          <span
+            v-if="threshold !== null"
+            class="text-[12px] text-slate-400"
+            :title="t('judge.thresholdHint')"
+          >
             {{ t('judge.threshold', { threshold: n(threshold, 'percent') }) }}
           </span>
           <span v-if="judge.disposition" class="text-[12px] text-slate-400">

package/app/components/merge/MergeEffortChips.vue

@@ -87,7 +87,10 @@ function pick(effort: ReviewEffort) {
 <template>
   <div data-testid="merge-effort-chips" class="mt-2">
     <div class="flex items-center gap-1.5">
-      <span class="text-[10px] uppercase tracking-wide text-slate-500">
+      <span
+        class="text-[10px] uppercase tracking-wide text-slate-500"
+        :title="t('merge.effort.promptHint')"
+      >
         {{ t('merge.effort.prompt') }}
       </span>
       <UBadge
@@ -96,6 +99,7 @@ function pick(effort: ReviewEffort) {
         color="neutral"
         variant="subtle"
         size="sm"
+        :title="t('merge.changeClass.hint')"
       >
         {{ classLabel }}
       </UBadge>

package/app/components/panels/ReportsPanel.vue

@@ -309,12 +309,15 @@ watch(
                   </div>
                 </div>
                 <div class="mt-2 flex items-center gap-4 text-[11px] text-slate-500">
-                  <span class="flex items-center gap-1">
+                  <span class="flex items-center gap-1" :title="t('reports.legend.meteredHint')">
                     <span class="h-2 w-2 rounded-sm bg-violet-500" />{{
                       t('reports.legend.metered')
                     }}
                   </span>
-                  <span class="flex items-center gap-1">
+                  <span
+                    class="flex items-center gap-1"
+                    :title="t('reports.legend.subscriptionHint')"
+                  >
                     <span class="h-2 w-2 rounded-sm bg-amber-600" />{{
                       t('reports.legend.subscription')
                     }}

package/app/components/panels/ReportsSpendBreakdown.vue

@@ -40,7 +40,11 @@ const max = computed(() => maxOf(props.rows, spendMagnitude))
                figure would report money that was never billed. -->
           <span class="shrink-0 tabular-nums text-slate-400">
             {{ money(row.meteredCost) }}
-            <span v-if="row.subscriptionCost > 0" class="text-amber-400">
+            <span
+              v-if="row.subscriptionCost > 0"
+              class="text-amber-400"
+              :title="t('reports.legend.subscriptionHint')"
+            >
               {{ t('reports.spend.subscriptionAside', { value: money(row.subscriptionCost) }) }}
             </span>
           </span>

package/app/components/panels/StepEffortReport.vue

@@ -42,7 +42,12 @@ const difficultyClass = computed(() => BAR_CLASS[effortBand(props.report.difficu
     </div>
 
     <div class="flex items-center gap-2">
-      <span class="text-[12px] text-slate-300">{{ t('panels.stepDetail.effort.difficulty') }}</span>
+      <span
+        class="text-[12px] text-slate-300"
+        :title="t('panels.stepDetail.effort.difficultyHint')"
+      >
+        {{ t('panels.stepDetail.effort.difficulty') }}
+      </span>
       <div class="h-1.5 flex-1 overflow-hidden rounded-full bg-slate-700/60">
         <div
           class="h-full rounded-full"
@@ -50,7 +55,11 @@ const difficultyClass = computed(() => BAR_CLASS[effortBand(props.report.difficu
           :style="{ width: `${difficultyPct}%` }"
         />
       </div>
-      <span data-testid="step-effort-difficulty" class="text-[12px] font-medium text-slate-200">
+      <span
+        data-testid="step-effort-difficulty"
+        class="text-[12px] font-medium text-slate-200"
+        :title="t('panels.stepDetail.effort.difficultyHint')"
+      >
         {{ t('panels.stepDetail.effort.outOfTen', { value: report.difficulty }) }}
       </span>
     </div>

package/app/components/panels/StepFragmentAdherence.vue

@@ -33,7 +33,9 @@ function label(item: FragmentAdherence[number]): string {
       class="mb-2 flex items-center gap-1.5 text-[11px] font-semibold uppercase tracking-wide text-slate-400"
     >
       <UIcon name="i-lucide-clipboard-check" class="h-3.5 w-3.5" />
-      <span>{{ t('panels.stepDetail.adherence.heading') }}</span>
+      <span :title="t('panels.stepDetail.adherence.headingHint')">
+        {{ t('panels.stepDetail.adherence.heading') }}
+      </span>
     </div>
 
     <div class="space-y-2.5">
@@ -54,7 +56,10 @@ function label(item: FragmentAdherence[number]): string {
               :style="{ width: `${ratingPct(item.rating)}%` }"
             />
           </div>
-          <span class="shrink-0 text-[12px] font-medium text-slate-200">
+          <span
+            class="shrink-0 text-[12px] font-medium text-slate-200"
+            :title="t('panels.stepDetail.adherence.ratingHint')"
+          >
             {{ t('panels.stepDetail.adherence.outOfTen', { value: item.rating }) }}
           </span>
         </div>

package/app/components/panels/StepMetadataCard.vue

@@ -207,7 +207,10 @@ async function copyRunId() {
 
     <!-- standards (prompt fragments) folded into this step -->
     <div v-if="step.selectedFragmentIds && step.selectedFragmentIds.length" class="mt-4">
-      <div class="text-[11px] uppercase tracking-wide text-slate-500">
+      <div
+        class="text-[11px] uppercase tracking-wide text-slate-500"
+        :title="t('panels.stepMeta.standardsAppliedHint')"
+      >
         {{ t('panels.stepMeta.standardsApplied') }}
       </div>
       <div class="mt-1 flex flex-wrap gap-1">

package/app/components/pipeline/EstimateThresholdFields.vue

@@ -0,0 +1,74 @@
+<script setup lang="ts">
+// The estimate-gate threshold row, shared by every gate editor in the pipeline builder: a
+// companion step's own gate, a consensus step's escalation gate, and the Tester QC companion's
+// gate. One component because the three rendered the same 0..1 inputs from three copies of the
+// markup — and, more to the point, because the explanation these numbers need has to be worded
+// once. A bare "risk >=" label says nothing about where the score comes from, what its scale is,
+// or how the axes combine, and the scale is the trap: every other score the product shows a user
+// (judge verdicts, effort difficulty, adherence ratings) is out of ten, so an unlabelled 0..1
+// field reads as "risk 1 out of 10" and gates a step that was meant to run on everything.
+//
+// The gate itself is edited by the parent (the builder mutates store drafts in place), so this
+// component only renders and reports: it never writes through the `gating` prop.
+import type { EstimateAxis } from '~/utils/estimateGating'
+import {
+  ESTIMATE_AXIS_FIELD,
+  ESTIMATE_AXIS_HINT_KEYS,
+  ESTIMATE_AXIS_LABEL_KEYS,
+  parseAxisThreshold,
+} from '~/utils/estimateGating'
+
+const props = defineProps<{
+  /** The gate being edited. Read-only here — changes go back through `update`. */
+  gating: { minComplexity?: number; minRisk?: number; minImpact?: number }
+  /** Which axes this gate exposes, in render order. */
+  axes: readonly EstimateAxis[]
+  /** What clearing the gate DOES, which differs per gate and is half the explanation. */
+  outcome: 'step' | 'consensus'
+}>()
+
+const emit = defineEmits<{ update: [axis: EstimateAxis, value: number | undefined] }>()
+
+const { t } = useI18n()
+
+// Exhaustive Record over the two outcomes with LITERAL keys, so the typed-message-key check sees
+// them and a third outcome fails the typecheck rather than falling back to the step wording.
+const OUTCOME_HINT_KEYS: Record<'step' | 'consensus', string> = {
+  step: 'pipeline.builder.gatingRunWhenAnyHint',
+  consensus: 'pipeline.builder.gatingRunWhenAnyConsensusHint',
+}
+
+const fields = computed(() =>
+  props.axes.map((axis) => ({
+    axis,
+    label: t(ESTIMATE_AXIS_LABEL_KEYS[axis]),
+    hint: t(ESTIMATE_AXIS_HINT_KEYS[axis]),
+    value: props.gating[ESTIMATE_AXIS_FIELD[axis]],
+  })),
+)
+
+function commit(axis: EstimateAxis, raw: string) {
+  emit('update', axis, parseAxisThreshold(raw))
+}
+</script>
+
+<template>
+  <div class="flex flex-wrap items-center gap-2 border-t border-slate-800 pt-2">
+    <span class="text-[10px] text-slate-500" :title="t(OUTCOME_HINT_KEYS[outcome])">
+      {{ t('pipeline.builder.runWhenAny') }}
+    </span>
+    <template v-for="f in fields" :key="f.axis">
+      <label class="text-slate-400" :title="f.hint">{{ f.label }}</label>
+      <input
+        :value="f.value"
+        :title="f.hint"
+        type="number"
+        min="0"
+        max="1"
+        step="0.1"
+        class="w-14 rounded border border-slate-700 bg-slate-900 px-1.5 py-0.5 text-slate-100"
+        @change="commit(f.axis, ($event.target as HTMLInputElement).value)"
+      />
+    </template>
+  </div>
+</template>

package/app/components/pipeline/OutputBudgetInput.vue

@@ -63,6 +63,7 @@ function commit(raw: string | number) {
     :min="MIN_AGENT_MAX_OUTPUT_TOKENS"
     :max="MAX_AGENT_MAX_OUTPUT_TOKENS"
     :placeholder="placeholder"
+    :title="t('pipeline.outputBudget.hint')"
     :disabled="disabled"
     @change="commit(($event.target as HTMLInputElement).value)"
   />

package/app/components/pipeline/PipelineBuilder.vue

@@ -5,7 +5,9 @@ import type { AgentKind, Pipeline, PipelinePurpose } from '~/types/domain'
 import AgentPalette from '~/components/palettes/AgentPalette.vue'
 import AgentKindIcon from '~/components/pipeline/AgentKindIcon.vue'
 import AgentPromptEditor from '~/components/pipeline/AgentPromptEditor.vue'
+import EstimateThresholdFields from '~/components/pipeline/EstimateThresholdFields.vue'
 import OutputBudgetInput from '~/components/pipeline/OutputBudgetInput.vue'
+import { ESTIMATE_AXES, ESTIMATE_AXIS_FIELD, type EstimateAxis } from '~/utils/estimateGating'
 import { showOverrideField } from '~/utils/uiMode'
 import {
   agentKindMeta,
@@ -47,6 +49,31 @@ function addParticipant(i: number) {
 function removeParticipant(i: number, pIdx: number) {
   pipelines.draftConsensus[i]?.participants.splice(pIdx, 1)
 }
+/**
+ * The consensus escalation gate exposes only the two axes its toggle seeds (risk + impact) —
+ * complexity is a fine reason to run a deeper TEST audit but a poor reason to convene a panel,
+ * which is about disagreement risk. A module constant rather than a template literal so the
+ * array identity is stable across re-renders.
+ */
+const CONSENSUS_ESTIMATE_AXES: readonly EstimateAxis[] = ['risk', 'impact']
+
+// Writing one axis floor back onto each of the three draft gates. These are functions rather
+// than assignments inlined in the template because a template `v-if` does not narrow inside an
+// event handler's closure, so the inline form needs a non-null assertion at every call site —
+// and a `!` on a gate that has since been toggled off is the one shape that throws.
+function setCompanionGatingAxis(i: number | null, axis: EstimateAxis, value: number | undefined) {
+  const gating = i === null ? undefined : pipelines.draftGating[i]
+  if (gating) gating[ESTIMATE_AXIS_FIELD[axis]] = value
+}
+function setConsensusGatingAxis(i: number, axis: EstimateAxis, value: number | undefined) {
+  const gating = pipelines.draftConsensus[i]?.gating
+  if (gating) gating[ESTIMATE_AXIS_FIELD[axis]] = value
+}
+function setTesterQualityGatingAxis(i: number, axis: EstimateAxis, value: number | undefined) {
+  const gating = pipelines.draftTesterQuality[i]?.gating
+  if (gating) gating[ESTIMATE_AXIS_FIELD[axis]] = value
+}
+
 /** Toggle gating on/off for a draft step's consensus config. */
 function toggleGating(i: number) {
   const cfg = pipelines.draftConsensus[i]
@@ -786,43 +813,15 @@ async function clone(p: Pipeline) {
                     @click="pipelines.toggleDraftGating(unit.companionIndex)"
                   />
                 </div>
-                <div
+                <EstimateThresholdFields
                   v-if="pipelines.draftGating[unit.companionIndex]?.enabled"
-                  class="flex flex-wrap items-center gap-2 border-t border-slate-800 pt-2"
-                >
-                  <span class="text-[10px] text-slate-500">{{
-                    t('pipeline.builder.runWhenAny')
-                  }}</span>
-                  <label class="text-slate-400">{{
-                    t('pipeline.builder.complexityThreshold')
-                  }}</label>
-                  <input
-                    v-model.number="pipelines.draftGating[unit.companionIndex]!.minComplexity"
-                    type="number"
-                    min="0"
-                    max="1"
-                    step="0.1"
-                    class="w-14 rounded border border-slate-700 bg-slate-900 px-1.5 py-0.5 text-slate-100"
-                  />
-                  <label class="text-slate-400">{{ t('pipeline.builder.riskThreshold') }}</label>
-                  <input
-                    v-model.number="pipelines.draftGating[unit.companionIndex]!.minRisk"
-                    type="number"
-                    min="0"
-                    max="1"
-                    step="0.1"
-                    class="w-14 rounded border border-slate-700 bg-slate-900 px-1.5 py-0.5 text-slate-100"
-                  />
-                  <label class="text-slate-400">{{ t('pipeline.builder.impactThreshold') }}</label>
-                  <input
-                    v-model.number="pipelines.draftGating[unit.companionIndex]!.minImpact"
-                    type="number"
-                    min="0"
-                    max="1"
-                    step="0.1"
-                    class="w-14 rounded border border-slate-700 bg-slate-900 px-1.5 py-0.5 text-slate-100"
-                  />
-                </div>
+                  :gating="pipelines.draftGating[unit.companionIndex]!"
+                  :axes="ESTIMATE_AXES"
+                  outcome="step"
+                  @update="
+                    (axis, value) => setCompanionGatingAxis(unit.companionIndex, axis, value)
+                  "
+                />
               </div>
 
               <!-- Consensus config (shown when the step is consensus-enabled). -->
@@ -953,31 +952,14 @@ async function clone(p: Pipeline) {
                       :title="t('pipeline.builder.consensusGateTooltip')"
                       @click="toggleGating(unit.index)"
                     />
-                    <template v-if="pipelines.draftConsensus[unit.index]!.gating?.enabled">
-                      <label class="text-slate-400">{{
-                        t('pipeline.builder.riskThreshold')
-                      }}</label>
-                      <input
-                        v-model.number="pipelines.draftConsensus[unit.index]!.gating!.minRisk"
-                        type="number"
-                        min="0"
-                        max="1"
-                        step="0.1"
-                        class="w-14 rounded border border-slate-700 bg-slate-900 px-1.5 py-0.5 text-slate-100"
-                      />
-                      <label class="text-slate-400">{{
-                        t('pipeline.builder.impactThreshold')
-                      }}</label>
-                      <input
-                        v-model.number="pipelines.draftConsensus[unit.index]!.gating!.minImpact"
-                        type="number"
-                        min="0"
-                        max="1"
-                        step="0.1"
-                        class="w-14 rounded border border-slate-700 bg-slate-900 px-1.5 py-0.5 text-slate-100"
-                      />
-                    </template>
                   </div>
+                  <EstimateThresholdFields
+                    v-if="pipelines.draftConsensus[unit.index]!.gating?.enabled"
+                    :gating="pipelines.draftConsensus[unit.index]!.gating!"
+                    :axes="CONSENSUS_ESTIMATE_AXES"
+                    outcome="consensus"
+                    @update="(axis, value) => setConsensusGatingAxis(unit.index, axis, value)"
+                  />
                 </template>
               </div>
 
@@ -1013,43 +995,13 @@ async function clone(p: Pipeline) {
                     @click="pipelines.toggleDraftTesterQualityGating(unit.index)"
                   />
                 </div>
-                <div
+                <EstimateThresholdFields
                   v-if="pipelines.draftTesterQuality[unit.index]?.gating?.enabled"
-                  class="flex flex-wrap items-center gap-2 border-t border-slate-800 pt-2"
-                >
-                  <span class="text-[10px] text-slate-500">{{
-                    t('pipeline.builder.runWhenAny')
-                  }}</span>
-                  <label class="text-slate-400">{{
-                    t('pipeline.builder.complexityThreshold')
-                  }}</label>
-                  <input
-                    v-model.number="pipelines.draftTesterQuality[unit.index]!.gating!.minComplexity"
-                    type="number"
-                    min="0"
-                    max="1"
-                    step="0.1"
-                    class="w-14 rounded border border-slate-700 bg-slate-900 px-1.5 py-0.5 text-slate-100"
-                  />
-                  <label class="text-slate-400">{{ t('pipeline.builder.riskThreshold') }}</label>
-                  <input
-                    v-model.number="pipelines.draftTesterQuality[unit.index]!.gating!.minRisk"
-                    type="number"
-                    min="0"
-                    max="1"
-                    step="0.1"
-                    class="w-14 rounded border border-slate-700 bg-slate-900 px-1.5 py-0.5 text-slate-100"
-                  />
-                  <label class="text-slate-400">{{ t('pipeline.builder.impactThreshold') }}</label>
-                  <input
-                    v-model.number="pipelines.draftTesterQuality[unit.index]!.gating!.minImpact"
-                    type="number"
-                    min="0"
-                    max="1"
-                    step="0.1"
-                    class="w-14 rounded border border-slate-700 bg-slate-900 px-1.5 py-0.5 text-slate-100"
-                  />
-                </div>
+                  :gating="pipelines.draftTesterQuality[unit.index]!.gating!"
+                  :axes="ESTIMATE_AXES"
+                  outcome="step"
+                  @update="(axis, value) => setTesterQualityGatingAxis(unit.index, axis, value)"
+                />
               </div>
             </li>
           </ol>

package/app/components/settings/ConsensusGroupsSection.vue

@@ -427,7 +427,10 @@ function fail(title: string, e: unknown) {
           {{ t('settings.consensusGroups.editor.gatedHint') }}
         </p>
         <div v-if="editor.gated" class="flex flex-wrap items-center gap-3 text-xs">
-          <label class="flex items-center gap-1.5 text-slate-400">
+          <label
+            class="flex items-center gap-1.5 text-slate-400"
+            :title="t('pipeline.builder.riskThresholdHint')"
+          >
             {{ t('pipeline.builder.riskThreshold') }}
             <UInput
               v-model.number="editor.minRisk"
@@ -439,7 +442,10 @@ function fail(title: string, e: unknown) {
               class="w-20"
             />
           </label>
-          <label class="flex items-center gap-1.5 text-slate-400">
+          <label
+            class="flex items-center gap-1.5 text-slate-400"
+            :title="t('pipeline.builder.impactThresholdHint')"
+          >
             {{ t('pipeline.builder.impactThreshold') }}
             <UInput
               v-model.number="editor.minImpact"
@@ -451,7 +457,10 @@ function fail(title: string, e: unknown) {
               class="w-20"
             />
           </label>
-          <label class="flex items-center gap-1.5 text-slate-400">
+          <label
+            class="flex items-center gap-1.5 text-slate-400"
+            :title="t('pipeline.builder.complexityThresholdHint')"
+          >
             {{ t('settings.consensusGroups.editor.complexityThreshold') }}
             <UInput
               v-model.number="editor.minComplexity"

package/app/utils/estimateGating.spec.ts

@@ -0,0 +1,44 @@
+import { describe, it, expect } from 'vitest'
+import {
+  ESTIMATE_AXES,
+  ESTIMATE_AXIS_FIELD,
+  ESTIMATE_AXIS_HINT_KEYS,
+  ESTIMATE_AXIS_LABEL_KEYS,
+  parseAxisThreshold,
+} from './estimateGating'
+
+describe('parseAxisThreshold', () => {
+  it('clears the axis on an empty or unparseable field rather than storing a zero floor', () => {
+    // The two are opposites: an unset axis is not considered, where a 0 floor always passes.
+    expect(parseAxisThreshold('')).toBeUndefined()
+    expect(parseAxisThreshold('   ')).toBeUndefined()
+    expect(parseAxisThreshold('abc')).toBeUndefined()
+    expect(parseAxisThreshold('0')).toBe(0)
+  })
+
+  it('keeps a value inside the estimator scale', () => {
+    expect(parseAxisThreshold('0.6')).toBe(0.6)
+    expect(parseAxisThreshold(' 0.25 ')).toBe(0.25)
+  })
+
+  it('clamps out-of-range input instead of rejecting it', () => {
+    // A fat-fingered extra digit lands on the ceiling rather than failing the save with a 422.
+    expect(parseAxisThreshold('10')).toBe(1)
+    expect(parseAxisThreshold('-3')).toBe(0)
+  })
+})
+
+describe('estimate axis vocabulary', () => {
+  it('covers every axis in both key maps and the field map', () => {
+    for (const axis of ESTIMATE_AXES) {
+      expect(ESTIMATE_AXIS_LABEL_KEYS[axis]).toBeTruthy()
+      expect(ESTIMATE_AXIS_HINT_KEYS[axis]).toBeTruthy()
+      expect(ESTIMATE_AXIS_FIELD[axis]).toBeTruthy()
+    }
+  })
+
+  it('gives each axis its own hint, so no two axes explain the same thing', () => {
+    const hints = ESTIMATE_AXES.map((axis) => ESTIMATE_AXIS_HINT_KEYS[axis])
+    expect(new Set(hints).size).toBe(ESTIMATE_AXES.length)
+  })
+})

package/app/utils/estimateGating.ts

@@ -0,0 +1,60 @@
+/**
+ * The three axes a `task-estimator` step scores a task on, and the presentation vocabulary every
+ * surface that lets a human gate work on them shares.
+ *
+ * Deliberately NOT `RISK_POLICY_AXES`: those are the axes a `merger` scores a finished pull
+ * request on, and although the three names coincide, the two are produced by different agents at
+ * different points in a run and mean different things to a reader. Folding them together would
+ * make a rename in one silently retitle the other.
+ */
+export const ESTIMATE_AXES = ['complexity', 'risk', 'impact'] as const
+
+export type EstimateAxis = (typeof ESTIMATE_AXES)[number]
+
+/**
+ * Axis → label key. Exhaustive over the union with LITERAL catalog keys, so the typed-message-key
+ * check sees them and a new axis fails the typecheck rather than rendering a raw key.
+ */
+export const ESTIMATE_AXIS_LABEL_KEYS: Record<EstimateAxis, string> = {
+  complexity: 'pipeline.builder.complexityThreshold',
+  risk: 'pipeline.builder.riskThreshold',
+  impact: 'pipeline.builder.impactThreshold',
+}
+
+/**
+ * Axis → the `StepGating`/`ConsensusGating` field carrying its floor. Both schemas spell the
+ * three the same way, which is what lets one editor serve every gate in the builder.
+ */
+export const ESTIMATE_AXIS_FIELD: Record<EstimateAxis, 'minComplexity' | 'minRisk' | 'minImpact'> =
+  {
+    complexity: 'minComplexity',
+    risk: 'minRisk',
+    impact: 'minImpact',
+  }
+
+/** Axis → the tooltip explaining what the axis measures and on what scale. Same discipline. */
+export const ESTIMATE_AXIS_HINT_KEYS: Record<EstimateAxis, string> = {
+  complexity: 'pipeline.builder.complexityThresholdHint',
+  risk: 'pipeline.builder.riskThresholdHint',
+  impact: 'pipeline.builder.impactThresholdHint',
+}
+
+/**
+ * Read one axis threshold field back into a stored floor.
+ *
+ * An emptied or unparseable field CLEARS the axis rather than storing `0`, which is the whole
+ * reason this is a function: the two are opposites. An unset axis is not considered at all,
+ * where a floor of `0` is cleared by every estimate there is — so a user who deletes the number
+ * to stop gating on risk would, under a `?? 0`, have gated on it permanently instead.
+ *
+ * The scale is the estimator's 0..1, and a value outside it is CLAMPED rather than rejected, so
+ * a fat-fingered `10` lands on the ceiling instead of silently failing the pipeline save with a
+ * 422 from the contract's score bounds.
+ */
+export function parseAxisThreshold(raw: string): number | undefined {
+  const trimmed = raw.trim()
+  if (trimmed === '') return undefined
+  const parsed = Number.parseFloat(trimmed)
+  if (!Number.isFinite(parsed)) return undefined
+  return Math.min(1, Math.max(0, parsed))
+}