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

AGENTS.md

@@ -245,6 +245,11 @@ gates.
 
 Apply the whole-viewport attention review in `docs/development/design.md`
 ("Earn The User's Attention") before implementation and in PR visual evidence.
+For production-bound interactive UI changes, carry one ordinary user task through
+`docs/development/frontend-delivery.md`: compare the shortest authorized journey
+before coding, validate the packaged interaction and owning state, and distinguish
+proposed changes from installed behavior. For documentation and prototypes, name
+the simulated boundary without claiming packaged or installed readback.
 
 Before changing or reproducing any LoopX UI, read and follow the repository-root
 `docs/development/design.md`. This includes websites, dashboards, desktop applications,

docs/development/design.md

@@ -260,6 +260,12 @@ bounded horizontal scrolling.
 
 ## UI Reproduction Workflow
 
+For feature development, carry one user task through the
+[task-first delivery workflow](frontend-delivery.md#task-first-delivery--从用户任务开始).
+A visually consistent composition must also eliminate unnecessary re-entry and
+confirmation, identify the affected target, and show truthful state after action.
+
+
 For UI implementation, migration, or reproduction:
 
 1. Read this file before editing.

docs/development/frontend-delivery.md

@@ -6,6 +6,82 @@ validation only; resolving a source merge followed by a build produces one
 coherent HTML/JavaScript/CSS set. Do not concatenate competing HTML entrypoints or
 asset-retention manifests when resolving an older PR.
 
+## Task-first delivery / 从用户任务开始
+
+Use the existing task/PR delivery brief, not a second checklist or approval form.
+Production-bound interactions require packaged task and state readback. For a
+prototype or documentation example, compare the proposed journey but label its
+simulated boundary instead of claiming that the interaction is installed.
+Before implementation, name one ordinary request, its current failure, the
+observable result, affected entrypoints and existing state/effect owner. Derive
+acceptance from that request, a demonstrated failure and the nearest accepted
+product contract, before designing components or copying the current click
+sequence into tests. Reuse a relevant, accepted
+[Golden Query](../product/use-cases/steward/golden-queries.md) when one covers the
+task; proposed or unrelated queries can inform exploration but are not a
+mandatory acceptance source. If none applies, the task, failure and owning
+contract still define acceptance. Inspect current main and related work first.
+A passing implementation-shaped test is not an independent experience oracle.
+
+Carry the same task through these steps:
+
+1. **Compare the journey.** Write the current and proposed user steps in the
+   existing before/after evidence. Count required navigation, information the
+   user must repeat, questions, confirmations and recovery effort. Explain the
+   information, authority or unavoidable prerequisite supplied by each required
+   step; remove a step that supplies none. This is a comparison, not a universal
+   click limit. Keep necessary scoped consent and explicit effect confirmation;
+   make optional refinement optional. A complete conversational draft should not
+   require a second form just to repeat the same facts.
+2. **Choose the owner and composition.** Reuse the existing typed state and
+   action owner and inspect companion App/CLI/messaging paths. Follow
+   [design.md](design.md#earn-the-users-attention) for the whole viewport, not
+   individual cards. Navigation follows user purpose; clearly show the target
+   and source of a setting. Do not expose storage scopes as competing pages or
+   list controls that cannot apply to the selected target.
+3. **Implement and challenge.** Use the smallest meaningful regression derived
+   from the accepted outcome. Select realistic populated data and one negative
+   or recovery path likely to falsify the claim: multiple owners, out-of-order
+   timestamps, stale/disconnected state, duplicate click, cancellation or reload.
+   Select by the touched risk, not all cases for every patch. Reuse shared TS
+   projections; fix the owning selector rather than sorting an already-sorted
+   mock or adding a frontend-only source of truth.
+4. **Walk the actual product.** Start at the affected user entry, use the built
+   packaged surface, inspect the rendered viewport, perform the task and read
+   back the result. Validate affected narrow/keyboard/language behavior. Pair
+   browser fixtures with the real owning backend when they replace the rule
+   being claimed. Use disposable synthetic state; do not alter active Goals.
+   Record source/build identity and fixture boundaries. Source preview, packaged
+   browser, installed App and real model each prove different things.
+5. **Review the task before the diff narrative.** The review capability's
+   `problem_context.outcome_impact.user_experience` references the same journey
+   and validation, then asks what remains wrong even if every test passes.
+   Reused evidence needs its revision and unchanged assumptions. A material
+   unsupported claim remains unproven. A necessary confirmation can be accepted
+   with its authority basis; green CI cannot justify redundant confirmation.
+6. **Deliver and read back.** Report the observable improvement, evidence limits
+   and whether code is proposed, merged, packaged or installed. After an
+   authorized upgrade, reopen the exact installed surface and check the same
+   task; a pushed PR does not repair an already-running App. Use existing
+   install/release owners and retain the previous working version for rollback.
+
+Public PR evidence should fit in the existing summary/validation: one short
+before/after journey, a screenshot or clip for the affected visual composition,
+and the state readback plus tested revision and limits. Keep private messages,
+local paths and raw run logs out. The existing public first-screen preview gate
+still applies; do not add user approvals for routine implementation decisions.
+
+**Evaluation cadence:** ordinary work runs offline regressions and affected
+browser/backend checks. Paid model interpretation and review-decision probes
+belong to release-candidate qualification, with failures/skips retained. A
+scripted browser passing cannot certify model intent recognition; an unrun live
+probe is not a pass. See [release readiness](../product/release-readiness.md).
+
+中文要点：先定义用户想完成的事，再比较最短合法路径；复用已有授权与状态归属，
+减少重填、重复确认和页面跳转。以真实构建页面、代表性数据和状态回读验收，区分
+模拟边界、打包验证和安装生效。评审先挑战交互成本与证据，再解释代码；平时不跑
+付费模型评测，不用测试数量或 PR 合并代替用户任务完成。
+
 ## Source development and updates
 
 Prepare Python with `uv sync --extra test`, then run from the repository root:

examples/fixtures/pr-review-history/README.md

@@ -54,11 +54,17 @@ Run from the checkout root:
 
 ```sh
 uv run --extra test python -m pytest tests/capabilities/test_pr_review_body.py -q
-# Requires the normal process-only provider credentials; no tools or writes.
+# Release qualification only; normal process-only credentials, no tools or writes.
 LOOPX_REVIEW_LIVE_TEST=1 uv run --extra test python -m pytest \
   tests/capabilities/test_pr_review_behavior.py -k historical -q
 ```
 
+The same release-only runner also contains paired synthetic frontend cases for
+redundant confirmation, recent-completion ordering and settings target clarity.
+Run the full `test_pr_review_behavior.py` suite without `-k historical` to include
+them at release qualification. Routine PRs run offline checks with live calls
+disabled. Positive twins prevent a blanket rejection of forms or confirmation.
+
 Live results qualify reasoning over supplied evidence only. They do not
 demonstrate autonomous repository investigation, rerun the old provider
 concurrency tests, or establish an improvement over a baseline model. No

loopx/capabilities/pr_review_queue/README.md

@@ -63,6 +63,19 @@ continuation, retry/restart, competing work, truthful status, intervention cost
 and correction/recovery. Reuse walkthroughs and validation references rather
 than producing a second report or requiring a soak for every change.
 
+Policy revision 12 makes that journey comparison concrete within the existing
+fields: compare required steps with the shortest valid authorized path, justify
+each mandatory question/confirmation, inspect populated whole-view composition,
+and distinguish fixture, packaged and installed evidence. No new result field,
+UI-only capability or second review authority is added. The checker still
+validates declarations rather than usability; the reviewer must execute and
+inspect the evidence. The paired frontend cases in `test_pr_review_behavior.py`
+challenge unnecessary forms, misleading recency and scope-confused settings,
+with positive controls preserving legitimate consent. These reasoning probes
+run only for release qualification; offline checks do not certify model quality.
+LoopX authors use the [frontend delivery workflow](../../../docs/development/frontend-delivery.md);
+reviews of other repositories follow their own product contracts.
+
 Legitimate safety, budget and dependency waits can be an `accepted_tradeoff`
 with an independent acceptance basis and bounded cost/recovery. Do not weaken
 authority to manufacture progress. A scoped `not_applicable` still names the

loopx/capabilities/pr_review_queue/review_contract.py

@@ -7,7 +7,7 @@
 from .review_body import REQUIRED_FINAL_SECTIONS, review_body_requirements
 
 # Increment when review requirements change without changing the packet shape.
-REVIEW_POLICY_REVISION = 11
+REVIEW_POLICY_REVISION = 12
 
 # A red check is an observation, not evidence that the reviewed PR caused it.
 # This contract belongs to review judgment; merge readiness still owns whether
@@ -54,6 +54,21 @@
         "For user_experience, compare the real affected CLI, UI or messaging journey: setup and "
         "repeated intervention, truthful state/readback, actionable failure, correction/cancel and "
         "recovery. Inspect existing companion surfaces; a backend success is not a usable journey. "
+        "For an affected user journey, establish the ordinary task and expected result before "
+        "reading the implementation path. In existing before_after and walkthrough evidence, "
+        "compare required navigation, re-entry of known information, clarification, confirmation "
+        "and recovery steps with the shortest valid path through the existing authority boundary. "
+        "Explain what new information or authority each mandatory step supplies; a form that "
+        "works can still be redundant. Optional editing is not a mandatory decision. Do not "
+        "remove necessary scoped consent or correctness checks to minimize clicks. "
+        "For visible changes inspect the rendered whole viewport with representative populated "
+        "data, not only component presence: target/owner, hierarchy, truthful freshness/order "
+        "and the next action must be understandable together. Follow one risk-relevant "
+        "correction, cancel, reload or unavailable path through state readback. Identify source "
+        "revision, built/installed surface and any mocked boundary in existing evidence refs. "
+        "A fixture that supplies fresh sorted data cannot prove production freshness or sorting; "
+        "a screenshot cannot prove persistence or adoption. Reuse unchanged evidence with an "
+        "invalidation check; do not demand every viewport/state or paid model calls per PR. "
         "Reuse concrete walkthrough and validation references; select bounded cases by changed "
         "risk rather than requiring a long soak or every surface for every PR. Derive expected "
         "outcomes from the accepted product contract, not from the patch. A deliberate safety, "

skills/loopx-self-repair/references/repair-patterns.md

@@ -13,7 +13,7 @@ teaches a reusable control-plane lesson.
 | `acceptance_hold_recovery_selection_split` | Newly created advancement work is acceptance-unbound, repeated vision replans never expose its hold, or a replan packet also selects an unrelated due monitor. | Canonical acceptance tasks, scoped source Todos, bounded trigger checkpoints, effective action and original Turn receipt. | Recovery covered stale associations only; generic vision gaps displaced hold identities; candidate inventory leaked into the selected execution target. | Route missing and stale associations through the existing bounded replan lane, retain exact hold checkpoints before generic gaps, and separate replan from candidate selection. Keep owner association and completion validation enforced. A new unbound repair Todo is not runnable recovery; only a qualified successor or concrete blocker settles the exact hold. Validate real File/SQLite CLI paths and receipt reentry without mutating an active Goal. |
 | `acceptance_validation_failure_flattened` | A bound Todo is `ready` and its ordinary validator passes, yet completion reports only `goal_acceptance_validation_rejected`; the agent searches contract bindings before discovering a workspace or runner failure. | Exact Todo acceptance state, completion's typed criterion failure, recorded delivery workspace, current worktree cleanliness, and the privacy-safe runner receipt. | The completion boundary collapsed a failed criterion receipt into a generic contract error, hiding the workspace or command status. | Project the failed criterion ID, allowlisted validation status, safe exit code and bounded next action without command output or local paths. Repair the execution context and retry under the same Turn/lease; do not rebind owner criteria or infer a Goal-wide hold. |
 | `review_compatibility_assumption_gap` | A correct fix retains parallel protocol paths, and the review treats historical receipt recovery as proof that every old request decoder is needed. | Published review, structured compatibility rationale, real caller/deployment inventory, stored request versus receipt shape, and smaller-design readback. | Re-review verifies the last bug but does not separate compatibility obligations or test consolidation; free-text claims pass as evidence. | Replace the capability's existing compatibility rationale with a bounded structured assessment. Distinguish transient requests, independent client rollout and persisted replay formats; compare one typed current contract; preserve real legacy consumers. Cover needless retention and unsafe removal with positive twins. Keep optional simplifications advisory and do not make field completeness certify evidence truth. |
-| `review_outcome_continuity_gap` | Local feature checks pass while later work starves, recovery only records a blocker, or ordinary users face new repeated intervention. | Accepted product outcome, published review, real later invocations, affected user surfaces, durable progress and authorized recovery. | Review proved one operation or prevention of bypass without checking sustained progress and the complete user journey. | Make long-horizon continuity and user experience explicit judgments in the existing problem context. Reuse bounded real walkthroughs; apply scope counterexamples when gates are involved. Accept deliberate waits only with an independent basis and recovery or safe terminal route. Qualify with exact-source historical counterexamples and repaired positive controls; keep old verdicts out of model inputs and distinguish reported historical checks from newly executed tests. Section length and declared evidence cannot certify truth. |
+| `review_outcome_continuity_gap` | Local feature checks pass while later work starves, recovery only records a blocker, or ordinary users face new repeated intervention. | Accepted product outcome, published review, real later invocations, affected user surfaces, durable progress and authorized recovery. | Review proved one operation or prevention of bypass without checking sustained progress and the complete user journey. | Make long-horizon continuity and user experience explicit judgments in the existing problem context. Reuse bounded real walkthroughs; apply scope counterexamples when gates are involved. Accept deliberate waits only with an independent basis and recovery or safe terminal route. Qualify with exact-source historical counterexamples and repaired positive controls; keep old verdicts out of model inputs and distinguish reported historical checks from newly executed tests. Section length and declared evidence cannot certify truth. For frontend friction, compare the shortest authorized task path before encoding the UI sequence; inspect populated composition and real state readback. Record fixture/build/install boundaries and repair the existing delivery workflow, not a second checklist. |
 | `source_context_legacy_downgrade` | An unstamped record mutates state through a legacy path after the authoritative source disappears, although another record in the same owner context preserves an exact source identity. | Selected record identity, all same-context durable candidates, source path availability, operation entrypoint, and business-file bytes before and after refusal. | The adapter treated one selected record's missing identity as proof that the whole context was legacy and ignored exact historical evidence when the current authority could not be read. | Resolve source-context availability once for selection and mutation. Exact history may prove that legacy fallback is unsafe, but it must never supply or guess the current identity. Fail closed before writes when authority is unavailable; preserve contexts with no exact history through opposite legacy controls across every mutation entrypoint. |
 | `archive_capture_classification_gap` | Whole-Goal capture rejects a reachable archived Agent record although its active read was valid. | Recorded role/class, existing legacy read classification, transitive dependency closure, bootstrap and writer-outbox readback. | Archive storage preserved the role but omitted the resolved class; capture treated missing class as missing authority. | Keep recorded identity separate from compatibility classification. Only a recorded Agent role can adopt the existing read class; use it consistently for closure and materialization. Preserve the class on new archive moves, keep user authority fail-closed, and validate full source capture in disposable real providers without changing the active Goal. |
 | `shadow_proof_transport_amplification` | A large Goal cannot capture its first mutation or finish drain although the same tiny Goal succeeds; RPC rejects an oversized response. | Same source population, base/head serialized response sizes, actual sequence/drain callers, qualified lineage and cursor readback. | A consumer needing progress or partition markers received the full head and every historical projection across the language boundary. | Keep full history verification in the typed owner and return a purpose-specific compact proof. Preserve receipts, sequence and lineage checks; do not raise transport limits, truncate source records or weaken qualification to make the test pass. Cover the old oversized response and real CLI capture, drain and reviewed cutover on a disposable snapshot. |