verify-app

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Verify the app

验证应用

The question this skill answers: which features did this change touch, how do I exercise them on an isolated instance, and what proves they work?

Two parts, after Poteto's verification skills: a remote control (

node scripts/verify.mjs

, no argument lists every command) and a feature map (

docs/verify/

, one file per area with the same four H2s: Sub-features, How to get to it, Driving it with verify, Gotchas). The CLI drives a running instance; it is not a test runner. Compose its commands: never write a driver script for a verification.

The product's part of the CLI (seed states, the server folders

doctor

watches, extra

up

flags, the browser's locale and permissions, the report's words) lives in

scripts/verify-app.mjs

; the rest is the same in every app.

本 skill 要回答的问题是：本次变更触及了哪些功能、如何在隔离实例中操作这些功能，以及有什么证据证明它们能正常工作？

在 Poteto 的验证 skills 之后，它分为两部分：一个 remote control（

node scripts/verify.mjs

，不带参数时会列出所有命令）和一个 feature map（

docs/verify/

，每个领域一个文件，均使用相同的四个 H2：Sub-features、How to get to it、Driving it with verify、Gotchas）。该 CLI 用于驱动正在运行的实例，而不是 test runner。组合使用这些命令：验证时绝不编写 driver script。

CLI 中与产品相关的部分（seed 状态、

doctor

监视的 server 文件夹、额外的

up

flags、浏览器的 locale 和 permissions、报告措辞）位于

scripts/verify-app.mjs

；其余部分在所有应用中都相同。

Pick a flow

选择流程

Every checkout gets its own instance: port, data folder, browser and logs are derived from the checkout's path and live in

.verify/<port>/

. A git worktree (

git rev-parse --git-dir

) never fights the main checkout or another agent's worktree.

Fresh worktree or clone:
```
node scripts/verify.mjs setup
```
installs dependencies and Chromium if missing, builds the page,
```
up
```
,
```
doctor
```
.
Already set up:
```
up
```
then
```
doctor
```
.
Done:
```
down
```
;
```
cleanup
```
deletes this instance's data and logs (
```
cleanup --all
```
also reports, traces, screenshots). Remove a worktree yourself, from the main checkout, once its branch is pushed.

doctor

must print

fresh

. Otherwise it names the problem:

STALE BUNDLE

(run

npm run build

STALE SERVER

or commit changed (

down

then

up

WRONG INSTANCE

(the port or the browser belongs to something else).

每个 checkout 都有自己的实例：端口、数据文件夹、浏览器和日志均根据 checkout 的路径生成，并存放在

.verify/<port>/

中。Git worktree（

git rev-parse --git-dir

）不会与主 checkout 或另一个 agent 的 worktree 发生冲突。

全新 worktree 或 clone：
```
node scripts/verify.mjs setup
```
会在缺少依赖和 Chromium 时进行安装，然后构建页面、执行
```
up
```
和
```
doctor
```
。
已经设置完成： 执行
```
up
```
，然后执行
```
doctor
```
。
完成： 执行
```
down
```
；
```
cleanup
```
会删除该实例的数据和日志（
```
cleanup --all
```
还会清理 reports、traces 和 screenshots）。分支 push 后，需从主 checkout 中自行移除该 worktree。

doctor

必须打印

fresh

。否则，它会指出具体问题：

STALE BUNDLE

（运行

npm run build

）、

STALE SERVER

或 commit 已发生变化（先

down

，再

up

）、

WRONG INSTANCE

（端口或浏览器属于其他实例）。

Procedure

操作步骤

```
node scripts/verify.mjs features
```
: name every area the change affects; read only those files (
```
features <area>
```
), plus
```
journeys
```
when the change crosses areas. Read the laws the change touches in
```
docs/INVARIANTS.md
```
.
```
node scripts/verify.mjs check
```
: the gate, the project's check command (
```
project.md
```
): lint, the contracts (feature map, laws, architecture rules), unit tests, formal models, typecheck + build, bundle secrets, end-to-end journeys. It must pass before anything else counts.
```
check --fast
```
while iterating;
```
contract
```
alone needs no install. Formal models need Java: without it they are NOT RUN, and the gate says "incomplete", never "passed" (
```
formal/README.md
```
).
```
setup
```
or
```
up
```
+
```
doctor
```
→
```
fresh
```
.

report <area…>

writes

.verify/report-<branch>.md

, the template you fill.

Put the instance in the state you need with
```
seed <state>
```
instead of clicking through;
```
reset
```
for a blank instance. For running states (a reload or a switch mid-run):
```
down
```
then
```
up --delay 4000
```
.

mark "<what you test>"

, then drive the feature the way a person does:

open

click

type

upload

press

wait-settle

Collect the proof:
```
api <route>
```
after the action and after a reload (
```
open "/"
```
reloads);
```
network-summary --since-mark
```
(the requests the action made, statuses, failures);
```
console --errors --since-mark
```
(no page error);
```
snapshot
```
, or
```
screenshot
```
for the product owner.
```
trace start
```
…
```
trace stop
```
when a reviewer must replay the action (
```
npx playwright show-trace <zip>
```
);
```
perf
```
for a page-weight question.
Front laws on any state:
```
a11y
```
(controls without an accessible name, tab order: APP-F6),
```
viewport 375 812
```
then
```
overflow
```
and
```
screenshot
```
(phone width: APP-F7), then
```
viewport 1440 900
```
.
Fake models by default: they check the plumbing, not the wording. For a change to what an agent writes, say that it needs
```
up --real
```
. Use
```
up --real
```
only for agent behaviour, with the Codex login in
```
CODEX_AUTH_FILE
```
.
If the change adds or changes something a person can see, update its file in
```
docs/verify/
```
in the same branch (and a journey in
```
test/e2e/
```
when it crosses areas).
```
check
```
refuses a file without the four H2s. If it changes how a law is proved, update
```
scripts/verify/VERIFY.json
```
:
```
check
```
refuses a law with no evidence and no recorded deferral.

```
node scripts/verify.mjs features
```
：列出变更影响的每个领域；只阅读这些领域对应的文件（
```
features <area>
```
），如果变更跨越多个领域，还要阅读
```
journeys
```
。阅读变更在
```
docs/INVARIANTS.md
```
中触及的规则。
```
node scripts/verify.mjs check
```
：运行 gate，即项目在
```
project.md
```
中定义的 check 命令，包括 lint、契约检查（feature map、规则、架构规则）、单元测试、形式化模型、类型检查 + 构建、bundle secrets 检查以及端到端 journey。其他验证产生效力之前，它必须通过。迭代期间可使用
```
check --fast
```
；单独执行
```
contract
```
无需安装依赖。形式化模型需要 Java：没有 Java 时，它们会显示为 NOT RUN，gate 会报告
```
incomplete
```
，绝不会报告
```
passed
```
（
```
formal/README.md
```
）。
执行
```
setup
```
，或
```
up
```
+
```
doctor
```
→
```
fresh
```
。

report <area…>

会写入

.verify/report-<branch>.md

，这是需要填写的模板。

使用
```
seed <state>
```
将实例置于所需状态，不要通过逐项点击完成；使用
```
reset
```
清空实例。需要以运行状态启动时（中途 reload 或 switch），先执行
```
down
```
，再执行
```
up --delay 4000
```
。
执行
```
mark "<what you test>"
```
，然后像用户一样操作功能：使用
```
open
```
、
```
click
```
、
```
type
```
、
```
upload
```
、
```
press
```
和
```
wait-settle
```
。
收集证据：操作后及 reload 后执行
```
api <route>
```
（
```
open "/"
```
会触发 reload）；执行
```
network-summary --since-mark
```
（查看该操作发出的请求、状态和失败情况）；执行
```
console --errors --since-mark
```
（确认没有页面错误）；执行
```
snapshot
```
，或为 product owner 提供
```
screenshot
```
。当 reviewer 需要重放操作时，执行
```
trace start
```
…
```
trace stop
```
（
```
npx playwright show-trace <zip>
```
）；涉及页面重量问题时执行
```
perf
```
。
任何状态下都要检查前端规则：
```
a11y
```
（缺少 accessible name 的控件、tab 顺序：APP-F6），
```
viewport 375 812
```
，然后执行
```
overflow
```
和
```
screenshot
```
（手机宽度：APP-F7），最后执行
```
viewport 1440 900
```
。
默认使用 fake models：它们检查的是基础链路，而不是文案。若变更涉及 agent 写入的内容，应说明需要
```
up --real
```
。仅在涉及 agent 行为时使用
```
up --real
```
，并在
```
CODEX_AUTH_FILE
```
中提供 Codex 登录信息。
如果变更新增或修改了用户可见内容，需在同一分支中更新
```
docs/verify/
```
下的对应文件；如果变更跨越多个领域，还要更新
```
test/e2e/
```
中的 journey。
```
check
```
会拒绝缺少四个 H2 的文件。如果变更改变了某项规则的证明方式，需更新
```
scripts/verify/VERIFY.json
```
：
```
check
```
会拒绝既无证据也无延期记录的规则。

Proof bar

证明标准

A proof exercises the production path and shows the result a skeptical reviewer would accept.

Drive through the page and its normal server calls.
```
eval
```
reads state after the user path ran;
```
post
```
only prepares a state, like
```
seed
```
: neither is the proof.
```
api
```
/
```
post --bearer <token>
```
act as that token's identity.
A proof from an instance that is not
```
fresh
```
is not evidence.
Cover every reachable entry point and the success, failure, empty, cancel/rerun and persistence paths the change can affect (the area file lists them;
```
page.route
```
in a journey, or a stopped server, makes a request fail).
Show the trigger and the stable end state together (
```
mark
```
, the action, the
```
--since-mark
```
evidence).
Side effects, not pixels: the stored record (
```
api /api/<route>
```
), the run row (
```
api /api/runs
```
), the state after a reload or a
```
down
```
/
```
up
```
.
Fake models count only because they sit behind the production boundary (the model provider, under the same runtime, server and web). Anything that skips the web or the server is not coverage of the page.
Name what you could not reach (native file picker, OS drag and drop, real provider, production only) and the closest real path you covered instead.

证明必须走生产路径，并展示审慎的 reviewer 能够接受的结果。

通过页面及其正常 server 调用进行操作。
```
eval
```
读取用户路径执行后的状态；
```
post
```
只像
```
seed
```
一样准备状态：二者都不是证明。
```
api
```
/
```
post --bearer <token>
```
以该 token 的身份执行操作。
来自非
```
fresh
```
实例的证明不构成证据。
覆盖变更可能影响的每个可达入口，以及成功、失败、空状态、取消/重跑和持久化路径（领域文件会列出这些路径；journey 中的
```
page.route
```
或停止 server 可使请求失败）。
同时展示触发动作和稳定后的最终状态（
```
mark
```
、操作以及
```
--since-mark
```
证据）。
关注副作用，而不是像素：已存储的记录（
```
api /api/<route>
```
）、run 行（
```
api /api/runs
```
）、reload 或
```
down
```
/
```
up
```
后的状态。
Fake models 只有位于生产边界之后才具有证明力（model provider 位于相同的 runtime、server 和 web 之下）。任何绕过 web 或 server 的做法都不算覆盖页面。
说明哪些内容无法触达（native file picker、OS 拖放、real provider、仅生产环境可用的功能），并说明所覆盖的最接近真实路径。

Evidence, cheapest adequate first

证据：优先采用成本最低但足够充分的层级

text

lint + contracts + unit tests → formal models → end-to-end journeys (fake models)
→ driven instance (verify) → real models on the instance (up --real)
→ the people's own use

A passing layer never proves a claim of a higher layer: a green unit test says nothing about the page; a fake-model journey says nothing about the wording.

text

lint + contracts + unit tests → formal models → end-to-end journeys (fake models)
→ driven instance (verify) → real models on the instance (up --real)
→ the people's own use

某一层通过，绝不能证明更高层的主张：unit test 全绿说明不了页面是否正常；fake-model journey 说明不了文案是否正确。

Never

绝不做

Real user data anywhere in the repository, tests, fixtures, reports or committed screenshots: only invented data.
Production as a test bed. The
```
verify up
```
instance is yours; production is the users' (
```
docs/verify/deploy.md
```
is read-only checks after a deploy).
"Verified" from a merge, a green CI or a deployment: what ran where is the release skill's question, and "unknown" is a valid answer.

仓库、测试、fixtures、reports 或已提交的 screenshots 中绝不包含真实用户数据：只能使用虚构数据。
不要把 production 当作测试床。
```
verify up
```
实例归你使用；production 属于用户（
```
docs/verify/deploy.md
```
仅用于部署后的只读检查）。
不能仅凭 merge、绿色 CI 或 deployment 就声称“Verified”：在哪里运行了什么属于 release skill 的问题，而“unknown”也是有效答案。

Report before calling it verified

在称为 verified 之前编写报告

Fill

.verify/report-<branch>.md

(from

report <area…>

) and paste it in the pull request (the evidence table of

.github/pull_request_template.md

commit,
```
doctor
```
line,
```
check
```
result (and whether formal models ran), models (fake / real);
per area: the paths driven, the commands, the observed side effect (key output);
skipped or unreachable paths: what blocks each one, and the closest real path covered;
what is not proved here (for instance: wording needs real models).

填写

.verify/report-<branch>.md

（由

report <area…>

生成），并将其粘贴到 pull request 中（

.github/pull_request_template.md

的证据表）：

commit、
```
doctor
```
输出、
```
check
```
结果（以及形式化模型是否运行）、所用模型（fake / real）；
按领域列出：所操作的路径、执行的命令、观察到的副作用（关键输出）；
跳过或无法触达的路径：各自的阻碍因素，以及所覆盖的最接近真实路径；
此处未证明的内容（例如，文案需要 real models 才能验证）。