clawfort/openspec/specs/queued-image-refetch-with-backoff/spec.md

Purpose

Canonical specification for queued-image-refetch-with-backoff requirements synced from OpenSpec change deltas.

Requirements

Requirement: Latest-30 queue construction

The refetch-images command SHALL enqueue up to the latest 30 news items for processing in batch mode and support targeted single-article mode when permalink targeting is provided.

Scenario: Queue population

• WHEN refetch-images is started without a permalink target
• THEN the command loads recent news items
• AND enqueues at most 30 items ordered from newest to oldest

Scenario: Targeted permalink mode

• WHEN refetch-images is started with a valid permalink target
• THEN the command enqueues only the resolved article
• AND bypasses latest-30 queue expansion

Requirement: Sequential processing

The image refetch queue SHALL be processed one item at a time.

Scenario: Single-item worker behavior

• WHEN queue processing runs
• THEN only one queued item is processed concurrently
• AND next item starts only after current item completes/fails

Requirement: Exponential backoff on transient failures

The queue processor SHALL retry transient image-provider failures using exponential backoff.

Scenario: Rate-limited provider response

• WHEN provider call returns rate-limit or transient error
• THEN command retries with exponential delay between attempts
• AND stops retrying after configured max attempts

Requirement: Progress and completion reporting

The command SHALL emit operator-readable progress and final summary output.

Scenario: Queue progress output

• WHEN queue processing is in progress
• THEN the command prints per-item progress (processed/succeeded/failed)
• AND prints final totals on completion