ADR-002: Three-ID Model for Checklist Item Identification

Attribute	Value
Status	Accepted
Date	March 2026

Context

Every checklist item needs identification that serves three different audiences: customers referencing findings in reports and support conversations, engineers debugging assessment logic, and the system matching graph query results to checklist items.

Decision

Implement a three-ID model: CYC ID (customer-facing, stable), ARC Short ID (human-readable internal debug reference), GUID (machine-readable primary key).

Options Considered

Option A — Assessment-scoped sequence: IDs generated fresh per assessment ordered by severity and area. Simple to implement, but IDs change between assessments — makes Tier 3 drift tracking impossible.

Option B — Fixed sequence (chosen): IDs assigned once at product setup mapped to checklist items. Stable across assessment cycles. Required for drift detection.

Option C — Use ARC GUID directly as customer ID: Stable, but GUIDs are not human-readable and expose internal methodology structure to customers.

Rationale

Fixed sequence (Option B) was chosen because Tier 3 drift detection requires stable IDs to track remediation progress across assessments. A client must be able to see that CYC-ALZ-NET-H-001 moved from non_compliant to compliant between March and June assessments.

The CYC ID format encodes enough context (checklist-area-severity-sequence) to be meaningful without exposing internal methodology. The ARC Short ID (B03.02) is preserved internally for engineer readability during debugging.

Consequences

• cyc_id_mapping.json is the source of truth and must be stored in the CYC database
• When Microsoft removes a checklist item, the CYC ID is deprecated but never reassigned
• SAP items have no ARC Short ID — arc_id is null for these items
• Three ALZ items have duplicate ARC Short IDs confirming GUID must be the machine key