@elevasis/sdk 1.20.2 → 1.22.0

package/reference/claude-config/skills/knowledge/operations/codify-level-a.md

@@ -1,100 +1,100 @@
-# Codify Pipeline: Level A (Config-Only Edits)
-
-Level A is the codify pipeline for changes that land exclusively in
-`core/config/organization-model.ts`. No new TypeScript files are created. The entire
-ceremony is: snapshot current file, propose the edit, write the edit, validate, and roll back on
-failure.
-
-This pipeline is called by domain operations (identity, customers, offerings, roles, goals,
-techStack, features, labels) after the user has confirmed the proposed change. The caller provides
-the specific field/block being changed and the proposed new value.
-
----
-
-## Pipeline
-
-### Step 1: Snapshot
-
-Before any write, read `core/config/organization-model.ts` and keep the full file content
-in memory as the rollback snapshot. Do not write any file during this step.
-
-```
-Read("core/config/organization-model.ts")
--- store as ROLLBACK_SNAPSHOT
-```
-
-### Step 2: Apply the edit
-
-Use the Edit tool to apply the caller's proposed change to
-`core/config/organization-model.ts`.
-
-Rules for the edit:
-
-- Edit only the specific field or block the caller specified. Do not reformat or restructure
-  unrelated sections.
-- Preserve all other keys in `defineOrganizationModel({...})` exactly as they are.
-- Maintain the existing code style (trailing commas, quote style, indentation) of the file.
-- If the target field does not yet exist in the adapter call, add it as a new property in the
-  appropriate position (following the declared domain order in the schema).
-
-### Step 3: TypeScript type-check
-
-Run the type-check for the operations package:
-
-```bash
-pnpm -C operations check-types
-```
-
-Capture stdout and stderr. If the command exits non-zero, proceed to Step 5 (rollback).
-
-### Step 4: Runtime schema validation
-
-Confirm that the adapter's output passes `OrganizationModelSchema.parse()`. The adapter calls
-`resolveOrganizationModel()` internally, which merges defaults with overrides and then parses the
-result. A successful `check-types` pass is strong evidence that the schema is valid, but
-cross-reference checks (segment ID refs in offerings, role reporting refs, period ordering in
-goals) are runtime-only.
-
-If the project exposes a validation script (e.g. `pnpm -C operations check`), run that too:
-
-```bash
-pnpm -C operations check
-```
-
-If either validation step fails, proceed to Step 5 (rollback).
-
-### Step 5: Rollback (on failure only)
-
-If Step 3 or Step 4 failed:
-
-1. Write the ROLLBACK_SNAPSHOT content back to `core/config/organization-model.ts`
-   verbatim (use the Write tool with the exact snapshot content).
-2. Confirm the file has been restored by checking that the content matches the snapshot.
-3. Return the error message to the caller.
-
-The caller is responsible for reporting the rollback to the user.
-
-### Step 6: Success signal
-
-If Steps 3 and 4 both passed, return a success signal to the caller with:
-
-- The fields changed
-- `Type-check: PASS`
-- `Schema validation: PASS`
-
-The caller formats and presents the final report.
-
----
-
-## Caller Contract
-
-Callers must provide before invoking this pipeline:
-
-- **Target file:** always `core/config/organization-model.ts`
-- **Target block:** the specific domain key or sub-key being changed (e.g. `identity`,
-  `customers.segments`, `roles.roles`, `resources.entries[id="hubspot"]`)
-- **Proposed value:** the new TypeScript literal to write for that block
-- **Confirmed:** the user has already said yes to the proposed change
-
-This pipeline does not ask the user any questions. All confirmation happens in the domain
-operation before this pipeline is invoked.
+# Codify Pipeline: Level A (Config-Only Edits)
+
+Level A is the codify pipeline for changes that land exclusively in
+`core/config/organization-model.ts`. No new TypeScript files are created. The entire
+ceremony is: snapshot current file, propose the edit, write the edit, validate, and roll back on
+failure.
+
+This pipeline is called by domain operations (identity, customers, offerings, roles, goals,
+techStack, systems, actions, labels, and legacy feature compatibility) after the user has confirmed the proposed change. The caller provides
+the specific field/block being changed and the proposed new value.
+
+---
+
+## Pipeline
+
+### Step 1: Snapshot
+
+Before any write, read `core/config/organization-model.ts` and keep the full file content
+in memory as the rollback snapshot. Do not write any file during this step.
+
+```
+Read("core/config/organization-model.ts")
+-- store as ROLLBACK_SNAPSHOT
+```
+
+### Step 2: Apply the edit
+
+Use the Edit tool to apply the caller's proposed change to
+`core/config/organization-model.ts`.
+
+Rules for the edit:
+
+- Edit only the specific field or block the caller specified. Do not reformat or restructure
+  unrelated sections.
+- Preserve all other keys in `defineOrganizationModel({...})` exactly as they are.
+- Maintain the existing code style (trailing commas, quote style, indentation) of the file.
+- If the target field does not yet exist in the adapter call, add it as a new property in the
+  appropriate position (following the declared domain order in the schema).
+
+### Step 3: TypeScript type-check
+
+Run the type-check for the operations package:
+
+```bash
+pnpm -C operations check-types
+```
+
+Capture stdout and stderr. If the command exits non-zero, proceed to Step 5 (rollback).
+
+### Step 4: Runtime schema validation
+
+Confirm that the adapter's output passes `OrganizationModelSchema.parse()`. The adapter calls
+`resolveOrganizationModel()` internally, which merges defaults with overrides and then parses the
+result. A successful `check-types` pass is strong evidence that the schema is valid, but
+cross-reference checks (segment ID refs in offerings, role reporting refs, period ordering in
+goals) are runtime-only.
+
+If the project exposes a validation script (e.g. `pnpm -C operations check`), run that too:
+
+```bash
+pnpm -C operations check
+```
+
+If either validation step fails, proceed to Step 5 (rollback).
+
+### Step 5: Rollback (on failure only)
+
+If Step 3 or Step 4 failed:
+
+1. Write the ROLLBACK_SNAPSHOT content back to `core/config/organization-model.ts`
+   verbatim (use the Write tool with the exact snapshot content).
+2. Confirm the file has been restored by checking that the content matches the snapshot.
+3. Return the error message to the caller.
+
+The caller is responsible for reporting the rollback to the user.
+
+### Step 6: Success signal
+
+If Steps 3 and 4 both passed, return a success signal to the caller with:
+
+- The fields changed
+- `Type-check: PASS`
+- `Schema validation: PASS`
+
+The caller formats and presents the final report.
+
+---
+
+## Caller Contract
+
+Callers must provide before invoking this pipeline:
+
+- **Target file:** always `core/config/organization-model.ts`
+- **Target block:** the specific domain key or sub-key being changed (e.g. `identity`,
+  `customers.segments`, `roles.roles`, `resources.hubspot`)
+- **Proposed value:** the new TypeScript literal to write for that block
+- **Confirmed:** the user has already said yes to the proposed change
+
+This pipeline does not ask the user any questions. All confirmation happens in the domain
+operation before this pipeline is invoked.

package/reference/claude-config/skills/knowledge/operations/codify-level-b.md

@@ -1,158 +1,159 @@
-# Codify Pipeline: Level B (New Extension TypeScript Files)
-
-Level B is the codify pipeline for changes that require creating a new TypeScript file under
-`core/config/extensions/`. This pipeline is used when the user wants to add a custom
-feature, a custom entity type, or any structural addition that cannot be expressed as a simple
-field override in `core/config/organization-model.ts`.
-
-Level B is **only offered when the user explicitly asks** for something that requires a new file.
-Never silently escalate from Level A to Level B. If Level A is sufficient, use it.
-
----
-
-## When Level B applies
-
-- Adding a custom feature that does not exist in the platform defaults (new `FeatureSchema` entry
-  with a custom ID, manifest wiring, and route references)
-- Adding a custom entity extension (new Zod schema extending a base entity type)
-- Any structural addition the caller's domain operation has determined cannot be expressed as a
-  field value in the existing adapter
-
-The calling operation (e.g. `features.md`) is responsible for deciding when Level B is needed
-and for confirming the intent with the user before invoking this pipeline.
-
----
-
-## Pipeline
-
-### Step 1: Snapshot all files that will be touched
-
-Before any write, read and snapshot:
-
-1. `core/config/organization-model.ts` (always touched for wiring)
-2. The target extension file path (if it already exists -- confirm overwrite with user)
-
-```
-Read("core/config/organization-model.ts")   -- store as ROLLBACK_ADAPTER
-Read("core/config/extensions/{target}.ts")  -- store as ROLLBACK_EXTENSION (if exists)
-```
-
-The target extension file path follows the naming convention:
-`core/config/extensions/{kebab-case-feature-id}.ts`
-
-### Step 2: Scaffold the extension file
-
-Create `core/config/extensions/{id}.ts` using the Write tool.
-
-The file shape depends on the extension type:
-
-**Custom feature (most common Level B case):**
-
-```typescript
-/**
- * {Feature label} feature extension.
- * Registered in core/config/organization-model.ts.
- */
-import type { OrganizationModelFeature } from '@elevasis/core/organization-model'
-
-export const {FEATURE_CONST}: OrganizationModelFeature = {
-  id: '{feature-id}',
-  label: '{Feature Label}',
-  description: '{optional description}',
-  enabled: true,
-  entityIds: [],
-  surfaceIds: [],
-  resourceIds: [],
-  capabilityIds: [],
-}
-```
-
-Replace `{FEATURE_CONST}` with the SCREAMING_SNAKE_CASE version of the feature ID
-(e.g. `CLIENT_PORTAL_FEATURE`).
-
-The caller provides the exact field values based on what the user confirmed.
-
-### Step 3: Wire the extension into the adapter
-
-Edit `core/config/organization-model.ts` to:
-
-1. Import the new constant from the extension file.
-2. Add it to the `features` array in the `defineOrganizationModel({...})` call.
-
-Example import addition:
-
-```typescript
-import { CLIENT_PORTAL_FEATURE } from './extensions/client-portal'
-```
-
-Example features array addition:
-
-```typescript
-features: [
-  ...existingFeatures,
-  CLIENT_PORTAL_FEATURE,
-],
-```
-
-### Step 4: TypeScript type-check
-
-```bash
-pnpm -C operations check-types
-```
-
-Capture stdout and stderr. If the command exits non-zero, proceed to Step 6 (rollback).
-
-### Step 5: Runtime schema validation
-
-```bash
-pnpm -C operations check
-```
-
-If either check fails, proceed to Step 6 (rollback).
-
-### Step 6: Rollback (on failure only)
-
-If Step 4 or Step 5 failed:
-
-1. Restore `core/config/organization-model.ts` from ROLLBACK_ADAPTER.
-2. If the extension file did not previously exist, delete it. If it previously existed, restore
-   from ROLLBACK_EXTENSION.
-3. Re-run `pnpm -C operations check-types` to confirm the restore is clean. If the restore
-   itself fails type-check, report both the original error and the restore state to the user --
-   do not silently leave the project in a broken state.
-4. Return the error message to the caller.
-
-### Step 7: Success signal
-
-If Steps 4 and 5 both passed, return a success signal to the caller with:
-
-- Extension file path created
-- Adapter wiring changes (import + features array entry)
-- `Type-check: PASS`
-- `Schema validation: PASS`
-
-The caller formats and presents the final report to the user.
-
----
-
-## Caller Contract
-
-Callers must provide before invoking this pipeline:
-
-- **Extension file path:** `core/config/extensions/{id}.ts`
-- **Extension file content:** the full TypeScript content for the new file
-- **Adapter changes:** the exact import line and features-array addition to write into the adapter
-- **Confirmed:** the user has already said yes to the proposed change and explicitly requested
-  a new extension file
-
-This pipeline does not ask the user any questions. All confirmation and escalation decisions
-happen in the domain operation before this pipeline is invoked.
-
----
-
-## Constraint: Extension files are Tier 3 (never synced)
-
-Files under `core/config/extensions/` are Tier 3 -- project-specific, never overwritten
-by `/external sync`. This means custom features and entity extensions survive template upgrades
-automatically. Do not put platform-default overrides in extension files; those belong directly in
-`core/config/organization-model.ts` (Tier 2, merge-aware).
+# Codify Pipeline: Level B (New Extension TypeScript Files)
+
+Level B is the codify pipeline for changes that require creating a new TypeScript file under
+`core/config/extensions/`. This pipeline is used when the user wants to add or extend a System,
+add an Action, add a custom entity type, or make any structural addition that cannot be expressed as a simple
+field override in `core/config/organization-model.ts`.
+
+Level B is **only offered when the user explicitly asks** for something that requires a new file.
+Never silently escalate from Level A to Level B. If Level A is sufficient, use it.
+
+---
+
+## When Level B applies
+
+- Adding or extending a System that does not exist in the platform defaults, including routing,
+  manifest wiring, and route references
+- Adding an Action that is invokable by a workflow, agent, command, or UI trigger
+- Adding a custom entity extension (new Zod schema extending a base entity type)
+- Any structural addition the caller's domain operation has determined cannot be expressed as a
+  field value in the existing adapter
+
+The calling operation (or the legacy compatibility notes in `features.md`) is responsible for deciding when Level B is needed
+and for confirming the intent with the user before invoking this pipeline.
+
+---
+
+## Pipeline
+
+### Step 1: Snapshot all files that will be touched
+
+Before any write, read and snapshot:
+
+1. `core/config/organization-model.ts` (always touched for wiring)
+2. The target extension file path (if it already exists -- confirm overwrite with user)
+
+```
+Read("core/config/organization-model.ts")   -- store as ROLLBACK_ADAPTER
+Read("core/config/extensions/{target}.ts")  -- store as ROLLBACK_EXTENSION (if exists)
+```
+
+The target extension file path follows the naming convention:
+`core/config/extensions/{kebab-case-system-or-action-id}.ts`
+
+### Step 2: Scaffold the extension file
+
+Create `core/config/extensions/{id}.ts` using the Write tool.
+
+The file shape depends on the extension type:
+
+**Custom system/action extension (common Level B case):**
+
+```typescript
+/**
+ * {System or action label} extension.
+ * Registered in core/config/organization-model.ts.
+ */
+import type { OrganizationModelSystem } from '@elevasis/core/organization-model'
+
+export const {SYSTEM_CONST}: OrganizationModelSystem = {
+  id: '{system-or-action-id}',
+  label: '{System or Action Label}',
+  description: '{optional description}',
+  enabled: true,
+  entityIds: [],
+  surfaceIds: [],
+  resourceIds: [],
+  actionIds: [],
+}
+```
+
+Replace `{SYSTEM_CONST}` with the SCREAMING_SNAKE_CASE version of the system or action ID
+(e.g. `CLIENT_PORTAL_SYSTEM`).
+
+The caller provides the exact field values based on what the user confirmed.
+
+### Step 3: Wire the extension into the adapter
+
+Edit `core/config/organization-model.ts` to:
+
+1. Import the new constant from the extension file.
+2. Add it to the appropriate `systems` or `actions` collection in the `defineOrganizationModel({...})` call.
+
+Example import addition:
+
+```typescript
+import { CLIENT_PORTAL_SYSTEM } from './extensions/client-portal'
+```
+
+Example system collection addition:
+
+```typescript
+systems: [
+  ...existingSystems,
+  CLIENT_PORTAL_SYSTEM,
+],
+```
+
+### Step 4: TypeScript type-check
+
+```bash
+pnpm -C operations check-types
+```
+
+Capture stdout and stderr. If the command exits non-zero, proceed to Step 6 (rollback).
+
+### Step 5: Runtime schema validation
+
+```bash
+pnpm -C operations check
+```
+
+If either check fails, proceed to Step 6 (rollback).
+
+### Step 6: Rollback (on failure only)
+
+If Step 4 or Step 5 failed:
+
+1. Restore `core/config/organization-model.ts` from ROLLBACK_ADAPTER.
+2. If the extension file did not previously exist, delete it. If it previously existed, restore
+   from ROLLBACK_EXTENSION.
+3. Re-run `pnpm -C operations check-types` to confirm the restore is clean. If the restore
+   itself fails type-check, report both the original error and the restore state to the user --
+   do not silently leave the project in a broken state.
+4. Return the error message to the caller.
+
+### Step 7: Success signal
+
+If Steps 4 and 5 both passed, return a success signal to the caller with:
+
+- Extension file path created
+- Adapter wiring changes (import + systems/actions collection entry)
+- `Type-check: PASS`
+- `Schema validation: PASS`
+
+The caller formats and presents the final report to the user.
+
+---
+
+## Caller Contract
+
+Callers must provide before invoking this pipeline:
+
+- **Extension file path:** `core/config/extensions/{id}.ts`
+- **Extension file content:** the full TypeScript content for the new file
+- **Adapter changes:** the exact import line and systems/actions collection addition to write into the adapter
+- **Confirmed:** the user has already said yes to the proposed change and explicitly requested
+  a new extension file
+
+This pipeline does not ask the user any questions. All confirmation and escalation decisions
+happen in the domain operation before this pipeline is invoked.
+
+---
+
+## Constraint: Extension files are Tier 3 (never synced)
+
+Files under `core/config/extensions/` are Tier 3 -- project-specific, never overwritten
+by `/external sync`. This means custom systems, actions, and entity extensions survive template upgrades
+automatically. Do not put platform-default overrides in extension files; those belong directly in
+`core/config/organization-model.ts` (Tier 2, merge-aware).