truf-server/openspec/changes/retire-zero-alive-keywords/specs/discovery-keyword-pruning/spec.md

ADDED Requirements

Requirement: Source-specific zero-alive retirement rule

The system SHALL retire an exact source/query pair only when it has at least 1,000 successful completed scans, zero historically alive linked credentials, and zero pending candidate checks at the reviewed evidence cutoff.

Scenario: Historical alive result preserves the pair

• WHEN any credential linked through a candidate occurrence for the exact source/query pair has ever produced status_group='alive'
• THEN that source/query pair SHALL remain active regardless of the credential's current status

Scenario: Pending candidate preserves the pair

• WHEN an otherwise zero-alive source/query pair has a pending or leased candidate check
• THEN the pair SHALL remain active until the candidate evidence matures

Scenario: Insufficient scan exposure preserves the pair

• WHEN a zero-alive mature pair has fewer than 1,000 successful completed scans
• THEN the pair SHALL remain active

Scenario: Exact pair qualifies for retirement

• WHEN the exact pair has at least 1,000 successful completed scans, zero historical alive credentials, and zero pending or leased candidates
• THEN the pair SHALL qualify for reviewed retirement without affecting the same query in another source

Requirement: Rejected query evidence remains visible

Canonical configuration SHALL retain a machine-checkable rejection record for every retired source/query pair while keeping rejected pairs absent from active query rotation.

Scenario: Rejected pair is loaded

• WHEN canonical query policy is validated
• THEN every rejected entry SHALL identify its exact source, query, status rejected_zero_alive, evidence cutoff, successful scans, findings, unique credentials, pending candidates, historical alive credentials, and reviewed queue count

Scenario: Active and rejected policy overlaps

• WHEN the same exact source/query pair appears in both active rotation and rejected evidence
• THEN policy validation SHALL fail closed

Scenario: Rejection evidence is incomplete

• WHEN a rejected entry omits or weakens the approved zero-alive evidence fields
• THEN policy validation SHALL fail closed

MODIFIED Requirements

Requirement: Operational and historical authority is preserved

Keyword retirement SHALL stop future discovery and SHALL permit existing unfenced pending/deferred targets attributed to retired exact source/query pairs to enter an audited, reversible cold state without deleting or rewriting historical authority.

Scenario: Dedicated source sentinels remain

• WHEN archive, gist, CI-log, or HuggingFace source rotations are loaded
• THEN their operational sentinel queries SHALL remain configured and SHALL NOT be evaluated as interchangeable discovery keywords

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 is preserved but held

• WHEN a previously admitted unfenced target is attributed to a retired exact source/query pair and selected by reviewed policy
• THEN its queue row SHALL remain present with all attribution, retry, deduplication, scan, reservation, and coverage history preserved while its status becomes unclaimable cold

Scenario: Historical records remain unchanged

• WHEN a zero-alive policy cold transition is applied
• THEN existing target scans, findings, candidates, credentials, keycheck results, completed queue rows, and coverage records SHALL NOT be deleted or rewritten