---
id: CAP-PFM-ELG-005
title: Replace obsolete rules without losing their uses
feature: FEAT-PFM-ELG-01
product_area: platform
module: eligibility
revision: 1
status: draft
product_intent: confirmed
implementation_evidence: observed
supersedes:
  - CAP-ELIG-GOV-005
  - CAP-ELIG-GOV-006
  - CAP-ELIG-GOV-007
  - CAP-ELIG-GOV-008
  - CAP-ELIG-GOV-011
  - CAP-ELIG-DEF-013
source_sha:
  services-platform: ad3f6a6582843008ed0f5a17b131878d15829af1
  react-console: baf6dae382d6f41dce976c7f848667ccc37e076f
intent_sources:
  - 'services-platform:docs/milestones/plans/PLAT-M11-plan.md#2. Scope'
purpose: >-
  Administrators need a controlled path away from an obsolete rule. Retirement
  preserves dependent decisions while they move to a replacement.
outcomes:
  - >-
    Existing consumers continue using deprecated rules while new uses choose
    alternatives.
  - A replacement operation transfers compatible uses together.
  - Archiving waits until all dependencies have cleared.
concepts:
  - CON-PFM-ELG-001
  - CON-PFM-ELG-002
actors:
  - ACT-PFM-023
surfaces:
  - console
  - api
preconditions: []
postconditions: []
permissions:
  - key: platform.eligibility.retire
    where_checked: api
    scope: tenant
rules:
  - id: BR-CAP-PFM-ELG-005-01
    proved_by: [ATS-PFM-ELG-005-01, TST-PFM-ELG-186, TST-PFM-ELG-411]
    statement: >-
      Retirement authority is required to deprecate, archive, restore, delete or
      transfer a rule’s uses; draft-writing and binding authority alone do not
      suffice.
    kind: permission
    enforced_at:
      - api
    must_prove: true
    provenance: test
    source: >-
      services-platform:modules/eligibility/tests/e2e/eligibility-definitions.e2e.spec.js#refuses
      the deprecation to a writer without the retire permission, 403
    origin: none
  - id: BR-CAP-PFM-ELG-005-02
    proved_by: [ATS-PFM-ELG-005-02, TST-PFM-ELG-172, TST-PFM-ELG-173, TST-PFM-ELG-411]
    statement: >-
      Deprecation preserves existing evaluations but blocks new uses, with an
      optional replacement that is active, published and different from the
      original rule.
    kind: lifecycle
    enforced_at:
      - service
    must_prove: true
    provenance: test
    source: >-
      services-platform:modules/eligibility/tests/e2e/eligibility-definitions.e2e.spec.js#refuses
      a new binding of the deprecated rule, 409
    origin: none
  - id: BR-CAP-PFM-ELG-005-03
    proved_by: [ATS-PFM-ELG-002-10, ATS-PFM-ELG-005-03, ATS-PFM-ELG-005-09, TST-PFM-ELG-174, TST-PFM-ELG-450]
    statement: >-
      Archive rejects rules still followed or pinned by active bindings or
      referenced by live rules’ current drafts or published versions, reporting
      both dependency counts.
    kind: policy
    enforced_at:
      - service
    must_prove: true
    provenance: test
    source: >-
      services-platform:modules/eligibility/tests/integration/services/persistence/definitions.integration.spec.js#refuses
      while an active binding follows it, counting the binding, and leaves it
      active
    origin: none
  - id: BR-CAP-PFM-ELG-005-04
    proved_by: [ATS-PFM-ELG-005-04, TST-PFM-ELG-450, TST-PFM-ELG-481]
    statement: >-
      Archive blocks drafts, new bindings and binding reactivation; restoration
      returns the rule to active standing and removes its replacement
      designation.
    kind: lifecycle
    enforced_at:
      - service
    must_prove: true
    provenance: test
    source: >-
      services-platform:modules/eligibility/tests/unit/lifecycle.spec.js#refuses
      making a binding of an archived definition active again
    origin: none
  - id: BR-CAP-PFM-ELG-005-05
    proved_by: [ATS-PFM-ELG-004-14, ATS-PFM-ELG-005-05, ATS-PFM-ELG-005-10, ATS-PFM-ELG-005-11, ATS-PFM-ELG-007-18, TST-PFM-ELG-175, TST-PFM-ELG-433]
    statement: >-
      Replacement moves compatible following bindings without duplicating a
      consumer use, republishes referencing rules and leaves pinned bindings and
      references for a person to resolve.
    kind: lifecycle
    enforced_at:
      - service
    must_prove: true
    provenance: test
    source: >-
      services-platform:modules/eligibility/tests/integration/services/governance/lifecycle.integration.spec.js#lists
      the pinned binding for a person to move, and leaves it on the deprecated
      definition
    origin: none
  - id: BR-CAP-PFM-ELG-005-06
    proved_by: [ATS-PFM-ELG-005-06, TST-PFM-ELG-176, TST-PFM-ELG-433]
    statement: >-
      Transferring references requires an active published replacement and
      reports any referencing expression that fails validation without
      publishing it.
    kind: validation
    enforced_at:
      - service
    must_prove: true
    provenance: test
    source: >-
      services-platform:modules/eligibility/tests/integration/services/governance/lifecycle.integration.spec.js#refuses
      a replacement that was never published
    origin: none
  - id: BR-CAP-PFM-ELG-005-07
    proved_by: [ATS-PFM-ELG-005-07, TST-PFM-ELG-411, TST-PFM-ELG-433]
    statement: >-
      Deletion removes only never-published rules and their drafts, dependencies
      and plans, refusing rules with bindings, references or resolved conversion
      reviews.
    kind: policy
    enforced_at:
      - service
    must_prove: true
    provenance: test
    source: >-
      services-platform:modules/eligibility/tests/e2e/eligibility-definitions.e2e.spec.js#refuses
      a published definition, 409, naming the archive instead
    origin: none
  - id: BR-CAP-PFM-ELG-005-08
    proved_by: [ATS-PFM-ELG-005-08, TST-PFM-ELG-182, TST-PFM-ELG-450]
    statement: >-
      A lifecycle request with an obsolete version fails, while a request
      without a version proceeds against the current record.
    kind: validation
    enforced_at:
      - service
    must_prove: true
    provenance: test
    source: >-
      services-platform:modules/eligibility/tests/integration/services/persistence/definitions.integration.spec.js#refuses
      a lifecycle move at a version that is no longer current
    origin: >-
      services-platform:docs/milestones/plans/PLAT-M11-plan.md#Appendix A.
      Behaviours that stand as built unless Andrew objects
  - id: BR-CAP-PFM-ELG-005-09
    proved_by: []
    statement: >-
      The product should support withdrawing one published version as the
      retirement permission describes, but no exposed operation currently offers
      that action.
    kind: lifecycle
    enforced_at:
      - service
    must_prove: false
    provenance: unknown
    source: FND-PFM-ELG-005
    origin: none
scenarios:
  - id: SC-CAP-PFM-ELG-005-01
    given: An expression has one active price use and one published reference.
    when: The administrator requests archive.
    then: >-
      The refusal counts both dependencies; removing them permits archive and
      later restoration.
    provenance: test
    source: >-
      react-console:acceptance/eligibility/playwright/journeys/governance/ELIG-ACC-0142.spec.ts#ELIG-ACC-0142
  - id: SC-CAP-PFM-ELG-005-02
    given: An obsolete annual rule designates a rolling replacement.
    when: The administrator transfers its dependencies.
    then: >-
      Followers move, pins remain for manual handling and references receive
      fresh releases with change notes.
    provenance: test
    source: >-
      react-console:acceptance/eligibility/playwright/journeys/governance/ELIG-ACC-0143.spec.ts#ELIG-ACC-0143
edge_cases: []
constraints: []
depends_on:
  - CAP-PFM-ELG-004
related:
  - CAP-PFM-ELG-002
  - CAP-PFM-ELG-007
journeys: []
open_questions: []
evidence:
  - >-
    services-platform: docs/eligibility.md;
    docs/milestones/PLAT-M11-eligibility-rules.md and plans/PLAT-M11-plan.md;
    docs/proposals/eligibility/17-decision-register.md; aws/platform.service.ts
    (ELIGIBILITY_PERMISSIONS); modules/eligibility/aws/api/definitions.routes.ts
    (deprecate, archive, restore, delete, migrate_references), lifecycle.ts,
    services/governance/lifecycle.ts, services/persistence/definitions.ts
    (deleteDefinition, liveUsageOf), versions.ts (retireVersion),
    db/eligibility-migration-reviews.table.ts (the delete refusal);
    docs/debt/eligibility-migrate-references-in-request.md; rule-level source
    and test references
  - >-
    react-console: components/configuration/resources/eligibility-rules.tsx
    (Archive, Restore); acceptance/eligibility/journeys/governance/ELIG-ACC-0140
    to 0144, 0150, 0154.
controls: [TC-AZ-001, TC-AZ-002, TC-AZ-003, TC-AZ-004, TC-DAT-001, TC-DAT-002, TC-DAT-003, TC-DAT-004, TC-IAM-001, TC-IAM-006, TC-LOG-004, TC-LOG-005, TC-PI-001, TC-PI-003, TC-PI-005, TC-TEN-001, TC-TEN-002, TC-TEN-003, TC-VEN-001, TC-VEN-002, TC-VEN-003]
exercised_by: [FAS-PFM-ELG-01-02, FAS-PFM-ELG-01-04]
suites: [TST-PFM-ELG-172, TST-PFM-ELG-173, TST-PFM-ELG-174, TST-PFM-ELG-175, TST-PFM-ELG-176, TST-PFM-ELG-182, TST-PFM-ELG-186, TST-PFM-ELG-411, TST-PFM-ELG-433, TST-PFM-ELG-450, TST-PFM-ELG-481]
---
# Replace obsolete rules without losing their uses

## Purpose

Administrators need a controlled path away from an obsolete rule. Retirement preserves dependent decisions while they move to a replacement.

## How It Works

The administrator reviews dependencies and selects a replacement when appropriate. Deprecation discourages new uses while existing consumers keep working. A transfer report distinguishes moved uses from those needing attention. Pinned dependencies remain a deliberate choice for their owners. Referencing expressions are released again when replacement is valid. The administrator clears remaining dependencies before archive. Restoration makes an archived rule available again. Deletion is reserved for unused work that was never released. Stale lifecycle requests require another read. The product should expose individual-version withdrawal if that remains the intended retirement action.

## Relationships

- Release, schedule and restore rule versions releases replacement expressions in rules that include the retired definition.