GitOps delivery

Terminology changes should be delivered with the same care as code changes. SkeinRank supports a Terminology-as-Code direction where JSON or YAML dictionaries can be linted, reviewed, planned, and applied into governed runtime snapshots.

GitOps delivery turns reviewed terminology changes into versioned snapshots that can be activated by bindings.

Delivery lifecycle

1. AuthorEdit JSON/YAML dictionaries in a repository.

2. LintCheck schema, duplicates, stop-list collisions, and policy violations.

3. PlanPreview create/update/delete impact before applying changes.

4. ReviewUse PR review and evidence links to approve terminology changes.

5. ApplyImport approved changes into the governance API.

6. SnapshotPublish immutable runtime state for selected bindings.

CI checks

A lightweight CI pipeline should fail before merge when terminology changes are unsafe.

Example checks:

• dictionary schema is valid;
• canonical values are normalized;
• aliases are not duplicated inside a profile;
• stop-list entries do not conflict with approved aliases;
• required slots are present;
• apply plan has no destructive changes unless explicitly allowed;
• tests or fixtures still pass.

GitLab CI sketch

stages: [lint, plan]

terminology:lint:
  stage: lint
  script:
    - skeinrank dictionary lint dictionaries/

terminology:plan:
  stage: plan
  script:
    - skeinrank dictionary plan dictionaries/ --output plan.json
  artifacts:
    paths:
      - plan.json

The exact CLI commands should follow the installed SkeinRank package version in your repository. Keep examples close to the package docs and avoid inventing project-specific wrapper names in production runbooks.

ArgoCD / Flux shape

GitOps systems should not directly mutate runtime state without validation. A safer shape is:

Dictionary PR merged
      ↓
CI lint + plan passed
      ↓
Deployment job calls governance API apply endpoint
      ↓
Snapshot is published
      ↓
Binding is activated or staged

ArgoCD or Flux can deploy the service and configuration. The governance API should still own validation, audit, and snapshot publication.

Promotion environments

A practical rollout path is:

Environment	Purpose	Binding behavior
Dev	Fast iteration and local demo dictionaries.	Profile-only preview is acceptable.
Staging	Evidence review, apply planning, and dry-run enrichment.	Bindings point to staging indexes or aliases.
Production	Low-noise runtime canonicalization and search/RAG context.	Bindings pin approved immutable snapshots.

Rollback rule

GitOps should make rollback boring:

previous dictionary commit + previous snapshot + previous binding activation = recoverable runtime behavior

That is why snapshots and bindings are separate concepts.