truf-server/openspec/changes/prune-low-yield-discovery-keywords/specs/discovery-keyword-pruning/spec.md

ADDED Requirements

Requirement: All-provider strict-yield pruning rule

The system SHALL retire a discovery term only when canonical lineage shows zero historical strict-usable credential linkage for every provider and the term has meaningful measured exposure.

Scenario: Any strict-usable linkage preserves a term

• WHEN any credential linked to a configured term has ever met the canonical usable_llm rule
• THEN that term SHALL remain in every configured source rotation

Scenario: Credential exposure qualifies a zero-yield term

• WHEN a term has zero strict-usable linkage and at least 30 linked credential observations
• THEN the term SHALL qualify for retirement

Scenario: Scanner-cost exposure qualifies a zero-yield term

• WHEN a term has zero strict-usable linkage, at least 200 scan events, and at least 20 cumulative scanner-hours
• THEN the term SHALL qualify for retirement

Scenario: Low-exposure zero-yield term remains a canary

• WHEN a zero-yield term satisfies neither exposure condition
• THEN it SHALL remain configured until more evidence is available

Requirement: Approved global retirement cohort

The system SHALL omit the approved 38-term zero-yield cohort from every source rotation where each exact term was configured.

Scenario: Shared broad-source cohort is removed

• WHEN GitHub, GitLab, DockerHub, npm, PyPI, or package-git loads its query rotation
• THEN it SHALL omit autonomous, benchmarks, claw, code-assistant, codegen, dspy, embedding, embeddings, eval, evals, gateway, grok, haystack, inference, inference-api, knowledge, llamaindex, model, model-router, models, ollama, orchestration, prompts, replicate, rerank, reranker, retrieval, router, tokenizer, tool-use, vector, and vllm

Scenario: Cross-source zero-yield terms are removed

• WHEN an affected rotation is loaded
• THEN chatgpt, gpt, and moonshot SHALL be absent from GitHub, GitLab, DockerHub, npm, PyPI, package-git, and Postman, and openai SHALL be absent from GitHub, GitLab, DockerHub, and Postman

Scenario: Zero-yield Postman signatures are removed

• WHEN Postman loads its query rotation
• THEN dashscope-intl.aliyuncs.com and generativelanguage.googleapis.com SHALL be absent

Scenario: Post-prune list sizes are deterministic

• WHEN canonical configuration is loaded
• THEN query counts SHALL be GitHub 64, GitLab 46, DockerHub 46, npm 43, PyPI 43, package-git 43, and Postman 33

Requirement: Operational and historical authority is preserved

Keyword retirement SHALL stop future discovery for the retired terms without deleting or rewriting source state, target queues, scans, findings, credentials, or results.

Scenario: Dedicated source sentinels remain

• WHEN archive and gist source rotations are loaded
• THEN gharchive, gharchive-files, and gists SHALL remain as their sole configured query tokens

Scenario: Persisted rotation index remains valid

• WHEN an existing query index exceeds a shortened query list
• THEN normal modulo-based rotation SHALL select a valid configured query without a state-file edit

Scenario: Existing backlog remains intact

• WHEN the pruned configuration is deployed
• THEN previously admitted targets and all historical attribution records SHALL remain unchanged

Requirement: Retired query overrides are removed

The canonical configuration SHALL NOT retain a query override for a retired query.

Scenario: Literal OpenAI overrides are absent

• WHEN GitHub, GitLab, and DockerHub configuration is loaded
• THEN each source SHALL omit the openai query override while preserving overrides for retained bounded queries