@owlmeans/viable-common 0.0.18 → 0.0.20

package/src/connect/jobs.ts

@@ -0,0 +1,40 @@
+import type { ConnectJobKind } from './consts.js'
+
+/**
+ * The separator a job id is joined with.
+ *
+ * `~`, because every other separator in play is already spoken for: a route alias is
+ * colon-delimited and so is every run id (`init:<projectId>`, `story:<storyId>`), so a job id
+ * built with one could not be split back apart.
+ */
+export const JOB_SEPARATOR = '~'
+
+/**
+ * A job's id: its kind, the project card it belongs to, and the subject it is about.
+ *
+ * The suffix is a CARD id for a story job and a run id for a pipeline job — never a story code.
+ * Declared here rather than by whoever answers the job, because the SDK composes the id it then
+ * polls for: two spellings of one id is a job nobody can find.
+ */
+export const jobIdOf = (kind: ConnectJobKind, projectId: string, suffix?: string): string =>
+  [kind, projectId, ...(suffix != null ? [suffix] : [])].join(JOB_SEPARATOR)
+
+export interface ParsedJobId {
+  kind: ConnectJobKind
+  projectId: string
+  suffix?: string
+}
+
+/** Split a job id back into what {@link jobIdOf} composed it from. */
+export const parseJobId = (jobId: string): ParsedJobId => {
+  const [kind, projectId, ...rest] = jobId.split(JOB_SEPARATOR)
+  // A suffix may carry the separator back if one ever ends up in a card or run id, so the tail is
+  // rejoined rather than taken as its first segment.
+  const suffix = rest.length > 0 ? rest.join(JOB_SEPARATOR) : undefined
+
+  return {
+    kind: kind as ConnectJobKind,
+    projectId: projectId ?? '',
+    ...(suffix != null ? { suffix } : {}),
+  }
+}

package/src/connect/references.ts

@@ -10,8 +10,7 @@ import type {
   ConnectModifyBody, ConnectOpSubmission, ConnectPipelineParams, ConnectPipelineResumeBody,
   ConnectPipelineState, ConnectProjectLlmBody, ConnectProjectSettings, ConnectProjectStatus,
   ConnectProjectSummary, ConnectSessionOpen, ConnectSessionParams, ConnectSessionView,
-  ConnectStoryBody, ConnectStoryDeletion, ConnectStoryItem, ConnectStoryList, ConnectStoryMutation,
-  ConnectStoryQuery, ConnectWaitQuery, ConversionStatusView, ConvertCheck,
+  ConnectWaitQuery, ConversionStatusView, ConvertCheck,
 } from './types.js'
 
 type ConnectReference<Request extends RequestShape, Response> =
@@ -47,16 +46,6 @@ export interface ConnectReferences {
     }, ConnectProjectSettings>
     job: ConnectReference<{ params: ConnectJobParams, query: ConnectWaitQuery }, ConnectJob>
   }
-  story: {
-    list: ConnectReference<{ params: { id: string }, query: ConnectStoryQuery }, ConnectStoryList>
-    get: ConnectReference<{ params: { id: string, storyId: string } }, ConnectStoryItem>
-    create: ConnectReference<{ params: { id: string }, body: ConnectStoryBody }, ConnectStoryMutation>
-    update: ConnectReference<{
-      params: { id: string, storyId: string }, body: ConnectStoryBody
-    }, ConnectStoryMutation>
-    delete: ConnectReference<{ params: { id: string, storyId: string } }, ConnectStoryDeletion>
-    develop: ConnectReference<{ params: { id: string, storyId: string } }, ConnectJob>
-  }
   files: {
     list: ConnectReference<{ params: { id: string } }, string[]>
   }
@@ -139,16 +128,6 @@ export const connectRef: ConnectReferences = {
       params: { id: string, inquiryId: string }, body: ConnectInquiryAnswerBody
     }, unknown>(connect.inquiry.answer),
   },
-  story: {
-    list: entrypointRef<{ params: { id: string }, query: ConnectStoryQuery }, ConnectStoryList>(connect.story.list),
-    get: entrypointRef<{ params: { id: string, storyId: string } }, ConnectStoryItem>(connect.story.get),
-    create: entrypointRef<{ params: { id: string }, body: ConnectStoryBody }, ConnectStoryMutation>(connect.story.create),
-    update: entrypointRef<{
-      params: { id: string, storyId: string }, body: ConnectStoryBody
-    }, ConnectStoryMutation>(connect.story.update),
-    delete: entrypointRef<{ params: { id: string, storyId: string } }, ConnectStoryDeletion>(connect.story.delete),
-    develop: entrypointRef<{ params: { id: string, storyId: string } }, ConnectJob>(connect.story.develop),
-  },
   files: {
     list: entrypointRef<{ params: { id: string } }, string[]>(connect.files.list),
   },

package/src/connect/schemas.ts

@@ -9,7 +9,7 @@ import type {
   ConnectAttachBody, ConnectConfirmBody, ConnectConvertCreateBody, ConnectConvertProceedBody,
   ConnectCreateBody, ConnectJobParams, ConnectLlmBody, ConnectModifyBody, ConnectPipelineParams,
   ConnectPipelineResumeBody, ConnectProjectLlmBody, ConnectSession, ConnectSessionOpen,
-  ConnectSessionParams, ConnectStoryBody, ConnectStoryQuery, ConnectWaitQuery
+  ConnectSessionParams, ConnectWaitQuery
 } from './types.js'
 
 /**
@@ -26,7 +26,6 @@ import type {
  */
 
 const idValue = { type: 'string', minLength: 1, maxLength: 128 } as const
-const textValue = { type: 'string', minLength: 1, maxLength: 65536 } as const
 
 export const ConnectCapabilitiesSchema = {
   type: 'object',
@@ -156,13 +155,6 @@ export const ConnectProjectIdSchema = {
   additionalProperties: false,
 } as JSONSchemaType<{ id: string }>
 
-export const ConnectStoryParamsSchema = {
-  type: 'object',
-  properties: { id: idValue, storyId: idValue },
-  required: ['id', 'storyId'],
-  additionalProperties: false,
-} as JSONSchemaType<{ id: string, storyId: string }>
-
 export const ConnectOpParamsSchema = {
   type: 'object',
   properties: { sessionId: idValue, opId: idValue },
@@ -177,19 +169,6 @@ export const ConnectJobParamsSchema = {
   additionalProperties: false,
 } as JSONSchemaType<ConnectJobParams>
 
-export const ConnectStoryQuerySchema = {
-  type: 'object',
-  properties: {
-    page: { type: 'integer', minimum: 0, nullable: true },
-    size: { type: 'integer', minimum: 1, maximum: 100, nullable: true },
-    status: { type: 'string', maxLength: 32, nullable: true },
-    area: { type: 'string', maxLength: 32, nullable: true },
-    q: { type: 'string', maxLength: 256, nullable: true },
-  },
-  required: [],
-  additionalProperties: false,
-} as JSONSchemaType<ConnectStoryQuery>
-
 export const ConnectCreateBodySchema = {
   type: 'object',
   properties: {
@@ -207,6 +186,7 @@ export const ConnectConfirmBodySchema = {
     description: { type: 'string', maxLength: 16384, nullable: true },
     specification: { type: 'string', maxLength: 262144, nullable: true },
     vision: { type: 'string', maxLength: 16384, nullable: true },
+    designSystem: { type: 'string', maxLength: 262144, nullable: true },
     target: { type: 'string', enum: [...Object.values(ConnectTarget), null], nullable: true },
   },
   required: [],
@@ -220,13 +200,6 @@ export const ConnectModifyBodySchema = {
   additionalProperties: false,
 } as JSONSchemaType<ConnectModifyBody>
 
-export const ConnectStoryBodySchema = {
-  type: 'object',
-  properties: { story: textValue },
-  required: ['story'],
-  additionalProperties: false,
-} as JSONSchemaType<ConnectStoryBody>
-
 export const ConnectAttachBodySchema = {
   type: 'object',
   properties: {

package/src/connect/types.ts

@@ -86,15 +86,24 @@ export interface ConnectSessionView {
  * A derived view of "what the platform is doing for this project right now".
  *
  * Never stored. It is composed per request from the project lock, the slot record, the story
- * record, the latest pipeline run row and the operations queued for the project — the same facts
+ * card, the latest pipeline run row and the operations queued for the project — the same facts
  * the manager UI reads, arranged for a caller that has one question ("may I stop waiting?") and
  * one follow-up ("what do I call next?").
+ *
+ * Its `id` is composed and parsed only through `jobIdOf` / `parseJobId`.
  */
 export interface ConnectJob {
   id: string
   kind: ConnectJobKind
   status: ConnectJobStatus
+  /** The project CARD id. */
   projectId: string
+  /**
+   * The story CARD id — never the story's code.
+   *
+   * The name is kept because a parent agent reads it: a wire field name is that agent's
+   * vocabulary and is never renamed, only re-documented.
+   */
   storyId?: string
   runId?: string
   /** The pipeline step in flight, when a run row says. */
@@ -137,43 +146,27 @@ export interface ConnectWaitQuery {
   wait?: number
 }
 
-/** Paging and filtering for the story list a connector reads. */
-export interface ConnectStoryQuery {
-  page?: number
-  size?: number
-  status?: string
-  area?: string
-  /** Free-text match against the story narrative and its code. */
-  q?: string
-}
-
-export interface ConnectStoryList {
-  items: ConnectStoryItem[]
-  page: number
-  size: number
-  total: number
-}
-
-export interface ConnectStoryItem {
-  id: string
-  code?: string
-  story: string
-  area?: string
-  status: string
-  primary: boolean
-  warning?: string
-  createdAt: string
-}
-
 /** What a connector needs to know about a project in one call. */
 export interface ConnectProjectStatus {
+  /**
+   * The project card, flattened into the names a parent agent already reads.
+   *
+   * `name` is the card's `title` and `alias` its `code`; the three brief parts are the bodies of
+   * the project's `specification`, `vision` and `design-system` specifications. `status` and
+   * `intrinsic` are the card's own — a key of the project flow and the intrinsic state it maps to —
+   * typed as plain strings because this view crosses a version skew and a newer platform may
+   * answer with a status an older connector has never heard of.
+   */
   project: {
     id: string
     name: string
     alias: string
     description?: string
+    status: string
+    intrinsic: string
     specification?: string
     vision?: string
+    designSystem?: string
   }
   slot?: {
     id: string
@@ -297,12 +290,19 @@ export interface ConnectCreateBody {
   target?: ConnectTarget
 }
 
-/** Confirm a drafted project, optionally editing what the analysis produced. */
+/**
+ * Confirm a drafted project, optionally editing what the analysis produced.
+ *
+ * The keys are a parent agent's vocabulary and stay as they are: `name` becomes the card's
+ * `title`, and each brief part present is written into the project's specification of that
+ * category before the confirm transition runs.
+ */
 export interface ConnectConfirmBody {
   name?: string
   description?: string
   specification?: string
   vision?: string
+  designSystem?: string
   target?: ConnectTarget
 }
 
@@ -310,10 +310,6 @@ export interface ConnectModifyBody {
   prompt: string
 }
 
-export interface ConnectStoryBody {
-  story: string
-}
-
 export interface ConnectPipelineParams {
   id: string
   runId: string
@@ -419,23 +415,6 @@ export interface ConnectProjectSummary {
   alias: string
 }
 
-/** A story item returned after creating, editing or fetching one story. */
-export interface ConnectStoryMutation {
-  id: string
-  code?: string
-  story: string
-  area?: string
-  status: string
-  primary: boolean
-  warning?: string
-  createdAt: string
-}
-
-/** The success answer for deleting a story. */
-export interface ConnectStoryDeletion {
-  deleted: boolean
-}
-
 /** The persistent state of one pipeline run, read by a connector without platform internals. */
 export interface ConnectPipelineState {
   runId: string

package/src/design/consts.ts

@@ -8,9 +8,6 @@
  */
 export const STORY_DESIGN_VERSION = 1
 
-/** The code a scaffold plan is filed under, since it belongs to a project rather than a story. */
-export const SCAFFOLD_CODE = 'scaffold'
-
 /** How far a design may drift from the project it was written against before it is stale. */
 export enum DesignStaleness {
   /** Usable as it stands. */

package/src/design/helpers.ts

@@ -4,15 +4,19 @@ import { DesignStaleness, STORY_DESIGN_VERSION } from './consts.js'
 import type { StoryDesign } from './types.js'
 
 /**
- * The in-memory aggregate the coders take, derived from the design.
+ * The in-memory aggregate the coders take, derived from the design ALONE.
  *
  * Derived rather than stored, and derived HERE rather than at the platform: the aggregate is what
  * every generation helper reads, and a second place that assembles it is a second place that can
  * assemble it differently. The `code` in particular is load-bearing - the scaffold stamps every
  * placeholder it draws with it, so a run keyed by anything else cannot recognise its own
  * reservation.
+ *
+ * For a context with no card behind it. Where a story card exists, `userStoryOf(card, design)` is
+ * the reader: the card wins on the narrative, code, area and actor, which a person may have
+ * changed since the design was written.
  */
-export const userStoryOf = (design: StoryDesign): UserStory => {
+export const userStoryOfDesign = (design: StoryDesign): UserStory => {
   const componentOf = (name: string): StoryComponent | null => {
     const component = design.components.find(entry => entry.name === name)
     if (component == null) {

package/src/design/types.ts

@@ -168,24 +168,25 @@ export interface StoryDesign {
   provenance: StoryDesignProvenance
 }
 
-/** What a caller hands the store; the revision is the store's to allocate. */
-export interface StoryDesignInput {
-  projectId: string
-  storyId?: string
-  code: string
-  kind: string
-  payload: unknown
+/** Who wrote a design revision and why — recorded on the transition, never in the design. */
+export interface StoryDesignPutOptions {
   runId?: string
+  cause?: string
 }
 
 /**
  * How the implementation stage reaches the design, without knowing where it lives.
  *
  * A port rather than a resource for the usual reason: two questions is the whole of what an
- * implementation step needs, and a port that small is satisfiable by a record store, a file, or a
- * test double.
+ * implementation step needs, and a port that small is satisfiable by a planning facade, a file,
+ * or a test. Both methods are addressed by a CARD id — the story card for a story design, the
+ * project card for a scaffold plan — and the port decides which specification slot of that card
+ * holds the payload. The code a design carries is the target's vocabulary; it never addresses a
+ * record.
  */
 export interface StoryDesignPort {
-  current: (projectId: string, code: string) => Promise<{ revision: number, design: StoryDesign } | null>
-  put: (input: StoryDesignInput) => Promise<number>
+  /** The card's current design and its revision; `null` when none was written or its version differs. */
+  current: (cardId: string) => Promise<{ revision: number, design: StoryDesign } | null>
+  /** Write a design as the card's next revision and answer the revision number it received. */
+  put: (cardId: string, design: StoryDesign, opts?: StoryDesignPutOptions) => Promise<number>
 }

package/src/execution/types.ts

@@ -6,6 +6,7 @@ import type { PurposeMetadata } from '../agent/types.js'
 import type { AgentProject, Entity, UserStory } from '../ba/types.js'
 import type { UXTransition } from '../ux/types.js'
 import type { SeniorityMode } from '../consts.js'
+import type { ViableProjectCard, ViableStoryCard } from '../planning/types.js'
 
 /**
  * Model-selection contracts are owned by `@owlmeans/llm-common` — the JSON-safe config
@@ -26,7 +27,15 @@ export interface ExecutionState extends LlmExecutionState {
   slot?: string
   projectId?: string
   entityId?: string
+  /** The brief the run reads — assembled from {@link ExecutionState.projectCard} and its specifications. */
   project?: AgentProject
+  /**
+   * The project card the run acts on, as plain data.
+   *
+   * Carried beside the brief rather than in place of it: a generator reads the brief, while
+   * whatever writes back — a status transition, a specification — needs the card's id and head.
+   */
+  projectCard?: ViableProjectCard
   entities?: Entity[]
   /**
    * Which blueprint this run is building against, as an id plus an override patch.
@@ -51,5 +60,7 @@ export interface TaskExecutionState
   extends ExecutionState, Omit<LlmTaskExecutionState, keyof LlmExecutionState> {
   mode?: SeniorityMode
   story?: UserStory
+  /** The story card the task develops, as plain data — the aggregate above is derived from it. */
+  card?: ViableStoryCard
   transitions?: UXTransition[]
 }

package/src/index.ts

@@ -19,4 +19,5 @@ export * from './connect/index.js'
 export * from './convert/index.js'
 export * from './scaffold/index.js'
 export * from './design/index.js'
+export * from './planning/index.js'
 export * from './branding.js'

package/src/planning/consts.ts

@@ -0,0 +1,182 @@
+import { CodeScope, CodeStyle } from '@owlmeans/planning'
+import type { CodePolicy } from '@owlmeans/planning'
+
+/**
+ * The OwlMeans Viable vocabulary over `@owlmeans/planning`.
+ *
+ * A project, a user story and the documents behind them are planning WORKCARDS of the types
+ * declared here. Everything generic — the record, the transition, the fold, the store, the protocol
+ * tree — belongs to the planning packages; what a Viable project or story IS, which statuses it
+ * moves through and which documents it carries, is declared once in this module and read by every
+ * runtime that writes one.
+ */
+
+/** A Viable project — the card every story, document and platform record of a product hangs under. */
+export const VIABLE_PROJECT_TYPE = 'viable:project'
+/** A user story — the unit of development a person starts. */
+export const VIABLE_STORY_TYPE = 'viable:user-story'
+/** Every document a project or story card carries (specification, vision, design system, plans). */
+export const VIABLE_SPEC_TYPE = 'viable:spec'
+
+/**
+ * Reserved card types. Declared in full so their code prefix and flow are decided once, and
+ * deliberately absent from the project type's `cardTypes`: nothing may create one yet.
+ */
+export const VIABLE_BUG_TYPE = 'viable:bug'
+export const VIABLE_IMPROVEMENT_TYPE = 'viable:improvement'
+export const VIABLE_REQUIREMENT_TYPE = 'viable:requirement'
+
+export const VIABLE_PROJECT_FLOW = 'viable:project'
+export const VIABLE_STORY_FLOW = 'viable:user-story'
+/** The one-status flow a document runs — a specification has no lifecycle of its own. */
+export const VIABLE_SPEC_FLOW = 'viable:spec'
+
+/**
+ * The story flow's status keys.
+ *
+ * Byte-identical to the strings a story has always carried — the frontmatter of
+ * `docs/stories/<code>.md`, the connector's job status mapping, the board's columns, their i18n
+ * keys and every end-to-end selector read these exact values. A key is a wire contract and is
+ * never renamed.
+ */
+export enum ViableStoryStatus {
+  Planned = 'planned',
+  InProgress = 'in-progress',
+  Completed = 'completed',
+  /** Intrinsically PLANNED: a failed story is work still to do, and retrying it is `start`. */
+  Failed = 'failed',
+}
+
+export enum ViableStoryTransition {
+  /** `planned | failed → in-progress` — the only move that asks for development. */
+  Start = 'start',
+  Complete = 'complete',
+  Fail = 'fail',
+  /** `* → planned` — the manual recovery, and the one move a completed story still accepts. */
+  Reset = 'reset',
+}
+
+export enum ViableProjectStatus {
+  /** Created from a prompt, specification drafted, nothing provisioned. */
+  Draft = 'draft',
+  /** The owner confirmed the brief; initialization is running or has run. */
+  Confirmed = 'confirmed',
+  /** Initialization finished at least once. */
+  Active = 'active',
+  Archived = 'archived',
+}
+
+export enum ViableProjectTransition {
+  Confirm = 'confirm',
+  Activate = 'activate',
+  Archive = 'archive',
+  Reopen = 'reopen',
+}
+
+/** The single status a document holds. */
+export enum ViableSpecStatus {
+  Current = 'current',
+}
+
+/** The palette key a board renders a status with. Presentation data, carried on the flow. */
+export enum ViableTone {
+  Blue = 'blue',
+  Yellow = 'yellow',
+  Green = 'green',
+  Red = 'red',
+  Neutral = 'neutral',
+}
+
+/**
+ * The specification slots Viable cards carry.
+ *
+ * Project: `specification`, `vision`, `design-system` (the brief) and `scaffold` (the drawn plan).
+ * Story: `design`. The co-located `*.spec/.ux/.ui.md` files of a target are FILES, not slots — that
+ * prose already lives inside the `design` payload — so `SpecCategory` is not a slot vocabulary.
+ */
+export enum ViableSpecCategory {
+  Specification = 'specification',
+  Vision = 'vision',
+  DesignSystem = 'design-system',
+  Scaffold = 'scaffold',
+  Design = 'design',
+}
+
+/** How many revisions of a `design` or `scaffold` document the history must be able to answer. */
+export const VIABLE_DESIGN_REVISIONS_KEPT = 3
+
+/**
+ * Relationship types between story cards.
+ *
+ * `follows` is WRITTEN: a connective story follows the flow story it was anchored after, created in
+ * the same transition as the card. `shares-widget` and `shares-screen` are DECLARED ONLY — the
+ * `scaffold` specification is their single authority, and a second copy as links would be a second
+ * answer that can disagree with it.
+ */
+export enum ViableRelationship {
+  Follows = 'follows',
+  SharesWidget = 'shares-widget',
+  SharesScreen = 'shares-screen',
+}
+
+/**
+ * Where a write came from, carried on `PlanningScope.channel` and recorded on the transition's
+ * `actor.channel`.
+ *
+ * It is never read from the wire: the manager API derives `Connect` from an access-token request
+ * and `Web` from everything else; the agent writes as `Agent` or `Pipeline`. Three rules key on it
+ * — the balance refusal class (`ConnectOutOfCredits` for `Connect`), re-formatting a narrative
+ * (`Web`/`Connect` only), and the develop trigger (a committed `start` by `Web`/`Connect` only).
+ */
+export enum ViableChannel {
+  Web = 'web',
+  Connect = 'connect',
+  Agent = 'agent',
+  Pipeline = 'pipeline',
+}
+
+/** The channels a PERSON writes through. */
+export const VIABLE_USER_CHANNELS: readonly string[] = Object.freeze([
+  ViableChannel.Web, ViableChannel.Connect,
+])
+
+export const VIABLE_STORY_CODE_PREFIX = 'US-'
+export const VIABLE_BUG_CODE_PREFIX = 'BUG-'
+export const VIABLE_IMPROVEMENT_CODE_PREFIX = 'IMP-'
+export const VIABLE_REQUIREMENT_CODE_PREFIX = 'REQ-'
+export const VIABLE_CARD_CODE_LENGTH = 5
+
+/** `US-` + five uppercase characters, unique within the project. The code a target is keyed by. */
+export const VIABLE_STORY_CODE: CodePolicy = Object.freeze({
+  prefix: VIABLE_STORY_CODE_PREFIX,
+  style: CodeStyle.Random,
+  length: VIABLE_CARD_CODE_LENGTH,
+  uppercase: true,
+  uniqueWithin: CodeScope.Parent,
+})
+
+/**
+ * A project's code is its alias — a slug unique within the organization.
+ *
+ * Minted by the platform's name ladder, which knows about retired aliases and refused hostnames;
+ * a code policy only guards uniqueness, so a create always supplies the code.
+ */
+export const VIABLE_PROJECT_CODE: CodePolicy = Object.freeze({
+  style: CodeStyle.Slug,
+  uniqueWithin: CodeScope.Entity,
+  // The alias moves: a rename changes it, and a refused preview certificate walks it to `alias-2`.
+  // A story code never moves — the target's files are named after it.
+  mutable: true,
+})
+
+export const VIABLE_BUG_CODE: CodePolicy = Object.freeze({
+  ...VIABLE_STORY_CODE, prefix: VIABLE_BUG_CODE_PREFIX,
+})
+
+export const VIABLE_IMPROVEMENT_CODE: CodePolicy = Object.freeze({
+  ...VIABLE_STORY_CODE, prefix: VIABLE_IMPROVEMENT_CODE_PREFIX,
+})
+
+export const VIABLE_REQUIREMENT_CODE: CodePolicy = Object.freeze({
+  ...VIABLE_STORY_CODE, prefix: VIABLE_REQUIREMENT_CODE_PREFIX,
+})