opensourceagi/qwksearch-research-agent/acceptance

Verify (Builder Self-Evidence)

You are the builder for a delivery. A separate review step judges it against either an existing verify plan or checks you author before testing. Some criteria demand evidence (a screenshot, a DOM snapshot, CLI output…). A criterion that declares requiredEvidence cannot pass on your text alone: if the artifact is missing, the structural gate marks it uncertain and the delivery is held.

Read the project layer first (when the repository has one)

Before touching an environment, check for .agents/acceptance/. A repository that verifies itself keeps its own layer there, and it outranks any guess you would otherwise make:

The division of labor: the project layer owns _how this repository is run_; this skill owns _what a valid acceptance round is_ (plan, evidence, report, immutable round, the hard rule below). Where they disagree on running, the project layer wins. Where they disagree on what may be published, this skill wins. Never invent a start command, a port, or an auth flow that PROJECT.md already answers, and never work around a divergence silently — fix the adapter in place during the run.

No .agents/acceptance/ means the repository has no project layer yet. Continue with the portable path below; if the run needs an adapter, bootstrap one first — project-adapter.md.

Read both living-log layers before executing a round that drives a product surface: this skill's generic common-mistakes.md and probe-mock-patterns.md, plus the project's own copies. Record new project-specific learnings in the project layer only.

Applicability invariant

This skill applies whenever the delivery needs real verification. It requires no ids at all — nothing about it is conditional on where it runs:

• Were you handed an operation id (a verify plan already exists for this

run)? Discover that plan and satisfy it.

• Otherwise — the normal case — author the checks yourself and publish a

structured report round.

• Attaching to something specific? Pass --subject (task:<id>,

topic:<id>, or document:<id>) when the caller named one. Otherwise omit it: lh acceptance run ingest attaches the round itself when it can, and creates a standalone acceptance when it cannot.

Never report this skill inapplicable, and never go hunting through the environment for an id to make it applicable. Missing ids are the default state, not a degraded one.

So while you do the work, capture the proof and submit it. The loop:

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

The skill package is portable, but execution capabilities are surface-specific: agent-browser serves Web/Electron, while native macOS and iOS Simulator require a local macOS display and their platform tools. No repository-specific scripts are required; rounds land under .acceptances/, which the CLI keeps out of git for you (see report.md).

Two entry points — an operation id is NOT required

Every evidence command targets a verification session (a round). How you name that session is a choice, not a prerequisite:

The authored path is the default. You have an operation id only when the invocation names one — a task, a caller, or the user hands it to you. Do not read the environment looking for one, and do not treat its absence as a problem to solve: a round created without an operation is simply recorded as standalone.

--operation and --run are interchangeable on result submit and result list. (evidence list takes neither — it keys off a positional <checkResultId> you read from result list.) On a later repair round, pass the previously printed --acceptance <acceptanceId> so the new snapshot joins the same history.

On the first ingest, always supply --requirement "<one-sentence business goal>". The requirement describes what the whole acceptance judges, not the narrower scope of one round. It is immutable once recorded.

HARD RULE — programmatic gates are NEVER acceptance checks

This is a binding constraint on every check you author, enforced at ingest — not a style preference.

Every check MUST be an outcome a person decides about the delivery: what the user sees, hears, reads, or receives. The repo's own automated gates are not that. The following MUST NOT appear as a check, in any round, under any phrasing:

• unit / integration / regression / snapshot tests; test suites or test cases
• coverage, type-check / tsc, lint / eslint, format, "compiles cleanly",

"build passes", "CI is green"

They are preconditions of shipping, and a page full of them buries the two or three checks that actually needed a human eye. Run them — then report them as one line of narrative, never as a check.

Enforcement, so plan around it rather than against it:

• lh acceptance run ingest drops every matching plan item and case and

warns — the round publishes without them, so a gate-check wastes the effort spent producing it.

• A round consisting only of such checks fails to publish entirely:

there is nothing in it for a person to accept.

The line is the _subject_ of the check, not who judged it: a CLI behavior check asserted by a command is a good acceptance item (verifier: "program"); "bun run test is green" is not. Before writing any plan, re-read each draft check and ask: _would the user click accept/reject on this?_ If the honest answer is "it's a gate", it does not go in.

Rounds are immutable — repair means a NEW round

A published round is a permanent record of what was true at that moment. Never re-submit into a round to "fix" it after changing the code — publish the re-verification as the next round, and let the acceptance page show the progression. Correcting a typo in the same session's report is fine; passing off post-fix evidence as the original round is not.

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

The acceptance (/acceptance/<acceptanceId>) is the stable cross-round decision surface that aggregates every immutable round for a subject. In the final reply, expose only the acceptance page. A fixed snapshot of the current round uses that same path with ?r=<roundIndex>; implementation-level run pages stay internal.

Prerequisites

• `lh` is authed. Confirm with lh acceptance run list --json (an empty []

means authed; an auth error means stop and surface it).

• A round path. Use the operation id when this run was given one. Otherwise

author a structured report; ingest creates both its round and its acceptance.

• Install only the UI driver required by the selected surface. Web/Electron

use agent-browser; native iOS uses Xcode/simctl plus a Simulator HID/AX CLI such as AXe, or the repository's existing UI-test driver. Probe installed tools before adding dependencies, and do not substitute a private agent plugin.

Step 1 — Discover the plan (what to prove)

Plan-driven path only. Authoring your own checks instead? Apply the

hard rule to

every check you write, then jump to

references/report.md and use the relevant surface

recipes below to capture its evidence. Publish that authored plan and its

cases together with lh acceptance run ingest.

One read tells you what to prove ($OPERATION_ID is the id this run was given):

lh verify plan state "$OPERATION_ID" --json

Each verifyPlan[] item carries id (the checkItemId), title, required, and verifierConfig.requiredEvidence ([{ type, hint }] — the artifacts you MUST capture). The checkItemId is the only handle you need: lh acceptance run result submit (Step 3) keys off it plus your operation id and creates the result row for you, so you do not need a checkResultId up front. (Result rows generally don't exist yet at this point — that's expected.) Exact shapes: references/plan-format.md.

Only items with a non-empty requiredEvidence need an artifact. Items without

it are judged on the deliverable text alone — don't fabricate evidence.

Step 2 — Pick the surface by what you changed

The criterion's hint usually implies the surface. Match the change you made to the cheapest surface that can actually prove it, and escalate only if needed: