agent-project-sdlc 0.1.24 → 0.1.26

package/README.md

@@ -19,15 +19,16 @@ npx sdlc-harness init --adopt
 
 | Capability | Entry Point | Description |
 |---|---|---|
-| Project initialization | `npx sdlc-harness init` | Creates `AGENTS.md`, `<harnessRoot>/state/**`, workflow skills, managed templates/policies, `.docs/**` and a Makefile include. |
-| Existing project adoption | `npx sdlc-harness init --adopt` | Adds Harness non-destructively to an existing repository. |
-| Configurable Harness root | `--harness-folder`, `package.json#sdlcHarness.harnessFolderName`, `sdlc-harness.config.json` | Supports Codex `.codex`, Claude `.claude`, Cursor `.cursor`, Cline `.cline`, Roo `.roo`, Gemini `.gemini` or a custom folder. |
+| Project initialization | `npx sdlc-harness init` | Creates `AGENTS.md`, `<harnessRoot>/state/**`, workflow skills, managed templates/policies, `.docs/**` and a Makefile include; fresh lifecycle starts at `REQUIREMENT_GATHERING`. |
+| Existing project adoption | `npx sdlc-harness init --adopt` | Adds Harness non-destructively to an existing repository; adopt lifecycle starts at `SPRINTING`. |
+| Configurable Harness root | `--harness-folder`, `package.json#sdlcHarness.harnessFolderName`, `sdlc-harness.config.json` | Supports Codex `.codex`, Claude `.claude`, Cursor `.cursor`, Cline `.cline`, Roo `.roo`, Gemini `.gemini` or a custom folder; root resolution prefers package.json, then config file, then `.agent`. |
 | 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. |
+| Workflow self-inspection | `npx sdlc-harness inspect-workflow` | Read-only check for workflow weight, fact-source drift, handoff clarity and recovery safety; metrics are labeled `measured`, `inferred`, `self_reported` or `unavailable`. |
+| 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,15 +84,35 @@ 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.
 
+`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`.
+
 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.
 
-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`, and add the `TESTING -> ARCHITECTING` / `TESTING -> 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.
+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`, `validate-uiux` and configured-root Python/Makefile gate fixes, 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, and the fresh/adopt initial phase split only affects new `init` runs. 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.
+
+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.
+
+## Workflow Self-Inspection
+
+Use `npx sdlc-harness inspect-workflow` when a user agent needs to check whether a repository is running the Harness workflow as intended, especially whether the workflow has become too heavy. The command is read-only: it does not write reports, run heavyweight tests, upload telemetry or invent precise token numbers.
+
+Each metric includes a `data_source`: `measured` for local files, fields or validator results the script actually read; `inferred` for proxies derived from size, duplication, missing fields or long handoff docs; `self_reported` for values explicitly supplied by the user or agent; and `unavailable` for data the local environment cannot know, such as true model token telemetry when the client did not provide it.
+
+Default workflow-weight thresholds are intentionally simple. `plan.yaml` over 200 lines is `WARN` and over 500 lines is `BLOCKED`; more than one open task is `BLOCKED`; current task `allowed_paths` over 12 is `WARN` and over 25 is `BLOCKED`; current task document refs over 5 is `WARN` and over 10 is `BLOCKED`; `working_notes` over 8 is `BLOCKED`; Development Self-Test Report size is `WARN` / `BLOCKED` above 80 / 120 lines for ordinary tasks and 120 / 180 lines for high-risk runtime tasks.
+
+When the agent or client has real recent-cost data, pass it explicitly:
+
+```sh
+npx sdlc-harness inspect-workflow --recent-minutes 18 --recent-turns 7 --estimated-tokens 12000
+```
 
-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, acceptance 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`.
+Use `--prompt` to print a self-inspection prompt for qualitative checks such as whether the current entry, task, next step, hard constraints and Review/Testing handoff are clear. Use `--json` when CI or another agent needs a machine-readable `decision`, `metrics` and `findings` report. `BLOCKED` exits non-zero; `WARN` remains a successful diagnostic exit.
 
-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_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`, 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.
+`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.
 
@@ -101,7 +122,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`.
 
@@ -121,7 +142,11 @@ npx sdlc-harness init --adopt
 npx sdlc-harness sync
 npx sdlc-harness upgrade
 npx sdlc-harness doctor
+npx sdlc-harness inspect-workflow
 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`；`TESTING` 阶段发现 bug 时，先在 `TEST_REPORT.md` 判定 `Bugfix Route`，再轻量回到 `ARCHITECTING` 或 `SPRINTING`。
+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,13 +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_replan` 回 `ARCHITECTING` 修改技术方案后再开发，`bugfix_implementation_gap` 回 `SPRINTING` 补实现任务，需求或验收变化走 RFC。
+- “测试发现 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`。
@@ -180,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。
@@ -202,7 +206,8 @@ 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_replan`
+`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

@@ -24,7 +24,7 @@ npm install -D agent-project-sdlc
 npx sdlc-harness init
 ```
 
-`init` 会先询问目标 Agent。直接回车选择默认 `Codex`，并把 Harness 配置写到 `.codex`。其它内置选项会写入对应目录，例如 `Claude Code -> .claude`、`Cursor -> .cursor`、`Cline -> .cline`、`Roo Code -> .roo`、`Gemini CLI -> .gemini`。选择 `Other` 时才会继续询问自定义文件夹名，此时直接回车默认 `.agent`。
+`init` 会先询问目标 Agent。直接回车选择默认 `Codex`，并把 Harness 配置写到 `.codex`。其它内置选项会写入对应目录，例如 `Claude Code -> .claude`、`Cursor -> .cursor`、`Cline -> .cline`、`Roo Code -> .roo`、`Gemini CLI -> .gemini`。选择 `Other` 时才会继续询问自定义文件夹名，此时直接回车默认 `.agent`。新项目 fresh init 从 `REQUIREMENT_GATHERING` 开始，避免绕过 PRD / UI/UX / architecture；已有项目使用 `--adopt` 时从 `SPRINTING` 接入，方便先对齐既有代码和 Harness 事实源。
 
 如果已经确定目录，可以跳过交互：
 
@@ -54,14 +54,15 @@ npx sdlc-harness init --adopt
 
 | 能力 | 入口 | 说明 |
 |---|---|---|
-| 新项目初始化 | `npx sdlc-harness init` | 选择目标 Agent，生成 Harness 根目录、状态文件、workflow skills、模板、策略、`.docs/**` 和 Makefile include |
-| 已有项目接入 | `npx sdlc-harness init --adopt` | 非破坏性接入已有仓库，不覆盖业务代码和已有项目事实源 |
-| 可配置 Harness 根目录 | `--harness-folder`、`package.json#sdlcHarness.harnessFolderName`、`sdlc-harness.config.json` | 支持 `.codex`、`.claude`、`.cursor`、`.cline`、`.roo`、`.gemini` 或自定义目录 |
+| 新项目初始化 | `npx sdlc-harness init` | 选择目标 Agent，生成 Harness 根目录、状态文件、workflow skills、模板、策略、`.docs/**` 和 Makefile include；fresh lifecycle 从 `REQUIREMENT_GATHERING` 开始 |
+| 已有项目接入 | `npx sdlc-harness init --adopt` | 非破坏性接入已有仓库，不覆盖业务代码和已有项目事实源；adopt lifecycle 从 `SPRINTING` 开始 |
+| 可配置 Harness 根目录 | `--harness-folder`、`package.json#sdlcHarness.harnessFolderName`、`sdlc-harness.config.json` | 支持 `.codex`、`.claude`、`.cursor`、`.cline`、`.roo`、`.gemini` 或自定义目录；解析优先级为 package.json、config file、默认 `.agent` |
 | 同步 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 等阶段事实链 |
+| 工作流自查 | `npx sdlc-harness inspect-workflow` | 只读检查 workflow weight、事实源漂移、交接清晰度和 recovery safety；每个指标标注 `measured` / `inferred` / `self_reported` / `unavailable` |
+| 阶段 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 +87,8 @@ npx sdlc-harness init --adopt
 把这个长产品方案切成 slices。
 根据 PRD 做技术方案。
 把现有技术方案切片。
+做 UI/UX 设计。
+补一下交互设计。
 根据技术方案拆 task。
 开始开发当前 task。
 继续开发下一个任务。
@@ -100,15 +103,48 @@ 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`。
+
+技术方案阶段需要产出 `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。
 
 阶段关系由 `<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 或可视化；目标只是降低遗漏和漂移。
 
-迁移成本较低：对使用 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`，并按需加入 `TESTING -> ARCHITECTING` / `TESTING -> SPRINTING` bugfix return edges；如果升级前直接运行新版 `validate-harness` 看到缺少 `transitions`，先执行 `upgrade` / `sync`。
+迁移成本较低：对使用 managed assets 的项目，运行 `npx sdlc-harness upgrade` 即可同步新的 `phase_contracts.yaml`、`tools/transition.py`、`pjsdlc_uiux_design`、`UI_UX_DESIGN_TEMPLATE.md`、`validate-uiux` 和 configured-root Python/Makefile gate 修复；也可以运行 `npx sdlc-harness sync` 只刷新 managed 文件。`lifecycle.yaml` 和 `plan.yaml` 不需要手动迁移，旧的 `allowed_next_phases` 会在下一次 `transition.py` 执行后按图重新生成；fresh/adopt 初始阶段只影响新执行的 `init`，不会重写已有 state。只有维护了自定义 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。
+
+### 工作流自查
+
+当你想知道“这个项目的 Harness 用法是否符合预期、是不是变得太重”时，运行：
+
+```sh
+npx sdlc-harness inspect-workflow
+```
+
+该命令只读检查本地事实源，不写报告、不跑重型测试、不上传 telemetry。输出状态是 `PASS`、`WARN` 或 `BLOCKED`；`BLOCKED` 会返回非零退出码。每条 metric 都会标注数据来源：
+
+- `measured`：脚本真实读到的文件、字段、validator 结果，例如 `plan.yaml` 行数、open task 数量、`allowed_paths` 数量。
+- `inferred`：脚本只能从体量、重复、字段缺失或长文档现象推断，例如当前交接上下文是否可能过重。
+- `self_reported`：用户或 Agent 显式传入的最近执行耗时、turns 或估算 token。
+- `unavailable`：当前环境没有真实 telemetry，命令不会伪造精确 token 或真实模型耗时。
+
+工作流重量的默认阈值是：`plan.yaml` 超过 200 行 `WARN`、超过 500 行 `BLOCKED`；open task 超过 1 个 `BLOCKED`；当前 task `allowed_paths` 超过 12 个 `WARN`、超过 25 个 `BLOCKED`；当前 task 关联文档超过 5 个 `WARN`、超过 10 个 `BLOCKED`；`working_notes` 超过 8 条 `BLOCKED`；`Development Self-Test Report` 普通任务超过 80 行 `WARN`、超过 120 行 `BLOCKED`，high-risk 任务使用 120 / 180 阈值。
+
+如果 Agent 或客户端知道最近一次 workflow 处理的实际成本，可以显式传入：
+
+```sh
+npx sdlc-harness inspect-workflow --recent-minutes 18 --recent-turns 7 --estimated-tokens 12000
+```
 
-在尚未进入开发前，`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。
+也可以让 Agent 用提示词自查：
 
-TESTING 阶段发现 bug 时，先在 `.docs/07_test/TEST_REPORT.md` 记录 `Bugfix Route`，再由 Manager 选择轻量 return：`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。
+```sh
+npx sdlc-harness inspect-workflow --prompt
+```
+
+`--prompt` 会要求 Agent 区分真实可测数据、推断数据、自报数据和不可测数据，并检查入口、当前任务、下一步、hard constraint promotion、交接卡边界和 Review / Testing 可消费性。`--json` 可用于 CI 或自动化读取。
 
 `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。
 
@@ -120,7 +156,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` 中移除。
 
@@ -186,6 +222,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 |
@@ -214,6 +251,13 @@ npx sdlc-harness sync
 npx sdlc-harness upgrade
 ```
 
+自查工作流重量和交接清晰度：
+
+```sh
+npx sdlc-harness inspect-workflow
+npx sdlc-harness inspect-workflow --prompt
+```
+
 运行当前阶段 gate：
 
 ```sh
@@ -226,6 +270,13 @@ make validate-current
 make validate-plan
 ```
 
+校验 UI/UX 阶段产物：
+
+```sh
+make validate-uiux
+npx sdlc-harness validate-uiux
+```
+
 校验整个 Harness：
 
 ```sh
@@ -246,6 +297,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,10 @@ 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"
@@ -191,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"
@@ -233,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"