truf-server/openspec/changes/stabilize-dockerhub-trufflehog-lifecycle/specs/docker-scan-lifecycle/spec.md

ADDED Requirements

Requirement: External Docker scan lifecycle ownership

The system SHALL bypass TruffleHog's embedded overseer for DockerHub image scans while retaining the existing external supervisor, scan-slot lease, timeout, output bounds, and Windows Job containment.

Scenario: Docker command construction

• WHEN the system constructs a TruffleHog command for a DockerHub image
• THEN the command includes both --local-dev and --no-update

Scenario: Non-Docker command construction

• WHEN the system constructs a TruffleHog command for a non-Docker source
• THEN this Docker-only capability does not add --local-dev

Requirement: Explicit Docker scan completion

The system SHALL record whether TruffleHog emitted the exact normal completion message finished scanning, and SHALL require both that marker and exit code 0 before treating process execution as complete.

Scenario: Normal completion

• WHEN a Docker TruffleHog process exits with code 0 after emitting finished scanning
• THEN diagnostic metadata records completed execution and no lifecycle error is added

Scenario: Missing completion marker

• WHEN a Docker TruffleHog process exits without emitting finished scanning
• THEN the result is classified as an incomplete retryable run and is not treated as clean or done

Scenario: Nonzero exit after completion marker

• WHEN a Docker TruffleHog process emits finished scanning but exits nonzero without a more specific diagnostic
• THEN the result is classified as a retryable wrapper exit rather than successful execution

Requirement: Bounded retry for incomplete Docker runs

The system SHALL route incomplete Docker lifecycle failures through the existing bounded target retry policy and SHALL preserve the terminal attempt limit.

Scenario: Retry remains available

• WHEN an incomplete Docker run occurs before the configured maximum target attempt
• THEN the queue defers the target using the configured retry delay

Scenario: Attempt limit is reached

• WHEN an incomplete Docker run occurs at the configured maximum target attempt
• THEN the queue records a terminal failed target and does not create an unbounded retry loop

Requirement: Partial finding preservation

The system SHALL retain findings emitted before an incomplete Docker process exit without representing the target as fully scanned.

Scenario: Findings precede incomplete exit

• WHEN TruffleHog emits one or more findings and then exits before complete execution is confirmed
• THEN those findings remain durable while the target receives retryable incomplete disposition

Requirement: Bounded Docker internal parallelism

The system SHALL pass source-configured internal concurrency to Docker TruffleHog commands while retaining the existing source worker and Windows Job limits.

Scenario: Docker canary resource settings

• WHEN the configured DockerHub source starts an image scan
• THEN TruffleHog runs with internal concurrency 4 and a target timeout of 600 seconds

Requirement: Nonfatal detector context timeout

The system SHALL retain the exact diagnostic a detector ignored the context timeout as degraded detector coverage rather than a fatal image-scan error.

Scenario: Completed scan with detector timeout

• WHEN a Docker scan emits the detector context-timeout diagnostic, emits finished scanning, and exits with code 0
• THEN the target result contains a detector_timeout warning and no lifecycle error

Scenario: Other timeout diagnostic

• WHEN a Docker scan emits a different timeout diagnostic
• THEN the existing retryable timeout error policy remains in effect

Requirement: Controlled historical replay

The system SHALL replay historical Docker failures matching the exact incomplete-exit signature only in bounded batches after lifecycle canary criteria pass.

Scenario: Canary has not passed

• WHEN lifecycle health has not met the defined canary criteria
• THEN historical terminal failures are not mass-requeued

Scenario: Canary has passed

• WHEN lifecycle health meets the defined canary criteria and a bounded replay batch is selected
• THEN only exact-signature Docker failures in that batch are returned to the pending queue