Assess architecture conformance — ADR decision implementation, cross-decision consistency, design-principles alignment, architecture drift, technical debt, and custom constraint rules
$ARGUMENTS
Generate a systematic Architecture Conformance Assessment that checks whether the decided architecture (ADRs, principles, approved designs) matches the designed/implemented architecture (HLD, DLD, DevOps artifacts). This command fills the gap between $arckit-health (quick metadata scan) and $arckit-analyze (deep governance across all dimensions) by focusing specifically on decided-vs-designed conformance, architecture drift, and architecture technical debt (ATD).
This is a point-in-time assessment — run at key project gates or after major design changes to track conformance over time.
a. PRIN (Architecture Principles, in projects/000-global/) (MUST exist):
b. ADR (Architecture Decision Records, in projects/{project-dir}/decisions/) (MUST exist):
More artifacts = better conformance assessment:
projects/{project-dir}/ — Requirements to cross-referenceprojects/{project-dir}/vendors/{vendor}/hld-v*.md — High-Level Designprojects/{project-dir}/vendors/{vendor}/dld-v*.md — Detailed Low-Level Designprojects/{project-dir}/reviews/ — Design review findingsprojects/{project-dir}/reviews/ — Detailed review findingsprojects/{project-dir}/ — Prior compliance assessmentprojects/{project-dir}/ — Requirements traceabilityprojects/{project-dir}/ — Risk context for exceptionsprojects/{project-dir}/ — CI/CD and deployment patternsc. .arckit/conformance-rules.md in the project root (if exists):
Note: Assessment is possible with minimal artifacts (principles + ADRs), but accuracy improves significantly with HLD/DLD and review documents.
Non-Destructive Assessment: Do NOT modify existing artifacts. Generate a new conformance assessment document only.
Evidence-Based Assessment: Every finding must cite specific file:section:line references. Avoid vague statements like "design addresses this" — be specific.
Honest Assessment: Do not inflate conformance scores. FAIL is better than false PASS. Untracked technical debt should be surfaced, not hidden.
Architecture Principles Authority: The architecture principles (ARC-000-PRIN-*.md in projects/000-global/) are non-negotiable. Any design that contradicts principles is automatically a FAIL.
ADR Decision Authority: Accepted ADR decisions are binding. Designs that ignore or contradict accepted decisions are non-conformant.
Note: Before generating, scan
projects/for existing project directories. For each project, list allARC-*.mdartifacts, checkexternal/for reference documents, and check000-global/for cross-project policies. If no external docs exist but they would improve output, ask the user.
Read the template (with user override support):
.arckit/templates/conformance-assessment-template.md exists in the project root.arckit/templates/conformance-assessment-template.md (default)Tip: Users can customize templates with
$arckit-customize conformance
Check Architecture Principles:
ARC-000-PRIN-*.md in projects/000-global/Check ADRs:
ARC-*-ADR-*.md files in projects/{project-dir}/decisions/external/ files) — extract audit findings, compliance gaps, certification evidence, remediation plansprojects/000-global/external/ — extract enterprise compliance frameworks, cross-project conformance benchmarks.arckit/references/citation-instructions.md. Place inline citation markers (e.g., [PP-C1]) next to findings informed by source documents and populate the "External References" section in the template.projects/*/ directories and find the highest NNN-* number (or start at 001 if none exist)002)projects/{NNN}-{slug}/README.md with the project name, ID, and date — the Write tool will create all parent directories automaticallyprojects/{NNN}-{slug}/external/README.md with a note to place external reference documents herePROJECT_ID = the 3-digit number, PROJECT_PATH = the new directory pathRead the following artifacts. Do NOT read entire files — extract relevant sections for each conformance check.
Architecture Principles (projects/000-global/ARC-000-PRIN-*.md):
ADRs (projects/{project-dir}/decisions/ARC-*-ADR-*.md):
Design Documents (if exist):
projects/{project-dir}/vendors/{vendor}/hld-v*.md — Architecture overview, technology stack, patterns, componentsprojects/{project-dir}/vendors/{vendor}/dld-v*.md — Detailed implementation, API specs, infrastructureReview Documents (if exist):
ARC-*-HLDR-*.md in reviews/ — HLD review conditions, findingsARC-*-DLDR-*.md in reviews/ — DLD review conditions, findingsOther Artifacts (if exist):
ARC-*-REQ-*.md — Requirements for traceabilityARC-*-PRIN-COMP-*.md — Prior principles compliance (for trend comparison)ARC-*-TRAC-*.md — Traceability matrixARC-*-RISK-*.md — Risk register (for exception context)ARC-*-DEVOPS-*.md — DevOps strategy (for technology stack drift check)Custom Rules (if exist):
.arckit/conformance-rules.md in the project rootRun ALL 12 conformance checks. Each check produces a PASS/FAIL/NOT ASSESSED status with evidence.
For EACH ADR with status "Accepted":
Evidence format: ADR "Title" (file:line) → HLD Section X (file:line) — [IMPLEMENTED/NOT FOUND]
Evidence format: ADR-001 (file:line) CONFLICTS WITH ADR-005 (file:line) — [description]
Evidence format: Superseded ADR "Title" (file:line) — residue found in HLD Section X (file:line)
For EACH architecture principle:
Note: This differs from $arckit-principles-compliance which provides RAG scoring with remediation plans. This check is a binary gate: does the design conform or not?
Evidence format: Principle "Name" — HLD Section X (file:line) [SATISFIES/VIOLATES] — [description]
Evidence format: Condition "[text]" (file:line) — [RESOLVED in file:line / UNRESOLVED]
Evidence format: Exception "EXC-NNN" (file:line) — expired [DATE], [REMEDIATED/STILL ACTIVE]
Evidence format: Exception "EXC-NNN" — remediation plan [EXISTS/MISSING], progress [EVIDENCE/NONE]
Evidence format: Technology "[name]" — ADR (file:line) says [X], Design (file:line) uses [Y]
Evidence format: Pattern "[name]" chosen in ADR/HLD (file:line) — DLD component [X] (file:line) uses [different pattern]
.arckit/conformance-rules.md if it existsEvidence format: Rule "[text]" — [SATISFIED/VIOLATED] at (file:line)
Evidence format: ATD-NNN: "[description]" — Category: [category], Source: (file:line)
Evidence format: Potential ATD: "[description]" found at (file:line) — not documented in any ADR/risk/exception
Scoring:
(PASS count / (PASS + FAIL count)) × 100Deviation Tier Assignment — for each FAIL finding, assign a tier based on result + severity:
Tier-Specific Response Requirements:
Overall Recommendation:
Use the document ID ARC-{PROJECT_ID}-CONF-v{VERSION} (e.g., ARC-001-CONF-v1.0).
Before writing the file, read .arckit/references/quality-checklist.md and verify all Common Checks plus the CONF per-type checks pass. Fix any failures before proceeding.
Use the Write tool to save the document to projects/{project-dir}/ARC-{PROJECT_ID}-CONF-v{VERSION}.md.
Populate the template with all conformance check results, following the structure defined in the template.
IMPORTANT: Use Write tool, not output to user. Document will be 500-2000 lines depending on the number of ADRs, principles, and findings.
Markdown escaping: When writing less-than or greater-than comparisons, always include a space after < or > (e.g., < 3 seconds, > 99.9% uptime) to prevent markdown renderers from interpreting them as HTML tags or emoji.
Display concise summary (NOT full document):
✅ Architecture conformance assessment generated
📊 **Conformance Summary**:
- Overall Score: [X]% ([CONFORMANT / CONFORMANT WITH CONDITIONS / NON-CONFORMANT])
- Checks Passed: [X] / [Y]
- Checks Failed: [X]
- Not Assessed: [X]
[IF RED findings:]
🔴 **RED — Escalate** ([N]):
- [Check ID]: [Brief description]
[List all RED findings]
[IF YELLOW findings:]
🟡 **YELLOW — Negotiate** ([N]):
- [Check ID]: [Brief description]
[List all YELLOW findings]
[IF GREEN findings:]
🟢 **GREEN — Acceptable** ([N]):
- [Check ID]: [Brief description]
[List all GREEN findings]
[IF ATD items found:]
📦 **Architecture Technical Debt**: [X] known items, [Y] potential untracked items
📄 **Document**: projects/{project-dir}/ARC-{PROJECT_ID}-CONF-v{VERSION}.md
🔍 **Recommendation**:
[CONFORMANT]: ✅ Architecture conforms to decisions and principles
[CONFORMANT WITH CONDITIONS]: ⚠️ No critical deviations — [N] YELLOW findings need remediation by [date]
[NON-CONFORMANT]: ❌ [N] RED findings require escalation before proceeding
**Next Steps**:
1. Review detailed findings in the generated document
2. [IF RED findings:] Escalate critical deviations to architecture board immediately
3. [IF YELLOW findings:] Agree remediation plans or fallback positions within 30 days
4. [IF ATD items:] Review technical debt register with architecture board
5. [IF custom rules missing:] Consider creating `.arckit/conformance-rules.md` for project-specific rules
6. Schedule next conformance check at [next gate/phase]
After generating the assessment document:
Suggest Follow-up Commands:
📋 **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
Track in Project: Suggest adding remediation actions to project tracking:
< or > (e.g., < 3 seconds, > 99.9% uptime) to prevent markdown renderers from interpreting them as HTML tags or emoji