> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rkat.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Skills Governance Runbook

> Operational runbook for source UUID lifecycle, lineage migrations, and remap governance.

This runbook defines the required operator workflow for skill source identity changes.

## Canonical Identity

* Canonical identity is `SkillKey { source_uuid, skill_name }`.
* `source_uuid` is immutable unless changed through lineage events.
* Runtime execution paths consume canonical identity only.

## Required Source Record Fields

Every source identity record must include:

* `source_uuid`
* `display_name`
* `transport_kind`
* locator `fingerprint`
* `status` (`active`, `disabled`, or `retired`)

## Governance Checks

Startup rejects:

* UUID collisions with conflicting fingerprints unless lineage explicitly permits.
* UUID mutation without lineage.
* split/merge/rotate lineage without complete per-skill remap coverage.

## Companion Skill Governance

Every nontrivial Meerkat-owned agent-facing tool family should provide:

* concise tool descriptions and schemas
* human docs for concepts, guides, reference, and examples where appropriate
* an embedded companion skill gated by `requires_capabilities`

Document an explicit exemption when a built-in tool family is too small or too
mechanical to justify a companion skill.

Companion skills teach agents how to call existing tools. They must not become
semantic owners of lifecycle, readiness, policy, or terminal truth. Machines,
services, stores, and typed dispatch paths remain authoritative.

## Migration Procedures

### Rotate (one source to one source)

1. Add lineage event `rotate` from old UUID to new UUID.
2. Add remap rows for all affected skills (`old_uuid/skill` -> `new_uuid/skill`).
3. Deploy config and verify canonicalization tests pass.

### Rename or relocate (same logical source, new UUID/path binding)

1. Add lineage event `rename_or_relocate` from old UUID to new UUID.
2. Add remap rows for all affected skills.
3. Verify canonicalization still resolves the same semantic skills under the new source identity.

### Split (one source to many)

1. Add lineage event `split` with all target UUIDs.
2. Add explicit per-skill remaps from old UUID to exactly one target UUID per skill.
3. Reject deployment if any source skill lacks remap coverage.

### Merge (many sources to one)

1. Add lineage event `merge` with all origin UUIDs and target UUID.
2. Add explicit per-skill remaps from each origin UUID skill to target UUID skill.
3. Reject deployment if any origin skill lacks remap coverage.

## Incident Recovery

If startup fails with lineage/remap validation:

1. Freeze rollout and keep prior registry active.
2. Fix missing remaps or incorrect lineage edge.
3. Re-run identity migration tests:

```bash theme={null}
cargo test -p meerkat-core --test skill_identity_migrations
```

4. Roll forward only after tests pass and resolver-boundary canonicalization is verified.