@elevasis/sdk 1.28.1 → 1.30.0

package/reference/scaffold/operations/propagation-pipeline.md

@@ -1,156 +1,156 @@
----
-title: Propagation Pipeline
-description: Three-layer pipeline that keeps Organization OS artifacts current across the monorepo and all template-derived external projects -- source generation, registry-driven sync planning/apply, and verification.
----
+---
+title: Propagation Pipeline
+description: Three-layer pipeline that keeps Organization OS artifacts current across the monorepo and all template-derived external projects -- source generation, registry-driven sync planning/apply, and verification.
+---
 <!-- @generated by packages/sdk/scripts/copy-reference-docs.mjs -- DO NOT EDIT -->
 <!-- Regenerate: pnpm scaffold:sync -->
 
-
-# Propagation Pipeline
-
-`🟢 Stable` -- These pipelines run automatically. Understand them when debugging sync issues or extending the scaffold.
-
----
-
-## Architecture
-
-The Organization OS propagation pipeline has three layers. Each has its own scripts, triggers, and failure modes.
-
-```
-Layer 1: Source Generation (pnpm scaffold:sync)
-   Regenerates derived docs from TypeScript types and manifests
-        ↓
-Layer 2: Registry-Driven Sync Planning + Apply (/external sync)
-   Plans registry-backed writes/deletes, then applies the approved scope
-        ↓
-Layer 3: Sync Verification (pnpm sync:verify)
-   Asserts correctness across all template-derived projects after apply
-```
-
----
-
-## Layer 1: Source Generation
-
-`pnpm scaffold:sync` is the meta-script that regenerates all derived documentation and validates the output. It chains three sub-scripts:
-
-| Script                                  | Input                                                                                                                                         | Output                                                              |
-| --------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- |
-| `generate-scaffold-contracts.js`        | `packages/core/src/organization-model/types.ts`, `packages/ui/src/features/registry/types.ts`, `packages/core/src/platform/registry/types.ts` | `packages/core/src/reference/_generated/contracts.md`               |
-| `generate-scaffold-feature-registry.js` | `packages/ui/src/features/registry/manifests.ts`, `packages/ui/src/features/*/manifest.ts`                                                    | `packages/ui/src/scaffold/_generated/feature-registry.md`           |
-| `generate-reference-artifacts.js`       | SDK manifest, navigation sources                                                                                                              | `packages/sdk/reference/_reference-manifest.json`, `_navigation.md` |
-
-After generation, `validate-reference-artifacts.js` checks that the outputs are consistent. Exit 1 if drifted.
-
-### Trigger Points
-
-- **`/external sync` Phase 0 (Scaffold Sync Preflight):** Runs before any writes. Generated file changes fold into the sync scope so they propagate naturally to `_template` and downstream projects.
-- **`/sdk release` Step 1 (Shared Reference Preflight):** Runs before publish. Generated changes must be committed; validator failure is a hard blocker.
-- **Manual:** `pnpm scaffold:sync` is idempotent and safe to run anytime.
-- **Opt-out:** `--skip-scaffold-sync` on `/external sync` (rare).
-
-### Design: Regenerate-on-Propagation
-
-Drift is healed at the moment it would otherwise leak downstream. This is cheaper and more reliable than CI-only checks. The single meta-script gives one command to reason about, while the chained sub-scripts remain individually callable for debugging.
-
----
-
-## Layer 2: Registry-Driven Sync Planning + Apply
-
-`/external sync` now treats the scaffold registry as the execution contract rather than relying on tier prose alone.
-The canonical ownership vocabulary is:
-
-| Category        | Strategy examples                               | Meaning                                                                 |
-| --------------- | ----------------------------------------------- | ----------------------------------------------------------------------- |
-| `replace`       | `replace-all`                                   | Template-managed surface; copy from template baseline                   |
-| `merge`         | `merge-baseline`, `merge-regions`               | Merge-aware surface; preserve project customizations where required     |
-| `never-touch`   | `verify-only`                                   | Project-owned surface; planner may report drift but never writes        |
-| `generated`     | `generated-freshness`                           | Generated surface; verify/regen instead of copying                      |
-
-Current command helpers:
-
-```bash
-pnpm sync:plan -- --all                  # registry-backed dry-run plan
-pnpm sync:apply -- --all                 # registry-backed apply pass
-pnpm sync:verify                         # post-apply verification
-```
-
-Per-project or scoped runs pass the project name and optional `--path` / `--source` filters through to the planner/apply script.
-
-Delete behavior is explicit:
-
-- managed deletes apply only to `replace` surfaces
-- deletion is allowed only when the path appears in the manifest-backed tombstone list
-- absence from the template alone is not enough to delete a downstream file
-
-Generated surfaces are also explicit:
-
-- they are planned as `generated`
-- apply does not copy them as normal source files
-- the relevant regen command must run, then `pnpm sync:verify` checks freshness
-
-The external skill doc (`.claude/skills/external/SKILL.md`) remains the workflow authority, but it should be read as planner/apply/verify orchestration over the registry model above.
-
----
-
-## Layer 3: Sync Verification
-
-`pnpm sync:verify` runs 86+ automated checks to assert propagation correctness. The script lives at `scripts/external/verify-sync.js`.
-
-### Per-Project Checks (auto-discovered)
-
-| Category       | What It Checks                                                                                                                                                                                                                                                                                                                                              |
-| -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `deps`         | `@elevasis/ui`, `@elevasis/sdk`, `@elevasis/core` versions match template                                                                                                                                                                                                                                                                                   |
-| `tier1`        | registry-backed replace surfaces match template where verification still models them as exact baselines                                                                                                                                                                                                                                                     |
+
+# Propagation Pipeline
+
+`🟢 Stable` -- These pipelines run automatically. Understand them when debugging sync issues or extending the scaffold.
+
+---
+
+## Architecture
+
+The Organization OS propagation pipeline has three layers. Each has its own scripts, triggers, and failure modes.
+
+```
+Layer 1: Source Generation (pnpm scaffold:sync)
+   Regenerates derived docs from TypeScript types and manifests
+        ↓
+Layer 2: Registry-Driven Sync Planning + Apply (/external sync)
+   Plans registry-backed writes/deletes, then applies the approved scope
+        ↓
+Layer 3: Sync Verification (pnpm sync:verify)
+   Asserts correctness across all template-derived projects after apply
+```
+
+---
+
+## Layer 1: Source Generation
+
+`pnpm scaffold:sync` is the meta-script that regenerates all derived documentation and validates the output. It chains three sub-scripts:
+
+| Script                                  | Input                                                                                                                                         | Output                                                              |
+| --------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- |
+| `generate-scaffold-contracts.js`        | `packages/core/src/organization-model/types.ts`, `packages/ui/src/features/registry/types.ts`, `packages/core/src/platform/registry/types.ts` | `packages/core/src/reference/_generated/contracts.md`               |
+| `generate-scaffold-feature-registry.js` | `packages/ui/src/features/registry/manifests.ts`, `packages/ui/src/features/*/manifest.ts`                                                    | `packages/ui/src/scaffold/_generated/feature-registry.md`           |
+| `generate-reference-artifacts.js`       | SDK manifest, navigation sources                                                                                                              | `packages/sdk/reference/_reference-manifest.json`, `_navigation.md` |
+
+After generation, `validate-reference-artifacts.js` checks that the outputs are consistent. Exit 1 if drifted.
+
+### Trigger Points
+
+- **`/external sync` Phase 0 (Scaffold Sync Preflight):** Runs before any writes. Generated file changes fold into the sync scope so they propagate naturally to `_template` and downstream projects.
+- **`/sdk release` Step 1 (Shared Reference Preflight):** Runs before publish. Generated changes must be committed; validator failure is a hard blocker.
+- **Manual:** `pnpm scaffold:sync` is idempotent and safe to run anytime.
+- **Opt-out:** `--skip-scaffold-sync` on `/external sync` (rare).
+
+### Design: Regenerate-on-Propagation
+
+Drift is healed at the moment it would otherwise leak downstream. This is cheaper and more reliable than CI-only checks. The single meta-script gives one command to reason about, while the chained sub-scripts remain individually callable for debugging.
+
+---
+
+## Layer 2: Registry-Driven Sync Planning + Apply
+
+`/external sync` now treats the scaffold registry as the execution contract rather than relying on tier prose alone.
+The canonical ownership vocabulary is:
+
+| Category      | Strategy examples                 | Meaning                                                             |
+| ------------- | --------------------------------- | ------------------------------------------------------------------- |
+| `replace`     | `replace-all`                     | Template-managed surface; copy from template baseline               |
+| `merge`       | `merge-baseline`, `merge-regions` | Merge-aware surface; preserve project customizations where required |
+| `never-touch` | `verify-only`                     | Project-owned surface; planner may report drift but never writes    |
+| `generated`   | `generated-freshness`             | Generated surface; verify/regen instead of copying                  |
+
+Current command helpers:
+
+```bash
+pnpm sync:plan -- --all                  # registry-backed dry-run plan
+pnpm sync:apply -- --all                 # registry-backed apply pass
+pnpm sync:verify                         # post-apply verification
+```
+
+Per-project or scoped runs pass the project name and optional `--path` / `--source` filters through to the planner/apply script.
+
+Delete behavior is explicit:
+
+- managed deletes apply only to `replace` surfaces
+- deletion is allowed only when the path appears in the manifest-backed tombstone list
+- absence from the template alone is not enough to delete a downstream file
+
+Generated surfaces are also explicit:
+
+- they are planned as `generated`
+- apply does not copy them as normal source files
+- the relevant regen command must run, then `pnpm sync:verify` checks freshness
+
+The external skill doc (`.claude/skills/external/SKILL.md`) remains the workflow authority, but it should be read as planner/apply/verify orchestration over the registry model above.
+
+---
+
+## Layer 3: Sync Verification
+
+`pnpm sync:verify` runs 86+ automated checks to assert propagation correctness. The script lives at `scripts/external/verify-sync.js`.
+
+### Per-Project Checks (auto-discovered)
+
+| Category       | What It Checks                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `deps`         | `@elevasis/ui`, `@elevasis/sdk`, `@elevasis/core` versions match template                                                                                                                                                                                                                                                                                                                                                                                                  |
+| `tier1`        | registry-backed replace surfaces match template where verification still models them as exact baselines                                                                                                                                                                                                                                                                                                                                                                    |
 | `org-os`       | Organization model exists, exports canonical symbols, imports from `@elevasis/core/organization-model`, either calls `createFoundationOrganizationModel` or uses explicit `resolveOrganizationModel(..., { mergeDefaults: false })` canonical assembly, app-config references org model, `__root.tsx` uses `ElevasisAuthenticatedShell` / `ElevasisSystemsProvider` + `canonicalOrganizationModel`, `main.tsx` uses `createElevasisApp`, all 3 CSS subpath imports present |
-| `placeholders` | No unresolved `__PROJECT_SLUG__`, `__PROJECT_NAME__`, `__PROJECT_DESCRIPTION__` in key config files                                                                                                                                                                                                                                                         |
-| `scripts`      | `ui` and `operations` `package.json` have required npm scripts                                                                                                                                                                                                                                                                                              |
-| `lib`          | `ui/src/lib/`, `lib/`, `test-utils/` exist with minimum file counts                                                                                                                                                                                                                                                                                         |
-| `tier3`        | project-owned preservation boundaries such as `nav-items.ts` remain intact                                                                                                                                                                                                                                                                                  |
-| `conflicts`    | No merge conflict markers in source files                                                                                                                                                                                                                                                                                                                   |
-| `git`          | Working tree is clean                                                                                                                                                                                                                                                                                                                                       |
-| `lockfile`     | `pnpm-lock.yaml` and `node_modules` exist                                                                                                                                                                                                                                                                                                                   |
-
-### Monorepo-Level Checks
-
-| Category    | What It Checks                                  |
-| ----------- | ----------------------------------------------- |
-| `scaffold`  | `pnpm scaffold:sync` passes (artifacts current) |
-| `artifacts` | 5 generated artifacts exist and have content    |
-
-### Usage
-
-```bash
-pnpm sync:verify              # Post-sync assertion (exit 1 on failures)
-pnpm sync:verify --pre         # Pre-sync drift report (always exit 0)
-pnpm sync:verify -- ZentaraHQ  # Single project
-```
-
-### Integration Points
-
-- **`/external sync` preflight:** Runs `pnpm sync:verify --pre` before planning so current drift is visible before any writes
-- **`/external sync` planner/apply:** `pnpm sync:plan` previews registry-backed writes/deletes, then `pnpm sync:apply` executes the approved plan
-- **`/external sync` post-apply:** Runs `pnpm sync:verify` to assert correctness after the planner/apply pass
-- **Automated coverage:** tests live under `scripts/external/__tests__/` including planner/apply coverage
-
-### Planner Interpretation Note
-
-`pnpm sync:verify` still carries some historical `tier1` / `tier3` labels in its output, but the ownership semantics now come from the registry-backed categories used by the planner:
-
-- `.claude/commands/**`, `hooks/**`, `rules/**`, `scripts/**`, `skills/**`, and `.claude/settings.json` are managed `replace` surfaces
-- `nav-items.ts`, `operations/src/**`, `shared/src/**`, `CLAUDE.md`, and extension files are `never-touch`
-- generated surfaces are verified for freshness, not copied
-
-Treat the old tier labels as display shorthand inside the verifier, not as the canonical execution contract.
-
----
-
-## Remaining Gaps (Future Work)
-
-| Gap                                                                       | Priority |
-| ------------------------------------------------------------------------- | -------- |
-| System manifest validation (all manifests imported in `__root.tsx`)       | Medium   |
-| TypeScript verification (`check-types` per project)                       | Medium   |
-| Template docs surface validation (`docs/index.md`, `agent-start-here.md`) | Medium   |
-| Environment variable template validation (`.env.example` completeness)    | Low      |
-| CI drift check (fail if worktree dirty after `scaffold:sync`)             | Low      |
+| `placeholders` | No unresolved `__PROJECT_SLUG__`, `__PROJECT_NAME__`, `__PROJECT_DESCRIPTION__` in key config files                                                                                                                                                                                                                                                                                                                                                                        |
+| `scripts`      | `ui` and `operations` `package.json` have required npm scripts                                                                                                                                                                                                                                                                                                                                                                                                             |
+| `lib`          | `ui/src/lib/`, `lib/`, `test-utils/` exist with minimum file counts                                                                                                                                                                                                                                                                                                                                                                                                        |
+| `tier3`        | project-owned preservation boundaries such as `nav-items.ts` remain intact                                                                                                                                                                                                                                                                                                                                                                                                 |
+| `conflicts`    | No merge conflict markers in source files                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| `git`          | Working tree is clean                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
+| `lockfile`     | `pnpm-lock.yaml` and `node_modules` exist                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+
+### Monorepo-Level Checks
+
+| Category    | What It Checks                                  |
+| ----------- | ----------------------------------------------- |
+| `scaffold`  | `pnpm scaffold:sync` passes (artifacts current) |
+| `artifacts` | 5 generated artifacts exist and have content    |
+
+### Usage
+
+```bash
+pnpm sync:verify              # Post-sync assertion (exit 1 on failures)
+pnpm sync:verify --pre         # Pre-sync drift report (always exit 0)
+pnpm sync:verify -- ZentaraHQ  # Single project
+```
+
+### Integration Points
+
+- **`/external sync` preflight:** Runs `pnpm sync:verify --pre` before planning so current drift is visible before any writes
+- **`/external sync` planner/apply:** `pnpm sync:plan` previews registry-backed writes/deletes, then `pnpm sync:apply` executes the approved plan
+- **`/external sync` post-apply:** Runs `pnpm sync:verify` to assert correctness after the planner/apply pass
+- **Automated coverage:** tests live under `scripts/external/__tests__/` including planner/apply coverage
+
+### Planner Interpretation Note
+
+`pnpm sync:verify` still carries some historical `tier1` / `tier3` labels in its output, but the ownership semantics now come from the registry-backed categories used by the planner:
+
+- `.claude/skills/**`, `hooks/**`, `rules/**`, `scripts/**`, and `.claude/settings.json` are managed `replace` surfaces
+- `nav-items.ts`, `operations/src/**`, `shared/src/**`, `CLAUDE.md`, and extension files are `never-touch`
+- generated surfaces are verified for freshness, not copied
+
+Treat the old tier labels as display shorthand inside the verifier, not as the canonical execution contract.
+
+---
+
+## Remaining Gaps (Future Work)
+
+| Gap                                                                       | Priority |
+| ------------------------------------------------------------------------- | -------- |
+| System manifest validation (all manifests imported in `__root.tsx`)       | Medium   |
+| TypeScript verification (`check-types` per project)                       | Medium   |
+| Template docs surface validation (`docs/index.md`, `agent-start-here.md`) | Medium   |
+| Environment variable template validation (`.env.example` completeness)    | Low      |
+| CI drift check (fail if worktree dirty after `scaffold:sync`)             | Low      |

package/reference/scaffold/operations/scaffold-maintenance.md

@@ -29,9 +29,10 @@ Scaffold docs are co-located with their owning package and copied into the SDK r
 | --------------------------- | --------------------------------------------------------------- | --------------------------------------------- |
 | Organization Model          | `packages/core/src/organization-model/organization-model.mdx`   | `scaffold/core/organization-model.mdx`        |
 | Organization Graph          | `packages/core/src/organization-model/organization-graph.mdx`   | `scaffold/core/organization-graph.mdx`        |
-| Glossary                    | `packages/core/src/reference/glossary.md`                       | `scaffold/reference/glossary.md`              |
-| Contracts (auto-gen)        | `packages/core/src/reference/_generated/contracts.md`           | `scaffold/reference/contracts.md`             |
-| UI Recipes                  | `packages/ui/src/scaffold/recipes.md`                           | `scaffold/ui/recipes.md`                      |
+| Glossary                    | `packages/core/src/reference/glossary.md`                       | `scaffold/reference/glossary.md`              |
+| Contracts (auto-gen)        | `packages/core/src/reference/_generated/contracts.md`           | `scaffold/reference/contracts.md`             |
+| System Interface Capabilities (auto-gen) | `packages/core/src/reference/_generated/system-interface-capabilities.md` | `scaffold/reference/system-interface-capabilities.md` |
+| UI Recipes                  | `packages/ui/src/scaffold/recipes.md`                           | `scaffold/ui/recipes.md`                      |
 | System Flags & Gating       | `packages/ui/src/scaffold/feature-flags-and-gating.md`          | `scaffold/ui/feature-flags-and-gating.md`     |
 | Customization               | `packages/ui/src/scaffold/customization.md`                     | `scaffold/ui/customization.md`                |
 | System Shell                | `packages/ui/src/scaffold/feature-shell.mdx`                    | `scaffold/ui/feature-shell.mdx`               |
@@ -57,7 +58,16 @@ Generated by `scripts/monorepo/generate-scaffold-contracts.js` from TypeScript s
 - `packages/ui/src/features/registry/types.ts` -- System Registry
 - `packages/core/src/platform/registry/types.ts` -- Resource Registry, Deployment Spec
 
-Output: `packages/core/src/reference/_generated/contracts.md`
+Output: `packages/core/src/reference/_generated/contracts.md`
+
+### System Interface Capabilities (`system-interface-capabilities.md`)
+
+Generated by `scripts/monorepo/generate-scaffold-contracts.js` from:
+
+- `packages/core/src/organization-model/domains/systems.ts` -- `SYSTEM_INTERFACE_PROFILES`
+- `packages/core/src/business/acquisition/ontology-validation.ts` -- derived-readiness validation constants and checks
+
+Output: `packages/core/src/reference/_generated/system-interface-capabilities.md`
 
 ### System Registry (`feature-registry.md`)