truf-server/openspec/changes/restore-openai-discovery-coverage/specs/openai-discovery-coverage/spec.md

ADDED Requirements

Requirement: Exact OpenAI core discovery

The system SHALL include the literal openai query in the normal GitHub, GitLab, and DockerHub core discovery rotations.

Scenario: Exact provider term is rotated

• WHEN each supported source reaches its configured exact-query position
• THEN the source SHALL execute discovery using the literal openai term and persist normal cycle attribution

Scenario: Successful exact-query cycle advances

• WHEN an exact-query source cycle completes successfully
• THEN the source SHALL advance to its next configured query through the existing persisted rotation

Scenario: Failed exact-query cycle is retained

• WHEN exact-query discovery fails before a successful cycle completion
• THEN the source SHALL retain the same query according to existing failure semantics

Requirement: Query-scoped safety bounds

The system SHALL support exact-query overrides for only pages, per_page, and max_targets, without changing source-wide defaults for other queries.

Scenario: Exact query receives bounded arguments

• WHEN a source builds arguments for openai
• THEN it SHALL apply that source's configured page, page-size, and target overrides

Scenario: Ordinary query retains source defaults

• WHEN the same source builds arguments for any query without an override
• THEN it SHALL retain the source-wide page, page-size, and target values

Scenario: Invalid override fails closed

• WHEN a query override is not a mapping or contains a key outside the allowlist
• THEN argument construction SHALL fail before discovery or queue mutation

Requirement: Source-specific rollout limits

The initial production policy SHALL constrain GitHub and GitLab exact discovery to one page each and DockerHub exact discovery to two pages of ten results, while preserving the existing global scan limit and changed-target promotion cap.

Scenario: Docker exact discovery is bounded

• WHEN DockerHub executes the exact openai query
• THEN it SHALL request at most two pages of ten repositories and claim at most twenty targets in that cycle

Scenario: Revision-aware source remains bounded

• WHEN GitLab exact discovery observes multiple changed completed projects
• THEN updated-target promotion SHALL remain capped by the existing one-per-cycle policy

Scenario: Docker target authority is unchanged

• WHEN DockerHub exact discovery returns repository names
• THEN only targets satisfying the existing immutable digest requirement SHALL reach scanning

Requirement: End-to-end canary evidence

The rollout SHALL be evaluated from source discovery through durable scan completion, candidate completion, provider result, and projection drain without exposing credential or target values.

Scenario: Safe canary completes

• WHEN the first exact-query cycles run after deployment
• THEN operators SHALL verify source limits, new and updated admissions, queue dispositions, pipeline completion, and runtime health using aggregate evidence

Scenario: Useful yield is reported accurately

• WHEN exact-query scans create OpenAI candidates
• THEN operators SHALL report genuinely new credentials and their explicit API outcomes separately from cached-known occurrences and stale legacy file state