truf-server/openspec/changes/stabilize-gitlab-discovery-retries/specs/gitlab-discovery-resilience/spec.md

ADDED Requirements

Requirement: Bounded GitLab discovery transport retries

The system SHALL retry idempotent GitLab project discovery requests after transient transport failures using a source-configured bounded attempt count and delay.

Scenario: Transient timeout succeeds on retry

• WHEN a GitLab project discovery request times out and a later attempt within the configured budget succeeds
• THEN discovery continues using the successful response without restarting the source

Scenario: Retry budget is bounded

• WHEN every GitLab project discovery attempt fails transiently
• THEN the request stops after the configured attempt count and does not retry indefinitely

Requirement: Exhausted discovery is a nonfatal source cycle

The system SHALL record an exhausted GitLab discovery transport failure as a failed cycle without terminating the supervised source child.

Scenario: Discovery attempts are exhausted

• WHEN GitLab project discovery exhausts its transport attempt budget
• THEN the cycle is finished as failed and the configured source loop remains alive

Scenario: Query position is retained

• WHEN a GitLab discovery cycle fails from an exhausted transport error
• THEN the current query is not advanced and is eligible for the next cycle

Requirement: Discovery failure isolation

The system SHALL keep transport-only GitLab discovery failures separate from authentication, rate-limit, scanner, and non-GitLab source policy.

Scenario: Token remains healthy after transport failure

• WHEN GitLab discovery fails only because of a network transport error
• THEN the active token is not marked invalid or rate limited

Scenario: Other source behavior is unchanged

• WHEN a non-GitLab source encounters an API request failure
• THEN this GitLab-only cycle handling does not alter its existing behavior