truf-server/openspec/changes/improve-core-scan-coverage/specs/git-ref-delta-scanning/spec.md

ADDED Requirements

Requirement: Git scans are bound to an exact revision

The system SHALL resolve a normalized ref and exact commit SHA for each claimed GitHub or GitLab repository before invoking TruffleHog and SHALL bind that immutable plan to the active reservation.

Scenario: Repository search supplies no ref hint

• WHEN a claimed repository came from metadata search without an exact ref
• THEN the system resolves the provider's current default branch and its exact head SHA

Scenario: Discovery supplies an exact ref hint

• WHEN an event-backed target includes a valid branch ref
• THEN the system resolves and binds that specific ref instead of substituting the default branch

Scenario: Revision lookup fails

• WHEN the provider API cannot return a valid ref and commit SHA
• THEN the claim receives a bounded retryable source failure and no exact coverage state advances

Requirement: Git updates scan every newly introduced commit

The system SHALL scan the exact claimed head after the last successfully covered head for the same ref and SHALL NOT apply rolling age or maximum-depth limits to that incremental range.

Scenario: Same ref advances

• WHEN ref R was successfully covered at commit A and now resolves to descendant commit D
• THEN the scan is pinned to D with A as its boundary and includes commits introduced between them

Scenario: Secret is added and then deleted in the delta

• WHEN one newly introduced commit adds a secret and a later newly introduced commit removes it
• THEN both commits remain in scan scope even though the final filesystem snapshot is clean

Scenario: Head is unchanged

• WHEN the resolved head equals the successfully covered head for the same ref
• THEN the system records an exact no-op without launching a redundant repository scan

Requirement: Git baseline and discontinuity handling remain pinned

The system SHALL use a pinned bounded baseline for a first-seen ref or an unusable incremental base and SHALL identify that mode without claiming unbounded historical coverage.

Scenario: Ref has no covered head

• WHEN an exact ref is claimed without prior successful coverage
• THEN the system scans its pinned head using the configured baseline depth bound and establishes that head as the future delta boundary on success

Scenario: Covered base is unavailable

• WHEN force push, ref recreation, or remote history removal makes the covered SHA unusable
• THEN the system falls back to a pinned bounded baseline and records the continuity reset

Requirement: Git coverage advances only after successful fenced work

The system SHALL update a queue row's covered ref and head only when successful ingestion applies a matching immutable reservation plan.

Scenario: Exact scan succeeds

• WHEN a pinned baseline or delta result is ingested with queue disposition done and its plan matches the active reservation
• THEN the queue's covered ref and head advance to the claimed head

Scenario: Exact scan fails or is deferred

• WHEN execution fails, times out, loses its fence, or receives a deferred disposition
• THEN the previously covered ref and head remain unchanged

Scenario: Remote advances during a scan

• WHEN a newer commit appears after the worker binds its immutable head
• THEN successful completion advances coverage only to the bound head and leaves the newer update eligible for later discovery

Requirement: Exact Git scope is observable

The system SHALL durably record the executed ref, head, base, scan mode, baseline bound, and whether immutable execution was preserved.

Scenario: Operator inspects an incremental scan

• WHEN an exact delta result is committed
• THEN its normalized scan metadata identifies the covered range without exposing source credentials

Scenario: Metadata discovery observes repository-level activity

• WHEN no branch-specific event exists
• THEN observability identifies the provider-resolved default-branch scope rather than implying coverage of every repository ref