@owlmeans/viable-common 0.0.18 → 0.0.20

package/src/planning/errors.ts

@@ -0,0 +1,117 @@
+import { ResilientError } from '@owlmeans/error'
+import { ResourceError } from '@owlmeans/resource'
+
+/**
+ * The project and story refusals every process that writes a planning card can raise.
+ *
+ * Declared HERE rather than by the platform because the viable planning plugin throws them from a
+ * process-neutral package, and a refusal class that exists only on one side of a hop cannot be
+ * `instanceof`-matched on the other. Type names and markers are wire contracts: the browser
+ * phrases a refusal by marker (`viable-project:…`), so neither may change. The bases are declared
+ * with them because an error class is unmarshalled by type name with the LAST registration
+ * winning — a second declaration of a base anywhere else would replace this one.
+ */
+export class ProjectResourceError extends ResourceError {
+  public static override typeName = `ViableProject${ResourceError.typeName}`
+
+  constructor(message: string = 'error') {
+    super(`viable-project:${message}`)
+    this.type = ProjectResourceError.typeName
+  }
+}
+
+/** No project card with that id in the caller's organization. */
+export class ProjectNotFound extends ProjectResourceError {
+  public static override typeName = `NotFound${ProjectResourceError.typeName}`
+
+  constructor(message: string = 'error') {
+    super(`not-found:${message}`)
+    this.type = ProjectNotFound.typeName
+  }
+}
+
+/** The project exists, and the caller may not act on it. */
+export class ProjectPermissionError extends ProjectResourceError {
+  public static override typeName = `Permission${ProjectResourceError.typeName}`
+
+  constructor(message: string = 'error') {
+    super(`permission:${message}`)
+    this.type = ProjectPermissionError.typeName
+  }
+}
+
+export class ProjectStoryError extends ProjectResourceError {
+  public static override typeName = `Story${ProjectResourceError.typeName}`
+
+  constructor(message: string = 'error') {
+    super(`story:${message}`)
+    this.type = ProjectStoryError.typeName
+  }
+}
+
+/** No story card with that id or code under the project. */
+export class ProjectStoryNotFound extends ProjectStoryError {
+  public static override typeName = `NotFound${ProjectStoryError.typeName}`
+
+  constructor(message: string = 'error') {
+    super(`not-found:${message}`)
+    this.type = ProjectStoryNotFound.typeName
+  }
+}
+
+/**
+ * The story is in a state the requested write does not apply to.
+ *
+ * `wrong-status` is the marker a completed story's refusal carries — the manager matches the whole
+ * `viable-project:story:missconfigured:` prefix, so the reason after it is free to grow.
+ */
+export class ProjectStoryMissconfigured extends ProjectStoryError {
+  public static override typeName = `Missconfigured${ProjectStoryError.typeName}`
+
+  constructor(message: string = 'error') {
+    super(`missconfigured:${message}`)
+    this.type = ProjectStoryMissconfigured.typeName
+  }
+}
+
+export class ProjectError extends ResilientError {
+  public static override typeName = `ViableProject${ResilientError.typeName}`
+
+  constructor(message: string = 'error') {
+    super(ProjectError.typeName, `viable-project:${message}`)
+  }
+}
+
+export class ProjectAgentError extends ProjectError {
+  public static override typeName = `Agent${ProjectError.typeName}`
+
+  constructor(message: string = 'error') {
+    super(`agent:${message}`)
+    this.type = ProjectAgentError.typeName
+  }
+}
+
+/**
+ * The project's agent is already busy with what was asked for.
+ *
+ * `story` is the reason a second story start carries: one story of a project is in progress at a
+ * time, because a develop run holds the project's sandbox for its whole length.
+ */
+export class ProjectAgentOccupied extends ProjectAgentError {
+  public static override typeName = `Occupied${ProjectAgentError.typeName}`
+
+  constructor(message: string = 'error') {
+    super(`occupied:${message}`)
+    this.type = ProjectAgentOccupied.typeName
+  }
+}
+
+ResilientError.registerErrorClass(ProjectResourceError)
+ResilientError.registerErrorClass(ProjectNotFound)
+ResilientError.registerErrorClass(ProjectPermissionError)
+ResilientError.registerErrorClass(ProjectStoryError)
+ResilientError.registerErrorClass(ProjectStoryNotFound)
+ResilientError.registerErrorClass(ProjectStoryMissconfigured)
+ResilientError.registerErrorClass(ProjectError)
+ResilientError.registerErrorClass(ProjectAgentError)
+ResilientError.registerErrorClass(ProjectAgentOccupied)

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 }[]