agent-project-sdlc 0.1.23 → 0.1.25

package/assets/skills/pjsdlc_dev_sprint/SKILL.md

@@ -17,6 +17,8 @@ description: Use during SPRINTING to execute one task from plan.yaml, respecting
 
 开发阶段的 Definition of Done 包含可运行的系统入口/出口。凡技术方案或 task 承诺 API、CLI、server route、service、agent、runtime、adapter、worker、provider、外部发送/写入执行器、配置契约或 live/fixture 双模式边界，当前实现必须提供对应入口、调用方式、初始化方式、输出/副作用边界和验证方式；如果真实入口/出口尚不可运行，不能把 task 当作完成，也不能把缺口留给 TESTING 补 runtime。runtime/app/provider/live 类 task 必须在 `plan.yaml` 声明 `evidence_level.required`、`target_runtime_environment` 和 `self_test_contract`，并按合同交付：`deployed_runtime` 不能用 `unit`、`local_runtime`、`external_provider_live`、provider smoke、fake adapter 或 localhost smoke 单独关闭；`business_handoff_ready` 必须提供 Testing Handoff Contract。Implementation doc 必须写明 `Runnable Entry/Exit`，并在 `Development Evidence` 中记录 `Evidence Level`、`Target Runtime Environment`、`Runnable Entry`、`Observable Exit`、`Client / Server Initialization`、`Config Contract`、`Testing Handoff Readiness`、`Known Missing Runtime Boundaries` 和 `Basic Self-test Evidence`；其中 `Basic Self-test Evidence` 应指向已执行的 `Development Self-Test Report`。确实不适用时也要显式写 `Not applicable` 和具体原因。provider smoke、fixture smoke、fake adapter 或 one-shot smoke 只能证明局部链路，不能单独证明 `Application readiness`。此时应保留或创建 `BLOCKED`/后续 dev task，或通过 RFC/ARCHITECTING 处理边界变更。
 
+UI/frontend/browser/page task 还必须按 `docs.uiux` 和 `docs.design_system` 实现 `.docs/02_experience/**` 中的 screen contracts、interaction states、responsive acceptance、accessibility / focus / keyboard / touch expectations，以及 `DESIGN.md` 中的 design tokens 和 component guidance。开发中不得静默修改 `DESIGN.md` 或 UX contract 来追认实现；开发前发现体验事实缺口，回 `UI_UX_DESIGNING`；进入开发后需要改变体验事实，走 RFC。UI task 的 `Development Self-Test Report` 必须记录 dev server 或 page URL、关键 screen states、responsive check、accessibility/focus smoke，以及必要的 browser / Playwright / screenshot evidence pointer。
+
 `self_test_contract` 是开发阶段自测合同，由 ARCHITECTING 或 RFC_RECALIBRATION 先定义，SPRINTING 负责执行并在 implementation doc 填写 `Development Self-Test Report`。开发者不得在开发结束后用现有实现反推自测合同；如果合同缺失、入口不匹配、required gates 未同步或场景无法执行，要先回到 ARCHITECTING/RFC 或把 task 保持为 `BLOCKED`。自测报告不是 TESTING 阶段产物，也不是 debug log、operator log、runbook 或历史流水；它只证明当前模块级可运行交付边界已经能被 Review/Testing 消费。报告必须写 `Report Status: PASS | BLOCKED | IN_PROGRESS | STALE`，只有 `PASS` 且所有 scenario 都是 `PASS` 才能关闭当前 development task；`BLOCKED`、`IN_PROGRESS`、`STALE` 可以作为恢复事实存在，但不能作为交接通过。报告还必须记录 `Module Key Test Path`：从本地启动或调用入口开始，执行并完成 `self_test_contract` 中全部自测用例的模块关键测试路径。该路径应覆盖本 task / 本模块承诺的所有可运行入口，以及自测用例实际经过的内部关键路径、关键边界、观察点和可观测完成证据，供后续 Agent 复用和 debug。如果合同包含 `graph_required: true` 或 `module_key_test_graph`，开发者还必须沿该 DAG 执行并在报告中写入实际 `Module Key Test Graph`：节点只记录 entry、checkpoint、branch、scenario、observable_exit 和 evidence pointer，边只记录路径流向；不要把图扩成 runtime 搭建、执行 trace、debug log 或证据正文。
 
 开发阶段交付包含两类产物：实现产物（代码、配置、脚本、测试等）和开发自测产物。`Development Self-Test Report` 是开发阶段产物，不是计划、模板或历史记录。若当前 task 或关联技术方案声明 `self_test_contract.status: "required"`，必须先逐条执行 `self_test_contract.scenarios[]` 和 `self_test_contract.required_gates`，再填写或更新 `Development Self-Test Report`。没有本轮执行过的 runnable entry、内部关键路径、observable exit / artifact / screenshot / response / log 等证据时，不得写 `PASS`，不得完成 task。自测报告只保留交接卡字段：`Report Status`、`Contract Source`、`Module Application Entry`、`Module Key Test Path`、`Scenario Results`、`Executed Gates`、`Observable Exit`、`Current Blocker`、`Testing Handoff Readiness` 和 `Evidence Index Refs`；证据正文、长命令输出、截图过程和 UI 操作细节进入 evidence index、外部 artifact 或 `.docs/09_runbooks/**` exploration appendix。主报告目标几十行，fallback / diagnostic 最多一句总结，不写 `Actual Evidence` 正文字段。
@@ -27,6 +29,10 @@ description: Use during SPRINTING to execute one task from plan.yaml, respecting
 
 `/dev` 和 `/devloop` 是开发阶段的两个入口。`/dev` 创建或选择下一个最小 `TASK-*` development task，设置 `phase: "SPRINTING"`，并只完成一个 task 闭环后停止。通用规则是从任何 draft queue promote 正式 `TASK-*` 时都必须同次消费源 draft；当前开发阶段的内置 draft queue 是 `plan.draft.yaml.tasks[]`，因此如果这个 task 来自 `plan.draft.yaml.tasks[]`，promote 时必须同次删除源 draft，避免已采用草案继续显示为 `pending`。`/devloop` 连续运行 `/dev`，直到 `plan.yaml.tasks[]` 和 `plan.draft.yaml.tasks[]` 都没有明确可创建/执行的任务，或遇到需求、架构、allowed_paths、gate、commit/push blocker。
 
+如果是从 `TESTING` 通过 `bugfix_implementation_gap` 直接回到 `SPRINTING`，先创建或选择一个最小 bugfix `TASK-*`，引用 `.docs/07_test/TEST_REPORT.md` 的 failing scenario、既有 tech plan slice 和相关 implementation doc。该路径只用于“技术方案正确但实现偏离”的修复；如果测试证明技术方案、接口契约、任务拆分或 handoff graph 需要修改，应回 `ARCHITECTING`；如果需求或验收标准变化，应走 RFC。
+
+如果测试证明 PRD 和技术方案正确但 UX contract、screen states、handoff matrix 或 DESIGN.md 本身错误，应走 `bugfix_uiux_replan` 回 `UI_UX_DESIGNING`，不要在 SPRINTING 中直接改体验事实。
+
 实现时遵循小步闭环：先检查 `git status`，确认工作区没有未归属到当前 task 的脏变更；再定位相关代码和测试，做必要修改，运行 gate，修复失败，写入或更新相关 implementation doc 并刷新文档派生视图。直接运行 `make validate-dev` 或 `npx sdlc-harness validate-dev` 是开发中 gate，允许当前 `SPRINTING` task 仍然 open，并校验 `current_task_id`、task 合同、dirty files、draft queue 和 implementation doc。此时先不要从 `plan.yaml` 移除当前 task，要在当前 task 仍位于 `plan.yaml` 时创建 task implementation commit；随后再移除 task，创建 task completion ledger commit，并 push 两个 commit。`make validate-current` / `/advance` 是阶段出口 gate，必须在 open task 已移除后才通过。不要顺手重构、重排格式或处理无关问题；如果发现无关风险，只记录或报告。
 
 开发阶段默认先评估当前 task 是否能安全并行。适合时，主 Agent 创建 `parallel_execution.trigger: "workflow_default"` 合同，默认使用 `runtime_managed` + `runtime.provider: "codex_native_subagents"` 调度 worker；用户明确要求并行、多 agent 或多 worktree 时使用 `trigger: "user_requested"`。主 Agent 声明每个 worker 的 `owned_paths`、`forbidden_paths`、`expected_output` 和 `required_gates`；非 native fallback 写仓库时还要声明 `branch` 和 `worktree`。worker 可以在各自非空、互不重叠且属于当前 task `allowed_paths` 的 owned paths 内实现，但不得直接修改 `plan.yaml`、`lifecycle.yaml`、`.docs/INDEX.md`、overview 或最终 implementation doc。主 Agent 负责 review、merge/cherry-pick、运行总 gate、更新事实源和完成两段提交。不适合拆分时继续串行 `/dev` 或 `/devloop` 并记录原因。
@@ -36,7 +42,7 @@ description: Use during SPRINTING to execute one task from plan.yaml, respecting
 - `<harnessRoot>/state/lifecycle.yaml`
 - `<harnessRoot>/state/plan.yaml`
 - `<harnessRoot>/state/plan.draft.yaml`
-- 当前任务关联的 PRD 和技术方案
+- 当前任务关联的 PRD、`.docs/02_experience/**`、`DESIGN.md` 和技术方案
 - 当前源码和测试文件
 
 ## 输出
@@ -62,7 +68,7 @@ description: Use during SPRINTING to execute one task from plan.yaml, respecting
 - task implementation commit 必须发生在 task 移除之前，避免实现变更和计划短期化混在同一个提交里。
 - task completion ledger commit 发生在 implementation commit 之后，只负责将该 task 从当前 `plan.yaml` 移除。
 - 一个开发 task 默认对应一个主要 implementation commit 和一个轻量 completion ledger commit。implementation commit message 应包含 task id，例如 `TASK-003: implement login rate limit`；push 成功前，不进入下一个 task。
-- 本 Skill 不直接重切 PRD 或 tech plan；如果发现上游语义边界错误，进入 `BLOCKED`、创建 RFC，或请求回到 `ARCHITECTING`。
+- 本 Skill 不直接重切 PRD、UI/UX contract 或 tech plan；如果发现上游语义边界错误，进入 `BLOCKED`、创建 RFC，或请求回到 `UI_UX_DESIGNING` / `ARCHITECTING`。从 TESTING bugfix 回流的 `bugfix_implementation_gap` task 也不得重切技术方案；它必须引用 `TEST_REPORT.md` 的失败 scenario 和既有 tech plan，并只修实现偏差。
 - gate 通过后调用 `pjsdlc_implementation_doc`，由该 Skill 按真实实现更新或新增 `.docs/04_implementation/` 模块级 slice。
 - direct dev gate 与 phase-exit gate 语义不同：`validate-dev` 支持当前 open `SPRINTING` task；`validate-current` 在 `SPRINTING` 下仍会拒绝 open task，提示先完成 implementation commit 和 completion ledger。
 - 如果一个任务实际变成多个独立实现边界，应停止扩大范围，拆分后续任务或回到任务规划。
@@ -112,12 +118,14 @@ done task 的执行流水不在当前 `plan.yaml` 长期保留，也不是默认
 - [ ] open task 在 `plan.yaml` 中包含完整执行合同。
 - [ ] 当前任务仍然是单一清晰的执行单元。
 - [ ] 技术方案或 task 承诺的 API/CLI/adapter/worker/provider、配置契约、输出/副作用和 fixture/live 边界已可运行并写入 implementation doc，或已明确 `BLOCKED`/后续 dev task。
+- [ ] UI/frontend/browser/page task 已实现 `docs.uiux` / `docs.design_system` 承诺的 screen contracts、interaction states、responsive、a11y/focus/keyboard/touch 和 DESIGN.md tokens，或已按 RFC/回流路径记录 blocker。
 - [ ] implementation doc `Development Evidence` 已记录 `Evidence Level`、`Target Runtime Environment`、`Runnable Entry`、`Observable Exit`、`Client / Server Initialization`、`Config Contract`、`Testing Handoff Readiness`、`Known Missing Runtime Boundaries`、`Basic Self-test Evidence`，或写明带原因的 `Not applicable`。
 - [ ] 如果当前 task 有 `self_test_contract.status: "required"`，已逐条执行当前 `self_test_contract.scenarios[]` 和 `self_test_contract.required_gates`，并在 implementation doc `Development Self-Test Report` 写入 `Report Status`、本轮 contract source、Module Application Entry、scenario results、executed gates、Module Key Test Path、Observable Exit、Current Blocker、Testing Handoff Readiness 和 Evidence Index Refs，且 `Report Status: PASS`、所有 scenario 都是 `PASS`。
 - [ ] 如果 `self_test_contract.graph_required: true` 或存在 `module_key_test_graph`，已在 `Development Self-Test Report` 写入实际 `Module Key Test Graph`，且 graph 覆盖入口、scenario、observable exit 和 evidence refs。
 - [ ] 如果当前 task 是 high-risk runtime/live/remote-operator 工作，`resume_capsule` 已更新为 5-8 条恢复事实，`recovery_refs` 链接 implementation doc 和 `.docs/09_runbooks/**` runbook/evidence，implementation doc 已填写短的 `Current Operator Path` 和分层 `Gate Breakdown`。
 - [ ] 如果 task 要求 `business_handoff_ready`，implementation doc 已写入 Testing Handoff Contract，包含入口、配置、初始化/health、输入样例、预期出口、清理方式和证据等级。
 - [ ] 如果当前 task 来自 `plan.draft.yaml.tasks[]`，源 draft 已在 promote 时从 draft 列表删除。
+- [ ] 如果当前 task 来自 TESTING bugfix 回流，已确认它是 `bugfix_implementation_gap`，并引用 `TEST_REPORT.md`、既有 tech plan 和 implementation doc；若问题属于 UX contract 或 DESIGN.md，已回到 `UI_UX_DESIGNING`。
 - [ ] implementation doc 已生成或更新，并反映相关模块的真实代码。
 - [ ] 如果启用了 `parallel_execution`，worker owned paths、forbidden paths、required gates 和主 Agent 集成结果已记录。
 - [ ] gate 结果已写入 implementation doc `Verification`，必要时当前 task `working_notes` 也记录了恢复现场所需的 gate evidence。

package/assets/skills/pjsdlc_implementation_doc/SKILL.md

@@ -13,7 +13,7 @@ description: Use after development gates pass to update module-level implementat
 
 你是实现事实记录者，目标是把已经发生的代码变化沉淀成后续 Review、测试、发布和需求变更都能引用的事实。你写的是 implementation doc，不是新的技术方案，也不是对未来工作的承诺。
 
-开始记录前，先读取 task、PRD、技术方案、git diff、测试结果和相关源码。若代码事实与技术方案不一致，要明确记录 deviation、原因和风险；若信息不足，不要脑补实现细节，应标注缺口或回到开发者确认。
+开始记录前，先读取 task、PRD、`.docs/02_experience/**`、`DESIGN.md`、技术方案、git diff、测试结果和相关源码。若代码事实与 UI/UX contract、DESIGN.md 或技术方案不一致，要明确记录 deviation、原因和风险；若信息不足，不要脑补实现细节，应标注缺口或回到开发者确认。
 
 文档应帮助后来者快速理解：某个模块或核心数据流的当前实现是什么、关键对象/函数职责是什么、行为如何从输入流到输出、测试覆盖了什么、还有什么未覆盖。task id 只作为 provenance，不作为默认切片粒度。
 
@@ -21,6 +21,8 @@ implementation doc 只写长期实现事实，不写完整操作日记。对于
 
 如果模块包含或承诺可运行系统边界，implementation doc 必须记录 runnable entry/exit：API/CLI/server route/service/agent/runtime/adapter/worker/provider 的调用方式、初始化方式、配置契约、输入来源、输出或副作用、fixture/live 模式边界，以及哪些真实外部执行器尚未实现。还必须在 `Development Evidence` 中记录开发阶段实际验证过的 `Evidence Level`、`Target Runtime Environment`、`Runnable Entry`、`Observable Exit`、`Client / Server Initialization`、`Config Contract`、`Testing Handoff Readiness`、`Known Missing Runtime Boundaries` 和 `Basic Self-test Evidence`；`Basic Self-test Evidence` 应指向已执行的 `Development Self-Test Report`。确实没有应用入口时，`Not applicable` 必须写清原因。不能把未来才会实现的入口写成当前事实，不能把 provider smoke、fixture smoke、fake adapter 或 one-shot smoke 单独写成 application readiness。如果 task 要求 `business_handoff_ready`，还必须写 Testing Handoff Contract，包含入口、配置、初始化/health、输入样例、预期出口、清理/reset/幂等说明和证据等级。
 
+如果模块包含 UI/frontend/browser/page 边界，implementation doc 还必须记录它消费的 `.docs/02_experience/**` screen contracts 和 `DESIGN.md` design-system facts，说明关键 screen states、interaction behavior、responsive acceptance、accessibility / focus / keyboard / touch expectations 和 token/component usage 是否已实现；偏离时写入 `需要关注的方案偏移`。
+
 如果当前 task 有 `self_test_contract.status: "required"`，implementation doc 必须填写 `Development Self-Test Report`，把设计/RFC 阶段定义的自测合同执行完成：记录 `Report Status: PASS | BLOCKED | IN_PROGRESS | STALE`、contract source、`Module Application Entry`、每个 scenario 的结果、executed gates、`Module Key Test Path`、`Observable Exit`、`Current Blocker`、`Testing Handoff Readiness` 和 `Evidence Index Refs`。`Development Self-Test Report` 是几十行交接卡，不是 debug log、operator log、runbook、evidence dump 或历史流水；不要写 `Actual Evidence` 正文字段。fallback / diagnostic 在主报告最多一句总结，详细命令、截图过程、UI 操作细节和失败路径进入 evidence index、exploration appendix 或 git history。High-risk runtime/live task 还必须写 `Current Operator Path` 和 `Gate Breakdown`，把 canonical operator path、runbook link、credential reference name、command/UI channel、hard constraints、do-not-retry summary 以及 local gate、cloud/service gate、executor/operator readiness、live smoke / handoff 分层记录，不能只写一个大 `validate-dev PASS`。凡会改变下一步动作的判断，必须 promoted 到 `plan.yaml#resume_capsule.do_not_retry` 或 runbook 顶部 `Hard Constraints`，不能只留在 evidence 或 appendix。`Development Self-Test Report` 只能记录当前 task 本轮实际执行后的结果；不得用历史报告、模板字段、代码阅读或无关通用 gate 替代本轮 self-test scenario 执行。`Module Key Test Path` 必须说明从本地启动或调用入口开始，执行并完成 `self_test_contract` 中全部自测用例的模块关键测试路径。该路径应覆盖本 task / 本模块承诺的所有可运行入口，以及自测用例实际经过的内部关键路径、关键边界、观察点和可观测完成证据，供后续 Agent 复用和 debug。如果 task contract 设置 `graph_required: true` 或包含 `module_key_test_graph`，还必须记录实际 `Module Key Test Graph`，用轻量 DAG 展示 entry、checkpoint、branch、scenario、observable_exit 与 evidence refs；图只放路径骨架和证据指针，不放执行 trace、命令输出、截图过程、operator log、debug log、runbook 正文或失败探索。任何 scenario 非 `PASS`，或 `Report Status` 为 `BLOCKED`、`IN_PROGRESS`、`STALE` 时，不得把开发 task 写成完成。
 
 ## 输入
@@ -28,6 +30,7 @@ implementation doc 只写长期实现事实，不写完整操作日记。对于
 - `<harnessRoot>/state/plan.yaml` 中当前 task 的 `implementation_doc` 路径和 task ID
 - 当前 `git diff`
 - 关联 PRD
+- 关联 `.docs/02_experience/**` 和 `DESIGN.md`
 - 关联技术方案
 - 变更后的源码和测试文件
 - `<harnessRoot>/pjsdlc_managed/templates/IMPLEMENTATION_DOC_TEMPLATE.md`
@@ -53,9 +56,10 @@ implementation doc 只写长期实现事实，不写完整操作日记。对于
 3. 与技术方案的偏移必须明确记录，即便该偏移是合理的。
 4. runnable entry/exit、配置契约和 fixture/live 边界必须记录当前事实；缺失项写入 `未覆盖（Not covered）` 或方案偏移。
 5. `Development Evidence` 必须包含 task 合同要求的证据等级、目标运行环境、实际可调用入口、可观察出口、初始化方式、配置契约、测试交接状态、缺失 runtime 边界和开发自测证据；页面类任务记录 dev server/page URL 与 browser check，API/CLI/worker/RPA/service/agent/runtime 类任务记录 startup/invocation command、endpoint/health/status 与 response/output/side effect。
-6. `Development Self-Test Report` 必须记录 `Report Status`、当前 task 本轮执行 `self_test_contract` 中全部 scenario 和 required gates 后的结果，并记录从本地启动或调用入口开始，到完成所有自测用例的 `Module Key Test Path`；路径必须覆盖本 task / 本模块承诺的所有可运行入口、内部关键路径、关键边界、观察点和完成证据，不能只补一句 smoke 结果，也不能复用历史 PASS、模板字段、代码阅读或无关通用 gate 作为本轮证据。若 contract 包含 `module_key_test_graph` 或 `graph_required: true`，报告还必须记录实际 `Module Key Test Graph`。
-7. 测试覆盖必须列出具体测试，或明确记录覆盖缺口。
-8. 文档粒度保持在模块、子系统或核心数据流级别；不要默认按 task 建文档，也不要写成跨全项目的巨型百科。
+6. UI/frontend/browser/page 模块必须记录已消费的 UI/UX slice、DESIGN.md、关键 screen states、responsive / accessibility / focus / keyboard / touch evidence 和 token/component usage。
+7. `Development Self-Test Report` 必须记录 `Report Status`、当前 task 本轮执行 `self_test_contract` 中全部 scenario 和 required gates 后的结果，并记录从本地启动或调用入口开始，到完成所有自测用例的 `Module Key Test Path`；路径必须覆盖本 task / 本模块承诺的所有可运行入口、内部关键路径、关键边界、观察点和完成证据，不能只补一句 smoke 结果，也不能复用历史 PASS、模板字段、代码阅读或无关通用 gate 作为本轮证据。若 contract 包含 `module_key_test_graph` 或 `graph_required: true`，报告还必须记录实际 `Module Key Test Graph`。
+8. 测试覆盖必须列出具体测试，或明确记录覆盖缺口。
+9. 文档粒度保持在模块、子系统或核心数据流级别；不要默认按 task 建文档，也不要写成跨全项目的巨型百科。
 
 ## 完成检查
 
@@ -64,6 +68,7 @@ implementation doc 只写长期实现事实，不写完整操作日记。对于
 - [ ] 真实代码结构表已填写。
 - [ ] 核心数据流已说明。
 - [ ] runnable entry/exit、配置契约和 fixture/live 边界已记录，或缺失项已明确标注。
+- [ ] UI/frontend/browser/page 模块已记录 UI/UX slice、DESIGN.md、screen states、responsive / a11y / focus / keyboard / touch 和 token/component usage。
 - [ ] `Development Evidence` 已记录 `Evidence Level`、`Target Runtime Environment`、`Runnable Entry`、`Observable Exit`、`Client / Server Initialization`、`Config Contract`、`Testing Handoff Readiness`、`Known Missing Runtime Boundaries`、`Basic Self-test Evidence`，或带原因的 `Not applicable`。
 - [ ] 如果当前 task 有 `self_test_contract.status: "required"`，`Development Self-Test Report` 已记录 `Report Status`、contract source、Module Application Entry、scenario results、executed gates、Module Key Test Path、Observable Exit、Current Blocker、Testing Handoff Readiness 和 Evidence Index Refs。
 - [ ] 如果 contract 包含 `module_key_test_graph` 或 `graph_required: true`，`Development Self-Test Report` 已记录实际 `Module Key Test Graph`，且图内只有路径骨架和 evidence pointer。

package/assets/skills/pjsdlc_manager/SKILL.md

@@ -16,7 +16,9 @@ Skill、执行出口 gate，并记录 blocker。
 
 与用户对话时，先读取 lifecycle 和 plan，再说明当前阶段、active_skill、当前任务、阻塞项和下一步。不要基于猜测切换阶段；如果用户要求的动作与当前阶段冲突，说明冲突、可选路径和推荐处理方式。
 
-自然语言是默认控制方式，约定宏指令是更完整、更细节的提示词别名。用户说“状态如何”“继续”“下一步”“完善产品方案”“设计技术方案”“开始开发”“开始循环：写任务，执行任务”“跑测试”“准备 review”“需求变了”等，不应要求用户记忆 `/xxx`；你应先读取 lifecycle 和 plan，再把意图映射到对应 workflow action。执行 `/status`、`/next`、`/advance`、`/rfc`、`/prd`、`/design`、`/dev`、`/devloop` 等宏指令时，输出要短而明确：当前事实是什么、将调用哪个 gate 或 Skill、成功后会进入哪里、失败时如何保持状态安全。
+如果当前是 `TESTING` 且 `.docs/07_test/TEST_REPORT.md` 的 Final decision 为 `BLOCKED`，先读取其中的 `Bugfix Route` 再切换阶段。`bugfix_uiux_replan` 使用 `python3 tools/transition.py --to UI_UX_DESIGNING` 回到体验设计阶段，修正 UX flow、screen contracts、interaction states、DESIGN.md 或 handoff matrix；`bugfix_replan` 使用 `python3 tools/transition.py --to ARCHITECTING` 回到技术方案阶段，修正 tech plan、接口契约、任务拆分或 handoff graph 后再进入开发；`bugfix_implementation_gap` 使用 `python3 tools/transition.py --to SPRINTING` 回到开发阶段，只创建或选择小的实现偏差修复 task。若报告显示需求、验收标准或产品边界变化，仍进入 `RFC_RECALIBRATION`。不要把测试 bug 直接当作无分类重试。
+
+自然语言是默认控制方式，约定宏指令是更完整、更细节的提示词别名。用户说“状态如何”“继续”“下一步”“完善产品方案”“做 UI/UX 设计”“交互设计”“视觉设计”“设计技术方案”“开始开发”“开始循环：写任务，执行任务”“跑测试”“准备 review”“需求变了”等，不应要求用户记忆 `/xxx`；你应先读取 lifecycle 和 plan，再把意图映射到对应 workflow action。执行 `/status`、`/next`、`/advance`、`/rfc`、`/prd`、`/uiux`、`/design`、`/dev`、`/devloop` 等宏指令时，输出要短而明确：当前事实是什么、将调用哪个 gate 或 Skill、成功后会进入哪里、失败时如何保持状态安全。
 
 自然语言和宏指令必须进入同一组 workflow action；区别在于 `/xxx` 入口携带更稳定的细节约束，简单自然语言入口更低成本，但需要你根据当前阶段、plan 和文档上下文补足细节。
 
@@ -44,24 +46,26 @@ Parallel Execution 是默认评估、按需启用：每个阶段 task 开始时
 11. 用户自然语言询问状态时，等价执行 `/status`。
 12. 用户自然语言要求继续、推进或下一步时，等价执行 `/next`。
 13. 用户自然语言要求进入下一阶段或检查是否可进入下一阶段时，等价执行 `/advance`。
-14. 用户自然语言表达需求或设计变化时，先判断阶段：如果当前是 `ARCHITECTING` 且尚未进入开发，可以说明将回到 `REQUIREMENT_GATHERING` 并用 `python3 tools/transition.py --to REQUIREMENT_GATHERING` 切回 PM/PRD 工作流；如果当前是 `SPRINTING` 或之后，进入 RFC workflow。
-15. 用户输入 `/prd`，或自然语言要求“完善产品方案”“写 PRD”“文档切片”“我提供信息，你帮我完善产品方案”时，如果 `current_phase` 是 `REQUIREMENT_GATHERING`，调用产品方案工作流；如果 `current_phase` 是 `ARCHITECTING`，先确认没有 open design task 需要收尾，说明将开发前回退到 `REQUIREMENT_GATHERING`，再用 `python3 tools/transition.py --to REQUIREMENT_GATHERING` 切换到 PM/PRD 工作流；该工作流必须先创建或选择一个最小 `TASK-*` open task，并设置 `phase: "REQUIREMENT_GATHERING"`，再执行一个 PRD 生成或切片 task；否则说明当前阶段冲突和推荐路径。
-16. 用户输入 `/design`，或自然语言要求“设计技术方案”“做架构方案”“根据 PRD 做技术方案”“切技术方案”时，如果 `current_phase` 是 `ARCHITECTING`，调用架构和技术方案工作流；该工作流必须先创建或选择一个最小 `TASK-*` open task，并设置 `phase: "ARCHITECTING"`，再执行一个 architecture / tech plan / `plan.draft.yaml` 生成或切片 task；否则说明当前阶段冲突和推荐路径。
-17. 用户输入 `/dev`，或自然语言要求“开始开发”“做当前任务”“做下一个任务”“继续开发下一个任务”时，如果 `current_phase` 是 `SPRINTING`，创建或选择一个最小 `TASK-*` development task 并执行一个 task 闭环；如果 task 来自 `plan.draft.yaml.tasks[]`，promote 时必须同次删除源 draft；否则说明当前阶段冲突和推荐路径。
-18. 用户输入 `/devloop`，或自然语言要求“开始循环：写任务，执行任务”“把开发循环跑完”“连续开发”时，如果 `current_phase` 是 `SPRINTING`，连续运行 `/dev` 循环，直到 `plan.yaml.tasks[]` 和 `plan.draft.yaml.tasks[]` 都没有明确可做任务或遇到 blocker；否则说明当前阶段冲突和推荐路径。
-19. 用户自然语言要求跑测试或验证时，运行当前 task 或当前阶段的对应 gate。
-20. 每个阶段 task 开始时先判断当前阶段和当前 task 是否适合并行；如果适合，生成或使用 `parallel_execution.trigger: "workflow_default"` 合同；如果用户明确要求并行、多 agent 或多 worktree，使用 `trigger: "user_requested"`。
-21. 默认使用 `runtime_managed` + `runtime.provider: "codex_native_subagents"`；native subagent 不可用时使用 `user_orchestrated` 并输出每个 worker 的可复制 prompt；高风险写入或用户要求强隔离时可选择 `codex_exec_worktree` fallback。
-22. 用户自然语言要求 review 时，如果 `current_phase` 是 `REVIEWING`，创建或选择一个最小 `TASK-*` review task，并设置 `phase: "REVIEWING"`；reviewer 只读源码，不直接改源码。
-23. 用户自然语言要求刷新文档总览时，运行 `make docs-overview`。
-24. `/plan` 和 `/goal` 是客户端模式入口，不由 Harness 自动开启；如果用户手动组合 `/plan` 或 `/goal` 与自然语言或宏指令，应按对应 workflow action 继续执行。
-25. 如果动作会改变阶段、创建或删除 task、提交、push 或发布，先用一句话说明即将执行的动作和验证方式，再继续。
+14. 用户自然语言表达需求或设计变化时，先判断阶段：如果当前是 `UI_UX_DESIGNING` 或 `ARCHITECTING` 且尚未进入开发，可以说明将回到对应的前置阶段，并用 `python3 tools/transition.py --to REQUIREMENT_GATHERING` 或 `python3 tools/transition.py --to UI_UX_DESIGNING` 切回补事实；如果当前是 `SPRINTING` 或之后，进入 RFC workflow。
+15. 用户输入 `/prd`，或自然语言要求“完善产品方案”“写 PRD”“文档切片”“我提供信息，你帮我完善产品方案”时，如果 `current_phase` 是 `REQUIREMENT_GATHERING`，调用产品方案工作流；如果 `current_phase` 是 `UI_UX_DESIGNING` 或 `ARCHITECTING`，先确认没有 open design task 需要收尾，说明将开发前回退到 `REQUIREMENT_GATHERING`，再用 `python3 tools/transition.py --to REQUIREMENT_GATHERING` 切换到 PM/PRD 工作流；该工作流必须先创建或选择一个最小 `TASK-*` open task，并设置 `phase: "REQUIREMENT_GATHERING"`，再执行一个 PRD 生成或切片 task；否则说明当前阶段冲突和推荐路径。
+16. 用户输入 `/uiux`，或自然语言要求“做 UI/UX 设计”“交互设计”“视觉设计”“设计屏幕状态”“补 DESIGN.md”时，如果 `current_phase` 是 `UI_UX_DESIGNING`，调用体验设计工作流；如果 `current_phase` 是 `ARCHITECTING` 且尚未进入开发，可先确认没有 open architecture task 需要收尾，再用 `python3 tools/transition.py --to UI_UX_DESIGNING` 切回体验设计阶段；该工作流必须先创建或选择一个最小 `TASK-*` open task，并设置 `phase: "UI_UX_DESIGNING"`，再执行一个 UX flow / screen contract / DESIGN.md / handoff matrix task；否则说明当前阶段冲突和推荐路径。
+17. 用户输入 `/design`，或自然语言要求“设计技术方案”“做架构方案”“根据 PRD 做技术方案”“切技术方案”时，如果 `current_phase` 是 `ARCHITECTING`，调用架构和技术方案工作流；该工作流必须先创建或选择一个最小 `TASK-*` open task，并设置 `phase: "ARCHITECTING"`，再执行一个 architecture / tech plan / `plan.draft.yaml` 生成或切片 task；否则说明当前阶段冲突和推荐路径。
+18. 用户输入 `/dev`，或自然语言要求“开始开发”“做当前任务”“做下一个任务”“继续开发下一个任务”时，如果 `current_phase` 是 `SPRINTING`，创建或选择一个最小 `TASK-*` development task 并执行一个 task 闭环；如果 task 来自 `plan.draft.yaml.tasks[]`，promote 时必须同次删除源 draft；否则说明当前阶段冲突和推荐路径。
+19. 用户输入 `/devloop`，或自然语言要求“开始循环：写任务，执行任务”“把开发循环跑完”“连续开发”时，如果 `current_phase` 是 `SPRINTING`，连续运行 `/dev` 循环，直到 `plan.yaml.tasks[]` 和 `plan.draft.yaml.tasks[]` 都没有明确可做任务或遇到 blocker；否则说明当前阶段冲突和推荐路径。
+20. 用户自然语言要求跑测试或验证时，运行当前 task 或当前阶段的对应 gate。
+21. 用户自然语言要求修复测试发现的 bug 时，如果当前是 `TESTING`，先读取 `TEST_REPORT.md#Bugfix Route`；`bugfix_uiux_replan` 回 `UI_UX_DESIGNING`，`bugfix_replan` 回 `ARCHITECTING`，`bugfix_implementation_gap` 回 `SPRINTING`，需求或验收变化走 RFC。
+22. 每个阶段 task 开始时先判断当前阶段和当前 task 是否适合并行；如果适合，生成或使用 `parallel_execution.trigger: "workflow_default"` 合同；如果用户明确要求并行、多 agent 或多 worktree，使用 `trigger: "user_requested"`。
+23. 默认使用 `runtime_managed` + `runtime.provider: "codex_native_subagents"`；native subagent 不可用时使用 `user_orchestrated` 并输出每个 worker 的可复制 prompt；高风险写入或用户要求强隔离时可选择 `codex_exec_worktree` fallback。
+24. 用户自然语言要求 review 时，如果 `current_phase` 是 `REVIEWING`，创建或选择一个最小 `TASK-*` review task，并设置 `phase: "REVIEWING"`；reviewer 只读源码，不直接改源码。
+25. 用户自然语言要求刷新文档总览时，运行 `make docs-overview`。
+26. `/plan` 和 `/goal` 是客户端模式入口，不由 Harness 自动开启；如果用户手动组合 `/plan` 或 `/goal` 与自然语言或宏指令，应按对应 workflow action 继续执行。
+27. 如果动作会改变阶段、创建或删除 task、提交、push 或发布，先用一句话说明即将执行的动作和验证方式，再继续。
 
 ## Plan Protocol
 
 每个 open task 都必须在 `plan.yaml` 中包含 `id`、`phase`、`docs`、`allowed_paths`、`required_gates` 和 `acceptance_criteria`；新 task 统一使用 `TASK-*` id，历史 `DEV-*`、`PRD-*`、`DES-*` task 只作为兼容输入保留。文档和流程产物 task 使用 `result_docs` 指向本 task 产出的 PRD、architecture、tech plan、ADR、review、test、release、RFC 或 `plan.draft.yaml`，开发 task 使用 `implementation_doc` 指向模块级实现事实。任何阶段如果从 draft queue promote 正式 `TASK-*`，必须同次消费并删除源 draft；当前内置 draft queue 是 `plan.draft.yaml.tasks[]`，用于保存尚未采用的开发草案。done/cancelled task 不长期留在当前 `plan.yaml`。完成后的产物事实以对应 `.docs/**` slice 或模块级 implementation doc 为准，动作历史以 git/PR/CI/release 系统作为 cold archive，`next_task_sequence` 负责继续分配后续 task id。
 
-`/prd`、`/design`、`/dev`、`/review`、`/test`、`/release` 和 `/rfc` 都是单 task 推进：默认只完成一个 `TASK-*`。`validate-plan` 用于检查当前 open task 合同是否完整。direct `validate-dev` / `make validate-dev` 是 `SPRINTING` 开发中 gate，允许一个合法当前 open task 存在；`validate-current` / `/advance` 在 `SPRINTING` 下仍是阶段出口 gate，要求没有 open task 残留。其它阶段出口 gate `validate-pm`、`validate-design`、`validate-review`、`validate-test`、`validate-release` 和 `validate-rfc` 也要求没有 open task 残留。
+`/prd`、`/uiux`、`/design`、`/dev`、`/review`、`/test`、`/release` 和 `/rfc` 都是单 task 推进：默认只完成一个 `TASK-*`。`validate-plan` 用于检查当前 open task 合同是否完整。direct `validate-dev` / `make validate-dev` 是 `SPRINTING` 开发中 gate，允许一个合法当前 open task 存在；`validate-current` / `/advance` 在 `SPRINTING` 下仍是阶段出口 gate，要求没有 open task 残留。其它阶段出口 gate `validate-pm`、`validate-uiux`、`validate-design`、`validate-review`、`validate-test`、`validate-release` 和 `validate-rfc` 也要求没有 open task 残留。
 
 `parallel_execution` 是按需顶层合同，缺省表示当前 task 串行。启用后必须声明 `enabled`、`trigger`、`mode`、`coordinator`、`workers` 和 `integration`；默认并行还应声明 `runtime.provider: "codex_native_subagents"`。不要在合同内重复保存 `phase` 或 `linked_task_id`，当前阶段来自 lifecycle 的 `current_phase`，当前任务来自 plan 的 `current_task_id`。
 

package/assets/skills/pjsdlc_reviewer/SKILL.md

@@ -13,12 +13,14 @@ description: Use during REVIEWING for read-only review of requirement fit, imple
 
 你是严格但建设性的代码与交付审查者，目标是发现会影响需求一致性、正确性、可维护性、测试充分性或发布风险的问题。你只读审查，不直接修改源码。
 
-Review 时先建立证据链：PRD 说什么、技术方案承诺什么、implementation doc 声称做了什么、diff 实际改了什么、gate/test 证明了什么。Findings 必须优先输出，按严重程度排序，并尽量引用具体文件、需求、任务或文档路径。
+Review 时先建立证据链：PRD 说什么、UI/UX screen contracts 和 DESIGN.md 承诺什么、技术方案承诺什么、implementation doc 声称做了什么、diff 实际改了什么、gate/test 证明了什么。Findings 必须优先输出，按严重程度排序，并尽量引用具体文件、需求、任务或文档路径。
 
 不要把个人偏好包装成 blocker。区分 blocking issue、follow-up improvement 和 open question。如果没有发现问题，要明确说明，同时列出剩余测试缺口或残余风险。
 
 Review 必须把“当前模块没有可运行入口/出口”视为阻断项，而不是普通测试缺口。凡 PRD、技术方案或 implementation doc 承诺 API、CLI、server route、service、agent、runtime、adapter、worker、provider、外部发送/写入执行器、配置契约或 live/fixture 双模式边界，Review 都要读取技术方案的 `Development Deliverable Contract`、`Development Self-Test Contract` 或等价交付边界，并核对真实代码和实现文档是否提供可调用入口、初始化方式、输出/副作用边界和验证方式；如果 task 声明了 `evidence_level.required`、`target_runtime_environment` 或 `self_test_contract`，还必须核对实际证据等级、执行地点、目标运行环境、自测 scenario 结果、`module_key_test_path`、`module_key_test_graph`（若声明）和 required gates 是否匹配。high-risk runtime/live/remote-operator 工作要先看 `plan.yaml#resume_capsule` 和 `.docs/09_runbooks/**` runbook，确认 canonical path、do-not-retry、hard constraints、evidence index 和 exploration appendix 已把恢复主线与失败探索分开；Review 不应从失败探索中重新选择主路径。凡会改变下一步动作的判断，如果只埋在 evidence、notes、exploration appendix 或长 implementation doc 中，而没有 promoted 到 `resume_capsule.do_not_retry`、runbook 顶部 `Hard Constraints` 或短 `Current Operator Path`，应判为 blocker。implementation doc 还必须包含结构化 `Development Evidence`，说明 `Evidence Level`、`Target Runtime Environment`、`Runnable Entry`、`Observable Exit`、`Client / Server Initialization`、`Config Contract`、`Testing Handoff Readiness`、`Known Missing Runtime Boundaries` 和 `Basic Self-test Evidence`，或带原因的 `Not applicable`；如果 task 有 `self_test_contract.status: "required"`，还必须包含已执行的 `Development Self-Test Report`，并记录 `Report Status`、`Module Application Entry`、从本地启动或调用入口开始到完成全部自测用例的 `Module Key Test Path`、`Observable Exit`、`Current Blocker`、`Testing Handoff Readiness` 和 `Evidence Index Refs`。如果 contract 设置 `graph_required: true` 或包含 `module_key_test_graph`，报告必须含实际 `Module Key Test Graph`，覆盖 promised entry/exit、scenario、checkpoint 和 evidence refs。该报告不是 debug log、operator log、runbook、evidence dump 或历史流水；看到这些混入 scenario evidence 或 graph node 时应判为 blocker。`Report Status` 必须是 `PASS` 且所有 scenario 都是 `PASS` 才能进入 TESTING。该路径应覆盖本 task / 本模块承诺的所有可运行入口、内部关键路径、关键边界、观察点和可观测完成证据；high-risk task 还必须包含短的 `Current Operator Path` 和分层 `Gate Breakdown`。如果 task 要求 `deployed_runtime` 或 `business_handoff_ready`，但证据只是在开发机 `localhost`、provider live smoke、fixture smoke、fake adapter 或文档描述，应判 `BLOCKED`。缺失时 gate decision 应为 `BLOCKED`，并要求回到 SPRINTING/RFC，而不是允许进入 TESTING 后补 runtime。Review 报告必须写出 `Runnable Entry`、`Observable Exit`、`Initialization`、`Config Contract`、`Testing Handoff Readiness` 的 `PASS`/`BLOCKED` checklist；任一 `BLOCKED` 不得进入 TESTING。Review 不创建 `.docs/07_test/**` 正式测试产物；如果发现现有测试事实源仍链接已被 RFC supersede 的旧路线证据，应将其列为进入 TESTING 前的 blocker，并要求 RFC 清理或更新索引。
 
+对 UI/frontend/browser/page 改动，Review 还必须核对实现是否符合 `.docs/02_experience/**` 的 screen contracts、loading/empty/error/success/permission states、interaction behavior、responsive breakpoints、accessibility / focus / keyboard / touch expectations，以及 `DESIGN.md` tokens / components。缺少设计交接证据、实现与 screen contract 不一致、或明显绕过 DESIGN.md，应作为 blocking finding，而不是普通样式建议。
+
 Review 产出本身也是 workflow task。开始 review 前，先在 `<harnessRoot>/state/plan.yaml` 创建或选择一个足够小的 `TASK-*` open task，并设置 `phase: "REVIEWING"`；当前轮只产出一个 review batch、一个风险主题 slice 或一次 PR review 结论。不要在一个任务里覆盖多个互不相关的 review 主题。
 
 Review 阶段默认先评估是否适合并行只读审查。适合时，主 Reviewer 使用 `parallel_execution.trigger: "workflow_default"` 和 `runtime.provider: "codex_native_subagents"` 调度 worker 分别检查需求一致性、架构风险、测试缺口、runnable entry/exit 或安全风险；用户明确要求并行时使用 `trigger: "user_requested"`。worker 必须 `writes_repo: false`，只提交 findings 和证据；最终 `REVIEW_REPORT.md` 与 PASS/BLOCKED 结论由主 Reviewer 汇总。
@@ -27,6 +29,8 @@ Review 阶段默认先评估是否适合并行只读审查。适合时，主 Rev
 
 - `<harnessRoot>/state/plan.yaml`
 - `.docs/01_product/`
+- `.docs/02_experience/`
+- `DESIGN.md`
 - `.docs/03_tech_plan/`
 - `.docs/04_implementation/`
 - `.docs/07_test/`（只读，用于发现 stale test facts）
@@ -78,6 +82,7 @@ Review 阶段受 `plan.yaml` 管控：
 - [ ] 当前 review 工作已绑定 `plan.yaml` 中一个最小 `TASK-*` task，并设置 `phase: "REVIEWING"`。
 - [ ] 当前 task 已从 `plan.yaml` 移除，或因中断/blocker 保留为可恢复 open task。
 - [ ] 已评估需求一致性。
+- [ ] 已评估 UI/UX screen contracts、interaction behavior、responsive、a11y 和 DESIGN.md token usage 是否被实现遵守。
 - [ ] 已评估架构和可维护性风险。
 - [ ] 已评估 runnable entry/exit、配置契约和 fixture/live 边界是否足以进入 TESTING。
 - [ ] 已评估 implementation doc 是否包含 Evidence Level、Target Runtime Environment、Runnable Entry、Observable Exit、Client / Server Initialization、Config Contract、Testing Handoff Readiness、Known Missing Runtime Boundaries 和 Basic Self-test Evidence。

package/assets/skills/pjsdlc_rfc_recalibrate/SKILL.md

@@ -13,13 +13,13 @@ description: Use during RFC_RECALIBRATION to process requirement changes with im
 
 你是变更控制负责人，目标是把新的需求、修正或范围变化限制在清晰的影响链路内。你需要保护已稳定的 PRD、技术方案、实现文档和任务状态，避免因为一个变化重写整个项目。
 
-处理 RFC 时，先确认变化来源、动机、验收标准、紧急程度和影响范围。必须区分产品语义变化、技术实现偏移、任务边界调整和单纯文档澄清。对不确定的影响，先记录假设和待验证项，再决定是否回到 PM、ARCHITECTING 或 SPRINTING。
+处理 RFC 时，先确认变化来源、动机、验收标准、紧急程度和影响范围。必须区分产品语义变化、UI/UX 体验事实变化、技术实现偏移、任务边界调整和单纯文档澄清。对不确定的影响，先记录假设和待验证项，再决定是否回到 PM、UI_UX_DESIGNING、ARCHITECTING 或 SPRINTING。
 
 输出应包含 impact analysis、受影响产物、任务状态调整、测试事实源影响、回归要求和恢复路径。只修改受影响 slice；如果变化跨越多个独立能力，应拆分 RFC 或生成增量任务。
 
 影响面分析必须先于补丁。至少检查 docs/state/skills/policies/templates/tools/package assets/tests/migrations/generated artifacts 是否受影响；如果某一类不受影响，也要显式说明不受影响或不需要修改。对于 Harness package 相关变更，还要检查 `sync`、`upgrade`、source mappings、package assets 和用户项目迁移行为。
 
-如果 RFC 替换模块技术路线、entry/exit、环境依赖、required gates、handoff、blocker、模块关键测试路径或验收边界，必须同步审查 `.docs/07_test/**` 和开发自测链路。模块关键测试路径变化包括本 task / 本模块承诺的可运行入口、内部关键路径、关键边界、观察点或完成证据变化；如果使用 `module_key_test_graph`，entry、scenario、checkpoint、observable exit、edge 或 evidence refs 的变化也属于 RFC graph impact。被新方案 supersede 的测试环境、测试进度、测试用例、测试报告和 partial evidence 要从当前测试事实源删除或迁出，并从 `.docs/INDEX.md` 和 generated overview 中移除链接；历史证据只保留在 RFC provenance、git history、CI/release 系统或明确 archive 语义中，不能继续放在当前 `.docs/07_test/**` 冒充现行测试依据。RFC 必须写明 `Test Fact Source Impact`：reviewed test docs、superseded test docs、retained test docs 和原因；还必须写明 `Development Self-Test Impact`：entry/exit、runtime / target environment、required gates、tech plan self-test contract、`plan.yaml` / `plan.draft.yaml` task contract、implementation doc self-test report、Module Key Test Path / Graph、Review / Testing handoff 的影响。如果只是文案澄清且不影响测试事实源或自测链路，可分别写 `none`。
+如果 RFC 替换 UX flow、screen contracts、interaction states、DESIGN.md、模块技术路线、entry/exit、环境依赖、required gates、handoff、blocker、模块关键测试路径或验收边界，必须同步审查 `.docs/02_experience/**`、`DESIGN.md`、`.docs/03_tech_plan/**`、`plan.yaml` / `plan.draft.yaml`、`.docs/06_review/**`、`.docs/07_test/**` 和开发自测链路。模块关键测试路径变化包括本 task / 本模块承诺的可运行入口、内部关键路径、关键边界、观察点或完成证据变化；如果使用 `module_key_test_graph`，entry、scenario、checkpoint、observable exit、edge 或 evidence refs 的变化也属于 RFC graph impact。被新方案 supersede 的测试环境、测试进度、测试用例、测试报告和 partial evidence 要从当前测试事实源删除或迁出，并从 `.docs/INDEX.md` 和 generated overview 中移除链接；历史证据只保留在 RFC provenance、git history、CI/release 系统或明确 archive 语义中，不能继续放在当前 `.docs/07_test/**` 冒充现行测试依据。RFC 必须写明 `UI/UX Impact`：reviewed experience docs、DESIGN.md impact、superseded screen contracts、retained UX facts 和原因；必须写明 `Test Fact Source Impact`：reviewed test docs、superseded test docs、retained test docs 和原因；还必须写明 `Development Self-Test Impact`：entry/exit、runtime / target environment、required gates、tech plan self-test contract、`plan.yaml` / `plan.draft.yaml` task contract、implementation doc self-test report、Module Key Test Path / Graph、Review / Testing handoff 的影响。如果只是文案澄清且不影响 UI/UX、测试事实源或自测链路，可分别写 `none`。
 
 RFC recalibration 本身也是 workflow task。开始处理变更前，先在 `<harnessRoot>/state/plan.yaml` 创建或选择一个足够小的 `TASK-*` open task，并设置 `phase: "RFC_RECALIBRATION"`；当前轮只处理一个 RFC 文件、一个 impact analysis 单元或一个局部补丁单元。
 
@@ -29,6 +29,8 @@ RFC 阶段默认先评估是否适合并行 impact analysis。适合时，主 Ag
 
 - `.docs/rfc/RFC_*.md`
 - 当前 PRD 和技术方案
+- `.docs/02_experience/`
+- `DESIGN.md`
 - `.docs/04_implementation/`
 - `<harnessRoot>/state/plan.yaml`
 - `tools/impact_analyzer.py`
@@ -36,7 +38,7 @@ RFC 阶段默认先评估是否适合并行 impact analysis。适合时，主 Ag
 ## 输出
 
 - 更新后的 RFC status 或 impact notes
-- 局部更新后的 PRD 和技术方案
+- 局部更新后的 PRD、UI/UX facts、DESIGN.md 和技术方案
 - 被标记为 `pending_revision` 的受影响任务，或新增增量任务
 - Regression requirements
 - Test fact source impact
@@ -47,7 +49,7 @@ RFC 阶段默认先评估是否适合并行 impact analysis。适合时，主 Ag
 
 - `.docs/rfc/` 按一次需求变更切片，一份 RFC 只描述一个可独立评估、实现和回归的变更。
 - 如果用户一次提出多个互不依赖的变更，应拆成多份 RFC。
-- RFC 的 impact analysis 负责判断是否需要重切 PRD、tech plan、`self_test_contract`、implementation doc、Development Self-Test Report、Module Key Test Path / Graph、test strategy、test cases 或 test report，并覆盖 state、tools、package assets、tests、migration 和 generated overview。
+- RFC 的 impact analysis 负责判断是否需要重切 PRD、UI/UX screen contracts、DESIGN.md、tech plan、`self_test_contract`、implementation doc、Development Self-Test Report、Module Key Test Path / Graph、review report、test strategy、test cases 或 test report，并覆盖 state、tools、package assets、tests、migration 和 generated overview。
 - 对受影响产物做局部补丁，不重写无关稳定 slice。
 - 每次 RFC 影响了文档边界，都要更新 `.docs/INDEX.md` 并记录受影响任务状态。
 
@@ -56,7 +58,7 @@ RFC 阶段默认先评估是否适合并行 impact analysis。适合时，主 Ag
 RFC 阶段受 `plan.yaml` 管控：
 
 1. 没有 open task 时，先创建一个最小 `TASK-*` task，设置 `phase: "RFC_RECALIBRATION"` 和 `current_task_id`。
-2. open task 必须包含 `phase`、`docs`、`allowed_paths`、`required_gates`、`acceptance_criteria` 和 `result_docs`；`result_docs` 指向本 task 计划产出的 RFC、受影响 PRD/tech plan/test docs 或 plan update。
+2. open task 必须包含 `phase`、`docs`、`allowed_paths`、`required_gates`、`acceptance_criteria` 和 `result_docs`；`result_docs` 指向本 task 计划产出的 RFC、受影响 PRD、UI/UX docs、DESIGN.md、tech plan、test docs 或 plan update。
 3. 单个 task 的目标应足够小：一份 RFC 的 impact analysis、一个受影响 slice 的局部补丁、一组任务状态调整，或一个回归要求更新。
 4. 执行当前 task 时只编辑 `allowed_paths` 中的 RFC、受影响 facts、`.docs/INDEX.md`、overview 和 `plan.yaml`。
 5. 完成后运行 `make validate-plan` 和 task required gates；阶段出口前运行 `make validate-rfc`。
@@ -79,6 +81,7 @@ RFC 阶段受 `plan.yaml` 管控：
 - [ ] 当前 RFC 工作已绑定 `plan.yaml` 中一个最小 `TASK-*` task，并设置 `phase: "RFC_RECALIBRATION"`。
 - [ ] 当前 task 已从 `plan.yaml` 移除，或因中断/blocker 保留为可恢复 open task。
 - [ ] Product impact 和 technical impact 已记录。
+- [ ] `UI/UX Impact` 已记录；如果 RFC 影响 screen contracts、interaction states、handoff matrix 或 DESIGN.md，已同步相关事实源和下游引用。
 - [ ] 已判断 RFC 是否需要拆分，以及是否影响其它阶段 slice。
 - [ ] 已列出 docs/state/skills/policies/templates/tools/package assets/tests/migrations/generated artifacts 的影响面。
 - [ ] 已记录 `Test Fact Source Impact`，并清理被 supersede 的 `.docs/07_test/**` 当前事实链接。

package/assets/skills/pjsdlc_tester/SKILL.md

@@ -13,12 +13,18 @@ description: Use during TESTING to produce a test matrix, run regression, and do
 
 你是测试负责人，目标是把需求、风险和实现变化转成可执行、可追踪、可复用的测试产物。必须严格区分三类文档：`TEST_STRATEGY.md` 描述范围、环境、优先级和执行策略；`TEST_CASES.md` 描述要测什么、前置条件、步骤和预期结果；`TEST_REPORT.md` 只记录 TESTING 阶段实际执行后的结果、证据、覆盖缺口和最终结论。不要把测试用例、测试计划或待填报告命名为 `TEST_REPORT.md`。
 
-开始测试规划前，先建立映射关系：PRD acceptance criteria、技术方案关键接口/数据模型、implementation doc 的真实改动、Review findings 和现有测试。对每个测试项说明它覆盖的需求或风险；对暂不覆盖的内容说明原因、残余风险和 follow-up。
+开始测试规划前，先建立映射关系：PRD acceptance criteria、`.docs/02_experience/**` screen contracts / handoff matrix、`DESIGN.md`、技术方案关键接口/数据模型、implementation doc 的真实改动、Review findings 和现有测试。对每个测试项说明它覆盖的需求、体验状态或风险；对暂不覆盖的内容说明原因、残余风险和 follow-up。
+
+`TEST_CASES.md` 是执行前或执行中可复用的测试设计事实源。每个 case 使用稳定 `TC-*` ID，并记录 `Requirement / Risk Ref`、`Type`、`Priority`、`Runnable Entry`、`Preconditions`、`Steps`、`Expected Exit` 和可选短 `Evidence Pointer`。case 不记录执行结果、回归证据、bugfix route 或最终结论；这些只写入 `TEST_REPORT.md`。`TEST_REPORT.md` 的 Test Matrix 应引用 `TEST_CASES.md` 中的 `TC-*`，除非本轮是极小 smoke 且报告明确写明无需独立 case slice 的原因。
 
 执行回归时，优先选择能证明阶段出口的 gate。测试无法运行、环境缺失或数据不可得时，不要宣布通过；如果已经进入 TESTING，应在 `TEST_REPORT.md` 中记录 `BLOCKED`、已完成检查和恢复条件。
 
 TESTING 只能调用 SPRINTING/REVIEWING 已确认 `PASS` 的入口做输入/输出验证。可以补充测试、fixture、mock、assertion helper 和测试文档，但不能在 TESTING 中新增或长期维护 product runtime、server/API/CLI/adapter、direct poller、cloud bootstrap、systemd unit、真实 provider adapter、package runtime script 或部署脚本。如果发现真实入口/出口不存在、implementation doc 缺少 `Development Evidence` 或 `Development Self-Test Report`、自测报告缺少 `Report Status: PASS`、缺少从本地启动或调用入口到完成全部自测用例的 `Module Key Test Path`、缺少 `Evidence Index Refs`、或该路径没有覆盖本 task / 本模块承诺的入口、内部关键路径、关键边界、观察点和完成证据，live 模式不可调用、配置契约缺失、Review readiness checklist 不是全 `PASS`，或 `Evidence Level` / `Target Runtime Environment` / `self_test_contract` 与 task 或技术方案承诺不一致，应记录 `BLOCKED`、生成 RFC 或后续 dev task 建议，并停止把测试阶段扩大成开发/集成搭建。若 `self_test_contract` 设置 `graph_required: true` 或包含 `module_key_test_graph`，TESTING 必须按 `Module Key Test Graph` 选择入口、checkpoint、scenario 和 observable exit，不能重新发明 runtime 或把图扩成测试执行引擎。`Development Self-Test Report` 不是 debug log、operator log、runbook、evidence dump 或探索流水；测试只消费其模块入口、核心路径、出口和最小证据指针。high-risk runtime/live/remote-operator 验证要先读 `plan.yaml#resume_capsule`，再读 `.docs/09_runbooks/**` runbook 和 evidence index，最后才读 exploration appendix；测试只沿 canonical path 和 hard constraints 验证，不重新尝试 `do_not_retry` 中的失败路径。开发尚未交付可测试 entry/exit、目标运行环境、Development Self-Test Report 或 Testing Handoff Contract 时，不要在 `.docs/07_test/**` 提前生成正式测试用例或正式报告；验收思路应留在 PRD acceptance criteria、tech plan verification strategy 或非 `.docs/07_test/**` 的草稿说明里。`TEST_REPORT.md` 不能在描述缺少 entry/exit、缺少 Development Evidence、缺少 Development Self-Test Report、证据等级不匹配或未交付应用入口时给出 `PASS`。
 
+UI/frontend/browser/page 测试用例应从 `.docs/02_experience/**` 的 handoff matrix 和 screen contracts 生成，覆盖关键 loading/empty/error/success/permission states、responsive breakpoints、accessibility / focus / keyboard / touch expectations 和 DESIGN.md token/component usage。TESTING 不重新设计 UI；如果测试证明 PRD 正确但 UX contract、screen state、handoff matrix 或 DESIGN.md 错误，`TEST_REPORT.md` 的 Final decision 必须为 `BLOCKED`，并写 `Bugfix Route: bugfix_uiux_replan`。
+
+当 TESTING 发现 bug，`TEST_REPORT.md` 的 Final decision 必须为 `BLOCKED`，并写明 `Bugfix Route`。`bugfix_uiux_replan` 表示测试证明 UX flow、screen contract、interaction state、handoff matrix 或 DESIGN.md 需要修改，Manager 可从 `TESTING` 轻量回退到 `UI_UX_DESIGNING`；`bugfix_replan` 表示测试证明技术方案、接口契约、任务拆分、测试入口或 handoff graph 需要修改，Manager 可从 `TESTING` 轻量回退到 `ARCHITECTING`，先修正 tech plan / `plan.draft.yaml`，再回到 `SPRINTING`。`bugfix_implementation_gap` 表示既有 UI/UX 和技术方案仍正确，只是实现没有按方案交付，Manager 可从 `TESTING` 轻量回退到 `SPRINTING` 创建或选择小的 bugfix dev task；该路径是保留口子，不是预期常态。若测试暴露的是需求、验收标准或产品边界变化，仍然进入 `RFC_RECALIBRATION`。
+
 测试设计和回归证据产出本身也是 workflow task。开始测试前，先在 `<harnessRoot>/state/plan.yaml` 创建或选择一个足够小的 `TASK-*` open task，并设置 `phase: "TESTING"`；当前轮只产出一个测试策略 slice、测试用例 slice、回归批次、风险验证片区或一组 scoped test changes。`plan.yaml` 仍是唯一执行计划事实源，`.docs/07_test/**` 只记录当前方案的 test strategy、test cases、executed regression evidence、coverage gaps 和 final decision，不表达“下一步如何开发”，也不保留已被 RFC supersede 的旧测试结果。
 
 测试阶段默认先评估是否适合并行验证。适合时，主 Tester 使用 `parallel_execution.trigger: "workflow_default"` 和 `runtime.provider: "codex_native_subagents"` 调度 worker 分别执行互不依赖的回归片区、smoke、兼容性或风险验证；用户明确要求并行时使用 `trigger: "user_requested"`。worker 只提交证据和必要的 scoped test changes；最终 `.docs/07_test/**`、coverage gaps、PASS/BLOCKED 决策和阶段 gate 由主 Agent 汇总。不适合拆分时保持串行并记录原因。
@@ -27,6 +33,8 @@ TESTING 只能调用 SPRINTING/REVIEWING 已确认 `PASS` 的入口做输入/输
 
 - `<harnessRoot>/state/plan.yaml`
 - `.docs/01_product/`
+- `.docs/02_experience/`
+- `DESIGN.md`
 - `.docs/03_tech_plan/`
 - `.docs/04_implementation/`
 - `.docs/06_review/REVIEW_REPORT.md`
@@ -44,7 +52,7 @@ TESTING 只能调用 SPRINTING/REVIEWING 已确认 `PASS` 的入口做输入/输
 - 更新后的 `<harnessRoot>/state/plan.yaml`
 - 回归证据记录
 - 覆盖缺口清单
-- `BLOCKED` 时的 RFC/dev follow-up 建议和恢复条件
+- `BLOCKED` 时的 `Bugfix Route`、RFC/dev follow-up 建议和恢复条件
 
 ## 语义切片
 
@@ -59,7 +67,7 @@ TESTING 只能调用 SPRINTING/REVIEWING 已确认 `PASS` 的入口做输入/输
 测试阶段受 `plan.yaml` 管控：
 
 1. 没有 open task 时，先创建一个最小 `TASK-*` task，设置 `phase: "TESTING"` 和 `current_task_id`。
-2. open task 必须包含 `phase`、`docs`、`allowed_paths`、`required_gates`、`acceptance_criteria` 和 `result_docs`；`result_docs` 指向本 task 计划产出的 `.docs/07_test/**` 文件，必要时也列出 scoped test files。
+2. open task 必须包含 `phase`、`docs`、`allowed_paths`、`required_gates`、`acceptance_criteria` 和 `result_docs`；`result_docs` 指向本 task 计划产出的 `.docs/07_test/**` 文件，必要时也列出 scoped test files。若当前 task 计划产出 `TEST_CASES.md`，case 必须使用 `TC-*` ID 并满足测试用例规范。
 3. 单个 task 的目标应足够小：一个测试策略 slice、一个测试用例 slice、一个回归批次、一个风险验证片区，或一组紧密相关的测试变更。
 4. 执行当前 task 时只编辑 `allowed_paths` 中的测试、测试文档、`.docs/INDEX.md`、overview 和 `plan.yaml`。
 5. 完成后运行 `make validate-plan` 和 task required gates；阶段出口前运行 `make validate-test`。
@@ -67,11 +75,11 @@ TESTING 只能调用 SPRINTING/REVIEWING 已确认 `PASS` 的入口做输入/输
 
 ## 规则
 
-1. 测试用例必须追溯到 PRD acceptance criteria 或 Review findings，并绑定 SPRINTING/REVIEWING 已确认的 runnable entry/exit、Development Evidence、Development Self-Test Report、Evidence Level、Target Runtime Environment 和 Testing Handoff Contract；复杂路径还要消费 Module Key Test Graph，而不是在 TESTING 中重新设计 runtime path。
+1. 测试用例必须追溯到 PRD acceptance criteria、`.docs/02_experience/**` screen contracts / handoff matrix、Review findings 或 risk paths，并绑定 SPRINTING/REVIEWING 已确认的 runnable entry/exit、Development Evidence、Development Self-Test Report、Evidence Level、Target Runtime Environment 和 Testing Handoff Contract；复杂路径还要消费 Module Key Test Graph，而不是在 TESTING 中重新设计 runtime path。
 2. 根据风险补充边界、负向、回归和集成测试。
 3. 如果有意延后覆盖，必须记录风险和 follow-up。
 4. 不得新增 product runtime、server/API/CLI/adapter、poller、cloud bootstrap、systemd unit、真实 provider adapter、package runtime script 或部署脚本；这些属于 SPRINTING/RFC。
-5. 测试发现入口/出口或 Development Evidence 缺失时，Final decision 必须为 `BLOCKED`，并指出回到 SPRINTING/RFC 的具体条件。
+5. 测试发现入口/出口或 Development Evidence 缺失时，Final decision 必须为 `BLOCKED`，并指出回到 `ARCHITECTING`、`SPRINTING` 或 `RFC_RECALIBRATION` 的具体条件。
 6. 新测试策略使用 `.docs/07_test/TEST_STRATEGY.md`，新测试用例使用 `.docs/07_test/TEST_CASES.md`，执行报告使用 `.docs/07_test/TEST_REPORT.md`；不要新建或继续依赖 `.docs/07_test/TEST_PLAN.md`。
 7. `TEST_REPORT.md` 不得包含 `pending`、`TBD`、`待填`、`TODO` 或占位结论；未执行或不可执行时 Final decision 必须为 `BLOCKED` 并给出恢复条件。
 8. RFC 改变技术路线、entry/exit 或验收边界后，必须确认 `.docs/07_test/**` 中旧路线测试证据已删除或不再从 `.docs/INDEX.md` 暴露。
@@ -82,6 +90,8 @@ TESTING 只能调用 SPRINTING/REVIEWING 已确认 `PASS` 的入口做输入/输
 ## 完成检查
 
 - [ ] Test matrix 已把需求映射到测试。
+- [ ] UI/frontend/browser/page 用例已消费 `.docs/02_experience/**` handoff matrix、screen contracts 和 DESIGN.md，而不是在 TESTING 中重新设计 UI。
+- [ ] 如果本轮生成或引用 `TEST_CASES.md`，每个 case 都有稳定 `TC-*`、requirement/risk ref、runnable entry、steps 和 expected exit。
 - [ ] 当前测试工作已绑定 `plan.yaml` 中一个最小 `TASK-*` task，并设置 `phase: "TESTING"`。
 - [ ] 当前 task 已从 `plan.yaml` 移除，或因中断/blocker 保留为可恢复 open task。
 - [ ] Regression checklist 已完成。
@@ -93,6 +103,7 @@ TESTING 只能调用 SPRINTING/REVIEWING 已确认 `PASS` 的入口做输入/输
 - [ ] 未把测试计划、测试用例或待填内容写成 `TEST_REPORT.md`。
 - [ ] 已确认 `.docs/07_test/**` 只包含当前方案仍有效的测试事实。
 - [ ] Coverage gaps 已明确。
+- [ ] 若 Final decision 为 `BLOCKED` 且原因是 bug，已写明 `Bugfix Route: bugfix_replan | bugfix_implementation_gap | RFC_RECALIBRATION`。
 - [ ] 如果启用了并行测试，worker evidence 已由主 Agent 汇总到测试产物。
 - [ ] 已运行 `make docs-overview` 刷新 `.docs/<stage>/overview.md`。
 - [ ] Final decision 是 `PASS` 或 `BLOCKED`。

package/assets/skills/pjsdlc_uiux_design/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: pjsdlc_uiux_design
+description: Use during UI_UX_DESIGNING to create UX flow, screen contracts, interaction states, responsive/a11y acceptance, and optional DESIGN.md design-system handoff.
+---
+
+# UI/UX Design Skill
+
+## 目的
+
+把已确认的 PRD 转成后续架构、开发、Review 和测试可以消费的体验事实源。该阶段不写业务代码，也不替代技术方案；它只固定用户旅程、信息架构、屏幕契约、交互状态、响应式 / accessibility 验收和视觉设计系统。
+
+## 角色提示词
+
+你是资深产品设计师和 UX 设计负责人。目标不是做漂亮但不可执行的 UI 描述，而是把 PRD 中的用户场景转成可实现、可审查、可测试的 screen contracts 和 design-system handoff。
+
+开始前先确认 PRD 的 requirement IDs、目标用户、用户场景、验收标准、Out of Scope 和 Open Questions。若产品边界不足以决定用户旅程、屏幕范围或关键交互，不要用设计文档替代 PRD；先收尾或移除当前 open UI/UX task，再请 Manager 使用 `python3 tools/transition.py --to REQUIREMENT_GATHERING` 回到 PM/PRD 工作流。
+
+UI/UX 产出本身也是 workflow task。没有 open task 时，先在 `<harnessRoot>/state/plan.yaml` 创建一个最小 `TASK-*` task，设置 `phase: "UI_UX_DESIGNING"` 和 `current_task_id`。当前轮只完成一个能力、一个用户旅程、一组相关 screen contracts、一次 DESIGN.md 设计系统补充，或一个明确的 `not_applicable` 体验交接结论。不要在一个任务中连续重写大量产品和设计事实。
+
+视觉 UI 场景必须维护根目录 `DESIGN.md`。`DESIGN.md` 使用 Google DESIGN.md format：YAML front matter 保存 colors、typography、spacing、rounded、components；Markdown 正文保存 Overview、Colors、Typography、Layout、Elevation & Depth、Shapes、Components、Do's and Don'ts。tokens 是规范值，正文解释如何应用。`@google/design.md` warning 只作为设计风险提示；error 必须修复或记录 blocker。
+
+CLI、API、agent、operator workflow 等没有传统视觉界面的项目仍然可以进入本阶段，但应在 UX slice 中写 `Applicability: cli_or_api_experience` 并聚焦命令/接口入口、反馈、错误、恢复路径、权限提示和 handoff matrix。完全不适用时写 `Applicability: not_applicable`、PRD refs 和 N/A reason；不要生成空洞的屏幕表。
+
+UI/UX 阶段默认先评估是否适合并行调研或草图拆解。适合时，主 Agent 使用 `parallel_execution.trigger: "workflow_default"` 和 `runtime.provider: "codex_native_subagents"` 调度 worker 做用户旅程、屏幕状态、设计系统或竞品/规范调研；worker 不直接写最终事实源，最终 `.docs/02_experience/**`、`DESIGN.md`、`.docs/INDEX.md` 和 task 状态由主 Agent 合成。
+
+## 输入
+
+- `.docs/INDEX.md`
+- `<harnessRoot>/state/plan.yaml`
+- 相关 `.docs/01_product/` PRD
+- 现有 `.docs/02_experience/`
+- 可选现有 `DESIGN.md`
+- `<harnessRoot>/pjsdlc_managed/templates/UI_UX_DESIGN_TEMPLATE.md`
+
+## 输出
+
+- `.docs/02_experience/` 下的 UX / screen contract 文档
+- 视觉 UI 场景的根目录 `DESIGN.md`
+- 更新后的 `<harnessRoot>/state/plan.yaml`
+- 更新后的 `.docs/INDEX.md`
+
+## 语义切片
+
+- `.docs/02_experience/` 按业务能力、用户旅程、屏幕组、平台表面或体验风险切片。
+- 同一用户旅程中的多个屏幕可以在同一 slice；独立流程、独立验收标准或独立平台表面应拆成不同 slice。
+- `DESIGN.md` 是全局设计系统事实源，不按能力切片；能力级例外或临时偏移写入对应 UX slice 的 `Design system reference` 或 `Open Questions`。
+- `overview.md` 是 generated artifact，不算 UI/UX deliverable，也不能作为 `docs.uiux` 引用。
+
+## Plan Protocol
+
+1. 没有 open task 时，先创建一个最小 `TASK-*` task，设置 `phase: "UI_UX_DESIGNING"` 和 `current_task_id`。
+2. open task 必须包含 `phase`、`docs`、`allowed_paths`、`required_gates`、`acceptance_criteria` 和 `result_docs`；`result_docs` 指向本 task 计划产出的 `.docs/02_experience/**` 和可选 `DESIGN.md`。
+3. 执行当前 task 时只编辑 `allowed_paths` 中的文件，完成后更新 `.docs/INDEX.md`、运行 `make docs-overview`，并至少运行 `make validate-plan`；阶段出口前运行 `make validate-uiux`。
+4. task 完成后，从 `plan.yaml.tasks` 移除该 task；如果仍有 pending `TASK-*` UI/UX task，下一轮 `/uiux` 或 `/next` 再继续。
+5. 进入 `SPRINTING` 后发现 UX、screen contract 或 DESIGN.md 需要改变，走 RFC workflow；不要在开发中静默改设计事实。
+
+## 规则
+
+1. UX slice 必须引用 PRD 路径和 requirement IDs，除非明确 `Applicability: not_applicable`。
+2. 视觉 UI 必须有 screen contracts，至少覆盖适用的 loading、empty、error、success、permission states，responsive breakpoints，以及 accessibility / focus / keyboard / touch expectations。
+3. 视觉 UI 必须引用或生成根目录 `DESIGN.md`；非视觉体验必须写清 `Design system reference: not_applicable` 和原因。
+4. Handoff matrix 必须把 requirement -> screen/state -> component/interaction -> acceptance/test seed 连接起来，供 ARCHITECTING 和 TESTING 消费。
+5. 不要在 `.docs/02_experience/**` 写技术架构、数据模型或开发任务拆分；这些属于 `ARCHITECTING`。
+6. 不要在 TESTING 或 SPRINTING 中补写新的 UX contract 来追认实现；设计事实变化应回到 `UI_UX_DESIGNING` 或 RFC。
+
+## 完成检查
+
+- [ ] 当前 UI/UX 工作已绑定 `plan.yaml` 中一个最小 `TASK-*` task，并设置 `phase: "UI_UX_DESIGNING"`。
+- [ ] `.docs/02_experience/` 下存在非 overview 的 UX 产物，或明确记录 `Applicability: not_applicable`。
+- [ ] UX slice 引用了 PRD 和 requirement IDs，或记录了明确 N/A reason。
+- [ ] 视觉 UI 的 screen contracts 覆盖关键状态、响应式和 accessibility / focus / keyboard / touch。
+- [ ] 视觉 UI 的 `DESIGN.md` 通过 `@google/design.md` linter 的 error 检查；warning 已作为风险或偏移记录。
+- [ ] Handoff matrix 能被 ARCHITECTING、SPRINTING、REVIEWING 和 TESTING 消费。
+- [ ] `.docs/INDEX.md` 已链接新增产物。
+- [ ] 已运行 `make docs-overview` 刷新 `.docs/02_experience/overview.md`。
+- [ ] `make validate-uiux` 准备通过。

package/assets/templates/PLAN_TEMPLATE.yaml

@@ -59,6 +59,10 @@ tasks:
         - ".docs/00_raw/example.md"
       product:
         - ".docs/01_product/example.md"
+      uiux:
+        - ".docs/02_experience/example.md"
+      design_system:
+        - "DESIGN.md"
       architecture: []
       tech_plan: []
       rfc: []

package/assets/templates/REVIEW_TEMPLATE.md

@@ -3,6 +3,8 @@
 ## 1. Review 范围
 
 - PRD:
+- UI/UX:
+- DESIGN.md:
 - 技术方案（Technical design）:
 - 实现文档（Implementation docs）:
 - Diff/commit:
@@ -21,11 +23,19 @@
 
 - 
 
-## 5. Test Gaps（测试缺口）
+## 5. UX / Design Conformance（体验与设计一致性）
+
+- Screen contracts:
+- Interaction states:
+- Responsive / accessibility:
+- DESIGN.md token usage:
+- Blocking gaps before TESTING:
+
+## 6. Test Gaps（测试缺口）
 
 - 
 
-## 6. Runnable Entry/Exit Readiness（可运行入口/出口）
+## 7. Runnable Entry/Exit Readiness（可运行入口/出口）
 
 - Entry points:
 - Exit / side effects:
@@ -37,7 +47,7 @@
 - Testing Handoff Contract:
 - Blocking gaps before TESTING:
 
-## 7. Application Readiness Checklist（应用就绪检查）
+## 8. Application Readiness Checklist（应用就绪检查）
 
 - Runnable Entry: `PASS` / `BLOCKED`
 - Observable Exit: `PASS` / `BLOCKED`
@@ -45,7 +55,7 @@
 - Config Contract: `PASS` / `BLOCKED`
 - Testing Handoff Readiness: `PASS` / `BLOCKED`
 
-## 8. Gate Result（阶段结论）
+## 9. Gate Result（阶段结论）
 
 - Decision: `PASS` / `BLOCKED`
 - Required before testing:

package/assets/templates/RFC_TEMPLATE.md

@@ -23,22 +23,30 @@
 |---|---|---|
 |  |  | low/medium/high |
 
-## 5. Acceptance Criteria
+## 5. UI/UX Impact（体验影响）
+
+- Reviewed experience docs:
+- DESIGN.md impact:
+- Superseded screen contracts: none
+- Retained UX facts:
+- Reason:
+
+## 6. Acceptance Criteria
 
 - [ ] 
 
-## 6. Regression Requirements（回归要求）
+## 7. Regression Requirements（回归要求）
 
 - [ ] 
 
-## 7. Test Fact Source Impact（测试事实源影响）
+## 8. Test Fact Source Impact（测试事实源影响）
 
 - Reviewed test docs:
 - Superseded test docs: none
 - Retained test docs:
 - Reason:
 
-## 8. Development Self-Test Impact（开发自测影响）
+## 9. Development Self-Test Impact（开发自测影响）
 
 - Entry/exit impact:
 - Runtime / target environment impact:
@@ -49,6 +57,6 @@
 - Module key test path impact:
 - Review / Testing handoff impact:
 
-## 9. Status
+## 10. Status
 
 - Status: DRAFT