@cat-factory/app 0.109.2 → 0.109.3

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

@@ -76,6 +76,7 @@ function onHandle(e: PointerEvent) {
     </div>
     <div
       data-testid="initiative-card"
+      :data-status="status"
       class="cursor-pointer rounded-b-lg border border-indigo-800/60 bg-indigo-950/40 p-3 transition hover:border-indigo-600"
       :class="[selected ? 'ring-2 ring-indigo-400/60' : '', awaitingAnswers ? 'board-pulse' : '']"
       @click.stop="select"

package/app/components/initiative/InitiativeTrackerWindow.vue

@@ -16,6 +16,7 @@ import {
   INITIATIVE_ITEM_STATUS_LABEL_KEYS,
   INITIATIVE_STATUS_LABEL_KEYS,
   initiativeProgress,
+  pendingCheckpointPhase,
 } from '~/utils/initiative'
 
 const board = useBoardStore()
@@ -42,6 +43,33 @@ const progressPct = computed(() =>
     : 0,
 )
 
+// Phase checkpoints (D2): the phase whose completed checkpoint is awaiting review (recomputed
+// live from the entity — mirrors the loop's `pendingCheckpoint`), and whether the initiative is
+// currently PAUSED at it. The tracker is the review surface: it shows the phase's committed
+// artifacts + PRs, so a resume/cancel decision is taken right here.
+const checkpointPhase = computed(() =>
+  pendingCheckpointPhase(initiative.value?.phases, initiative.value?.items),
+)
+const pausedAtCheckpoint = computed(
+  () => initiative.value?.status === 'paused' && checkpointPhase.value !== null,
+)
+// The phase whose checkpoint is genuinely holding the initiative RIGHT NOW (paused for review) —
+// only then does its badge read "awaiting review". A phase whose items just settled but whose
+// pause hasn't landed yet stays an upcoming checkpoint, so the badge can't get ahead of the banner.
+const awaitingReviewPhaseId = computed(() =>
+  pausedAtCheckpoint.value ? (checkpointPhase.value?.id ?? null) : null,
+)
+
+/** Resume (GO) or cancel (NO_GO) an initiative paused at a checkpoint. */
+async function checkpointControl(action: 'resume' | 'cancel') {
+  if (!blockId.value) return
+  try {
+    await initiatives.control(blockId.value, action)
+  } catch (error) {
+    reportError(error)
+  }
+}
+
 const policyRules = computed(() => initiative.value?.policy?.rules ?? [])
 function ruleAxes(rule: { minComplexity?: number; minRisk?: number; minImpact?: number }): string {
   const axes = [
@@ -205,6 +233,48 @@ async function savePolicy() {
           </div>
 
           <template v-else>
+            <!-- Paused at a phase checkpoint (D2): a completed checkpoint phase is awaiting
+                 review before the next phase spawns. Read the phase's artifacts/PRs below,
+                 then resume (continue) or cancel (stop) the initiative right here. -->
+            <section
+              v-if="pausedAtCheckpoint"
+              class="mb-4 rounded-lg border border-amber-500/40 bg-amber-500/10 p-3.5"
+              data-testid="initiative-checkpoint-pause"
+            >
+              <div class="flex items-start gap-2.5">
+                <UIcon
+                  name="i-lucide-pause-circle"
+                  class="mt-0.5 h-4 w-4 shrink-0 text-amber-300"
+                />
+                <div class="min-w-0 flex-1">
+                  <h3 class="text-[13px] font-semibold text-amber-200">
+                    {{ t('initiative.checkpoint.pausedTitle') }}
+                  </h3>
+                  <p class="mt-0.5 text-[12px] leading-relaxed text-amber-100/80">
+                    {{ t('initiative.checkpoint.pausedBody', { phase: checkpointPhase!.title }) }}
+                  </p>
+                  <div class="mt-2.5 flex flex-wrap gap-2">
+                    <button
+                      class="rounded bg-indigo-600 px-2.5 py-1 text-[11px] font-medium text-white hover:bg-indigo-500 disabled:opacity-50"
+                      :disabled="initiatives.controlling"
+                      data-testid="initiative-checkpoint-resume"
+                      @click="checkpointControl('resume')"
+                    >
+                      {{ t('initiative.inspector.resume') }}
+                    </button>
+                    <button
+                      class="rounded border border-rose-500/50 px-2.5 py-1 text-[11px] font-medium text-rose-300 hover:bg-rose-500/10 disabled:opacity-50"
+                      :disabled="initiatives.controlling"
+                      data-testid="initiative-checkpoint-cancel"
+                      @click="checkpointControl('cancel')"
+                    >
+                      {{ t('initiative.inspector.cancel') }}
+                    </button>
+                  </div>
+                </div>
+              </div>
+            </section>
+
             <!-- Goal & constraints -->
             <section v-if="initiative.goal" class="mb-4">
               <h3 class="mb-1 text-[11px] font-semibold uppercase tracking-wide text-slate-500">
@@ -249,8 +319,33 @@ async function savePolicy() {
 
             <!-- Phases + items -->
             <section v-for="phase in phases" :key="phase.id" class="mb-5">
-              <h3 class="mb-1 text-sm font-semibold text-slate-200">
-                {{ t('initiative.tracker.phase', { title: phase.title }) }}
+              <h3 class="mb-1 flex items-center gap-2 text-sm font-semibold text-slate-200">
+                <span>{{ t('initiative.tracker.phase', { title: phase.title }) }}</span>
+                <!-- Checkpoint annotation (D2): this phase pauses the initiative for human review
+                     once its items settle. Cleared → already reviewed; the pending one → awaiting
+                     review; otherwise an upcoming gate. -->
+                <UBadge
+                  v-if="phase.checkpoint"
+                  :color="
+                    phase.checkpointClearedAt
+                      ? 'neutral'
+                      : awaitingReviewPhaseId === phase.id
+                        ? 'warning'
+                        : 'info'
+                  "
+                  variant="subtle"
+                  size="sm"
+                  :data-testid="`initiative-phase-checkpoint-${phase.id}`"
+                >
+                  <UIcon name="i-lucide-flag" class="mr-1 h-3 w-3" />
+                  {{
+                    phase.checkpointClearedAt
+                      ? t('initiative.checkpoint.cleared')
+                      : awaitingReviewPhaseId === phase.id
+                        ? t('initiative.checkpoint.awaiting')
+                        : t('initiative.checkpoint.badge')
+                  }}
+                </UBadge>
               </h3>
               <p v-if="phase.goal" class="mb-2 text-[12px] text-slate-400">{{ phase.goal }}</p>
               <div class="overflow-x-auto rounded-lg border border-slate-800">

package/app/utils/initiative.spec.ts

@@ -0,0 +1,73 @@
+import { INITIATIVE_ITEM_TERMINAL_STATUSES } from '@cat-factory/contracts'
+import { describe, it, expect } from 'vitest'
+import type { InitiativeItem, InitiativePhase } from '~/types/domain'
+import { pendingCheckpointPhase } from './initiative'
+
+// `pendingCheckpointPhase` mirrors the backend `pendingCheckpoint` (orchestration
+// `initiative.logic.ts`); these pin the same ordering/edge cases the loop pauses on, so the
+// tracker window's live banner + phase badges can't drift from the engine's decision.
+
+const phase = (over: Partial<InitiativePhase> & { id: string }): InitiativePhase => ({
+  title: over.id,
+  goal: '',
+  ...over,
+})
+
+const item = (id: string, phaseId: string, status: InitiativeItem['status']): InitiativeItem => ({
+  id,
+  phaseId,
+  title: id,
+  description: '',
+  dependsOn: [],
+  status,
+})
+
+describe('pendingCheckpointPhase', () => {
+  it('returns null when no phase is flagged checkpoint', () => {
+    const phases = [phase({ id: 'p1' })]
+    const items = [item('a', 'p1', 'done')]
+    expect(pendingCheckpointPhase(phases, items)).toBeNull()
+  })
+
+  it('returns a checkpoint phase once all its items settle (done/skipped)', () => {
+    const phases = [phase({ id: 'p1', checkpoint: true })]
+    const items = [item('a', 'p1', 'done'), item('b', 'p1', 'skipped')]
+    expect(pendingCheckpointPhase(phases, items)?.id).toBe('p1')
+  })
+
+  it('does not fire while a checkpoint phase still holds a non-terminal item', () => {
+    const phases = [phase({ id: 'p1', checkpoint: true })]
+    expect(pendingCheckpointPhase(phases, [item('a', 'p1', 'in_progress')])).toBeNull()
+    // A BLOCKED item (a halted phase) is non-terminal too, so the checkpoint waits.
+    expect(pendingCheckpointPhase(phases, [item('a', 'p1', 'blocked')])).toBeNull()
+  })
+
+  it('never re-fires a cleared checkpoint', () => {
+    const phases = [phase({ id: 'p1', checkpoint: true, checkpointClearedAt: 123 })]
+    expect(pendingCheckpointPhase(phases, [item('a', 'p1', 'done')])).toBeNull()
+  })
+
+  it('skips an item-less checkpoint phase (nothing to review)', () => {
+    const phases = [phase({ id: 'p1', checkpoint: true })]
+    expect(pendingCheckpointPhase(phases, [])).toBeNull()
+  })
+
+  it('returns the FIRST uncleared, completed checkpoint phase in declared order', () => {
+    const phases = [
+      phase({ id: 'p1', checkpoint: true, checkpointClearedAt: 1 }),
+      phase({ id: 'p2', checkpoint: true }),
+      phase({ id: 'p3', checkpoint: true }),
+    ]
+    const items = [item('a', 'p1', 'done'), item('b', 'p2', 'done'), item('c', 'p3', 'done')]
+    // p1 already cleared → p2 is the pending one (even though p3 is also complete + uncleared).
+    expect(pendingCheckpointPhase(phases, items)?.id).toBe('p2')
+  })
+
+  // Drift guard: the checkpoint fires on EVERY status the backend counts as terminal, because the
+  // frontend gates on the SAME `INITIATIVE_ITEM_TERMINAL_STATUSES` the engine does — not a local
+  // copy. If the backend adds a terminal status, this fires the checkpoint on it automatically.
+  it.each([...INITIATIVE_ITEM_TERMINAL_STATUSES])('fires on the terminal status %s', (status) => {
+    const phases = [phase({ id: 'p1', checkpoint: true })]
+    expect(pendingCheckpointPhase(phases, [item('a', 'p1', status)])?.id).toBe('p1')
+  })
+})

package/app/utils/initiative.ts

@@ -1,7 +1,9 @@
+import { INITIATIVE_ITEM_TERMINAL_STATUSES } from '@cat-factory/contracts'
 import type {
   InitiativeFollowUp,
   InitiativeItem,
   InitiativeItemStatus,
+  InitiativePhase,
   InitiativePresetDescriptor,
   InitiativePresetInputs,
   InitiativeStatus,
@@ -98,13 +100,37 @@ export function defaultPresetInputs(
   return inputs
 }
 
-/** Item statuses that count as settled — mirrors the backend terminal-status set. */
-const SETTLED: ReadonlySet<InitiativeItemStatus> = new Set(['done', 'skipped'])
-
 /** Completion rollup across an initiative's items, or null when there are none. */
 export function initiativeProgress(
   items: InitiativeItem[] | undefined,
 ): { settled: number; total: number } | null {
   if (!items || items.length === 0) return null
-  return { settled: items.filter((i) => SETTLED.has(i.status)).length, total: items.length }
+  return {
+    settled: items.filter((i) => INITIATIVE_ITEM_TERMINAL_STATUSES.has(i.status)).length,
+    total: items.length,
+  }
+}
+
+/**
+ * The phase whose completed checkpoint (D2) is awaiting a human, or null. Mirrors the backend
+ * `pendingCheckpoint` (orchestration `initiative.logic.ts`) so the SPA recomputes the pending
+ * checkpoint from the live entity — the same shape the loop pauses on — rather than reading a
+ * derived flag off the wire: the FIRST phase, in declared order, flagged `checkpoint`, NOT yet
+ * cleared (`checkpointClearedAt`), holding at least one item, with every item terminal. Uses the
+ * canonical `INITIATIVE_ITEM_TERMINAL_STATUSES` (the SAME set the backend gates on) so the
+ * terminal-status membership cannot drift from the engine, not just the ordering. An open tracker
+ * window then follows the checkpoint as items settle without a reload.
+ */
+export function pendingCheckpointPhase(
+  phases: InitiativePhase[] | undefined,
+  items: InitiativeItem[] | undefined,
+): InitiativePhase | null {
+  const all = items ?? []
+  for (const phase of phases ?? []) {
+    if (phase.checkpoint !== true || phase.checkpointClearedAt !== undefined) continue
+    const phaseItems = all.filter((i) => i.phaseId === phase.id)
+    if (phaseItems.length === 0) continue
+    if (phaseItems.every((i) => INITIATIVE_ITEM_TERMINAL_STATUSES.has(i.status))) return phase
+  }
+  return null
 }

package/i18n/locales/de.json

@@ -3547,6 +3547,13 @@
       "maxConcurrentField": "Max. gleichzeitige Aufgaben",
       "defaultPipelineField": "Standard-Pipeline",
       "failed": "Die Initiative konnte nicht aktualisiert werden"
+    },
+    "checkpoint": {
+      "badge": "Checkpoint",
+      "awaiting": "Warten auf Prüfung",
+      "cleared": "Geprüft",
+      "pausedTitle": "Pausiert zur Prüfung",
+      "pausedBody": "Phase „{phase}\" ist abgeschlossen. Prüfe oben die committeten Artefakte und PRs, setze dann fort, um weiterzumachen, oder brich die Initiative ab."
     }
   },
   "app": {

package/i18n/locales/en.json

@@ -4522,6 +4522,13 @@
       "maxConcurrentField": "Max concurrent tasks",
       "defaultPipelineField": "Default pipeline",
       "failed": "Could not update the initiative"
+    },
+    "checkpoint": {
+      "badge": "Checkpoint",
+      "awaiting": "Awaiting review",
+      "cleared": "Reviewed",
+      "pausedTitle": "Paused for review",
+      "pausedBody": "Phase \"{phase}\" is complete. Review its committed artifacts and PRs above, then resume to continue or cancel to stop the initiative."
     }
   },
   "environmentWizard": {

package/i18n/locales/es.json

@@ -4393,6 +4393,13 @@
       "maxConcurrentField": "Tareas concurrentes maximas",
       "defaultPipelineField": "Pipeline por defecto",
       "failed": "No se pudo actualizar la iniciativa"
+    },
+    "checkpoint": {
+      "badge": "Punto de control",
+      "awaiting": "Pendiente de revisión",
+      "cleared": "Revisado",
+      "pausedTitle": "En pausa para revisión",
+      "pausedBody": "La fase «{phase}» está completa. Revisa arriba los artefactos y las PR confirmados y luego reanuda para continuar o cancela para detener la iniciativa."
     }
   },
   "environmentWizard": {

package/i18n/locales/fr.json

@@ -4393,6 +4393,13 @@
       "maxConcurrentField": "Taches simultanees maximales",
       "defaultPipelineField": "Pipeline par defaut",
       "failed": "Impossible de mettre a jour l'initiative"
+    },
+    "checkpoint": {
+      "badge": "Point de contrôle",
+      "awaiting": "En attente de revue",
+      "cleared": "Revu",
+      "pausedTitle": "En pause pour revue",
+      "pausedBody": "La phase « {phase} » est terminée. Examinez ci-dessus les artefacts et les PR validés, puis reprenez pour continuer ou annulez pour arrêter l'initiative."
     }
   },
   "environmentWizard": {

package/i18n/locales/he.json

@@ -4404,6 +4404,13 @@
       "maxConcurrentField": "מקסימום משימות במקביל",
       "defaultPipelineField": "צינור ברירת מחדל",
       "failed": "לא ניתן לעדכן את היוזמה"
+    },
+    "checkpoint": {
+      "badge": "נקודת ביקורת",
+      "awaiting": "ממתין לבדיקה",
+      "cleared": "נבדק",
+      "pausedTitle": "מושהה לבדיקה",
+      "pausedBody": "השלב \"{phase}\" הושלם. בדקו למעלה את הפריטים וה-PR שנשמרו, ואז חדשו כדי להמשיך או בטלו כדי לעצור את היוזמה."
     }
   },
   "environmentWizard": {

package/i18n/locales/it.json

@@ -3547,6 +3547,13 @@
       "maxConcurrentField": "Massimo di attivita concorrenti",
       "defaultPipelineField": "Pipeline predefinita",
       "failed": "Impossibile aggiornare l'iniziativa"
+    },
+    "checkpoint": {
+      "badge": "Checkpoint",
+      "awaiting": "In attesa di revisione",
+      "cleared": "Revisionato",
+      "pausedTitle": "In pausa per la revisione",
+      "pausedBody": "La fase «{phase}» è completa. Rivedi sopra gli artefatti e le PR salvati, poi riprendi per continuare o annulla per interrompere l'iniziativa."
     }
   },
   "app": {

package/i18n/locales/ja.json

@@ -4405,6 +4405,13 @@
       "maxConcurrentField": "最大同時実行タスク数",
       "defaultPipelineField": "既定のパイプライン",
       "failed": "イニシアチブを更新できませんでした"
+    },
+    "checkpoint": {
+      "badge": "チェックポイント",
+      "awaiting": "レビュー待ち",
+      "cleared": "レビュー済み",
+      "pausedTitle": "レビューのため一時停止",
+      "pausedBody": "フェーズ「{phase}」が完了しました。上記のコミット済み成果物と PR を確認し、続行する場合は再開、中止する場合はイニシアチブをキャンセルしてください。"
     }
   },
   "environmentWizard": {

package/i18n/locales/pl.json

@@ -4393,6 +4393,13 @@
       "maxConcurrentField": "Maks. rownoczesnych zadan",
       "defaultPipelineField": "Domyslny pipeline",
       "failed": "Nie udalo sie zaktualizowac inicjatywy"
+    },
+    "checkpoint": {
+      "badge": "Punkt kontrolny",
+      "awaiting": "Oczekuje na przegląd",
+      "cleared": "Sprawdzono",
+      "pausedTitle": "Wstrzymano do przeglądu",
+      "pausedBody": "Faza „{phase}\" została ukończona. Przejrzyj powyżej zatwierdzone artefakty i PR-y, a następnie wznów, aby kontynuować, albo anuluj, aby zatrzymać inicjatywę."
     }
   },
   "environmentWizard": {

package/i18n/locales/tr.json

@@ -4405,6 +4405,13 @@
       "maxConcurrentField": "Maks. es zamanli gorev",
       "defaultPipelineField": "Varsayilan pipeline",
       "failed": "Girisim guncellenemedi"
+    },
+    "checkpoint": {
+      "badge": "Kontrol noktası",
+      "awaiting": "İnceleme bekliyor",
+      "cleared": "İncelendi",
+      "pausedTitle": "İnceleme için duraklatıldı",
+      "pausedBody": "\"{phase}\" aşaması tamamlandı. Yukarıdaki işlenmiş yapıtları ve PR'leri inceleyin, ardından devam etmek için sürdürün ya da girişimi durdurmak için iptal edin."
     }
   },
   "environmentWizard": {

package/i18n/locales/uk.json

@@ -4393,6 +4393,13 @@
       "maxConcurrentField": "Макс. одночасних завдань",
       "defaultPipelineField": "Типовий конвеєр",
       "failed": "Не вдалося оновити ініціативу"
+    },
+    "checkpoint": {
+      "badge": "Контрольна точка",
+      "awaiting": "Очікує на перегляд",
+      "cleared": "Переглянуто",
+      "pausedTitle": "Призупинено для перегляду",
+      "pausedBody": "Фазу «{phase}» завершено. Перегляньте вище закомічені артефакти та PR, потім відновіть, щоб продовжити, або скасуйте, щоб зупинити ініціативу."
     }
   },
   "environmentWizard": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cat-factory/app",
-  "version": "0.109.2",
+  "version": "0.109.3",
   "description": "Reusable Nuxt layer for the Agent Architecture Board SPA (components, stores, composables, pages). Consume it from a thin deployment app via `extends: ['@cat-factory/app']` and point it at your backend with NUXT_PUBLIC_API_BASE. See deploy/frontend for an example.",
   "repository": {
     "type": "git",