# Acceptance Criteria Verification

Canonical owner for the acceptance-criteria verification procedure run during the `pre_approval_gate`. Referenced from [Copilot PR Follow-up Skill](../copilot-pr-followup/SKILL.md#pre-approval-gate-contract).

## Procedure

<!-- rule: ACCEPT-CRITERIA-VERIFY-AND-REFLECT -->
`ACCEPT-CRITERIA-VERIFY-AND-REFLECT`: Before posting the `pre_approval_gate` comment, the agent MUST verify every acceptance criteria checklist item in the issue linked to this PR, and MUST reflect the verified items back into both the linked issue body and the PR body (exception: when the linked issue body is not the spec-of-record — under a lightweight session (tracker-backed or issue-less; the PR body is the spec) or a plan-file promotion session (the committed plan doc the PR body points to is the spec) — the step 5 issue-body mirroring is skipped; see the fork below):

> **Non-tracker spec-source fork:** when the linked issue body is not the spec-of-record, handle each of the three arms as below.
>
> **Tracker-backed lightweight** (`--issue --lightweight`): a linked issue exists, so keep the `Closes #N` linkage and all issue-level tracking, but the **PR body**, not the issue body, is the canonical spec-of-record read for AC/DoD. Still resolve the linked issue for tracking, but read the AC/DoD/invariants from the PR body rather than the issue body (skip step 2's issue-body read for spec purposes). Run `node scripts/loop/validate-pr-body-spec.mjs --repo <owner/name> --pr <pr-number> --expected-issue <issue-number>` (reuses `@dev-loops/core/loop/issue-refinement-artifact`) to confirm the body carries the required invariants — it fails closed with a per-section `missing_*` reason if any is absent, in which case post the gate comment with verdict `blocked`. The PR body MUST carry the `Closes #N` linkage (or GitHub's other closing-keyword forms): `validate-pr-body-spec` fails closed with `missing_closing_issue_reference` without it, and with `closes_wrong_issue` when `--expected-issue` doesn't match. Then continue at step 3, extracting the **Acceptance criteria** checklist items from the PR body itself; step 5's issue-body AC-tick update is unnecessary since the issue body is not the spec surface (the PR body is ticked in step 6 as usual).
>
> **Issue-less lightweight** (`--lightweight` alone): no linked issue exists — by design, not a gap. There is nothing to resolve at step 1 and nothing to read or mirror at steps 2 and 5; skip all three. Read AC/DoD/invariants directly from the PR body and run `node scripts/loop/validate-pr-body-spec.mjs --repo <owner/name> --pr <pr-number> --no-issue`, which fails closed with a per-section `missing_*` reason for any absent invariant and with `unexpected_closing_issue_reference` if the body carries a closing reference to an issue that doesn't back it (a closing reference MUST NOT be present). On any validation failure, post the gate comment with verdict `blocked`. Step 1's "zero candidates → blocked" rule is scoped to tracker-backed sessions; for a deliberately issue-less session, zero closing references is the expected state, not a blocked condition. Continue at step 3 against the PR body, then step 4 and 6 as usual.
>
> **Plan-file promotion (P4), a local-planning origin:** no linked issue exists; skip steps 1, 2 and 5. AC/DoD live in the PR body, copied from the committed plan doc that is the spec-of-record; read them from the PR body as usual.
>
> The default issue-backed procedure below is unchanged.

1. **Resolve the linked issue number deterministically:** use `node scripts/github/view-pr.mjs --repo <owner/name> --pr <pr-number> --json closingIssuesReferences,body` and apply this decision tree: if there is exactly one closing issue reference, use it; else if there is exactly one PR-body `Closes #N` / `Fixes #N` pattern, use it; otherwise (zero or multiple candidates), post the gate comment with verdict `blocked` (gate cannot complete deterministically) rather than guessing.

2. **Read the issue body:** `node scripts/github/view-issue.mjs --repo <owner/name> --issue <issue-number> --json body --jq '.issue.body'`

3. **Extract acceptance criteria.** Under #1951 the authoritative acceptance criteria live in the issue's `## AC / DoD matrix` (the criterion column) and are projected onto the PR body as list-form checkboxes (`derivePrChecklistsFromIssueMatrix`). Read the acceptance criteria from the **PR body's** Acceptance criteria checklist (both `- [ ]` and `- [x]` items). When the issue body ALSO carries an interactive `## Acceptance criteria` checklist (a pre-#1951 issue), extract those too for the issue-side sync in step 5. Acceptance verification MUST NOT depend on the issue carrying duplicate interactive checkboxes. Ignore items from other sections (DoD, tasks, non-goals) that are not acceptance criteria.

4. **Verify each AC item** against the proposed changes on the current PR head.

5. **Automatic tick (dry run before composing, write before the post):** the reviewers of the `acceptance-criteria` and `pr-checklist` angles list the exact label of each checklist item they verified at this head in their findings artifact's `verifiedItems` field (defined in the review agent's structured findings artifact). Fan-in carries the deduplicated union into the durable findings ledger. For a `pre_approval_gate` post with `--findings-ledger`, `upsert-checkpoint-verdict.mjs` computes the ticked bodies as a dry run for exactly those labels before it composes the verdict. In `fanout_fanin` mode the ledger must first pass the fan-out angle-coverage checks. In every mode its provenance must be consistent and record a fresh (not carried) `acceptance-criteria` or `pr-checklist` review. Otherwise nothing is ticked. The poster flips each matching `- [ ]` to `- [x]` in the PR body's unchecked Acceptance criteria and Definition of done items. When the spec-of-record still has unticked AC items (`uncheckedAcItems`), it also ticks each linked issue body that the coordination load read and that carries unticked AC items. A label outside those unchecked lists is not ticked. A verified label that an open judge act item (including one with an evidence-only remedy) names by label text is skipped for the PR body and for linked issue bodies. An `ac:<n>` / `dod:<n>` id skips only the PR-body row: a resolved id leaves that PR row unticked, and a linked issue's AC row with the same label is still ticked. An id that does not resolve in the pinned spec, or whose text matches no unchecked PR row, skips every PR-body row of its category (PR-body rows only). Do not hand-tick a row left unticked for an open act item with `tick-verified-checkboxes`. A linked issue whose body the coordination load could not fetch is skipped and stays spec-of-record unavailable. The match is exact-label, and the tick never blanket-checks and never unchecks. Each changed body gets one edit, written only after every refusal check and directly before the verdict is posted. The verdict composition and the `clean` guards read the dry-run ticked bodies. A failed fetch or edit of a body being ticked fails closed, and no verdict is posted. A refusal changes no body. Before any write, a live preview re-reads each body and refuses with "The checklist of PR N (or issue N) changed after the gate read it" when its checkbox rows or their AC/DoD scopes differ from the dry run; no verdict is posted and nothing is ticked. The remedy is to re-run the gate against the current body. A failed post (HTTP error) after the write keeps the ticks, and a rerun is idempotent. The tick does not run for `draft_gate`. On a matrix-representation issue the issue-side tick is a no-op, and the PR body's derived checklist is the ticked surface.

   <!-- rule: CHECKLIST-SCOPE-ONE-MODEL -->
   **CHECKLIST-SCOPE-ONE-MODEL:** every PR-body tick-integrity check reads checklist scope from `checklistLineScopes` in `packages/core/src/loop/issue-refinement-artifact.mjs`: the fence-aware scope of a line is `ac`, `dod`, or none, set by its nearest Acceptance criteria or Definition of done heading, so a Definition of done section nested under Acceptance criteria is `dod`. The category-scoped tick, the live checklist preview and the `edit-pr` and `edit-issue` untick guards (the same `untickedRows` check and `--allow-untick` refusal on every body they write) key a checkbox row by that scope plus its label. A heading rename inside one scope keeps a checked row. A heading edit that moves a checked row into or out of a scope counts as losing it (the refusal reads "unticked, deleted, reworded, or moved into or out of its AC/DoD scope") and needs `--allow-untick`. A second fence scanner or section classifier MUST NOT decide that scope for the PR body. The linked-issue tick keeps its own `acOnly` section filter.

   **Manual tick paths:** the automatic tick needs `verifiedItems`, and only the fan-out path writes them (per-angle artifacts through `consolidate-fanin`). It also reads the unchecked PR-body lists, which the coordination state fills only for a tracker-backed PR with a linked issue (step 7). The tick reads `verifiedItems` only from a trusted ledger: consistent provenance that records a fresh `acceptance-criteria` or `pr-checklist` review, plus fan-out angle coverage in `fanout_fanin` mode. Two paths therefore tick nothing automatically. The first is a post that carries no trusted `verifiedItems`: a post without `--findings-ledger`, a light-mode `inline_single_agent` round (with or without a ledger), or a ledger that lacks a fresh `acceptance-criteria` or `pr-checklist` review or fails the `fanout_fanin` angle coverage. The second is a lightweight or issue-less PR. On those paths the operator ticks each verified item before posting with `node scripts/github/tick-verified-checkboxes.mjs --repo <owner/name> --issue <issue-number> --pr <pr-number> --verified <exact label>...`. Without a tracker-backed issue, the operator passes `--pr` alone. The CLI applies the same exact-label tick. On a fan-out post for a tracker-backed PR with a linked issue, the CLI is a manual correction tool only.

6. **PR body tick:** the step 5 tick covers the PR body, so the merged PR shows checked AC/DoD. The tick is automatic on a fan-out post for a tracker-backed PR with a linked issue. On the manual tick paths the operator runs the CLI. An item that no reviewer verified stays `- [ ]`, and so does a deferred item.

7. **Deterministic pre-approval completeness block (#1877):** any unchecked `- [ ]` in the PR body's own Acceptance criteria / Definition of done checklists fails the `pre_approval_gate` closed — `upsert-checkpoint-verdict.mjs` refuses a `clean` verdict while `prBodyUncheckedAcItems`/`prBodyUncheckedDodItems` are non-empty, so a PR cannot reach approval with an open acceptance criterion. Scope: the coordination state populates those fields for a **tracker-backed ready PR with at least one deterministically-linked issue** — including when every linked-issue body fetch fails (the PR body is local, so the block stays armed) — but NOT for the lightweight/issue-less path (the draft-exit `validate-pr-body-spec` check owns that surface), and not for a PR body with no resolvable linked issue. An item that no reviewer listed in `verifiedItems` stays unchecked and therefore blocks. The `**Gate blockers:**` line of the posted verdict states the count per blocker kind, and a visible list below it names every remaining item. This check enforces **completeness**, NOT **truthfulness**. The step 5 tick applies only a reviewer's own verification. Verifying that each `[x]` is real remains the reviewer/judge's responsibility (the `pr-checklist` angle and the judge's AC/DoD/non-goals relevance pass).

8. **Post the gate comment:** always post a `pre_approval_gate` comment for every completed gate attempt; the precondition refusals described below post none (the checkpoint verdict comment contract requires a visible comment even for non-`clean` verdicts). The fan-in ledger's `overallVerdict` is the review verdict; the checkpoint verdict composes it with the deterministic gate blockers:

   | Review ledger and gate state | Checkpoint verdict |
   |---|---|
   | review ledger clean and all gate prerequisites satisfied | `clean` |
   | blocking-severity review finding, no independent gate blocker | `findings_present` |
   | unmet AC/DoD or another deterministic gate blocker | `blocked` |
   | review/fan-in itself unable to complete | `blocked` |

   With a `--findings-ledger`, `upsert-checkpoint-verdict.mjs` derives this composed verdict when `--verdict` is omitted and records the underlying review verdict and the named blockers when they differ. In all cases include a note on AC verification status.

   Precondition refusals stay refusals and never compose into this table. Spec-of-record linkage is a draft-boundary precondition. `detect-pr-gate-coordination-state.mjs` records the refinement artifact as `missing` (finding `missing_refinement_artifact`) on a draft PR when it finds no deterministically resolvable linked issue and no valid PR-body spec, or when it cannot fetch any linked issue body. The coordination state then refuses gate entry with `REPORT_BLOCKED` before any fan-in runs. On a ready PR the same cases leave the spec-of-record AC data unresolved and add no blocker; the step-7 PR-body AC/DoD completeness block stays armed only when at least one linked issue resolves (including when every linked-issue body fetch fails).

When the spec-of-record surface carries no acceptance-criteria items at all — no PR-body AC checklist AND (for a matrix-representation issue) no matrix rows to project — the outcome is `blocked`, never `clean`. This case is a precondition refusal. `validate-pr-body-spec` rejects a tracker-backed PR body without AC checkbox items (`missing_acceptance_criteria`) at `create-pr.mjs` and again at `ready-for-review.mjs`. The draft-boundary coordination state refuses gate entry for an issue-less PR body that fails the same check. If the `pre_approval_gate` still finds no AC source, do not post a checkpoint: stop, report the gate `blocked` to the operator, and name the missing AC source explicitly. A matrix-representation issue with no interactive issue-side AC checklist is NOT itself "no AC".
