@owlmeans/viable-common 0.0.19 → 0.0.20

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,
+})

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)