Product acceptance verification

# Product acceptance verification

## Goal

Independently verify whether the delivered increment satisfies its accepted product contract, preserves protected behavior, and is fit to advance to release-readiness review.

Acceptance is a claim about observable behavior, not effort, code completion, or the delivery author’s confidence. Audit the implementation against the contract criterion by criterion.

This is an acceptance audit. Do not deploy, change production, use secrets, access real user data, or silently repair product behavior. Keep implementation changes separate from the audit.

Default to read-only verification plus the audit artifacts named below. A clearly safe correction to audit documentation or an isolated test-only gap may be made only when it does not alter product behavior, broaden scope, mask a failure, or disturb unrelated work; record it explicitly as an audit repair and rerun the affected checks.

Complete the audit autonomously. Do not stop to ask clarifying questions. When a criterion cannot be proven, mark it `NOT VERIFIABLE` and choose a decision that reflects the gap.

## Prerequisites

Read, in order:

* every applicable `AGENTS.md` and repository instruction file
* the current increment contract, YAML, and changelog
* the current implementation plan, YAML, and changelog
* the current delivery report, YAML, and changelog
* the actual changed files, tests, schemas, interfaces, documentation, and relevant working-tree or commit diff
* existing baseline tests and current repository status
* any existing `docs/product/acceptance-verification.md`, `docs/product/acceptance-verification.yaml`, and `docs/product/acceptance-verification-changelog.md`

The increment ID and inherited artifact versions must agree. Proceed toward `ACCEPT` or `ACCEPT WITH LIMITS` only from a `DELIVERED` delivery decision. A `PARTIAL` delivery may be audited, but it forces `HOLD` until the contracted scope and delivery record agree. If the delivery decision is `BLOCKED` or `CONTRACT CONFLICT`, do not manufacture acceptance; return `HOLD` or `REJECT` as the evidence warrants.

If the implementation diff cannot be isolated from unrelated changes, identify the uncertainty and do not attribute those changes to the increment.

## Evidence standard

Label every material claim with exactly one:

* `OBSERVED`: directly demonstrated by reproducible test output, code inspection, or an inspectable artifact
* `DERIVED`: concluded from cited observations; show the derivation
* `ASSUMED`: unverified; never sufficient to pass a criterion
* `UNKNOWN`: unresolved; state what would resolve it

Use one criterion status:

* `PASS`: expected behavior and relevant failure behavior were demonstrated
* `FAIL`: behavior contradicted the criterion or a protected invariant
* `NOT RUN`: a planned check was available but was not executed
* `NOT VERIFIABLE`: the available environment or instrumentation cannot establish the claim
* `OUT OF SCOPE`: allowed only for a criterion explicitly removed by an accepted narrow contract version

A test passes only what it asserts. Snapshot existence is not semantic accessibility. Absence of an error is not performance evidence. Manual inspection must include exact steps, input, and observed result.

## Step 1: Freeze the audit basis

Record:

* increment ID and exact contract, plan, and delivery versions
* implementation diff or changed-file basis
* working-tree state, including unrelated changes
* runtime, toolchain, test-data, and environment constraints
* any artifact mismatch or delivery deviation

Do not let contract edits made after delivery retroactively redefine success. If the governing version is ambiguous, return `HOLD`.

## Step 2: Reproduce the delivered baseline

Run the repository-supported focused checks reported by delivery before adding independent probes.

For each command record command, relevant environment, exit status, duration when available, result, skipped tests, warnings, and whether the result matches the delivery report.

Do not use production credentials, live services, or real customer data. Use synthetic, fixture, or local test data. Do not start a development server unless the user or repository instructions explicitly authorize it.

If the delivery report says a check passed and it cannot be reproduced, treat the discrepancy as evidence, not an inconvenience.

## Step 3: Verify every acceptance criterion

Create a criterion matrix with:

* criterion ID and contracted behavior
* evidence label
* test or inspection used
* expected result
* observed result
* status
* defect or gap ID when not passed

Create linked rule, permission, success-measure, and quality-bar matrices from the contract. For each stable ID, record the governing clause, verification evidence, expected and observed result, and status. A criterion can cover several IDs only when each result remains independently visible.

Exercise the happy path and contracted error, empty, loading, permission, boundary, and recovery states. Verify observable output rather than internal implementation alone.

Check that assumed thresholds remain labeled and that the implementation did not silently turn an unknown into a claimed fact.

Verify business-rule precedence and conflicting states, allowed and forbidden actions for every implicated role, tenant, entitlement, ownership, and data boundary, and every release-blocking quality bar. A passing user path does not establish that a forbidden path is blocked or that a quality threshold holds.

## Step 4: Verify protected invariants and regression risk

For every protected invariant, run or inspect its named regression evidence. Then examine the actual diff for plausible adjacent regressions:

* public interfaces and backward compatibility
* data integrity and migration behavior
* authorization, authentication, trust boundaries, and sensitive-data handling
* keyboard, focus, semantics, contrast, motion, and assistive-technology behavior where UI is affected
* performance budgets, resource use, concurrency, or latency where relevant
* error recovery, reliability, idempotency, and partial failure
* localization, platform, browser, or device behavior where the supported surface requires it

Apply these checks proportionally. For every materially relevant category, record evidence. For every category declared not applicable, state why.

Run the relevant regression suite supported by the repository. A pre-existing failure must be distinguished from a regression with evidence; it is not automatically ignored.

## Step 5: Audit observability and rollback claims

Without touching production or external systems, verify that:

* outcome and guardrail signals exist as contracted and do not expose secrets or personal data
* local tests or inspection demonstrate event, log, metric, or trace behavior where feasible
* failure modes are diagnosable at the promised level
* feature-flag, compatibility, migration, and rollback paths match the documented plan
* user or data state that cannot be reversed is explicitly named

Do not execute a destructive rollback. Use tests, dry runs, reversible local fixtures, or static inspection. An untested rollback claim remains `UNKNOWN`.

## Step 6: Classify findings without repairing the product

For each finding assign:

* severity: `BLOCKER`, `MAJOR`, `MINOR`, or `NOTE`
* affected criterion or invariant
* reproducible evidence
* user or system consequence
* minimum condition for closure

Do not edit product code to make a failed criterion pass during the audit. Do not weaken, delete, skip, or rewrite a test or criterion.

If you add a clearly safe missing test or correct audit documentation, list the exact files under `audit_repairs`, explain why behavior is unchanged, and keep the resulting diff separate from the implementation finding.

## Step 7: Desk-test the acceptance decision

1. Every in-scope criterion has one status and reproducible evidence.
2. Every business rule, permission, protected invariant, success measure, and quality bar was checked or is explicitly not verifiable.
3. Delivery claims were reproduced rather than copied.
4. Relevant accessibility, security, privacy, performance, reliability, compatibility, and data-integrity risks were tested proportionally.
5. Observability and rollback claims were checked without production access.
6. No product failure was silently repaired or hidden.
7. Unrelated and pre-existing work remains distinguishable.

## Decision

Conclude with exactly one:

* `ACCEPT`: all in-scope criteria pass, no protected invariant fails, and no material quality risk remains
* `ACCEPT WITH LIMITS`: the named exposure or use may proceed despite only minor, bounded limitations that do not contradict the core outcome
* `HOLD`: acceptance cannot be established because required checks, environment, evidence, or isolation are missing
* `REJECT`: one or more criteria or protected invariants fail, or material risk makes the increment unfit to advance

Lead with:

“As of [date], acceptance verification for increment [increment_id] against contract [version] found [N] pass, [N] fail, [N] not run, and [N] not verifiable criteria, plus [N] blocker/major findings; decision [ACCEPT / ACCEPT WITH LIMITS / HOLD / REJECT].”

## Deliverables

Create or update only the audit artifacts and any explicitly recorded safe test or documentation repair:

### 1. `docs/product/acceptance-verification.md`

Lead sentence, frozen audit basis, reproduction log, criterion, business-rule, permission, success-measure, and quality-bar matrices, invariant and regression results, observability and rollback audit, findings, audit repairs, limitations, desk-test results, and decision.

### 2. `docs/product/acceptance-verification.yaml`

Include `version`, `status`, `as_of_date`, `decision`, `increment_id`, `contract_version`, `plan_version`, `delivery_version`, `audit_basis`, `criterion_results`, `business_rule_results`, `permission_results`, `success_measure_results`, `quality_bar_results`, `invariant_results`, `verification_runs`, `observability_results`, `rollback_results`, `findings`, `audit_repairs`, `limitations`, `assumptions`, `unknowns`, and `sources`.

Use stable criterion and finding IDs. Record failures, skips, and unknowns. Unknown values are `null` with an explanation.

### 3. `docs/product/acceptance-verification-changelog.md`

Append only. Record version, date, inherited artifact versions, decision, changed findings, and newly observed evidence. Never erase a prior failed audit; append the re-verification.

Parse the YAML and confirm that the artifacts agree with the actual commands, diff, and contract.

## Boundaries

* Do not deploy, release, merge, push, contact production, use secrets, or access real user data.
* Do not modify product behavior during acceptance verification.
* Do not silently fix failed criteria, broaden scope, or weaken tests.
* Only clearly safe, isolated test or documentation gaps may be corrected, and every correction must be reported as an audit repair.
* Do not treat skipped, flaky, or unreproducible checks as passes.
* Do not overwrite, reset, reformat, or otherwise disturb unrelated work.

## Done when

* Every in-scope criterion, business rule, permission, protected invariant, success measure, and quality bar has an honest, evidence-backed status.
* Delivery results were independently reproduced where the environment permits.
* Relevant regression, accessibility, security, privacy, performance, reliability, compatibility, observability, and rollback risks were assessed proportionally.
* Findings are reproducible and product repairs remain separate.
* The decision follows the evidence rather than schedule pressure.
* The Markdown, YAML, append-only changelog, commands, and implementation diff agree.