​

Architecture Conformance Assessment

​

Command

arckit conformance <project ID or scope>

​

Arguments

• scope (required): Project ID or “all projects”

​

Examples

arckit conformance "001"
arckit conformance "all projects"

​

Purpose

1. Decided-vs-Designed Conformance - Do designs match ADR decisions?
2. Architecture Drift - Has the architecture drifted from approved patterns?
3. Architecture Technical Debt (ATD) - What technical debt exists?
4. Principles Alignment - Do designs conform to architecture principles?
5. Review Condition Resolution - Are review findings addressed?
6. Exception Expiry - Are exceptions still valid?

​

The 12 Conformance Checks

​

HIGH Severity Checks

• Are Accepted ADR decisions implemented in HLD/DLD?
• Evidence: ADR decision text appears in design documents

• Do Accepted ADRs contradict each other?
• Evidence: No conflicting technology choices or patterns

• Does the design violate any architecture principles?
• Binary pass/fail constraint checking (not RAG scoring)

• Are HLD/DLD review conditions resolved?
• Evidence: Conditions from HLDR/DLDR are addressed

• Have exceptions expired without renewal?
• Evidence: No expired exceptions still active

​

MEDIUM Severity Checks

• Does design reference superseded ADR patterns?
• Evidence: No residue from superseded decisions

• Do active exceptions have remediation plans?
• Evidence: Progress toward remediation

• Do technologies in design match ADR decisions?
• Evidence: No undocumented technology adoption

• Are patterns consistently applied across components?
• Evidence: No deviations without ADR justification

• Is there potential debt not explicitly acknowledged?
• Evidence: No TODO/FIXME markers, ad-hoc adoptions

​

VARIABLE Severity Checks

• Do designs satisfy custom rules in .arckit/conformance-rules.md?
• Severity: MUST/MUST NOT → HIGH, SHOULD/SHOULD NOT → MEDIUM

​

LOW Severity Checks

• What acknowledged debt exists?
• Evidence: ADR negative consequences, accepted risks, deferred fixes
• Categories: DEFERRED-FIX, ACCEPTED-RISK, WORKAROUND, DEPRECATED-PATTERN, SCOPE-REDUCTION, EXCEPTION

​

Deviation Tier Assignment

• 🔴 RED: FAIL + HIGH severity — escalate immediately, blocks next gate
• 🟡 YELLOW: FAIL + MEDIUM severity — negotiate remediation within 30 days
• 🟢 GREEN: FAIL + LOW severity — acceptable deviation, document and monitor

​

Overall Recommendation

• CONFORMANT: All checks PASS (or NOT ASSESSED), no FAIL findings
• CONFORMANT WITH CONDITIONS: No RED findings, YELLOW/GREEN findings have remediation plans, conformance ≥80%
• NON-CONFORMANT: Any RED finding, or conformance <80%

​

Output

• Executive summary with conformance score and overall recommendation
• Detailed results for all 12 checks with evidence
• RED/YELLOW/GREEN finding categorization
• Remediation guidance for each tier
• Known and untracked technical debt register
• Custom rule violations (if .arckit/conformance-rules.md exists)

​

Prerequisites

• PRIN (Architecture Principles) - Non-negotiable governance standards
• ADR (Architecture Decision Records) - At least one accepted ADR

• REQ (Requirements) - For cross-referencing
• Vendor HLD/DLD files
• HLDR/DLDR (Design Reviews) - Review findings
• PRIN-COMP (Principles Compliance) - Prior assessments
• TRAC (Traceability Matrix)
• RISK (Risk Register) - Exception context
• DEVOPS (DevOps Strategy) - Technology stack drift check

​

Custom Constraint Rules

# Custom Conformance Rules

## Security Rules
- All API services MUST use OAuth 2.0 for authentication
- Database connections MUST NOT use plaintext credentials
- All OFFICIAL-SENSITIVE data MUST be encrypted at rest

## Architecture Rules  
- All microservices SHOULD expose health check endpoints
- External integrations MUST use the approved API gateway

​

Architecture Technical Debt (ATD)

• DEFERRED-FIX: Known deficiency deferred to later phase
• ACCEPTED-RISK: Risk consciously accepted as trade-off
• WORKAROUND: Temporary solution deviating from intended pattern
• DEPRECATED-PATTERN: Superseded pattern not yet migrated
• SCOPE-REDUCTION: Quality/feature removed for timeline/budget
• EXCEPTION: Approved principle exception with expiry

• Technologies in design but not in ADR decisions
• TODO/FIXME/HACK/WORKAROUND markers
• Inconsistencies between HLD and DLD
• Design elements contradicting principles without exception
• Review findings not addressed in subsequent versions

​

Operating Constraints

• Non-Destructive: Do NOT modify existing artifacts
• Evidence-Based: Every finding must cite file:section:line references
• Honest Assessment: FAIL is better than false PASS
• Architecture Principles Authority: Principles are non-negotiable
• ADR Decision Authority: Accepted ADRs are binding

​

Related Commands

• arckit principles-compliance - Detailed RAG scoring of principle compliance
• arckit analyze - Comprehensive governance gap analysis
• arckit traceability - Requirements traceability matrix
• arckit health - Quick metadata health check

​

Resources

• Architecture Conformance Checking (ACC) research
• ArchUnit (Java architecture testing framework)
• C4 Model - Architecture Decision Records