@cat-factory/app 0.255.1 → 0.256.1

package/README.md

@@ -286,9 +286,13 @@ browser older than a new member, a row older than a retired one).
 Purpose is filtered by three predicates in `@cat-factory/contracts`, and the difference between
 the first two is the point:
 
-- `purposeSuggestsAgentCategory` is **relevance**: what the palette OFFERS. Opinionated (a
+- `purposeSuggestsAgentKind` is **relevance**: what the palette OFFERS. Opinionated (a
   review pipeline designs nothing; a planning pipeline has no pull request to gate), because a
-  wrong guess costs one purpose switch.
+  wrong guess costs one purpose switch. It reads the kind's `category` through
+  `purposeSuggestsAgentCategory` and then the kind's OWN `presentation.purposes`, and the two
+  INTERSECT: a declaration may only hide more, never buy a kind back into a purpose its section
+  is not offered to, which is what keeps relevance inside compatibility whatever a deployment
+  declares.
 - `purposeAllowsAgentCategory` is **compatibility**: what the builder will SAVE. It states only
   what is contradictory (a pipeline that writes no code carrying an implementation step) and
   drives the draft's conflict warning.
@@ -311,6 +315,19 @@ it that way: the palette may hide what the save gate tolerates, so tightening th
 never turns a stored pipeline into one its own editor refuses, but offering a kind the save gate
 then rejects would be a dead end with the refusal arriving after the work.
 
+**A category is a shelf label, not a statement of what a kind does**, which is why relevance is
+asked of the KIND. Keeping `docs` for a `review` pipeline so the Domain Rules Reviewer survives
+also handed it the two kinds that WRITE documentation into the repo, and `document` and `research`
+had identical rows, so moving the dial between them narrowed nothing at all. A kind that belongs
+to one use-case says so in `presentation.purposes` and leaves a section its siblings stay in; the
+section keeps deciding for every kind that declares nothing, which is the normal case and the one
+a deployment-registered kind falls into for free. Declare it only to opt OUT: it can never widen,
+and a list naming only purposes this build cannot name is read as no declaration at all rather
+than as excluding everything, the same default-open reading the unknown `purpose` gets. An EMPTY
+list is refused at registration instead (`agentPresentationSchema`, and `catalog.spec.ts` for the
+static half valibot never parses): the reader cannot tell one from declaring nothing, so it would
+offer the kind everywhere its section is offered, which is the inverse of what writing it means.
+
 **Each hint counts what relaxing THAT dial alone would reveal**, which is why each reduction is one
 function (`utils/agentPalette.ts` for the catalog, `utils/pipelineLibrary.ts` for the library)
 rather than chained filters at the call site. Chaining them

package/app/modular/agent-kinds.ts

@@ -27,6 +27,9 @@ export function customKindToArchetype(kind: CustomAgentKind): AgentArchetype {
     color: p.color,
     description: p.description,
     ...(p.category ? { category: p.category } : {}),
+    // Carried verbatim, INCLUDING a list this build cannot fully name: `purposeSuggestsAgentKind`
+    // owns the reading of an unrecognised member, so filtering here would fork that rule.
+    ...(p.purposes?.length ? { purposes: p.purposes } : {}),
     // A kind that declares no tier is left WITHOUT one rather than stamped with the default
     // here, so the single fallback stays in `agentTierVisibleAt` — filling it in at the
     // projection would fork the rule the moment the default changes.

package/app/modular/capabilities.spec.ts

@@ -70,6 +70,55 @@ describe('buildWorkspaceCapabilitiesManifest', () => {
     expect(workspaceCapabilitiesVersion([], [])).not.toBe(base)
   })
 
+  it('changes the version for EVERY declared field, including the ones nothing renders', () => {
+    // The signature covers the whole entry rather than a list of fields somebody kept in step,
+    // because an omitted one is not a cosmetic miss: `hydrateCapabilities` no-ops on an unchanged
+    // version, so an open tab keeps filtering its palette on the declaration the backend just
+    // replaced. Asserted field by field over the ones that steer the builder rather than the
+    // label, which is the class the old field list kept missing.
+    const base = workspaceCapabilitiesVersion([kind()], [])
+    expect(workspaceCapabilitiesVersion([kind({ purposes: ['review'] })], [])).not.toBe(base)
+    expect(workspaceCapabilitiesVersion([kind({ category: 'docs' })], [])).not.toBe(base)
+    expect(workspaceCapabilitiesVersion([kind({ tier: 'basic' })], [])).not.toBe(base)
+    expect(workspaceCapabilitiesVersion([{ ...kind(), container: false }], [])).not.toBe(base)
+    expect(workspaceCapabilitiesVersion([{ ...kind(), binaryOutput: true }], [])).not.toBe(base)
+    expect(
+      workspaceCapabilitiesVersion([{ ...kind(), companionTargets: ['coder' as AgentKind] }], []),
+    ).not.toBe(base)
+    // And a purposes list is ORDER-bearing content, not a set: two spellings of the same
+    // declaration are two declarations, so re-signing is the honest answer over guessing.
+    expect(workspaceCapabilitiesVersion([kind({ purposes: ['review', 'build'] })], [])).not.toBe(
+      workspaceCapabilitiesVersion([kind({ purposes: ['build', 'review'] })], []),
+    )
+  })
+
+  it('ignores the KEY ORDER a snapshot happened to serialize with', () => {
+    // The whole point of canonicalizing rather than hashing the raw JSON: a re-serialization
+    // that reorders keys is the same catalog, and re-swapping the manifest for it would
+    // invalidate every `agentKindMeta` consumer for nothing.
+    const ordered: CustomAgentKind = {
+      kind: 'acme-audit' as AgentKind,
+      container: true,
+      presentation: { label: 'Audit', icon: 'i-lucide-shield', color: '#fff', description: 'd' },
+    }
+    const reordered: CustomAgentKind = {
+      presentation: { description: 'd', color: '#fff', icon: 'i-lucide-shield', label: 'Audit' },
+      container: true,
+      kind: 'acme-audit' as AgentKind,
+    }
+    expect(workspaceCapabilitiesVersion([reordered], [])).toBe(
+      workspaceCapabilitiesVersion([ordered], []),
+    )
+  })
+
+  it('reads an explicitly-undefined field as an absent one', () => {
+    // A projection that spreads a conditional field (`...(x ? { x } : {})`) and one that assigns
+    // `x: undefined` describe the same catalog, so they must not hash differently.
+    expect(workspaceCapabilitiesVersion([{ ...kind(), binaryOutput: undefined }], [])).toBe(
+      workspaceCapabilitiesVersion([kind()], []),
+    )
+  })
+
   it('changes the version when a task-type field, its fields, or the set differs', () => {
     const base = workspaceCapabilitiesVersion([], [taskType()])
     expect(workspaceCapabilitiesVersion([], [taskType({ label: 'Renamed' })])).not.toBe(base)

package/app/modular/capabilities.ts

@@ -19,43 +19,46 @@ import type { AppSlots } from './slots'
 /** The stable id for the per-workspace capability manifest built from the snapshot. */
 export const WORKSPACE_CAPABILITIES_MANIFEST_ID = 'cat-factory:workspace-capabilities'
 
+/**
+ * Every key of `value`, recursively, in sorted order: the canonical form
+ * {@link workspaceCapabilitiesVersion} signs. Arrays keep their order (a capability list's order is
+ * content: it is the order the palette and the picker render in); objects lose theirs, so a
+ * re-serialization with reordered keys can't spuriously differ.
+ */
+function canonicalize(value: unknown): unknown {
+  if (Array.isArray(value)) return value.map(canonicalize)
+  if (value === null || typeof value !== 'object') return value
+  return Object.fromEntries(
+    Object.entries(value)
+      .filter(([, entry]) => entry !== undefined)
+      .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+      .map(([key, entry]) => [key, canonicalize(entry)]),
+  )
+}
+
 /**
  * A deterministic, key-order-independent content signature covering BOTH capability lists, used as
  * the manifest `version`. The workspace snapshot re-delivers the SAME deployment capabilities on
  * every board-event refresh (a full `workspace.refresh()` re-hydrates each time), so a
- * content-derived version lets each store skip re-projecting an UNCHANGED catalog — otherwise every
+ * content-derived version lets each store skip re-projecting an UNCHANGED catalog: otherwise every
  * refresh would replace its read-model and needlessly invalidate every `agentKindMeta` /
  * `taskTypeMeta` consumer. It still changes (and swaps wholesale) when a different workspace's
- * capabilities genuinely differ. Serialized as fixed-order tuples of only the fields that affect
- * display/pairing, so a re-serialization with reordered object keys can't spuriously differ.
+ * capabilities genuinely differ.
+ *
+ * Signs the WHOLE entry, canonicalized, rather than a hand-listed tuple of the fields that seemed
+ * to matter. The two mistakes are not symmetric: folding in a field nothing renders costs one
+ * re-projection nobody sees, while OMITTING one costs correctness, because `hydrateCapabilities`
+ * short-circuits on an unchanged version and the store then keeps serving the PREVIOUS declaration
+ * until something else swaps the manifest. A field list drifts silently into that: it was missing
+ * `tier` and `binaryOutput` before `purposes` was added to it, so a backend that re-declared any of
+ * the three reached an open tab as the catalog it had replaced. There is nothing volatile in either
+ * shape (no timestamps, no ids minted per request), so signing all of it costs nothing.
  */
 export function workspaceCapabilitiesVersion(
   kinds: readonly CustomAgentKind[],
   taskTypes: readonly CustomTaskType[],
 ): string {
-  return JSON.stringify([
-    kinds.map((k) => [
-      k.kind,
-      k.container,
-      k.presentation.label,
-      k.presentation.icon,
-      k.presentation.color,
-      k.presentation.description,
-      k.presentation.category ?? null,
-      k.presentation.resultView ?? null,
-    ]),
-    taskTypes.map((t) => [
-      t.taskType,
-      t.presentation.label,
-      t.presentation.icon,
-      t.presentation.color,
-      t.presentation.description,
-      t.defaultPipelineId ?? null,
-      t.formPanel ?? null,
-      // The descriptor list affects the create-form, so fold its shape into the signature too.
-      (t.fields ?? []).map((f) => [f.key, f.type, f.label, f.required ?? false]),
-    ]),
-  ])
+  return JSON.stringify([canonicalize(kinds), canonicalize(taskTypes)])
 }
 
 /**

package/app/types/domain.ts

@@ -117,7 +117,7 @@ export type {
   PreviewStatus,
 } from '@cat-factory/contracts'
 
-import type { AgentCategory, AgentKind, AgentTier } from '@cat-factory/contracts'
+import type { AgentCategory, AgentKind, AgentTier, PipelinePurpose } from '@cat-factory/contracts'
 
 // The document-kind list + the per-kind field descriptors are runtime values (used to render
 // the picker and the conditional per-kind inputs), so they are re-exported as values — the
@@ -135,6 +135,12 @@ export interface AgentArchetype {
   description: string
   /** Palette category this archetype is grouped under. Absent ⇒ ungrouped/system kind. */
   category?: AgentCategory
+  /**
+   * The pipeline PURPOSES the palette offers this kind to, WITHIN the ones its {@link category}
+   * already admits (`purposeSuggestsAgentKind`). Absent ⇒ the category alone decides, which is
+   * the normal case: declare this only to opt OUT of a purpose the category would admit.
+   */
+  purposes?: readonly PipelinePurpose[]
   /**
    * How specialist this kind is — the tier the palette / model-preset override list filter on
    * (`basic` shows only basic kinds, `intermediate` adds those, `advanced` shows everything).

package/app/utils/agentPalette.spec.ts

@@ -1,4 +1,5 @@
 import { describe, expect, it } from 'vitest'
+import type { PipelinePurpose } from '@cat-factory/contracts'
 import type { AgentArchetype } from '~/types/domain'
 import { groupAgentPalette, narrowAgentPalette } from '~/utils/agentPalette'
 
@@ -6,6 +7,7 @@ const archetype = (
   kind: string,
   category?: AgentArchetype['category'],
   tier?: AgentArchetype['tier'],
+  purposes?: AgentArchetype['purposes'],
 ): AgentArchetype => ({
   kind: kind as AgentArchetype['kind'],
   label: kind,
@@ -14,6 +16,7 @@ const archetype = (
   description: kind,
   ...(category ? { category } : {}),
   ...(tier ? { tier } : {}),
+  ...(purposes ? { purposes } : {}),
 })
 
 // Spread across both dials on purpose: every combination of relevant/irrelevant to a `planning`
@@ -100,6 +103,33 @@ describe('narrowAgentPalette', () => {
     expect(hiddenByBoth).toBe(1)
   })
 
+  it('narrows WITHIN a category when a kind declares the purposes it is for', () => {
+    // The reason relevance is asked of the KIND: a category is a shelf label, so `documenter` and
+    // `doc-reviewer` sit on the same shelf while only one of them belongs in a pipeline that
+    // reviews someone else's pull request. Both dials still apply to the declaring kind.
+    const catalog = [
+      archetype('documenter', 'docs', 'basic', ['build', 'document']),
+      archetype('doc-reviewer', 'docs', 'basic', ['build', 'review']),
+      archetype('house-style', 'docs', 'basic'),
+    ]
+    const offered = (purpose: PipelinePurpose) =>
+      narrowAgentPalette(catalog, purpose, 'advanced').offered.map((a) => a.kind)
+    expect(offered('review')).toEqual(['doc-reviewer', 'house-style'])
+    expect(offered('document')).toEqual(['documenter', 'house-style'])
+    // `planning` drops the whole `docs` category, and the declarations do not override that for
+    // the kinds that named it: a declared list is the kind's own answer, not an exemption.
+    expect(offered('planning')).toEqual([])
+    expect(narrowAgentPalette(catalog, 'review', 'advanced').hiddenByPurpose).toBe(1)
+  })
+
+  it('falls back to the category when a declared list names nothing this build knows', () => {
+    // The mirror of the unknown-purpose rule: a kind whose entire list was retired has told this
+    // build nothing, so its section decides rather than the kind vanishing from every palette.
+    const stale = archetype('acme-doc', 'docs', 'basic', ['acme-migration' as never])
+    expect(narrowAgentPalette([stale], 'document', 'advanced').offered).toEqual([stale])
+    expect(narrowAgentPalette([stale], 'planning', 'advanced').offered).toEqual([])
+  })
+
   it('keeps a purpose this build does not recognise from narrowing anything', () => {
     // A stored `purpose` from a build that shipped a member this one has not (or has retired):
     // unknown is not a licence to guess, so the palette offers what the tier admits and says so.

package/app/utils/agentPalette.ts

@@ -2,7 +2,7 @@ import {
   type AgentTier,
   agentTierVisibleAt,
   type PipelinePurpose,
-  purposeSuggestsAgentCategory,
+  purposeSuggestsAgentKind,
 } from '@cat-factory/contracts'
 import type { AgentArchetype } from '~/types/domain'
 
@@ -36,16 +36,17 @@ export interface NarrowedAgentPalette<T> {
  * Reduce `archetypes` to what the palette offers at `purpose` + `tier`, with each dial's hint
  * count (see {@link NarrowedAgentPalette} for what the counts promise).
  *
- * An archetype carrying no `category` has nothing for the purpose dial to judge, so it is always
- * relevant; an absent `tier` is `DEFAULT_AGENT_TIER`. Both are how a deployment-registered kind
- * that declares neither behaves, and neither is a reason to drop it from the catalog.
+ * Relevance is asked of the KIND (`purposeSuggestsAgentKind`), which reads the kind's own
+ * `purposes` when it declares one and falls back to its `category`'s row otherwise, so a kind
+ * that belongs to one use-case can leave a section its siblings still belong in. An archetype
+ * carrying neither has nothing for the purpose dial to judge and is always relevant; an absent
+ * `tier` is `DEFAULT_AGENT_TIER`. All three are how a deployment-registered kind that declares
+ * nothing behaves, and none of them is a reason to drop it from the catalog.
  */
-export function narrowAgentPalette<T extends Pick<AgentArchetype, 'tier' | 'category'>>(
-  archetypes: readonly T[],
-  purpose: PipelinePurpose,
-  tier: AgentTier,
-): NarrowedAgentPalette<T> {
-  const relevant = (a: T) => !a.category || purposeSuggestsAgentCategory(purpose, a.category)
+export function narrowAgentPalette<
+  T extends Pick<AgentArchetype, 'tier' | 'category' | 'purposes'>,
+>(archetypes: readonly T[], purpose: PipelinePurpose, tier: AgentTier): NarrowedAgentPalette<T> {
+  const relevant = (a: T) => purposeSuggestsAgentKind(purpose, a)
   const inTier = (a: T) => agentTierVisibleAt(a.tier, tier)
   return {
     offered: archetypes.filter((a) => relevant(a) && inTier(a)),

package/app/utils/catalog.spec.ts

@@ -1,5 +1,7 @@
 import { describe, it, expect } from 'vitest'
+import { PIPELINE_PURPOSES, purposeAllowsAgentCategory } from '@cat-factory/contracts'
 import type { AgentKind, BlockStatus, BlockType } from '~/types/domain'
+import { narrowAgentPalette } from '~/utils/agentPalette'
 import {
   AGENT_ARCHETYPES,
   AGENT_BY_KIND,
@@ -85,6 +87,39 @@ describe('catalog', () => {
     expect(basic).toEqual(expect.arrayContaining(['architect', 'coder', 'tester-api']))
   })
 
+  it('leaves every purpose a palette to build from, and every declaration saveable', () => {
+    // Two properties over the whole grid rather than a pinned count, which every ordinary
+    // addition would break without naming anything.
+    //
+    // A `purposes` declaration only ever HIDES, so the way to get it wrong is to hide too much:
+    // a purpose whose palette reduces to nothing is a dial setting with no way forward, and the
+    // widest tier is where that has to be checked because the tier hint is the way out of a thin
+    // one. And relevance stays a subset of compatibility per KIND, so a declaration can never
+    // offer a step the save gate would then refuse.
+    for (const purpose of PIPELINE_PURPOSES) {
+      const offered = narrowAgentPalette(AGENT_ARCHETYPES, purpose, 'advanced').offered
+      expect(offered.length, `${purpose} offers no agent at all`).toBeGreaterThan(0)
+      for (const a of offered) {
+        expect(
+          !a.category || purposeAllowsAgentCategory(purpose, a.category),
+          `${a.kind} is offered to a ${purpose} pipeline its step could not be saved in`,
+        ).toBe(true)
+      }
+    }
+  })
+
+  it('never declares an EMPTY `purposes` (which reads as no declaration, not as "nowhere")', () => {
+    // `agentPresentationSchema` refuses an empty list at registration, but this catalog is
+    // authored in TypeScript and parsed by nothing, so the same guard has to be asserted for the
+    // half valibot never sees. Left empty, a kind someone meant to offer NOWHERE is offered
+    // everywhere its section is: `purposeSuggestsAgentKind` cannot tell an authored `[]` from a
+    // kind that declared nothing at all.
+    for (const a of [...AGENT_ARCHETYPES, ...Object.values(SYSTEM_AGENT_META)]) {
+      if (!a.purposes) continue
+      expect(a.purposes.length, `${a.kind} declares an empty purposes list`).toBeGreaterThan(0)
+    }
+  })
+
   it('never shadows a companion producer as a system kind', () => {
     // A companion is never placed directly: the builder renders it as a toggle on its producer
     // step, so a producer that cannot be placed takes its companion out of the builder with it.

package/app/utils/catalog.ts

@@ -35,6 +35,10 @@ export const AGENT_ARCHETYPES: AgentArchetype[] = [
     icon: 'i-lucide-clipboard-check',
     color: '#f59e0b',
     category: 'review',
+    // Settles the PRODUCT layer before anyone builds, which is every use-case except reviewing
+    // someone else's open pull request: there the requirements are already someone's shipped
+    // decision and nothing here can change them.
+    purposes: ['build', 'document', 'research', 'planning'],
     description:
       'Reviews the collected context (description + linked PRDs/RFCs) for gaps, ambiguities, assumptions and risks before the architect starts.',
     // Opens the dedicated structured review window (answer/dismiss findings → incorporate
@@ -48,6 +52,8 @@ export const AGENT_ARCHETYPES: AgentArchetype[] = [
     icon: 'i-lucide-bug',
     color: '#f59e0b',
     category: 'review',
+    // Triages a BUG REPORT for fixability, so it only makes sense where something gets fixed.
+    purposes: ['build'],
     description:
       'Triages a bug report for fixability — raising questions, gaps and assumptions about the report before anyone starts fixing it.',
     // Opens the dedicated structured review window (answer/dismiss findings → incorporate
@@ -65,6 +71,9 @@ export const AGENT_ARCHETYPES: AgentArchetype[] = [
     icon: 'i-lucide-search-code',
     color: '#38bdf8',
     category: 'review',
+    // Traces a bug to its root cause in the code: a fixing pipeline's opening move, and nothing
+    // a document, review, spike or plan has any use for.
+    purposes: ['build'],
     description:
       'Read-only, multi-repo codebase investigation that traces the bug to its root cause and decides whether the report is fixable as-is or needs the reporter to clarify (no code changes).',
     resultView: 'generic-structured',
@@ -81,6 +90,9 @@ export const AGENT_ARCHETYPES: AgentArchetype[] = [
     icon: 'i-lucide-clipboard-check',
     color: '#6366f1',
     category: 'review',
+    // Reviews an EXISTING open pull request, which is the whole of the review use-case, and is
+    // available to a build pipeline that wants a deep pass over the pull request it just opened.
+    purposes: ['build', 'review'],
     description:
       'Deep, token-bounded review of an open pull request: slices a large diff into cohesive ' +
       'chunks, reviews each, and returns prioritized findings.',
@@ -148,6 +160,8 @@ export const AGENT_ARCHETYPES: AgentArchetype[] = [
     icon: 'i-lucide-clipboard-list',
     color: '#c084fc',
     category: 'design',
+    // Writes the in-repo spec the implementation is then built against.
+    purposes: ['build', 'planning'],
     description:
       "Aggregates every task's clarified requirements into the service's in-repo specification (spec.json) with full acceptance-scenario coverage, derived into Gherkin.",
   },
@@ -158,6 +172,9 @@ export const AGENT_ARCHETYPES: AgentArchetype[] = [
     icon: 'i-lucide-drafting-compass',
     color: '#a78bfa',
     category: 'design',
+    // Designs the shape of a CODE change, so it belongs wherever code is planned or written and
+    // nowhere a document is being authored.
+    purposes: ['build', 'research', 'planning'],
     description: 'Designs the shape of the solution and breaks down the work.',
   },
   {
@@ -170,6 +187,8 @@ export const AGENT_ARCHETYPES: AgentArchetype[] = [
     icon: 'i-lucide-map',
     color: '#22d3ee',
     category: 'design',
+    // Decomposes a repository into services and modules on the board.
+    purposes: ['build', 'planning'],
     description: 'Maps the repository into the service → modules blueprint.',
   },
   {
@@ -310,6 +329,9 @@ export const AGENT_ARCHETYPES: AgentArchetype[] = [
     icon: 'i-lucide-book-open-text',
     color: '#818cf8',
     category: 'docs',
+    // WRITES documentation into the repository, which a pipeline that reviews someone else's
+    // pull request never does.
+    purposes: ['build', 'document'],
     description: 'Produces docs and usage examples.',
   },
   {
@@ -319,6 +341,8 @@ export const AGENT_ARCHETYPES: AgentArchetype[] = [
     icon: 'i-lucide-scroll-text',
     color: '#84cc16',
     category: 'docs',
+    // Writes domain-rule docs into the repository (see `documenter`).
+    purposes: ['build', 'document'],
     description:
       'Reads the implementation and writes/updates business-logic & domain-rule docs in the repo, weaving in linked context documents.',
   },
@@ -329,6 +353,9 @@ export const AGENT_ARCHETYPES: AgentArchetype[] = [
     icon: 'i-lucide-shield-alert',
     color: '#ef4444',
     category: 'docs',
+    // The review activity that groups under Documentation: it reads a change against the
+    // documented rules and reports violations, writing nothing.
+    purposes: ['build', 'review'],
     description:
       'Reviews a change against the documented domain rules and reports violations, undocumented changes and unexpected drift.',
   },

package/app/utils/pipeline.spec.ts

@@ -8,7 +8,9 @@ import {
   pipelineAllowedForTaskType,
   purposeAllowsAgentCategory,
   purposeSuggestsAgentCategory,
+  purposeSuggestsAgentKind,
 } from '@cat-factory/contracts'
+import type { PipelinePurpose } from '@cat-factory/contracts'
 import type { Block, Pipeline } from '~/types/domain'
 import {
   pipelineAllowedForManualStart,
@@ -216,6 +218,73 @@ describe('purposeSuggestsAgentCategory (builder palette filter)', () => {
   })
 })
 
+describe('purposeSuggestsAgentKind (what the palette actually filters on)', () => {
+  it('defers to the category for a kind that declares no purposes of its own', () => {
+    // The normal case, and the one that keeps a deployment-registered kind exactly as visible as
+    // it was before kinds could speak for themselves.
+    for (const purpose of [...PIPELINE_PURPOSES, UNKNOWN_PURPOSE]) {
+      for (const category of AGENT_CATEGORIES) {
+        expect(purposeSuggestsAgentKind(purpose, { category })).toBe(
+          purposeSuggestsAgentCategory(purpose, category),
+        )
+      }
+      expect(purposeSuggestsAgentKind(purpose, {})).toBe(true)
+    }
+  })
+
+  it('lets a kind narrow within a category its siblings still belong to', () => {
+    // What the category table structurally cannot say: `docs` survives a `review` pipeline so the
+    // Domain Rules Reviewer does, which also handed it the two kinds that WRITE documentation.
+    const author = { category: 'docs', purposes: ['build', 'document'] } as const
+    expect(purposeSuggestsAgentKind('document', author)).toBe(true)
+    expect(purposeSuggestsAgentKind('review', author)).toBe(false)
+    expect(purposeSuggestsAgentCategory('review', 'docs')).toBe(true)
+  })
+
+  it('is a declaration, not an exemption from the category', () => {
+    // A kind cannot buy its way back into a purpose its section is not offered to: `docs` is gone
+    // for `planning`, and the palette drops the kind whether or not it named `planning` itself.
+    const doc = { category: 'docs', purposes: ['planning'] } as const
+    expect(purposeSuggestsAgentKind('planning', doc)).toBe(
+      purposeSuggestsAgentCategory('planning', 'docs'),
+    )
+  })
+
+  it('reads a list naming nothing this build knows as no declaration at all', () => {
+    const stale = { category: 'docs', purposes: [UNKNOWN_PURPOSE] } as const
+    for (const purpose of PIPELINE_PURPOSES) {
+      expect(purposeSuggestsAgentKind(purpose, stale)).toBe(
+        purposeSuggestsAgentCategory(purpose, 'docs'),
+      )
+    }
+    // And a purpose this build cannot name still narrows nothing, declaration or not.
+    expect(
+      purposeSuggestsAgentKind(UNKNOWN_PURPOSE, { category: 'docs', purposes: ['build'] }),
+    ).toBe(true)
+  })
+
+  it('never offers what the save gate would refuse', () => {
+    // The same invariant the category predicate carries, restated where the palette now reads it:
+    // a kind's own declaration may only ever hide more, so it can never open a hole through which
+    // a kind is offered and its step then blocks the save.
+    for (const purpose of [...PIPELINE_PURPOSES, UNKNOWN_PURPOSE]) {
+      for (const category of AGENT_CATEGORIES) {
+        const declarations: (readonly PipelinePurpose[] | undefined)[] = [
+          undefined,
+          PIPELINE_PURPOSES,
+          ['build'],
+          [UNKNOWN_PURPOSE],
+        ]
+        for (const purposes of declarations) {
+          if (purposeSuggestsAgentKind(purpose, { category, purposes })) {
+            expect(purposeAllowsAgentCategory(purpose, category)).toBe(true)
+          }
+        }
+      }
+    }
+  })
+})
+
 describe('a purpose or category this build does not recognise', () => {
   it('is recognised as unknown rather than trusted', () => {
     for (const purpose of PIPELINE_PURPOSES) expect(isPipelinePurpose(purpose)).toBe(true)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cat-factory/app",
-  "version": "0.255.1",
+  "version": "0.256.1",
   "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.40",
     "wretch": "^3.0.9",
-    "@cat-factory/contracts": "0.282.0"
+    "@cat-factory/contracts": "0.283.1"
   },
   "devDependencies": {
     "@toad-contracts/testing": "0.3.2",