@cat-factory/app 0.12.0 → 0.14.0

package/app/components/spec/ServiceSpecWindow.vue

@@ -0,0 +1,348 @@
+<script setup lang="ts">
+// Service-spec window — the dedicated surface for a service's prescriptive specification,
+// opened from the inspector's "View Requirements" button (via the universal result-view
+// host). It reads the sharded `spec/` artifact off the service repo's default branch and
+// lets the human navigate the structured spec tree (modules → feature groups → requirements
+// + acceptance criteria + domain rules). When the spec is present on main, a toggle switches
+// to the rendered Gherkin scenarios (the seeded `.feature` files).
+import type {
+  RequirementGroup,
+  RequirementItem,
+  RequirementPriority,
+  SpecModule,
+} from '~/types/spec'
+
+const board = useBoardStore()
+const serviceSpec = useServiceSpecStore()
+
+type ViewMode = 'structured' | 'gherkin'
+const mode = ref<ViewMode>('structured')
+// Selected feature group, keyed by its module + group index so a name collision can't
+// cross-select. Null = show the service overview.
+const selected = ref<{ m: number; g: number } | null>(null)
+
+const { open, blockId, close } = useResultView('service-spec', {
+  onOpen: (id) => {
+    mode.value = 'structured'
+    selected.value = null
+    void serviceSpec.load(id)
+  },
+})
+
+const block = computed(() => (blockId.value ? board.getBlock(blockId.value) : undefined))
+const view = computed(() => (blockId.value ? serviceSpec.viewFor(blockId.value) : undefined))
+const loading = computed(() => (blockId.value ? serviceSpec.isLoading(blockId.value) : false))
+const errored = computed(() => (blockId.value ? serviceSpec.isErrored(blockId.value) : false))
+const spec = computed(() => view.value?.spec ?? null)
+const modules = computed<SpecModule[]>(() => spec.value?.modules ?? [])
+const present = computed(() => !!view.value?.present && !!spec.value)
+const hasGherkin = computed(() => (view.value?.features.length ?? 0) > 0)
+
+// Auto-select the first non-empty group once a present spec is shown, so the main pane isn't
+// empty. Depends on `blockId` as well as `present`: switching directly to ANOTHER already-cached
+// present block (via the inspector, without closing) changes `blockId` while `present` stays
+// true, so a watch on `present` alone would never re-fire and the second block would open on
+// the empty Overview pane. `immediate` covers the first, uncached open (present flips false→true
+// after the load). `onOpen` resets `selected` to null first (it runs before this watch, since
+// `useResultView` registers its blockId watch earlier), so a stale selection never leaks across.
+watch(
+  [present, blockId],
+  ([is]) => {
+    if (is && !selected.value) {
+      const m = modules.value.findIndex((mod) => (mod.groups?.length ?? 0) > 0)
+      if (m >= 0) selected.value = { m, g: 0 }
+    }
+  },
+  { immediate: true },
+)
+
+const selectedModule = computed<SpecModule | null>(() =>
+  selected.value ? (modules.value[selected.value.m] ?? null) : null,
+)
+const selectedGroup = computed<RequirementGroup | null>(() => {
+  if (!selected.value) return null
+  return selectedModule.value?.groups?.[selected.value.g] ?? null
+})
+
+// The Gherkin `.feature` content matching the selected group. Features carry display names
+// (not slugs), and the harness permits same-named groups in one module (only the on-disk
+// SLUGS are collision-suffixed), so a plain name match can cross-select. When several
+// features share the (module, group) name pair, disambiguate by the group's ordinal among
+// its same-named siblings — both lists derive from the same name-sorted walk, so the ordinals
+// line up.
+const selectedFeature = computed(() => {
+  const mod = selectedModule.value
+  const grp = selectedGroup.value
+  if (!mod || !grp) return null
+  const matches =
+    view.value?.features.filter((f) => f.module === mod.name && f.group === grp.name) ?? []
+  if (matches.length <= 1) return matches[0] ?? null
+  const sameNamed = (mod.groups ?? []).filter((g) => g.name === grp.name)
+  const ordinal = sameNamed.indexOf(grp)
+  return matches[ordinal] ?? matches[0] ?? null
+})
+
+function selectGroup(m: number, g: number) {
+  selected.value = { m, g }
+}
+
+const PRIORITY_META: Record<RequirementPriority, { label: string; chip: string }> = {
+  must: { label: 'Must', chip: 'error' },
+  should: { label: 'Should', chip: 'warning' },
+  could: { label: 'Could', chip: 'neutral' },
+}
+
+function reqCount(group: RequirementGroup): number {
+  return group.requirements?.length ?? 0
+}
+function priorityMeta(item: RequirementItem) {
+  return PRIORITY_META[item.priority] ?? PRIORITY_META.could
+}
+</script>
+
+<template>
+  <Teleport to="body">
+    <div
+      v-if="open"
+      class="fixed inset-0 z-50 flex items-center justify-center bg-slate-950/70 p-4 backdrop-blur-sm"
+      @click.self="close"
+    >
+      <div
+        class="flex h-[90vh] w-full max-w-5xl flex-col overflow-hidden rounded-2xl border border-slate-800 bg-slate-900 shadow-2xl"
+      >
+        <!-- header -->
+        <header class="flex items-center gap-3 border-b border-slate-800 px-6 py-4">
+          <div
+            class="flex h-9 w-9 shrink-0 items-center justify-center rounded-lg bg-indigo-500/15"
+          >
+            <UIcon name="i-lucide-scroll-text" class="h-5 w-5 text-indigo-300" />
+          </div>
+          <div class="min-w-0">
+            <h1 class="truncate text-base font-semibold text-white">Requirements</h1>
+            <p v-if="block" class="truncate text-xs text-slate-500">
+              {{ spec?.service || block.title }}
+            </p>
+          </div>
+          <div class="ml-auto flex items-center gap-1.5">
+            <!-- view toggle: Gherkin only when the spec (and its feature files) are on main -->
+            <div v-if="present" class="flex items-center rounded-lg border border-slate-700 p-0.5">
+              <UButton
+                :color="mode === 'structured' ? 'primary' : 'neutral'"
+                :variant="mode === 'structured' ? 'soft' : 'ghost'"
+                size="xs"
+                icon="i-lucide-list-tree"
+                @click="mode = 'structured'"
+              >
+                Structured
+              </UButton>
+              <UButton
+                :color="mode === 'gherkin' ? 'primary' : 'neutral'"
+                :variant="mode === 'gherkin' ? 'soft' : 'ghost'"
+                size="xs"
+                icon="i-lucide-square-check-big"
+                :disabled="!hasGherkin"
+                :title="hasGherkin ? 'Gherkin scenarios' : 'No scenarios on main yet'"
+                @click="mode = 'gherkin'"
+              >
+                Gherkin
+              </UButton>
+            </div>
+            <UButton icon="i-lucide-x" color="neutral" variant="ghost" size="sm" @click="close" />
+          </div>
+        </header>
+
+        <!-- loading -->
+        <div
+          v-if="loading && !view"
+          class="flex flex-1 items-center justify-center gap-2 text-sm text-slate-400"
+        >
+          <UIcon name="i-lucide-loader-circle" class="h-4 w-4 animate-spin" />
+          Loading the specification…
+        </div>
+
+        <!-- error -->
+        <div
+          v-else-if="errored"
+          class="flex flex-1 flex-col items-center justify-center gap-2 p-8 text-center text-sm text-slate-400"
+        >
+          <UIcon name="i-lucide-triangle-alert" class="h-6 w-6 text-amber-400" />
+          Could not load the specification. Try reopening this window.
+        </div>
+
+        <!-- empty: no spec on the repo's default branch yet -->
+        <div
+          v-else-if="!present"
+          class="flex flex-1 flex-col items-center justify-center gap-3 p-8 text-center"
+        >
+          <UIcon name="i-lucide-scroll-text" class="h-8 w-8 text-slate-600" />
+          <div>
+            <p class="text-sm font-medium text-slate-300">No specification yet</p>
+            <p class="mx-auto mt-1 max-w-md text-xs text-slate-500">
+              This service has no spec on its default branch. A specification is generated as tasks
+              run their pipelines; once it lands on main it will appear here, with its Gherkin
+              scenarios.
+            </p>
+          </div>
+        </div>
+
+        <!-- spec body: navigable tree + detail -->
+        <div v-else class="flex min-h-0 flex-1">
+          <!-- nav: modules → feature groups -->
+          <nav class="w-64 shrink-0 overflow-y-auto border-r border-slate-800 px-3 py-4">
+            <UButton
+              block
+              class="mb-2 justify-start"
+              :color="selected === null ? 'primary' : 'neutral'"
+              :variant="selected === null ? 'soft' : 'ghost'"
+              size="xs"
+              icon="i-lucide-info"
+              @click="selected = null"
+            >
+              Overview
+            </UButton>
+            <div v-for="(mod, mi) in modules" :key="mi" class="mb-3">
+              <div
+                class="px-2 pb-1 text-[11px] font-semibold uppercase tracking-wide text-slate-500"
+              >
+                {{ mod.name }}
+              </div>
+              <ul class="space-y-0.5">
+                <li v-for="(group, gi) in mod.groups ?? []" :key="gi">
+                  <button
+                    type="button"
+                    class="flex w-full items-center justify-between gap-2 rounded-md px-2 py-1.5 text-left text-[13px] transition"
+                    :class="
+                      selected?.m === mi && selected?.g === gi
+                        ? 'bg-indigo-500/15 text-indigo-200'
+                        : 'text-slate-300 hover:bg-slate-800'
+                    "
+                    @click="selectGroup(mi, gi)"
+                  >
+                    <span class="truncate">{{ group.name }}</span>
+                    <span class="shrink-0 text-[10px] text-slate-500">{{ reqCount(group) }}</span>
+                  </button>
+                </li>
+                <li
+                  v-if="(mod.groups?.length ?? 0) === 0"
+                  class="px-2 py-1 text-[11px] italic text-slate-600"
+                >
+                  No feature groups
+                </li>
+              </ul>
+            </div>
+          </nav>
+
+          <!-- detail -->
+          <div class="min-w-0 flex-1 overflow-y-auto px-6 py-5">
+            <!-- service overview -->
+            <template v-if="selected === null">
+              <h2 class="text-lg font-semibold text-white">{{ spec?.service }}</h2>
+              <p v-if="spec?.summary" class="mt-2 whitespace-pre-line text-sm text-slate-300">
+                {{ spec.summary }}
+              </p>
+              <p v-else class="mt-2 text-sm text-slate-500">No service summary.</p>
+              <p class="mt-4 text-xs text-slate-500">
+                {{ modules.length }} module(s). Select a feature group on the left to view its
+                requirements{{ hasGherkin ? ' or switch to the Gherkin scenarios' : '' }}.
+              </p>
+            </template>
+
+            <!-- selected feature group -->
+            <template v-else-if="selectedGroup">
+              <div class="mb-1 text-[11px] uppercase tracking-wide text-slate-500">
+                {{ selectedModule?.name }}
+              </div>
+              <h2 class="text-lg font-semibold text-white">{{ selectedGroup.name }}</h2>
+              <p v-if="selectedGroup.summary" class="mt-1 text-sm text-slate-400">
+                {{ selectedGroup.summary }}
+              </p>
+
+              <!-- GHERKIN view: the rendered .feature file for this group -->
+              <template v-if="mode === 'gherkin'">
+                <pre
+                  v-if="selectedFeature"
+                  class="mt-4 overflow-x-auto rounded-lg border border-slate-800 bg-slate-950/60 p-4 text-[12.5px] leading-relaxed text-slate-200"
+                ><code>{{ selectedFeature.content }}</code></pre>
+                <div
+                  v-else
+                  class="mt-4 rounded-lg border border-dashed border-slate-700 p-6 text-center text-sm text-slate-500"
+                >
+                  No Gherkin scenarios for this group.
+                </div>
+              </template>
+
+              <!-- STRUCTURED view: requirements + acceptance + domain rules -->
+              <template v-else>
+                <div v-if="reqCount(selectedGroup) === 0" class="mt-4 text-sm text-slate-500">
+                  No requirements in this group.
+                </div>
+                <ul class="mt-4 space-y-4">
+                  <li
+                    v-for="req in selectedGroup.requirements ?? []"
+                    :key="req.id"
+                    class="rounded-lg border border-slate-800 bg-slate-900/60 p-4"
+                  >
+                    <div class="flex items-start justify-between gap-3">
+                      <h3 class="text-sm font-semibold text-slate-100">{{ req.title }}</h3>
+                      <div class="flex shrink-0 items-center gap-1.5">
+                        <UBadge :color="priorityMeta(req).chip as any" variant="subtle" size="sm">
+                          {{ priorityMeta(req).label }}
+                        </UBadge>
+                        <UBadge color="neutral" variant="subtle" size="sm">{{ req.kind }}</UBadge>
+                      </div>
+                    </div>
+                    <p
+                      class="mt-1.5 whitespace-pre-line text-[13px] leading-relaxed text-slate-300"
+                    >
+                      {{ req.statement }}
+                    </p>
+                    <!-- acceptance criteria (Given/When/Then) -->
+                    <div v-if="(req.acceptance?.length ?? 0) > 0" class="mt-3 space-y-1.5">
+                      <div
+                        v-for="ac in req.acceptance ?? []"
+                        :key="ac.id"
+                        class="rounded-md border border-slate-800 bg-slate-950/50 px-3 py-2 text-[12.5px] leading-relaxed"
+                      >
+                        <p class="text-slate-300">
+                          <span class="font-semibold text-emerald-400">Given</span> {{ ac.given }}
+                        </p>
+                        <p class="text-slate-300">
+                          <span class="font-semibold text-sky-400">When</span> {{ ac.when }}
+                        </p>
+                        <p class="text-slate-300">
+                          <span class="font-semibold text-violet-400">Then</span> {{ ac.outcome }}
+                        </p>
+                      </div>
+                    </div>
+                  </li>
+                </ul>
+
+                <!-- domain rules / invariants scoped to this group -->
+                <div v-if="(selectedGroup.rules?.length ?? 0) > 0" class="mt-6">
+                  <div
+                    class="mb-2 flex items-center gap-1.5 text-[11px] font-semibold uppercase tracking-wide text-slate-400"
+                  >
+                    <UIcon name="i-lucide-shield-check" class="h-3.5 w-3.5" />
+                    Domain rules
+                  </div>
+                  <ul class="space-y-1.5">
+                    <li
+                      v-for="rule in selectedGroup.rules ?? []"
+                      :key="rule.id"
+                      class="rounded-md border border-slate-800 bg-slate-900/60 px-3 py-2 text-[13px] text-slate-300"
+                    >
+                      {{ rule.rule }}
+                      <span v-if="rule.rationale" class="text-slate-500">
+                        — {{ rule.rationale }}</span
+                      >
+                    </li>
+                  </ul>
+                </div>
+              </template>
+            </template>
+          </div>
+        </div>
+      </div>
+    </div>
+  </Teleport>
+</template>

package/app/composables/api/spec.ts

@@ -0,0 +1,14 @@
+import type { ServiceSpecView } from '~/types/spec'
+import type { ApiContext } from './context'
+
+/**
+ * The service-spec read (the inspector's "View Requirements" window). Reassembles the
+ * sharded `spec/` artifact from the service repo's default branch. Always 200: a service
+ * with no spec on main (or no GitHub connected) returns `{ present: false }`.
+ */
+export function specApi({ http, ws }: ApiContext) {
+  return {
+    getServiceSpec: (workspaceId: string, blockId: string) =>
+      http<ServiceSpecView>(`${ws(workspaceId)}/blocks/${encodeURIComponent(blockId)}/spec`),
+  }
+}

package/app/composables/api/tasks.ts

@@ -3,6 +3,7 @@ import type {
   SourceTask,
   TaskConnection,
   TaskSearchResult,
+  TaskSourceDiagnostic,
   TaskSourceKind,
   TaskSourceState,
 } from '~/types/domain'
@@ -41,6 +42,13 @@ export function tasksApi({ http, ws }: ApiContext) {
     disconnectTaskSource: (workspaceId: string, source: TaskSourceKind) =>
       http(`${ws(workspaceId)}/task-sources/${source}/connection`, { method: 'DELETE' }),
 
+    // Live "check setup" probe: authenticates against the source and reads a slice
+    // of its issues API, returning a classified verdict the panel renders verbatim.
+    checkTaskSource: (workspaceId: string, source: TaskSourceKind) =>
+      http<TaskSourceDiagnostic>(`${ws(workspaceId)}/task-sources/${source}/diagnostics`, {
+        method: 'POST',
+      }),
+
     listTasks: (workspaceId: string) => http<SourceTask[]>(`${ws(workspaceId)}/tasks`),
 
     importTask: (workspaceId: string, source: TaskSourceKind, body: { ref: string }) =>

package/app/composables/useApi.ts

@@ -15,6 +15,7 @@ import { recurringApi } from './api/recurring'
 import { releaseHealthApi } from './api/releaseHealth'
 import { reviewsApi } from './api/reviews'
 import { slackApi } from './api/slack'
+import { specApi } from './api/spec'
 import { tasksApi } from './api/tasks'
 import { workspacesApi } from './api/workspaces'
 
@@ -78,6 +79,7 @@ export function useApi() {
     ...documentsApi(ctx),
     ...tasksApi(ctx),
     ...reviewsApi(ctx),
+    ...specApi(ctx),
     ...notificationsApi(ctx),
     ...presetsApi(ctx),
     ...releaseHealthApi(ctx),

package/app/stores/serviceSpec.ts

@@ -0,0 +1,72 @@
+import { defineStore } from 'pinia'
+import { reactive, ref } from 'vue'
+import type { ServiceSpecView } from '~/types/spec'
+import { useWorkspaceStore } from '~/stores/workspace'
+
+/**
+ * Service-spec read state for the inspector's "View Requirements" window. The spec lives
+ * sharded in the service repo under `spec/`; the backend reassembles it from the repo's
+ * default branch and serves a {@link ServiceSpecView}. Read-only and fetched on demand
+ * (per service frame block), cached per block. Nothing is persisted client-side.
+ */
+export const useServiceSpecStore = defineStore('serviceSpec', () => {
+  const api = useApi()
+  const workspace = useWorkspaceStore()
+
+  /** The fetched view per block id (undefined = not yet fetched). */
+  const views = ref<Record<string, ServiceSpecView>>({})
+  /**
+   * In-flight loads keyed by block id — the SINGLE source of truth for "is this block
+   * loading". A reactive Map so `isLoading` (derived from `.has`) tracks set/delete, and it
+   * also coalesces overlapping loads onto one request: no separate loading-flag Set to keep
+   * in sync.
+   */
+  const inFlight = reactive(new Map<string, Promise<void>>())
+  /** Block ids whose last fetch failed (network / unexpected error). */
+  const erroredByBlock = ref<Set<string>>(new Set())
+
+  function viewFor(blockId: string): ServiceSpecView | undefined {
+    return views.value[blockId]
+  }
+  function isLoading(blockId: string): boolean {
+    return inFlight.has(blockId)
+  }
+  function isErrored(blockId: string): boolean {
+    return erroredByBlock.value.has(blockId)
+  }
+
+  function setErrored(key: string, on: boolean) {
+    const next = new Set(erroredByBlock.value)
+    if (on) next.add(key)
+    else next.delete(key)
+    erroredByBlock.value = next
+  }
+
+  /** Fetch (and cache) the spec view for a service frame block. */
+  async function load(blockId: string) {
+    if (!workspace.workspaceId) return
+    const pending = inFlight.get(blockId)
+    if (pending) return pending
+    setErrored(blockId, false)
+    const promise = (async () => {
+      try {
+        const view = await api.getServiceSpec(workspace.requireId(), blockId)
+        views.value = { ...views.value, [blockId]: view }
+      } catch {
+        setErrored(blockId, true)
+      } finally {
+        inFlight.delete(blockId)
+      }
+    })()
+    inFlight.set(blockId, promise)
+    return promise
+  }
+
+  return {
+    views,
+    viewFor,
+    isLoading,
+    isErrored,
+    load,
+  }
+})

package/app/stores/tasks.ts

@@ -4,6 +4,7 @@ import type {
   SourceTask,
   TaskConnection,
   TaskSearchResult,
+  TaskSourceDiagnostic,
   TaskSourceKind,
   TaskSourceState,
 } from '~/types/domain'
@@ -27,11 +28,21 @@ export const useTasksStore = defineStore('tasks', () => {
 
   /** null = unknown (not probed yet), true/false = integration on/off. */
   const available = ref<boolean | null>(null)
+  /**
+   * Why the last probe failed, when it did — captured (rather than swallowed) so
+   * the settings panel can explain *why* nothing is surfaced (integration disabled
+   * vs a server/backend error) instead of a blanket "install integration first".
+   */
+  const probeError = ref<{ status: number | null; message: string } | null>(null)
   /** The configured sources, each with its descriptor + per-workspace state (available + enabled). */
   const sources = ref<TaskSourceState[]>([])
   /** Live connections, one per connected (credentialed) source. */
   const connections = ref<TaskConnection[]>([])
   const tasks = ref<SourceTask[]>([])
+  /** The last live setup-check verdict per source (from `checkSetup`). */
+  const diagnostics = ref<Partial<Record<TaskSourceKind, TaskSourceDiagnostic>>>({})
+  /** The source currently running a setup check, if any. */
+  const checking = ref<TaskSourceKind | null>(null)
   const loading = ref(false)
 
   /** Sources the workspace currently has a live connection to. */
@@ -85,16 +96,43 @@ export const useTasksStore = defineStore('tasks', () => {
         api.listTaskConnections(workspace.requireId()),
       ])
       available.value = true
+      probeError.value = null
       sources.value = srcs
       connections.value = conns
-    } catch {
-      // 503 (integration disabled) or any error → hide the UI entry points.
+    } catch (e) {
+      // 503 (integration disabled) or any error → hide the UI entry points, but keep
+      // the reason so the settings panel can explain it (a 503 is "turned off on this
+      // deployment"; a 500 is "the backend errored — e.g. a migration isn't applied").
       available.value = false
+      const err = e as { statusCode?: number; data?: { error?: { message?: string } } }
+      const serverMessage = err?.data?.error?.message
+      probeError.value = {
+        status: err?.statusCode ?? null,
+        message: serverMessage || (e instanceof Error ? e.message : String(e)),
+      }
       sources.value = []
       connections.value = []
     }
   }
 
+  /**
+   * Run a live setup check for a source (authenticate + read), caching the verdict
+   * so the panel can show exactly what's wrong (missing App / wrong token / lacking
+   * the Issues permission) and how to fix it. Re-probes on success so a
+   * just-fixed source flips `available`/`enabled` without a manual reload.
+   */
+  async function checkSetup(source: TaskSourceKind): Promise<TaskSourceDiagnostic> {
+    checking.value = source
+    try {
+      const result = await api.checkTaskSource(workspace.requireId(), source)
+      diagnostics.value = { ...diagnostics.value, [source]: result }
+      if (result.ok) await probe()
+      return result
+    } finally {
+      checking.value = null
+    }
+  }
+
   /** Connect the workspace to a source with its credential bag. */
   async function connect(source: TaskSourceKind, credentials: Record<string, string>) {
     const conn = await api.connectTaskSource(workspace.requireId(), source, credentials)
@@ -165,9 +203,12 @@ export const useTasksStore = defineStore('tasks', () => {
 
   return {
     available,
+    probeError,
     sources,
     connections,
     tasks,
+    diagnostics,
+    checking,
     loading,
     connectedSources,
     anyConnected,
@@ -178,6 +219,7 @@ export const useTasksStore = defineStore('tasks', () => {
     isConnected,
     tasksForBlock,
     probe,
+    checkSetup,
     connect,
     disconnect,
     setEnabled,

package/app/stores/ui.ts

@@ -336,6 +336,10 @@ export const useUiStore = defineStore('ui', () => {
   function openClarityReview(blockId: string) {
     resultView.value = { view: 'clarity-review', blockId, instanceId: null, stepIndex: null }
   }
+  // Open the service-spec window for a service frame (the inspector's "View Requirements").
+  function openServiceSpec(blockId: string) {
+    resultView.value = { view: 'service-spec', blockId, instanceId: null, stepIndex: null }
+  }
   function closeResultView() {
     resultView.value = null
   }
@@ -440,6 +444,7 @@ export const useUiStore = defineStore('ui', () => {
     closeOpenRouter,
     openRequirementReview,
     openClarityReview,
+    openServiceSpec,
     closeRequirementReview,
     openStepDetail,
     closeStepDetail,

package/app/types/spec.ts

@@ -0,0 +1,74 @@
+// The prescriptive, service-level SPECIFICATION read view. These shapes mirror the
+// `@cat-factory/contracts` `spec.ts` wire schemas exactly (see the note in `domain.ts`),
+// so the service-spec endpoint's payload drops straight into the store. The spec lives
+// sharded in the service repo under `spec/`; the backend reassembles it from the repo's
+// default branch and serves it as `ServiceSpecView` for the inspector's "View
+// Requirements" window.
+
+export type RequirementPriority = 'must' | 'should' | 'could'
+export type RequirementKind = 'functional' | 'nonfunctional' | 'constraint'
+
+/** One acceptance criterion in Given/When/Then form — the seed for a Gherkin scenario. */
+export interface AcceptanceCriterion {
+  id: string
+  given: string
+  when: string
+  /** The Gherkin "Then" clause (named `outcome` so the object is never thenable). */
+  outcome: string
+}
+
+/** A single prescriptive requirement, traceable to the board task(s) it came from. */
+export interface RequirementItem {
+  id: string
+  title: string
+  statement: string
+  kind: RequirementKind
+  priority: RequirementPriority
+  sourceBlockIds?: string[]
+  acceptance?: AcceptanceCriterion[]
+}
+
+/** A domain rule / invariant scoped to the feature group it governs. */
+export interface DomainRule {
+  id: string
+  rule: string
+  rationale?: string
+  sourceBlockIds?: string[]
+}
+
+/** A feature / logical group: related requirements plus the domain rules scoped to them. */
+export interface RequirementGroup {
+  name: string
+  summary?: string
+  requirements?: RequirementItem[]
+  rules?: DomainRule[]
+}
+
+/** A module (domain) — the top level of the taxonomy, holding feature groups. */
+export interface SpecModule {
+  name: string
+  summary?: string
+  groups?: RequirementGroup[]
+}
+
+/** The unified prescriptive specification document for one service. */
+export interface SpecDoc {
+  service: string
+  summary?: string
+  modules?: SpecModule[]
+}
+
+/** A rendered Gherkin feature file read back from the repo. */
+export interface SpecFeatureFile {
+  module: string
+  group: string
+  path: string
+  content: string
+}
+
+/** The service-spec view: the reassembled tree + its Gherkin files (empty when none). */
+export interface ServiceSpecView {
+  present: boolean
+  spec: SpecDoc | null
+  features: SpecFeatureFile[]
+}