# PR lifecycle contract

Canonical owner for **PR state vocabulary** rules for the GitHub/Copilot workflow family
in `dev-loops` — the deterministic family-local PR lifecycle contract.

## Purpose

This contract freezes the end-to-end lifecycle semantics for one PR as it moves through:

```text
draft-stage local gate -> draft remediation -> ready-for-review
-> explicit Copilot request/wait -> Copilot remediation / reply-resolve / re-review
-> final local pre-approval gate -> human approval / merge waits
```

This document owns the **family-local lifecycle semantics** only.
It does not redefine helper transport mechanics, reviewer-loop internals, conductor routing, or merge policy.

## Relationship to adjacent contracts

| Surface | Relationship |
|---|---|
| [Copilot Loop State Graph](./copilot-loop-state-graph.md) | Copilot-family inner-loop state machine consumed by this lifecycle |
| [Reviewer Loop State Graph](./reviewer-loop-state-graph.md) | Reviewer-side review production / submission boundary consumed by this lifecycle |
| [Gate Review Comment Contract](./gate-review-comment-contract.md) | Visible evidence contract for `draft_gate` and `pre_approval_gate` |
| [Conductor Routing Contract](./conductor-routing-contract.md) | Downstream consumer of family-local lifecycle outcomes |
| [Merge preconditions](merge-preconditions.md) | Merge gate after the lifecycle waits |

## Core rules

<!-- rule: LIFECYCLE-ONE-STATE -->
`LIFECYCLE-ONE-STATE`: Exactly **one current lifecycle state** MUST apply at a time.

- The lifecycle MUST fail closed when required evidence is missing, stale, ambiguous, or unparsable (see [Fail-closed rules](#fail-closed-rules), `LIFECYCLE-FAIL-CLOSED`).
- Every gate-crossing decision is for the **current PR head SHA**.
- Draft existence alone is **not** draft-gate readiness.
- A draft PR MUST clear the draft-stage gate for the current head before becoming ready and requesting Copilot. Once non-draft, the transition record remains valid across head changes; requests/re-requests do not require a new draft gate.
- Ready -> draft resets the lifecycle back into draft-stage gating.
- A merge-blocking marker in the PR **title** blocks the draft -> ready transition and, for non-draft PRs, blocks entry to the pre-approval gate and final approval (`title_marker_blocked`). Markers are permitted only while the PR remains draft. [Merge preconditions](merge-preconditions.md#title-markers) owns which constructions count.
- Human approval / merge are explicit external waits, not hidden remediation states.

<!-- rule: LIFECYCLE-CHANGELOG-COMPLETENESS -->
`LIFECYCLE-CHANGELOG-COMPLETENESS`: A PR classified as notable — a conventional-commit `feat`/`fix` subject, or a diff that touches code (per the shared diff-file classifier, `classifyFile()` from `@dev-loops/core/analysis/diff-analyzer`) — MUST record a changelog note (issues #1864/#2293) when the repository opts in with `changelog.required: true` in `.devloops` (this repository's `.devloops` is the reference example). The key is read only from the `.devloops` family file; a value in `.pi/dev-loop/defaults.*` has no effect. Without that setting the rule is skipped. Only `create-pr` and `test:docs` print the notice `changelog completeness check skipped: changelog.required is not set (LIFECYCLE-CHANGELOG-COMPLETENESS)`; the pre-push-delta `--result` path skips silently. File presence such as `changes/README.md` never enables it, and a non-boolean value fails config load. `create-pr` and the pre-push-delta `--result` path read the setting from the committed HEAD config file (`.devloops`, `.devloops.yaml`, `.devloops.yml` or `.devloops.json`, in loader order), so an uncommitted edit has no effect; `test:docs` reads the working tree. The subject input is the PR title when a PR exists (`DEVLOOPS_PR_TITLE`, set by CI and by `gate resolve-validation`; a conventional title is then the only subject input), and the commit range otherwise (unset, empty, or non-conventional title). The code-file rule applies in every case. The canonical way is a **changeset fragment**: a NEW, uniquely named `changes/<slug>.md` file (see `changes/README.md`), so concurrent PRs do not conflict on `CHANGELOG.md`. A list item under `## Unreleased` in `CHANGELOG.md` still satisfies the requirement; that body must use the fragment line format (only `- ` entries and `### Added|Changed|Fixed` headings). `scripts/docs/validate-changelog-completeness.mjs`, wired into `test:docs` (whose CI leg fetches the base branch on pull requests), fails closed on a notable PR that adds neither a fragment nor an Unreleased item (`changes/README.md` is not a fragment). A PR with no `feat`/`fix` subject AND no code-file diff (docs/config/test/ci-only per `classifyFile()`) is exempt; a chore-subject PR that touches code is NOT. With no resolvable base ref (shallow local checkout, no origin), the local check degrades to a notice. At release, `scripts/release/bump-version.mjs` assembles pending fragments into `## Unreleased` (via `scripts/release/assemble-changelog-fragments.mjs`) and removes them; the release-time empty-section guard (`scripts/release/extract-changelog-section.mjs`) is the second line of defense.

Before PR creation, `create-pr` validates the selected base as a literal branch name, refusing options, refspecs and revision syntax before any fetch while retaining support for valid branch names. It then fetches only `origin <base>` and refuses a fetch failure with `base_fetch_failed_before_pr`. After its size check, when `origin/<base>` resolves and the selected head commit equals checkout `HEAD`, it runs changelog completeness against that base with the supplied PR title. Failure refuses with `changelog_incomplete_before_pr`, naming the comparison SHA; no override flag exists, and the opt-in setting is the only switch. An unresolved origin base or a different selected head skips this working-tree check. In pre-push-delta `--result` mode, a cumulative baseline-to-HEAD diff touching `changes/` runs the same validator with default base resolution before writing the gate-delta record. A refusal writes the sealed record with one medium finding that names `LIFECYCLE-CHANGELOG-COMPLETENESS` and carries the diagnostic, and exits 0 except on the reviewer-only route, where a `locally_clear` prior record is never replaced (`PRE-PUSH-DELTA-EXIT-BOUND` owns the exit behavior). The writer marks each such finding `lifecycle: true`, and only that flag identifies one. When the decision is otherwise locally clear, the outcome becomes `needs_fix` with `nextStep: fix_and_rereview` (`bounded_out` at invocation 3). A decision that is already not clear keeps its outcome and gains the finding. A thrown error (configuration, git, a missing base, a validator crash, or a changelog input that differs from HEAD) is infrastructure: the run exits 2 and no record is written. When the committed `test:docs` script calls `scripts/docs/docs-validators.mjs` (the one list of docs validators that `test:docs` runs), the same `--result` run also runs its link, rule-ownership and decision-record validators and records each refusing validator (for example `ADR-SUPERSEDE-NOT-REWRITE`) as one medium finding by the same route. The validators read the working tree, so the run refuses with `docs_validators_dirty_worktree` (exit 2, no record) while a tracked or untracked non-ignored file differs from HEAD, so the validators judge the reviewed commit ([ADR 0259](https://github.com/mfittko/dev-loops/blob/main/docs/decisions/0259-delta-lifecycle-refusal-is-a-finding.md)); a repository whose `test:docs` does not call the module runs the changelog check only. The delta seam and validators do not fetch.

<!-- rule: LIFECYCLE-NO-PRIVATE-REPO-NAMES -->
`LIFECYCLE-NO-PRIVATE-REPO-NAMES`: Issues, PRs, comments, commit messages and changelog fragments MUST NOT name a private consumer repo or its PR numbers. They say "a consumer repo" or "a consumer soak" instead.

## Two required local gates

Each gate runs an independent review chain (`GATE-EXEC-SEPARATE-CHAINS`); see
[Checkpoint Review Chain Contract](./gate-review-sub-loop-contract.md). Every gate
pass writes a durable disposition ledger (`GATE-EXEC-DISPOSITION-LEDGER`) before the
visible comment defined by [Gate Review Comment Contract](./gate-review-comment-contract.md).

### 1. `draft_gate`

<!-- term: gate:draft_gate --> Applies while the PR is draft.

Purpose:
- decide whether the current draft head is materially reviewable
- decide whether the PR stays draft for more remediation or may leave draft
- when `gates.draft.requireCi=true` (default), require green current-head CI before the draft gate may be entered; when `false`, this draft-only CI prerequisite may be skipped

Boundary note:
- `draft_gate` governs only the draft -> ready-for-review boundary for the reviewed head
- a clean verdict on a fully judged round requires an empty judge act list, and on a round with an unjudged finding requires no finding at a severity in the gate's `blockCleanOnFindingSeverities` (resolved from config via `resolveGateConfig(config, "draft").blockCleanOnFindingSeverities`)
- `gates.draft.requireCi=false` does **not** relax `pre_approval_gate` — that boundary has its own separate `gates.preApproval.requireCi` knob (default `true`). A repo may opt the pre-approval boundary out independently; this does not waive the sanctioned merge wrapper's green-CI precondition in [Merge Preconditions](merge-preconditions.md#required-before-merge).

### 2. `pre_approval_gate`

Applies after Copilot convergence and before final approval / merge claims.

This gate uses review angles resolved from config (`resolveGateAngles(config, "preApproval")`).

Boundary note:
- `pre_approval_gate` governs only final approval readiness for the reviewed head
- CI precondition: `resolveGateConfig(config, "preApproval").requireCi` (default `true`) requires green current-head CI at this gate boundary; `gates.preApproval.requireCi: false` opts this boundary out. Gate readiness is not merge permission: [Merge Preconditions](merge-preconditions.md#required-before-merge) still governs the merge wrapper.
- a clean verdict on a fully judged round requires an empty judge act list, and on a round with an unjudged finding requires no finding at a severity in the gate's `blockCleanOnFindingSeverities` (resolved from config via `resolveGateConfig(config, "preApproval").blockCleanOnFindingSeverities`)
- non-draft PRs do not need *per-head* `draft_gate` evidence to enter the post-draft review / `pre_approval_gate` lifecycle — the one-time draft -> ready transition record still applies; a non-draft PR with no clean `draft_gate` evidence at all fails closed and must reconcile that missing evidence first (see the current-head `draft_gate` evidence bullet under [Fail-closed rules](#fail-closed-rules))

## Lifecycle states

The family-local lifecycle SHOULD be modeled in this vocabulary. These state identifiers are part of the stable contract surface for this lifecycle, even if adjacent helper implementations evolve around them:

| State | Meaning |
|---|---|
| <!-- term: state:draft_local_review_gate --> `draft_local_review_gate` | draft PR is at the local draft-stage gate boundary |
| <!-- term: state:draft_local_remediation --> `draft_local_remediation` | draft-stage findings require more local remediation while the PR remains draft |
| <!-- term: state:ready_state_needs_copilot_request --> `ready_state_needs_copilot_request` | draft gate is clear for the current head; Copilot request is the next legal step |
| `waiting_for_copilot_review` | Copilot request/re-review is observably in progress for the current head |
| <!-- term: state:copilot_feedback_remediation --> `copilot_feedback_remediation` | unresolved Copilot feedback exists; fixes are the next active step |
| <!-- term: state:copilot_reply_resolve_pending --> `copilot_reply_resolve_pending` | fixes were applied, but GitHub thread reply/resolve work still remains |
| <!-- term: state:merge_conflict_resolution --> `merge_conflict_resolution` | current PR head conflicts with base or local reconcile is in progress; resolve conflicts before any further gate progression |
| <!-- term: state:final_local_preapproval_gate --> `final_local_preapproval_gate` | current-head post-Copilot convergence is ready for the final local gate |
| <!-- term: state:final_gate_remediation --> `final_gate_remediation` | Pre-approval gate findings require more remediation after the final gate |
| <!-- term: state:waiting_for_human_pr_approval --> `waiting_for_human_pr_approval` | local gates are satisfied; waiting for explicit human approval |
| <!-- term: state:waiting_for_merge --> `waiting_for_merge` | approval exists; waiting for merge / merge-triggering external action |
| <!-- term: state:terminal_slice_complete --> `terminal_slice_complete` | merged/closed and no further owned step remains |
| <!-- term: state:stopped_needs_user_decision --> `stopped_needs_user_decision` | blocked/ambiguous state requiring explicit human decision |

## Required transitions

At minimum, the lifecycle MUST enforce these transitions:

- `draft_local_review_gate` -> `draft_local_remediation`
  - blocking `draft_gate` findings
- `draft_local_review_gate` -> `ready_state_needs_copilot_request`
  - clean current-head `draft_gate` evidence exists
- `draft_local_review_gate` -> `stopped_needs_user_decision`
  - human decision required
- `draft_local_remediation` -> `draft_local_review_gate`
  - fixes pushed on the draft head
- `ready_state_needs_copilot_request` -> `waiting_for_copilot_review`
  - explicit request/confirm succeeded
- `ready_state_needs_copilot_request` -> `stopped_needs_user_decision`
  - request unavailable or blocked
- `waiting_for_copilot_review` -> `copilot_feedback_remediation`
  - unresolved Copilot feedback exists
- `copilot_feedback_remediation` -> `copilot_reply_resolve_pending`
  - fixes applied but reply/resolve still remains
- `copilot_reply_resolve_pending` -> `ready_state_needs_copilot_request`
  - reply/resolve complete and another Copilot pass is required
- any open non-terminal lifecycle slice -> `merge_conflict_resolution`
  - current-head merge state is conflicted (`DIRTY` / `CONFLICTING`) or local conflict reconciliation is already in progress
- `merge_conflict_resolution` -> normal lifecycle re-entry state
  - only after local conflict resolution produces a new head, validation is rerun for the touched conflict slice, and gate state is re-detected for that new head
- `waiting_for_copilot_review` -> `final_local_preapproval_gate`
  - the current-head request/re-review cycle has settled cleanly with no unresolved feedback and no further Copilot pass is needed
- `final_local_preapproval_gate` -> `final_gate_remediation`
  - pre-approval gate findings require changes
- `final_local_preapproval_gate` -> `waiting_for_human_pr_approval`
  - clean current-head `pre_approval_gate` evidence exists
- `final_gate_remediation` -> `final_local_preapproval_gate`
  - fixes pushed after pre-approval gate findings
- `waiting_for_human_pr_approval` -> `waiting_for_merge`
  - approval arrives
- `waiting_for_human_pr_approval` -> `draft_local_review_gate`
  - PR reset to draft
- `waiting_for_merge` -> `terminal_slice_complete`
  - merged/closed and the PR lifecycle is complete

### Required negative boundaries

- no initial draft-to-ready Copilot handoff before clean current-head `draft_gate` evidence; subsequent non-draft requests retain the transition record
- no direct skip from fix-applied to Copilot re-request while reply/resolve remains incomplete
- no reuse of ready-side or gate evidence after ready -> draft
- <!-- rule: LIFECYCLE-CONFLICT-BLOCKS-PROGRESS --> `LIFECYCLE-CONFLICT-BLOCKS-PROGRESS`: a conflicted PR MUST NOT be treated as `waiting_for_human_pr_approval`, `waiting_for_merge`, or merge-ready, even if older gate comments and CI were previously green
- no implicit fallthrough from approval/merge waits into remediation without a triggering event

## Remediation ownership boundary

The lifecycle MUST keep the next action class explicit:
- draft-stage local findings route to `draft_local_remediation`
- unresolved Copilot feedback routes to `copilot_feedback_remediation`
- fixes applied but unresolved GitHub reply/resolve work remains route to `copilot_reply_resolve_pending`
- pre-approval gate findings route to `final_gate_remediation`
- merge conflicts route to `merge_conflict_resolution` and MUST be reconciled locally on the PR branch before lifecycle re-entry
- human approval / merge remain explicit external waits

Reviewer-loop reminder:
- reviewer-loop semantics end at a review result / submission boundary
- this lifecycle defines what happens after that boundary without absorbing reviewer-loop planning/submission behavior

## Required evidence classes

The lifecycle distinguishes three evidence classes:

1. **observable GitHub state**
   - PR draft/non-draft/merged/closed state
   - current head SHA
   - reviews, review threads, requested reviewers
   - any current-head validation/check freshness only where an adjacent gate/helper already makes a boundary CI-dependent

2. **visible gate evidence on the PR**
   - current-head `draft_gate` evidence when draft-gate clearance is required
   - current-head `pre_approval_gate` evidence when final approval readiness is required

3. **durable disposition ledger** — owned by `GATE-EXEC-DISPOSITION-LEDGER`
   (see [Checkpoint Review Chain Contract](./gate-review-sub-loop-contract.md#disposition-ledger-and-durable-logging))

### Precedence rules

- current observable PR/head state beats stale local memory
- required visible gate evidence beats local-only gate records for crossing a gate boundary
- incomplete or conflicting evidence yields fail-closed blocked/reconcile behavior, not optimistic progression

## Fail-closed rules

<!-- rule: LIFECYCLE-FAIL-CLOSED -->
`LIFECYCLE-FAIL-CLOSED`: The lifecycle MUST stop or reconcile rather than advance when:
- current head SHA cannot be determined
- required current-head `draft_gate` evidence is missing
- required current-head `pre_approval_gate` evidence is missing
- gate evidence exists but gate name, verdict, or reviewed SHA is missing or unparsable
- evidence exists only for an older head SHA
- review-thread capture failed or is incomplete, so unresolved feedback cannot safely be treated as zero
- Copilot request status is failed, unavailable without in-progress evidence, or otherwise ambiguous for the current head
- a required current-head wait cannot be confirmed settled
- the current head reports conflicted merge state (`DIRTY` / `CONFLICTING`) or local git conflict markers are present; enter `merge_conflict_resolution` instead of progressing
- a boundary that is already CI/validation-dependent cannot confirm current-head freshness because the relevant status is pending, none, unknown, or stale
- a required visible gate comment could not be confirmed posted

In those cases the workflow MUST NOT:
- leave draft
- request or re-request Copilot review
- declare final approval readiness
- silently fall through to a more permissive state

## Cross-references

- [Contract style guide](contract-style-guide.md)
