[Aparnap2]

What changed

Documentation-only, plus two comment-only source edits. No lifecycle behaviour changed.

File	Change
docs/adr/011-claim-expiry-contract.md	NEW — the ratification that never existed
docs/specs/09_DECISION_LOG.md	+19 — the decision-log entry (house pattern)
docs/specs/06_PROGRESS.md	+3/−2 — completed bullet; Last updated → 2026-10-21; live Current base pointer → main@254c4b9
docs/AGENT_OPERATING_CONTRACT.md	item 5 now lists EXPIRED in the transition chain
docs/KNOWN_LIMITATIONS.md	+1 — new row KL-18
apps/api/internal/claims/statemachine.go	comment-only — header no longer claims a parity that did not exist
packages/domain/state_machine.py	docstring-only — states it is superseded for lifecycle semantics and is not a mirror

Base main@254c4b92dddf59a758a133c1edbf7618dcc011b2 · commit bb6421a · branch docs/adr-011-claim-expiry-contract. ADR-011 avoids the pending ADR-010 in PR #161.

The gap this closes

EXPIRED was implemented, wired, tested and deployed — but no document ever ratified it. Its semantics were attested only by code comments citing a Linear id this repo does not record, while two things made that dangerous:

• statemachine.go:3-7 described itself as "the Go port of the Python specification in packages/domain/state_machine.py" — a specification with 13 statuses and no EXPIRED. The file claimed parity it did not have.
• fixtures/golden_cases.json — the cross-language contract designated by ADR-001 — has nine cases and none covers EXPIRED. The one status on which the two implementations disagree was exactly the status the contract did not cover.

What ADR-011 records

EXPIRED is an approved state of the authoritative Go lifecycle (S5/APA-26):

• Terminal-for-round — no out-edges; terminality is enforced by absence from claims.Transitions.
• Exactly two inbound edges — HITL → EXPIRED and ACTION_PENDING → EXPIRED (HITL-wait timeout).
• Timeout expiry can never decide a claim — post-expiry APPROVE/REJECT/ESCALATE/HOLD are illegal, and APPROVE from HITL was already illegal because HITL has no VERIFIED edge.
• Re-drive is a new round, never an implicit edge.
• The Go edge is authoritative; the Python artefact is superseded for lifecycle semantics and is not a mirror.

Alternatives considered and rejected in the ADR: resyncing the Python graph to a true 14-status mirror (contradicts ADR-001's demotion and keeps a second lifecycle alive); removing the Go edges (the deployed GCW workflow posts EXPIRE on the HITL-timeout path — that branch would have no business-state outcome); leaving it undocumented (the status quo that caused this).

Evidence the implementation already behaves this way

Nothing in the implementation changed; these already existed and still pass:

• apps/api/internal/claims/claim.go:117-121 — the status and its stated intent.
• apps/api/internal/claims/statemachine.go:53-60 — the only two inbound edges.
• apps/api/internal/handlers/decision.go:95-100 — EXPIRE wired into the HMAC decision endpoint with the same HMAC, version and idempotency controls as every other decision.
• workflows/claim-investigation.yaml — the deployed workflow already posts EXPIRE (expire / expire_escalated).
• apps/api/internal/claims/expiry_red_test.go — the S5/APA-26 contract.
• apps/api/internal/handlers/decision_expiry_test.go — 4 PostgreSQL-gated tests.
• apps/api/internal/repository/postgres/hitl_expiry_test.go — TestHITL_ExpiredExcludedFromPending.

Verification

gofmt -l .                     -> clean
go vet ./... / go build ./...  -> clean
go test ./... -count=1         -> 41 packages ok, 0 failures   (real PostgreSQL; claimops_app, rolsuper=f, rolbypassrls=f)
go test -race -count=1 ./...   -> clean, no data races
uv run pytest tests/unit -q    -> 67 passed
uv run ruff check .            -> All checks passed!
uv run mypy packages scripts/ci -> Success: no issues found in 11 source files

The expiry behaviour was re-asserted unchanged after the edit: TestExpiry_HITLToExpired_Legal, TestExpiry_ActionPendingToExpired_Legal, TestExpiry_NoOutEdges, TestExpiry_ApproveFromHITL_Illegal, TestDecision_PostExpiryDecisions_Rejected_Live, TestHITL_ExpiredExcludedFromPending — all PASS.

Diff shape proof: git diff on statemachine.go contains only // comment lines; git diff on packages/domain/state_machine.py is a single hunk at line 1 (the docstring). No executable line changed in either file.

Scope notes and deliberate omissions

• Two disclosures. (1) 06_PROGRESS.md's Current base: was a live pointer to main@dffa160; because the file now carries a fact true as of 254c4b9, I updated it rather than leave the file internally inconsistent. This incidentally resolves one of the three W17 pointers; 09_DECISION_LOG.md:490 and 10_PHASE3_E2E_QUALIFICATION.md:5 remain for that separate pass. (2) packages/domain/state_machine.py is touched — docstring only — because its silence is precisely what caused the misattribution this ADR resolves.
• Deliberately not bundled: the statemachine.go comment describing golden case 08 as witnessing "stale-version wins over legality" is also inaccurate (case 08's edge is legal, so the case witnesses only that a stale version is rejected). That is a separate focused change.
• Still open, not closed here: the cross-language fixture has no EXPIRED case; the canonical audit-action vocabulary (Go emits claim.transitioned, the fixture says claim.status.transition); and the Go-vs-Python malformed-claim rule. These are tracked separately and are not resolved by this ADR.
• docs/KNOWN_LIMITATIONS.md gains KL-18 registering the narrower Python graph rather than silently reconciling it.

Status

Documentation and comments only. Not authorized to merge — opened as a draft for review. No branch-protection change, no deployment. Release status NOT QUALIFIED; this closes no release gate.

[coderabbitai]

Important

• 🔍 Trigger review

This repository does not receive automatic reviews because it has fewer than 10 stars.

⚙️ Run configuration

• Configuration used: defaults
• Review profile: CHILL
• Plan: Advanced
• Run ID: cfe7f70c-09de-4e6d-afa9-1c675b87e953

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}