truf-server/openspec/changes/expand-openai-ecosystem-discovery/specs/openai-ecosystem-discovery/spec.md

ADDED Requirements

Requirement: Source-specific OpenAI ecosystem queries

The system SHALL include the approved first-wave OpenAI ecosystem queries only in the source rotations whose search semantics match those queries.

Scenario: GitHub searches integration signatures

• WHEN GitHub reaches the first-wave positions in its normal rotation
• THEN it SHALL search OPENAI_API_KEY, api.openai.com, and openai-agents

Scenario: GitLab searches branded project metadata

• WHEN GitLab reaches the first-wave positions in its normal rotation
• THEN it SHALL search openai-api, openai-agents, and librechat

Scenario: DockerHub searches deployable ecosystems

• WHEN DockerHub reaches the first-wave positions in its normal rotation
• THEN it SHALL search librechat, lobechat, and openai-proxy

Scenario: Broad generic expansion is excluded

• WHEN the first-wave configuration is evaluated
• THEN it SHALL NOT add new broad variants of gpt, llm, chatgpt, ai, or model

Requirement: Independent bounded query policies

Each first-wave query SHALL have an exact allowlisted override that bounds both discovery volume and scan claims without changing source defaults or other query policies.

Scenario: GitHub signature queries are bounded

• WHEN GitHub builds arguments for OPENAI_API_KEY or api.openai.com
• THEN it SHALL use one page of 25 results and claim at most five targets

Scenario: GitHub agent query is bounded

• WHEN GitHub builds arguments for openai-agents
• THEN it SHALL use one page of 50 results and claim at most five targets

Scenario: GitLab queries are bounded

• WHEN GitLab builds arguments for a first-wave query
• THEN it SHALL use one page, the configured 25- or 50-result page size, and claim at most five targets

Scenario: DockerHub queries are bounded

• WHEN DockerHub builds arguments for a first-wave query
• THEN it SHALL use at most two pages of ten repositories and claim at most ten targets

Scenario: Existing authority limits remain unchanged

• WHEN any first-wave query runs
• THEN global scan concurrency, revision-aware promotion limits, cooldowns, and Docker digest requirements SHALL remain authoritative

Requirement: Natural rotation and failure behavior

The first-wave queries SHALL use the existing persisted source rotation without direct query-state modification.

Scenario: Successful query advances

• WHEN a first-wave discovery cycle completes successfully
• THEN the source SHALL advance through the existing persisted rotation semantics

Scenario: Failed query is retained

• WHEN first-wave discovery fails before successful completion
• THEN the source SHALL retain that query according to existing failure semantics

Scenario: Backlog work does not masquerade as discovery

• WHEN a source drains existing backlog while a first-wave query is current
• THEN canary attribution SHALL distinguish backlog-only cycles from the actual discovery cycle

Requirement: Per-query end-to-end canary evidence

Operators SHALL evaluate each first-wave query through durable source, scan, candidate, provider-result, and projection evidence without exposing targets or credential values.

Scenario: Query cohort reaches terminal accounting

• WHEN a first-wave query admits new or updated targets
• THEN operators SHALL verify queue dispositions, scan completion, candidate completion, and projection drain for that exact query cohort

Scenario: Useful yield is measured separately

• WHEN a first-wave cohort creates OpenAI candidates
• THEN genuinely new credentials and their explicit API outcomes SHALL be reported separately from cached-known occurrences

Scenario: Retention decision uses measured value

• WHEN the bounded canary is complete
• THEN each query SHALL be retained, revised, or removed using its distinct credential yield, usable outcomes, and operational error cost rather than fetched count alone