@owlmeans/viable-common 0.0.19 → 0.0.20

package/src/planning/flows.ts

@@ -0,0 +1,204 @@
+import { IntrinsicPolicy, IntrinsicStatus, SpecificationFormat, WorkcardKind } from '@owlmeans/planning'
+import type {
+  AnyTypeSchema, ProjectTypeSchema, RelationshipType, SpecificationSlot, StatusFlowSchema,
+  WorkcardTypeSchema,
+} from '@owlmeans/planning'
+import { STORY_DESIGN_VERSION } from '../design/consts.js'
+import { StoryDesignSchema } from '../design/schemas.js'
+import { ScaffoldPlanSchema } from '../scaffold/schemas.js'
+import {
+  VIABLE_BUG_CODE, VIABLE_BUG_TYPE, VIABLE_DESIGN_REVISIONS_KEPT, VIABLE_IMPROVEMENT_CODE,
+  VIABLE_IMPROVEMENT_TYPE, VIABLE_PROJECT_CODE, VIABLE_PROJECT_FLOW, VIABLE_PROJECT_TYPE,
+  VIABLE_REQUIREMENT_CODE, VIABLE_REQUIREMENT_TYPE, VIABLE_SPEC_FLOW, VIABLE_SPEC_TYPE,
+  VIABLE_STORY_CODE, VIABLE_STORY_FLOW, VIABLE_STORY_TYPE, ViableProjectStatus,
+  ViableProjectTransition, ViableRelationship, ViableSpecCategory, ViableSpecStatus,
+  ViableStoryStatus, ViableStoryTransition, ViableTone,
+} from './consts.js'
+import {
+  ViableOpenFieldsSchema, ViableProjectFieldsSchema, ViableSpecFieldsSchema, ViableStoryFieldsSchema,
+} from './schemas.js'
+
+/**
+ * The story flow.
+ *
+ * `failed` maps to PLANNED: a failed story is work still to do, so "done" is the closed count and
+ * a retry is simply `start` again. `reset` from anywhere is the manual recovery — the one move a
+ * completed story still accepts.
+ */
+export const VIABLE_STORY_FLOW_SCHEMA: StatusFlowSchema = {
+  id: VIABLE_STORY_FLOW,
+  version: 1,
+  statuses: [
+    { key: ViableStoryStatus.Planned, intrinsic: IntrinsicStatus.Planned, initial: true, tone: ViableTone.Blue },
+    { key: ViableStoryStatus.InProgress, intrinsic: IntrinsicStatus.InProgress, tone: ViableTone.Yellow },
+    { key: ViableStoryStatus.Completed, intrinsic: IntrinsicStatus.Closed, tone: ViableTone.Green },
+    { key: ViableStoryStatus.Failed, intrinsic: IntrinsicStatus.Planned, tone: ViableTone.Red },
+  ],
+  transitions: [
+    {
+      name: ViableStoryTransition.Start,
+      from: [ViableStoryStatus.Planned, ViableStoryStatus.Failed],
+      to: ViableStoryStatus.InProgress,
+      explicit: true,
+    },
+    {
+      name: ViableStoryTransition.Complete,
+      from: [ViableStoryStatus.InProgress],
+      to: ViableStoryStatus.Completed,
+      explicit: true,
+    },
+    {
+      name: ViableStoryTransition.Fail,
+      from: [ViableStoryStatus.InProgress],
+      to: ViableStoryStatus.Failed,
+    },
+    { name: ViableStoryTransition.Reset, from: '*', to: ViableStoryStatus.Planned, explicit: true },
+  ],
+}
+
+/**
+ * The project flow.
+ *
+ * A create lands at `draft`; confirming the brief is `confirm`; the end of an initialization is
+ * `activate`. A reinitialization and a failed initialization are SLOT facts, not transitions, and
+ * destroying a project is a `delete` plus the platform's cascade — never `archive`.
+ */
+export const VIABLE_PROJECT_FLOW_SCHEMA: StatusFlowSchema = {
+  id: VIABLE_PROJECT_FLOW,
+  version: 1,
+  statuses: [
+    { key: ViableProjectStatus.Draft, intrinsic: IntrinsicStatus.Planned, initial: true, tone: ViableTone.Blue },
+    { key: ViableProjectStatus.Confirmed, intrinsic: IntrinsicStatus.InProgress, tone: ViableTone.Yellow },
+    { key: ViableProjectStatus.Active, intrinsic: IntrinsicStatus.InProgress, tone: ViableTone.Green },
+    { key: ViableProjectStatus.Archived, intrinsic: IntrinsicStatus.Closed, tone: ViableTone.Neutral },
+  ],
+  transitions: [
+    {
+      name: ViableProjectTransition.Confirm,
+      from: [ViableProjectStatus.Draft],
+      to: ViableProjectStatus.Confirmed,
+      explicit: true,
+    },
+    {
+      name: ViableProjectTransition.Activate,
+      from: [ViableProjectStatus.Confirmed],
+      to: ViableProjectStatus.Active,
+    },
+    { name: ViableProjectTransition.Archive, from: '*', to: ViableProjectStatus.Archived, explicit: true },
+    {
+      name: ViableProjectTransition.Reopen,
+      from: [ViableProjectStatus.Archived],
+      to: ViableProjectStatus.Active,
+      explicit: true,
+    },
+  ],
+}
+
+/** A document is written or revised; it has no lifecycle to move through. */
+export const VIABLE_SPEC_FLOW_SCHEMA: StatusFlowSchema = {
+  id: VIABLE_SPEC_FLOW,
+  version: 1,
+  statuses: [
+    { key: ViableSpecStatus.Current, intrinsic: IntrinsicStatus.Closed, initial: true, tone: ViableTone.Neutral },
+  ],
+  transitions: [],
+}
+
+const slot = (
+  category: ViableSpecCategory, format: SpecificationFormat, extra: Partial<SpecificationSlot> = {},
+): SpecificationSlot => ({ category, format, type: VIABLE_SPEC_TYPE, ...extra })
+
+/** The brief a person confirms, and the plan the scaffold draws from it. */
+export const VIABLE_PROJECT_SLOTS: SpecificationSlot[] = [
+  slot(ViableSpecCategory.Specification, SpecificationFormat.Markdown, { required: true }),
+  slot(ViableSpecCategory.Vision, SpecificationFormat.Markdown),
+  slot(ViableSpecCategory.DesignSystem, SpecificationFormat.Markdown),
+  slot(ViableSpecCategory.Scaffold, SpecificationFormat.Json, {
+    revisioned: true, keepRevisions: VIABLE_DESIGN_REVISIONS_KEPT, schema: ScaffoldPlanSchema,
+  }),
+]
+
+/** A story's design — the payload the implementation stage consumes. */
+export const VIABLE_STORY_SLOTS: SpecificationSlot[] = [
+  slot(ViableSpecCategory.Design, SpecificationFormat.Json, {
+    revisioned: true,
+    keepRevisions: VIABLE_DESIGN_REVISIONS_KEPT,
+    schema: StoryDesignSchema,
+    version: STORY_DESIGN_VERSION,
+  }),
+]
+
+const storyLink = (name: ViableRelationship): RelationshipType =>
+  ({ name, from: [VIABLE_STORY_TYPE], to: [VIABLE_STORY_TYPE], single: true })
+
+export const VIABLE_STORY_RELATIONSHIPS: RelationshipType[] = [
+  storyLink(ViableRelationship.Follows),
+  storyLink(ViableRelationship.SharesWidget),
+  storyLink(ViableRelationship.SharesScreen),
+]
+
+export const VIABLE_PROJECT_TYPE_SCHEMA: ProjectTypeSchema = {
+  type: VIABLE_PROJECT_TYPE,
+  kind: WorkcardKind.Project,
+  version: 1,
+  fields: ViableProjectFieldsSchema,
+  flows: [VIABLE_PROJECT_FLOW],
+  intrinsic: IntrinsicPolicy.Primary,
+  specifications: VIABLE_PROJECT_SLOTS,
+  code: VIABLE_PROJECT_CODE,
+  cardTypes: [VIABLE_STORY_TYPE],
+}
+
+export const VIABLE_STORY_TYPE_SCHEMA: WorkcardTypeSchema = {
+  type: VIABLE_STORY_TYPE,
+  kind: WorkcardKind.Card,
+  version: 1,
+  fields: ViableStoryFieldsSchema,
+  flows: [VIABLE_STORY_FLOW],
+  intrinsic: IntrinsicPolicy.Primary,
+  specifications: VIABLE_STORY_SLOTS,
+  relationships: VIABLE_STORY_RELATIONSHIPS,
+  code: VIABLE_STORY_CODE,
+}
+
+export const VIABLE_SPEC_TYPE_SCHEMA: WorkcardTypeSchema = {
+  type: VIABLE_SPEC_TYPE,
+  kind: WorkcardKind.Specification,
+  version: 1,
+  fields: ViableSpecFieldsSchema,
+  flows: [VIABLE_SPEC_FLOW],
+  specifications: [],
+}
+
+const reserved = (type: string, code: WorkcardTypeSchema['code']): WorkcardTypeSchema => ({
+  type,
+  kind: WorkcardKind.Card,
+  version: 1,
+  fields: ViableOpenFieldsSchema,
+  flows: [VIABLE_STORY_FLOW],
+  intrinsic: IntrinsicPolicy.Primary,
+  specifications: [],
+  code,
+})
+
+/** Registered so their prefixes and flow are decided once; not creatable under a project yet. */
+export const VIABLE_RESERVED_TYPE_SCHEMAS: WorkcardTypeSchema[] = [
+  reserved(VIABLE_BUG_TYPE, VIABLE_BUG_CODE),
+  reserved(VIABLE_IMPROVEMENT_TYPE, VIABLE_IMPROVEMENT_CODE),
+  reserved(VIABLE_REQUIREMENT_TYPE, VIABLE_REQUIREMENT_CODE),
+]
+
+/** Every Viable type — what a planning plugin registers. */
+export const VIABLE_TYPE_SCHEMAS: AnyTypeSchema[] = [
+  VIABLE_PROJECT_TYPE_SCHEMA,
+  VIABLE_STORY_TYPE_SCHEMA,
+  VIABLE_SPEC_TYPE_SCHEMA,
+  ...VIABLE_RESERVED_TYPE_SCHEMAS,
+]
+
+/** Every Viable flow — registered beside the types. */
+export const VIABLE_FLOW_SCHEMAS: StatusFlowSchema[] = [
+  VIABLE_PROJECT_FLOW_SCHEMA,
+  VIABLE_STORY_FLOW_SCHEMA,
+  VIABLE_SPEC_FLOW_SCHEMA,
+]

package/src/planning/helpers.ts

@@ -0,0 +1,133 @@
+import { WorkcardKind } from '@owlmeans/planning'
+import type { Specification, Workcard } from '@owlmeans/planning'
+import { ProjectArea } from '../areas/consts.js'
+import type { StoryDraft } from '../areas/types.js'
+import type { AgentProject, UserStory } from '../ba/types.js'
+import { userStoryOfDesign } from '../design/helpers.js'
+import type { StoryDesign } from '../design/types.js'
+import type { StoryWriteInput } from '../metadata/types.js'
+import {
+  VIABLE_PROJECT_TYPE, VIABLE_STORY_TYPE, VIABLE_USER_CHANNELS, ViableSpecCategory,
+} from './consts.js'
+import { ProjectStoryMissconfigured } from './errors.js'
+import type {
+  StoryWriteContent, ViableProjectCard, ViableProjectFields, ViableStoryCard, ViableStoryFields,
+} from './types.js'
+
+/** A `viable:project` card — kind AND type, since a foreign provider may share either alone. */
+export const isViableProject = (card?: Workcard | null): card is ViableProjectCard =>
+  card != null && card.kind === WorkcardKind.Project && card.type === VIABLE_PROJECT_TYPE
+
+/** A `viable:user-story` card. */
+export const isViableStory = (card?: Workcard | null): card is ViableStoryCard =>
+  card != null && card.kind === WorkcardKind.Card && card.type === VIABLE_STORY_TYPE
+
+/** Whether a write came from a person (`web`, `connect`) rather than the platform's own runs. */
+export const isUserChannel = (channel?: string | null): boolean =>
+  channel != null && VIABLE_USER_CHANNELS.includes(channel)
+
+export const projectFieldsOf = (card: Workcard): ViableProjectFields =>
+  (card.fields ?? {}) as ViableProjectFields
+
+/**
+ * A story card's fields, with the two required ones always answered.
+ *
+ * An absent area reads as `guest` — the area that guards nothing — and an absent primary flag as
+ * `false`, so a reader never branches on a card written by a store that dropped them.
+ */
+export const storyFieldsOf = (card: Workcard): ViableStoryFields => {
+  const fields = (card.fields ?? {}) as Partial<ViableStoryFields>
+
+  return { ...fields, area: fields.area ?? ProjectArea.Guest, primary: fields.primary === true }
+}
+
+/** The draft shape the analysis prompts and moderation take, from a card. */
+export const storyDraftOf = (card: Workcard): StoryDraft =>
+  ({ story: card.title, area: storyFieldsOf(card).area })
+
+/**
+ * The aggregate the coders take, for a story CARD.
+ *
+ * The card wins on the narrative, the code, the area and the actor — a person may have changed any
+ * of them since the design was written. The design supplies what only it knows: the entities and
+ * the screens. Without a design the aggregate has no screens yet.
+ */
+export const userStoryOf = (card: Workcard, design?: StoryDesign | null): UserStory => {
+  const fields = storyFieldsOf(card)
+  const base: UserStory = design != null
+    ? userStoryOfDesign(design)
+    : { story: card.title, area: fields.area, entity: null as unknown as string, entities: [], screens: [] }
+  const code = card.code ?? base.code
+
+  return {
+    ...base,
+    story: card.title,
+    ...(code != null ? { code } : {}),
+    area: fields.area,
+    ...(fields.actor != null ? { actor: fields.actor } : {}),
+  }
+}
+
+/**
+ * The current document of one category among a card's specifications.
+ *
+ * The highest revision wins, then the most recently updated; a category nobody wrote answers
+ * `null`.
+ */
+export const currentSpecOf = (
+  specs: readonly Specification[], category: string,
+): Specification | null =>
+  specs
+    .filter(spec => spec.category === category)
+    .reduce<Specification | null>((best, spec) => {
+      if (best == null) return spec
+      const byRevision = (spec.revision ?? 0) - (best.revision ?? 0)
+      if (byRevision !== 0) return byRevision > 0 ? spec : best
+
+      return (spec.updatedAt ?? spec.createdAt) > (best.updatedAt ?? best.createdAt) ? spec : best
+    }, null)
+
+/** The body of a category's current document, `''` when there is none. */
+export const currentSpecBody = (specs: readonly Specification[], category: string): string =>
+  currentSpecOf(specs, category)?.body ?? ''
+
+/**
+ * The brief a generator reads, assembled from the project card and its specifications.
+ *
+ * `name` is the card's title and `alias` its code; a brief part nobody wrote is `''`, which is
+ * what every prompt already treats as "not stated".
+ */
+export const projectBriefOf = (project: Workcard, specs: readonly Specification[]): AgentProject => {
+  const { language } = projectFieldsOf(project)
+
+  return {
+    name: project.title,
+    ...(project.code != null ? { alias: project.code } : {}),
+    description: project.description ?? '',
+    specification: currentSpecBody(specs, ViableSpecCategory.Specification),
+    designSystem: currentSpecBody(specs, ViableSpecCategory.DesignSystem),
+    vision: currentSpecBody(specs, ViableSpecCategory.Vision),
+    ...(language != null ? { language } : {}),
+  }
+}
+
+/**
+ * What the metadata store writes to `docs/stories/<code>.md`, from the card and a run's content.
+ *
+ * The CODE is the target's only story identifier — a card id never reaches a target file — so a
+ * story card without one is refused rather than filed under its id.
+ */
+export const storyWriteInputOf = (card: Workcard, content: StoryWriteContent): StoryWriteInput => {
+  if (card.code == null || card.code === '') {
+    throw new ProjectStoryMissconfigured('no-code')
+  }
+  const { status, ...rest } = content
+
+  return {
+    ...rest,
+    code: card.code,
+    narrative: card.title,
+    status: status ?? card.status,
+    primary: storyFieldsOf(card).primary,
+  }
+}

package/src/planning/index.ts

@@ -0,0 +1,6 @@
+export * from './consts.js'
+export * from './errors.js'
+export * from './schemas.js'
+export * from './flows.js'
+export * from './helpers.js'
+export type * from './types.js'

package/src/planning/schemas.ts

@@ -0,0 +1,70 @@
+import type { JSONSchemaType } from 'ajv'
+import { CODE_MAX } from '@owlmeans/planning'
+import { ProjectArea } from '../areas/consts.js'
+import { StoryKind } from '../ba/consts.js'
+import { ConnectLlm, ConnectTarget } from '../connect/consts.js'
+import { ProjectOriginSchema } from '../convert/schemas.js'
+import { StoryActor } from '../design/runtime.js'
+import type { ViableProjectFields, ViableStoryFields } from './types.js'
+
+/**
+ * The `fields` schema of a `viable:project` card.
+ *
+ * A record-element schema: hand-written, cast, every optional key nullable with its type, every
+ * nullable enum listing `null`. Plain strings where the vocabulary grows in a library this record
+ * does not redeploy with (blueprint, case, game kind).
+ */
+export const ViableProjectFieldsSchema = {
+  type: 'object',
+  properties: {
+    formerAliases: {
+      type: 'array', items: { type: 'string', minLength: 1, maxLength: CODE_MAX }, nullable: true,
+    },
+    language: { type: 'string', minLength: 2, maxLength: 16, nullable: true },
+    blueprint: { type: 'string', minLength: 1, maxLength: 64, nullable: true },
+    blueprintCase: { type: 'string', minLength: 1, maxLength: 64, nullable: true },
+    gameKind: { type: 'string', minLength: 1, maxLength: 64, nullable: true },
+    target: { type: 'string', enum: [...Object.values(ConnectTarget), null], nullable: true },
+    origin: { ...ProjectOriginSchema, nullable: true },
+    connectLlmMode: { type: 'string', enum: [...Object.values(ConnectLlm), null], nullable: true },
+    converterLlmMode: { type: 'string', enum: [...Object.values(ConnectLlm), null], nullable: true },
+  },
+  required: [],
+  additionalProperties: false,
+} as unknown as JSONSchemaType<ViableProjectFields>
+
+/**
+ * The `fields` schema of a `viable:user-story` card.
+ *
+ * `area` is required, and a create that carries none is still valid by the time it is checked:
+ * validation runs after the planning middlewares, and the viable plugin's re-format hook fills the
+ * area of a narrative a person wrote.
+ */
+export const ViableStoryFieldsSchema = {
+  type: 'object',
+  properties: {
+    area: { type: 'string', enum: Object.values(ProjectArea) },
+    primary: { type: 'boolean' },
+    actor: { type: 'string', enum: [...Object.values(StoryActor), null], nullable: true },
+    warning: { type: 'string', maxLength: 1024, nullable: true },
+    kind: { type: 'string', enum: [...Object.values(StoryKind), null], nullable: true },
+  },
+  required: ['area', 'primary'],
+  additionalProperties: false,
+} as unknown as JSONSchemaType<ViableStoryFields>
+
+/** The open `fields` of a reserved card type — nothing is decided about them yet. */
+export const ViableOpenFieldsSchema = {
+  type: 'object',
+  properties: {},
+  required: [],
+  additionalProperties: true,
+} as unknown as JSONSchemaType<Record<string, unknown>>
+
+/** A document carries nothing under `fields`: its payload is the specification body. */
+export const ViableSpecFieldsSchema = {
+  type: 'object',
+  properties: {},
+  required: [],
+  additionalProperties: false,
+} as unknown as JSONSchemaType<Record<string, never>>

package/src/planning/types.ts

@@ -0,0 +1,75 @@
+import type { Card, Project, Specification } from '@owlmeans/planning'
+import type { ProjectArea } from '../areas/consts.js'
+import type { StoryKind } from '../ba/consts.js'
+import type { ConnectLlm, ConnectTarget } from '../connect/consts.js'
+import type { ProjectOrigin } from '../convert/types.js'
+import type { StoryActor } from '../design/runtime.js'
+import type { StoryWriteInput } from '../metadata/types.js'
+
+/**
+ * What a `viable:project` card keeps under `fields`.
+ *
+ * The alias is the card's `code`, the name its `title`; the brief parts are specifications. Every
+ * key is optional: a project created before a field existed carries none, and an absent value
+ * means the platform default (inherit a mode, the default blueprint, a cloud slot).
+ */
+export type ViableProjectFields = {
+  /** Aliases this project gave up. Names are retired, never freed to a sibling project. */
+  formerAliases?: string[]
+  /** The IETF tag generated UI text is written in. */
+  language?: string
+  /** The blueprint id the project was drawn with. */
+  blueprint?: string
+  /** The blueprint case classified from the prompt. Absent applies no patch. */
+  blueprintCase?: string
+  /** How a game is played; absent for every other case. */
+  gameKind?: string
+  /** Where the tree lives; absent is the platform's own slot. */
+  target?: ConnectTarget
+  /** Where converted code came from; present only on an import. */
+  origin?: ProjectOrigin
+  /** Who performs a run's model calls on this project; absent inherits the owner's preference. */
+  connectLlmMode?: ConnectLlm
+  /** Who performs a conversion's model calls on this project; absent inherits. */
+  converterLlmMode?: ConnectLlm
+}
+
+/**
+ * What a `viable:user-story` card keeps under `fields`.
+ *
+ * The narrative is the card's `title`, the flow ordinal its `order` (a double — a connective story
+ * sits between two flow steps), the status its primary flow status.
+ */
+export type ViableStoryFields = {
+  /** The audience acting in the story; its screens hang under this area. */
+  area: ProjectArea
+  /** The story whose screen is the project's front door. Exactly one per project. */
+  primary: boolean
+  /** Who acts; absent is a person. */
+  actor?: StoryActor
+  /** Why the last development did not end cleanly. Written as `''` to clear. */
+  warning?: string
+  /** Which half of the analysis the story came from. */
+  kind?: StoryKind
+}
+
+export interface ViableProjectCard extends Project {
+  fields: ViableProjectFields
+}
+
+export interface ViableStoryCard extends Card {
+  fields: ViableStoryFields
+}
+
+/** A document under a Viable card — the brief parts, the scaffold plan, a story design. */
+export type ViableSpecification = Specification
+
+/**
+ * What a develop run hands the metadata store beside the card.
+ *
+ * The code, the narrative and the primary flag are the CARD's and are never passed separately — a
+ * second copy is a second answer. `status` defaults to the card's own.
+ */
+export type StoryWriteContent =
+  & Omit<StoryWriteInput, 'code' | 'narrative' | 'primary' | 'status'>
+  & { status?: string }

package/src/scaffold/schemas.ts

@@ -168,15 +168,20 @@ const GuestHomePlanSchema: JSONSchemaType<GuestHomePlan> = {
     hero: {
       type: 'object',
       properties: {
-        eyebrow: { type: 'string', description: 'A 2-4 word positioning phrase above the headline' },
         headline: {
           type: 'string',
           description: 'The product\'s promise in one line, under 9 words. Never the product name alone'
         },
         sub: { type: 'string', description: 'One or two sentences: what it does and who it is for' },
         cta: { type: 'string', description: 'The call-to-action label, 2-3 words' },
+        eyebrow: {
+          type: 'string', nullable: true,
+          description: 'OPTIONAL, normally omitted. A small badge above the headline - set it only when'
+            + ' the specification explicitly asks for a label there. A landing page carries no badge by'
+            + ' default: the headline is what positions the product'
+        },
       },
-      required: ['eyebrow', 'headline', 'sub', 'cta'],
+      required: ['headline', 'sub', 'cta'],
       additionalProperties: false,
     },
     problem: {

package/src/scaffold/types.ts

@@ -91,7 +91,16 @@ export interface ProductIdentity {
 
 /** The guest area's landing page — the product's public face. */
 export interface GuestHomePlan {
-  hero: { eyebrow: string, headline: string, sub: string, cta: string }
+  hero: {
+    headline: string
+    sub: string
+    cta: string
+    /**
+     * A badge above the headline — OPTIONAL and normally absent. A landing page carries no badge
+     * unless its specification asks for one; the headline is what positions the product.
+     */
+    eyebrow?: string
+  }
   problem: { title: string, text: string }
   solution: { title: string, text: string }
   features: { title: string, text: string }[]

package/tests/branding.spec.ts

@@ -0,0 +1,37 @@
+import { describe, expect, it } from 'bun:test'
+
+import { brandingEnv } from '../src/branding.js'
+
+/**
+ * `BRANDING_CREDIT` is the one key whose ABSENCE means something different from an explicit
+ * empty string — the platform side of the bug this pins: `brandingCredit: ''` stored to hide the
+ * platform credit must survive as `BRANDING_CREDIT: ''`, not fall back to the "shown" default.
+ */
+describe('brandingEnv', () => {
+  it('emits an empty BRANDING_CREDIT for an explicitly hidden credit', () => {
+    expect(brandingEnv({ brandingCredit: '' }).BRANDING_CREDIT).toBe('')
+  })
+
+  it('emits BRANDING_CREDIT=1 when the credit is shown', () => {
+    expect(brandingEnv({ brandingCredit: '1' }).BRANDING_CREDIT).toBe('1')
+  })
+
+  it('defaults to shown (BRANDING_CREDIT=1) when nothing was ever delivered', () => {
+    // The safe direction: a delivery that lost the value keeps the credit rather than
+    // silently giving away a paid feature.
+    expect(brandingEnv({}).BRANDING_CREDIT).toBe('1')
+  })
+
+  it('composes the rest of the branding env from whatever is present, blank otherwise', () => {
+    expect(brandingEnv({
+      brandingCopyright: '© 2026 Acme', projectName: 'Acme CRM',
+    })).toEqual({
+      BRANDING_COPYRIGHT: '© 2026 Acme',
+      BRANDING_ORGANIZATION: '',
+      BRANDING_TERMS_URL: '',
+      BRANDING_PRIVACY_URL: '',
+      BRANDING_CREDIT: '1',
+      BRANDING_PRODUCT: 'Acme CRM',
+    })
+  })
+})

package/tests/connect-entrypoints.spec.ts

@@ -2,8 +2,10 @@ import { describe, expect, test } from 'bun:test'
 import { 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 { connect, ConnectJobKind } from '../src/connect/consts.js'
 import { connectProtocols } from '../src/connect/entrypoints.js'
+import { JOB_SEPARATOR, jobIdOf, parseJobId } from '../src/connect/jobs.js'
+import { connectRef } from '../src/connect/references.js'
 
 describe('@owlmeans/viable-common — connector protocol tree', () => {
   const tree = connectProtocols({
@@ -19,7 +21,37 @@ 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(38)
-    expect(new Set(protocols(tree).map(protocol => protocol.alias)).size).toBe(38)
+    expect(protocols(tree)).toHaveLength(32)
+    expect(new Set(protocols(tree).map(protocol => protocol.alias)).size).toBe(32)
+  })
+
+  test('carries no story routes: stories are planning cards served by the planning tree', () => {
+    expect((tree as Record<string, unknown>).story).toBeUndefined()
+    expect((connect as Record<string, unknown>).story).toBeUndefined()
+    expect((connectRef as unknown as Record<string, unknown>).story).toBeUndefined()
+    expect(protocols(tree).some(protocol => protocol.alias.includes(':story:'))).toBe(false)
+  })
+})
+
+describe('@owlmeans/viable-common — connector job ids', () => {
+  test('a story job id names the card and splits back into its parts', () => {
+    const id = jobIdOf(ConnectJobKind.StoryDevelop, 'project-card', 'story-card')
+
+    expect(id).toBe(['story-develop', 'project-card', 'story-card'].join(JOB_SEPARATOR))
+    expect(parseJobId(id)).toEqual({
+      kind: ConnectJobKind.StoryDevelop, projectId: 'project-card', suffix: 'story-card',
+    })
+  })
+
+  test('a job with no subject carries no suffix', () => {
+    expect(parseJobId(jobIdOf(ConnectJobKind.ProjectInit, 'p1'))).toEqual({
+      kind: ConnectJobKind.ProjectInit, projectId: 'p1',
+    })
+  })
+
+  test('a suffix that contains the separator is rejoined, never truncated', () => {
+    const suffix = `run${JOB_SEPARATOR}tail`
+
+    expect(parseJobId(jobIdOf(ConnectJobKind.PipelineResume, 'p1', suffix)).suffix).toBe(suffix)
   })
 })

package/tests/design.spec.ts

@@ -4,7 +4,7 @@ import { ProjectArea } from '../src/areas/consts.js'
 import { SpecCategory } from '../src/ba/consts.js'
 import {
   DesignStaleness, STORY_DESIGN_VERSION, StoryDesignSchema, designHash, designStaleness,
-  emptyStoryDesign, screenMapOf, userStoryOf,
+  emptyStoryDesign, screenMapOf, userStoryOfDesign,
 } from '../src/design/index.js'
 import type { StoryDesign } from '../src/design/index.js'
 
@@ -45,7 +45,7 @@ describe('viable-common - the design aggregate', () => {
   test('derives the UserStory the coders take, carrying the story code', () => {
     // The scaffold stamps every placeholder it draws with the code, so a run keyed by anything
     // else cannot recognise its own reservation.
-    const story = userStoryOf(withScreens())
+    const story = userStoryOfDesign(withScreens())
 
     expect(story.code).toBe('US-ABC12')
     expect(story.area).toBe(ProjectArea.User)
@@ -60,7 +60,7 @@ describe('viable-common - the design aggregate', () => {
     const broken = withScreens()
     broken.screens[0].components = ['BookingList', 'Ghost']
 
-    expect(userStoryOf(broken).screens[0].components.map(entry => entry.name)).toEqual(['BookingList'])
+    expect(userStoryOfDesign(broken).screens[0].components.map(entry => entry.name)).toEqual(['BookingList'])
   })
 
   test('screenMapOf is the shape every UX and UI prompt takes', () => {