@cat-factory/app 0.281.0 → 0.282.0

package/app/components/board/AddTaskModal.vue

@@ -28,6 +28,7 @@ import type { AppSlots, ResultViewContribution } from '~/modular/slots'
 import ContextAttachmentFields from '~/components/context/ContextAttachmentFields.vue'
 import DescriptorFields from '~/components/common/DescriptorFields.vue'
 import FragmentSelector from '~/components/fragments/FragmentSelector.vue'
+import ReviewSkillQueue from '~/components/skills/ReviewSkillQueue.vue'
 import RiskPolicyPicker from '~/components/riskPolicy/RiskPolicyPicker.vue'
 import { parseConflict } from '~/composables/usePipelineErrorToast'
 import { apiErrorEnvelope } from '~/composables/api/errors'
@@ -143,6 +144,9 @@ const docOutlineHints = ref('')
 // review focus. The single input is parsed into the contract's `prUrl`/`prNumber` fields.
 const reviewPrRef = ref('')
 const reviewFocus = ref('')
+// Specialist review playbooks queued onto the review, in the order the reviewer applies them.
+// Offered from the account catalog's `review` group only (see ReviewSkillQueue).
+const reviewSkillIds = ref<string[]>([])
 
 // Best-practice prompt fragments the user pins on the task up front (folded into its agents
 // on top of the service-level standards, exactly like the inspector's picker). Chosen from the
@@ -320,6 +324,7 @@ function buildTypeFields(): TaskTypeFields | undefined {
   if (taskType.value === 'review') {
     const f: TaskTypeFields = { ...parseReviewPrRef(reviewPrRef.value) }
     if (reviewFocus.value.trim()) f.reviewFocus = reviewFocus.value.trim()
+    if (reviewSkillIds.value.length) f.reviewSkillIds = [...reviewSkillIds.value]
     return Object.keys(f).length ? f : undefined
   }
   return buildCustomTypeFields()
@@ -569,6 +574,7 @@ watch(open, (isOpen) => {
   docOutlineHints.value = ''
   reviewPrRef.value = ''
   reviewFocus.value = ''
+  reviewSkillIds.value = []
   // Empty rather than default-seeded: `taskType` was just reset to a BUILT-IN above, which
   // declares no descriptor fields. Picking a custom type from here runs the `taskType` watcher,
   // and that is the one place the new type's declared defaults are seeded.
@@ -1170,6 +1176,10 @@ function openReviewFrictionDialog(conflict: NonNullable<ReturnType<typeof parseC
                 class="w-full"
               />
             </UFormField>
+            <!-- The team's specialist review playbooks, applied on top of the reviewer's standing
+                 role. Always shown (not advanced-only): queueing a security or performance pass is
+                 a per-review judgement a reviewer makes, not a platform setting. -->
+            <ReviewSkillQueue v-model="reviewSkillIds" />
           </div>
 
           <!-- A CUSTOM (deployment-registered) task type: a bespoke create-form section when its

package/app/components/panels/inspector/TaskReviewTarget.logic.spec.ts

@@ -0,0 +1,56 @@
+import { describe, expect, it } from 'vitest'
+import { reviewQueueDirty, reviewSkillQueuePatch } from './TaskReviewTarget.logic'
+import type { TaskTypeFields } from '~/types/domain'
+
+const stored: TaskTypeFields = {
+  prNumber: 42,
+  prUrl: 'https://github.com/acme/app/pull/42',
+  reviewFocus: 'the auth changes',
+  reviewSkillIds: ['src:s:security', 'src:s:perf'],
+  custom: { ticket: 'OPS-1' },
+}
+
+describe('reviewSkillQueuePatch', () => {
+  it('carries every other built-in key, so editing the queue cannot clear the target PR', () => {
+    // The write replaces the built-in half whole. A key left out of this payload is a key erased.
+    const patch = reviewSkillQueuePatch(stored, ['src:s:perf'])
+    expect(patch.prNumber).toBe(42)
+    expect(patch.prUrl).toBe(stored.prUrl)
+    expect(patch.reviewFocus).toBe(stored.reviewFocus)
+    expect(patch.reviewSkillIds).toEqual(['src:s:perf'])
+  })
+
+  it('CLEARS the queue when the last skill is removed', () => {
+    // The case that un-wedges a task whose queued skill left the catalog: every dispatch fails on
+    // that id, and removing it is the fix. Carrying the stored ids through would make this a
+    // silent no-op, which reads to the user as "the platform ignored me".
+    const patch = reviewSkillQueuePatch(stored, [])
+    expect(patch).not.toHaveProperty('reviewSkillIds')
+    expect(patch.prNumber).toBe(42)
+  })
+
+  it('never sends the custom half, which travels under its own request key', () => {
+    expect(reviewSkillQueuePatch(stored, ['src:s:security'])).not.toHaveProperty('custom')
+  })
+
+  it('starts a queue on a task that stored no fields at all', () => {
+    expect(reviewSkillQueuePatch(null, ['src:s:security'])).toEqual({
+      reviewSkillIds: ['src:s:security'],
+    })
+    expect(reviewSkillQueuePatch(undefined, [])).toEqual({})
+  })
+})
+
+describe('reviewQueueDirty', () => {
+  it('sees a REORDER, because the reviewer applies the queue in order', () => {
+    expect(reviewQueueDirty(['a', 'b'], ['b', 'a'])).toBe(true)
+    expect(reviewQueueDirty(['a', 'b'], ['a', 'b'])).toBe(false)
+  })
+
+  it('sees an addition, a removal, and an emptied queue', () => {
+    expect(reviewQueueDirty(['a'], ['a', 'b'])).toBe(true)
+    expect(reviewQueueDirty(['a', 'b'], ['a'])).toBe(true)
+    expect(reviewQueueDirty(['a'], [])).toBe(true)
+    expect(reviewQueueDirty([], [])).toBe(false)
+  })
+})

package/app/components/panels/inspector/TaskReviewTarget.logic.ts

@@ -0,0 +1,32 @@
+import type { TaskTypeFields } from '~/types/domain'
+
+// The pure half of TaskReviewTarget: what an edit of the review-skill queue SENDS. Extracted for
+// the reason every `*.logic.ts` here is (a decision worth a test should not need a mounted
+// component to reach), and this one carries a rule the shape of the request makes easy to get
+// wrong in exactly one direction.
+
+/**
+ * The `builtinTaskTypeFields` payload that stores `queue` as this task's review-skill queue.
+ *
+ * The built-in half is replaced WHOLE by the write (`replaceBuiltinHalf`), so every other built-in
+ * key has to be carried or editing the queue would clear the pull request the task reviews. The
+ * `custom` half travels under its own request key and is dropped here by construction.
+ *
+ * The stored queue is dropped from that carry-through FIRST, and that is the whole point: an
+ * EMPTY queue is expressed by the key being absent, so spreading the stored bag and then adding
+ * the key back only when non-empty would carry the old ids on the one edit that most needs to
+ * land. Removing the last queued skill is how a task wedged by a skill that left the catalog gets
+ * un-wedged, so it is precisely the case that must not silently no-op.
+ */
+export function reviewSkillQueuePatch(
+  stored: TaskTypeFields | null | undefined,
+  queue: readonly string[],
+): TaskTypeFields {
+  const { custom: _custom, reviewSkillIds: _stored, ...builtin } = stored ?? {}
+  return { ...builtin, ...(queue.length ? { reviewSkillIds: [...queue] } : {}) }
+}
+
+/** Whether the edit buffer differs from the stored queue, ORDER included (the queue is ordered). */
+export function reviewQueueDirty(stored: readonly string[], draft: readonly string[]): boolean {
+  return stored.length !== draft.length || stored.some((id, i) => draft[i] !== id)
+}

package/app/components/panels/inspector/TaskReviewTarget.vue

@@ -9,11 +9,23 @@
 // provider's own link (`prUrl`), which is what makes a plain read enough here; a task created
 // while no VCS was connected keeps only the number, and then the reference reads as text rather
 // than pretending to be a link.
-import { computed } from 'vue'
+//
+// The SKILL QUEUE is editable here, and that is not a convenience. A queued skill that has left
+// the catalog FAILS every dispatch of this task, and the refusal's remedy names the task's own
+// queue as where the fix is made; with the queue frozen at creation that remedy pointed at
+// nothing and the only exit was deleting a task whose id every stored reference holds. Same
+// reasoning as `TaskTypeFields`, which exists for the same shape of dead end.
+import { computed, ref, watch } from 'vue'
 import type { Block } from '~/types/domain'
 import InspectorSection from '~/components/panels/inspector/InspectorSection.vue'
+import ReviewSkillQueue from '~/components/skills/ReviewSkillQueue.vue'
+import {
+  reviewQueueDirty,
+  reviewSkillQueuePatch,
+} from '~/components/panels/inspector/TaskReviewTarget.logic'
 
 const props = defineProps<{ block: Block }>()
+const board = useBoardStore()
 const { t } = useI18n()
 
 const isReview = computed(() => props.block.taskType === 'review')
@@ -27,13 +39,46 @@ const label = computed(() => {
   return number ? t('inspector.reviewTarget.prNumber', { number }) : url.value
 })
 
-/** Nothing to show when the task carries no reference at all (nothing to link or name). */
-const hasTarget = computed(() => Boolean(label.value))
+/** The queue as STORED, the baseline the edit buffer is seeded from and compared against. */
+const stored = computed<string[]>(() => fields.value?.reviewSkillIds ?? [])
+
+// Local edit buffer, re-seeded whenever the stored queue changes underneath (a live board push,
+// or switching blocks). Editing writes on commit rather than per pick, so a half-built queue
+// never reaches the row a dispatch reads.
+const draft = ref<string[]>([...stored.value])
+watch(stored, (next) => {
+  draft.value = [...next]
+})
+
+const dirty = computed(() => reviewQueueDirty(stored.value, draft.value))
+const saving = ref(false)
+
+/**
+ * Write the queue through the BUILT-IN half of the per-type bag, which REPLACES that half whole.
+ * What that means for the payload (carry the other built-in keys; express an EMPTY queue by the
+ * key's absence rather than by an empty array riding a stored one) is
+ * {@link reviewSkillQueuePatch}, which is where it is tested.
+ */
+async function save() {
+  if (!dirty.value) return
+  saving.value = true
+  try {
+    await board.updateBlock(props.block.id, {
+      builtinTaskTypeFields: reviewSkillQueuePatch(props.block.taskTypeFields, draft.value),
+    })
+  } finally {
+    saving.value = false
+  }
+}
+
+function revert() {
+  draft.value = [...stored.value]
+}
 </script>
 
 <template>
   <InspectorSection
-    v-if="isReview && hasTarget"
+    v-if="isReview"
     :title="t('inspector.reviewTarget.title')"
     :hint="t('inspector.reviewTarget.hint')"
     icon="i-lucide-git-pull-request-arrow"
@@ -56,7 +101,7 @@ const hasTarget = computed(() => Boolean(label.value))
       <span class="w-full truncate text-start" :title="url">{{ label }}</span>
     </UButton>
     <p
-      v-else
+      v-else-if="label"
       class="rounded-lg border border-slate-800 bg-slate-900/40 p-2.5 text-xs text-slate-300"
       data-testid="inspector-review-target-link"
     >
@@ -65,5 +110,29 @@ const hasTarget = computed(() => Boolean(label.value))
     <p v-if="focus" class="text-xs leading-relaxed text-slate-500">
       {{ t('inspector.reviewTarget.focus', { focus }) }}
     </p>
+    <div data-testid="inspector-review-skills">
+      <ReviewSkillQueue v-model="draft" />
+      <div v-if="dirty" class="mt-2 flex items-center gap-2">
+        <UButton
+          size="xs"
+          color="primary"
+          variant="soft"
+          :loading="saving"
+          data-testid="inspector-review-skills-save"
+          @click="save"
+        >
+          {{ t('skills.reviewQueue.save') }}
+        </UButton>
+        <UButton
+          size="xs"
+          color="neutral"
+          variant="ghost"
+          data-testid="inspector-review-skills-revert"
+          @click="revert"
+        >
+          {{ t('skills.reviewQueue.revert') }}
+        </UButton>
+      </div>
+    </div>
   </InspectorSection>
 </template>

package/app/components/skills/ReviewSkillQueue.vue

@@ -0,0 +1,156 @@
+<script setup lang="ts">
+// The specialist review playbooks a REVIEW task queues onto its run: a Performance Review, a
+// Security Review, whatever the team authored. Stored on the task as `taskTypeFields
+// .reviewSkillIds` and resolved per dispatch onto the reviewer's own skills.
+//
+// Only the catalog's `review` group is offered. A skill declares what kind of work it does, so a
+// scaffolding playbook has no business in a picker whose job is to add review lenses; the store's
+// `reviewSkills` owns that filter and this component never re-derives it.
+//
+// ORDER is the point, which is why the selection renders as numbered badges rather than as a set:
+// the reviewer applies the queue in the order it was picked, so the person picking has to be able
+// to see (and change) that order. Clicking a badge removes it; picking again appends.
+//
+// Presentational and `v-model`-driven, like `FragmentSelector`: the caller owns where the list
+// lives and when it commits, so the create form and the inspector's editor bind the same
+// component and cannot offer a person two different pickers for one field.
+import { computed, ref } from 'vue'
+import { MAX_REVIEW_SKILLS } from '@cat-factory/contracts'
+import { useSkillsStore } from '~/stores/skills'
+
+const props = defineProps<{
+  /** The queued skill ids, in the order the reviewer applies them (`v-model`). */
+  modelValue: string[]
+}>()
+const emit = defineEmits<{ 'update:modelValue': [string[]] }>()
+
+const skills = useSkillsStore()
+const { t } = useI18n()
+
+const open = ref(false)
+
+const offered = computed(() => skills.reviewSkills)
+const selectedSet = computed(() => new Set(props.modelValue))
+/**
+ * Queued skills in QUEUE order (not catalog order), so the badges read as the run's sequence.
+ *
+ * NAMED from the whole catalog while only the `review` group is OFFERED: a skill regrouped after
+ * it was queued is still queued, and showing it by name is what lets someone recognise the entry
+ * they now have to drop. Only an id the catalog cannot resolve at all falls back to the raw id,
+ * which is exactly the entry that will fail the next dispatch.
+ */
+const queued = computed(() =>
+  props.modelValue.map(
+    (id) => skills.catalog.find((s) => s.id === id) ?? { id, name: id, description: '' },
+  ),
+)
+/** At the cap, unpicked rows stop being offered: the reviewer carries every queued skill's text. */
+const atCap = computed(() => props.modelValue.length >= MAX_REVIEW_SKILLS)
+
+function toggle(id: string) {
+  if (selectedSet.value.has(id)) {
+    emit(
+      'update:modelValue',
+      props.modelValue.filter((x) => x !== id),
+    )
+    return
+  }
+  if (atCap.value) return
+  emit('update:modelValue', [...props.modelValue, id])
+}
+</script>
+
+<template>
+  <div>
+    <div class="mb-1 flex items-center justify-between gap-2">
+      <span class="text-[11px] font-semibold uppercase tracking-wide text-slate-400">
+        {{ t('skills.reviewQueue.label') }}
+      </span>
+      <UPopover v-model:open="open" :content="{ align: 'end' }">
+        <UButton
+          size="xs"
+          variant="ghost"
+          color="neutral"
+          icon="i-lucide-plus"
+          trailing-icon="i-lucide-chevron-down"
+          data-testid="review-skill-add"
+        />
+
+        <template #content>
+          <div
+            class="flex max-h-[24rem] w-[min(24rem,92vw)] flex-col"
+            data-testid="review-skill-picker-panel"
+          >
+            <div class="min-h-0 flex-1 overflow-y-auto p-1">
+              <template v-if="offered.length">
+                <button
+                  v-for="s in offered"
+                  :key="s.id"
+                  type="button"
+                  class="flex w-full items-start gap-2 rounded px-2 py-1.5 text-start text-sm hover:bg-slate-800/60 disabled:cursor-not-allowed disabled:opacity-40"
+                  :class="selectedSet.has(s.id) ? 'text-slate-100' : 'text-slate-300'"
+                  :disabled="atCap && !selectedSet.has(s.id)"
+                  :aria-pressed="selectedSet.has(s.id)"
+                  :data-testid="`review-skill-option-${s.id}`"
+                  @click="toggle(s.id)"
+                >
+                  <UIcon
+                    :name="selectedSet.has(s.id) ? 'i-lucide-check' : 'i-lucide-plus'"
+                    class="mt-0.5 h-4 w-4 shrink-0"
+                    :class="selectedSet.has(s.id) ? 'text-primary-400' : 'text-slate-500'"
+                  />
+                  <span class="min-w-0 flex-1">
+                    <span class="block truncate">{{ s.name }}</span>
+                    <span class="block truncate text-[11px] text-slate-500">
+                      {{ s.description }}
+                    </span>
+                  </span>
+                </button>
+              </template>
+              <p v-else class="px-2 py-3 text-[12px] text-slate-500">
+                {{ t('skills.reviewQueue.pickerEmpty') }}
+              </p>
+            </div>
+
+            <p
+              v-if="atCap"
+              class="border-t border-slate-800 px-2 py-1.5 text-[11px] text-amber-400"
+            >
+              {{ t('skills.reviewQueue.capped', { max: MAX_REVIEW_SKILLS }) }}
+            </p>
+            <div class="flex justify-end border-t border-slate-800 p-1.5">
+              <UButton
+                size="xs"
+                color="neutral"
+                variant="soft"
+                data-testid="review-skill-picker-done"
+                @click="open = false"
+              >
+                {{ t('skills.reviewQueue.done') }}
+              </UButton>
+            </div>
+          </div>
+        </template>
+      </UPopover>
+    </div>
+    <div v-if="queued.length" class="flex flex-wrap gap-1">
+      <UBadge
+        v-for="(s, i) in queued"
+        :key="s.id"
+        color="primary"
+        variant="subtle"
+        size="sm"
+        class="cursor-pointer"
+        :title="s.description"
+        data-testid="review-skill-badge"
+        @click="toggle(s.id)"
+      >
+        <span class="me-1 tabular-nums text-slate-400">{{ i + 1 }}</span>
+        {{ s.name }}<UIcon name="i-lucide-x" class="ms-0.5 h-3 w-3" />
+      </UBadge>
+    </div>
+    <p v-else class="text-[11px] text-slate-500">
+      {{ t('skills.reviewQueue.hint') }}
+    </p>
+  </div>
+</template>

package/app/components/skills/SkillLibraryManager.vue

@@ -8,6 +8,7 @@
 import { computed, reactive, ref, watch } from 'vue'
 import type { GitHubAvailableRepo } from '~/types/domain'
 import { useSkillLibrary } from '~/stores/skillLibrary'
+import { SKILL_GROUP_LABEL_KEYS } from '~/utils/skills'
 import GitHubRepoSearchSelect from '~/components/github/GitHubRepoSearchSelect.vue'
 import RepoTreeBrowser from '~/components/github/RepoTreeBrowser.vue'
 
@@ -176,8 +177,19 @@ async function unlinkSource(id: string) {
         >
           <UIcon name="i-lucide-book-open-check" class="mt-0.5 h-4 w-4 shrink-0 text-sky-400" />
           <div class="min-w-0 flex-1">
-            <p class="truncate text-sm font-medium text-slate-100">{{ s.name }}</p>
+            <div class="flex items-center gap-2">
+              <p class="truncate text-sm font-medium text-slate-100">{{ s.name }}</p>
+              <UBadge color="neutral" variant="subtle" size="sm" class="shrink-0">
+                {{ t(SKILL_GROUP_LABEL_KEYS[s.group]) }}
+              </UBadge>
+            </div>
             <p class="text-xs text-slate-400">{{ s.description }}</p>
+            <!-- The manifest declared a group this build does not know (a typo, or a member
+                 retired since the sync). It is filed under Other, and saying which value was
+                 declared is what lets the author fix their frontmatter. -->
+            <p v-if="s.declaredGroup" class="mt-1 text-[11px] text-amber-400">
+              {{ t('skills.catalog.groupUnknown', { group: s.declaredGroup }) }}
+            </p>
             <p class="mt-1 flex flex-wrap gap-x-3 text-[11px] text-slate-500">
               <span v-if="s.resources.length">
                 {{ t('skills.catalog.resources', { count: s.resources.length }) }}

package/app/stores/skillLibrary.ts

@@ -49,7 +49,12 @@ function skillLibrarySetup(resolveAccountId: () => string | null) {
   /** Mirror the full catalog into the snapshot picker store as lightweight summaries. */
   function syncPicker() {
     useSkillsStore().hydrate(
-      catalog.value.map((s) => ({ id: s.id, name: s.name, description: s.description })),
+      catalog.value.map((s) => ({
+        id: s.id,
+        name: s.name,
+        description: s.description,
+        group: s.group,
+      })),
     )
   }
 

package/app/stores/skills.spec.ts

@@ -3,7 +3,12 @@ import { useSkillsStore } from '~/stores/skills'
 import { usePipelinesStore } from '~/stores/pipelines'
 import type { SkillSummary } from '~/types/domain'
 
-const summary = (id: string, name = id): SkillSummary => ({ id, name, description: `${name} desc` })
+const summary = (id: string, name = id, group: SkillSummary['group'] = 'other'): SkillSummary => ({
+  id,
+  name,
+  description: `${name} desc`,
+  group,
+})
 
 /**
  * The skill picker spans two stores: the snapshot-hydrated `useSkillsStore` (the catalog the
@@ -28,6 +33,27 @@ describe('skills picker store — snapshot-hydrated catalog', () => {
   })
 })
 
+describe('skills store — the review task’s queue offers only review skills', () => {
+  it('offers the review group in catalog order and nothing else', () => {
+    const skills = useSkillsStore()
+    skills.hydrate([
+      summary('sk_build', 'Scaffold a service', 'build'),
+      summary('sk_sec', 'Security review', 'review'),
+      summary('sk_perf', 'Performance review', 'review'),
+      summary('sk_loose', 'Uncategorised', 'other'),
+    ])
+    expect(skills.reviewSkills.map((s) => s.id)).toEqual(['sk_sec', 'sk_perf'])
+  })
+
+  it('offers nothing when the account has authored no review skills', () => {
+    // The ordinary state for an account whose catalog is all build playbooks. The picker renders
+    // its empty note from this; it must not fall back to offering the whole catalog.
+    const skills = useSkillsStore()
+    skills.hydrate([summary('sk_build', 'Scaffold a service', 'build')])
+    expect(skills.reviewSkills).toEqual([])
+  })
+})
+
 describe('pipelines store — per-step skill picker helpers', () => {
   it('sets, reads and clears a draft skill step’s skillId', () => {
     const pipelines = usePipelinesStore()

package/app/stores/skills.ts

@@ -1,12 +1,14 @@
 import { defineStore } from 'pinia'
-import { ref } from 'vue'
+import { computed, ref } from 'vue'
 import type { SkillSummary } from '~/types/domain'
+import { skillsInGroup } from '~/utils/skills'
 
 /**
  * The account's repo-sourced Claude Skills catalog (ADR 0024 slice 3),
  * hydrated from the workspace snapshot as lightweight `{ id, name, description }` summaries.
- * Drives the pipeline builder's per-step skill picker: a `skill` step binds its
- * `stepOptions.skillId` to one of these. Skills live in ONE tier (the account, shared across its
+ * Drives the pipeline builder's per-step skill picker (a `skill` step binds its
+ * `stepOptions.skillId` to one of these) and the review task's skill queue, which offers the
+ * `review` slice of the same catalog. Skills live in ONE tier (the account, shared across its
  * workspaces), so a snapshot hydrate is a straight replace — no per-board reset needed. The
  * account-settings management surface owns the full catalog + sources; it pushes its updated
  * summaries back here after a sync so the picker stays in step without a board reload.
@@ -14,9 +16,17 @@ import type { SkillSummary } from '~/types/domain'
 export const useSkillsStore = defineStore('skills', () => {
   const catalog = ref<SkillSummary[]>([])
 
+  /**
+   * The skills a REVIEW task may queue: the catalog's `review` group and nothing else. A skill is
+   * offered by what its manifest says it does, so a build or release-notes playbook never reaches
+   * a picker whose whole job is to add review lenses. Empty is the ordinary state (an account with
+   * no review skills authored yet), not a fault, and the picker says so rather than hiding.
+   */
+  const reviewSkills = computed(() => skillsInGroup(catalog.value, 'review'))
+
   function hydrate(list: SkillSummary[]) {
     catalog.value = list
   }
 
-  return { catalog, hydrate }
+  return { catalog, reviewSkills, hydrate }
 })

package/app/types/skills.ts

@@ -8,6 +8,7 @@
 // All wire shapes are sourced from @cat-factory/contracts (single source of truth).
 
 export type {
+  SkillGroup,
   SkillResource,
   AccountSkill,
   SkillSource,

package/app/utils/skills.spec.ts

@@ -0,0 +1,51 @@
+import { describe, expect, it } from 'vitest'
+import { SKILL_GROUPS } from '@cat-factory/contracts'
+import {
+  SKILL_GROUP_ICONS,
+  SKILL_GROUP_LABEL_KEYS,
+  SKILL_GROUP_ORDER,
+  skillsInGroup,
+} from '~/utils/skills'
+import type { SkillSummary } from '~/types/domain'
+
+// The group maps are what a picker renders a shelf from, and the vocabulary they cover lives in
+// contracts. What is asserted here is the RELATION that has to hold (every member of the shared
+// vocabulary is covered exactly once), never a hand-written count: adding a group must fail with
+// its name rather than teaching the next person to re-pin a number.
+
+const skill = (id: string, group: SkillSummary['group']): SkillSummary => ({
+  id,
+  name: id,
+  description: `${id} desc`,
+  group,
+})
+
+describe('skill group presentation', () => {
+  it('gives every group in the shared vocabulary a label key and an icon', () => {
+    for (const group of SKILL_GROUPS) {
+      expect(SKILL_GROUP_LABEL_KEYS[group]).toMatch(/^skills\.groups\./)
+      expect(SKILL_GROUP_ICONS[group]).toMatch(/^i-lucide-/)
+    }
+  })
+
+  it('orders every group exactly once, with the unclassified shelf last', () => {
+    expect([...SKILL_GROUP_ORDER].sort()).toEqual([...SKILL_GROUPS].sort())
+    expect(SKILL_GROUP_ORDER.at(-1)).toBe('other')
+  })
+})
+
+describe('skillsInGroup', () => {
+  it('keeps catalog order and admits only the asked-for group', () => {
+    const catalog = [
+      skill('sk_build', 'build'),
+      skill('sk_sec', 'review'),
+      skill('sk_other', 'other'),
+      skill('sk_perf', 'review'),
+    ]
+    expect(skillsInGroup(catalog, 'review').map((s) => s.id)).toEqual(['sk_sec', 'sk_perf'])
+    // A skill whose manifest declared an unknown group arrives already normalized to `other`, so
+    // it is offered on the unclassified shelf rather than everywhere or nowhere.
+    expect(skillsInGroup(catalog, 'other').map((s) => s.id)).toEqual(['sk_other'])
+    expect(skillsInGroup(catalog, 'test')).toEqual([])
+  })
+})

package/app/utils/skills.ts

@@ -0,0 +1,58 @@
+import { SKILL_GROUPS } from '@cat-factory/contracts'
+import type { SkillGroup, SkillSummary } from '~/types/domain'
+
+// ---------------------------------------------------------------------------
+// Shared presentation and filtering for the account's Claude Skills catalog.
+//
+// A skill declares a GROUP in its `SKILL.md` frontmatter (what kind of work its playbook does),
+// and the surfaces that offer skills each want a different slice of the catalog: the review
+// task's queue offers the `review` group, the library manager lists everything grouped. Both the
+// label lookup and the filter live here, once, rather than in each component.
+//
+// The label map is an exhaustive `Record<SkillGroup, string>`, so adding a member to the contracts
+// vocabulary fails the typecheck here instead of rendering a raw id (or nothing) in a picker.
+// ---------------------------------------------------------------------------
+
+/** i18n catalog key per group. Prose, so keys rather than the constants VCS labels use. */
+export const SKILL_GROUP_LABEL_KEYS: Record<SkillGroup, string> = {
+  build: 'skills.groups.build',
+  review: 'skills.groups.review',
+  test: 'skills.groups.test',
+  write: 'skills.groups.write',
+  plan: 'skills.groups.plan',
+  operate: 'skills.groups.operate',
+  other: 'skills.groups.other',
+}
+
+/** Icon per group, so a picker row reads as its shelf at a glance. */
+export const SKILL_GROUP_ICONS: Record<SkillGroup, string> = {
+  build: 'i-lucide-hammer',
+  review: 'i-lucide-clipboard-check',
+  test: 'i-lucide-flask-conical',
+  write: 'i-lucide-pen-line',
+  plan: 'i-lucide-map',
+  operate: 'i-lucide-server-cog',
+  other: 'i-lucide-book-open-check',
+}
+
+/**
+ * Display order for a grouped listing: the delivery loop first, `other` last. Derived FROM the
+ * contracts vocabulary rather than restated, so a member added there appears (before `other`)
+ * instead of silently vanishing from a listing that hard-coded the order.
+ */
+export const SKILL_GROUP_ORDER: readonly SkillGroup[] = [
+  ...SKILL_GROUPS.filter((g) => g !== 'other'),
+  'other',
+]
+
+/**
+ * The catalog entries a surface offering `group` may show, in catalog order.
+ *
+ * Filtering on the group the BACKEND already normalized: a summary's group is narrowed to the
+ * wire vocabulary before it reaches the snapshot, so nothing here re-derives a classification the
+ * catalog owns, and a skill whose manifest declared an unknown group is offered under `other`
+ * rather than being offered everywhere or nowhere.
+ */
+export function skillsInGroup(catalog: readonly SkillSummary[], group: SkillGroup): SkillSummary[] {
+  return catalog.filter((skill) => skill.group === group)
+}

package/i18n/locales/de.json

@@ -7380,7 +7380,8 @@
       "title": "Synchronisierte Skills",
       "empty": "Noch keine Skills synchronisiert. Verknüpfe unten eine Repo-Quelle, um ihre Skill-Ordner zu importieren.",
       "resources": "{count} Ressourcen",
-      "pinned": "fixiert auf {commit}"
+      "pinned": "fixiert auf {commit}",
+      "groupUnknown": "Gibt die Gruppe „{group}“ an, die diese Version nicht kennt; sie wird unter Sonstige geführt."
     },
     "sources": {
       "title": "Repo-Quellen",
@@ -7417,6 +7418,24 @@
       "checkSourceFailed": "Quelle konnte nicht geprüft werden",
       "sourceUnlinked": "Quelle getrennt",
       "unlinkSourceFailed": "Quelle konnte nicht getrennt werden"
+    },
+    "groups": {
+      "build": "Bauen",
+      "review": "Review",
+      "test": "Testen",
+      "write": "Schreiben",
+      "plan": "Planen",
+      "operate": "Betrieb",
+      "other": "Sonstige"
+    },
+    "reviewQueue": {
+      "label": "Review-Skills",
+      "hint": "Stelle spezialisierte Review-Playbooks aus deiner Skill-Bibliothek in eine Warteschlange. Der Reviewer wendet sie in der gewählten Reihenfolge an.",
+      "pickerEmpty": "Keine Review-Skills im Katalog. Ergänze group: review in der SKILL.md eines Skills, damit er hier erscheint.",
+      "capped": "Ein Review führt höchstens {max} Skills aus.",
+      "done": "Fertig",
+      "save": "Speichern",
+      "revert": "Zurücksetzen"
     }
   },
   "merge": {

package/i18n/locales/en.json

@@ -7639,7 +7639,8 @@
       "title": "Synced skills",
       "empty": "No skills synced yet. Link a repo source below to import its skill folders.",
       "resources": "{count} resources",
-      "pinned": "pinned {commit}"
+      "pinned": "pinned {commit}",
+      "groupUnknown": "Declares the group “{group}”, which this version does not know, so it is filed under Other."
     },
     "sources": {
       "title": "Repo sources",
@@ -7676,6 +7677,24 @@
       "checkSourceFailed": "Could not check source",
       "sourceUnlinked": "Source unlinked",
       "unlinkSourceFailed": "Could not unlink source"
+    },
+    "groups": {
+      "build": "Build",
+      "review": "Review",
+      "test": "Test",
+      "write": "Write",
+      "plan": "Plan",
+      "operate": "Operate",
+      "other": "Other"
+    },
+    "reviewQueue": {
+      "label": "Review skills",
+      "hint": "Queue specialist review playbooks from your skill library. The reviewer applies them in the order you pick.",
+      "pickerEmpty": "No review skills in your catalog. Add group: review to a skill’s SKILL.md to offer it here.",
+      "capped": "A review carries at most {max} skills.",
+      "done": "Done",
+      "save": "Save",
+      "revert": "Revert"
     }
   },
   "merge": {

package/i18n/locales/es.json

@@ -7380,7 +7380,8 @@
       "title": "Habilidades sincronizadas",
       "empty": "Aún no hay habilidades sincronizadas. Vincula una fuente de repositorio abajo para importar sus carpetas de habilidades.",
       "resources": "{count} recursos",
-      "pinned": "fijada en {commit}"
+      "pinned": "fijada en {commit}",
+      "groupUnknown": "Declara el grupo «{group}», que esta versión no conoce, así que se archiva en Otras."
     },
     "sources": {
       "title": "Fuentes de repositorio",
@@ -7417,6 +7418,24 @@
       "checkSourceFailed": "No se pudo comprobar la fuente",
       "sourceUnlinked": "Fuente desvinculada",
       "unlinkSourceFailed": "No se pudo desvincular la fuente"
+    },
+    "groups": {
+      "build": "Construir",
+      "review": "Revisar",
+      "test": "Probar",
+      "write": "Escribir",
+      "plan": "Planificar",
+      "operate": "Operar",
+      "other": "Otras"
+    },
+    "reviewQueue": {
+      "label": "Habilidades de revisión",
+      "hint": "Pon en cola manuales de revisión especializados de tu biblioteca de habilidades. El revisor los aplica en el orden que elijas.",
+      "pickerEmpty": "No hay habilidades de revisión en tu catálogo. Añade group: review al SKILL.md de una habilidad para ofrecerla aquí.",
+      "capped": "Una revisión lleva como máximo {max} habilidades.",
+      "done": "Listo",
+      "save": "Guardar",
+      "revert": "Descartar"
     }
   },
   "merge": {

package/i18n/locales/fr.json

@@ -7380,7 +7380,8 @@
       "title": "Compétences synchronisées",
       "empty": "Aucune compétence synchronisée pour l'instant. Reliez une source de dépôt ci-dessous pour importer ses dossiers de compétences.",
       "resources": "{count} ressources",
-      "pinned": "épinglée sur {commit}"
+      "pinned": "épinglée sur {commit}",
+      "groupUnknown": "Déclare le groupe « {group} », inconnu de cette version : la compétence est classée dans Autres."
     },
     "sources": {
       "title": "Sources de dépôt",
@@ -7417,6 +7418,24 @@
       "checkSourceFailed": "Impossible de vérifier la source",
       "sourceUnlinked": "Source dissociée",
       "unlinkSourceFailed": "Impossible de dissocier la source"
+    },
+    "groups": {
+      "build": "Construire",
+      "review": "Relire",
+      "test": "Tester",
+      "write": "Rédiger",
+      "plan": "Planifier",
+      "operate": "Exploiter",
+      "other": "Autres"
+    },
+    "reviewQueue": {
+      "label": "Compétences de relecture",
+      "hint": "Mettez en file des guides de relecture spécialisés issus de votre bibliothèque. Le relecteur les applique dans l’ordre choisi.",
+      "pickerEmpty": "Aucune compétence de relecture dans votre catalogue. Ajoutez group: review au SKILL.md d’une compétence pour la proposer ici.",
+      "capped": "Une relecture porte au maximum {max} compétences.",
+      "done": "Terminé",
+      "save": "Enregistrer",
+      "revert": "Rétablir"
     }
   },
   "merge": {

package/i18n/locales/he.json

@@ -7380,7 +7380,8 @@
       "title": "כישורים מסונכרנים",
       "empty": "עדיין אין כישורים מסונכרנים. קישר מקור מאגר למטה כדי לייבא את תיקיות הכישורים שלו.",
       "resources": "{count} משאבים",
-      "pinned": "מקובע ל-{commit}"
+      "pinned": "מקובע ל-{commit}",
+      "groupUnknown": "מצהיר על הקבוצה „{group}”, שגרסה זו אינה מכירה, ולכן הוא מסווג תחת אחר."
     },
     "sources": {
       "title": "מקורות מאגר",
@@ -7417,6 +7418,24 @@
       "checkSourceFailed": "לא ניתן לבדוק את המקור",
       "sourceUnlinked": "קישור המקור בוטל",
       "unlinkSourceFailed": "לא ניתן לבטל את קישור המקור"
+    },
+    "groups": {
+      "build": "בנייה",
+      "review": "סקירה",
+      "test": "בדיקה",
+      "write": "כתיבה",
+      "plan": "תכנון",
+      "operate": "תפעול",
+      "other": "אחר"
+    },
+    "reviewQueue": {
+      "label": "כישורי סקירה",
+      "hint": "הוסיפו לתור ספרי סקירה ייעודיים מספריית הכישורים. הסוקר מיישם אותם לפי סדר הבחירה.",
+      "pickerEmpty": "אין כישורי סקירה בקטלוג. הוסיפו group: review לקובץ SKILL.md של כישור כדי להציע אותו כאן.",
+      "capped": "סקירה נושאת {max} כישורים לכל היותר.",
+      "done": "סיום",
+      "save": "שמירה",
+      "revert": "שחזור"
     }
   },
   "merge": {

package/i18n/locales/it.json

@@ -7380,7 +7380,8 @@
       "title": "Competenze sincronizzate",
       "empty": "Nessuna competenza ancora sincronizzata. Collega una fonte di repository qui sotto per importare le sue cartelle di competenze.",
       "resources": "{count} risorse",
-      "pinned": "fissata su {commit}"
+      "pinned": "fissata su {commit}",
+      "groupUnknown": "Dichiara il gruppo «{group}», che questa versione non conosce, quindi è archiviata in Altre."
     },
     "sources": {
       "title": "Fonti di repository",
@@ -7417,6 +7418,24 @@
       "checkSourceFailed": "Impossibile controllare la fonte",
       "sourceUnlinked": "Fonte scollegata",
       "unlinkSourceFailed": "Impossibile scollegare la fonte"
+    },
+    "groups": {
+      "build": "Costruire",
+      "review": "Revisionare",
+      "test": "Testare",
+      "write": "Scrivere",
+      "plan": "Pianificare",
+      "operate": "Operare",
+      "other": "Altre"
+    },
+    "reviewQueue": {
+      "label": "Competenze di revisione",
+      "hint": "Metti in coda manuali di revisione specialistici dalla tua libreria. Il revisore li applica nell’ordine scelto.",
+      "pickerEmpty": "Nessuna competenza di revisione nel catalogo. Aggiungi group: review al SKILL.md di una competenza per proporla qui.",
+      "capped": "Una revisione porta al massimo {max} competenze.",
+      "done": "Fatto",
+      "save": "Salva",
+      "revert": "Ripristina"
     }
   },
   "merge": {

package/i18n/locales/ja.json

@@ -7380,7 +7380,8 @@
       "title": "同期済みスキル",
       "empty": "まだスキルが同期されていません。下のリポジトリソースをリンクしてスキルフォルダーをインポートしてください。",
       "resources": "リソース {count} 件",
-      "pinned": "{commit} に固定"
+      "pinned": "{commit} に固定",
+      "groupUnknown": "このバージョンが知らないグループ「{group}」を宣言しているため、その他に分類しています。"
     },
     "sources": {
       "title": "リポジトリソース",
@@ -7417,6 +7418,24 @@
       "checkSourceFailed": "ソースを確認できませんでした",
       "sourceUnlinked": "ソースのリンクを解除しました",
       "unlinkSourceFailed": "ソースのリンクを解除できませんでした"
+    },
+    "groups": {
+      "build": "ビルド",
+      "review": "レビュー",
+      "test": "テスト",
+      "write": "ライティング",
+      "plan": "計画",
+      "operate": "運用",
+      "other": "その他"
+    },
+    "reviewQueue": {
+      "label": "レビュースキル",
+      "hint": "スキルライブラリから専門的なレビュー手順書をキューに追加します。レビュアーは選んだ順に適用します。",
+      "pickerEmpty": "カタログにレビュースキルがありません。スキルの SKILL.md に group: review を追加するとここに表示されます。",
+      "capped": "1 回のレビューで扱えるスキルは最大 {max} 件です。",
+      "done": "完了",
+      "save": "保存",
+      "revert": "元に戻す"
     }
   },
   "merge": {

package/i18n/locales/pl.json

@@ -7380,7 +7380,8 @@
       "title": "Zsynchronizowane umiejętności",
       "empty": "Nie zsynchronizowano jeszcze żadnych umiejętności. Połącz poniżej źródło repozytorium, aby zaimportować jego foldery umiejętności.",
       "resources": "zasoby: {count}",
-      "pinned": "przypięta do {commit}"
+      "pinned": "przypięta do {commit}",
+      "groupUnknown": "Deklaruje grupę „{group}”, której ta wersja nie zna, więc trafia do Inne."
     },
     "sources": {
       "title": "Źródła repozytoriów",
@@ -7417,6 +7418,24 @@
       "checkSourceFailed": "Nie udało się sprawdzić źródła",
       "sourceUnlinked": "Źródło odłączone",
       "unlinkSourceFailed": "Nie udało się odłączyć źródła"
+    },
+    "groups": {
+      "build": "Budowanie",
+      "review": "Przegląd",
+      "test": "Testowanie",
+      "write": "Pisanie",
+      "plan": "Planowanie",
+      "operate": "Utrzymanie",
+      "other": "Inne"
+    },
+    "reviewQueue": {
+      "label": "Umiejętności przeglądu",
+      "hint": "Dodaj do kolejki wyspecjalizowane podręczniki przeglądu z biblioteki umiejętności. Recenzent zastosuje je w wybranej kolejności.",
+      "pickerEmpty": "Brak umiejętności przeglądu w katalogu. Dodaj group: review w pliku SKILL.md umiejętności, aby pojawiła się tutaj.",
+      "capped": "Jeden przegląd obejmuje najwyżej {max} umiejętności.",
+      "done": "Gotowe",
+      "save": "Zapisz",
+      "revert": "Przywróć"
     }
   },
   "merge": {

package/i18n/locales/tr.json

@@ -7380,7 +7380,8 @@
       "title": "Senkronize beceriler",
       "empty": "Henüz senkronize edilmiş beceri yok. Beceri klasörlerini içe aktarmak için aşağıda bir depo kaynağı bağlayın.",
       "resources": "{count} kaynak",
-      "pinned": "{commit} üzerine sabitlendi"
+      "pinned": "{commit} üzerine sabitlendi",
+      "groupUnknown": "Bu sürümün bilmediği “{group}” grubunu bildiriyor, bu yüzden Diğer altında listeleniyor."
     },
     "sources": {
       "title": "Depo kaynakları",
@@ -7417,6 +7418,24 @@
       "checkSourceFailed": "Kaynak denetlenemedi",
       "sourceUnlinked": "Kaynağın bağlantısı kaldırıldı",
       "unlinkSourceFailed": "Kaynağın bağlantısı kaldırılamadı"
+    },
+    "groups": {
+      "build": "Geliştirme",
+      "review": "İnceleme",
+      "test": "Test",
+      "write": "Yazma",
+      "plan": "Planlama",
+      "operate": "İşletme",
+      "other": "Diğer"
+    },
+    "reviewQueue": {
+      "label": "İnceleme becerileri",
+      "hint": "Beceri kitaplığınızdan uzmanlaşmış inceleme kılavuzlarını sıraya alın. İnceleyici bunları seçtiğiniz sırayla uygular.",
+      "pickerEmpty": "Katalogda inceleme becerisi yok. Bir becerinin SKILL.md dosyasına group: review ekleyin.",
+      "capped": "Bir inceleme en fazla {max} beceri taşır.",
+      "done": "Tamam",
+      "save": "Kaydet",
+      "revert": "Geri al"
     }
   },
   "merge": {

package/i18n/locales/uk.json

@@ -7380,7 +7380,8 @@
       "title": "Синхронізовані навички",
       "empty": "Ще немає синхронізованих навичок. Пов'яжіть джерело репозиторію нижче, щоб імпортувати його папки навичок.",
       "resources": "ресурсів: {count}",
-      "pinned": "закріплено на {commit}"
+      "pinned": "закріплено на {commit}",
+      "groupUnknown": "Оголошує групу «{group}», якої ця версія не знає, тож навичку віднесено до Інше."
     },
     "sources": {
       "title": "Джерела репозиторіїв",
@@ -7417,6 +7418,24 @@
       "checkSourceFailed": "Не вдалося перевірити джерело",
       "sourceUnlinked": "Джерело від'єднано",
       "unlinkSourceFailed": "Не вдалося від'єднати джерело"
+    },
+    "groups": {
+      "build": "Розробка",
+      "review": "Рецензування",
+      "test": "Тестування",
+      "write": "Написання",
+      "plan": "Планування",
+      "operate": "Експлуатація",
+      "other": "Інше"
+    },
+    "reviewQueue": {
+      "label": "Навички рецензування",
+      "hint": "Додайте до черги спеціалізовані посібники рецензування з бібліотеки навичок. Рецензент застосує їх у вибраному порядку.",
+      "pickerEmpty": "У каталозі немає навичок рецензування. Додайте group: review у SKILL.md навички, щоб вона зʼявилася тут.",
+      "capped": "Одне рецензування несе щонайбільше {max} навичок.",
+      "done": "Готово",
+      "save": "Зберегти",
+      "revert": "Скасувати зміни"
     }
   },
   "merge": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cat-factory/app",
-  "version": "0.281.0",
+  "version": "0.282.0",
   "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",
@@ -40,7 +40,7 @@
     "valibot": "^1.4.2",
     "vue": "3.5.41",
     "wretch": "^3.0.9",
-    "@cat-factory/contracts": "0.322.0"
+    "@cat-factory/contracts": "0.323.0"
   },
   "devDependencies": {
     "@toad-contracts/testing": "0.3.2",