Governance & Change Control
Version Lifecycle & Change Control Flow
How Claire handles component updates in a regulated environment — from initial development through approval, publication, and controlled downstream adoption. No auto-sync. Full traceability.
Phase A
Develop, Approve & Publish
A developer upgrades a component (agent, tool, skill, or flow). The change goes through versioning, review, and approval before being published.
1
Component is live in production. All downstream realms and tenants that have cloned this component are running V1.0. Audit trail is clean.
2
Developer initiates an upgrade. Claire automatically creates a
snapshot of V1.0 (the safety net) and opens a new draft version
V1.1-draft.
- Snapshot captures: definition, config, linked tools/skills, prompts — everything
- V1.0 remains the active published version — users are unaffected
- Developer works on V1.1-draft in isolation
3
Developer modifies the component — updates prompts, changes tool schemas, adjusts flow logic. All changes are tracked with deep-diff audit logging.
- Every save creates an incremental snapshot (full version history)
- Can test in isolation without affecting V1.0 users
- Can rollback to any previous snapshot at any time
- V1.0 continues serving production traffic
4
Developer submits V1.1 for review. The approval workflow triggers:
- Diff view: Reviewer sees exactly what changed between V1.0 and V1.1
- Impact preview: Shows which downstream realms/tenants have V1.0 cloned
- Test results: Attached validation evidence (if applicable)
- Approval chain: Configurable per realm — single approver or multi-level
5
Reviewer approves. V1.1 is published and becomes the new active version
in the realm where the change happened.
- V1.1 is now visible in the realm's Store
- Downstream realms/tenants are NOT auto-updated
- They see an "Update Available" notification
- V1.0 is preserved in version history — rollback always available
Downstream Adoption
Phase B
Controlled Downstream Update
A downstream realm owner (Use Case or Tenant admin) sees that a new version is available. They decide if and when to adopt it — with full impact analysis before any change.
6
The downstream realm admin sees a notification:
"FDA Audit Agent V1.1 is available. You are running V1.0."
- No automatic update — admin decides when to review
- Current V1.0 continues working unchanged
- Badge shows on the component in the Store and entity detail page
7
Admin clicks "Review Update". Claire runs a
full impact analysis:
- What changed: Field-by-field diff between V1.0 and V1.1 (prompts, schemas, config)
- What depends on this: Which flows use this agent? Which skills are attached? Which tools does it call?
- Downstream impact: If this is a Use Case realm — which tenants have cloned this component?
- Risk assessment: Are there breaking changes? (schema changes, removed tools, modified output format)
- Re-validation needs: What testing is recommended before adoption?
8
Admin submits the update for realm-level approval (same workflow as Phase A):
- Impact analysis report attached to the approval request
- Reviewer sees: what's changing, what it affects, what needs re-testing
- Can approve, reject, or request modifications
- If rejected — realm stays on V1.0, no changes made
9
Approved. Claire executes the update:
- Auto-snapshot: Creates backup of current V1.0 state (safety net)
- Apply update: Merges V1.1 changes into the realm's copy
- Preserve customizations: Tenant-specific overrides are maintained (merge, not overwrite)
- Audit log: Records who approved, when, what changed, and the impact analysis that was reviewed
10
Realm is now running V1.1. Full traceability:
- Version history shows: V1.0 → V1.1 with approval chain
- Rollback to V1.0 available at any time (one-click restore)
- If this realm has tenants — they now see "Update Available" (cycle repeats)
- Lineage: Platform Store V1.1 → iQuality V1.1 → Vertex Tenant (pending)
Dependency Cascade
Phase C
Dependency Chain — Automatic Phase B Triggers
Components don't exist in isolation. A Skill belongs to an Agent, an Agent belongs to a Flow. When a Skill is updated, Claire automatically traces the dependency chain and triggers Phase B (impact analysis + approval) at every level.
Dependency Cascade: Skill → Agent → Flow → Realm
Phase A Complete
🎯
SOP Compliance Check
Skill
V1.1 Published
Phase B auto-triggered
⚠ ↓
Impact Analysis Required
🤖
Audit Trail Reviewer
Agent — uses this skill
Skill V1.1 Available
⚠ Impact
Skill prompt template changed.
New output field sop_reference added.
Agent definition may need update.
Agent owner approves → publishes Agent V1.1
⚠ ↓
Impact Analysis Required
⚡
Audit Trail Review
Flow — uses this agent
Agent V1.1 Available
⚠ Impact
Agent now returns new field.
Transform node after agent may need
update to handle sop_reference.
Flow owner reviews → updates transform → publishes Flow V1.1
⚠ ↓
📦
iQuality
Use Case
Update Avail
⚠→
🏢
Vertex
Tenant
Update Avail
⚠→
🏢
Amgen
Tenant
Update Avail
Every ⚠ gate is an independent Phase B: impact analysis → approval → explicit pull. The chain only advances when each level approves.
Example: Skill Change Cascading Through the System
1
Developer updates "SOP Compliance Check" skill (V1.0 → V1.1)
Changed: prompt template refined, added new output field sop_reference
Phase A: Reviewed, approved, published as Skill V1.1 ✓
2
Agent "Audit Trail Reviewer" uses this skill
⚠ Phase B auto-triggered: "Skill dependency updated: V1.0 → V1.1"
Impact: skill prompt changed, new output field — agent definition compatible, no breaking changes
Agent owner reviews → approves → Agent V1.1 published ✓
3
Flow "Audit Trail Review" uses this agent
⚠ Phase B auto-triggered: "Agent dependency updated: V1.0 → V1.1"
Impact: agent now returns sop_reference field — Transform node after AR-04 needs update to include in report
Flow owner updates Transform node → submits for review
Approved → Flow V1.1 published ✓
4
Tenant "Vertex" has cloned this flow
⚠ Phase B: "Flow update available: V1.0 → V1.1"
Vertex admin reviews impact analysis → sees new SOP reference in reports → approves
Pulls update → auto-backup of V1.0 → V1.1 active ✓
5
Tenant "Amgen" has cloned this flow
⚠ Phase B: "Flow update available: V1.0 → V1.1"
Amgen admin reviews but decides to stay on V1.0 for now — quarterly review scheduled
No change. V1.0 continues running. Update remains available.
Key Principle
The cascade is automatic for notification but manual for adoption. Every level in the chain independently decides if and when to adopt. Amgen staying on V1.0 while Vertex upgrades to V1.1 is a perfectly valid state. No one is forced to update.
Reference
Version State Machine
Component Version Lifecycle
→
In Review
Submitted for
approval
→
Published
Active in
this realm
→
Available
Downstream
can adopt
↩
Rollback to any previous version at any time — auto-backup before restore
Cascade: How Updates Flow Down (With Gates)
🏪
Platform
V1.1
Published by CG
📦
Use Case
V1.1 Avail
Admin decides
🏢
Tenant
V1.1 Avail
Tenant decides
Every ⚠ gate requires: impact analysis → approval workflow → explicit pull. Never automatic.
Traceability
What Gets Recorded
| Event | Who | What's Captured | Where |
|---|
| Version Created | Developer | Full snapshot (definition, config, linked entities), deep diff from previous version | Version History |
| Submitted for Review | Developer | Submission timestamp, reviewer assignment, attached evidence | Audit Log |
| Approved / Rejected | Reviewer | Decision, justification, conditions, timestamp | Audit Log + Version |
| Published | System | Version label, publish timestamp, previous active version | Version History |
| Impact Analysis Run | Downstream Admin | Affected realms, affected flows, risk assessment, diff preview | Audit Log |
| Update Pulled | Downstream Admin | Source version, target version, auto-backup snapshot ID, approval chain | Version History + Audit |
| Rollback Executed | Admin | From version, to version, reason, auto-backup of current state | Version History + Audit |
| Clone / Import | Admin | Source realm, source entity ID, source version, target realm | Lineage + Audit |