@elevasis/core 0.24.1 → 0.26.0

package/src/organization-model/scaffolders/scaffoldKnowledgeNode.ts

@@ -0,0 +1,48 @@
+import type { OrganizationModel } from '..'
+import { assertSystemExists, slugify, titleize } from './helpers'
+import type { KnowledgeNodeScaffoldSpec, OmScaffoldPlan } from './types'
+
+export function scaffoldKnowledgeNode(model: OrganizationModel, spec: KnowledgeNodeScaffoldSpec): OmScaffoldPlan {
+  if (spec.systemPath !== undefined) assertSystemExists(model, spec.systemPath)
+  if (model.knowledge?.[spec.id] !== undefined) {
+    throw new Error(`knowledge node already exists: ${spec.id}`)
+  }
+
+  const title = spec.label ?? titleize(spec.id.replace(/^knowledge\./, ''))
+  const slug = slugify(spec.id.replace(/^knowledge\./, ''))
+  const kind = spec.kind ?? 'reference'
+  const links = spec.systemPath === undefined ? '' : `links:\n  - system:${spec.systemPath}\n`
+  const ownerIds = spec.ownerRoleId === undefined ? '' : `ownerIds:\n  - ${spec.ownerRoleId}\n`
+
+  return {
+    intent: 'knowledge',
+    id: spec.id,
+    summary: `Scaffold ${kind} knowledge node "${spec.id}".`,
+    writes: [
+      {
+        path: `packages/elevasis-core/src/knowledge/nodes/${slug}.mdx.stub`,
+        mode: 'create',
+        description: 'Knowledge node MDX skeleton.',
+        content: `---\nid: ${spec.id}\nkind: ${kind}\ntitle: ${JSON.stringify(title)}\nsummary: ${JSON.stringify(spec.description ?? `${title} knowledge node.`)}\n${links}${ownerIds}updatedAt: 2026-05-15\n---\n\n## Overview\n\nCapture the durable operating knowledge here.\n`
+      }
+    ],
+    edits: [
+      {
+        path: 'packages/elevasis-core/src/organization-model/knowledge.ts',
+        description: 'Register this generated node after replacing the .stub suffix.',
+        snippet: `${JSON.stringify(spec.id)}`
+      }
+    ],
+    warnings: [],
+    nextSteps: [
+      'Replace the .stub suffix after the node is ready to become canonical.',
+      spec.systemPath === undefined
+        ? 'Add links to the OM nodes this knowledge governs.'
+        : `Run pnpm exec elevasis om:verify --scope ${spec.systemPath}.`
+    ],
+    projectCommand:
+      spec.withProject && spec.systemPath !== undefined
+        ? `pnpm exec elevasis project:create --link-om ${spec.systemPath} --title "Add ${title} knowledge" --kind om-change`
+        : undefined
+  }
+}

package/src/organization-model/scaffolders/scaffoldOntologyRecord.ts

@@ -0,0 +1,38 @@
+import type { OrganizationModel } from '..'
+import { assertSystemExists, makeOntologyId, ontologyMapName, titleize } from './helpers'
+import type { OmScaffoldPlan, OntologyRecordScaffoldSpec } from './types'
+
+export function scaffoldOntologyRecord(model: OrganizationModel, spec: OntologyRecordScaffoldSpec): OmScaffoldPlan {
+  assertSystemExists(model, spec.systemPath)
+  const localId = spec.localId ?? spec.id
+  const ontologyId = makeOntologyId(spec.systemPath, spec.kind, localId)
+  const label = spec.label ?? titleize(localId)
+  const mapName = ontologyMapName(spec.kind)
+
+  return {
+    intent: 'ontology',
+    id: ontologyId,
+    summary: `Scaffold ${spec.kind} ontology record "${ontologyId}".`,
+    writes: [],
+    edits: [
+      {
+        path: 'packages/elevasis-core/src/organization-model/systems.ts',
+        description: `Add this record under ${spec.systemPath}.ontology.${mapName}.`,
+        snippet: `${JSON.stringify(ontologyId)}: {
+  id: ${JSON.stringify(ontologyId)},
+  label: ${JSON.stringify(label)},
+  ownerSystemId: ${JSON.stringify(spec.systemPath)}${spec.description === undefined ? '' : `,
+  description: ${JSON.stringify(spec.description)}`}
+}`
+      }
+    ],
+    warnings: [],
+    nextSteps: [
+      'Wire any cross-references using canonical ontology IDs.',
+      `Run pnpm exec elevasis om:verify --scope ${spec.systemPath}.`
+    ],
+    projectCommand: spec.withProject
+      ? `pnpm exec elevasis project:create --link-om ${spec.systemPath} --title "Add ${label} ontology" --kind om-change`
+      : undefined
+  }
+}

package/src/organization-model/scaffolders/scaffoldResource.ts

@@ -0,0 +1,59 @@
+import type { OrganizationModel } from '..'
+import { assertSystemExists, slugify, titleize } from './helpers'
+import type { OmScaffoldPlan, ResourceScaffoldSpec } from './types'
+
+export function scaffoldResource(model: OrganizationModel, spec: ResourceScaffoldSpec): OmScaffoldPlan {
+  assertSystemExists(model, spec.systemPath)
+  if (model.resources?.[spec.id] !== undefined) {
+    throw new Error(`resource already exists: ${spec.id}`)
+  }
+
+  const label = spec.label ?? titleize(spec.id)
+  const kind = spec.kind ?? 'workflow'
+  const slug = slugify(spec.id)
+  const writes = spec.withStubWorkflow
+    ? [
+        {
+          path: `packages/elevasis-core/src/workflows/${slug}.stub.ts`,
+          mode: 'create' as const,
+          description: 'Optional workflow implementation stub. Runtime wiring remains manual.',
+          content: `// Stub only. Replace with a real workflow implementation before registering the resource.\nexport const ${slug.replaceAll('-', '_')}Workflow = {\n  id: ${JSON.stringify(spec.id)}\n}\n`
+        }
+      ]
+    : []
+
+  return {
+    intent: 'resource',
+    id: spec.id,
+    summary: `Scaffold ${kind} Resource "${spec.id}" for System "${spec.systemPath}".`,
+    writes,
+    edits: [
+      {
+        path: 'packages/elevasis-core/src/organization-model/resources.ts',
+        description: 'Add this descriptor to platformResources/platformResourceDescriptors.',
+        snippet: `${JSON.stringify(spec.id)}: {
+  id: ${JSON.stringify(spec.id)},
+  order: 0,
+  kind: ${JSON.stringify(kind)},
+  systemPath: ${JSON.stringify(spec.systemPath)},
+  title: ${JSON.stringify(label)},
+  ${spec.description === undefined ? '' : `description: ${JSON.stringify(spec.description)},\n  `}${spec.ownerRoleId === undefined ? '' : `ownerRoleId: ${JSON.stringify(spec.ownerRoleId)},\n  `}status: 'active',
+  codeRefs: []
+}`
+      },
+      {
+        path: 'packages/elevasis-core/src/organization-model/topology.ts',
+        description: 'Add topology relationships only when this resource triggers, uses, or requires approval from another OM node.',
+        snippet: `// topologyRelationship({ from: topologyRef('resource', ${JSON.stringify(spec.id)}), kind: 'uses', to: ... })`
+      }
+    ],
+    warnings: ['Resource ontology bindings are intentionally omitted until action/read/write contracts are known.'],
+    nextSteps: [
+      'Bind resource.ontology.actions/reads/writes after the ontology records exist.',
+      `Run pnpm exec elevasis om:verify --scope ${spec.systemPath}.`
+    ],
+    projectCommand: spec.withProject
+      ? `pnpm exec elevasis project:create --link-om ${spec.systemPath} --title "Add ${label} resource" --kind om-change`
+      : undefined
+  }
+}

package/src/organization-model/scaffolders/scaffoldSystem.ts

@@ -0,0 +1,110 @@
+import type { OrganizationModel } from '..'
+import {
+  addProjectNextStep,
+  assertSystemPathAvailable,
+  localIdOf,
+  nextSystemOrder,
+  parentPathOf,
+  slugify,
+  titleize
+} from './helpers'
+import type { OmScaffoldPlan, SystemScaffoldSpec } from './types'
+
+export function scaffoldSystem(model: OrganizationModel, spec: SystemScaffoldSpec): OmScaffoldPlan {
+  const systemPath = spec.parent !== undefined && !spec.id.includes('.') ? `${spec.parent}.${spec.id}` : spec.id
+  assertSystemPathAvailable(model, systemPath)
+
+  const parentPath = parentPathOf(systemPath)
+  const localId = localIdOf(systemPath)
+  const label = spec.label ?? titleize(localId)
+  const roleId = spec.role ?? 'role.ops-lead'
+  const uiPath = spec.uiPath ?? `/${localId}`
+  const featureSlug = slugify(systemPath.replaceAll('.', '-'))
+  const knowledgeId = `knowledge.${featureSlug}-system-overview`
+  const order = nextSystemOrder(model, parentPath)
+  const withProject = spec.withProject ?? !spec.noProject
+
+  const systemEntry = `  ${JSON.stringify(localId)}: {
+    id: ${JSON.stringify(systemPath)},
+    order: ${order},
+    label: ${JSON.stringify(label)},
+    description: ${JSON.stringify(spec.description ?? `${label} bounded context.`)},
+    kind: ${JSON.stringify(spec.kind ?? 'operational')},
+    ${parentPath === undefined ? '' : `parentSystemId: ${JSON.stringify(parentPath)},\n    `}responsibleRoleId: ${JSON.stringify(roleId)},
+    governedByKnowledge: [${JSON.stringify(knowledgeId)}],
+    drivesGoals: [],
+    lifecycle: 'draft',
+    ui: {
+      path: ${JSON.stringify(uiPath)},
+      surfaces: [],
+      ${spec.icon === undefined ? '' : `icon: ${JSON.stringify(spec.icon)},`}
+    }${spec.withOntology ? `,
+    ontology: {
+      objectTypes: {}
+    }` : ''}
+  }`
+
+  const plan: OmScaffoldPlan = {
+    intent: 'system',
+    id: systemPath,
+    summary: `Scaffold System "${systemPath}" with nav, role wiring, governing knowledge, and a UI manifest stub.`,
+    writes: [
+      {
+        path: `packages/ui/src/features/${featureSlug}/manifest.stub.ts`,
+        mode: 'create',
+        description: 'SystemModule manifest stub. Route files are intentionally not generated.',
+        content: `import type { SystemModule } from '@repo/ui'\n\nexport const ${featureSlug.replaceAll('-', '_')}Manifest: SystemModule = {\n  systemId: ${JSON.stringify(systemPath)},\n  label: ${JSON.stringify(label)},\n  routes: []\n}\n`
+      },
+      {
+        path: `packages/elevasis-core/src/knowledge/nodes/${featureSlug}-system-overview.mdx.stub`,
+        mode: 'create',
+        description: 'Governing knowledge skeleton for the new System.',
+        content: `---\nid: ${knowledgeId}\nkind: reference\ntitle: ${JSON.stringify(`${label} System Overview`)}\nsummary: ${JSON.stringify(`Governing context for the ${label} System.`)}\nlinks:\n  - system:${systemPath}\nownerIds:\n  - ${roleId}\nupdatedAt: 2026-05-15\n---\n\n## Purpose\n\nDocument the operating boundaries, decisions, and ownership for ${label}.\n`
+      }
+    ],
+    edits: [
+      {
+        path: 'packages/elevasis-core/src/organization-model/systems.ts',
+        description:
+          parentPath === undefined
+            ? 'Add this entry to platformSystems.'
+            : `Add this entry under platformSystems ${parentPath}.systems.`,
+        snippet: systemEntry
+      },
+      {
+        path: 'packages/elevasis-core/src/organization-model/navigation.ts',
+        description: 'Confirm sidebar placement derives from ui.path or add explicit surface targeting if needed.',
+        snippet: `// System "${systemPath}" declares ui.path ${JSON.stringify(uiPath)}. Do not add route files in /om create.`
+      },
+      {
+        path: 'packages/elevasis-core/src/organization-model/roles.ts',
+        description: `Confirm ${roleId} exists or add the owning role before merging.`,
+        snippet: `// responsibleRoleId: ${JSON.stringify(roleId)}`
+      },
+      {
+        path: 'packages/elevasis-core/src/organization-model/assembly.ts',
+        description: 'Confirm roleFor()/owner routing covers the new System.',
+        snippet: `case ${JSON.stringify(systemPath)}:\n  return ${JSON.stringify(roleId)}`
+      },
+      {
+        path: 'packages/elevasis-core/src/organization-model/knowledge.ts',
+        description: 'Register the generated governing knowledge node after replacing the .stub suffix.',
+        snippet: `${JSON.stringify(knowledgeId)}`
+      }
+    ],
+    warnings: spec.withOntology
+      ? ['Ontology was requested; the default objectTypes block is intentionally empty until the domain language is known.']
+      : ['Ontology is opt-in. Re-run with --with-ontology when the object/action/catalog language is known.'],
+    nextSteps: [
+      'Review the planned OM edits and apply them in the listed source files.',
+      'Replace .stub suffixes only after the System entry is merged.',
+      `Run pnpm exec elevasis om:verify --scope ${systemPath}.`
+    ]
+  }
+
+  return addProjectNextStep(
+    plan,
+    withProject,
+    `pnpm exec elevasis project:create --link-om ${systemPath} --title "Build ${label} System" --kind system-build`
+  )
+}

package/src/organization-model/scaffolders/types.ts

@@ -0,0 +1,81 @@
+import type {
+  OrganizationModelIconToken,
+  OrganizationModelResourceKind,
+  OrganizationModelSystemKind
+} from '../types'
+import type { OntologyKind } from '../ontology'
+
+export type OmScaffoldIntent = 'system' | 'ontology' | 'resource' | 'knowledge'
+
+export interface OmScaffoldWrite {
+  path: string
+  content: string
+  description: string
+  mode: 'create'
+}
+
+export interface OmScaffoldEdit {
+  path: string
+  description: string
+  snippet: string
+}
+
+export interface OmScaffoldPlan {
+  intent: OmScaffoldIntent
+  id: string
+  summary: string
+  writes: OmScaffoldWrite[]
+  edits: OmScaffoldEdit[]
+  warnings: string[]
+  nextSteps: string[]
+  projectCommand?: string
+}
+
+export interface BaseOmScaffoldSpec {
+  id: string
+  label?: string
+  description?: string
+}
+
+export interface SystemScaffoldSpec extends BaseOmScaffoldSpec {
+  intent: 'system'
+  parent?: string
+  kind?: OrganizationModelSystemKind
+  uiPath?: string
+  icon?: OrganizationModelIconToken
+  role?: string
+  withOntology?: boolean
+  noProject?: boolean
+  withProject?: boolean
+}
+
+export interface OntologyRecordScaffoldSpec extends BaseOmScaffoldSpec {
+  intent: 'ontology'
+  systemPath: string
+  kind: OntologyKind
+  localId?: string
+  withProject?: boolean
+}
+
+export interface ResourceScaffoldSpec extends BaseOmScaffoldSpec {
+  intent: 'resource'
+  systemPath: string
+  kind?: OrganizationModelResourceKind
+  ownerRoleId?: string
+  withStubWorkflow?: boolean
+  withProject?: boolean
+}
+
+export interface KnowledgeNodeScaffoldSpec extends BaseOmScaffoldSpec {
+  intent: 'knowledge'
+  systemPath?: string
+  kind?: 'playbook' | 'strategy' | 'reference'
+  ownerRoleId?: string
+  withProject?: boolean
+}
+
+export type OmScaffoldSpec =
+  | SystemScaffoldSpec
+  | OntologyRecordScaffoldSpec
+  | ResourceScaffoldSpec
+  | KnowledgeNodeScaffoldSpec