truf-server/openspec/changes/cold-policy-stale-backlog/specs/target-queue-policy-holds/spec.md

ADDED Requirements

Requirement: Cold queue rows are not claimable

The system SHALL represent policy-held target work with target_queue.status='cold', and no scanner, legacy queue consumer, or Docker resolver SHALL claim a cold row.

Scenario: Scanner checks active backlog

• WHEN a queue row has status cold
• THEN the row SHALL be excluded from pending, due-deferred, retry, and periodic resolver admission

Scenario: Worker completes ordinary work

• WHEN a scan result is ingested
• THEN its queue disposition SHALL remain limited to ordinary lifecycle outcomes and SHALL NOT create a cold status

Requirement: Policy holds are exact and audited

The system SHALL transition queue rows into or out of cold state only through a reviewed, hash-fenced, append-only policy event under stopped-source lifecycle authority.

Scenario: Eligible stale row is held

• WHEN an exact manifest entry still matches an unfenced pending or deferred row whose source query is absent from canonical policy
• THEN the system SHALL atomically record the audit event and change only the row status and update timestamp to cold

Scenario: Selected row has an active fence

• WHEN a selected row has a queue lease, resolver lease, current claim, active result reservation, or submitted content lease
• THEN the policy apply SHALL fail closed without partially applying the manifest

Scenario: Exact apply is repeated

• WHEN the same reviewed manifest is applied again after a successful transition
• THEN the system SHALL report an idempotent duplicate without creating a second state transition

Requirement: Cold state is explicitly reversible

The system SHALL retain the exact prior queue status in policy audit history and SHALL require a reviewed reactivation manifest to restore a cold row.

Scenario: Cold row is rediscovered normally

• WHEN enqueue, synchronization, rediscovery, retry, or completion logic encounters an existing cold row
• THEN the row SHALL remain cold and its historical attribution SHALL remain unchanged

Scenario: Reviewed cold event is reactivated

• WHEN an exact reactivation manifest references an unreversed cold event and all row fences still match
• THEN the system SHALL restore the audited prior pending or deferred status and append a linked reactivation event

Requirement: Stale-query selection follows canonical policy

The system SHALL evaluate query staleness using case-sensitive exact source, platform, and query policy derived from canonical configuration.

Scenario: Configured query remains active

• WHEN a queue row's exact source/platform/query triple remains configured
• THEN automatic stale-policy planning SHALL NOT select the row

Scenario: Attribution cannot be classified safely

• WHEN query attribution is null, blank, operational, non-rotation, or belongs to an unknown source/platform pair
• THEN automatic planning SHALL skip and report the row rather than inferring retirement

Scenario: Initial Docker stale cohort is planned

• WHEN DockerHub policy planning is scoped to platform docker
• THEN it SHALL include eligible pending/deferred resolver anchors and digest rows attributed to removed exact queries and SHALL expose only aggregate counts plus non-sensitive manifest fields

Requirement: Docker resolvers honor current query policy

The system SHALL prevent completed or retryable Docker resolver anchors attributed to retired non-null queries from generating new digest queue rows.

Scenario: Periodic stale anchor becomes due

• WHEN a completed Docker resolver anchor is due but its exact query is not in the configured DockerHub allowlist
• THEN resolver admission SHALL leave the anchor unclaimed

Scenario: Configured anchor becomes due

• WHEN a Docker resolver anchor's exact query remains configured and all ordinary claim fences pass
• THEN resolver admission SHALL preserve the existing retry and periodic behavior

Requirement: Source pause preserves backlog authority

Pausing a source SHALL remove its worker from the active core without deleting or rewriting that source's queue or historical records.

Scenario: GitHub Actions is paused

• WHEN canonical runtime configuration is loaded after this change
• THEN GitHub Actions SHALL be absent from the supervisor core and disabled at both supervisor-source and source configuration layers while its configured query and persisted backlog remain intact

Requirement: Cold work is separately observable

Operational queue summaries SHALL report cold rows separately and SHALL NOT include them in active pending or deferred backlog counts.

Scenario: Queue state is summarized

• WHEN an operator inspects canonical target queue status
• THEN the summary SHALL expose a distinct cold count without representing those rows as retryable or claimable work