@owlmeans/viable-common 0.0.43 → 0.0.45

package/src/intent/entrypoints.ts

@@ -3,7 +3,7 @@ import { frontend, route, RouteMethod } from '@owlmeans/route'
 import { INTENT_API_PATH, INTENT_LANDING_PATH, intent } from './consts.js'
 import { IntentPickupBodySchema, IntentStashBodySchema } from './schemas.js'
 import type {
-  IntentPickupBody, IntentPickupResult, IntentProtocolOptions, IntentStashBody, IntentStashResult,
+  IntentPickupBody, IntentPickupResult, IntentProtocolOptions, IntentProtocols, IntentStashBody, IntentStashResult,
 } from './types.js'
 
 /**
@@ -20,7 +20,7 @@ import type {
  * The landing screen is `sticky`, like the OAuth consent screens: it is an ordinary in-app screen
  * that a visitor arrives at directly from another origin.
  */
-export const makeIntentProtocols = (opts: IntentProtocolOptions = {}) => {
+export const makeIntentProtocols = (opts: IntentProtocolOptions = {}): IntentProtocols => {
   const base = openProtocol(route(intent.base, opts.path ?? INTENT_API_PATH))
 
   return {
@@ -40,4 +40,3 @@ export const makeIntentProtocols = (opts: IntentProtocolOptions = {}) => {
   }
 }
 
-export type IntentProtocols = ReturnType<typeof makeIntentProtocols>

package/src/intent/index.ts

@@ -2,5 +2,4 @@ export * from './consts.js'
 export * from './schemas.js'
 export * from './errors.js'
 export * from './entrypoints.js'
-export * from './flow.js'
 export type * from './types.js'

package/src/intent/types.ts

@@ -1,3 +1,4 @@
+import type { EntrypointProtocol, OpenRequest, OpenValue } from '@owlmeans/entrypoint'
 import type { ResourceRecord } from '@owlmeans/resource'
 
 /** What the public site sends: the prompt and the person's confirmation of its processing. */
@@ -43,3 +44,12 @@ export interface IntentProtocolOptions {
   /** Path of the landing screen; defaults to `/start`. */
   landing?: string
 }
+
+/** The intent-first hand-off tree {@link makeIntentProtocols} declares. */
+export interface IntentProtocols {
+  base: EntrypointProtocol<OpenRequest, OpenValue>
+  stash: EntrypointProtocol<{ body: IntentStashBody }, IntentStashResult>
+  pickup: EntrypointProtocol<{ body: IntentPickupBody }, IntentPickupResult>
+  /** The landing screen — `sticky`, an in-app screen a visitor reaches from another origin. */
+  landing: EntrypointProtocol<OpenRequest, OpenValue>
+}

package/src/metadata/consts.ts

@@ -116,3 +116,40 @@ export const METADATA_SUFFIXES = [SPEC_SUFFIX, UX_SUFFIX, UI_SUFFIX]
 
 /** The trees the pipeline writes into — excluded wholesale when source files are enumerated. */
 export const METADATA_DIRS = [HARNESS_DIR, DOCS_DIR]
+
+export enum MetadataKind {
+  Project = 'project',
+  Story = 'story',
+  Source = 'source',
+  History = 'history',
+}
+
+export enum MetadataListKind {
+  Stories = 'stories',
+  Meta = 'meta',
+  // All metadata: the docs/ and .agents/ trees + co-located *.spec/.ux/.ui.md beside sources
+  All = 'all',
+}
+
+/**
+ * What a registry entry names.
+ *
+ * One entry per artifact the pipeline can generate, so that "where does this live" and "what is
+ * it called" have exactly one answer for the whole life of the project.
+ */
+export enum RegistryKind {
+  /** The single directory segment an entity owns across models/, resources/ and backend models/ */
+  EntityDir = 'entity-dir',
+  ModelType = 'model-type',
+  Resource = 'resource',
+  BackendModel = 'backend-model',
+  ApiHandlers = 'api-handlers',
+  Service = 'service',
+  Layout = 'layout',
+  Screen = 'screen',
+  Component = 'component',
+  ViewModel = 'view-model',
+  State = 'state',
+  /** Alias-only entry for one endpoint — carries no source path of its own */
+  ApiEntrypoint = 'api-entrypoint',
+}

package/src/metadata/types.ts

@@ -1,5 +1,6 @@
 
 import type { SpecCategory } from '../ba/consts.js'
+import { MetadataKind, MetadataListKind, RegistryKind } from './consts.js'
 
 export interface MetadataFile<T extends Record<string, unknown> = Record<string, unknown>> {
   path: string
@@ -12,20 +13,6 @@ export interface MetadataWriteInput<T extends Record<string, unknown> = Record<s
   body: string
 }
 
-export enum MetadataKind {
-  Project = 'project',
-  Story = 'story',
-  Source = 'source',
-  History = 'history',
-}
-
-export enum MetadataListKind {
-  Stories = 'stories',
-  Meta = 'meta',
-  // All metadata: the docs/ and .agents/ trees + co-located *.spec/.ux/.ui.md beside sources
-  All = 'all',
-}
-
 /**
  * Identifies a single metadata document to read:
  * - Project:  kind=Project, no ref/category needed
@@ -181,29 +168,6 @@ export interface StoryWriteInput {
 
 // ─── Name registry (.agents/memory/registry.md) ───────────────────────────────────────
 
-/**
- * What a registry entry names.
- *
- * One entry per artifact the pipeline can generate, so that "where does this live" and "what is
- * it called" have exactly one answer for the whole life of the project.
- */
-export enum RegistryKind {
-  /** The single directory segment an entity owns across models/, resources/ and backend models/ */
-  EntityDir = 'entity-dir',
-  ModelType = 'model-type',
-  Resource = 'resource',
-  BackendModel = 'backend-model',
-  ApiHandlers = 'api-handlers',
-  Service = 'service',
-  Layout = 'layout',
-  Screen = 'screen',
-  Component = 'component',
-  ViewModel = 'view-model',
-  State = 'state',
-  /** Alias-only entry for one endpoint — carries no source path of its own */
-  ApiEntrypoint = 'api-entrypoint',
-}
-
 /**
  * One allocated name.
  *

package/src/moderation/index.ts

@@ -1,4 +1,6 @@
 export * from './consts.js'
 export * from './schemas.js'
+export * from './verdict.js'
 export * from './utils.js'
 export type * from './types.js'
+export type * from './verdict/types.js'

package/src/moderation/utils.ts

@@ -1,35 +1,12 @@
-import { ModerationCategory } from './consts.js'
+import type { ModerationCategory } from './consts.js'
 import type { ModerationAction, ModerationPolicy, ModerationVerdict } from './types.js'
+import { moderationVerdictHelper } from './verdict.js'
 
-/**
- * Narrow whatever the model put in `category` to a real one, or to nothing.
- *
- * The wire field is a free string on purpose — see {@link ModerationVerdictSchema}. A model
- * that is allowing has nothing to categorise and still fills the field, so anything
- * unrecognized is treated as absent rather than as a failure.
- */
-export const normalizeCategory = (category?: string): ModerationCategory | undefined => {
-  const values = Object.values(ModerationCategory) as string[]
+/** @deprecated compat:factory-refactor — use `moderationVerdictHelper.normalizeCategory(…)` */
+export const normalizeCategory = (category?: string): ModerationCategory | undefined =>
+  moderationVerdictHelper.normalizeCategory(category)
 
-  return category != null && values.includes(category)
-    ? category as ModerationCategory
-    : undefined
-}
-
-/**
- * What to do about a verdict.
- *
- * Pure, because this is the part with the operational levers on it and the part most likely
- * to be wrong in a hurry: `enforce` turns the whole gate into an observer without a deploy,
- * and `bypassEntities` releases one entity when a real customer is wrongly refused.
- */
+/** @deprecated compat:factory-refactor — use `moderationVerdictHelper.decideModeration(…)` */
 export const decideModeration = (
   verdict: ModerationVerdict, policy: ModerationPolicy & { entityId?: string } = {}
-): ModerationAction => {
-  if (verdict.allowed) return 'allow'
-  if (policy.entityId != null && policy.bypassEntities?.includes(policy.entityId) === true) return 'allow'
-
-  // Defaults to ON: a gate that has to be switched on is a gate that is off in every
-  // environment nobody remembered to configure.
-  return policy.enforce !== false ? 'refuse' : 'shadow'
-}
+): ModerationAction => moderationVerdictHelper.decideModeration(verdict, policy)

package/src/moderation/verdict/types.ts

@@ -0,0 +1,22 @@
+import type { ModerationCategory } from '../consts.js'
+import type { ModerationAction, ModerationPolicy, ModerationVerdict } from '../types.js'
+
+/** Reading a moderation verdict: its category, and what to do about it. */
+export interface ModerationVerdictHelper {
+  /**
+   * Narrow whatever the model put in `category` to a real one, or to nothing.
+   *
+   * The wire field is a free string on purpose — see {@link ModerationVerdictSchema}. A model
+   * that is allowing has nothing to categorise and still fills the field, so anything
+   * unrecognized is treated as absent rather than as a failure.
+   */
+  normalizeCategory: (category?: string) => ModerationCategory | undefined
+  /**
+   * What to do about a verdict.
+   *
+   * Pure, because this is the part with the operational levers on it and the part most likely
+   * to be wrong in a hurry: `enforce` turns the whole gate into an observer without a deploy,
+   * and `bypassEntities` releases one entity when a real customer is wrongly refused.
+   */
+  decideModeration: (verdict: ModerationVerdict, policy?: ModerationPolicy & { entityId?: string }) => ModerationAction
+}

package/src/moderation/verdict.ts

@@ -0,0 +1,28 @@
+import { ModerationCategory } from './consts.js'
+import type { ModerationAction, ModerationPolicy, ModerationVerdict } from './types.js'
+import type { ModerationVerdictHelper } from './verdict/types.js'
+
+export const createModerationVerdictHelper = (): ModerationVerdictHelper => {
+  const normalizeCategory = (category?: string): ModerationCategory | undefined => {
+    const values = Object.values(ModerationCategory) as string[]
+
+    return category != null && values.includes(category)
+      ? category as ModerationCategory
+      : undefined
+  }
+
+  const decideModeration = (
+    verdict: ModerationVerdict, policy: ModerationPolicy & { entityId?: string } = {}
+  ): ModerationAction => {
+    if (verdict.allowed) return 'allow'
+    if (policy.entityId != null && policy.bypassEntities?.includes(policy.entityId) === true) return 'allow'
+
+    // Defaults to ON: a gate that has to be switched on is a gate that is off in every
+    // environment nobody remembered to configure.
+    return policy.enforce !== false ? 'refuse' : 'shadow'
+  }
+
+  return { normalizeCategory, decideModeration }
+}
+
+export const moderationVerdictHelper = createModerationVerdictHelper()

package/src/planning/card/types.ts

@@ -0,0 +1,44 @@
+import type { Workcard } from '@owlmeans/planning'
+import type { StoryDraft } from '../../areas/types.js'
+import type { UserStory } from '../../ba/types.js'
+import type { StoryDesign } from '../../design/types.js'
+import type { StoryWriteInput } from '../../metadata/types.js'
+import type {
+  StoryWriteContent, ViableProjectCard, ViableProjectFields, ViableStoryCard, ViableStoryFields,
+} from '../types.js'
+
+/** Reading Viable's planning cards — a project, a user story — and what a write carries. */
+export interface ViableCardHelper {
+  /** A `viable:project` card — kind AND type, since a foreign provider may share either alone. */
+  isViableProject: (card?: Workcard | null) => card is ViableProjectCard
+  /** A `viable:user-story` card. */
+  isViableStory: (card?: Workcard | null) => card is ViableStoryCard
+  /** Whether a write came from a person (`web`, `connect`) rather than the platform's own runs. */
+  isUserChannel: (channel?: string | null) => boolean
+  projectFieldsOf: (card: Workcard) => 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.
+   */
+  storyFieldsOf: (card: Workcard) => ViableStoryFields
+  /** The draft shape the analysis prompts and moderation take, from a card. */
+  storyDraftOf: (card: Workcard) => StoryDraft
+  /**
+   * 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.
+   */
+  userStoryOf: (card: Workcard, design?: StoryDesign | null) => UserStory
+  /**
+   * 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. The landing flag is carried
+   * only when it is set, so every other story's frontmatter keeps the shape it always had.
+   */
+  storyWriteInputOf: (card: Workcard, content: StoryWriteContent) => StoryWriteInput
+}

package/src/planning/card.ts

@@ -0,0 +1,77 @@
+import { WorkcardKind } from '@owlmeans/planning'
+import type { Workcard } from '@owlmeans/planning'
+import { ProjectArea } from '../areas/consts.js'
+import type { StoryDraft } from '../areas/types.js'
+import type { UserStory } from '../ba/types.js'
+import { storyDesignHelper } from '../design/story.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 } from './consts.js'
+import { ProjectStoryMissconfigured } from './errors.js'
+import type {
+  StoryWriteContent, ViableProjectCard, ViableProjectFields, ViableStoryCard, ViableStoryFields,
+} from './types.js'
+import type { ViableCardHelper } from './card/types.js'
+
+export const createViableCardHelper = (): ViableCardHelper => {
+  const isViableProject = (card?: Workcard | null): card is ViableProjectCard =>
+    card != null && card.kind === WorkcardKind.Project && card.type === VIABLE_PROJECT_TYPE
+
+  const isViableStory = (card?: Workcard | null): card is ViableStoryCard =>
+    card != null && card.kind === WorkcardKind.Card && card.type === VIABLE_STORY_TYPE
+
+  const isUserChannel = (channel?: string | null): boolean =>
+    channel != null && VIABLE_USER_CHANNELS.includes(channel)
+
+  const projectFieldsOf = (card: Workcard): ViableProjectFields =>
+    (card.fields ?? {}) as ViableProjectFields
+
+  const storyFieldsOf = (card: Workcard): ViableStoryFields => {
+    const fields = (card.fields ?? {}) as Partial<ViableStoryFields>
+
+    return { ...fields, area: fields.area ?? ProjectArea.Guest, primary: fields.primary === true }
+  }
+
+  const storyDraftOf = (card: Workcard): StoryDraft =>
+    ({ story: card.title, area: storyFieldsOf(card).area })
+
+  const userStoryOf = (card: Workcard, design?: StoryDesign | null): UserStory => {
+    const fields = storyFieldsOf(card)
+    const base: UserStory = design != null
+      ? storyDesignHelper.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 } : {}),
+    }
+  }
+
+  const storyWriteInputOf = (card: Workcard, content: StoryWriteContent): StoryWriteInput => {
+    if (card.code == null || card.code === '') {
+      throw new ProjectStoryMissconfigured('no-code')
+    }
+    const { status, ...rest } = content
+    const fields = storyFieldsOf(card)
+
+    return {
+      ...rest,
+      code: card.code,
+      narrative: card.title,
+      status: status ?? card.status,
+      primary: fields.primary,
+      ...(fields.landing === true ? { landing: true } : {}),
+    }
+  }
+
+  return {
+    isViableProject, isViableStory, isUserChannel, projectFieldsOf, storyFieldsOf, storyDraftOf, userStoryOf,
+    storyWriteInputOf,
+  }
+}
+
+export const viableCardHelper = createViableCardHelper()

package/src/planning/consts.ts

@@ -1,5 +1,4 @@
-import { CodeScope, CodeStyle } from '@owlmeans/planning'
-import type { CodePolicy } from '@owlmeans/planning'
+import { CodeScope, CodeStyle, type CodePolicy } from '@owlmeans/planning'
 
 /**
  * The OwlMeans Viable vocabulary over `@owlmeans/planning`.
@@ -180,3 +179,17 @@ export const VIABLE_IMPROVEMENT_CODE: CodePolicy = Object.freeze({
 export const VIABLE_REQUIREMENT_CODE: CodePolicy = Object.freeze({
   ...VIABLE_STORY_CODE, prefix: VIABLE_REQUIREMENT_CODE_PREFIX,
 })
+
+/**
+ * The sentence a landing story's narrative carries — what a person reading the board sees.
+ *
+ * The AUTHORITY is the card's `fields.landing` flag, never this text: the design and development
+ * stages key on the flag, and a person may reword the narrative at any time. The sentence exists so
+ * the board says in plain words why this story is different, and so the analyst and the designer,
+ * who read the narrative, write a screen that continues what the guest started.
+ *
+ * A constant, byte for byte, because {@link hasLandingSentence} is how a resumed decision step
+ * knows it already appended it.
+ */
+export const LANDING_STORY_SENTENCE = 'A visitor can start this on the landing page without an account;'
+  + ' after signing in they continue here with their choices carried over.'

package/src/planning/helpers.ts

@@ -1,136 +1,48 @@
-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 { viableCardHelper } from './card.js'
+import { viableSpecHelper } from './spec.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
+/** @deprecated compat:factory-refactor — use `viableCardHelper.isViableProject(…)` */
+export const isViableProject = (card?: Workcard | null): card is ViableProjectCard => viableCardHelper.isViableProject(card)
 
-/** 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
+/** @deprecated compat:factory-refactor — use `viableCardHelper.isViableStory(…)` */
+export const isViableStory = (card?: Workcard | null): card is ViableStoryCard => viableCardHelper.isViableStory(card)
 
-/** 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)
+/** @deprecated compat:factory-refactor — use `viableCardHelper.isUserChannel(…)` */
+export const isUserChannel = (channel?: string | null): boolean => viableCardHelper.isUserChannel(channel)
 
-export const projectFieldsOf = (card: Workcard): ViableProjectFields =>
-  (card.fields ?? {}) as ViableProjectFields
+/** @deprecated compat:factory-refactor — use `viableCardHelper.projectFieldsOf(…)` */
+export const projectFieldsOf = (card: Workcard): ViableProjectFields => viableCardHelper.projectFieldsOf(card)
 
-/**
- * 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>
+/** @deprecated compat:factory-refactor — use `viableCardHelper.storyFieldsOf(…)` */
+export const storyFieldsOf = (card: Workcard): ViableStoryFields => viableCardHelper.storyFieldsOf(card)
 
-  return { ...fields, area: fields.area ?? ProjectArea.Guest, primary: fields.primary === true }
-}
+/** @deprecated compat:factory-refactor — use `viableCardHelper.storyDraftOf(…)` */
+export const storyDraftOf = (card: Workcard): StoryDraft => viableCardHelper.storyDraftOf(card)
 
-/** 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 })
+/** @deprecated compat:factory-refactor — use `viableCardHelper.userStoryOf(…)` */
+export const userStoryOf = (card: Workcard, design?: StoryDesign | null): UserStory =>
+  viableCardHelper.userStoryOf(card, design)
 
-/**
- * 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
+/** @deprecated compat:factory-refactor — use `viableSpecHelper.currentSpecOf(…)` */
+export const currentSpecOf = (specs: readonly Specification[], category: string): Specification | null =>
+  viableSpecHelper.currentSpecOf(specs, category)
 
-  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. */
+/** @deprecated compat:factory-refactor — use `viableSpecHelper.currentSpecBody(…)` */
 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 } : {}),
-  }
-}
+  viableSpecHelper.currentSpecBody(specs, category)
 
-/**
- * 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. The landing flag is carried
- * only when it is set, so every other story's frontmatter keeps the shape it always had.
- */
-export const storyWriteInputOf = (card: Workcard, content: StoryWriteContent): StoryWriteInput => {
-  if (card.code == null || card.code === '') {
-    throw new ProjectStoryMissconfigured('no-code')
-  }
-  const { status, ...rest } = content
-  const fields = storyFieldsOf(card)
+/** @deprecated compat:factory-refactor — use `viableSpecHelper.projectBriefOf(…)` */
+export const projectBriefOf = (project: Workcard, specs: readonly Specification[]): AgentProject =>
+  viableSpecHelper.projectBriefOf(project, specs)
 
-  return {
-    ...rest,
-    code: card.code,
-    narrative: card.title,
-    status: status ?? card.status,
-    primary: fields.primary,
-    ...(fields.landing === true ? { landing: true } : {}),
-  }
-}
+/** @deprecated compat:factory-refactor — use `viableCardHelper.storyWriteInputOf(…)` */
+export const storyWriteInputOf = (card: Workcard, content: StoryWriteContent): StoryWriteInput =>
+  viableCardHelper.storyWriteInputOf(card, content)

package/src/planning/index.ts

@@ -1,7 +1,11 @@
 export * from './consts.js'
 export * from './errors.js'
 export * from './schemas.js'
-export * from './flows.js'
+export * from './card.js'
+export * from './spec.js'
 export * from './helpers.js'
 export * from './landing.js'
 export type * from './types.js'
+export type * from './card/types.js'
+export type * from './spec/types.js'
+export type * from './landing/types.js'

package/src/planning/landing/types.ts

@@ -0,0 +1,15 @@
+/** The landing sentence a landing-gate story's narrative carries. */
+export interface LandingSentenceHelper {
+  /** Whether a narrative already carries the landing sentence, whatever whitespace surrounds it. */
+  hasLandingSentence: (title: string) => boolean
+  /**
+   * The narrative with the landing sentence appended once.
+   *
+   * Idempotent — a narrative that already carries the sentence comes back unchanged, so a decision
+   * step that is resumed after it wrote the card never appends a second copy. It never produces a
+   * title longer than a card accepts (`TITLE_MAX`): a narrative with no room left is returned as it
+   * is rather than cut, because a person's words are worth more than the note, and the flag on the
+   * card still carries the fact.
+   */
+  withLandingSentence: (title: string) => string
+}