State machine & labels¶

The Finding custom resource is the authoritative state machine for one security finding. api/v1alpha1 owns the phase taxonomy and the legal transition table (transitions.go), every phase edge has exactly one writer component, and SetPhase refuses illegal moves — a controller cannot accidentally invent a transition. Labels on the tracking issue are a one-way projection of this state for humans and issue searches; nothing ever parses them back.

Phases¶

Finding.status.phase walks the happy path Opened → Enhanced → Investigating → Queued → Remediating → InReview → Remediated, with AwaitingApproval before Queued when a human must approve, and Dismissed / HandedOff / Failed as the other terminal phases. Queued is a real phase — remediation runs in priority order with bounded concurrency, so findings observably wait for a slot.

Terminal entry sets status.completedAt, which starts the finding TTL (default 14 days — the FindingRollup objects retain the statistics after deletion). Dismissed and HandedOff are revivable terminals: reopening the issue moves Dismissed → HandedOff, and a /approve comment moves HandedOff → Queued, clearing completedAt and cancelling the TTL.

Legal transitions¶

Self-transitions are always legal no-ops; everything else is refused by SetPhase. Per-edge ownership means no phase edge has two writers.

stateDiagram-v2
    [*] --> Opened : integration
    Opened --> Enhanced : context
    Enhanced --> Investigating : investigation (lease)
    Investigating --> Enhanced : retry revert
    Investigating --> Queued : verdict remediate, confident
    Investigating --> AwaitingApproval : low confidence / breaking hold
    Investigating --> Dismissed : verdict ignore
    Investigating --> HandedOff : verdict manual
    Investigating --> Failed : attempts exhausted
    AwaitingApproval --> Queued : /approve
    Queued --> Remediating : scheduler grant
    Remediating --> Queued : retry re-queue
    Remediating --> InReview : branch pushed, PR open
    Remediating --> Failed : attempts exhausted
    InReview --> Remediated : PR merged
    InReview --> Failed : PR closed unmerged
    Dismissed --> HandedOff : issue reopened
    HandedOff --> Queued : /approve revival
    Remediated --> [*]
    Failed --> [*]

Every non-terminal phase additionally has an edge to HandedOff, written by the integration-controller when a human closes the tracking issue — a person can always pull a finding out of the machine's hands.

Conditions¶

Facts that are not phases ride on status.conditions. Accumulation is the important one: alerts keep folding into a Finding while enhancement runs, so the window close cannot be a phase.

Findings parked with ForgeResolved: False are re-queued automatically when Forge resources change. A finding can also be paused by a human: spec.suspend: true halts pipeline progress until cleared.

Watching it¶

kubectl get patchy -n patchy                        # every patchy kind, one shot
kubectl get findings -w                             # phase, severity, priority, verdict, live
kubectl get investigations                          # per-attempt analysis children (short name: inv)
kubectl get remediations                            # per-attempt remediation children (rem)
kubectl get findingrollups                          # the all-time statistics (fr)
kubectl describe finding <name>                     # conditions, phase log, enrichments, attempts

Machine metadata that used to ride on issue labels — alert numbers, accumulation state, confidence, budgets, attempt counts, per-stage token/cost accounting — lives on these resources, nowhere else.

The projected labels¶

The tracking-issue projection stamps a trimmed, human-facing vocabulary, rendered from the Finding by the integration-controller (internal/labels). Every label is <key>: <value>, truncated to GitHub's 50-character cap; the multi-valued advisory key emits one label per identifier. Patchy only touches labels in the security- namespace, ignores foreign or malformed security-* labels, and does not manage label colors or descriptions.

That is the whole list — the projection is deliberately small. Labels exist for issue searches and human triage; the CR is the state, so no machine or usage labels exist on issues anymore.