fix(review): qualify user journeys before frontend implementation paths

[huangruiteng]

Goal and delivered outcome

A frontend can pass an author-scripted click path while making users repeat known information, navigate ambiguous settings scopes, or trust stale status. This PR makes the existing author and PR-review workflow establish the ordinary user task and shortest authorized journey before validating the implementation. Review policy revision 12 adds this judgment to the existing problem_context.outcome_impact.user_experience contract; the packet/result schema and decision owner remain unchanged. Results written under policy 11 require fresh review.

Review refinement and scope

The earlier review correctly found that a proposed, steward-specific Golden Query pack cannot be mandatory for every UI task. The workflow now derives acceptance from the request, demonstrated failure, and nearest accepted product contract. It reuses a relevant, accepted Golden Query when one covers the task; a settings task without one remains reviewable. Paired settings examples and an offline author-workflow check guard this fallback. Production-bound interactive UI work requires packaged interaction and state readback; documentation and prototypes must label simulated boundaries rather than claim installation.

The rest of the original process repair remains: compare mandatory navigation, re-entry and confirmations against a valid authority path; inspect populated whole-view composition; follow correction or recovery through the owning state; and distinguish source, fixture, package and installed evidence. This changes review instructions and release-only synthetic decision cases. It does not change an App component, runtime effect, API, permission, or persisted state, and does not itself repair an installed UI.

Validation

Tested head: 06cbc178661e26efb13c4079e87d1e56e18c1113 on current main base b9a34c3e79884ea04464afe1f087b1ff1294ff6a.

Check	Result	Limit
Six affected PR-review test modules	192 passed, 33 skipped	The skipped paid model-decision probes remain release-candidate qualification, not evidence of better model judgment.
Real pr-review CLI	Passed	Same exact PR target emits policy 11 at base and policy 12 at head, with unchanged packet schema and configured no-CI-wait behavior. examples/pr-review-command-smoke.py passed against public fixtures.
Docs, static and diff	Passed	Docs governance smoke, changed-Python Ruff, repository-configured mypy (19 source files), and diff hygiene.
Risk-selected premerge	Passed	5 direct checks, 10 catalog canaries, 8 risk-profile smokes and 1 public-boundary scan; 0 failures, 0 manual holds.
Exact-diff change quality	Passed	Nine-file final scope verified under the goal's strict receipt policy.

The paid probes were intentionally not run. A work-in-progress canary was stopped to incorporate an additional instruction-scope refinement; the complete final-head run above passed. No frontend rebuild is needed because no frontend source, bundle, API, or rendering behavior changed. The CLI and local tests validate the process contract, not autonomous reviewer judgment or an installed user journey.

Boundary

No private task state, credentials, raw run logs, generated output or local paths are in the PR. Both commits carry DCO sign-off. Future-facing review kept one existing packet owner and avoided a new UI-specific engine or acceptance registry.

[cocolord]

REQUEST_CHANGES — [P1] 通用 frontend workflow 把 steward/golden-queries.md 变成了每个 UI 任务的必需验收来源，但该文档自己标为 proposed 且只覆盖 steward 场景；本 PR 自带的 settings 正向案例就没有对应 Golden Query。核心 policy-12 方向和验证本身成立，但这条自动加载的作者指令会制造第二套无法普遍满足的 gate。

动机

本 PR 要修复一个真实的 review 盲点：前端能通过作者自己写出的点击脚本，却仍可能让用户重复输入、经历无意义确认、在错误 target 上操作，或把 fixture 已排序/已新鲜的数据误当 production freshness。现有 policy 11 已要求检查 setup、干预、readback、失败与恢复；此变更进一步要求先定义普通用户任务，再比较最短合法路径、解释每个 mandatory step 的信息或授权价值，并检查 populated whole viewport、真实 owning state 与 fixture/build/install 边界。这个目标能改善长期 review 质量，也不会改变终端用户当前 runtime。

问题在作者侧完整性：root AGENTS.md 会把所有 UI 变更导向新 workflow，而 workflow 说验收必须同时来自 request、demonstrated failure 和“the relevant Golden Query”。被链接的文档明确是 proposed steward evaluation specification，仅列 GQ01-GQ17 的创建、接入、协作、纠偏、材料与规模旅程；它不是通用 settings/storage acceptance registry。这样一个有用的 review 修复在自己的通用 author journey 上留下了不可满足的前置。

改动思路

实现主体复用了正确 owner。build_review_execution_contract 仍是唯一 review policy 来源，OUTCOME_IMPACT_ASSESSMENT.user_experience 在现有字段内增加任务、路径成本、viewport、状态回读和证据边界，没有新增 frontend-only schema；REVIEW_POLICY_REVISION 从 11 提升到 12，让旧结果必须重新执行而不能换标签。root 指令、design、frontend-delivery、capability README 与 self-repair pattern 共同解释同一规则；六个 synthetic negative/positive case 继续走既有 release-only model runner，普通 CI 不发付费调用。

正向真实路径已验证：base packet 发出 revision 11，head packet 发出 revision 12；新 rule 的 fingerprint 变化，result checker 继续按 installed policy 拒绝 stale result。默认 pytest 只执行离线结构与一致性检查，33 个 live decision probe 全部 skipped；显式 LOOPX_REVIEW_LIVE_TEST=1 才进入 provider transport。必要授权也没有被“最少点击”错误移除：accepted_tradeoff 在 long_horizon 和 user_experience 两个维度都必须给出 independent basis 与 bounded recovery。

负向路径是本次 blocker：一个普通 settings UI 改动从 AGENTS 进入 frontend-delivery，已有任务、缺陷与 settings owner，但 Golden Query pack 没有对应案例。此时作者只能硬套一个 steward query、扩张 proposed corpus，或违反“must derive”指令；这与同段“not a second checklist or approval form”直接冲突。最小修复不是新建 schema 或扩充所有 GQ，而是将句子改成“有相关且已接受的 Golden Query 时复用，否则使用 task + demonstrated failure + nearest owning product contract”，再用非 steward settings case 固定 fallback。

具体改动

关键代码讲解

review_contract.py::REVIEW_POLICY_REVISION 把 policy 从 11 升至 12；真实 packet builder 和 result checker 都消费这一 owner，因此兼容行为清晰：packet/result schema 不变，旧 evidence 必须重跑。review_contract.py::OUTCOME_IMPACT_ASSESSMENT 新增 15 行通用 reviewer rule，明确 shortest valid path 不是 universal click limit，必要 consent/correctness 要保留；还要求代表性 populated data、correction/cancel/reload/unavailable 路径、source revision、built/installed surface 和 mocked boundary。这个 generic contract 保持 domain-neutral，没有 substring 分类、第二状态机或新的 authority grant。

test_pr_review_behavior.py::FRONTEND_CASES 添加三组成对案例：重复 Goal 表单、错误 recency、混淆 settings target；positive twins 防止模型把 form/confirmation 一概拒绝。test_pr_review_result_check.py 把 accepted_tradeoff 的 basis/recovery 要求扩展到 user_experience。它们在默认运行中是离线 corpus/checker coverage；只有 release qualification 才实际问模型，README 也明确未运行不能算 pass。

其余变更把同一原则落到 AGENTS.md、design、frontend-delivery、capability README 和 self-repair pattern。exact diff 是 +169/-6：只有一个 15 行 production policy 增量，无 UI、API、持久状态或 runtime effect。架构放置、版本失效、default-off provider 调用和 typed decision values 都合适；阻断只位于 docs/development/frontend-delivery.md:11-18 的通用 acceptance-source 表述。

对主干的风险

自动验证很完整但无法覆盖这个语义反例：review contract/behavior/result-check 共 139 passed、33 expected skipped；real pr-review-command-smoke、docs-governance、changed Python ruff、配置内 19 个文件的 mypy 均通过。第一次 premerge 在 clean worktree 因缺 npm dev dependency 使 semantic scanner 失败；执行 locked npm ci --ignore-scripts 后，同一 scanner 通过，完整 premerge 重跑 19/19 通过（10 catalog canaries、8 risk-profile smokes、1 public boundary），manual hold 为 0。GitHub 当前 28 项 success、5 项预期 skip、0 failure。

这些绿灯证明 packet、checker、文档结构和默认关闭路径没有断，却不能证明每个 frontend task 都有 relevant Golden Query。最强反例正来自本 PR 的 settings fixture：测试要求用户看清 machine/project target，但 GQ 清单没有 settings/storage 条目。受影响范围是所有未来 UI 作者，因为 AGENTS 是自动加载的；错误结果不是 runtime 数据损坏，而是 review 流程被额外 gate 阻塞、验收依据被错误创造或 proposed 语义被提升为当前义务。修复只需收窄一条规则并增加离线 fallback test，无迁移或回滚成本。

Typed-state lens 未发现 substring denylist 或散落 boolean；domain-neutral generic packet 保持良好；behavior change 已通过 revision 12、README 和 PR body 披露；guidance/obligation 的主要问题正是把 proposed Golden Query 写成普遍 mandatory source。另有当前 PR 与 main 已冲突，属于独立 merge-readiness 问题；修复后仍需更新 head 并重跑 exact-head review。

我的整体评价

核心设计值得保留：它把用户任务、交互成本、真实 owner、whole-view composition 和证据限度放回同一个既有 review contract，且没有新增字段、UI-only engine 或默认付费调用。代码量与问题相称，future-facing pass 也已经通过复用单一 policy owner、保持 result schema 稳定、用 revision 明确失效旧证据来完成。

但当前 exact head 63c614284b1d8e9661f828b5ee4d654d6790e40d 不能批准，因为自动加载的作者 workflow 把 proposed、steward-scoped Golden Query pack 误当成所有 frontend 任务的现行必要前置。请做上述条件化 fallback，补一个无 matching GQ 的 settings 任务回归，并在解决当前 base conflict 后重新生成 packet/验证。33 个付费模型 probe 可继续留作 release-only 且如实标为未运行；不要求为本次 PR 启用它们。

English verdict: REQUEST_CHANGES - 63c6142 correctly strengthens policy-12 journey evidence and passes offline, premerge, and CI validation, but the generic author workflow unconditionally depends on a proposed steward-only Golden Query catalog that does not cover its own settings example. Make that reuse conditional with an owning-product-contract fallback and add a non-steward regression; then update the conflicting head and re-run exact-head review.

[mergify]

This pull request has merge conflicts with main and cannot be merged
until they are resolved. Please rebase or merge the base branch, @huangruiteng.

Choose the remote for the base repository, not an out-of-date fork.
For a fork clone, first inspect git remote -v; upstream must point
to https://github.com/loopx-project/loopx.git. If it is absent, add it
with git remote add upstream https://github.com/loopx-project/loopx.git.
Then run:

git fetch upstream
git rebase upstream/main
# Resolve each conflict, git add the resolved files, then git rebase --continue.
git push --force-with-lease origin HEAD

For a same-repository clone whose origin points to
https://github.com/loopx-project/loopx.git, use origin instead of
upstream for fetch/rebase. If you prefer merging the base, use
git merge <base-remote>/main and push normally.

Keep the DCO Signed-off-by trailer on every commit when you rebase.
https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/syncing-a-fork

[huangruiteng]

Approval conclusion (author-owned PR; GitHub blocks formal self-approval)

Exact head: 06cbc178661e26efb13c4079e87d1e56e18c1113. I reviewed the whole PR after the requested refinement; the old REQUEST_CHANGES applies to 63c614284b1d8e9661f828b5ee4d654d6790e40d, not this head.

动机

原问题是前端能通过作者写出的点击脚本，却仍让用户重填已知信息、进入含糊的设置目标，或把 fixture 的顺序与新鲜度当成真实产品状态。PR 的有界目标是修复作者与 PR review 的判断顺序：先建立普通用户任务、最短合法路径、必要授权步骤与状态回读，再解释实现；它并不交付某个 App 页面。上一轮 P1 指出了真实反例：通用工作流把 proposed、仅覆盖 steward 的 Golden Query 当成所有 UI 任务的必需验收源，连本 PR 的 settings 正向案例都不适用。

改动思路

现 head 保留既有 problem_context.outcome_impact.user_experience 与单一 review-policy owner，把任务、交互成本、whole-view composition、失败恢复和证据边界写入 policy 12。作者工作流以请求、已展示的失败和当前产品契约为验收根基；只有相关且已接受的 Golden Query 才复用为案例，没有匹配案例的 settings 任务不会被虚构的前置卡住。自动加载的 AGENTS 指令还限定为面向生产的交互改动；文档与原型需要标明模拟边界，不能声称已安装的状态回读。保留必要同意、正确性校验与显式 apply，不把少点击当成单一指标。

具体改动

关键代码讲解

• review_contract.py::REVIEW_POLICY_REVISION 从 11 升至 12。真实 pr-review CLI 在同一 PR 目标上，主干发出 11、此 head 发出 12；packet schema 未变。结果检查器按安装的 policy 拒绝旧版本结果，不能只改标签。
• review_contract.py::OUTCOME_IMPACT_ASSESSMENT 在既有 user-experience 字段内要求比较最短合法任务路径、强制步骤的信息/授权价值、代表性填充数据、真实 owner 回读及 source/build/install 边界。build_review_execution_contract 是此文本进入实际 packet 的消费点，没有新增 UI 专属 schema 或第二决策源。
• test_pr_review_behavior.py::FRONTEND_CASES 增加冗余表单、虚假最近完成顺序、settings target 混淆的三组成对判断；正向案例保留合法确认。test_non_steward_settings_acceptance_does_not_require_a_golden_query 固定无匹配 Query 时仍可按现有 settings 契约评审的作者工作流。test_pr_review_result_check.py 同时把合法 tradeoff 的独立依据与有界恢复校验覆盖到 user experience。

AGENTS、design、frontend-delivery、capability README、历史 probe 说明和 self-repair pattern 都指向这一个流程；冲突重放保留了主干已有的 self-repair 行，没有抹掉相邻修复。九个文件的 diff 是同一 review-process 修复，没有组件、bundle、API、权限或持久状态修改。

对主干的风险

最大风险不是运行时数据，而是自动加载的作者指令使普通 UI 工作被无关验收卡住，或把原型误报为已安装交互。上一轮 P1 的 settings 反例和我检查到的原型边界均已收窄。typed-state lens 未发现字符串 denylist 或第二状态分类器；通用 packet 保持领域中立；policy 11→12、README 与 PR body 明示默认评审行为变化；文档规范与机器强制的 revision/字段检查分开。没有 opt-in 功能主张，因而不把自动加载的指导伪装成 default-off 隔离。

最终 head 的六个 review 测试模块为 192 passed、33 skipped；真实 CLI 基线/head 对照、pr-review-command-smoke.py、docs-governance、Ruff、仓库配置 mypy（19 个目标文件）、diff 检查均通过。风险选取的 premerge 完成 5 个 direct、10 个 catalog、8 个 risk-profile 与 1 个 public-boundary 检查，0 failure、0 manual hold；九文件质量收据精确有效。Goal 配置 wait_for_ci=false，未查询远端 CI。33 个付费模型判断 probe 属于 release qualification，此次有意未运行；离线绿灯不能证明模型在所有真实情境下会做对判断。没有 App 代码变更，故无需前端重建，也不宣称安装后用户旅程已修复。

我的整体评价

这一版解决了原 PR 的流程盲点，也消除了评论指出的第二道虚构验收门槛。相对于不合并，reviewer 会得到新的任务路径判断；相对于另建 UI review 引擎，沿用一个 policy owner、现有证据字段和结果检查器更容易回滚。相关的 future-facing pass 已应用于验收来源和原型范围，剩余模型判断质量留给既有 release-only probe，不能用本次通过推断。对这个有界的 process-repair 目标，我在上述证据与限制下批准 exact head。

English verdict: APPROVE - 06cbc17 fixes the proposed steward-query gate and prototype-scope overreach while preserving the task-first policy-12 design. The exact-head CLI, 192 offline tests, risk-selected premerge, public-boundary scan, and quality receipt pass; 33 paid model probes remain unrun release-only evidence.