--- id: CAP-CRM-REG-009 title: Preserve a deliberate regional exception feature: FEAT-CRM-REG-03 product_area: crm module: regions revision: 2 status: draft product_intent: proposed implementation_evidence: observed supersedes: [] source_sha: services-crm: a8d1364f1dd44b723bb5f9acba12f983e9ec8d69 react-console: baf6dae382d6f41dce976c7f848667ccc37e076f intent_sources: - 'services-crm:docs/milestones/CRM-M1-contacts-and-organizations.plan.md#CRM-ACC-0023' - 'services-crm:docs/milestones/CRM-M1-contacts-and-organizations.plan.md#CRM-ACC-0120' - >- services-crm:docs/migrations/crm-regions/README.md#Behaviour changes, Not changed (kept as Rhythm 1.0 did; accepted by Andrew 2026-10-08) - >- services-crm:docs/migrations/crm-regions/README.md#Behaviour changes, item 3 (Andrew's requirement for the port: a region the workspace lacks is refused and a region in use cannot be deleted) purpose: Staff assign an exception region and protect that choice from automatic placement until they release it. outcomes: - Deliberate exceptions survive address changes and recalculation. - Releasing an exception restores eligibility for address-based placement. concepts: - CON-CRM-REG-003 actors: - ACT-CRM-001 - ACT-CRM-003 surfaces: - console - api preconditions: [] postconditions: [] permissions: - key: crm.contacts.update where_checked: api scope: tenant - key: crm.organizations.update where_checked: api scope: tenant rules: - id: BR-CAP-CRM-REG-009-01 proved_by: [ATS-CRM-REG-008-15, ATS-CRM-REG-009-01, ATS-CRM-REG-009-05, TST-CRM-REG-020, TST-CRM-REG-029, TST-CRM-REG-058, TST-CRM-REG-063] statement: >- A record with automatic assignment overridden retains its region through ordinary assignment and recalculation. kind: policy enforced_at: - service must_prove: true provenance: test source: >- services-crm:modules/regions/tests/integration/services/region-assignment/region-assignment.integration.spec.js#manual regions and the override › never changes the region of a contact that overrides automatic assignment origin: 'services-crm:docs/milestones/CRM-M1-contacts-and-organizations.plan.md#CRM-ACC-0023' - id: BR-CAP-CRM-REG-009-02 proved_by: [ATS-CRM-REG-009-02, ATS-CRM-REG-009-06, TST-CRM-REG-058] statement: >- Without an override, a manually chosen region survives an unchanged deciding address but yields to matching after that address changes. kind: policy enforced_at: - service must_prove: true provenance: test source: >- services-crm:modules/regions/tests/integration/services/region-assignment/region-assignment.integration.spec.js#manual regions and the override › replaces a manual region when the deciding address changes origin: >- services-crm:docs/migrations/crm-regions/README.md#Behaviour changes, Not changed (kept as Rhythm 1.0 did; accepted by Andrew 2026-10-08) - id: BR-CAP-CRM-REG-009-03 proved_by: [ATS-CRM-REG-008-15, ATS-CRM-REG-009-03, ATS-CRM-REG-009-05, ATS-CRM-REG-009-06, TST-CRM-REG-058] statement: >- Releasing the override reconciles the current deciding address, including changes made while automatic placement was held. kind: policy enforced_at: - service must_prove: true provenance: test source: >- services-crm:modules/regions/tests/integration/services/region-assignment/region-assignment.integration.spec.js#manual regions and the override › a contact moved while overridden, then switched back to automatic › assigns the region of the address it moved to once the override is off origin: 'services-crm:docs/milestones/CRM-M1-contacts-and-organizations.plan.md#CRM-ACC-0120' - id: BR-CAP-CRM-REG-009-04 proved_by: [] statement: Enabling the override alone causes no assignment change. kind: policy enforced_at: - service must_prove: false provenance: observed source: >- services-crm:modules/regions/services/region-assignment/region-assignment.ts:regionAssignmentOverrideHandler origin: none - id: BR-CAP-CRM-REG-009-05 proved_by: [ATS-CRM-REG-009-04, TST-CRM-REG-020, TST-CRM-REG-049, TST-CRM-REG-058] statement: Saving a record with a region outside its workspace is rejected without committing the record. kind: validation enforced_at: - service - database must_prove: true provenance: test source: >- services-crm:modules/regions/tests/integration/services/region-assignment/region-assignment.integration.spec.js#refusals › refuses a contact naming a region the tenant does not have origin: >- services-crm:docs/migrations/crm-regions/README.md#Behaviour changes, item 3 (Andrew's requirement for the port: a region the workspace lacks is refused and a region in use cannot be deleted) - id: BR-CAP-CRM-REG-009-06 proved_by: [] statement: Region references retained from before the region constraints were introduced remain accepted. kind: policy enforced_at: - database must_prove: false provenance: documented source: 'services-crm:docs/migrations/crm-regions/README.md#Behaviour changes' origin: >- services-crm:docs/migrations/crm-regions/README.md#Behaviour changes, item 3 (Andrew's requirement for the port: a region the workspace lacks is refused and a region in use cannot be deleted) - id: BR-CAP-CRM-REG-009-07 proved_by: [] statement: >- Organizations do not inherit a region through their hierarchy; placement uses each organization’s own address. kind: invariant enforced_at: - service must_prove: false provenance: documented source: 'react-console:acceptance/crm/inventory/business-rules.json#RUL-CRM-ORG-042' origin: none scenarios: - id: SC-CAP-CRM-REG-009-01 given: A Phoenix member deliberately belongs to the Nevada chapter. when: 'The coordinator selects Nevada, enables the override and later edits the Arizona address.' then: The member retains Nevada. provenance: test source: 'react-console:acceptance/crm/playwright/journeys/contacts/CRM-ACC-0023.spec.ts#CRM-ACC-0023' - id: SC-CAP-CRM-REG-009-02 given: The member’s manual exception is no longer needed. when: The coordinator releases the override. then: Address-based reconciliation can place the member in Arizona. provenance: test source: 'react-console:acceptance/crm/playwright/journeys/contacts/CRM-ACC-0023.spec.ts#CRM-ACC-0023' edge_cases: - id: SC-CAP-CRM-REG-009-03 given: An organization changed addresses while its placement was held. when: Staff release its override without another address edit. then: Assignment evaluates the current address. provenance: test source: >- services-crm:modules/regions/tests/integration/services/region-assignment/region-assignment.integration.spec.js#manual regions and the override › an organization moved while overridden, then switched back to automatic › assigns the region of the address it moved to once the override is off constraints: [] depends_on: - CAP-CRM-REG-001 related: - CAP-CRM-REG-008 - CAP-CRM-REG-011 journeys: - JNY-CRM-REG-003 open_questions: [] evidence: - >- services-crm: Examined the pinned regional implementation, its declared constraints and the supporting records. - 'react-console: Examined the pinned regional configuration surfaces and their available test evidence.' - 'services-crm:docs/milestones/CRM-M1-contacts-and-organizations.plan.md' - 'services-crm:docs/migrations/crm-regions/README.md' - >- services-crm:modules/regions/tests/integration/services/region-assignment/region-assignment.integration.spec.js - 'services-crm:modules/regions/services/region-assignment/region-assignment.ts' - 'react-console:acceptance/crm/inventory/business-rules.json' - 'react-console:acceptance/crm/playwright/journeys/contacts/CRM-ACC-0023.spec.ts' controls: [TC-AZ-001, TC-AZ-002, TC-AZ-003, TC-AZ-004, TC-AZ-006, TC-DAT-001, TC-DAT-002, TC-DAT-003, TC-LOG-004, TC-LOG-005, TC-PI-001, TC-PI-003, TC-PI-005, TC-PRV-001, TC-PRV-002, TC-TEN-001, TC-TEN-002, TC-TEN-003] exercised_by: [FAS-CRM-REG-03-01, FAS-CRM-REG-03-02, FAS-CRM-REG-03-03, FAS-CRM-REG-03-04, FAS-CRM-REG-03-05] suites: [TST-CRM-REG-020, TST-CRM-REG-029, TST-CRM-REG-049, TST-CRM-REG-058, TST-CRM-REG-063] --- # Preserve a deliberate regional exception ## Purpose Staff assign an exception region and protect that choice from automatic placement until they release it. ## How It Works A coordinator can select a region directly on a contact or organization. Enabling the automatic-assignment override preserves that deliberate choice through subsequent address moves. Recalculation respects the same exception. Without an override, the manual choice lasts until the deciding input changes or recalculation reevaluates it. Releasing an override schedules reconciliation of the current address. A move made while held can therefore determine the restored automatic placement. Enabling the override alone does not move the record. A region outside the workspace is rejected. An organization’s hierarchy does not supply an inherited regional placement. The acceptance tests record shortcomings in how contact screens display regional choices. ## Relationships - Maintain the region catalogue supplies the regional catalogue used by the surrounding work. - Keep placements aligned with address changes coordinates placement after committed address changes. - Apply the current policy across existing records applies policy changes to existing records.