# ADR 009: Immutable observed evidence and completion candidates

- HTML version: https://robbiepalmer.me/projects/work-graph/adrs/009-observed-evidence-before-automatic-release
- Project: Work Graph (https://robbiepalmer.me/projects/work-graph.md)
- Status: Accepted
- Date: 2026-09-22
- Initiatives: Semi-autonomous Software Development (https://robbiepalmer.me/initiatives/semi-autonomous-software-development.md)

## Context

[PDR 004](/projects/work-graph/pdrs/004-treat-delivery-observations-as-evidence)
keeps delivery observations separate from the decision to complete work.
[ADR 008](/projects/work-graph/adrs/008-github-delivery-evidence-ingestion)
adds repeated and potentially out-of-order events from a GitHub observer. The
coordination store must retain those facts, correlate them to work, and project
completion candidacy without weakening lease fencing.

The original release request carried merge and deployment URLs directly. An
observed evidence model must preserve equivalent human-readable provenance
while adding stable external identity and policy evaluation.

## Decision

Store external observations as immutable evidence records. Each record keeps
the provider, external identity, repository, commit SHA, evidence kind, state,
source URL, provider time, ingestion time, and correlation provenance.
Preserve every accepted observation while projecting the latest state needed
by queue and context reads.

Correlate evidence through explicit implementation pull-request links and an
exact commit chain. Preserve the pull-request head, merge commit, CI commit, and
deployed commit. Do not infer identity from branch names, titles,
work-item-like text, or temporal proximity.

Evidence ingestion may refresh a pull-request projection, append evidence, and
recompute a completion candidate. It cannot release or cancel the item, end or
acquire a lease, satisfy dependencies, or add unrelated blocking state.

Evaluate completion candidacy from versioned owner policy. The initial
projection requires all implementation pull requests selected by the policy to
be merged, required CI to pass for the accepted revisions, an allowed
production environment to report a successful deployment of the resulting
commit, no unfinished children, and no unresolved blocking attention. Store
the evidence identities and policy revision behind the result.

Change worker-initiated release to reference stored evidence while retaining a
human-readable snapshot in the immutable lifecycle event. A future automatic
release must be a separate domain operation with its own system actor. It must
atomically recheck evidence and work-item invariants and follow PDR 004's rule
for active leases.

## Consequences

Duplicate or out-of-order provider events do not repeat lifecycle transitions.
The system can explain a completion candidate and revise the current
projection without rewriting the facts that produced it.

The database and API gain evidence identities, projections, policy revisions,
and correlation data. A successful deployment can leave an item open because
the candidate projection and work lifecycle remain separate.

Automatic release cannot reuse the worker endpoint with elevated credentials.
It needs a new atomic operation and an explicit answer for active leases.

## Alternatives considered

### Release from the webhook consumer

Unique delivery IDs make event handling idempotent, but they do not prove the
whole planned outcome. The consumer could also race an active lease or another
required pull request.

### Let deployment workflows call the release endpoint

A workflow knows its own job result but not the complete child, attention,
pull-request, or lease state. Giving workflows worker credentials would spread
lifecycle authority across repositories.

### Keep only mutable snapshots

Overwriting current pull-request and deployment state is compact. It cannot
explain which facts and policy produced a candidate or distinguish late events
from regressions.

## Migration note

The 1 November 2026 PDR migration moved the completion policy into PDR 004.
This ADR keeps the immutable evidence, correlation, candidacy projection, and
release-operation architecture. No evidence or lifecycle rule changed.

---

Markdown index of this site: https://robbiepalmer.me/llms.txt