@cat-factory/app 0.197.0 → 0.198.0

package/README.md

@@ -55,6 +55,27 @@ over the WebSocket. How that sync works is written up in
 | `types/`          | TypeScript domain unions (`domain.ts`) and wire types mirroring the contracts.                                                                        |
 | `utils/`          | Small pure helpers.                                                                                                                                   |
 
+### A store must be instantiable outside a component `setup`
+
+A Pinia setup store runs its body on the FIRST `useStore()` anywhere in the app, and that
+caller is not always a component: `plugins/modular.client.ts` builds the nav gates
+(`createNavGates`) during plugin setup, which instantiates a handful of stores before any
+component exists. So nothing a store reaches for at setup time may require an active
+component instance.
+
+The one that bites is **`useI18n()`, which throws `MUST_BE_CALL_SETUP_TOP` outside a
+component** — and because it happens inside a plugin, Nuxt's error boundary replaces the
+whole app with its 500 page rather than surfacing a broken feature. Resolve translations
+through the Nuxt app's global i18n instance instead (`useNuxtApp().$i18n`, typed as
+`ReturnType<typeof useI18n>`), as `stores/board.ts`, `stores/recurringPipelines.ts` and
+`composables/usePipelineErrorToast.ts` do. This costs no typed-message-key coverage: tier 1
+only sees literal keys written in a `<script setup>`, never in a `.ts` store or composable.
+
+The blast radius is why this is a rule rather than a preference — a store reached one call
+earlier than before takes the entire SPA down at boot, and the unit suite cannot see it
+(nothing there installs the plugin). Every e2e spec does, because every one of them boots
+the app.
+
 ### 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.
@@ -184,13 +205,58 @@ congratulating the user on a walkthrough they did not see — and a tour that co
 be abridged should not be offered at all, which is what each tour's `when(gates)` is for (the
 task-creation tour requires board write AND a service frame to add a task to).
 
+**A step carries its own `when(gates)` when its BRANCH, not its control, is the thing that
+may not apply.** The two are different facts and only one of them is a defect: a skip means
+the control should be here and isn't, while a `when` means this board is not on that branch
+of the flow (a run parked on a decision has no approval gate, and the reverse). Reporting the
+second as an abridged tour would tell a user who saw exactly the right walkthrough that they
+missed half of it, every time. `resolveTours` (in `utils/tutorial.ts`, applied by
+`navSlotFilter`) drops the rejected steps and then drops a tour left with none, so a tour
+whose every step is branch-specific can never open on an empty cursor. With no gates service
+wired at all (a bare install withholds nothing) every branch survives instead, and only one
+of them can anchor — so the abridged notice ignores any skipped step that carries a `when`,
+which has already declared that not applying is legitimate.
+
+**Gates decide what is OFFERED; the running tour's script is resolved once and HELD.** The
+overlay snapshots its tour when it starts rather than re-reading the gated slot on every
+flip. This is not an optimisation: gates over live run state flip as a direct result of
+following the tour — `answer-park` is offered while something waits for a human, so the
+moment the user answers, its `when` goes false. A re-reading overlay tore itself down there,
+one step short of its own finish card and with nothing recorded as completed, at exactly the
+moment the user succeeded. Holding the script also freezes the branch `resolveTours` chose,
+so a step can't be swapped underneath a stationary cursor.
+
+**Gates must mean what the board RENDERS, not what the store holds.** `boardHasOpenDecision`
+/ `boardHasPendingApproval` are not the store's raw pending counts: a park on a frame block
+has no task card, and a reviewer gate mid-cycle is deliberately suppressed by the card
+(`useReviewStage().isBackground`), so either would offer a tour onto a control that isn't
+there. `hasActionablePark` (`modular/nav-gates.logic.ts`) is the shared rule; the run gates
+are task-scoped for the same reason.
+
+**Fixed proper nouns ride `bodyParams`, not the catalogs.** A step naming the sample
+repository slug (`SAMPLE_REPO` in `modular/tutorial-tours.ts`) passes it as a `{repo}`
+interpolation, so it is written once in code rather than translated into ten catalogs that
+each drift on their own — the same split components make for inline placeholders.
+
+The built-ins walk the delivery loop end to end, each gated on the state the previous one
+leaves behind, so the launch prompt only ever offers what this board can demonstrate: board
+basics, add a repository (`add-service`), create a task (`first-task`), run it (`run-task`),
+answer it when it parks (`answer-park`), review and merge the result (`review-merge`). One
+deliberate asymmetry: `run-task` points at Start without click-to-advance, because starting a
+run spends real model budget and nobody should discover they agreed to that by following a
+tutorial.
+
 Two runtime constraints worth knowing before changing the overlay: it must keep
 `pointer-events-auto` and swallow `pointerdown`, because Nuxt UI modals are reka-ui
 dismissable layers that set `body { pointer-events: none }` and dismiss on an outside
 pointerdown — without both, the tooltip's own buttons go inert and pressing one closes the
 user's half-filled form. And everything that DECIDES (skip direction, wait budget,
-target-click matching) lives in `components/tutorial/TutorialOverlay.logic.ts` so it is
-unit-tested; the SFC keeps only the DOM work.
+target-click matching, which skips count as abridged) lives in
+`components/tutorial/TutorialOverlay.logic.ts` so it is unit-tested; the SFC keeps only the
+DOM work. Note that target-click matching is by SELECTOR, not by the highlighted element:
+several anchors (`task-card`, `task-resolve`, `run-step`) render once per board item and the
+ring can only sit on one of them, so requiring the click to land on that one left a user who
+clicked the card the copy asked for with no way forward — such a step renders no Next.
 
 The catalog is the `tutorialTours` slot: first-party tours live in
 `modular/tutorial-tours.ts`, and a consumer deployment contributes its own through

package/app/components/github/AddServiceFromRepoModal.vue

@@ -380,7 +380,11 @@ function done() {
             :description="t('github.addService.repositoryHint')"
             required
           >
-            <div class="space-y-1.5">
+            <!-- The wrapper, not the UInputMenu itself, carries the anchor: a tutorial tour
+                 stop needs an element that is present the moment the modal mounts, and it
+                 highlights the whole field rather than whichever inner node Nuxt UI happens
+                 to forward the attribute to. -->
+            <div class="space-y-1.5" data-testid="add-service-repo-search">
               <UInputMenu
                 v-model="selectedRepoId"
                 v-model:search-term="repoSearch"
@@ -553,6 +557,7 @@ function done() {
               icon="i-lucide-plus"
               :loading="adding"
               :disabled="!canAdd"
+              data-testid="add-service-submit"
               @click="add"
             >
               {{ t('github.addService.add') }}

package/app/components/tutorial/TutorialOverlay.logic.spec.ts

@@ -5,7 +5,7 @@ import {
   resolveSkip,
   stepTargetIds,
   stepTargetSelectors,
-  tourWasAbridged,
+  unexpectedlySkippedSteps,
   waitBudgetMs,
 } from '~/components/tutorial/TutorialOverlay.logic'
 import { DEFAULT_TARGET_WAIT_MS } from '~/utils/tutorial'
@@ -99,28 +99,66 @@ describe('resolveSkip', () => {
 })
 
 describe('isTargetClickAdvance', () => {
-  const el = document.createElement('button')
-  const child = document.createElement('span')
-  el.appendChild(child)
-
-  it('advances on a real click on the highlighted control, or inside it', () => {
+  /** A control carrying `id`, with a nested span, mounted so `closest` can walk to it. */
+  const control = (id: string) => {
+    const el = document.createElement('button')
+    el.setAttribute('data-testid', id)
+    el.appendChild(document.createElement('span'))
+    document.body.appendChild(el)
+    return el
+  }
+
+  it('advances on a real click on the control, or inside it', () => {
+    const el = control('add-task-submit')
     const s = step({ target: 'add-task-submit', advanceOn: 'target-click' })
-    expect(isTargetClickAdvance(s, el, el)).toBe(true)
-    expect(isTargetClickAdvance(s, el, child)).toBe(true)
+    expect(isTargetClickAdvance(s, el)).toBe(true)
+    expect(isTargetClickAdvance(s, el.firstChild)).toBe(true)
+  })
+
+  it('advances on ANY instance of a control the board renders per item', () => {
+    // `task-card` / `task-resolve` / `run-step` exist once per board item, and the ring can
+    // only sit on one of them. Requiring the click to land on THAT one left a user who
+    // clicked the card the step's copy asked for with no way forward — a click-to-advance
+    // step renders no Next button.
+    control('task-card')
+    const second = control('task-card')
+    const s = step({ target: 'task-card', advanceOn: 'target-click' })
+    expect(isTargetClickAdvance(s, second)).toBe(true)
+  })
+
+  it('advances on a fallback anchor too, since either is the control the step named', () => {
+    const s = step({ target: 'ui-mode-switcher', altTargets: ['ui-mode-toggle'] })
+    expect(
+      isTargetClickAdvance({ ...s, advanceOn: 'target-click' }, control('ui-mode-toggle')),
+    ).toBe(true)
   })
 
-  it('ignores clicks elsewhere, on a Next-advanced step, or with no anchor', () => {
+  it('ignores clicks elsewhere, on a Next-advanced step, or on a non-element', () => {
     const s = step({ target: 'add-task-submit', advanceOn: 'target-click' })
-    expect(isTargetClickAdvance(s, el, document.createElement('div'))).toBe(false)
-    expect(isTargetClickAdvance(s, null, el)).toBe(false)
-    expect(isTargetClickAdvance(step({ target: 'x' }), el, el)).toBe(false)
-    expect(isTargetClickAdvance(null, el, el)).toBe(false)
+    expect(isTargetClickAdvance(s, control('run-start'))).toBe(false)
+    expect(isTargetClickAdvance(s, null)).toBe(false)
+    expect(isTargetClickAdvance(s, document.createTextNode('stray'))).toBe(false)
+    expect(isTargetClickAdvance(step({ target: 'add-task-submit' }), control('x'))).toBe(false)
+    expect(isTargetClickAdvance(null, control('y'))).toBe(false)
   })
 })
 
-describe('tourWasAbridged', () => {
-  it('is true once any step was skipped, so the finish card can say so', () => {
-    expect(tourWasAbridged(new Set())).toBe(false)
-    expect(tourWasAbridged(new Set(['addTask']))).toBe(true)
+describe('unexpectedlySkippedSteps', () => {
+  const plain = step({ id: 'addTask', target: 'frame-add-task' })
+  const branch = step({ id: 'approve', target: 'step-approve', when: () => true })
+
+  it('counts a skipped step whose control simply was not there', () => {
+    expect(unexpectedlySkippedSteps(new Set(['addTask']), [plain, branch])).toEqual([plain])
+  })
+
+  it('does not count a branch-gated step, whose absence it already declared legitimate', () => {
+    // The gates-absent case (a bare install withholds nothing, so BOTH branches of a tour
+    // are kept and only one can ever anchor). Reporting that as abridged would put a
+    // permanent "you missed some of this" on a tour that showed exactly the right branch.
+    expect(unexpectedlySkippedSteps(new Set(['approve']), [plain, branch])).toEqual([])
+  })
+
+  it('is empty for a tour that skipped nothing', () => {
+    expect(unexpectedlySkippedSteps(new Set(), [plain, branch])).toEqual([])
   })
 })

package/app/components/tutorial/TutorialOverlay.logic.ts

@@ -71,22 +71,55 @@ export function resolveSkip(
   return index + 1 < total ? { kind: 'move', index: index + 1 } : { kind: 'complete' }
 }
 
-/** Does this real click count as the "now click this" step's advance? */
+/** The part of a clicked node this check needs: CSS-selector ancestry. */
+interface ClickedNode {
+  closest(selector: string): unknown
+}
+
+/** The clicked node as something we can ask about ancestry, or null (a text node, `document`). */
+function asClickedNode(eventTarget: EventTarget | null): ClickedNode | null {
+  const node = eventTarget as ClickedNode | null
+  return node && typeof node.closest === 'function' ? node : null
+}
+
+/**
+ * Does this real click count as the "now click this" step's advance?
+ *
+ * Matched against the step's SELECTORS rather than against the one element the tracker
+ * happened to highlight, because several of the controls a tour points at are rendered once
+ * PER BOARD ITEM: `task-card`, `task-resolve`, `run-step`. The tracker anchors its ring to
+ * the first match in the DOM, which is not necessarily the card the step's own copy is
+ * asking for ("open a task whose run has finished"). Requiring the click to land inside THAT
+ * element meant a user who clicked the right card got no advance at all — and a
+ * click-to-advance step renders no Next button, so the tour had no way forward but Skip.
+ * Any instance of the control the step names is the action the step asked for.
+ */
 export function isTargetClickAdvance(
   step: TutorialStep | null,
-  targetEl: { contains: (node: Node) => boolean } | null,
   eventTarget: EventTarget | null,
 ): boolean {
-  if (!step || step.advanceOn !== 'target-click' || !targetEl) return false
-  return eventTarget instanceof Node && targetEl.contains(eventTarget)
+  if (!step || step.advanceOn !== 'target-click') return false
+  const node = asClickedNode(eventTarget)
+  if (!node) return false
+  return stepTargetSelectors(step).some((selector) => node.closest(selector) != null)
 }
 
 /**
- * A tour is ABRIDGED when it reached its end having skipped steps: the controls those
- * steps point at aren't part of this board/role/deployment. The final card says so
- * instead of congratulating the user on a walkthrough they never saw — absent and
- * complete must not render the same.
+ * The skipped steps whose absence is a DEFECT — which is what the final card's "abridged"
+ * notice is about: the controls those steps point at aren't part of this board/role/
+ * deployment, so saying nothing would congratulate the user on a walkthrough they never saw.
+ *
+ * A step carrying a `when` is excluded, because it has already declared that not applying is
+ * a legitimate state rather than a missing control. Normally such a step is DROPPED before
+ * the tour runs (see `resolveTours`), so it never reaches the skip path at all — but with no
+ * gates service wired (a bare install, where nothing is withheld) every branch of a tour is
+ * kept, and exactly one of them can ever anchor. Counting the other as abridged would put a
+ * permanent "you missed some of this" on a tour that showed the user precisely the branch
+ * their board is on.
  */
-export function tourWasAbridged(skippedStepIds: ReadonlySet<string>): boolean {
-  return skippedStepIds.size > 0
+export function unexpectedlySkippedSteps(
+  skippedStepIds: ReadonlySet<string>,
+  steps: readonly TutorialStep[],
+): TutorialStep[] {
+  return steps.filter((s) => skippedStepIds.has(s.id) && s.when === undefined)
 }

package/app/components/tutorial/TutorialOverlay.vue

@@ -4,12 +4,12 @@ import {
   DEFAULT_TARGET_WAIT_MS,
   TARGET_TRACK_INTERVAL_MS,
 } from '~/utils/tutorial'
-import type { CoachMarkLayout, TutorialRect, TutorialStep } from '~/utils/tutorial'
+import type { CoachMarkLayout, TutorialRect, TutorialStep, TutorialTour } from '~/utils/tutorial'
 import {
   isTargetClickAdvance,
   resolveSkip,
   stepTargetSelectors,
-  tourWasAbridged,
+  unexpectedlySkippedSteps,
   waitBudgetMs,
 } from './TutorialOverlay.logic'
 import type { TutorialDirection } from './TutorialOverlay.logic'
@@ -29,13 +29,38 @@ const { t } = useI18n()
 const tutorial = useTutorialStore()
 const { tours } = useTutorialTours()
 
-const tour = computed(() => tours.value.find((x) => x.id === tutorial.activeTourId) ?? null)
+/**
+ * The running tour's script, resolved ONCE from the slot when the tour starts and then HELD
+ * for its duration. Gates decide what is OFFERED; they do not get to rewrite a walkthrough
+ * that is already under way.
+ *
+ * Re-reading the gated slot on every flip was fine while the gates were slow-moving facts
+ * (a permission, a connection). Gates over live RUN state flip as a DIRECT RESULT of
+ * following the tour: `answer-park` is offered while something is waiting for a human, so
+ * the moment the user answered — the very thing the tour teaches — its `when` went false,
+ * the slot dropped the tour, and the watch below tore the overlay down one step short of its
+ * own finish card, with no completion recorded. Holding the script also freezes the branch
+ * `resolveTours` picked, so a step can't be swapped underneath a stationary cursor when a
+ * board that had both a decision and an approval loses one of them mid-tour.
+ */
+const tour = shallowRef<TutorialTour | null>(null)
+watch(
+  () => tutorial.activeTourId,
+  (id) => {
+    // Read untracked (a watch callback registers no dependencies), which is what pins the
+    // script: only starting a DIFFERENT tour re-resolves it.
+    tour.value = id ? (tours.value.find((x) => x.id === id) ?? null) : null
+  },
+  { immediate: true },
+)
+
 const step = computed<TutorialStep | null>(() => tour.value?.steps[tutorial.stepIndex] ?? null)
 const total = computed(() => tour.value?.steps.length ?? 0)
 const isLast = computed(() => tour.value !== null && tutorial.stepIndex >= total.value - 1)
 
-// The running tour vanished from the slot (a gate flipped, a consumer module withdrew it)
-// or the cursor ran past the end: end the tour instead of rendering a dead overlay.
+// The tour could not be resolved when it started (a stale persisted id, or a tour this board
+// is not offered at all) or the cursor ran past the end: end it instead of rendering a dead
+// overlay. Since the script is held, this can no longer fire because a gate flipped mid-tour.
 watch(
   () => [tour.value, step.value] as const,
   ([tr, st]) => {
@@ -44,7 +69,6 @@ watch(
   { immediate: true },
 )
 
-const targetEl = ref<HTMLElement | null>(null)
 const targetRect = ref<TutorialRect | null>(null)
 const cardEl = ref<HTMLElement | null>(null)
 const layout = ref<CoachMarkLayout>({ top: -9999, left: -9999, placement: 'center' })
@@ -62,7 +86,11 @@ const skippedStepIds = ref<Set<string>>(new Set())
 
 /** A targeted step whose anchor hasn't been found yet (renders the waiting note). */
 const searching = computed(() => step.value?.target !== undefined && targetRect.value === null)
-const abridged = computed(() => tourWasAbridged(skippedStepIds.value))
+/** The skips the final card must own up to — a branch-gated step's absence is not one. */
+const unexpectedSkips = computed(() =>
+  unexpectedlySkippedSteps(skippedStepIds.value, tour.value?.steps ?? []),
+)
+const abridged = computed(() => unexpectedSkips.value.length > 0)
 
 const viewport = () => ({ width: window.innerWidth, height: window.innerHeight })
 /** The tooltip's own size, or a sensible guess before it has rendered once. */
@@ -93,11 +121,9 @@ function measure() {
   const s = step.value
   if (!s) return
   if (!s.target) {
-    targetEl.value = null
     targetRect.value = null
   } else {
     const el = queryTarget(s)
-    targetEl.value = el
     if (!el) {
       targetRect.value = null
       // Centered while searching: the card must not sit at the PREVIOUS step's anchor —
@@ -122,7 +148,6 @@ function measure() {
 // the card has re-rendered its new copy (its size feeds the layout).
 watch(step, async (s) => {
   searchDeadline.value = performance.now() + (s ? waitBudgetMs(s) : DEFAULT_TARGET_WAIT_MS)
-  targetEl.value = null
   targetRect.value = null
   await nextTick()
   measure()
@@ -143,7 +168,7 @@ function back() {
 // control can't hide them) and follow along AFTER the app has reacted — the deferral lets
 // the real handler open its modal/submit its form before the tour moves its anchor.
 function onDocumentClick(event: MouseEvent) {
-  if (isTargetClickAdvance(step.value, targetEl.value, event.target)) {
+  if (isTargetClickAdvance(step.value, event.target)) {
     window.setTimeout(advance, 0)
   }
 }
@@ -208,7 +233,10 @@ onUnmounted(() => {
             {{ t('tutorial.overlay.progress', { current: tutorial.stepIndex + 1, total }) }}
           </span>
         </div>
-        <p class="text-sm text-slate-300">{{ t(step.bodyKey) }}</p>
+        <!-- `bodyParams` carries the fixed proper nouns a step names (a repository slug),
+             which live in the catalog's `{named}` placeholders rather than in nine
+             translations of the same literal. Absent for most steps. -->
+        <p class="text-sm text-slate-300">{{ t(step.bodyKey, step.bodyParams ?? {}) }}</p>
         <p
           v-if="searching"
           class="mt-2 flex items-center gap-1.5 text-xs text-slate-400"
@@ -231,7 +259,13 @@ onUnmounted(() => {
           class="mt-2 text-xs text-amber-300/90"
           data-testid="tutorial-abridged"
         >
-          {{ t('tutorial.overlay.abridged', { count: skippedStepIds.size }, skippedStepIds.size) }}
+          {{
+            t(
+              'tutorial.overlay.abridged',
+              { count: unexpectedSkips.length },
+              unexpectedSkips.length,
+            )
+          }}
         </p>
         <div class="mt-3 flex items-center justify-between gap-2">
           <UButton

package/app/composables/usePipelineErrorToast.spec.ts

@@ -49,7 +49,10 @@ beforeEach(() => {
   }
   vi.stubGlobal('useToast', () => ({ add, update }))
   vi.stubGlobal('useUiStore', () => ui)
-  vi.stubGlobal('useI18n', () => ({ t, te: (key: string) => hasKey(key) }))
+  // Stubbed on the Nuxt app's GLOBAL i18n instance, which is what this composable resolves
+  // (never `useI18n()`): it is called from store setup, where no component instance exists.
+  // See `frontend/app/README.md` — "A store must be instantiable outside a component setup".
+  vi.stubGlobal('useNuxtApp', () => ({ $i18n: { t, te: (key: string) => hasKey(key) } }))
 })
 
 function conflict(reason?: string, details: Record<string, unknown> = {}, message?: string) {

package/app/composables/usePipelineErrorToast.ts

@@ -331,7 +331,24 @@ export function describeGenericFailure(error: unknown): GenericFailure {
 export function usePipelineErrorToast() {
   const toast = useToast()
   const ui = useUiStore()
-  const { t, te } = useI18n()
+  // Resolved through the Nuxt app's global i18n instance rather than `useI18n()`, which
+  // requires an active component instance — the same pattern (and the same reason) as the
+  // board / recurring-pipelines stores.
+  //
+  // This composable is called from STORE SETUP (`stores/execution.ts`, `stores/agentRuns.ts`),
+  // and a Pinia setup store runs its body on the FIRST `useStore()` anywhere. That used to be
+  // a component, so `useI18n()` happened to be legal; the moment anything instantiated one of
+  // those stores earlier — `createNavGates()` does, from the `enforce: 'post'` modular plugin —
+  // vue-i18n threw `MUST_BE_CALL_SETUP_TOP`, the plugin threw, and Nuxt's error boundary
+  // replaced the entire app with its 500 page. Every single e2e spec failed on a blank board.
+  // A store must be instantiable outside a component, so the i18n handle it reaches for has
+  // to be too.
+  //
+  // Typed as `useI18n`'s own return (`$i18n` IS that global Composer in composition mode), so
+  // `t`/`te` keep their real signatures. No typed-message-key coverage is lost by the switch:
+  // tier 1 only sees literal keys written in a `<script setup>`, never in a `.ts` composable —
+  // the drift guard here is the exhaustive `CONFLICT_INFO` / `ApiErrorCode` records above.
+  const { t, te } = useNuxtApp().$i18n as ReturnType<typeof useI18n>
 
   // The five bespoke conflict reasons (a runtime-interpolated body + a "configure X" jump each)
   // live in a sibling factory over the same toast/ui/i18n handles, so this composable stays

package/app/modular/nav-contributions.spec.ts

@@ -26,6 +26,11 @@ const NO_GATES: NavGates = {
   // so a dropped item is unambiguously an RBAC/availability drop, not a tier drop.
   advancedMode: true,
   boardHasService: false,
+  boardHasTask: false,
+  boardHasRun: false,
+  boardHasOpenDecision: false,
+  boardHasPendingApproval: false,
+  boardHasFinishedRun: false,
 }
 
 const ALL_GATES: NavGates = {
@@ -39,6 +44,11 @@ const ALL_GATES: NavGates = {
   isAccountAdmin: true,
   advancedMode: true,
   boardHasService: true,
+  boardHasTask: true,
+  boardHasRun: true,
+  boardHasOpenDecision: true,
+  boardHasPendingApproval: true,
+  boardHasFinishedRun: true,
 }
 
 const slots = (): AppSlots => ({

package/app/modular/nav-contributions.ts

@@ -1,4 +1,5 @@
 import { defineModule } from '@modular-vue/core'
+import { resolveTours } from '~/utils/tutorial'
 import type { AppSlots } from './slots'
 
 // Re-exported for the slice-1 importers that reach `AppSlots` through this
@@ -89,6 +90,41 @@ export interface NavGates {
    * service lands on the board.
    */
   boardHasService: boolean
+  /**
+   * The open board has at least one task block. The service frame that {@link boardHasService}
+   * reports is where a task GOES; this is whether one is actually there to run, which is what
+   * a tour about the run controls needs — they live in the inspector of a task, and a board of
+   * empty frames offers nothing to open.
+   */
+  boardHasTask: boolean
+  /**
+   * Some run on a TASK block is cached for this board, in any state. Availability for the
+   * steps that explain a run's ANATOMY (the step list, its live progress), which have nothing
+   * to anchor to until a run has been started at least once.
+   *
+   * Task-scoped, like the three below: every surface these gates open is reached through a
+   * task card and its inspector, and a frame-level run (a blueprint pass, an initiative plan)
+   * renders none of them.
+   */
+  boardHasRun: boolean
+  /**
+   * Some task card is offering a human an unanswered DECISION to resolve.
+   *
+   * "Offering" rather than "exists": these two report what the board actually RENDERS, which
+   * is what a tour anchoring on the card's action can point at — see `hasActionablePark` for
+   * the two ways a park can exist with no control to show for it.
+   */
+  boardHasOpenDecision: boolean
+  /** Some task card is offering a human an unanswered APPROVAL gate. See above. */
+  boardHasPendingApproval: boolean
+  /**
+   * Some run on a task block has finished successfully. Availability for the review/merge
+   * tour: its subject is the OUTPUT of a run, so there has to be one that produced output. A
+   * FAILED run deliberately does not count — the failure banner is its own surface, and a
+   * tour about reading a result and merging it would spend its steps pointing at controls a
+   * failed run never renders.
+   */
+  boardHasFinishedRun: boolean
 }
 
 /** Command-palette placement + copy for a contribution that appears in the palette. */
@@ -542,11 +578,10 @@ export function navSlotFilter(slots: AppSlots, deps: { gates?: NavGates }): AppS
         )
       : nav,
     // Tutorial tours gate over the same reactive service, so a tour about a surface the
-    // caller can't reach (e.g. creating tasks without board write) never shows. Same
-    // gates-absent pass-through as `nav`.
-    tutorialTours: gates
-      ? tutorialTours.filter((t) => (t.when ? t.when(gates) : true))
-      : tutorialTours,
+    // caller can't reach (e.g. creating tasks without board write) never shows, and a step
+    // about a branch this board isn't on is dropped rather than skipped (see `resolveTours`).
+    // Same gates-absent pass-through as `nav`.
+    tutorialTours: gates ? resolveTours(tutorialTours, gates) : tutorialTours,
   }
 }
 

package/app/modular/nav-gates.logic.spec.ts

@@ -0,0 +1,41 @@
+import { describe, expect, it } from 'vitest'
+import { hasActionablePark } from '~/modular/nav-gates.logic'
+import type { ParkedGateRef } from '~/modular/nav-gates.logic'
+
+const onlyTasks = (id: string) => id.startsWith('task_')
+const nothingIsBackground = () => false
+
+describe('hasActionablePark', () => {
+  it('reports a park a task card really shows an action for', () => {
+    const parks: ParkedGateRef[] = [{ blockId: 'task_login', agentKind: 'architect' }]
+    expect(hasActionablePark(parks, onlyTasks, nothingIsBackground)).toBe(true)
+  })
+
+  it('ignores a park on a block that renders no task card', () => {
+    // A frame/module run parks too, but the affordance the tour anchors on is TaskCard's.
+    const parks: ParkedGateRef[] = [{ blockId: 'frame_billing', agentKind: 'blueprints' }]
+    expect(hasActionablePark(parks, onlyTasks, nothingIsBackground)).toBe(false)
+  })
+
+  it('ignores a reviewer gate the card suppresses as background work', () => {
+    // Mirrors `TaskCard.pendingApproval`: while the review is folding answers / re-reviewing
+    // it needs no human, so no Resolve button exists to point a tour at.
+    const parks: ParkedGateRef[] = [{ blockId: 'task_login', agentKind: 'requirements-review' }]
+    const isBackground = (kind: string | undefined) => kind === 'requirements-review'
+    expect(hasActionablePark(parks, onlyTasks, isBackground)).toBe(false)
+  })
+
+  it('reports the actionable one when a board holds both kinds at once', () => {
+    const parks: ParkedGateRef[] = [
+      { blockId: 'frame_billing', agentKind: 'architect' },
+      { blockId: 'task_login', agentKind: 'requirements-review' },
+      { blockId: 'task_signup', agentKind: 'coder' },
+    ]
+    const isBackground = (kind: string | undefined) => kind === 'requirements-review'
+    expect(hasActionablePark(parks, onlyTasks, isBackground)).toBe(true)
+  })
+
+  it('is false for a board with nothing parked at all', () => {
+    expect(hasActionablePark([], onlyTasks, nothingIsBackground)).toBe(false)
+  })
+})

package/app/modular/nav-gates.logic.ts

@@ -0,0 +1,36 @@
+/**
+ * The decisions the `NavGates` service makes that are worth testing without a Pinia runtime.
+ * `nav-gates.ts` itself is pure store wiring (getters over computeds); everything that
+ * DECIDES something lives here, the same split as `TutorialOverlay.logic.ts`.
+ */
+
+/** One park (an open decision or a pending approval gate) as the execution store projects it. */
+export interface ParkedGateRef {
+  blockId: string
+  agentKind?: string
+}
+
+/**
+ * Is some park actually SHOWING a human an action to take?
+ *
+ * The gates this answers (`boardHasOpenDecision` / `boardHasPendingApproval`) exist to offer
+ * a tour that anchors on a task card's attention affordance (`task-resolve`), so they have to
+ * mean what makes that affordance RENDER — not merely "a park exists somewhere in the cached
+ * runs". Two facts the raw store counts miss, both of which would offer the tour onto a board
+ * with no control to point at (the tour then anchor-skips and reports itself abridged, which
+ * is exactly the noise per-step `when` gating exists to avoid):
+ *
+ *  - a park on a frame or module block has no task card, so nothing renders the action;
+ *  - a reviewer gate mid-cycle is deliberately SUPPRESSED by the card (`TaskCard.pendingApproval`
+ *    → `useReviewStage().isBackground`): while the driver is folding answers or re-reviewing,
+ *    the gate needs no human and the card shows a working indicator instead.
+ *
+ * Both predicates are injected rather than reached for, so the rule is checkable on plain data.
+ */
+export function hasActionablePark(
+  parks: readonly ParkedGateRef[],
+  isTaskBlock: (blockId: string) => boolean,
+  isBackground: (agentKind: string | undefined, blockId: string) => boolean,
+): boolean {
+  return parks.some((p) => isTaskBlock(p.blockId) && !isBackground(p.agentKind, p.blockId))
+}