Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/tractorjuice/arc-kit/llms.txt

Use this file to discover all available pages before exploring further.

​
Architecture Conformance Assessment

Perform systematic architecture conformance assessment to check whether the decided architecture (ADRs, principles, approved designs) matches the designed/implemented architecture.

​
Command

arckit conformance <project ID or scope>

​
Arguments

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

​
Examples

arckit conformance "001"
arckit conformance "all projects"

​
Purpose

Generate a systematic conformance assessment that checks:
  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?
This fills the gap between /arckit:health (quick metadata scan) and /arckit:analyze (deep governance) by focusing specifically on conformance.

​
The 12 Conformance Checks

​
HIGH Severity Checks

ADR-IMPL: ADR Decision Implementation
  • Are Accepted ADR decisions implemented in HLD/DLD?
  • Evidence: ADR decision text appears in design documents
ADR-CONFL: Cross-ADR Consistency
  • Do Accepted ADRs contradict each other?
  • Evidence: No conflicting technology choices or patterns
PRIN-DESIGN: Principles-to-Design Alignment
  • Does the design violate any architecture principles?
  • Binary pass/fail constraint checking (not RAG scoring)
COND-RESOLVE: Review Condition Resolution
  • Are HLD/DLD review conditions resolved?
  • Evidence: Conditions from HLDR/DLDR are addressed
EXCPT-EXPIRY: Exception Register Expiry
  • Have exceptions expired without renewal?
  • Evidence: No expired exceptions still active

​
MEDIUM Severity Checks

ADR-SUPER: Superseded ADR Enforcement
  • Does design reference superseded ADR patterns?
  • Evidence: No residue from superseded decisions
EXCPT-REMEDI: Exception Remediation Progress
  • Do active exceptions have remediation plans?
  • Evidence: Progress toward remediation
DRIFT-TECH: Technology Stack Drift
  • Do technologies in design match ADR decisions?
  • Evidence: No undocumented technology adoption
DRIFT-PATTERN: Architecture Pattern Drift
  • Are patterns consistently applied across components?
  • Evidence: No deviations without ADR justification
ATD-UNTRACK: Untracked Technical Debt
  • Is there potential debt not explicitly acknowledged?
  • Evidence: No TODO/FIXME markers, ad-hoc adoptions

​
VARIABLE Severity Checks

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

​
LOW Severity Checks

ATD-KNOWN: Known Technical Debt
  • 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

For each FAIL finding:
  • 🔴 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

Generates ARC-{PROJECT_ID}-CONF-v{VERSION}.md with:
  • 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

MANDATORY (error if missing):
  • PRIN (Architecture Principles) - Non-negotiable governance standards
  • ADR (Architecture Decision Records) - At least one accepted ADR
RECOMMENDED (improves assessment accuracy):
  • 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

Optional: Create .arckit/conformance-rules.md with ArchCNL-style 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)

Known Debt Categories:
  • 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
Untracked Debt Signals:
  • 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
  • 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