change-management

Change Control

Every change to a critical asset gets a record. No exceptions.

Change record format

Storage

All change records: .compliance/changes/CHG-YYYY-NNN.json — one file per change.

Change record format

Required fields

{
  "change_id": "CHG-2026-001",
  "status": "proposed | approved | implementing | completed | rolled-back | rejected",
  "requested_at": "ISO 8601",
  "requested_by": "agent | user | system",
  "summary": "One-line description of what changes",
  "affected_assets": ["names from profile.critical_assets if applicable"],
  "impact": "critical | high | medium | low",
  "change_type": "code | config | infrastructure | access | data-schema | dependency",
  "risk_assessment": "What could go wrong",
  "rollback_plan": "How to reverse this change",
  "approval": {
    "required": true,
    "approved_by": "name or null",
    "approved_at": "ISO 8601 or null"
  }
}

Added after implementation

Field	When	Content
implemented_at	After execution	ISO 8601
verified_by	After testing	Who confirmed it works
closed_at	After verification	ISO 8601
actual_impact	If different from expected	What actually happened

Impact classification

Impact is determined by which critical assets are affected:

Impact	Criteria	Approval
Critical	Touches critical asset with CIA 5 in any dimension	Human approval required before execution
High	Touches any critical asset, or changes access controls	Human approval required
Medium	Touches systems connected to critical assets	Agent may proceed with notification
Low	No critical asset impact	Agent may proceed, log only

Change lifecycle

1. Propose

Before making a change to a critical asset:

• Create the change record
• Identify affected critical assets (check profile.critical_assets)
• Classify impact
• Define rollback plan — every change must be reversible

2. Approve

• Critical/High: present change record to user, wait for explicit approval
• Medium: notify user, proceed unless they object
• Low: proceed, record for audit trail

3. Implement

• Log the change via audit-logging (event_class: "tool_call", linked to change_id)
• Execute the change
• Record implemented_at

4. Verify

• Confirm the change works as expected
• Check that no unintended side effects occurred
• Record verified_by

5. Close or roll back

• If successful: close the change record
• If problems: execute rollback plan, log the rollback, document what went wrong

What counts as a change to a critical asset

Change type	Examples	Impact signal
Code	New feature touching critical asset data, DB migration, API endpoint changes	Schema changes = high. New queries = medium
Config	Firewall rules, conditional access policies, MFA settings, backup config	Security config = critical. Feature flags = low
Infrastructure	Server migration, cloud region change, scaling changes, DNS	Hosting change = check data residency. Scale = medium
Access	New user/service account, permission changes, admin role grants	Admin access to critical asset = critical
Data schema	New columns, table changes, data model modifications	On critical asset DB = high. On non-critical = medium
Dependency	New library, SDK update, vendor API version change	Check vendor-risk skill for vendor assessment

External ticketing integration

If the organisation uses a ticketing system, create change tickets there instead of (or in addition to) local JSON files. The local .compliance/changes/ path is the fallback when no external system is available.

Platform	How to integrate	Official skill
Jira	Use Jira MCP or REST API to create issues in the compliance project. Map: change_id → Jira key, impact → priority, status → workflow state, affected_assets → labels.	Jira MCP
Linear	Use Linear MCP to create issues. Map: impact → priority (Urgent/High/Medium/Low), change_type → label.	Linear MCP
ServiceNow	Use ServiceNow Change Management API. Map: impact → risk level, CHG record fields align 1:1 with ServiceNow change request schema.	ServiceNow REST API
GitHub Issues	Use gh issue create with labels for impact level and affected assets. Lightweight option for dev teams.	Built-in GitHub CLI

When creating external tickets, always also write the local .compliance/changes/CHG-*.json record — it feeds into the compliance-hub for retention and audit trail.

Agent instructions

1. Before modifying any file, config, or system: check if it's a critical asset or connected to one (read profile.critical_assets).
2. If it is: create a change record before proceeding. For critical/high impact, present to user and wait for approval.
3. If a ticketing system (Jira, Linear, ServiceNow) is available in the environment, create the ticket there AND write the local JSON record. If no external system: local record only.
4. Always define a rollback plan. For code changes: the previous commit. For config: the previous value. For infra: document how to revert.
5. Log every change via audit-logging, linking to the change_id.
6. After implementation, verify the change works and close the record.
7. If something goes wrong: execute rollback, document in the change record, consider whether to start an incident record via incident-management.
8. Cross-reference with vendor-risk: if the change introduces a new dependency, run vendor assessment first.