agent-project-sdlc 0.1.23 → 0.1.25

package/README.md

@@ -25,9 +25,9 @@ npx sdlc-harness init --adopt
 | Managed file sync | `npx sdlc-harness sync` | Materializes package canonical assets and safely updates package-managed guidance sections inside user-owned Markdown files while preserving project state, docs and local overrides. |
 | Upgrade | `npx sdlc-harness upgrade` | Runs migrations and sync for already-adopted projects, including legacy seed guidance migration. |
 | Diagnostics | `npx sdlc-harness doctor` | Reports Harness root, package version, schema version and key managed paths. |
-| Validators | `npx sdlc-harness validate-*`, `make validate-current`, `make validate-harness` | Checks product, design slicing, development, review, test, release, RFC, active plan shape, prompt language contract and generated overview freshness. |
+| Validators | `npx sdlc-harness validate-*`, `make validate-current`, `make validate-harness` | Checks product, UI/UX, architecture design slicing, development, review, test, release, RFC, active plan shape, prompt language contract and generated overview freshness. |
 | Harness Python tools | `tools/*.py` | Package-managed local workflow tools, including `transition.py`, Python validators and overview generation helpers. |
-| Lifecycle workflow | `<harnessRoot>/state/lifecycle.yaml`, `<harnessRoot>/state/plan.yaml`, `.docs/**` | Tracks REQUIREMENT_GATHERING, ARCHITECTING, SPRINTING, REVIEWING, TESTING, RELEASING and RFC_RECALIBRATION facts. |
+| Lifecycle workflow | `<harnessRoot>/state/lifecycle.yaml`, `<harnessRoot>/state/plan.yaml`, `.docs/**` | Tracks REQUIREMENT_GATHERING, UI_UX_DESIGNING, ARCHITECTING, SPRINTING, REVIEWING, TESTING, RELEASING and RFC_RECALIBRATION facts. |
 | Stage task control | `plan.yaml`, `make validate-plan`, `npx sdlc-harness validate-plan` | Keeps each stage's agent work in small `TASK-*` tasks with `phase` metadata and scoped paths/gates. |
 | Natural-language control | `AGENTS.md` plus workflow skills | Lets users say things like "continue", "start development", "run tests" or "requirements changed"; agents map these to workflow actions. |
 | Default parallel scheduling contract | `plan.yaml#parallel_execution` | Stage tasks default to a safe-parallelism check; suitable work uses Codex native subagents first, with user-orchestrated and worktree fallbacks. |
@@ -83,13 +83,19 @@ Release docs are current-state facts, not a version ledger. New release work sho
 
 The generic rule is that any workflow promoting a draft task into a formal `TASK-*` in `plan.yaml` must remove the source draft from its draft queue in the same state update. The formal task is then recovered only from `plan.yaml`; completed history lives in implementation docs, git, PR and CI records. The built-in Harness draft queue is currently `plan.draft.yaml.tasks[]`, which means unadopted development drafts only. `/devloop` treats the development queue as exhausted only when both `plan.yaml.tasks[]` and `plan.draft.yaml.tasks[]` have no executable task.
 
-Phase routing is expressed as a lightweight explicit directed graph in `<harnessRoot>/pjsdlc_managed/policies/phase_contracts.yaml`: `phases` stores stable phase contracts, while `transitions` stores legal edges and small runtime effects such as setting or clearing `suspended_phase`. This makes normal advance, pre-development return, RFC interrupt/resume and BLOCKED resume rules consumable by both the transition helper and validators. It is intentionally not a heavy graph engine: no history graph, traversal framework, node/edge classes or visualizer are introduced; the goal is to reduce missed rules and drift.
+`UI_UX_DESIGNING` sits between PRD and architecture. It writes `.docs/02_experience/**` UX slices with user journeys, screen contracts, interaction states, responsive/a11y acceptance and handoff matrix. Visual UI projects also maintain root `DESIGN.md` using Google's `DESIGN.md` format for design-system tokens and components; CLI/API/non-visual projects can declare `Applicability: cli_or_api_experience` or `Applicability: not_applicable` in the UX slice instead of creating `DESIGN.md`.
 
-Migration cost is low for projects that use managed assets: run `npx sdlc-harness upgrade` to sync the new `phase_contracts.yaml` and `tools/transition.py`, or run `npx sdlc-harness sync` if only managed files need refreshing. `lifecycle.yaml` and `plan.yaml` do not need manual migration; old `allowed_next_phases` values are regenerated from the graph on the next transition. Projects with custom phase policies should convert node-local `next` / `returns` to top-level `transitions`. If the new `validate-harness` reports missing `transitions`, run `upgrade` or `sync` before validating again.
+Phase routing is expressed as a lightweight explicit directed graph in `<harnessRoot>/pjsdlc_managed/policies/phase_contracts.yaml`: `phases` stores stable phase contracts, while `transitions` stores legal edges and small runtime effects such as setting or clearing `suspended_phase`. This makes normal advance, pre-development return, TESTING bugfix return, RFC interrupt/resume and BLOCKED resume rules consumable by both the transition helper and validators. It is intentionally not a heavy graph engine: no history graph, traversal framework, node/edge classes or visualizer are introduced; the goal is to reduce missed rules and drift.
 
-Before development starts, `ARCHITECTING` can return to `REQUIREMENT_GATHERING` for PRD edits. The manager uses `python3 tools/transition.py --to REQUIREMENT_GATHERING`, the PM workflow updates the PRD through one `TASK-*`, then `validate-pm` and `python3 tools/transition.py --to ARCHITECTING` return the project to design. Requirement or design changes after `SPRINTING` use RFC recalibration; `SPRINTING`, `REVIEWING`, `TESTING` and `RELEASING` can enter the controlled interrupt with `python3 tools/transition.py --to RFC_RECALIBRATION`, then return to `SPRINTING` after `validate-rfc`.
+Migration cost is low for projects that use managed assets: run `npx sdlc-harness upgrade` to sync the new `phase_contracts.yaml`, `tools/transition.py`, `pjsdlc_uiux_design`, `UI_UX_DESIGN_TEMPLATE.md` and `validate-uiux`, or run `npx sdlc-harness sync` if only managed files need refreshing. `lifecycle.yaml` and `plan.yaml` do not need manual migration; old `allowed_next_phases` values are regenerated from the graph on the next transition. Projects with custom phase policies should convert node-local `next` / `returns` to top-level `transitions`, and add `REQUIREMENT_GATHERING -> UI_UX_DESIGNING -> ARCHITECTING`, `ARCHITECTING -> UI_UX_DESIGNING`, and the `TESTING -> UI_UX_DESIGNING` / `ARCHITECTING` / `SPRINTING` bugfix return edges when they want the new routing. If the new `validate-harness` reports missing `transitions`, run `upgrade` or `sync` before validating again.
 
-`validate-design` treats semantic slicing as a hard gate. Generated `overview.md` files do not count as deliverables, development draft tasks in `plan.draft.yaml` must reference existing tech plan slices through `docs.tech_plan`, multiple development draft tasks need distinct primary tech plan slices, and explicit AI provider/copilot, external-system, or compliance/permission/audit themes require dedicated architecture slices. Draft tasks with runnable boundaries must also include `self_test_contract`, backed by a `Development Self-Test Contract` section in the tech plan; the contract must include `module_key_test_path` from local start or invocation to all self-test scenarios completion, covering every runnable entry promised by the current task/module and its internal key paths. Complex or high-risk paths may set `graph_required: true` and provide `module_key_test_graph` to express entries, checkpoints, scenarios, exits and evidence refs as a lightweight DAG.
+Before development starts, `ARCHITECTING` can return to `REQUIREMENT_GATHERING` for PRD edits or to `UI_UX_DESIGNING` for missing screen contracts, interaction states, responsive/a11y acceptance or `DESIGN.md`. The manager uses `python3 tools/transition.py --to REQUIREMENT_GATHERING` or `python3 tools/transition.py --to UI_UX_DESIGNING`, completes one stage task, runs that stage gate, then returns to the downstream phase. Requirement, acceptance, experience-contract or product-boundary changes after `SPRINTING` use RFC recalibration; `SPRINTING`, `REVIEWING`, `TESTING` and `RELEASING` can enter the controlled interrupt with `python3 tools/transition.py --to RFC_RECALIBRATION`, then return to `SPRINTING` after `validate-rfc`.
+
+When TESTING finds a bug, first record `Bugfix Route` in `.docs/07_test/TEST_REPORT.md`, then let the manager choose the lightweight return. `bugfix_uiux_replan` uses `python3 tools/transition.py --to UI_UX_DESIGNING` when PRD is correct but UX contract, screen contract, handoff matrix or `DESIGN.md` is wrong. `bugfix_replan` uses `python3 tools/transition.py --to ARCHITECTING` when the technical plan, interface contract, task breakdown, Development Self-Test Contract or Module Key Test Graph must change. `bugfix_implementation_gap` uses `python3 tools/transition.py --to SPRINTING` only when the technical plan is still correct and implementation deviated from it. Requirement, acceptance or product-boundary changes still use RFC recalibration.
+
+`validate-uiux` requires at least one non-overview `.docs/02_experience/**` deliverable. UX slices must cite PRD / requirement IDs or explicitly declare `Applicability: not_applicable`; visual UI slices require root `DESIGN.md` and fail on `@google/design.md` linter errors. Warnings are reported by the linter but are not treated as default blockers.
+
+`validate-design` treats semantic slicing as a hard gate. Generated `overview.md` files do not count as deliverables, development draft tasks in `plan.draft.yaml` must reference existing tech plan slices through `docs.tech_plan`, UI/frontend draft tasks must reference existing UX slices through `docs.uiux` and root `DESIGN.md` through `docs.design_system`, multiple development draft tasks need distinct primary tech plan slices, and explicit AI provider/copilot, external-system, or compliance/permission/audit themes require dedicated architecture slices. Draft tasks with runnable boundaries must also include `self_test_contract`, backed by a `Development Self-Test Contract` section in the tech plan; the contract must include `module_key_test_path` from local start or invocation to all self-test scenarios completion, covering every runnable entry promised by the current task/module and its internal key paths. Complex or high-risk paths may set `graph_required: true` and provide `module_key_test_graph` to express entries, checkpoints, scenarios, exits and evidence refs as a lightweight DAG.
 
 SPRINTING Definition of Done includes module-level runnable delivery boundaries. API, CLI, server route, service, agent, runtime, adapter, worker, provider, config-contract and fixture/live boundaries promised by a technical plan or task must be implemented or marked `BLOCKED` during development. Runtime/app/provider/live tasks must declare `evidence_level.required`, `target_runtime_environment` and `self_test_contract` in `plan.yaml`; every gate in `self_test_contract.required_gates` must also appear in task `required_gates`, and `self_test_contract.module_key_test_path` must describe the path from local start or invocation to all self-test scenarios completion, covering every runnable entry promised by the current task/module and its internal key paths. Complex task `module_key_test_graph` is the canonical handoff path detail: it is a DAG instead of a tree because scenarios can share setup and converge on the same observable exit; it is not a heavy test execution graph and must not store traces, debug logs, operator logs, runbook bodies or evidence bodies. `deployed_runtime` cannot be closed by `unit`, `local_runtime`, `external_provider_live`, provider smoke, fake adapters or localhost smoke alone, and `business_handoff_ready` requires a Testing Handoff Contract. The current task implementation doc must include `Development Evidence` and a completed `Development Self-Test Report` with `Report Status: PASS | BLOCKED | IN_PROGRESS | STALE`, contract source, Module Application Entry, scenario results, executed gates, Module Key Test Path, Module Key Test Graph when required, Observable Exit, Current Blocker, Testing Handoff Readiness and Evidence Index Refs; only `Report Status: PASS` with every scenario `PASS` can close a development task. The report proves module entry, core path, exit and minimal evidence pointers; it is not a debug log, operator log, runbook, evidence dump or exploration history. Fallback/diagnostic detail belongs in `.docs/09_runbooks/**` evidence indexes, appendices or git history. The report must not use an `Actual Evidence` body field, should stay under 80 lines for ordinary tasks and under 120 lines for high-risk runtime tasks. Module Key Test Path records actual entries, internal key paths, boundaries, checkpoints and observable completion evidence. Provider smoke, fixture smoke, fake adapters and one-shot smoke prove only local links; they do not by themselves prove application readiness. REVIEWING treats missing entry/exit, initialization, config contract, target runtime, evidence level or development evidence as blocking, and TESTING only exercises entrypoints that Review has confirmed as `PASS`; complex paths are consumed through Module Key Test Graph, and TESTING must not add product runtime, bootstrap, provider adapter, deploy code or package runtime scripts.
 
@@ -99,7 +105,7 @@ High-risk runtime/live/remote-operator tasks are resume-first. When the current
 
 Migration cost for the lightweight DAG test path graph is zero to low. Existing projects, tasks and implementation docs that only use `module_key_test_path` remain valid; missing graphs are not retroactively rejected. Managed consumers can run `npx sdlc-harness upgrade`, or `npx sdlc-harness sync` when only managed files need refreshing. New high-risk or multi-scenario tasks will be prompted to generate `graph_required: true` and a graph skeleton. Existing high-risk tasks can be manually improved by splitting their current Module Key Test Path into a DAG. No automatic text-to-graph migration is provided because branches, checkpoints and observable exits require human or Agent judgment, and automatic conversion can invent false structure.
 
-`validate-test` keeps its command name as the TESTING phase gate. `.docs/07_test/TEST_STRATEGY.md` describes scope, environment, priority and execution strategy; `.docs/07_test/TEST_CASES.md` describes cases bound to real runnable entry/exit; `.docs/07_test/TEST_REPORT.md` only records executed TESTING evidence, test matrix, regression evidence, runnable entry/exit coverage, coverage gaps and final decision. `validate-test` only accepts `TEST_REPORT.md`; it no longer treats `TEST_PLAN.md` as a report fallback.
+`validate-test` keeps its command name as the TESTING phase gate. `.docs/07_test/TEST_STRATEGY.md` describes scope, environment, priority and execution strategy; `.docs/07_test/TEST_CASES.md` describes cases bound to real runnable entry/exit; `.docs/07_test/TEST_REPORT.md` only records executed TESTING evidence, test matrix, regression evidence, runnable entry/exit coverage, coverage gaps and final decision. Cases in `TEST_CASES.md` use stable `TC-*` IDs and record requirement/risk refs, runnable entry, preconditions, steps, expected exit, type, priority and short evidence pointers; execution results, bugfix route and final decision stay in `TEST_REPORT.md`. `validate-test` only accepts `TEST_REPORT.md`; it no longer treats `TEST_PLAN.md` as a report fallback. Existing projects without `TEST_CASES.md` continue to pass, but reports that reference `TC-*`, TESTING tasks that plan `TEST_CASES.md`, or existing `TEST_CASES.md` files trigger lightweight case structure and reference validation.
 
 Do not create formal `.docs/07_test/**` test cases or reports before development has delivered testable entry/exit. When an RFC changes the technical route, entry/exit or acceptance boundary, review `.docs/07_test/**` and remove superseded test results from current facts and `.docs/INDEX.md`.
 
@@ -120,6 +126,9 @@ npx sdlc-harness sync
 npx sdlc-harness upgrade
 npx sdlc-harness doctor
 npx sdlc-harness validate-plan
+npx sdlc-harness validate-uiux
+npx sdlc-harness validate-design
+npx sdlc-harness validate-dev
 npx sdlc-harness validate-review
 npx sdlc-harness validate-test
 npx sdlc-harness validate-release

package/assets/agents/AGENTS_CORE.md

@@ -10,6 +10,8 @@
 - 计划草案：`.codex/state/plan.draft.yaml`
 - 项目长期记忆：`.codex/state/memory.md`
 - 产品文档：`.docs/01_product/`
+- 体验设计文档：`.docs/02_experience/`
+- 视觉设计系统：`DESIGN.md`（仅 visual UI 项目强制）
 - 架构文档：`.docs/02_architecture/`
 - 技术方案：`.docs/03_tech_plan/`
 - 实现文档：`.docs/04_implementation/`
@@ -32,7 +34,7 @@
 
 - `plan.yaml` 是当前和未来任务的短期执行计划事实源。每个阶段的每个 Agent 主任务都应先检查是否过长，必要时拆成大小合适的 open task；open task 直接包含 `phase`、`allowed_paths`、`required_gates`、`acceptance_criteria` 和必要的 `working_notes`。
 - `current_phase` 只保存在 `lifecycle.yaml`；不要在 `plan.yaml`、`plan.draft.yaml` 或 `parallel_execution` 中重复保存当前阶段。
-- 新建任务统一使用 `TASK-*` id，并通过 `phase` 标明属于 `REQUIREMENT_GATHERING`、`ARCHITECTING`、`SPRINTING`、`REVIEWING`、`TESTING`、`RELEASING` 或 `RFC_RECALIBRATION`；历史 `PRD-*`、`DES-*`、`DEV-*` 只作为兼容旧记录和旧提交的 provenance。
+- 新建任务统一使用 `TASK-*` id，并通过 `phase` 标明属于 `REQUIREMENT_GATHERING`、`UI_UX_DESIGNING`、`ARCHITECTING`、`SPRINTING`、`REVIEWING`、`TESTING`、`RELEASING` 或 `RFC_RECALIBRATION`；历史 `PRD-*`、`DES-*`、`DEV-*` 只作为兼容旧记录和旧提交的 provenance。
 - `next_task_sequence` 记录下一个可分配的 `TASK-*` 序号，避免删除历史 task 后发生 id 冲突。
 - 文档、Review、测试、发布和 RFC 类 task 使用 `result_docs` 指向本 task 产出的 PRD、architecture、tech plan、ADR、review report、test report、current release status、RFC 或 `plan.draft.yaml`；开发 task 使用 `implementation_doc` 指向模块级实现事实。
 - task 完成并写入或更新相关事实源后，从 `plan.yaml` 的 `tasks` 列表移除该 task；不要长期保留 done/cancelled task 摘要。
@@ -52,7 +54,7 @@
 - 机器契约保持英文，包括字段名、路径、命令、阶段枚举、状态枚举、脚本参数。
 - 不翻译 `.codex/state/*.yaml`、`.codex/pjsdlc_managed/policies/*.yaml` 中的 key。
 - 不翻译 `current_phase`、`active_skill`、`allowed_paths`、`required_gates`、`implementation_doc` 等字段名。
-- 不翻译 `REQUIREMENT_GATHERING`、`ARCHITECTING`、`SPRINTING`、`REVIEWING`、`TESTING`、`RELEASING`、`RFC_RECALIBRATION`、`BLOCKED` 等阶段枚举。
+- 不翻译 `REQUIREMENT_GATHERING`、`UI_UX_DESIGNING`、`ARCHITECTING`、`SPRINTING`、`REVIEWING`、`TESTING`、`RELEASING`、`RFC_RECALIBRATION`、`BLOCKED` 等阶段枚举。
 - 不翻译 `pending`、`in_progress`、`done`、`blocked`、`pending_revision`、`cancelled` 等任务状态。
 - 不翻译 `make validate-*`、`python3 tools/transition.py --to <PHASE>`、`.docs/01_product/`、`.codex/state/plan.yaml` 等命令和路径。
 - 后续更新 `.codex/skills/*/SKILL.md`、`.codex/skills/authoring/*/SKILL.md` 或 `.codex/pjsdlc_managed/templates/*.md` 时，遵循“中文解释 + 英文精确标识符”。Harness 根目录由 `package.json#sdlcHarness.harnessFolderName` 或 `sdlc-harness.config.json#harnessFolderName` 决定；本仓库显式配置为 `.codex`。
@@ -130,7 +132,7 @@ Strong success criteria 可以让你 independent loop。Weak criteria，例如
 ### Harness 补充原则
 
 1. 阶段约束优先：除非用户明确要求其它工作流动作，否则使用 `active_skill` 指定的 workflow skill，并服从当前阶段的 allowed paths、required gates 和交付物边界。
-2. 文档先于实现：产品文档和技术方案未形成前，不写业务代码；尚未进入 `SPRINTING` 且仍在 `ARCHITECTING` 时，可以通过 `transition.py --to REQUIREMENT_GATHERING` 回到 PM/PRD 工作流修改产品事实；进入 `SPRINTING` 后的需求变更必须进入 RFC 工作流。
+2. 文档先于实现：产品文档、体验设计和技术方案未形成前，不写业务代码；尚未进入 `SPRINTING` 且仍在 `ARCHITECTING` 时，可以通过 `transition.py --to REQUIREMENT_GATHERING` 回到 PM/PRD 工作流修改产品事实，或通过 `transition.py --to UI_UX_DESIGNING` 回到 UI/UX 工作流补体验事实；进入 `SPRINTING` 后的需求变更必须进入 RFC 工作流。
 3. 验证闭环：多步骤工作先给出简短计划，并为关键步骤绑定验证方式。除非被阻塞，否则持续迭代到对应 `required_gates`、阶段 gate 或明确的人工验收标准满足。
 4. 派生物可再生成：`overview.md`、包内 assets 等 generated artifact 必须由对应命令刷新，不手写局部补丁。
 
@@ -138,13 +140,13 @@ Strong success criteria 可以让你 independent loop。Weak criteria，例如
 
 1. 选择任何角色或 skill 前，先读取 `.codex/state/lifecycle.yaml`。
 2. 除非用户明确要求其它工作流动作，否则使用 `active_skill` 指定的 workflow skill。
-3. 产品文档和技术方案未形成前，不写业务代码。
+3. 产品文档、体验设计和技术方案未形成前，不写业务代码。
 4. 每个阶段一次只执行一个 open task；如果任务过长，先拆成多个 `TASK-*`，当前轮只推进 `current_task_id`。
 5. 每个阶段只编辑当前 open task 的 `allowed_paths` 允许的文件；只读角色仍不得修改源码。
 6. 不要在当前 open task 的 `required_gates` 通过前把任务标记为 `done`。
 7. 代码 gate 通过后，更新相关 implementation doc 和 `.docs/INDEX.md`。
 8. `reviewer` 角色只读，不直接修改源码。
-9. 进入 `SPRINTING` 后的需求变更必须进入 RFC 工作流；`ARCHITECTING` 阶段发现 PRD 需要修改时，可以先回到 `REQUIREMENT_GATHERING`。
+9. 进入 `SPRINTING` 后的需求变更必须进入 RFC 工作流；`ARCHITECTING` 阶段发现 PRD 需要修改时，可以先回到 `REQUIREMENT_GATHERING`，发现屏幕、交互或视觉事实缺失时可以回到 `UI_UX_DESIGNING`；`TESTING` 阶段发现 bug 时，先在 `TEST_REPORT.md` 判定 `Bugfix Route`，再轻量回到 `UI_UX_DESIGNING`、`ARCHITECTING` 或 `SPRINTING`。
 10. task/release 历史动作记录使用 git commit、tag 或外部 release 系统，不维护 `<harnessRoot>/archive/` 常规归档。
 11. 在 `SPRINTING` 阶段，task 完成闭环必须先创建 task implementation commit，再提交移除该 task 后的 task completion ledger commit；如果没有 remote/upstream、权限或凭证导致无法 push，不要开始下一个 task，先报告 blocker。
 12. 文档 slice 发生变化后，运行 `make docs-overview` 刷新对应 `overview.md`。
@@ -162,12 +164,14 @@ Strong success criteria 可以让你 independent loop。Weak criteria，例如
 - “现在到哪了 / 状态如何” → 等价 `/status`。
 - “继续 / 下一步 / 推进” → 等价 `/next`。
 - “能进入下一阶段吗 / 进入下一步” → 等价 `/advance`。
-- “需求变了 / 这个设计要改” → 如果当前仍在 `ARCHITECTING` 且尚未进入开发，可回到 `REQUIREMENT_GATHERING` 修改 PRD；如果已经进入 `SPRINTING` 或之后，进入 RFC workflow。
+- “需求变了 / 这个设计要改” → 如果当前仍在 `ARCHITECTING` 且尚未进入开发，可回到 `REQUIREMENT_GATHERING` 修改 PRD，或回到 `UI_UX_DESIGNING` 修改体验 / 屏幕 / 视觉事实；如果已经进入 `SPRINTING` 或之后，进入 RFC workflow。
 - “完善产品方案 / 写 PRD / 文档切片 / 我提供信息，你帮我完善产品方案” → 在 `REQUIREMENT_GATHERING` 等价 `/prd`；在 `ARCHITECTING` 且尚未进入开发时，先流转回 `REQUIREMENT_GATHERING`，再一次只执行一个 `phase: "REQUIREMENT_GATHERING"` 的 `TASK-*`。
+- “做 UI/UX 设计 / 交互设计 / 视觉设计 / 屏幕设计” → 等价 `/uiux`，一次只执行一个 `phase: "UI_UX_DESIGNING"` 的 `TASK-*`，产出 `.docs/02_experience/**` 和必要时的 `DESIGN.md`。
 - “设计技术方案 / 做架构方案 / 根据 PRD 做技术方案 / 切技术方案” → 等价 `/design`，一次只执行一个 `phase: "ARCHITECTING"` 的 `TASK-*`。
 - “开始开发 / 做当前任务 / 做下一个任务” → 等价 `/dev`。
 - “开始循环：写任务，执行任务 / 把开发循环跑完” → 等价 `/devloop`。
 - “跑测试 / 验证一下” → 运行当前 task 或阶段对应 gate。
+- “测试发现 bug / 回去修 / 修测试问题” → 如果当前是 `TESTING`，先读取 `TEST_REPORT.md#Bugfix Route`；`bugfix_uiux_replan` 回 `UI_UX_DESIGNING` 修改体验契约，`bugfix_replan` 回 `ARCHITECTING` 修改技术方案后再开发，`bugfix_implementation_gap` 回 `SPRINTING` 补实现任务，需求或验收变化走 RFC。
 - 每个阶段任务开始时，默认先做 parallel eligibility check；适合安全拆分时，主 Agent 创建或使用 `parallel_execution.trigger: "workflow_default"` 并调度 Codex native subagents。用户说“并行 / 多 agent / 多 worktree / parallel” → 使用 `trigger: "user_requested"` 强化该意图。
 - “准备 review / 帮我 review” → 进入只读 Review workflow。
 - “刷新文档总览 / 同步 overview” → 等价 `/overview`。
@@ -179,9 +183,10 @@ Parallel Execution 是默认评估、按需启用的协作协议。`parallel_exe
 
 - `/status`：报告当前阶段、角色、任务、阻塞项和下一步动作。
 - `/next`：运行当前阶段映射的 workflow skill。
-- `/advance`：校验当前阶段出口 gate，通过后才尝试流转；`ARCHITECTING` 的可选返回目标是 `REQUIREMENT_GATHERING`，用于开发前修改 PRD。
+- `/advance`：校验当前阶段出口 gate，通过后才尝试流转；`ARCHITECTING` 的可选返回目标是 `REQUIREMENT_GATHERING` 或 `UI_UX_DESIGNING`，用于开发前修改 PRD 或体验事实。
 - `/rfc <file>`：挂起当前流程并进入 RFC recalibration。
 - `/prd`：在 `REQUIREMENT_GATHERING` 创建或选择一个最小 `TASK-*` task，澄清需求或切片文档，并只更新当前 task 对应的 PRD、验收标准、open questions、`.docs/INDEX.md` 和 overview；如果当前是 `ARCHITECTING` 且尚未进入开发，可先回到 `REQUIREMENT_GATHERING`。
+- `/uiux`：在 `UI_UX_DESIGNING` 创建或选择一个最小 `TASK-*` task，基于 PRD 生成 UX flow、screen contracts、interaction states、responsive/a11y acceptance、handoff matrix 和必要时的 `DESIGN.md`。
 - `/design`：在 `ARCHITECTING` 创建或选择一个最小 `TASK-*` task，基于 PRD 生成或切分当前 task 对应的 architecture、tech plan 和 `plan.draft.yaml`。
 - `/dev`：在 `SPRINTING` 创建或选择下一个最小 `TASK-*` development task；如果从 `plan.draft.yaml.tasks[]` promote draft，必须同次消费并删除该 draft；随后执行一个 task，跑 gate，更新模块级 implementation doc，按两段 commit/push 闭环后停止。
 - `/devloop`：在 `SPRINTING` 连续运行 `/dev` 循环，直到 `plan.yaml.tasks[]` 和 `plan.draft.yaml.tasks[]` 都没有明确可执行任务，或遇到需求、架构、allowed_paths、gate、commit/push blocker。
@@ -200,3 +205,9 @@ python3 tools/transition.py --to <PHASE>
 
 流转前先运行阶段 gate，通常使用 `make validate-current`，或使用
 `.codex/pjsdlc_managed/policies/phase_contracts.yaml` 中列出的具体 `make validate-*` 目标。
+
+`TESTING` 中发现 bug 时不要直接重试或改 runtime。先让测试报告记录 `Bugfix Route`：`bugfix_uiux_replan`
+表示 PRD 正确但 UX contract / screen contract / `DESIGN.md` 错误，需要回 `UI_UX_DESIGNING`；`bugfix_replan`
+表示回 `ARCHITECTING` 修 tech plan / task breakdown / handoff graph；`bugfix_implementation_gap`
+表示技术方案仍正确、只回 `SPRINTING` 补实现偏差；需求、验收标准或产品边界变化仍走
+`RFC_RECALIBRATION`。

package/assets/docs/README.md

@@ -60,8 +60,8 @@ npx sdlc-harness init --adopt
 | 同步 managed workflow 文件 | `npx sdlc-harness sync` | 从包内 canonical assets 物化 `AGENTS.md` managed block、workflow skills、templates、policies、Makefile 片段、GitHub workflow，并安全更新 user-owned Markdown guidance sections |
 | 升级已接入项目 | `npx sdlc-harness upgrade` | 执行迁移并自动 `sync`，保留 state、docs、业务代码和本地 override，同时迁移旧 seed guidance |
 | 接入诊断 | `npx sdlc-harness doctor` | 检查 harness root、版本、schema、关键文件和 managed paths |
-| 阶段 gate | `npx sdlc-harness validate-*`、`make validate-current`、`make validate-harness` | 校验需求、设计切片、开发、Review、测试、发布、RFC、Harness 骨架、提示词语言契约和 overview freshness |
-| 生命周期工作流 | `lifecycle.yaml`、`plan.yaml`、`.docs/**` | 固定 REQUIREMENT_GATHERING、ARCHITECTING、SPRINTING、REVIEWING、TESTING、RELEASING、RFC_RECALIBRATION 等阶段事实链 |
+| 阶段 gate | `npx sdlc-harness validate-*`、`make validate-current`、`make validate-harness` | 校验需求、UI/UX、架构设计、开发、Review、测试、发布、RFC、Harness 骨架、提示词语言契约和 overview freshness |
+| 生命周期工作流 | `lifecycle.yaml`、`plan.yaml`、`.docs/**` | 固定 REQUIREMENT_GATHERING、UI_UX_DESIGNING、ARCHITECTING、SPRINTING、REVIEWING、TESTING、RELEASING、RFC_RECALIBRATION 等阶段事实链 |
 | 阶段小任务管控 | `plan.yaml`、`make validate-plan` | 每个阶段的 Agent 主任务都应拆成足够小的 `TASK-*` open task，并用 `phase` 标明所属阶段 |
 | 自然语言控制 | `AGENTS.md` + workflow skills | 用户可说“继续”“开始开发”“跑测试”“需求变了”等，由 Agent 映射到 `/next`、`/dev`、`/test`、RFC 等动作 |
 | 默认并行调度合同 | `plan.yaml#parallel_execution` | 阶段任务默认评估是否可安全并行；适合时优先使用 Codex native subagents，并保留 user-orchestrated / worktree fallback |
@@ -86,6 +86,8 @@ npx sdlc-harness init --adopt
 把这个长产品方案切成 slices。
 根据 PRD 做技术方案。
 把现有技术方案切片。
+做 UI/UX 设计。
+补一下交互设计。
 根据技术方案拆 task。
 开始开发当前 task。
 继续开发下一个任务。
@@ -100,13 +102,17 @@ Agent 会读取 `<harnessRoot>/state/lifecycle.yaml` 和 `<harnessRoot>/state/pl
 
 通用规则是：任何阶段或工作流如果把 draft task promote 成 `plan.yaml` 中的正式 `TASK-*`，必须在同一次状态更新里从源 draft queue 删除该 draft；正式 task 的恢复现场只保存在 `plan.yaml`，完成历史由 implementation docs、git/PR/CI 记录承担。当前 Harness 内置的 draft queue 只有 `plan.draft.yaml.tasks[]`，它表示尚未采用的开发草案；`/devloop` 只有在 `plan.yaml.tasks[]` 和 `plan.draft.yaml.tasks[]` 都没有明确可执行任务时，才把开发队列视为耗尽。
 
-技术方案阶段需要产出 `plan.draft.yaml`，是为了解决跨阶段交接和当前执行队列纯净性的冲突。`ARCHITECTING` 必须在进入开发前证明方案可以拆成具体、可验证的开发单元，包括修改范围、gate、implementation doc 和执行顺序；但这些未来开发 task 如果直接进入 `plan.yaml`，会和当前架构阶段 task 混在一起，让阶段 gate 无法区分“架构任务未完成”和“下一阶段任务已预拆”。因此开发任务先作为 draft 暂存，进入 `SPRINTING` 后再逐个 promote 成正式 `TASK-*`。其它阶段默认根据上一阶段已经稳定的事实源即时创建当前阶段 task，只有当某个阶段也需要提前为后续阶段生成具体执行任务时，才应引入同类 draft queue。
+`UI_UX_DESIGNING` 插在 PRD 和架构之间，用 `.docs/02_experience/**` 固定用户旅程、screen contracts、interaction states、responsive/a11y acceptance 和 handoff matrix。visual UI 项目还要维护根目录 `DESIGN.md`，用 Google `DESIGN.md` 格式保存 colors、typography、spacing、components 等设计系统事实；CLI/API/non-visual 项目可以在 UX slice 中声明 `Applicability: cli_or_api_experience` 或 `Applicability: not_applicable`。
 
-阶段关系由 `<harnessRoot>/pjsdlc_managed/policies/phase_contracts.yaml` 中的轻量显式有向图表达：`phases` 保存稳定阶段 contract，`transitions` 保存合法流转边和少量效果，例如设置或清理 `suspended_phase`。这样做是为了让正常推进、开发前返回、RFC interrupt/resume 和 BLOCKED resume 都被 transition helper 与 validator 读取，避免规则埋在长文档或工具硬编码里。它不是重型图引擎，不保存历史、不做复杂遍历、不引入 node/edge class 或可视化；目标只是降低遗漏和漂移。
+技术方案阶段需要产出 `plan.draft.yaml`，是为了解决跨阶段交接和当前执行队列纯净性的冲突。`ARCHITECTING` 必须在进入开发前证明方案可以拆成具体、可验证的开发单元，包括修改范围、gate、implementation doc、执行顺序，以及 UI/frontend task 对 `.docs/02_experience/**` 和 `DESIGN.md` 的引用；但这些未来开发 task 如果直接进入 `plan.yaml`，会和当前架构阶段 task 混在一起，让阶段 gate 无法区分“架构任务未完成”和“下一阶段任务已预拆”。因此开发任务先作为 draft 暂存，进入 `SPRINTING` 后再逐个 promote 成正式 `TASK-*`。其它阶段默认根据上一阶段已经稳定的事实源即时创建当前阶段 task，只有当某个阶段也需要提前为后续阶段生成具体执行任务时，才应引入同类 draft queue。
 
-迁移成本较低：对使用 managed assets 的项目，运行 `npx sdlc-harness upgrade` 即可同步新的 `phase_contracts.yaml` 和 `tools/transition.py`；也可以运行 `npx sdlc-harness sync` 只刷新 managed 文件。`lifecycle.yaml` 和 `plan.yaml` 不需要手动迁移，旧的 `allowed_next_phases` 会在下一次 `transition.py` 执行后按图重新生成。只有维护了自定义 phase policy 的项目需要把阶段内的 `next` / `returns` 转成 top-level `transitions`；如果升级前直接运行新版 `validate-harness` 看到缺少 `transitions`，先执行 `upgrade` / `sync`。
+阶段关系由 `<harnessRoot>/pjsdlc_managed/policies/phase_contracts.yaml` 中的轻量显式有向图表达：`phases` 保存稳定阶段 contract，`transitions` 保存合法流转边和少量效果，例如设置或清理 `suspended_phase`。这样做是为了让正常推进、开发前返回、TESTING bugfix return、RFC interrupt/resume 和 BLOCKED resume 都被 transition helper 与 validator 读取，避免规则埋在长文档或工具硬编码里。它不是重型图引擎，不保存历史、不做复杂遍历、不引入 node/edge class 或可视化；目标只是降低遗漏和漂移。
 
-在尚未进入开发前，`ARCHITECTING` 可以回到 `REQUIREMENT_GATHERING` 修改 PRD：Manager 使用 `python3 tools/transition.py --to REQUIREMENT_GATHERING` 切回 PM/PRD 工作流，完成 PRD task 和 `validate-pm` 后，再用 `python3 tools/transition.py --to ARCHITECTING` 回到设计阶段。进入 `SPRINTING` 后的需求或设计变化走 RFC workflow；`SPRINTING`、`REVIEWING`、`TESTING` 和 `RELEASING` 都可以通过 `python3 tools/transition.py --to RFC_RECALIBRATION` 进入受控 RFC 中断，RFC 完成后回到 `SPRINTING` 重新完成开发自测和 handoff。
+迁移成本较低：对使用 managed assets 的项目，运行 `npx sdlc-harness upgrade` 即可同步新的 `phase_contracts.yaml`、`tools/transition.py`、`pjsdlc_uiux_design`、`UI_UX_DESIGN_TEMPLATE.md` 和 `validate-uiux`；也可以运行 `npx sdlc-harness sync` 只刷新 managed 文件。`lifecycle.yaml` 和 `plan.yaml` 不需要手动迁移，旧的 `allowed_next_phases` 会在下一次 `transition.py` 执行后按图重新生成。只有维护了自定义 phase policy 的项目需要把阶段内的 `next` / `returns` 转成 top-level `transitions`，并加入 `REQUIREMENT_GATHERING -> UI_UX_DESIGNING -> ARCHITECTING`、`ARCHITECTING -> UI_UX_DESIGNING`、`TESTING -> UI_UX_DESIGNING` / `ARCHITECTING` / `SPRINTING` return edges；如果升级前直接运行新版 `validate-harness` 看到缺少 `transitions`，先执行 `upgrade` / `sync`。
+
+在尚未进入开发前，`ARCHITECTING` 可以回到 `REQUIREMENT_GATHERING` 修改 PRD，也可以回到 `UI_UX_DESIGNING` 补 screen contracts、interaction states、responsive/a11y acceptance 或 `DESIGN.md`：Manager 使用 `python3 tools/transition.py --to REQUIREMENT_GATHERING` 或 `python3 tools/transition.py --to UI_UX_DESIGNING` 切回对应工作流，完成 task 和 gate 后再回到后续阶段。进入 `SPRINTING` 后的需求、验收标准、体验契约或产品边界变化走 RFC workflow；`SPRINTING`、`REVIEWING`、`TESTING` 和 `RELEASING` 都可以通过 `python3 tools/transition.py --to RFC_RECALIBRATION` 进入受控 RFC 中断，RFC 完成后回到 `SPRINTING` 重新完成开发自测和 handoff。
+
+TESTING 阶段发现 bug 时，先在 `.docs/07_test/TEST_REPORT.md` 记录 `Bugfix Route`，再由 Manager 选择轻量 return：`bugfix_uiux_replan` 走 `python3 tools/transition.py --to UI_UX_DESIGNING`，用于 PRD 正确但 UX contract、screen contract、handoff matrix 或 `DESIGN.md` 错误；`bugfix_replan` 走 `python3 tools/transition.py --to ARCHITECTING`，用于技术方案、接口契约、任务拆分、Development Self-Test Contract 或 Module Key Test Graph 需要改；`bugfix_implementation_gap` 走 `python3 tools/transition.py --to SPRINTING`，只用于技术方案正确但实现偏离的修复。需求、验收标准或产品边界变化仍走 RFC。
 
 `validate-design` 会把架构阶段的语义切片作为硬 gate：`overview.md` 不计入 deliverables，`plan.draft.yaml` 中每个开发 draft task 必须通过 `docs.tech_plan` 指向存在的 tech plan slice；多个开发 draft task 默认需要不同 primary tech plan slice。PRD、tech plan 或 draft task 明确出现 AI provider / copilot、外部系统边界、合规 / 权限 / 审计等横切主题时，也需要对应的专门 architecture slice。可运行边界类 draft task 还必须带 `self_test_contract`，并在 tech plan 中有 `Development Self-Test Contract`；合同必须记录 `module_key_test_path`，说明从本地启动或调用入口开始，到完成全部自测 scenario 的模块关键测试路径，并覆盖本 task / 本模块承诺的所有可运行入口和内部关键路径。复杂或 high-risk 路径可设置 `graph_required: true` 并提供 `module_key_test_graph`，把入口、checkpoint、scenario、出口和 evidence refs 表达成轻量 DAG。
 
@@ -118,7 +124,7 @@ SPRINTING 的 Definition of Done 包含模块级可运行交付边界：技术
 
 轻量 DAG 测试路径图的迁移成本为零到低：旧项目、旧 task 和旧 implementation doc 只写 `module_key_test_path` 仍然有效；缺少 graph 不会被 retroactive fail。升级 managed consumers 时运行 `npx sdlc-harness upgrade`，只刷新 managed files 时运行 `npx sdlc-harness sync`。新 high-risk / multi-scenario task 会由更新后的 prompts 倾向生成 `graph_required: true` 和 `module_key_test_graph` skeleton。旧 high-risk task 如需提升交接质量，可手动把现有 `Module Key Test Path` 拆成 DAG；不提供自动 text-to-graph migration，因为分支、checkpoint 和 observable exit 需要人工或 Agent 判断，自动转换容易制造虚假结构。
 
-`validate-test` 仍然是 TESTING 阶段 gate 名称。`.docs/07_test/TEST_STRATEGY.md` 描述测试范围、环境、优先级和执行策略；`.docs/07_test/TEST_CASES.md` 描述绑定真实 runnable entry/exit 的测试用例；`.docs/07_test/TEST_REPORT.md` 只记录 TESTING 阶段实际执行后的 test matrix、regression evidence、runnable entry/exit coverage、coverage gaps 和 final decision。`validate-test` 只接受 `TEST_REPORT.md`，不会把 `TEST_PLAN.md` 当作 report fallback。
+`validate-test` 仍然是 TESTING 阶段 gate 名称。`.docs/07_test/TEST_STRATEGY.md` 描述测试范围、环境、优先级和执行策略；`.docs/07_test/TEST_CASES.md` 描述绑定真实 runnable entry/exit 的测试用例；`.docs/07_test/TEST_REPORT.md` 只记录 TESTING 阶段实际执行后的 test matrix、regression evidence、runnable entry/exit coverage、coverage gaps 和 final decision。`TEST_CASES.md` 中的 case 使用稳定 `TC-*` ID，记录 requirement/risk ref、runnable entry、preconditions、steps、expected exit、type、priority 和短 evidence pointer；执行结果、bugfix route 和最终结论只进入 `TEST_REPORT.md`。`validate-test` 只接受 `TEST_REPORT.md`，不会把 `TEST_PLAN.md` 当作 report fallback；旧项目缺少 `TEST_CASES.md` 不会直接失败，但当报告引用 `TC-*`、当前 TESTING task 计划产出 `TEST_CASES.md`，或该文件已存在时，会轻量校验 case 结构和 report 引用。
 
 开发尚未完成可测试 entry/exit 前，不要在 `.docs/07_test/**` 生成正式测试用例或测试报告；验收思路应保留在 PRD acceptance criteria、tech plan verification strategy 或非执行性草稿里。RFC 改变技术路线、entry/exit 或验收边界时，必须审查 `.docs/07_test/**`，把被新方案 supersede 的旧测试结果从当前事实源和 `.docs/INDEX.md` 中移除。
 
@@ -184,6 +190,7 @@ SPRINTING 写入 worker 必须使用互不重叠的 `owned_paths`，且这些路
 | `/status` | 现在到哪一步了 | 读取 lifecycle/plan，报告当前阶段、任务、阻塞项和下一步 |
 | `/next` | 继续推进 | 按当前阶段的 `active_skill` 执行下一步 |
 | `/prd` | 完善产品方案 | 在需求阶段创建或选择一个最小 `TASK-*` task；如果当前仍在架构阶段且未进入开发，可先回到 `REQUIREMENT_GATHERING` 修改 PRD |
+| `/uiux` | 做 UI/UX 设计 | 在体验设计阶段创建或选择一个最小 `TASK-*` task，生成 `.docs/02_experience/**` 和 visual UI 的 `DESIGN.md` |
 | `/design` | 设计技术方案 | 在架构阶段创建或选择一个最小 `TASK-*` task，生成或切分当前 architecture / tech plan / `plan.draft.yaml` 产物 |
 | `/dev` | 做下一个任务 | 创建或选择下一个最小 `TASK-*` development task，完成一个 task 闭环后停止 |
 | `/devloop` | 开始循环：写任务，执行任务 | 连续运行 `/dev`，直到 `plan.yaml` 和 `plan.draft.yaml` 都没有明确任务或遇到 blocker |
@@ -224,6 +231,13 @@ make validate-current
 make validate-plan
 ```
 
+校验 UI/UX 阶段产物：
+
+```sh
+make validate-uiux
+npx sdlc-harness validate-uiux
+```
+
 校验整个 Harness：
 
 ```sh
@@ -244,6 +258,8 @@ make docs-overview
 | `<harnessRoot>/state/plan.yaml` | 当前和未来 task 的短期执行计划 |
 | `<harnessRoot>/state/memory.md` | 跨阶段稳定知识的摘要和正式事实源链接 |
 | `.docs/01_product/` | PRD、用户场景、验收标准 |
+| `.docs/02_experience/` | UX flow、screen contracts、interaction states、responsive/a11y acceptance 和 handoff matrix |
+| `DESIGN.md` | visual UI 项目的设计系统事实源；CLI/API/non-visual 项目不强制 |
 | `.docs/02_architecture/` | 架构边界和高层设计 |
 | `.docs/03_tech_plan/` | 技术方案、接口契约、任务拆分 |
 | `.docs/04_implementation/` | 模块、子系统和核心数据流的真实实现事实 |

package/assets/make/sdlc-harness.mk

@@ -1,7 +1,7 @@
 PYTHON ?= python3
 SDLC_HARNESS ?= npx sdlc-harness
 
-.PHONY: help status docs-overview validate-doc-overviews validate-harness validate-current validate-plan validate-pm validate-design validate-dev validate-review validate-test validate-release validate-rfc lint test-current-domain test-all build
+.PHONY: help status docs-overview validate-doc-overviews validate-harness validate-current validate-plan validate-pm validate-uiux validate-design validate-dev validate-review validate-test validate-release validate-rfc lint test-current-domain test-all build
 
 help:
 	@echo "AI SDLC Harness commands"
@@ -12,6 +12,7 @@ help:
 	@echo "  make validate-current    运行当前 lifecycle phase 的 gate"
 	@echo "  make validate-plan       校验 plan.yaml task 合同，允许当前 open task"
 	@echo "  make validate-pm         校验产品需求产物"
+	@echo "  make validate-uiux       校验 UI/UX 体验事实源和 DESIGN.md"
 	@echo "  make validate-design     校验架构设计、技术方案和任务草案"
 	@echo "  make validate-dev        校验 sprint 任务状态、draft 消费、路径、代码 gate 和实现文档"
 	@echo "  make validate-review     校验 Review report"
@@ -44,6 +45,9 @@ validate-pm:
 	test -f .docs/INDEX.md
 	$(PYTHON) tools/validate_prd.py
 
+validate-uiux:
+	$(PYTHON) tools/validate_uiux_design.py
+
 validate-design:
 	$(PYTHON) tools/validate_design.py
 	$(PYTHON) tools/validate_plan_draft.py

package/assets/policies/allowed_paths.yaml

@@ -13,6 +13,13 @@ phases:
       - ".docs/01_product/**"
       - ".docs/INDEX.md"
 
+  UI_UX_DESIGNING:
+    write:
+      - ".docs/02_experience/**"
+      - "DESIGN.md"
+      - "<harnessRoot>/state/plan.yaml"
+      - ".docs/INDEX.md"
+
   ARCHITECTING:
     write:
       - ".docs/02_architecture/**"
@@ -53,6 +60,8 @@ phases:
     write:
       - ".docs/rfc/**"
       - ".docs/01_product/**"
+      - ".docs/02_experience/**"
+      - "DESIGN.md"
       - ".docs/03_tech_plan/**"
       - ".docs/07_test/**"
       - ".docs/09_runbooks/**"

package/assets/policies/gates.yaml

@@ -23,6 +23,12 @@ gates:
     required_for:
       - "REQUIREMENT_GATHERING"
 
+  validate-uiux:
+    command: "make validate-uiux"
+    purpose: "验证 UI/UX 体验事实源、屏幕契约、交互状态、响应式 / a11y 验收和 DESIGN.md 设计系统"
+    required_for:
+      - "UI_UX_DESIGNING"
+
   validate-design:
     command: "make validate-design"
     purpose: "验证架构设计、技术方案、任务草案和任务字段完整性"

package/assets/policies/phase_contracts.yaml

@@ -23,6 +23,23 @@ phases:
     gates:
       - "make validate-pm"
 
+  UI_UX_DESIGNING:
+    goal: "根据产品方案形成体验事实源、屏幕契约、交互状态和设计系统交接约束"
+    role: "designer"
+    skill: "pjsdlc_uiux_design"
+    inputs:
+      - "<harnessRoot>/state/plan.yaml"
+      - ".docs/01_product/"
+      - ".docs/02_experience/"
+      - "DESIGN.md"
+    outputs:
+      - "<harnessRoot>/state/plan.yaml"
+      - ".docs/02_experience/"
+      - "DESIGN.md"
+      - ".docs/INDEX.md"
+    gates:
+      - "make validate-uiux"
+
   ARCHITECTING:
     goal: "根据产品方案生成架构设计、技术方案和任务草案"
     role: "architect"
@@ -30,6 +47,8 @@ phases:
     inputs:
       - "<harnessRoot>/state/plan.yaml"
       - ".docs/01_product/"
+      - ".docs/02_experience/"
+      - "DESIGN.md"
       - ".docs/02_architecture/"
     outputs:
       - "<harnessRoot>/state/plan.yaml"
@@ -48,7 +67,9 @@ phases:
       - "<harnessRoot>/state/plan.draft.yaml"
       - "current open task plan contract"
       - ".docs/01_product/"
+      - ".docs/02_experience/"
       - ".docs/03_tech_plan/"
+      - "DESIGN.md"
     outputs:
       - "src/"
       - "tests/"
@@ -65,8 +86,10 @@ phases:
     inputs:
       - "<harnessRoot>/state/plan.yaml"
       - ".docs/01_product/"
+      - ".docs/02_experience/"
       - ".docs/03_tech_plan/"
       - ".docs/04_implementation/"
+      - "DESIGN.md"
       - "git diff"
     outputs:
       - "<harnessRoot>/state/plan.yaml"
@@ -81,10 +104,12 @@ phases:
     inputs:
       - "<harnessRoot>/state/plan.yaml"
       - ".docs/01_product/"
+      - ".docs/02_experience/"
       - ".docs/03_tech_plan/"
       - ".docs/04_implementation/"
       - ".docs/09_runbooks/"
       - ".docs/06_review/"
+      - "DESIGN.md"
     outputs:
       - "<harnessRoot>/state/plan.yaml"
       - ".docs/07_test/TEST_STRATEGY.md"
@@ -125,7 +150,9 @@ phases:
     inputs:
       - ".docs/rfc/"
       - ".docs/01_product/"
+      - ".docs/02_experience/"
       - ".docs/03_tech_plan/"
+      - "DESIGN.md"
       - "<harnessRoot>/state/plan.yaml"
     outputs:
       - ".docs/rfc/"
@@ -152,6 +179,10 @@ transitions:
     trigger: "advance"
     kind: "normal"
   - from: "REQUIREMENT_GATHERING"
+    to: "UI_UX_DESIGNING"
+    trigger: "advance"
+    kind: "normal"
+  - from: "UI_UX_DESIGNING"
     to: "ARCHITECTING"
     trigger: "advance"
     kind: "normal"
@@ -171,6 +202,18 @@ transitions:
     to: "RELEASING"
     trigger: "advance"
     kind: "normal"
+  - from: "TESTING"
+    to: "UI_UX_DESIGNING"
+    trigger: "bugfix_uiux_replan"
+    kind: "return"
+  - from: "TESTING"
+    to: "ARCHITECTING"
+    trigger: "bugfix_replan"
+    kind: "return"
+  - from: "TESTING"
+    to: "SPRINTING"
+    trigger: "bugfix_implementation_gap"
+    kind: "return"
   - from: "RELEASING"
     to: "COMPLETED"
     trigger: "advance"
@@ -183,6 +226,14 @@ transitions:
     to: "REQUIREMENT_GATHERING"
     trigger: "return_to_prd"
     kind: "return"
+  - from: "UI_UX_DESIGNING"
+    to: "REQUIREMENT_GATHERING"
+    trigger: "return_to_prd"
+    kind: "return"
+  - from: "ARCHITECTING"
+    to: "UI_UX_DESIGNING"
+    trigger: "return_to_uiux"
+    kind: "return"
   - from: "SPRINTING"
     to: "RFC_RECALIBRATION"
     trigger: "requirement_change"
@@ -225,6 +276,12 @@ transitions:
     kind: "interrupt"
     effects:
       set_suspended_phase: true
+  - from: "UI_UX_DESIGNING"
+    to: "BLOCKED"
+    trigger: "blocked"
+    kind: "interrupt"
+    effects:
+      set_suspended_phase: true
   - from: "ARCHITECTING"
     to: "BLOCKED"
     trigger: "blocked"

package/assets/skills/pjsdlc_architect_design/SKILL.md

@@ -13,9 +13,9 @@ description: Use during ARCHITECTING to create architecture docs, technical plan
 
 你是资深架构师，目标是把产品需求转成能落地、能验证、能分工的技术方案。你不仅要产出 architecture / tech plan 文档，还要在对话中帮助用户澄清边界、约束、风险和可行路径。
 
-开始设计前，先确认 PRD 的 requirement IDs、目标用户、验收标准、Out of Scope 和未决问题。如果需求不足以做技术决策，要明确列出缺口；如果存在多种方案，要用简洁的 tradeoff 说明成本、风险、迁移复杂度、可测试性和长期维护影响。
+开始设计前，先确认 PRD 的 requirement IDs、目标用户、验收标准、Out of Scope 和未决问题，并读取 `.docs/02_experience/**` 与可选 `DESIGN.md`。如果需求不足以做技术决策，要明确列出缺口；如果 UI/UX facts 不足以拆 frontend/browser/page task，要先回到 `UI_UX_DESIGNING` 补 screen contracts、interaction states、responsive / a11y acceptance 或 DESIGN.md；如果存在多种方案，要用简洁的 tradeoff 说明成本、风险、迁移复杂度、可测试性和长期维护影响。
 
-架构产物应区分稳定边界和实现计划：architecture slice 记录领域边界、子系统、关键风险和长期约束；tech plan slice 记录接口契约、数据模型、模块方案、任务拆分和 gate。不要把重大架构变化藏在 task 描述里。
+架构产物应区分稳定边界和实现计划：architecture slice 记录领域边界、子系统、关键风险和长期约束；tech plan slice 记录接口契约、数据模型、模块方案、任务拆分和 gate。面向 UI/frontend/browser/page 的 tech plan 必须包含 `Experience Input Review`，说明消费了哪些 `.docs/02_experience/**` screen contracts、handoff matrix 和 `DESIGN.md` design tokens。不要把重大架构变化或体验事实变化藏在 task 描述里。
 
 ADR 用来解决“后来的人只看到结果，看不到当年取舍”的问题。architecture / tech plan 可以记录当前方案的局部设计理由；如果一个决定有明确备选方案、影响多个模块或阶段、未来容易被质疑、修改成本高，或需要保留 supersede 关系，就写入 `.docs/05_decisions/`。`<harnessRoot>/state/memory.md` 只保留这类决策的简短提示和链接，不承载完整背景、备选方案、取舍和后果。
 
@@ -23,6 +23,8 @@ ADR 用来解决“后来的人只看到结果，看不到当年取舍”的问
 
 如果在 `ARCHITECTING` 中发现 PRD 缺失、验收标准不清或产品边界需要调整，且项目尚未进入 `SPRINTING`，不要用架构文档替代产品事实。先收尾或移除当前 open design task，再请 Manager 使用 `python3 tools/transition.py --to REQUIREMENT_GATHERING` 回到 PM/PRD 工作流修改 `.docs/01_product/**`。进入 `SPRINTING` 后的需求变化走 RFC workflow。
 
+如果是从 `TESTING` 通过 `bugfix_replan` 回到 `ARCHITECTING`，默认只修正测试报告证明有问题的 tech plan、interface contract、task breakdown、Development Self-Test Contract 或 Module Key Test Graph，并引用 `.docs/07_test/TEST_REPORT.md` 中的失败 scenario。不要把这条路径扩成全量重设计；如果 bugfix 需要修改 PRD、acceptance criteria 或产品边界，转入 `RFC_RECALIBRATION`。
+
 架构阶段默认先评估是否适合并行调研或方案拆解。适合时，主 Agent 使用 `parallel_execution.trigger: "workflow_default"` 和 `runtime.provider: "codex_native_subagents"` 调度 worker 分别做架构草稿、接口分析、风险清单或方案对比；用户明确要求并行时使用 `trigger: "user_requested"`。worker 不直接写最终 architecture、tech plan、ADR 或 `plan.draft.yaml`，最终事实源和任务草案由主 Agent 合成；不适合拆分时保持串行并记录原因。
 
 ## 输入
@@ -30,6 +32,8 @@ ADR 用来解决“后来的人只看到结果，看不到当年取舍”的问
 - `.docs/INDEX.md`
 - `<harnessRoot>/state/plan.yaml`
 - 相关 `.docs/01_product/` PRD
+- 相关 `.docs/02_experience/` UX / screen contract 文档
+- 可选 `DESIGN.md`
 - 现有 `.docs/02_architecture/`
 - 当前代码结构概览
 - `<harnessRoot>/pjsdlc_managed/templates/TECH_DESIGN_TEMPLATE.md`
@@ -52,10 +56,11 @@ ADR 用来解决“后来的人只看到结果，看不到当年取舍”的问
 - 写 ADR 的判断标准：存在备选方案、影响多个产物或阶段、未来容易被质疑、修改成本高、或需要说明 `Supersedes / Superseded by` 时，写 ADR；只影响当前模块内部实现细节、且理由已能在 architecture / tech plan 中局部说明时，不单独写 ADR。
 - 如果一个技术方案跨越多个独立模块，应拆成多个 tech plan slice，并在 `plan.draft.yaml` 中分别引用。
 - `plan.draft.yaml` 中每个开发 draft task 必须在 `docs.tech_plan` 引用已有 `.docs/03_tech_plan/` slice；多个开发 draft task 默认应引用不同的 primary tech plan slice，不能用一个总纲 tech plan 覆盖全部模块任务。
+- UI/frontend/browser/page draft task 必须在 `docs.uiux` 引用已有 `.docs/02_experience/` slice，并在 `docs.design_system` 引用 `DESIGN.md`。非 UI task 可省略这些字段；如果刻意不适用，应在 tech plan 的 `Experience Input Review` 写明 N/A。
 - `overview.md` 是 generated artifact，不算 architecture / tech plan deliverable，也不能作为 `docs.tech_plan` 引用。
 - 如果 PRD、tech plan 或 draft task 明确出现 AI provider / AI copilot、外部系统边界、合规 / 权限 / 审计等横切主题，应各自有专门的 architecture slice；不要把多个横切架构问题都塞进一个总览文档。
 - 如果实现计划改变了已有模块边界，应更新相关 architecture slice，而不是只在 task 描述里补一句。
-- 只要技术方案或 draft task 出现 service、agent、runtime、worker、frontend app、provider/live integration 或外部可运行边界，task breakdown 必须包含最后一公里 runtime 初始化和 testing handoff 交付：目标运行环境、启动/部署或预览方式、health/readiness、smoke 输入输出、日志/错误证据、测试可调用入口和出口。
+- 只要技术方案或 draft task 出现 service、agent、runtime、worker、frontend app、browser/page、provider/live integration 或外部可运行边界，task breakdown 必须包含最后一公里 runtime 初始化和 testing handoff 交付：目标运行环境、启动/部署或预览方式、health/readiness、smoke 输入输出、日志/错误证据、测试可调用入口和出口。browser/page self-test scenarios 应从 `.docs/02_experience/**` screen contracts 和 handoff matrix 派生，而不是由 ARCHITECTING 临时发明。
 - 这类开发 draft task 必须写入 `evidence_level.required`、`target_runtime_environment` 和 `self_test_contract`。`evidence_level.required` 只能使用 `unit`、`local_runtime`、`external_provider_live`、`deployed_runtime`、`business_handoff_ready`；`target_runtime_environment.kind` 只能使用 `local`、`ci`、`staging`、`cloud_vm`、`managed_service`、`browser`、`worker`、`not_applicable`。`self_test_contract` 的 `source` 必须引用当前 tech plan slice，`required_gates` 必须同步到 task `required_gates`，`scenarios[]` 至少覆盖一个可运行入口和可观测出口，`module_key_test_path` 必须描述从本地启动或调用入口开始，到完成所有自测 scenario 的模块关键测试路径，并覆盖本 task / 本模块承诺的所有可运行入口和内部关键路径。
 - 复杂或高风险自测路径要同时生成轻量 DAG skeleton：当 scenario >= 3、多分支、多入口、runtime/live/provider/browser/worker，或 Review/Testing 需要明确消费 checkpoint / exit / evidence refs 时，在 `self_test_contract` 设置 `graph_required: true` 并填写 `module_key_test_graph`。图只保存 handoff path 的 `entry`、`checkpoint`、`branch`、`scenario`、`observable_exit` 节点和边，以及短 `evidence_ref` 指针；不要把命令输出、截图过程、operator log、debug log、runbook 正文、失败探索或历史流水塞进图。普通单入口 / 少量 scenario task 保留短 `module_key_test_path` 即可。
 - 如果 draft task 属于 high-risk runtime/live/remote-operator 工作（`external_provider_live`、`deployed_runtime`、`business_handoff_ready`，或目标环境为 `cloud_vm`、`managed_service`、`browser`、`worker`），还必须预留恢复分层：`docs.runbook` 指向 `.docs/09_runbooks/**` 下的 runbook / evidence index / exploration appendix，`allowed_paths` 覆盖这些文件，acceptance criteria 要求 promote 后维护 `plan.yaml#resume_capsule`，并把会改变下一步动作的判断 promoted 到 `resume_capsule.do_not_retry` 或 runbook 顶部 `Hard Constraints`。runbook 写 canonical operator path 和 hard constraints，evidence index 只写证据指针，exploration appendix 隔离失败尝试；不要把这些内容塞进 implementation doc 主线。
@@ -67,7 +72,7 @@ ADR 用来解决“后来的人只看到结果，看不到当年取舍”的问
 架构和技术方案阶段的方案生成、既有文档切片和上一阶段事实源合成都受 `plan.yaml` 管控：
 
 1. 没有 open task 时，先创建一个最小 `TASK-*` task，设置 `phase: "ARCHITECTING"` 和 `current_task_id`。
-2. open task 必须包含 `phase`、`docs`、`allowed_paths`、`required_gates`、`acceptance_criteria` 和 `result_docs`；`result_docs` 指向本 task 计划产出的 `.docs/02_architecture/`、`.docs/03_tech_plan/`、`.docs/05_decisions/` 或 `<harnessRoot>/state/plan.draft.yaml`。
+2. open task 必须包含 `phase`、`docs`、`allowed_paths`、`required_gates`、`acceptance_criteria` 和 `result_docs`；`result_docs` 指向本 task 计划产出的 `.docs/02_architecture/`、`.docs/03_tech_plan/`、`.docs/05_decisions/` 或 `<harnessRoot>/state/plan.draft.yaml`。若当前设计涉及 UI/frontend/browser/page，task `docs` 应引用 `.docs/02_experience/**` 和 `DESIGN.md`。
 3. 单个 task 的目标应足够小：一个子系统 architecture slice、一个 tech plan slice、一个接口契约、一组开发任务草案，或从完整技术方案中切出的一个语义 slice。
 4. 如果需要多个 architecture / tech plan slices，先生成多个 pending `TASK-*` tasks 或至少创建当前 task 并在 `working_notes` 写明剩余 slices；当前轮只执行一个 task。
 5. 执行当前 task 时只编辑 `allowed_paths` 中的文件，完成后更新 `.docs/INDEX.md`、运行 `make docs-overview`，并至少运行 `make validate-plan`；阶段出口前再运行 `make validate-design`。
@@ -81,21 +86,26 @@ ADR 用来解决“后来的人只看到结果，看不到当年取舍”的问
 2. 每个 open task 必须包含 `id`、`phase`、`title`、`status`、`summary`、`docs`、`allowed_paths`、`required_gates`、`acceptance_criteria` 和 `result_docs`；开发阶段 task 继续使用 `implementation_doc`。
 3. `plan.draft.yaml` 不得自动覆盖 `plan.yaml`。
 4. `plan.draft.yaml` 中开发 draft task 的 `docs.tech_plan` 必须指向存在的 tech plan slice；如果 task 数量超过一个，不能全部指向同一个 primary tech plan 文件。
-5. 风险或不清晰的问题按 `<harnessRoot>/pjsdlc_managed/policies/risk_matrix.yaml` 标记。
-6. 任务边界应足够小，能在一次设计执行内闭环；`result_docs` 应指向将被更新或新增的 architecture、tech plan、ADR 或 `plan.draft.yaml` 文件。
-7. `make validate-design` 是阶段出口 gate；如果还有 open `TASK-*` design task，不要请求进入 `SPRINTING`。
+5. UI/frontend/browser/page draft task 的 `docs.uiux` 必须指向存在的 `.docs/02_experience/` slice，`docs.design_system` 必须指向存在的 `DESIGN.md`。
+6. 风险或不清晰的问题按 `<harnessRoot>/pjsdlc_managed/policies/risk_matrix.yaml` 标记。
+7. 任务边界应足够小，能在一次设计执行内闭环；`result_docs` 应指向将被更新或新增的 architecture、tech plan、ADR 或 `plan.draft.yaml` 文件。
+8. `make validate-design` 是阶段出口 gate；如果还有 open `TASK-*` design task，不要请求进入 `SPRINTING`。
+9. 从 TESTING bugfix 回流的设计任务必须引用 `TEST_REPORT.md` 的 `Bugfix Route: bugfix_replan` 和失败 scenario，只补受影响的 tech plan / draft task，不修改产品事实。若 bugfix route 是 `bugfix_uiux_replan`，应回到 `UI_UX_DESIGNING` 而不是在 ARCHITECTING 修改 UX facts。
 
 ## 完成检查
 
 - [ ] 架构文档和技术方案已生成。
+- [ ] UI/frontend/browser/page 技术方案已包含 `Experience Input Review`，并引用对应 `.docs/02_experience/**` 与 `DESIGN.md`。
 - [ ] 相关接口契约和数据结构已明确。
 - [ ] 当前设计产出或切片工作已绑定 `plan.yaml` 中一个最小 `TASK-*` task，并设置 `phase: "ARCHITECTING"`。
 - [ ] 当前 task 已从 `plan.yaml` 移除，或因中断/blocker 保留为可恢复 open task。
 - [ ] 已判断 architecture / tech plan / ADR 的语义切片边界。
 - [ ] `plan.draft.yaml` 中每个开发 draft task 已通过 `docs.tech_plan` 绑定到对应 tech plan slice。
+- [ ] UI/frontend/browser/page draft task 已通过 `docs.uiux` 和 `docs.design_system` 绑定体验事实源和设计系统。
 - [ ] 如果用户要求把完整技术方案切成 tech plan slices，已删除被替代的完整 tech plan file，并同步 `plan.draft.yaml` 引用。
 - [ ] task draft 字段完整且范围清晰；runtime/app/provider/live 类 task 已声明 `evidence_level`、`target_runtime_environment` 和 `self_test_contract`。
 - [ ] 复杂或 high-risk 自测路径已判断是否需要 `graph_required: true`；需要时已在 tech plan 和 draft task 中生成 `module_key_test_graph` skeleton。
+- [ ] 如果来自 TESTING bugfix 回流，已只修正 `bugfix_replan` 指向的技术方案或任务边界，并保留 `TEST_REPORT.md` 失败 scenario 引用。
 - [ ] `.docs/INDEX.md` 已链接新增产物。
 - [ ] 已运行 `make docs-overview` 刷新 `.docs/<stage>/overview.md`。
 - [ ] `make validate-design` 准备通过。