acceptance

# 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). | Delivery state | Action | | ------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Documentation/instruction-only change, or pure refactor/tooling change with no product behavior change | Skip product acceptance and briefly state why. Keep any applicable quality checks. | | Gitlink-only sync | Do not launch a fresh acceptance. Link the upstream change and its existing acceptance when available; disclose missing upstream evidence without claiming it passed. Cloud changes accompanying the sync are assessed separately. | | Completed acceptance already published and still covers the delivery | Reuse its URL and coverage. Do not create a round or rerun cases just for the PR. | | Completed acceptance report and evidence exist locally and still cover the delivery | Inspect coverage and artifacts, then upload that report using [report.md](references/report.md). Preserve the original execution provenance; no product rerun, new plan, or repeated completed checker review is needed merely for upload. | | The delivery was already exercised on the real product earlier in this session (observations and raw artifacts exist, no report yet) | Do not rerun, re-plan, or open a checker stage. Write `plan[]` and `cases[]` from the observations already made, attach the original artifacts (logs, command output, captures) with their original provenance, disclose any required medium that was never captured instead of recapturing it, and ingest. | | Product behavior lacks valid evidence, or relevant behavior changed after verification | Execute only the missing or affected outcomes, retain unaffected evidence with its original provenance, and publish according to the round rules below. | 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. ## Execution ownership and independent review For new execution, use one fresh-context `acceptance-runner` for environment preflight, planning, product interaction, capture, report assembly, publication, and cleanup. Explicitly select a lighter model with the required tools; do not inherit the builder's full conversation or default high-cost model. The primary keeps scope, product decisions, code repairs, and delivery accountability, and coordinates through brief reports. Reuse the runner for follow-ups. Read [delegation.md](references/delegation.md) once to assign source ownership, model capability, budgets, and handoffs. Each unchanged source section, runtime probe, and evidence inspection has one owner: pass its acquired facts and provenance, rather than fetching it again in another agent. Workers load only their role instructions and needed references, not this entire entrypoint. Use one `acceptance-checker` in the first round: at most two plan-feedback responses before execution, then exactly one final report/evidence review. It is the default owner of verdict-bearing media inspection; the runner captures and indexes that media without pre-reviewing it. Read [acceptance-checker.md](references/acceptance-checker.md) only in that owner. The checker is the plan gate; never ask the user for routine plan approval. The primary resolves findings and tells the runner when execution or publication may proceed. There is no per-case approval loop or repeated full review after fixes. Follow-up rounds have no independent checker gate. Assign new artifact inspection to one capable owner and re-run only affected cases. If delegation is unavailable, use one bounded execution context and disclose missing independent review. If model selection is unavailable, record the actual or inherited model rather than claiming lower cost. Retain all evidence requirements in either fallback. ## Read the project layer first Before touching an environment, its execution owner checks for `.agents/acceptance/`. Reuse sections and facts already acquired for the same revision; other agents receive the relevant rules and provenance in their handoff instead of independently reading these files: | File | What it owns | | ------------------------ | ------------------------------------------------------------ | | `PROJECT.md` | Start/stop commands, ports, services, auth, surfaces, probes | | `PROCESS.md` | The run process: plan gate, execution rules, teardown | | `common-mistakes.md` | Project living log — what earlier rounds got wrong here | | `probe-mock-patterns.md` | Project living log — how to force state on this product | 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](references/project-adapter.md). ## Living logs — inject each by its own shape The execution owner acquires the relevant generic and project sections once the target is known and records their versions in the shared handoff: - **[common-mistakes.md](references/common-mistakes.md)** — acquire its **Checklist** once. Assign applicable lines to the execution or inspection owner, and apply those retained rules before `pass`; do not re-read the file for each case. Pull an entry by id only when its detail is needed and not already acquired. - **[probe-mock-patterns.md](references/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. ```bash 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. ## CLI discovery Use the installed `lh` as the command reference. The assigned execution or publishing owner consults the relevant subcommand's `--help` only when syntax or capability is unknown, and records the learned usage by CLI version. Reuse that result across stages and agents; do not walk the whole help tree, repeat discovery for every case, or invoke a write command to probe support. Prefer CLI-provided schemas, examples and non-publishing validation. Read a linked payload schema or legacy recipe only when the installed CLI lacks that capability. Help teaches syntax; the rules below retain subject/operation identity, immutable rounds, evidence coverage, language and safe recovery. Inspect structured errors and ingest warnings; successful JSON parsing or a zero exit code alone does not establish publication or complete coverage. ## 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`. | You have | Path | | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | | No plan — you author the checks | Write `result.json` + `assets/`, publish with `lh acceptance run ingest` — [report.md](references/report.md) | | An operation id you were given | Read the frozen plan, write the same round directory keyed by its check item ids, publish with `ingest --operation` — [plan-format.md](references/plan-format.md) | The paths differ only in where the checks come from and which round the ingest lands in. Capture is identical: the surface guides, recordings with [chapters](references/video-chapters.md), before/after pairs, screenshots inspected by their designated owner, `proposal.md`. A handed-down plan never licenses a lighter capture. 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: the execution or publishing owner runs `lh acceptance preflight --json` once before writing any plan or report text, or reuses its recorded result while server, scope, credentials, and language configuration are unchanged. An auth error means stop and surface it. Install only the UI driver the selected surface needs; probe before adding dependencies, and never substitute a private agent plugin. Its `language.locale` is the **report language**: write every human-readable field (title, plan, case names, observations, evidence descriptions, conclusion, `report.md`, `proposal.md`) in it, even when the prompt that invoked you is in another language — a delegating agent's prompt does not show which language the user reads. The publish commands reject text in the wrong script, so run `lh acceptance run ingest <dir> --dry-run` with the same target flags the publish will use as soon as the plan is in `result.json`, before executing it. Offline `validate` does not check account language or remote plan membership and never replaces this dry-run. Never publish merely to test whether a payload is accepted. When `language.status` is `unset`, use the language the user converses in. On a CLI without `preflight`, check auth with `lh acceptance run list --json`. ## Optional user-journey flows For a requirement with state transitions or independently reviewable journeys, read [flows.md](references/flows.md) only when authoring or updating that graph. Ordinary checklist rounds do not load it. ## 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. ## Rules you will be tempted to skip Not judgment calls — the moves an agent under pressure makes and must not. Each excuse below was made in a real round. | Excuse | Reality |