# Organization Model Ontology Refactor

## Why this note exists

The template now demonstrates the Organization Model ontology and topology bridge. New semantic contracts should be authored in `System.ontology`; executable Resources bind through `resource.ontology.actions` and optional `resource.ontology.primaryAction`; durable operational wiring belongs in `organizationModel.topology.relationships`. Legacy `entities`, `actions`, and `System.content` remain compatibility mirrors for current consumers.

## Applies to

- `core/config/organization-model.ts`
- `core/config/organization-model.test.ts`
- `core/config/organization-model.contract.test.ts`
- `core/config/README.md`
- `operations/src/index.ts`
- `operations/src/resource-registry.test.ts`
- `operations/src/README.md`
- `.claude/rules/organization-model.md`
- `.claude/rules/operations.md`

## Required actions

1. Preserve system-colocated ontology scopes when syncing template organization-model changes.
2. Migrate Resource descriptors from `ontology.implements` / `actionKey` to `ontology.actions` / `ontology.primaryAction`; keep `codeRefs` with the Resource descriptor.
3. Preserve `organizationModel.topology.relationships` when syncing template organization-model changes; keep secrets, credential values, provider webhook mechanics, and per-run state outside the OM.
4. Keep `entities`, `actions`, and `System.content` aligned as compatibility mirrors until downstream consumers move fully to compiled ontology indexes.
5. Do not overwrite project-owned `core/config/extensions/**` files.

## Verification

Run the template verification lane after applying this sync:

```bash
pnpm -C external/_template/core test
pnpm -C external/_template/core exec tsc --noEmit
pnpm -C external/_template/operations check
pnpm -C external/_template/operations check-types
pnpm -C external/_template/operations test
pnpm sync:verify --pre
```

## Not handled by /git-sync

- Choosing project-specific ontology IDs for tenant-owned systems.
- Choosing project-specific topology relationships for tenant-owned workflows, checkpoints, integrations, or schedules.
- Migrating project-owned extension files under `core/config/extensions/**`.
- Retiring compatibility mirrors before the full internal, SDK, scaffold, and external template-family green cycle.
