Acceptance Evidence for Deliveries

Acceptance (Builder Self-Evidence)

You are the builder for a delivery. A separate review step judges it against a plan — checks you author, or a verify plan handed to this run. A check that declares requiredEvidence cannot pass on your text alone: a missing artifact marks it uncertain and holds the delivery.

author (or discover) the plan  →  pick the surface  →  capture evidence  →  publish the round  →  self-check coverage

Decide whether to execute before starting a round

Creating or updating a PR, marking it ready, or being asked to upload a report must not by itself start another verification run. First inspect the requested scope and the task's existing reports, evidence, and published acceptance links (from the conversation, PR, or local .acceptances/ directory).

Evidence is reusable when its criteria cover the requested behavior, its artifacts are available and support the observations, and subsequent code, dependency, configuration, or environment changes do not invalidate those observations. Compare the relevant changes; a different commit SHA, rebase, PR event, or report publication status alone is not a reason to rerun. Failed/blocked checks and missing required evidence are not passes: repair or supplement those specific gaps. An explicit user request for fresh verification still takes precedence.

The execution, environment setup, plan/checker, and capture sections below apply when executing acceptance. For reuse or upload only, inspect the existing report and evidence and complete the necessary publication/coverage steps; do not boot services or replay completed cases. Uploading does not change when or against which implementation the evidence was captured.

Independent acceptance review (first round only)

The primary checks the environment, writes the plan, executes cases, inspects evidence, repairs failures, and publishes. Use one acceptance-checker agent at two points in the first acceptance round: give at most two feedback responses on the plan and cases before execution, then perform exactly one quick report/evidence check against the agreed criteria before publishing. A second plan check is optional, only to check the primary's revisions; there is no third plan-feedback response. Count the two stages separately. After either stage's limit, the primary owns remaining corrections and verification. The acceptance-checker is the plan gate — never ask the user to approve a plan; ask the user only for a user-owned prerequisite or a product decision that changes the plan. In both stages, the primary supplies an explicit file list and the relevant diff text or prepared diff artifact paths. The acceptance-checker limits code reading to these materials; it must not run git diff or discover its own scope. This does not restrict inspection of the plan, report, or evidence. During evidence review, use it only to identify the updates and the agreed cases whose evidence needs checking; the core task is checking the report against the plan and artifacts. Do not reopen requirements, expand into code review, or investigate implementation details. Return contradictions to the primary for explanation or repair. Follow-up rounds have no acceptance-checker: the primary re-runs, inspects, and publishes itself. Do not delegate execution or require per-case approval.

Read acceptance-checker.md for the input/output contract, review boundaries, and follow-up rules. Acceptance review supplements the primary's own checks and any configured verifier; it does not replace either. If delegation or required media inspection is unavailable, disclose the missing review and unverified claims rather than claiming independent acceptance.

Read the project layer first

Before touching an environment, check for .agents/acceptance/:

The project layer owns how this repository is run; this skill owns what a valid round is (plan, evidence, report, immutable round, the hard rule). On running, the project layer wins; on what may be published, this skill wins. Never invent a start command, port, or auth flow PROJECT.md answers; fix a divergence in the adapter during the run instead of working around it. No .agents/acceptance/ → bootstrap one first: project-adapter.md.

Living logs — inject each by its own shape

Both layers (this skill's generic copies and the project's own) are loaded once the target is known, silently:

• common-mistakes.md — read its Checklist in full, now and again before marking any case pass. Pull an entry by id only when a checklist line applies to a case.
• probe-mock-patterns.md — read the heading index, then pull only the entries this round needs. Pick by meaning, not keyword; rg over the body is the fallback.

rg -n '^#{2,4} ' <file>          # the index, with line numbers
sed -n '<start>,<end>p' <file>   # one entry, in full

Record new project-specific learnings in the project layer only.

Two paths — no id is required

Every evidence command targets a round. The authored path is the default; you have an operation id only when the invocation names one. Never hunt the environment for one, and never report this skill inapplicable — a round without an operation is simply recorded as standalone.

Pass --subject (task:<id> / topic:<id> / document:<id>) only when the caller named one; otherwise ingest attaches the round itself when it can and creates a standalone acceptance when it cannot. On the first ingest, always supply --requirement "<one-sentence business goal>" — the durable goal of the whole acceptance, not this round's scope; it is immutable once recorded.

Prerequisites: lh is authed (lh acceptance run list --json returns [] or data; an auth error means stop and surface it), and only the UI driver the selected surface needs is installed — probe before adding dependencies, and never substitute a private agent plugin.

Optional user-journey flows

Before authoring checks, identify the independently reviewable user tasks in the requirement. Use those tasks as business groups, not the PR title or test surface. For example, reassignment, scheduled continuation, and failure recovery can be separate groups when the delivery covers all three; do not impose these groups on unrelated work. Each check should have an outcome the user can accept or reject independently. Keep shared entry/accessibility checks separate and avoid repeating their expectations across business checks.

When acceptance depends on a sequence of user states, publish its graph during planning, before implementation or verification begins. Keep the checklist paths above for independent checks; a graph is optional and does not replace evidence or human review.

For flow-based plans, each flow's title is its checks' default checklist category. Publish independent user journeys as separate flows in the same acceptance/run; use subflows for actual composed journeys. An umbrella flow containing checks for several independent tasks collapses them into one checklist group. Edges must describe real user transitions, not artificial links added to make unrelated checks reachable. Start at the user entry and follow the journey through outcomes and recovery; UUIDs identify nodes and must not encode business order. Read back the published plan and inspect its groups and reading order before execution.

For an existing acceptance that only needs different checklist groups, use lh acceptance regroup <acceptanceId> --file groups.json. Read the acceptance bundle first; write { expectedVersion, groups: [{ title, checkItemIds }] }, using the exact union checks[].id values and acceptance.metadata.checkGrouping.version (0 when absent). The groups replace the current presentation grouping; an empty list restores plan categories. Unassigned checks keep their plan category. This preserves check IDs, numbering, evidence and review history without creating a round. It does not change flow transitions or verification conditions. Do not move execution nodes or start a new round just to reorganize the checklist; those operations have different execution semantics.

1. Use the named acceptance, or create one before publishing the flow. If none was named, first run lh acceptance create --help and confirm it shows Usage: lh acceptance create [options] and --requirement. Parent-command help or a zero exit code alone does not prove support. If unavailable, upgrade @lobehub/cli to a release that supports this command and check again; updating the skill alone does not upgrade the CLI. If still unavailable, report flow-first creation as blocked. Do not invent a subject ID, upload an empty report, or substitute lh acceptance run create (which creates a round).

   lh acceptance create --title "Checkout recovery" \
     --requirement "Customers can recover from a declined payment and complete checkout" --json

   --requirement is a required, nonblank durable business goal; --title is optional. Omit --subject for a fresh standalone subject, even when an ambient topic exists. Pass --subject task:<id>, topic:<id>, document:<id>, or standalone:<id> only for an explicitly supplied subject. Reusing a subject preserves its recorded requirement, title, and state; it does not reopen it. Creation does not create a verification round, report, results, or passing verdict.

   The JSON contains acceptanceId, acceptanceUrl, requirement, status, and subject: { subjectType, subjectId }. Use acceptanceId in all flow commands below, not subject.subjectId or a verification run ID. Share acceptanceUrl verbatim; it already uses the CLI's configured server.

   Write a JSON file with definition: { title, entryNodeId, nodes, edges }. Give nodes and edges stable UUIDs. Each node has id and exactly one of criterionId (existing check asset), check: { id, title, definition } (a check asset with steps, fixtures, preconditions and expected outcome), or subFlowId (another flow in this acceptance). Edges have id, sourceNodeId, targetNodeId, trigger, required, and optional condition. Every node must be reachable from the entry. Publish child flows before referencing them.

2. lh acceptance flow publish <acceptanceId> --file flow.json saves the definition and returns flowId. To edit it, include that flowId and the current expectedHash in the file. lh acceptance flow view <acceptanceId> reads definitions, snapshots and results. Publishing does not execute checks. Revise a graph in place rather than publishing a second one; a superseded graph left behind still renders as its own journey with its own unexecuted checks. lh acceptance flow delete <acceptanceId> --flow <flowId> removes one that never should have existed, and only while it has no verified history: it is refused once a settled round has run it, or while another flow invokes it as a subflow.

3. lh acceptance flow plan <acceptanceId> --flow <flowId> creates a draft round with the graph and its plan. While the round is only planned it follows the live graph: publishing an edit refreshes its snapshot and plan in place, and running flow plan again refreshes the same draft instead of opening another round. Add --run <verifyRunId> to attach another flow to the same draft. Read lh acceptance run get <verifyRunId> --json for the actual plan IDs: each branch and subflow invocation has its own checkItemId; never substitute the reusable asset ID.

4. Share the acceptance link so the user can inspect the proposed nodes, branches and expected outcomes before implementation. Read and address any actionable feedback. Preparing a plan neither executes checks nor approves delivery; there is no separate flow-confirmation action. Continue within the user's authorized scope, or pause if the user explicitly asked to review before work. For requested changes, publish the revised definition with its flowId and expectedHash; the draft round follows automatically. Never open another round or another flow just to revise a plan that has not executed.

5. Implement the work and exercise the real product, then use lh acceptance flow record <acceptanceId> --file result.json, containing verifyRunId, checkItemId, verdict (passed, failed, uncertain, or blocked) and observation. Record only what was observed. Use the returned result ID to attach required artifacts through lh acceptance run evidence (inspect its --help), following the same evidence rules as checklist checks.

6. After all required checks are recorded and passed, run lh acceptance flow complete <acceptanceId> --run <verifyRunId>. Completion settles verification; it does not accept the delivery on the user's behalf. Read back the round and verify evidence coverage before handing it over.

To rerun the exact old graph, prepare a plan with --from-run <sourceVerifyRunId> and omit --run for a fresh round. This preserves the old definition and starts without results. Each replay starts as an unexecuted draft. A round is frozen by its first recorded result; only then does it keep its number. An lh acceptance run ingest that reaches an acceptance whose latest round is still a draft folds into that draft rather than opening a new round. Accepted or closed acceptances must be explicitly reopened before starting. Edges describe business transitions; they do not automatically schedule execution. Continue to read lh acceptance feedback <acceptanceId> --actionable before repairs and publish new rounds into the same acceptance.

HARD RULE — programmatic gates are NEVER acceptance checks

Every check MUST be an outcome a person decides about the delivery: what the user sees, hears, reads, or receives. These MUST NOT appear as a check, under any phrasing: unit / integration / regression / snapshot tests, coverage, type-check / tsc, lint / eslint, format, "compiles", "build passes", "CI is green". Run them, then report them as one line of narrative.

Enforced at ingest: every matching item (matched on title, category, AND method — "run bun run test" under a product-sounding title still matches) is dropped with a warning and summary recounted; a round of only such checks fails to publish. The line is the subject of the check, not who judged it: a CLI behavior asserted by a command is a fine check (verifier: "program"); "the suite is green" is not. Before writing any plan, ask of each draft check: would the user click accept/reject on this?

Rounds are immutable — repair means a NEW round

A published round is a permanent record. Never re-submit into a round after changing the code — publish the re-verification as the next round and let the acceptance page show the progression.

Before a repair round, read the aggregate with lh acceptance view <acceptanceId | type:id> --json. Omit checks whose latest userReview.action is accept; address non-stale rejects under their exact stable ids; when a check semantically replaces another, declare supersedes: ['old-id'] and repeat the full lineage in every later round that reuses the successor id. Pass --acceptance <acceptanceId> so the round joins the same history.