ADR-176: Comprehensive Change Management Framework
Status
ACCEPTED
Date
2026-02-11 (drafted), 2026-02-12 (finalized)
Context
CODITECT is a multi-repository AI development platform with 97 submodules, 3,458 components, and 776 AI agents. The platform operates in a dual capacity: it must comply with change management standards internally AND provide change management capabilities to its customers.
Problem
Prior to this ADR, change management governance was fragmented:
- ADR-175 established an excellent standards-aligned process — but only for component migrations (1 of 12 change types)
- 12 distinct change types exist in CODITECT, each with different risk profiles, approval requirements, and standards implications
- No unified change classification model — all changes treated with the same level of scrutiny
- No defined change authorities — unclear who approves what
- No AI/ML-specific change management — agent behavior, prompt, and model changes have no formal governance despite being high-risk
- No emergency change procedure — critical fixes follow the same process as routine changes
- No formal Configuration Management Plan — cannot demonstrate CM program to auditors
A comprehensive analysis (see internal/analysis/change-management/change-management-standards-analysis-2026-02-11.md) identified 8 critical gaps and 5 medium gaps against NIST SP 800-53, ISO 27001, ITIL v4, and regulatory requirements (SOC 2, FedRAMP, PCI DSS v4.0).
Requirements
- Unified governance for all 12 change types under one framework
- Risk-based classification that routes changes through appropriate approval levels
- Standards compliance with NIST SP 800-53 CM controls, ISO 10007, ISO 27001 A.8.32, ITIL v4 Change Enablement
- AI/ML-specific governance aligned with ISO 42001 and NIST AI RMF 1.0
- Customer applicability — framework must be offered as a capability to CODITECT customers
- Audit evidence generation for SOC 2, FedRAMP, and ISO 27001 certifications
- Backward compatibility — must not break existing Git PR workflow, ADR process, or hook system
Decision
We adopt a 5-tier change classification model built on ITIL v4 Change Enablement, enriched with NIST SP 800-53 CM controls (CM-1 through CM-14) and ISO 10007 configuration management activities. This framework governs all changes to the CODITECT platform and is offered as a configurable capability to customers.
Change Classification Model
| Tier | Classification | Risk | Approval | SLA | Examples |
|---|
| 1 | Standard | Pre-assessed, low risk | Auto-approved via hooks | Immediate | Doc updates, metadata, style changes, session logs |
| 2 | Normal | Medium, needs assessment | PR review + designated reviewer | 1-3 business days | Feature PRs, new agents/skills, dependency updates |
| 3 | Major | High, cross-system impact | ADR + human approval | 3-5 business days | Database migrations, breaking API changes, framework architecture changes |
| 4 | Emergency | Critical, time-sensitive | Fast-track: single senior approver + mandatory post-review | 4 hours | Security patches, production outages, data breach response |
| 5 | AI/ML | Variable, requires AI-specific assessment | AI Change Assessment + designated reviewer | 2-5 business days | Model selection changes, prompt engineering, agent behavior changes, training data changes |
Change Types and Classification
| # | Change Type | Default Tier | May Escalate To | Change Authority |
|---|
| 1 | Code changes (PRs, commits) | 2 (Normal) | 3 (Major) if breaking | Repository maintainer |
| 2 | Component migration (cross-repo) | 3 (Major) | — | Senior architect (ADR-175) |
| 3 | Configuration changes (feature flags, env vars) | 2 (Normal) | 3 (Major) if production | DevOps lead |
| 4 | Infrastructure changes (IaC, K8s, Terraform) | 2 (Normal) | 3 (Major) if production | DevOps lead |
| 5 | Database/schema changes (migrations) | 3 (Major) | — | Database architect + senior architect |
| 6 | AI/ML model changes (prompts, agents, model selection) | 5 (AI/ML) | 3 (Major) if customer-facing | AI Change Board |
| 7 | Framework component changes (skills, hooks, commands) | 2 (Normal) | 3 (Major) if governance | Senior architect |
| 8 | Customer-facing API changes | 3 (Major) | — | Senior architect + product owner |
| 9 | Documentation changes | 1 (Standard) | 2 (Normal) if policy docs | Repository maintainer |
| 10 | Security changes (patches, vuln remediation) | 4 (Emergency) | — | Security specialist |
| 11 | Organizational process changes (workflows, policies) | 3 (Major) | — | Senior architect + stakeholder |
| 12 | Registry/metadata changes | 1 (Standard) | — | Auto-hook (component-indexer) |
Change Authorities
| Role | Scope | NIST Mapping |
|---|
| Auto-hook system | Tier 1 (Standard) changes | CM-3(5): Automated Change Implementation |
| Repository maintainer | Tier 2 (Normal) within their repo | CM-5: Access Restrictions for Change |
| DevOps lead | Infrastructure and configuration changes | CM-6: Configuration Settings |
| Senior architect | Tier 3 (Major) changes, ADR approvals | CM-3: Configuration Change Control |
| Security specialist | Tier 4 (Emergency) security changes | CM-3(4): Automated Security Response |
| AI Change Board | Tier 5 (AI/ML) changes | ISO 42001: AI governance |
| Platform owner | Escalation authority for all tiers | CM-1: Policy and Procedures |
Change Process by Tier
Tier 1: Standard Changes
Request → Auto-validate (hooks) → Implement → Auto-record (session log + audit trail)
- Trigger: Commit/push of qualifying file types
- Validation: Hooks enforce task ID (task-id-validator), naming conventions (naming-enforcer), component indexing (component-indexer-hook)
- Approval: Pre-approved by change model definition; no human gate required
- Record: Session log entry + git commit + hook execution log
- NIST controls: CM-3(5), CM-8
Tier 2: Normal Changes
Request → Impact assessment → PR review → Approve → Implement → Verify → Record
- Trigger: Pull request creation
- Assessment: MCP impact analysis tools (blast radius, call graph, decision awareness)
- Review: At least one designated reviewer per repository CODEOWNERS
- Approval: Reviewer approval on PR
- Verification: CI/CD checks pass (tests, lint, security scan)
- Record: PR description, review comments, CI results, session log
- NIST controls: CM-3, CM-4, CM-5
Tier 3: Major Changes
Request → ADR draft → Impact analysis → Stakeholder review → Approval gate → Implementation plan → Execute → Verify → Post-implementation review → Record
- Trigger: Identified by change type table or escalation from Tier 2
- ADR: Architecture Decision Record documenting context, decision, alternatives, consequences
- Impact analysis: Full blast radius via MCP tools + cross-repository dependency analysis
- Review: Stakeholders identified by impact analysis
- Approval: ADR acceptance + explicit human approval
- PIR: Post-Implementation Review within 5 business days of completion
- Record: ADR, impact analysis, approval evidence, PIR findings, session log
- NIST controls: CM-3, CM-3(2), CM-3(7), CM-4, CM-9
Tier 4: Emergency Changes
Declare emergency → Single-approver fast-track → Implement → Verify → Mandatory post-review (within 48h)
- Trigger: Production outage, security vulnerability, data breach, critical bug in production
- Declaration: Any team member can declare; must log severity and business impact
- Approval: Single senior authority (senior architect OR security specialist); no CAB required
- Implementation: Expedited; bypass normal PR review process
- Post-review: Mandatory within 48 hours; produces PIR document with:
- Root cause analysis
- Was the emergency classification appropriate?
- What changes would have prevented the emergency?
- Follow-up actions
- Record: Emergency declaration, approval, implementation evidence, PIR
- NIST controls: CM-3, CM-3(4)
Tier 5: AI/ML Changes
Request → AI Change Assessment → Risk scoring → Designated review → Approval → Implement → Monitor → Evaluate → Record
- Trigger: Any modification to AI agent behavior, prompt templates, model selection, training data, or inference parameters
- AI Change Assessment (new artifact) evaluates:
- Behavioral impact: How does this change alter agent outputs?
- Safety impact: Could this change produce harmful, biased, or incorrect outputs?
- Performance impact: Latency, cost, quality metrics delta
- Compliance impact: Regulatory implications (EU AI Act, NIST AI RMF)
- Reversibility: Can the change be rolled back cleanly?
- Risk scoring: Low / Medium / High / Critical based on assessment
- Monitoring: Post-deployment monitoring period (minimum 7 days for customer-facing changes)
- Evaluation: Compare actual behavior against predicted behavior from assessment
- Record: AI Change Assessment, approval, monitoring results, evaluation findings
- Standards: ISO 42001, NIST AI RMF 1.0, NIST AI 600-1
Configuration Management Activities (ISO 10007 Alignment)
| Activity | Implementation | Artifacts |
|---|
| CM Planning | This ADR + CLAUDE.md directives + per-repo CODEOWNERS | ADR-176, CLAUDE.md, CODEOWNERS |
| Configuration Identification | platform.db, component-counts.json, framework-registry.json, component-activation-status.json | Component inventory, baseline configurations |
| Configuration Change Control | 5-tier classification model (above) | Change requests, approvals, implementation evidence |
| Configuration Status Accounting | Session logs, trajectory dashboard, /cxq --stats, git history | Status reports, audit trails, DORA metrics |
| Configuration Verification & Audit | Hooks (task-id-validator, component-indexer, naming-enforcer), MoE judges, CI/CD checks | Verification reports, audit findings |
NIST SP 800-53 CM Control Implementation
| Control | Title | Implementation | Status |
|---|
| CM-1 | Policy and Procedures | This ADR + CLAUDE.md | Now addressed |
| CM-2 | Baseline Configuration | platform.db, registries, component-counts.json | Existing |
| CM-3 | Configuration Change Control | 5-tier classification model | Now addressed |
| CM-3(1) | Automated Documentation | Session logs, auto-indexing hooks | Existing |
| CM-3(2) | Testing and Validation | CI/CD pipeline, Tier 3 PIR | Now addressed |
| CM-3(4) | Automated Security Response | Tier 4 Emergency process | Now addressed |
| CM-3(5) | Automated Change Implementation | Tier 1 Standard auto-approval | Existing |
| CM-3(7) | Review System Changes | Tier 3 Major ADR review process | Now addressed |
| CM-4 | Impact Analyses | MCP impact analysis + call graph tools | Existing |
| CM-5 | Access Restrictions for Change | Git branch protection, CODEOWNERS, role-based authorities | Existing + enhanced |
| CM-6 | Configuration Settings | Feature flags via Tier 2 process (future: centralized config service) | Partially addressed |
| CM-7 | Least Functionality | Scope: progressive component disclosure (ADR-162) | Existing |
| CM-8 | System Component Inventory | platform.db, component-indexer.py | Existing |
| CM-9 | Configuration Management Plan | This ADR serves as the CM Plan | Now addressed |
| CM-14 | Signed Components | Planned: code-signing-specialist agent | Planned |
Customer-Facing Capabilities
This framework is designed to be offered to CODITECT customers as configurable capabilities:
| Capability | Description | Customer Value |
|---|
| Change Classification Engine | Configurable 5-tier model with custom rules per change type | Customers define their own change policies |
| Change Workflow Automation | Approval routing based on classification tier | Reduces manual routing; enforces compliance |
| Impact Analysis Service | MCP-powered blast radius and dependency analysis | Risk-informed change decisions |
| Compliance Evidence Collection | Auto-generated audit trails per change | SOC 2, ISO 27001, FedRAMP evidence packages |
| Change Calendar | Visibility into planned changes with conflict detection | Coordination across teams; blackout period enforcement |
| Change Analytics Dashboard | DORA metrics: change failure rate, lead time, deployment frequency, MTTR | Data-driven process improvement |
| AI Change Assessment | Structured evaluation for AI/ML changes | ISO 42001 compliance; responsible AI governance |
| Post-Implementation Review | Templated PIR workflow with action item tracking | Continuous improvement from change outcomes |
Metrics and Measurement
| Metric | Source | Target | Standard |
|---|
| Change failure rate | PIR outcomes / total changes | < 15% | DORA |
| Change lead time | Request to implementation | Tier 1: < 1h, Tier 2: < 3d, Tier 3: < 5d | DORA |
| Emergency change ratio | Tier 4 / total changes | < 5% | ITIL v4 |
| PIR completion rate | PIRs completed / PIRs required | 100% for Tier 3+4 | Internal |
| Unauthorized change rate | Changes bypassing classification | 0% | SOC 2 CC8.1 |
| AI change monitoring completion | Monitoring periods completed / required | 100% for Tier 5 | ISO 42001 |
Alternatives Considered
Alternative 1: Extend ADR-175 to Cover All Change Types
- Pros: Single ADR, builds on proven model
- Cons: ADR-175 is specifically about component migration with a 12-step workflow; overloading it with 12 change types would make it unwieldy and dilute its focused purpose
- Rejected: Separate ADR provides cleaner governance; ADR-175 remains the authoritative source for migration-specific processes
Alternative 2: Adopt COBIT 2019 as Primary Framework
- Pros: Comprehensive IT governance framework; BAI06/BAI07 directly address change management
- Cons: COBIT is heavyweight, enterprise-focused, and less prescriptive on implementation; ITIL v4 is more operationally practical for a development platform
- Rejected: ITIL v4 + NIST provides better operational guidance while COBIT principles are still incorporated (Section 3.4 of analysis document)
Alternative 3: Lightweight Change Management (Git-Only)
- Pros: Simple; relies on existing Git PR workflow for everything
- Cons: No change classification, no AI/ML governance, insufficient for SOC 2 / FedRAMP / ISO 27001 compliance, no emergency change procedure
- Rejected: Fails multiple standards requirements; insufficient for a platform that serves regulated customers
Alternative 4: Per-Repository Change Management
- Pros: Each repo defines its own change process; flexibility
- Cons: Inconsistent compliance posture; no unified reporting; changes spanning repos have no single authority; customers can't rely on consistent governance
- Rejected: Unified framework essential for platform-level compliance and customer confidence
Consequences
Positive
- Unified governance — All 12 change types covered under one framework with appropriate risk-based controls
- Standards compliant — Addresses 12 of 14 NIST 800-53 CM controls (CM-10 and CM-11 are N/A for SaaS)
- Audit-ready — SOC 2 CC6.1/CC8.1, ISO 27001 A.8.32, FedRAMP CM overlay requirements met
- AI-specific governance — First formal process for AI/ML changes aligned with ISO 42001 and NIST AI RMF
- Emergency preparedness — Clear fast-track process for critical changes with mandatory post-review
- Customer value — Change management capabilities become a differentiating product feature
- Backward compatible — Existing Git PR workflow, ADR process, and hook system continue unchanged; this framework categorizes and governs them rather than replacing them
Negative
- Process overhead — Tier 3 and Tier 5 changes require additional artifacts (ADRs, AI Change Assessments, PIRs)
- Role definition needed — AI Change Board and change authorities need to be staffed/designated
- Tooling gaps — Change Calendar, Analytics Dashboard, and centralized config management are future work
- Cultural shift — Contributors accustomed to informal change processes must adapt to classification
Risks
| Risk | Mitigation |
|---|
| Over-classification (too many changes routed to Tier 3+) | Regular review of classification rules; escalation data analysis |
| Under-classification (high-risk changes routed as Standard) | Hook-based guardrails; impact analysis triggers automatic escalation |
| Emergency process abuse | PIR must assess classification appropriateness; trending tracked as metric |
| AI Change Assessment becoming rubber-stamp | Structured template with mandatory fields; periodic audit of assessments |
Implementation
| Component | Description | Status |
|---|
| ADR-176 (this document) | Change Management Framework and CM Plan | Complete |
| Analysis document | Standards research and gap analysis | Complete |
| Change classification rules | Hook or script to classify changes by type/tier | Planned |
Phase 2: Process Automation (Next)
| Component | Description | Status |
|---|
| Change classification hook | Auto-classify changes on commit/PR | Planned |
| AI Change Assessment template | Structured template for Tier 5 changes | Planned |
| Emergency change procedure | Runbook for Tier 4 fast-track process | Planned |
| PIR template | Post-Implementation Review template | Planned |
agents/change-management.md enhancement | Upgrade from stub to full standards-aligned agent | Planned |
Phase 3: Customer Capabilities (Future)
| Component | Description | Status |
|---|
| Change Workflow Engine | Configurable approval workflows | Planned |
| Change Calendar | Planned change visibility | Planned |
| Change Analytics Dashboard | DORA metrics and reporting | Planned |
| Compliance Evidence Exporter | Auto-generated audit packages | Planned |
ADRs
- ADR-175 — Component Migration Process (governs Tier 3 component relocation changes)
- ADR-049 — Component Creation Lifecycle (governs new component Tier 2 changes)
- ADR-054 — Track Nomenclature (task tracking for all change types)
- ADR-116 — Track-Based Plan Architecture (planning framework for major changes)
- ADR-118 — Four-Tier Database Architecture (configuration identification: platform.db)
- ADR-161 — Component QA Framework (verification activity)
- ADR-162 — Progressive Component Disclosure (CM-7 Least Functionality)
- ADR-173 — Structured Inter-Session Message Schema (change coordination)
Standards
- NIST SP 800-128 — Guide for Security-Focused Configuration Management
- NIST SP 800-53 Rev 5 — Security and Privacy Controls, CM Family (CM-1 through CM-14)
- NIST CSF 2.0 — Cybersecurity Framework (GOVERN function)
- NIST SP 800-37 Rev 2 — Risk Management Framework
- NIST AI RMF 1.0 — AI Risk Management Framework
- NIST AI 600-1 — Generative AI Profile
- ISO 10007:2017 — Quality Management: Configuration Management Guidelines
- ISO/IEC 20000-1:2018 — IT Service Management
- ISO 27001:2022 — Information Security Management Systems (Annex A.8.32)
- ISO/IEC 27002:2022 — Information Security Controls (8.32)
- ISO 42001:2023 — AI Management System Standard
- ISO 9001:2015 — Quality Management Systems (Clause 6.3)
- ITIL v4 — Change Enablement, Release Management, Service Configuration Management
Regulatory
- SOC 2 Type II — CC6.1 (Logical and Physical Access), CC8.1 (Change Management)
- FedRAMP — NIST 800-53 CM controls overlay
- PCI DSS v4.0 — Requirement 6 (Develop and Maintain Secure Systems)
- HIPAA — 164.312(e) Technical Safeguards
- GDPR — Article 25 Data Protection by Design
- EU AI Act — Risk-based AI governance requirements
Analysis
- Analysis Document:
change-management-standards-analysis-2026-02-11.md
- Full Path:
internal/analysis/change-management/change-management-standards-analysis-2026-02-11.md
Author: Claude (Opus 4.6)
Reviewed: 2026-02-12
Task: [H.0]
Project: PILOT