---
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 seven sub-scripts:

| Script                 | Input                                                                                                                 | Output                                                                                                     |
| ---------------------- | --------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| `scaffold:generate`    | Scaffold contract and feature-registry sources                                                                        | `packages/core/src/reference/_generated/**`, `packages/ui/src/scaffold/_generated/feature-registry.md`     |
| `knowledge:generate`   | Elevasis core knowledge nodes and UI knowledge body sources                                                           | Generated knowledge nodes and UI knowledge bodies                                                          |
| `gen:sdk-catalog`      | SDK catalog source definitions                                                                                         | SDK catalog artifacts                                                                                      |
| `gen:sdk-adapters`     | SDK adapter definitions                                                                                                | SDK adapter artifacts                                                                                      |
| `copy-docs`            | SDK docs, package-owned reference docs, scaffold docs, and `_template/.claude` config                                  | `packages/sdk/reference/**` copied docs and scaffold reference bundle                                       |
| `sdk-ref:generate`     | SDK manifest and navigation sources                                                                                    | `packages/sdk/reference/_reference-manifest.json`, `packages/sdk/reference/_navigation.md`                  |
| `sdk-ref:check`        | Generated SDK reference artifacts                                                                                      | Freshness validation for `packages/sdk/reference/_reference-manifest.json` and `_navigation.md`             |

The final `sdk-ref:check` step validates that the reference artifacts 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/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      |
