Arckit Conformance

User Input

$ARGUMENTS

Goal

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.

Prerequisites

Architecture Principles (MANDATORY)

a. PRIN (Architecture Principles, in projects/000-global/) (MUST exist):

• If NOT found: ERROR "Run $arckit-principles first to define governance standards for your organization"

Architecture Decision Records (MANDATORY)

b. ADR (Architecture Decision Records, in projects/{project-dir}/decisions/) (MUST exist):

• If NOT found: ERROR "Run $arckit-adr first — conformance assessment requires at least one accepted ADR"

Project Artifacts (RECOMMENDED)

More artifacts = better conformance assessment:

• REQ (Requirements) in projects/{project-dir}/ — Requirements to cross-reference
• projects/{project-dir}/vendors/{vendor}/hld-v*.md — High-Level Design
• projects/{project-dir}/vendors/{vendor}/dld-v*.md — Detailed Low-Level Design
• HLDR (HLD Review) in projects/{project-dir}/reviews/ — Design review findings
• DLDR (DLD Review) in projects/{project-dir}/reviews/ — Detailed review findings
• PRIN-COMP (Principles Compliance) in projects/{project-dir}/ — Prior compliance assessment
• TRAC (Traceability Matrix) in projects/{project-dir}/ — Requirements traceability
• RISK (Risk Register) in projects/{project-dir}/ — Risk context for exceptions
• DEVOPS (DevOps Strategy) in projects/{project-dir}/ — CI/CD and deployment patterns

Custom Constraint Rules (OPTIONAL)

c. .arckit/conformance-rules.md in the project root (if exists):

• Contains user-defined ArchCNL-style constraint rules
• Format: Natural language rules with MUST/MUST NOT/SHOULD/SHOULD NOT keywords
• Example: "All API services MUST use OAuth 2.0 for authentication"
• Example: "Database connections MUST NOT use plaintext credentials"

Note: Assessment is possible with minimal artifacts (principles + ADRs), but accuracy improves significantly with HLD/DLD and review documents.

Operating Constraints

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.

Execution Steps

Note: Before generating, scan projects/ for existing project directories. For each project, list all ARC-*.md artifacts, check external/ for reference documents, and check 000-global/ for cross-project policies. If no external docs exist but they would improve output, ask the user.

0. Read the Template

Read the template (with user override support):

• First, check if .arckit/templates-custom/conformance-assessment-template.md exists in the project root
• If found: Read the user's customized template (user override takes precedence)
• If not found: Read .arckit/templates/conformance-assessment-template.md (default)
• Then read .arckit/templates/_partials/RENDERING.md and resolve the <!-- DOC-CONTROL-HEADER --> marker in the template before writing. Do not hand-write the Document Control table: the partial RENDERING.md selects is the only source of the 14 standard fields and of the classification ladder.

Tip: Users can customize templates with $arckit-customize conformance

1. Validate Prerequisites

Check Architecture Principles:

• Look for ARC-000-PRIN-*.md in projects/000-global/
• If NOT found: ERROR "Architecture principles not found. Run $arckit-principles first."

Check ADRs:

• Look for ARC-*-ADR-*.md files in projects/{project-dir}/decisions/
• If NONE found: ERROR "No ADRs found. Run $arckit-adr first — conformance assessment requires at least one accepted ADR."

1b. Read external documents and policies

• Read any external documents listed in the project context (external/ files) — extract audit findings, compliance gaps, certification evidence, remediation plans
• Read any enterprise standards in projects/000-global/external/ — extract enterprise compliance frameworks, cross-project conformance benchmarks
• If no external docs exist but they would improve the assessment, note this as an assessment limitation
• Citation traceability: When referencing content from external documents, follow the citation instructions in .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.

2. Identify the Target Project

• Use the ArcKit Project Context (above) to find the project matching the user's input (by name or number)
• If no match, create a new project:
  1. Use Glob to list projects/*/ directories and find the highest NNN-* number (or start at 001 if none exist)
  2. Calculate the next number (zero-padded to 3 digits, e.g., 002)
  3. Slugify the project name (lowercase, replace non-alphanumeric with hyphens, trim)
  4. Use the Write tool to create projects/{NNN}-{slug}/README.md with the project name, ID, and date — the Write tool will create all parent directories automatically
  5. Also create projects/{NNN}-{slug}/external/README.md with a note to place external reference documents here
  6. Set PROJECT_ID = the 3-digit number, PROJECT_PATH = the new directory path

3. Load All Relevant Artifacts

Read the following artifacts. Do NOT read entire files — extract relevant sections for each conformance check.

Architecture Principles (projects/000-global/ARC-000-PRIN-*.md):

• Extract ALL principles dynamically (name, statement, rationale, implications)

ADRs (projects/{project-dir}/decisions/ARC-*-ADR-*.md):

• For EACH ADR, extract: title, status (Accepted/Superseded/Deprecated/Proposed), decision text, context, consequences (positive and negative), related ADRs
• Track supersession chains (which ADR supersedes which)

Design Documents (if exist):

• projects/{project-dir}/vendors/{vendor}/hld-v*.md — Architecture overview, technology stack, patterns, components
• projects/{project-dir}/vendors/{vendor}/dld-v*.md — Detailed implementation, API specs, infrastructure

Review Documents (if exist):

• ARC-*-HLDR-*.md in reviews/ — HLD review conditions, findings
• ARC-*-DLDR-*.md in reviews/ — DLD review conditions, findings

Other Artifacts (if exist):

• ARC-*-REQ-*.md — Requirements for traceability
• ARC-*-PRIN-COMP-*.md — Prior principles compliance (for trend comparison)
• ARC-*-TRAC-*.md — Traceability matrix
• ARC-*-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 root

4. Execute Conformance Checks

Run ALL 12 conformance checks. Each check produces a PASS/FAIL/NOT ASSESSED status with evidence.

Check ADR-IMPL: ADR Decision Implementation (Severity: HIGH)

For EACH ADR with status "Accepted":

1. Extract the Decision section text
2. Search HLD and DLD for evidence that the decision is implemented
3. Check that the technology/pattern/approach chosen in the ADR appears in the design
4. PASS: Design documents reference or implement the ADR decision
5. FAIL: Decision is accepted but not reflected in design documents
6. NOT ASSESSED: No HLD/DLD available to check against

Evidence format: ADR "Title" (file:line) → HLD Section X (file:line) — [IMPLEMENTED/NOT FOUND]

Check ADR-CONFL: Cross-ADR Consistency (Severity: HIGH)

1. Compare all Accepted ADRs for contradictions:
   • Technology choices that conflict (e.g., ADR-001 chooses PostgreSQL, ADR-005 chooses MongoDB for same purpose)
   • Pattern choices that conflict (e.g., ADR-002 mandates event-driven, ADR-007 mandates synchronous API calls for same integration)
   • Scope overlaps where decisions disagree
2. PASS: No contradictions found between accepted ADRs
3. FAIL: Contradictions identified — list conflicting ADR pairs with specific conflicts

Evidence format: ADR-001 (file:line) CONFLICTS WITH ADR-005 (file:line) — [description]

Check ADR-SUPER: Superseded ADR Enforcement (Severity: MEDIUM)

1. Identify all Superseded ADRs
2. Check that HLD/DLD does NOT reference patterns/technologies from superseded decisions
3. Check that the superseding ADR's decision IS reflected instead
4. PASS: No residue from superseded decisions found in design
5. FAIL: Design still references superseded decision patterns/technologies

Evidence format: Superseded ADR "Title" (file:line) — residue found in HLD Section X (file:line)

Check PRIN-DESIGN: Principles-to-Design Alignment (Severity: HIGH)

For EACH architecture principle:

1. Extract the principle statement and implications
2. Search HLD/DLD for design elements that satisfy or violate the principle
3. Apply binary pass/fail constraint checking (unlike principles-compliance which uses RAG scoring):
   • Does the design VIOLATE this principle? → FAIL
   • Does the design SATISFY this principle? → PASS
   • Insufficient evidence to determine? → NOT ASSESSED
4. This is a hard constraint check, not a maturity assessment

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]

Check COND-RESOLVE: Review Condition Resolution (Severity: HIGH)

1. Read HLD/DLD review documents (HLDR, DLDR)
2. Look for conditions — typically flagged as "APPROVED WITH CONDITIONS", "CONDITIONAL", "CONDITIONS", or specific condition markers
3. For each condition found:
   • Search for evidence of resolution in subsequent artifacts or updated designs
   • Check if condition has been addressed in a newer version of the reviewed document
4. PASS: All review conditions have resolution evidence
5. FAIL: Unresolved conditions found — list each with its source and status

Evidence format: Condition "[text]" (file:line) — [RESOLVED in file:line / UNRESOLVED]

Check EXCPT-EXPIRY: Exception Register Expiry (Severity: HIGH)

1. Search for exception registers in principles-compliance assessment, risk register, and review documents
2. Look for patterns: "Exception", "EXC-", "Approved exception", "Waiver", "Exemption"
3. For each exception found, check if the expiry date has passed (compare to today's date)
4. PASS: No expired exceptions found (or no exceptions exist)
5. FAIL: Expired exceptions found that haven't been renewed or remediated

Evidence format: Exception "EXC-NNN" (file:line) — expired [DATE], [REMEDIATED/STILL ACTIVE]

Check EXCPT-REMEDI: Exception Remediation Progress (Severity: MEDIUM)

1. For each active (non-expired) exception found:
   • Check if a remediation plan exists
   • Check if there's evidence of progress toward remediation
   • Check if remediation timeline is realistic given remaining time to expiry
2. PASS: All active exceptions have remediation plans with evidence of progress
3. FAIL: Exceptions missing remediation plans or showing no progress

Evidence format: Exception "EXC-NNN" — remediation plan [EXISTS/MISSING], progress [EVIDENCE/NONE]

Check DRIFT-TECH: Technology Stack Drift (Severity: MEDIUM)

1. Extract technology choices from ADRs (databases, frameworks, languages, cloud services, tools)
2. Extract technology references from HLD, DLD, and DevOps strategy
3. Compare: do the technologies in design documents match ADR decisions?
4. Look for technologies appearing in design that were NOT decided via ADR (undocumented technology adoption)
5. PASS: Technology stack in design matches ADR decisions
6. FAIL: Technologies in design don't match ADR decisions, or undocumented technologies found

Evidence format: Technology "[name]" — ADR (file:line) says [X], Design (file:line) uses [Y]

Check DRIFT-PATTERN: Architecture Pattern Drift (Severity: MEDIUM)

1. Extract architecture patterns from ADRs and HLD (microservices, event-driven, REST, CQRS, etc.)
2. Check DLD for consistent pattern application across all components
3. Look for components that deviate from the chosen pattern without an ADR justifying the deviation
4. PASS: Patterns consistently applied across all design artifacts
5. FAIL: Inconsistent pattern application found

Evidence format: Pattern "[name]" chosen in ADR/HLD (file:line) — DLD component [X] (file:line) uses [different pattern]

Check RULE-CUSTOM: Custom Constraint Rules (Severity: Variable)

1. Read .arckit/conformance-rules.md if it exists
2. For each rule defined:
   • Parse the rule (natural language with MUST/MUST NOT/SHOULD/SHOULD NOT)
   • Search design artifacts for evidence of compliance or violation
   • Assign severity based on keyword: MUST/MUST NOT → HIGH, SHOULD/SHOULD NOT → MEDIUM
3. PASS: Rule satisfied with evidence
4. FAIL: Rule violated — cite specific violation
5. NOT ASSESSED: Insufficient artifacts to check rule
6. If no custom rules file exists: mark as NOT ASSESSED with note "No custom rules defined"

Evidence format: Rule "[text]" — [SATISFIED/VIOLATED] at (file:line)

Check ATD-KNOWN: Known Technical Debt (Severity: LOW)

1. Catalogue acknowledged architecture technical debt from:
   • ADR negative consequences: "Consequences" sections listing accepted downsides
   • Risk register accepted risks: Risks accepted as trade-offs (ACCEPT treatment)
   • Review conditions: Deferred items from HLD/DLD reviews
   • Workarounds: Temporary solutions documented in design
   • Scope reductions: Quality/features removed for timeline/budget
2. Classify each debt item into ATD 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
3. PASS: Known debt is documented and tracked (this check always passes if debt is acknowledged)
4. NOT ASSESSED: No artifacts available to catalogue debt

Evidence format: ATD-NNN: "[description]" — Category: [category], Source: (file:line)

Check ATD-UNTRACK: Untracked Technical Debt (Severity: MEDIUM)

1. Look for potential architecture technical debt NOT explicitly acknowledged:
   • Technologies in design but not in ADR decisions (ad-hoc adoption)
   • TODO/FIXME/HACK/WORKAROUND markers in design documents
   • Inconsistencies between HLD and DLD suggesting shortcuts
   • Design elements contradicting principles without an exception
   • Review findings not addressed in subsequent versions
2. PASS: No untracked debt detected
3. FAIL: Potential untracked debt identified — list items for team review

Evidence format: Potential ATD: "[description]" found at (file:line) — not documented in any ADR/risk/exception

5. Calculate Conformance Score

Scoring:

• Count PASS, FAIL, NOT ASSESSED for each check
• Calculate overall conformance percentage: (PASS count / (PASS + FAIL count)) × 100
• Exclude NOT ASSESSED from the denominator

Deviation Tier Assignment — for each FAIL finding, assign a tier based on result + severity:

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

Tier-Specific Response Requirements:

• For each 🔴 RED finding: explain the architecture risk, propose an alternative approach, recommend escalation to architecture board/CTO
• For each 🟡 YELLOW finding: provide specific remediation steps + timeline, include a fallback position if remediation is deferred
• For each 🟢 GREEN finding: document the deviation rationale, set a review date, no blocking action required

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%

6. Generate Document

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.

7. Show Summary to User

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]

Post-Generation Actions

After generating the assessment document:

1. 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
   

2. Track in Project: Suggest adding remediation actions to project tracking:

   • Create backlog items for FAIL findings
   • Schedule architecture technical debt review
   • Set next conformance check date

Important Notes

• 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