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

ADDED Requirements

Requirement: External GitLab scan lifecycle ownership

The system SHALL bypass TruffleHog's embedded overseer for configured GitLab repository scans while retaining external supervision, scan-slot leases, timeout enforcement, output bounds, and Windows Job containment.

Scenario: GitLab command construction

• WHEN the GitLab source constructs a TruffleHog Git command with external lifecycle enabled
• THEN the command includes both --local-dev and --no-update

Scenario: Non-GitLab command construction

• WHEN another source constructs a TruffleHog Git command without external lifecycle enabled
• THEN the command does not gain --local-dev or GitLab completion policy

Requirement: Explicit GitLab scan completion

The system SHALL require both exit code 0 and the exact finished scanning marker before treating an externally managed GitLab TruffleHog process as complete.

Scenario: Normal GitLab completion

• WHEN the process exits code 0 after emitting finished scanning
• THEN completion metadata is recorded and no lifecycle error is added

Scenario: Missing GitLab completion marker

• WHEN the process exits without emitting finished scanning
• THEN the result is classified as retryable command_incomplete and is not treated as complete

Scenario: Nonzero exit after completion marker

• WHEN the process emits finished scanning and exits nonzero without a more specific fatal diagnostic
• THEN the result is classified as retryable wrapper_exit

Requirement: Bounded retry for incomplete GitLab scans

The system SHALL route incomplete GitLab lifecycle outcomes through the existing bounded target retry policy.

Scenario: Retry remains available

• WHEN an incomplete GitLab scan 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 GitLab scan occurs at the maximum target attempt
• THEN the queue records a terminal failed target without an unbounded loop

Requirement: Partial GitLab finding preservation

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

Scenario: Findings precede incomplete exit

• WHEN TruffleHog emits findings and then exits before completion is confirmed
• THEN those findings remain durable while the target receives retryable incomplete disposition

Requirement: Controlled GitLab lifecycle rollout

The system SHALL enable and replay GitLab lifecycle behavior only through bounded, observable stages.

Scenario: Canary has not passed

• WHEN the GitLab lifecycle canary has not reached its observation threshold
• THEN historical terminal failures are not mass-requeued

Scenario: Canary has passed

• WHEN the canary is healthy and a bounded exact-signature batch is selected
• THEN only targets in that batch are returned to the pending queue