@owlmeans/viable-common 0.0.25 → 0.0.26

package/src/skills/roles.ts

@@ -111,11 +111,17 @@ and you are told which one with each task.
 
   [ViablePersona.VisualDesigner]: persona(`
 You are a visual ui designer specializing in writing design guidelines and design systems
-for web applications that loves to produce expressive and bright interfaces.
-Unless a specification asks for something else, you default to a modern, expressive language —
-gradients, glass surfaces, layered shadows, restrained motion — while keeping every surface
-plainly readable. What makes a design yours is the values you choose, never the techniques you
-leave out.
+for web applications, and your interfaces are calm, precise and unmistakably the product's own.
+Your house style: a white ground in light mode and a black one in dark mode; colour from ONE
+product accent and never from backgrounds; depth only from hairlines, neutral tiles and a single
+floating shadow; a heavy grotesk display face with tight tracking and generous whitespace carrying
+the brand; motion that is small and belongs to the picture. You never reach for gradients, glass,
+blur or glow, and the older decoration classes a project still defines are painted flat and are
+never your tools. You change any of this only when the customer's specification explicitly asks —
+it names a background colour, a dark-only or coloured theme, a brand palette, or gradients. The
+product's subject matter is not such a request: a bakery is not a warm background, a bank is not a
+blue one. What makes a design this product's is its accent, its type and its illustration — never
+an added effect.
 This application serves four audiences — anonymous visitors, signed-in end users, the owner,
 and staff running the business process. Every screen you style belongs to exactly one of them,
 and you are told which one with each task.

package/src/types.ts

@@ -33,6 +33,17 @@ export interface SlotConstMetadata {
   brandingPrivacyUrl: string
   brandingCredit: string
   brandingHideCreditIntent: string
+  /**
+   * The Google tag the owner attached — a `GTM-` container or a `G-`/`GT-`/`AW-`/`DC-` tag id —
+   * loaded by the generated application behind its cookie consent, in the preview and in
+   * production alike.
+   *
+   * OPTIONAL, unlike the branding keys above, and OMITTED from a push while it is unset: a slot
+   * publisher built before the key existed validates the signed body against a schema that does
+   * not declare it, strips it, and refuses the whole configuration with a 401. An unset tag must
+   * therefore never reach one — which only absence guarantees.
+   */
+  brandingGoogleTag?: string
 }
 
 export interface SlotSecretMetadata {
@@ -82,6 +93,25 @@ export interface SlotListMetadata {
    * hosts are always accepted and are never in this list.
    */
   allowedOrigins: string[]
+  /**
+   * Extra Content-Security-Policy source expressions the slot's runtime adds to what it serves —
+   * a third party a generated app legitimately needs that the platform does not already know about.
+   *
+   * OPTIONAL and omitted from a push while empty, for the reason `brandingGoogleTag` is: an older
+   * publisher refuses a signed body carrying a key its schema does not declare, and a slot
+   * provisioned before the key existed simply has no value for it. The runtime reads it
+   * defensively and filters every source before it reaches a header.
+   *
+   * The Google tag's hosts are NOT carried here: the publisher derives them itself from
+   * `brandingGoogleTag` (and, for a production build, from the record the build writes), so the
+   * tag and the hosts it needs cannot disagree. Nothing writes this key today; it is declared so the
+   * publisher's existing reader has a vocabulary entry and a schema slot.
+   *
+   * Deliberately NOT in `metadataLists`. That array enumerates the lists an OWNER stores — one
+   * `project-config` row each, loaded on every metadata read and pushed back verbatim — and no
+   * owner-facing setting stores this one.
+   */
+  cspSources?: string[]
 }
 
 export interface CustomSecretMetadata {

package/tests/blueprint.spec.ts

@@ -0,0 +1,98 @@
+import { describe, expect, test } from 'bun:test'
+import {
+  applyBlueprintCase, BLUEPRINT_CASES, BlueprintCase, landingGatePreferenceOf, LandingGatePreference,
+  personaSkillsOf,
+} from '../src/blueprint/index.js'
+import type { Blueprint } from '../src/blueprint/index.js'
+import { ViableSkill } from '../src/skills/consts.js'
+import { ViablePersona } from '../src/skills/roles.js'
+
+/** Just enough of a blueprint for a case to be applied to — the shape a test builds. */
+const base = (extra: Partial<Blueprint> = {}): Blueprint => ({
+  id: 'test-blueprint',
+  title: 'Test',
+  technology: { id: 'ts', language: 'typescript', runtime: 'bun', extensions: ['.ts'], buildScripts: {}, packageManager: 'bun' },
+  stack: { id: 'owlmeans', framework: 'owlmeans', topology: {} as Blueprint['stack']['topology'], skills: [ViableSkill.TsStyle] },
+  template: { id: 'seed', overlay: 'seed', patches: [] },
+  createApp: { id: 'create-app', package: '@owlmeans/create-app', bare: true, template: 'bare' },
+  packages: {
+    id: 'packages',
+    capabilities: { postgres: true, kv: false, queue: false, worker: false, agents: false, validation: true },
+    libraries: {},
+    skills: [ViableSkill.ShadcnUi],
+    personaSkills: { [ViablePersona.BusinessAnalyst]: [ViableSkill.MainFlowFocus] },
+  },
+  ...extra,
+})
+
+describe('viable-common - the landing-gate preference', () => {
+  test('answers Allow for no blueprint, no layer and a value this deploy never heard of', () => {
+    expect(landingGatePreferenceOf()).toBe(LandingGatePreference.Allow)
+    expect(landingGatePreferenceOf(base())).toBe(LandingGatePreference.Allow)
+    expect(landingGatePreferenceOf({ experience: { landingGate: 'insist' as never } }))
+      .toBe(LandingGatePreference.Allow)
+    expect(landingGatePreferenceOf({ experience: { landingGate: LandingGatePreference.Discourage } }))
+      .toBe(LandingGatePreference.Discourage)
+  })
+
+  test('each case weighs the gate: web and the AI kinds encourage, scalable allows, a game discourages', () => {
+    const preferences = Object.fromEntries(Object.values(BlueprintCase).map(id =>
+      [id, landingGatePreferenceOf(applyBlueprintCase(base(), id))]))
+
+    expect(preferences).toEqual({
+      [BlueprintCase.Web]: LandingGatePreference.Encourage,
+      [BlueprintCase.Scalable]: LandingGatePreference.Allow,
+      [BlueprintCase.AiPipeline]: LandingGatePreference.Encourage,
+      [BlueprintCase.AiAgent]: LandingGatePreference.Encourage,
+      [BlueprintCase.Game]: LandingGatePreference.Discourage,
+    })
+  })
+
+  test('a case overrides the base layer key by key, and no case leaves a blueprint without one', () => {
+    const allowing = base({ experience: { landingGate: LandingGatePreference.Allow } })
+
+    expect(landingGatePreferenceOf(applyBlueprintCase(allowing, BlueprintCase.Game)))
+      .toBe(LandingGatePreference.Discourage)
+    expect(applyBlueprintCase(base(), undefined).experience).toBeUndefined()
+    expect(Object.isFrozen(applyBlueprintCase(base(), BlueprintCase.Web).experience)).toBe(true)
+  })
+})
+
+describe('viable-common - the landing-gate skill in the cases', () => {
+  const gatePersonas = [
+    ViablePersona.BusinessAnalyst, ViablePersona.UxDesigner, ViablePersona.LayoutArchitect,
+    ViablePersona.ComponentArchitect, ViablePersona.UiViewCoder, ViablePersona.UiNavCoder,
+  ]
+
+  test('reaches the analyst and the frontend personas of every encouraging case, and nobody else', () => {
+    for (const id of [BlueprintCase.Web, BlueprintCase.AiPipeline, BlueprintCase.AiAgent]) {
+      const cased = applyBlueprintCase(base(), id)
+      for (const persona of gatePersonas) {
+        expect(personaSkillsOf(cased, persona), `${id} → ${persona}`).toContain(ViableSkill.LandingGate)
+      }
+      expect(personaSkillsOf(cased, ViablePersona.ApiCoder)).not.toContain(ViableSkill.LandingGate)
+    }
+    for (const id of [BlueprintCase.Scalable, BlueprintCase.Game]) {
+      const cased = applyBlueprintCase(base(), id)
+      for (const persona of gatePersonas) {
+        expect(personaSkillsOf(cased, persona), `${id} → ${persona}`).not.toContain(ViableSkill.LandingGate)
+      }
+    }
+  })
+
+  test('is merged with what a case and the base already give a persona, never in place of it', () => {
+    const agent = applyBlueprintCase(base(), BlueprintCase.AiAgent)
+
+    expect(personaSkillsOf(agent, ViablePersona.BusinessAnalyst)).toEqual([
+      ViableSkill.MainFlowFocus, ViableSkill.AgenticChoice, ViableSkill.LandingGate,
+    ])
+    expect(personaSkillsOf(agent, ViablePersona.UxDesigner))
+      .toEqual([ViableSkill.AgenticChoice, ViableSkill.LandingGate])
+    expect(personaSkillsOf(agent, ViablePersona.WorkerCoder)).toEqual([
+      ViableSkill.AgenticChoice, ViableSkill.TargetLlm, ViableSkill.LibrariesAi,
+      ViableSkill.TargetAgentTools,
+    ])
+    expect(BLUEPRINT_CASES[BlueprintCase.AiPipeline].patch.packages?.personaSkills?.[ViablePersona.BusinessAnalyst])
+      .toEqual([ViableSkill.AgenticChoice, ViableSkill.LandingGate])
+  })
+})

package/tests/branding.spec.ts

@@ -1,6 +1,7 @@
 import { describe, expect, it } from 'bun:test'
 
-import { brandingEnv } from '../src/branding.js'
+import { BRANDING_ENV_KEYS, brandingEnv } from '../src/branding.js'
+import { metadataConfigs, metadataLists } from '../src/consts.js'
 
 /**
  * `BRANDING_CREDIT` is the one key whose ABSENCE means something different from an explicit
@@ -32,6 +33,25 @@ describe('brandingEnv', () => {
       BRANDING_PRIVACY_URL: '',
       BRANDING_CREDIT: '1',
       BRANDING_PRODUCT: 'Acme CRM',
+      BRANDING_GOOGLE_TAG: '',
     })
   })
+
+  it('carries the Google tag, and emits it empty when none is set', () => {
+    // The METADATA key is omitted from a push while unset (an older publisher refuses it); the
+    // ENVIRONMENT key is always there, and '' is what tells the build to load no tag.
+    expect(brandingEnv({ brandingGoogleTag: 'G-ABC123XYZ' }).BRANDING_GOOGLE_TAG).toBe('G-ABC123XYZ')
+    expect(brandingEnv({}).BRANDING_GOOGLE_TAG).toBe('')
+  })
+
+  it('emits exactly the keys BRANDING_ENV_KEYS names', () => {
+    expect(Object.keys(brandingEnv({})).sort()).toEqual([...BRANDING_ENV_KEYS].sort())
+  })
+})
+
+describe('the metadata vocabulary', () => {
+  it('delivers the Google tag as a config key, and keeps the derived CSP list out of the stored lists', () => {
+    expect(metadataConfigs).toContain('brandingGoogleTag')
+    expect(metadataLists as string[]).not.toContain('cspSources')
+  })
 })

package/tests/connect-entrypoints.spec.ts

@@ -1,8 +1,10 @@
 import { describe, expect, test } from 'bun:test'
-import { openProtocol, protocols } from '@owlmeans/entrypoint'
+import Ajv from 'ajv'
+import { aliasOf, openProtocol, protocols } from '@owlmeans/entrypoint'
 import { DEFAULT_GUARD } from '@owlmeans/auth-common'
-import { route } from '@owlmeans/route'
-import { connect } from '../src/connect/consts.js'
+import { route, RouteMethod } from '@owlmeans/route'
+import { connect, CONNECT_BRANDING_GOOGLE_TAG_MAX } from '../src/connect/consts.js'
+import { ConnectProjectBrandingSaveSchema } from '../src/connect/schemas.js'
 import { connectProtocols } from '../src/connect/entrypoints.js'
 import { connectRef } from '../src/connect/references.js'
 
@@ -21,8 +23,45 @@ describe('@owlmeans/viable-common — connector protocol tree', () => {
     expect(tree.convert.proceed.alias).toBe(connect.convert.proceed)
     expect(tree.inquiry.answer.alias).toBe(connect.inquiry.answer)
     expect(tree.files.list.alias).toBe(connect.files.list)
-    expect(protocols(tree)).toHaveLength(32)
-    expect(new Set(protocols(tree).map(protocol => protocol.alias)).size).toBe(32)
+    expect(protocols(tree)).toHaveLength(34)
+    expect(new Set(protocols(tree).map(protocol => protocol.alias)).size).toBe(34)
+  })
+
+  test('reads and saves a project\'s branding at one path, under the owned base and no paid gate', () => {
+    const paid = connectProtocols({
+      guard: DEFAULT_GUARD,
+      gate: { alias: 'test-gate', params: ['owner'] },
+      localLlm: { alias: 'test-paid-llm', params: ['cap'] },
+      updateBase: openProtocol(route('manager:update', '/update')),
+    })
+    const get = paid.project.branding.get
+    const save = paid.project.branding.save
+
+    expect(get.alias).toBe(connect.project.branding.get)
+    expect(save.alias).toBe(connect.project.branding.save)
+    expect(get.route.route.path).toBe('/project/:id/branding')
+    expect(save.route.route.path).toBe('/project/:id/branding')
+    expect(get.route.route.method).toBe(RouteMethod.GET)
+    expect(save.route.route.method).toBe(RouteMethod.POST)
+    expect(aliasOf(get.route.route.parent)).toBe(connect.base)
+    expect(aliasOf(save.route.route.parent)).toBe(connect.base)
+    // The paid local-LLM gate sits on its own two routes; branding carries no gate of its own and
+    // inherits only the base's guard and ownership gate.
+    expect(paid.project.llm.gate?.alias).toBe('test-paid-llm')
+    expect(get.gate).toBeUndefined()
+    expect(save.gate).toBeUndefined()
+    expect(connectRef.project.branding.save.alias).toBe(connect.project.branding.save)
+    expect(connectRef.project.branding.get.alias).toBe(connect.project.branding.get)
+  })
+
+  test('the branding save body is a patch of strings that can never carry the credit', () => {
+    const validate = new Ajv({ strict: false }).compile(ConnectProjectBrandingSaveSchema)
+
+    expect(validate({})).toBe(true)
+    expect(validate({ googleTag: 'GTM-ABCD123', termsUrl: '/terms', privacyUrl: '' })).toBe(true)
+    expect(validate({ copyright: '' })).toBe(false)
+    expect(validate({ hideCredit: true })).toBe(false)
+    expect(validate({ googleTag: 'G-'.padEnd(CONNECT_BRANDING_GOOGLE_TAG_MAX + 1, 'X') })).toBe(false)
   })
 
   test('keeps story mutations in planning and exposes only the composed story status', () => {

package/tests/planning.spec.ts

@@ -4,7 +4,7 @@ import addFormats from 'ajv-formats'
 import { ResilientError } from '@owlmeans/error'
 import {
   canTransit, CodeScope, CodeStyle, intrinsicOf, IntrinsicStatus, makeSchemaRegistry,
-  SpecificationFormat, transitionsFrom, WorkcardKind,
+  SpecificationFormat, TITLE_MAX, transitionsFrom, WorkcardKind,
 } from '@owlmeans/planning'
 import type { Specification } from '@owlmeans/planning'
 import { ProjectArea } from '../src/areas/consts.js'
@@ -14,6 +14,9 @@ import { STORY_DESIGN_VERSION } from '../src/design/consts.js'
 import { emptyStoryDesign } from '../src/design/helpers.js'
 import { StoryActor } from '../src/design/runtime.js'
 import type { StoryDesign } from '../src/design/types.js'
+import {
+  hasLandingSentence, LANDING_STORY_SENTENCE, withLandingSentence,
+} from '../src/index.js'
 import {
   isUserChannel, isViableProject, isViableStory, ProjectAgentOccupied, ProjectNotFound,
   ProjectStoryMissconfigured, projectBriefOf, storyDraftOf, storyWriteInputOf, userStoryOf,
@@ -255,9 +258,24 @@ describe('viable-common - the viable field schemas', () => {
     expect(project({
       formerAliases: ['old-name'], language: 'en', blueprint: 'owlmeans', blueprintCase: 'web',
       target: null, connectLlmMode: 'local', origin: { kind: 'github', repoUrl: 'https://x/y' },
+      landing: { story: 'US-ABC12', at },
     })).toBe(true)
     expect(project({ alias: 'slot-booker' })).toBe(false)
   })
+
+  test('a story carries the landing flag, spelled or nulled', () => {
+    expect(story({ area: ProjectArea.User, primary: false, landing: true })).toBe(true)
+    expect(story({ area: ProjectArea.User, primary: false, landing: null })).toBe(true)
+    expect(story({ area: ProjectArea.User, primary: false, landing: 'yes' })).toBe(false)
+  })
+
+  test('a project records a decided "no gate" as story null, and never a decision without a time', () => {
+    // Absent = never decided; `story: null` = decided, no gate. Both must be spellable.
+    expect(project({ landing: { story: null, at } })).toBe(true)
+    expect(project({ landing: null })).toBe(true)
+    expect(project({ landing: { story: 'US-ABC12' } })).toBe(false)
+    expect(project({ landing: { story: 'US-ABC12', at, reason: 'best fit' } })).toBe(false)
+  })
 })
 
 describe('viable-common - the viable card helpers', () => {
@@ -311,6 +329,16 @@ describe('viable-common - the viable card helpers', () => {
       .toThrow(ProjectStoryMissconfigured)
   })
 
+  test('storyWriteInputOf copies the landing flag from the card, and only when it is set', () => {
+    const content = {
+      userStory: userStoryOf(storyCard()), screenPaths: {}, componentPaths: {}, transitions: [],
+    }
+    const landing = storyCard({ fields: { area: ProjectArea.User, primary: false, landing: true } })
+
+    expect(storyWriteInputOf(landing, content).landing).toBe(true)
+    expect('landing' in storyWriteInputOf(storyCard(), content)).toBe(false)
+  })
+
   test('only a person writes through the web and connect channels', () => {
     expect(isUserChannel(ViableChannel.Web)).toBe(true)
     expect(isUserChannel(ViableChannel.Connect)).toBe(true)
@@ -319,6 +347,33 @@ describe('viable-common - the viable card helpers', () => {
   })
 })
 
+describe('viable-common - the landing sentence', () => {
+  test('is appended once, with one space, and a resumed step never adds a second copy', () => {
+    const once = withLandingSentence('A member books a slot.')
+
+    expect(once).toBe(`A member books a slot. ${LANDING_STORY_SENTENCE}`)
+    expect(withLandingSentence(once)).toBe(once)
+    expect(hasLandingSentence(once)).toBe(true)
+    expect(hasLandingSentence('A member books a slot.')).toBe(false)
+  })
+
+  test('is recognised whatever whitespace a person left around it', () => {
+    const rewrapped = `A member books a slot.\n${LANDING_STORY_SENTENCE.replace('; after', ';\n  after')}`
+
+    expect(hasLandingSentence(rewrapped)).toBe(true)
+    expect(withLandingSentence(rewrapped)).toBe(rewrapped)
+  })
+
+  test('never makes a title longer than a card accepts, and never cuts the narrative', () => {
+    const long = 'x'.repeat(TITLE_MAX - 10)
+
+    expect(withLandingSentence(long)).toBe(long)
+    expect(withLandingSentence('x'.repeat(TITLE_MAX - LANDING_STORY_SENTENCE.length - 1)).length)
+      .toBe(TITLE_MAX)
+    expect(withLandingSentence('  ')).toBe(LANDING_STORY_SENTENCE)
+  })
+})
+
 describe('viable-common - the follows anchor', () => {
   test('mergeConnectingStories carries the clamped anchor on each connective entry', () => {
     const flow = [

package/tests/scaffold.spec.ts

@@ -0,0 +1,131 @@
+import { describe, expect, test } from 'bun:test'
+import Ajv from 'ajv'
+import { validateSpecificationBody } from '@owlmeans/planning'
+import { ProjectArea } from '../src/areas/consts.js'
+import { ViableSpecCategory, VIABLE_PROJECT_SLOTS } from '../src/planning/index.js'
+import { BENTO_FRAGMENT_KINDS, WidgetKind } from '../src/scaffold/consts.js'
+import { ScaffoldPlanSchema } from '../src/scaffold/schemas.js'
+import type { ScaffoldPlan } from '../src/scaffold/types.js'
+
+/**
+ * The scaffold plan's schema is TWO things at once: the shape a model answers with, and the
+ * validator of the project card's `scaffold` document. A plan written before the landing-page
+ * overhaul carries none of its fields, and must still pass — or that project's plan can never be
+ * revised again. Compiled the way the planning registry compiles it (no formats, not strict).
+ */
+const oldPlan = (): ScaffoldPlan => ({
+  identity: { name: 'Crumb & Crust', description: 'Recipes and bakes from a welcoming community.' },
+  guestHome: {
+    hero: { headline: 'Find your next bake.', sub: 'Photo-led recipes.', cta: 'Get started', eyebrow: 'New' },
+    problem: { title: 'Inspiration lacks detail', text: 'A bake is easy to find.' },
+    solution: { title: 'Bakes worth making', text: 'The full process in one place.' },
+    features: [{ title: 'Complete recipes', text: 'Clear ingredient lists.' }],
+    testimonials: [{ quote: 'I found a rye loaf.', name: 'Mara L.', role: 'Home baker' }],
+  },
+  areas: [{ area: ProjectArea.Guest, intro: { title: 'Welcome', text: 'Browse.' }, sections: ['Bakes'] }],
+  stories: [{
+    code: 'US-ABC12',
+    section: 'Bakes',
+    screen: 'Bakes/Find a bake',
+    widget: { kind: WidgetKind.List, title: 'Bake finder', description: 'Bakes you can make.' },
+    sketch: { headline: 'Your bakes', caption: 'What you can bake', items: ['Rye loaf'] },
+    home: true,
+  }],
+  motifs: 'A rye loaf on a board.',
+})
+
+const newPlan = (): ScaffoldPlan => {
+  const plan = oldPlan()
+
+  return {
+    ...plan,
+    guestHome: {
+      ...plan.guestHome,
+      hero: {
+        headline: 'Find your next bake.', sub: 'Photo-led recipes.', cta: 'Get started',
+        secondary: { label: 'Browse bakes' },
+        browse: { label: 'Just browsing? Explore bakes', href: '#features' },
+      },
+      features: [
+        {
+          title: 'Complete recipes', text: 'Clear ingredient lists.',
+          fragment: {
+            kind: 'list', title: 'INGREDIENTS · 1 LOAF',
+            rows: [{ label: 'Rye flour', value: '350 g' }, { label: 'Water', value: '390 g' }],
+          },
+        },
+        { title: 'Baking notes', text: 'Small adjustments.', fragment: { kind: 'note', rows: [{ label: 'Drop the oven.' }] } },
+        { title: 'Photo-led bakes', text: 'Every idea starts with the bake.' },
+        { title: 'Baker attribution', text: 'See who made it.', fragment: { kind: 'people', rows: [{ label: 'Mara L.', value: 'Rye' }] } },
+      ],
+      steps: [
+        { title: 'Pick what you have', text: 'Tap the ingredients.' },
+        { title: 'See what you can bake', text: 'Ranked by your pantry.' },
+        { title: 'Open the full method', text: 'Sign in with your email.' },
+      ],
+      labels: { steps: 'How it works', stepsTitle: 'From pantry to basket.', problem: 'The problem' },
+      closing: {
+        headline: 'Your next bake starts here.', lead: 'Browse freely.', primary: 'Get started',
+        secondary: { label: 'Browse bakes' },
+        links: [{ title: 'Explore bakes', text: 'Open to everyone.' }, { title: 'Share your bake', text: 'Post it.', href: '#' }],
+      },
+      gate: {
+        story: 'US-ABC12',
+        target: 'web:bake-finder',
+        question: "What's in your pantry?",
+        hint: 'No account needed',
+        label: 'Your pantry',
+        inputs: ['Bread flour', 'Rye flour', 'Butter', 'Eggs', 'Yeast'],
+        selected: ['Bread flour', 'Rye flour', 'Butter', 'Yeast'],
+        results: [{ title: 'Seeded rye loaf', meta: 'Uses all 3 · 3 h 20 min', needs: ['Bread flour', 'Rye flour', 'Yeast'] }],
+        count: { one: '{n} bake matches', many: '{n} bakes match', none: 'No matches yet' },
+        empty: 'Pick two or more ingredients.',
+        note: 'Sign in with your email. Your picks come with you.',
+        cta: 'Open recipes →',
+        lock: 'Full method after sign-in',
+      },
+    },
+  }
+}
+
+describe('viable-common - the scaffold plan schema', () => {
+  const validate = new Ajv({ strict: false, allErrors: true }).compile(ScaffoldPlanSchema)
+  const slot = VIABLE_PROJECT_SLOTS.find(entry => entry.category === ViableSpecCategory.Scaffold)!
+
+  test('a plan stored before the landing overhaul still validates', () => {
+    expect(validate(oldPlan()), JSON.stringify(validate.errors)).toBe(true)
+    expect(() => validateSpecificationBody(slot, JSON.stringify(oldPlan()))).not.toThrow()
+  })
+
+  test('a plan carrying every new field validates', () => {
+    expect(validate(newPlan()), JSON.stringify(validate.errors)).toBe(true)
+    expect(() => validateSpecificationBody(slot, JSON.stringify(newPlan()))).not.toThrow()
+  })
+
+  test('a provider that spells an unset optional as null is accepted', () => {
+    const plan = newPlan() as unknown as { guestHome: Record<string, unknown> }
+    plan.guestHome.gate = null
+    plan.guestHome.closing = null
+    ;(plan.guestHome.hero as Record<string, unknown>).secondary = null
+
+    expect(validate(plan), JSON.stringify(validate.errors)).toBe(true)
+  })
+
+  test('still refuses an undeclared field and a fragment kind nothing can draw', () => {
+    const stray = newPlan() as unknown as { guestHome: Record<string, unknown> }
+    stray.guestHome.badge = 'New'
+    expect(validate(stray)).toBe(false)
+
+    const fragment = newPlan()
+    fragment.guestHome.features[0].fragment = { kind: 'chart' as never, rows: [] }
+    expect(validate(fragment)).toBe(false)
+  })
+
+  test('declares no count as minItems/maxItems — counts live in the descriptions', () => {
+    const text = JSON.stringify(ScaffoldPlanSchema)
+
+    expect(text).not.toContain('minItems')
+    expect(text).not.toContain('maxItems')
+    expect(BENTO_FRAGMENT_KINDS).toEqual(['list', 'note', 'people', 'steps'])
+  })
+})

package/tests/skills.spec.ts

@@ -1,7 +1,8 @@
 import { describe, expect, it } from 'bun:test'
 
-import { ViableSkill } from '../src/skills/consts.js'
-import { viableSkill } from '../src/skills/catalogue.js'
+import { SKILL_ORDER, ViableSkill } from '../src/skills/consts.js'
+import { VIABLE_SKILLS, viableSkill } from '../src/skills/catalogue.js'
+import { VIABLE_PERSONAS, ViablePersona } from '../src/skills/roles.js'
 
 /**
  * Pins the catalogue's own "wrap exactly once" teaching — the incident this guards against was
@@ -45,3 +46,63 @@ describe('viable-common catalogue — handler wrap-once', () => {
     }
   })
 })
+
+/**
+ * The prompt service SKIPS an alias it cannot resolve, so a skill in the enum with no body is a
+ * rule no model ever receives — nothing fails, the prompt simply lacks it.
+ */
+describe('viable-common catalogue — completeness', () => {
+  it('declares one body and one sort weight for every skill in the enum', () => {
+    const declared = VIABLE_SKILLS.map(entry => entry.alias)
+
+    expect(Object.values(ViableSkill).filter(alias => !declared.includes(alias))).toEqual([])
+    expect(new Set(declared).size).toBe(declared.length)
+    for (const alias of Object.values(ViableSkill)) {
+      expect(typeof SKILL_ORDER[alias], alias).toBe('number')
+    }
+  })
+})
+
+/**
+ * The house style is taught in two places a designer and a coder read — the visual designer's
+ * persona and the shadcn skill — and a template ships the same values. Neither may drift back
+ * to teaching the decoration the template now paints flat.
+ */
+describe('viable-common catalogue — the house style', () => {
+  it('ShadcnUi teaches the white ground, one accent and flat depth, and repaints the old classes', () => {
+    const body = viableSkill(ViableSkill.ShadcnUi).body
+
+    expect(body).toContain('bg-background')
+    expect(body).toContain('ONE product accent')
+    expect(body).toContain('shadow-floating')
+    expect(body).toContain('REPAINTED flat')
+    expect(body).toContain('explicitly asks')
+    expect(body).not.toContain('DECORATION VOCABULARY')
+    expect(body).not.toMatch(/\/\/ right[^\n]*gradient/)
+    expect(body).toContain('SelectItem')
+  })
+
+  it('the visual designer defaults to the house style and changes it only on an explicit ask', () => {
+    const role = VIABLE_PERSONAS[ViablePersona.VisualDesigner].role
+
+    expect(role).toContain('white ground')
+    expect(role).toContain('ONE')
+    expect(role).toContain('explicitly asks')
+    expect(role).not.toContain('expressive and bright')
+    expect(role).not.toMatch(/default to .*gradients/)
+  })
+
+  it('LandingGate teaches the gate card, the synchronous handoff and the screen that reads it', () => {
+    const body = viableSkill(ViableSkill.LandingGate).body
+
+    expect(body).toContain('data-home-gate')
+    expect(body).toContain('aria-pressed')
+    expect(body).toContain('writeLandingHandoff(target')
+    expect(body).toContain('readLandingHandoff')
+    expect(body).toContain('clearLandingHandoff()')
+    expect(body).toContain("useLogin(target)")
+    expect(body).toContain('SYNCHRONOUS')
+    expect(body).toContain('WRONG')
+    expect(body).not.toContain('${')
+  })
+})