agent-project-sdlc 0.1.24 → 0.1.25

package/assets/templates/TECH_DESIGN_TEMPLATE.md

@@ -11,7 +11,15 @@
 - 相关 APIs（Related APIs）:
 - 相关数据（Related data）:
 
-## 3. 方案架构
+## 3. Experience Input Review（体验输入审查）
+
+- UI/UX slices:
+- DESIGN.md:
+- Screen contracts consumed:
+- Handoff matrix consumed:
+- Not applicable reason:
+
+## 4. 方案架构
 
 - 领域边界（Domain boundary）:
 - 主要组件（Main components）:
@@ -25,27 +33,27 @@ Input
 -> Output
 ```
 
-## 4. 接口契约（Interface Contract）
+## 5. 接口契约（Interface Contract）
 
 | 接口（Interface） | 方法/事件（Method/Event） | 请求（Request） | 响应（Response） | 错误（Errors） |
 |---|---|---|---|---|
 |  |  |  |  |  |
 
-## 5. 数据模型（Data Model）
+## 6. 数据模型（Data Model）
 
 | 实体（Entity） | 字段（Fields） | 负责人（Owner） | 备注（Notes） |
 |---|---|---|---|
 |  |  |  |  |
 
-## 6. 任务拆分（Task Breakdown）
+## 7. 任务拆分（Task Breakdown）
 
-| Task ID | 标题（Title） | Allowed Paths | Required Gates | Implementation Doc |
-|---|---|---|---|---|
-| TASK-001 |  | `src/**`, `tests/**` | `make lint`, `make test-current-domain` | `.docs/04_implementation/...` |
+| Task ID | 标题（Title） | UI/UX refs | Design system | Allowed Paths | Required Gates | Implementation Doc |
+|---|---|---|---|---|---|---|
+| TASK-001 |  | `.docs/02_experience/...` | `DESIGN.md` | `src/**`, `tests/**` | `make lint`, `make test-current-domain` | `.docs/04_implementation/...` |
 
 `Implementation Doc` 应指向模块、子系统或核心数据流级文档；多个 task 可以更新同一份文档，task id 和 commit 记录在该文档的 provenance / Change Log 中。
 
-## 7. Development Self-Test Contract（开发自测合同，待执行）
+## 8. Development Self-Test Contract（开发自测合同，待执行）
 
 > service / agent / runtime / worker / frontend app / provider-live / API / CLI 等可运行边界的开发 task 必填，并同步写入 `plan.draft.yaml.tasks[].self_test_contract`。
 
@@ -62,12 +70,12 @@ Input
 
 - Not applicable reason:
 
-## 8. 风险与缓解
+## 9. 风险与缓解
 
 | 风险（Risk） | 等级（Level） | 缓解措施（Mitigation） |
 |---|---|---|
 |  | P1 |  |
 
-## 9. 需要关注的方案偏移
+## 10. 需要关注的方案偏移
 
 - 

package/assets/templates/TEST_CASES_TEMPLATE.md

@@ -9,17 +9,19 @@
 
 ## 2. Cases（用例）
 
-| ID | Requirement | Preconditions | Steps | Expected Result |
-|---|---|---|---|---|
-| TC-001 |  |  |  |  |
+| Case ID | Requirement / Risk Ref | Type | Priority | Runnable Entry | Preconditions | Steps | Expected Exit | Evidence Pointer |
+|---|---|---|---|---|---|---|---|---|
+| TC-001 |  | unit/integration/e2e/regression/smoke/manual | P0/P1/P2 |  |  |  |  |  |
 
 ## 3. Traceability（追溯）
 
 - PRD acceptance criteria:
 - Review findings:
 - Risk paths:
+- TEST_REPORT references:
 
 ## 4. Notes（备注）
 
 - Fixture/live boundary:
 - Data setup:
+- Case body only records test design. Execution result, regression evidence, bugfix route and final decision belong in `TEST_REPORT.md`.

package/assets/templates/TEST_STRATEGY_TEMPLATE.md

@@ -5,6 +5,8 @@
 - In scope:
 - Out of scope:
 - Target release/module:
+- UI/UX handoff refs:
+- DESIGN.md:
 
 ## 2. Environment（环境）
 
@@ -12,6 +14,7 @@
 - Expected exits / side effects:
 - Config contract:
 - Fixture/live boundary:
+- Screen states / responsive / a11y environment:
 
 ## 3. Priority（优先级）
 
@@ -25,3 +28,4 @@
 - Manual checks:
 - Regression gates:
 - Blocker handling:
+- UI/UX contract coverage:

package/assets/templates/UI_UX_DESIGN_TEMPLATE.md

@@ -0,0 +1,67 @@
+# [Feature/Capability] UI/UX Design
+
+## 1. PRD refs and Requirement IDs
+
+- PRD:
+- Requirement IDs:
+
+## 2. Applicability
+
+- Applicability: `visual_ui | cli_or_api_experience | not_applicable`
+- N/A reason:
+
+## 3. User journeys
+
+| Journey ID | User / Role | Goal | Entry | Success exit | Failure / recovery |
+|---|---|---|---|---|---|
+| UXJ-001 |  |  |  |  |  |
+
+## 4. Information architecture / routes / screens
+
+| Surface | Route / Entry | Screen ID | Purpose | Primary user action |
+|---|---|---|---|---|
+| web / mobile / CLI / API / operator |  | SCR-001 |  |  |
+
+## 5. Screen contracts
+
+| Screen ID | Requirement refs | Entry / route | Loading | Empty | Error | Success | Permission | Primary actions | Validation rules |
+|---|---|---|---|---|---|---|---|---|---|
+| SCR-001 |  |  |  |  |  |  |  |  |  |
+
+### Responsive and accessibility acceptance
+
+- Breakpoints / form factors:
+- Keyboard / focus behavior:
+- Touch target behavior:
+- Contrast / readable states:
+- Assistive text / labels:
+
+## 6. Component and interaction contracts
+
+| Component / Pattern | States | Interaction behavior | Feedback | Notes |
+|---|---|---|---|---|
+| navigation / form / table / list / modal / toast | default / hover / focus / disabled / error / success |  |  |  |
+
+## 7. Design system reference
+
+- DESIGN.md: `DESIGN.md | not_applicable`
+- Token / component notes:
+- Known deviations:
+
+## 8. Handoff matrix
+
+| Requirement | Screen / state | Component / interaction | Acceptance / test seed |
+|---|---|---|---|
+|  |  |  |  |
+
+## 9. Open Questions / Out of Scope
+
+### Open Questions
+
+| Question | Owner | Status |
+|---|---|---|
+|  |  | open |
+
+### Out of Scope
+
+- 

package/assets/tools/harness_utils.py

@@ -28,6 +28,7 @@ PARALLEL_TRIGGERS = {"user_requested", "workflow_default"}
 PARALLEL_RUNTIME_PROVIDERS = {"codex_native_subagents", "user_orchestrated", "codex_exec_worktree"}
 PARALLEL_ALLOWED_PHASES = {
     "REQUIREMENT_GATHERING",
+    "UI_UX_DESIGNING",
     "ARCHITECTING",
     "SPRINTING",
     "REVIEWING",
@@ -35,7 +36,7 @@ PARALLEL_ALLOWED_PHASES = {
     "RELEASING",
     "RFC_RECALIBRATION",
 }
-PARALLEL_READ_ONLY_PHASES = {"REQUIREMENT_GATHERING", "ARCHITECTING", "REVIEWING", "RELEASING", "RFC_RECALIBRATION"}
+PARALLEL_READ_ONLY_PHASES = {"REQUIREMENT_GATHERING", "UI_UX_DESIGNING", "ARCHITECTING", "REVIEWING", "RELEASING", "RFC_RECALIBRATION"}
 PARALLEL_PROTECTED_WRITE_PATTERNS = {
     ".codex/state/**",
     "<harnessRoot>/state/**",
@@ -48,6 +49,7 @@ PARALLEL_PROTECTED_WRITE_PATTERNS = {
 TASK_ID_PATTERN = re.compile(r"^[A-Z]+-(\d+)$")
 TASK_PHASES = {
     "REQUIREMENT_GATHERING",
+    "UI_UX_DESIGNING",
     "ARCHITECTING",
     "SPRINTING",
     "REVIEWING",
@@ -1172,7 +1174,7 @@ def validate_parallel_execution_contract(data: dict[str, Any], current_phase: st
     require("linked_task_id" not in contract, "parallel_execution must not define linked_task_id; use plan.yaml current_task_id")
     require(
         current_phase in PARALLEL_ALLOWED_PHASES,
-        "parallel_execution is only supported during REQUIREMENT_GATHERING, ARCHITECTING, SPRINTING, REVIEWING, TESTING, RELEASING, or RFC_RECALIBRATION",
+        "parallel_execution is only supported during REQUIREMENT_GATHERING, UI_UX_DESIGNING, ARCHITECTING, SPRINTING, REVIEWING, TESTING, RELEASING, or RFC_RECALIBRATION",
     )
     require(contract.get("coordinator") == "main_agent", 'parallel_execution.coordinator must be "main_agent"')
 

package/assets/tools/validate_design.py

@@ -33,6 +33,24 @@ CROSS_CUTTING_CATEGORIES = [
         "architecture_terms": ["compliance", "permission", "authorization", "audit", "合规", "权限", "审计", "授权", "客户确认", "回执归档"],
     },
 ]
+UI_DRAFT_TASK_TERMS = [
+    "frontend",
+    "front-end",
+    "browser",
+    "page",
+    "screen",
+    "route",
+    "component",
+    "visual_ui",
+    "design.md",
+    ".docs/02_experience/",
+    "页面",
+    "前端",
+    "屏幕",
+    "交互",
+    "组件",
+    "视觉",
+]
 
 
 def main() -> None:
@@ -43,6 +61,7 @@ def main() -> None:
     architecture_docs = markdown_deliverables(".docs/02_architecture")
     tech_plan_docs = markdown_deliverables(".docs/03_tech_plan")
     product_docs = markdown_deliverables(".docs/01_product")
+    experience_docs = markdown_deliverables(".docs/02_experience")
     require(architecture_docs, "No architecture deliverables found in .docs/02_architecture/")
     require(tech_plan_docs, "No technical plan deliverables found in .docs/03_tech_plan/")
 
@@ -50,12 +69,12 @@ def main() -> None:
     require(contains_any(text, ["prd", "requirement", "需求"]), "Design must cite product requirements")
     require(contains_any(text, ["api", "interface", "接口", "contract", "契约"]), "Design must describe interfaces or contracts")
     require(contains_any(text, ["task", "任务", "breakdown"]), "Design must include task breakdown")
-    draft_tasks = validate_draft_task_tech_plan_refs(tech_plan_docs)
+    draft_tasks = validate_draft_task_tech_plan_refs(tech_plan_docs, experience_docs)
     validate_cross_cutting_architecture(product_docs, tech_plan_docs, architecture_docs, draft_tasks)
     print(f"Design artifacts OK: {len(architecture_docs)} architecture, {len(tech_plan_docs)} tech plan")
 
 
-def validate_draft_task_tech_plan_refs(tech_plan_docs: list) -> list[dict]:
+def validate_draft_task_tech_plan_refs(tech_plan_docs: list, experience_docs: list) -> list[dict]:
     draft = load_plan(".codex/state/plan.draft.yaml")
     require("current_phase" not in draft, "plan.draft.yaml must not define current_phase; lifecycle.yaml is the single source for current_phase")
     require("current_task_id" not in draft, "plan.draft.yaml must not define current_task_id because drafts are not active task state")
@@ -63,6 +82,7 @@ def validate_draft_task_tech_plan_refs(tech_plan_docs: list) -> list[dict]:
     require(tasks, "plan.draft.yaml must contain at least one task before leaving ARCHITECTING")
 
     available_tech_plans = {repo_relative(path) for path in tech_plan_docs}
+    available_experience_docs = {repo_relative(path) for path in experience_docs}
     development_tasks: list[dict] = []
     primary_refs: list[str] = []
     for index, task in enumerate(tasks):
@@ -80,6 +100,7 @@ def validate_draft_task_tech_plan_refs(tech_plan_docs: list) -> list[dict]:
         for ref in normalized_refs:
             require(ref.startswith(".docs/03_tech_plan/"), f"Draft task {task.get('id')} docs.tech_plan must point into .docs/03_tech_plan/: {ref}")
             require(ref in available_tech_plans, f"Draft task {task.get('id')} references missing or generated tech plan slice: {ref}")
+        validate_uiux_design_refs_for_draft_task(task, available_experience_docs)
         validate_self_test_contract_tech_plan_binding(task, normalized_refs)
         primary_refs.append(normalized_refs[0])
 
@@ -92,6 +113,38 @@ def validate_draft_task_tech_plan_refs(tech_plan_docs: list) -> list[dict]:
     return tasks
 
 
+def validate_uiux_design_refs_for_draft_task(task: dict, available_experience_docs: set[str]) -> None:
+    docs = task.get("docs")
+    if not isinstance(docs, dict):
+        return
+    task_id = task.get("id")
+    uiux_refs = [normalize_doc_ref(ref) for ref in as_list(docs.get("uiux"))]
+    design_refs = [normalize_doc_ref(ref) for ref in as_list(docs.get("design_system"))]
+    ui_task = is_ui_draft_task(task)
+
+    if ui_task:
+        require(uiux_refs, f"UI/frontend draft task {task_id} must reference a UI/UX slice in docs.uiux")
+        require(design_refs, f"UI/frontend draft task {task_id} must reference DESIGN.md in docs.design_system")
+
+    for ref in uiux_refs:
+        require(ref.startswith(".docs/02_experience/"), f"Draft task {task_id} docs.uiux must point into .docs/02_experience/: {ref}")
+        require(ref in available_experience_docs, f"Draft task {task_id} references missing or generated UI/UX slice: {ref}")
+
+    for ref in design_refs:
+        require(ref == "DESIGN.md", f"Draft task {task_id} docs.design_system must point to DESIGN.md: {ref}")
+        require(repo_path("DESIGN.md").exists(), f"Draft task {task_id} references missing design system: DESIGN.md")
+
+
+def is_ui_draft_task(task: dict) -> bool:
+    docs = task.get("docs")
+    docs_text = ""
+    if isinstance(docs, dict):
+        docs_text = "\n".join(ref for value in docs.values() for ref in as_list(value))
+    runtime_text = "\n".join(str(task.get(key) or "") for key in ["target_runtime_environment", "self_test_contract"])
+    text = "\n".join(str(task.get(key) or "") for key in ["id", "title", "summary", "phase"]) + "\n" + docs_text + "\n" + runtime_text
+    return contains_any(text, UI_DRAFT_TASK_TERMS)
+
+
 def validate_cross_cutting_architecture(product_docs: list, tech_plan_docs: list, architecture_docs: list, draft_tasks: list[dict]) -> None:
     source_text = "\n".join(
         [

package/assets/tools/validate_harness.py

@@ -32,6 +32,7 @@ def main() -> None:
     required_dirs = [
         ".docs/00_raw",
         ".docs/01_product",
+        ".docs/02_experience",
         ".docs/02_architecture",
         ".docs/03_tech_plan",
         ".docs/04_implementation",

package/assets/tools/validate_rfc.py

@@ -48,6 +48,23 @@ SELF_TEST_TRIGGER_TERMS = [
     "阻塞",
 ]
 SELF_TEST_IMPACT_TERMS = ["development self-test impact", "开发自测影响"]
+UI_UX_TRIGGER_TERMS = [
+    "ui/ux",
+    "ux",
+    "screen",
+    "interaction",
+    "design.md",
+    "frontend",
+    "browser",
+    "page",
+    "visual",
+    "体验",
+    "屏幕",
+    "交互",
+    "视觉",
+    "前端",
+]
+UI_UX_IMPACT_TERMS = ["ui/ux impact", "体验影响"]
 
 
 def superseded_test_docs(docs) -> list[str]:
@@ -85,6 +102,7 @@ def main() -> None:
     invalid = [status for status in statuses if status not in allowed]
     require(not invalid, "Invalid RFC status: " + ", ".join(invalid))
     validate_development_self_test_impact(docs)
+    validate_uiux_impact(docs)
     print(f"RFC artifacts OK: {len(docs)} file(s)")
 
 
@@ -101,6 +119,19 @@ def validate_development_self_test_impact(docs) -> None:
             )
 
 
+def validate_uiux_impact(docs) -> None:
+    for doc in docs:
+        number = rfc_number(doc.name)
+        if number is not None and number < 27:
+            continue
+        text = doc.read_text(encoding="utf-8")
+        if contains_any(text, UI_UX_TRIGGER_TERMS):
+            require(
+                contains_any(text, UI_UX_IMPACT_TERMS),
+                f"{doc.relative_to(repo_path('.')).as_posix()} must include UI/UX Impact when RFC changes experience docs, screen contracts, DESIGN.md, frontend, or browser behavior",
+            )
+
+
 def rfc_number(file_name: str) -> int | None:
     match = re.match(r"^RFC[_-](\d+)", file_name, re.IGNORECASE)
     return int(match.group(1)) if match else None

package/assets/tools/validate_test_plan.py

@@ -1,4 +1,7 @@
 #!/usr/bin/env python3
+import re
+from typing import Optional
+
 from harness_utils import (
     changed_files,
     contains_any,
@@ -13,7 +16,9 @@ from harness_utils import (
 )
 
 TEST_REPORT_PATH = ".docs/07_test/TEST_REPORT.md"
+TEST_CASES_PATH = ".docs/07_test/TEST_CASES.md"
 PLACEHOLDER_TERMS = ["pending", "tbd", "todo", "待填", "待补", "placeholder"]
+CASE_ID_RE = re.compile(r"\bTC-\d{3,}\b")
 MISSING_READINESS_TERMS = [
     "missing entry",
     "missing exit",
@@ -44,6 +49,10 @@ MISSING_READINESS_TERMS = [
 ]
 
 
+def as_list(value) -> list:
+    return value if isinstance(value, list) else []
+
+
 def read_test_report() -> tuple[str, str]:
     require(
         repo_path(TEST_REPORT_PATH).exists(),
@@ -52,8 +61,115 @@ def read_test_report() -> tuple[str, str]:
     return read_text(TEST_REPORT_PATH), TEST_REPORT_PATH
 
 
+def test_case_refs(text: str) -> list[str]:
+    return sorted(set(CASE_ID_RE.findall(text)))
+
+
+def plan_references_test_cases(plan: dict) -> bool:
+    for task in as_list(plan.get("tasks")):
+        if not isinstance(task, dict):
+            continue
+        if str(task.get("phase") or "") != "TESTING":
+            continue
+        refs = [str(item) for item in as_list(task.get("result_docs"))]
+        if TEST_CASES_PATH in refs:
+            return True
+    return False
+
+
+def split_markdown_row(line: str) -> list[str]:
+    return [cell.strip() for cell in line.strip().strip("|").split("|")]
+
+
+def is_separator_row(line: str) -> bool:
+    stripped = line.strip()
+    return stripped.startswith("|") and set(stripped.replace("|", "").strip()) <= {"-", ":", " "}
+
+
+def find_table_header(lines: list[str], row_index: int) -> Optional[list[str]]:
+    for index in range(row_index - 1, 0, -1):
+        if not is_separator_row(lines[index]):
+            continue
+        header = lines[index - 1]
+        if header.strip().startswith("|"):
+            return split_markdown_row(header)
+    return None
+
+
+def header_index(headers: list[str], *terms: str) -> Optional[int]:
+    lowered = [header.lower() for header in headers]
+    for index, header in enumerate(lowered):
+        if any(term in header for term in terms):
+            return index
+    return None
+
+
+def required_cell(cells: list[str], index: Optional[int]) -> str:
+    if index is None or index >= len(cells):
+        return ""
+    return cells[index].strip()
+
+
+def validate_test_cases(text: str, report_text: str) -> list[str]:
+    errors: list[str] = []
+    if contains_any(text, PLACEHOLDER_TERMS):
+        errors.append("TEST_CASES.md must not contain pending/TBD/TODO/placeholder content")
+
+    lines = text.splitlines()
+    rows: list[tuple[int, list[str], list[str]]] = []
+    for index, line in enumerate(lines):
+        if not line.strip().startswith("|") or not CASE_ID_RE.search(line):
+            continue
+        header = find_table_header(lines, index)
+        if header is None:
+            errors.append("TEST_CASES.md cases must be listed in a Markdown table with headers")
+            continue
+        rows.append((index + 1, header, split_markdown_row(line)))
+
+    ids = [CASE_ID_RE.search("|".join(cells)).group(0) for _, _, cells in rows if CASE_ID_RE.search("|".join(cells))]
+    if not ids:
+        errors.append("TEST_CASES.md must include at least one TC-* case")
+    duplicates = sorted({case_id for case_id in ids if ids.count(case_id) > 1})
+    if duplicates:
+        errors.append(f"TEST_CASES.md Case ID must be unique: {', '.join(duplicates)}")
+
+    for line_number, headers, cells in rows:
+        requirement = header_index(headers, "requirement", "risk", "需求", "风险")
+        runnable_entry = header_index(headers, "runnable entry", "runnable", "entry", "入口")
+        steps = header_index(headers, "steps", "步骤")
+        expected_exit = header_index(headers, "expected exit", "expected result", "expected", "预期", "出口")
+        missing = []
+        if not required_cell(cells, requirement):
+            missing.append("Requirement / Risk Ref")
+        if not required_cell(cells, runnable_entry):
+            missing.append("Runnable Entry")
+        if not required_cell(cells, steps):
+            missing.append("Steps")
+        if not required_cell(cells, expected_exit):
+            missing.append("Expected Exit")
+        if missing:
+            errors.append(f"TEST_CASES.md row {line_number} missing required case fields: {', '.join(missing)}")
+
+    refs = test_case_refs(report_text)
+    missing_refs = sorted(set(refs) - set(ids))
+    if missing_refs:
+        errors.append(f"TEST_REPORT.md references case IDs not found in TEST_CASES.md: {', '.join(missing_refs)}")
+    return errors
+
+
+def validate_test_cases_if_needed(plan: dict, report_text: str) -> None:
+    cases_path = repo_path(TEST_CASES_PATH)
+    should_validate = bool(test_case_refs(report_text)) or plan_references_test_cases(plan) or cases_path.exists()
+    if not should_validate:
+        return
+    require(cases_path.exists(), f"Missing test cases: expected {TEST_CASES_PATH} because TEST_REPORT.md or current TESTING task references test cases")
+    for error in validate_test_cases(read_text(TEST_CASES_PATH), report_text):
+        require(False, error)
+
+
 def main() -> None:
-    validate_plan_contract(load_plan(), allow_open=False)
+    plan = load_plan()
+    validate_plan_contract(plan, allow_open=False)
     text, source = read_test_report()
     require(
         not contains_any(text, PLACEHOLDER_TERMS),
@@ -72,6 +188,7 @@ def main() -> None:
             not contains_any(text, MISSING_READINESS_TERMS),
             "Test report cannot PASS while runnable entry/exit or Development Evidence is missing; use BLOCKED with recovery conditions",
         )
+    validate_test_cases_if_needed(plan, text)
     if load_lifecycle().get("current_phase") == "TESTING":
         for error in testing_boundary_errors_for_changed_files(changed_files()):
             require(False, error)

package/assets/tools/validate_uiux_design.py

@@ -0,0 +1,101 @@
+#!/usr/bin/env python3
+import json
+import subprocess
+
+from harness_utils import (
+    contains_any,
+    load_lifecycle,
+    load_plan,
+    markdown_deliverables,
+    repo_path,
+    run_main,
+    require,
+    validate_plan_contract,
+)
+
+
+DESIGN_MD = "DESIGN.md"
+
+
+def main() -> None:
+    lifecycle = load_lifecycle()
+    plan = load_plan()
+    validate_plan_contract(plan, allow_open=lifecycle.get("current_phase") != "UI_UX_DESIGNING")
+
+    docs = markdown_deliverables(".docs/02_experience")
+    require(docs, "No UI/UX deliverables found in .docs/02_experience/")
+    visual_ui = False
+    for doc in docs:
+        text = doc.read_text(encoding="utf-8")
+        relative = doc.relative_to(repo_path(".")).as_posix()
+        not_applicable = contains_any(text, ["applicability: not_applicable", "applicability: `not_applicable`"])
+        visual_ui = visual_ui or contains_any(text, ["applicability: visual_ui", "applicability: `visual_ui`"])
+        if not_applicable:
+            continue
+        require(contains_any(text, ["prd", "requirement", "需求"]), f"{relative} must cite PRD and requirement IDs")
+        require(contains_any(text, ["user journey", "user journeys", "用户旅程"]), f"{relative} must include user journeys")
+        require(contains_any(text, ["handoff matrix", "交接矩阵"]), f"{relative} must include a handoff matrix")
+        require(
+            contains_any(text, ["loading", "empty", "error", "success", "permission", "加载", "空状态", "错误", "成功", "权限"]),
+            f"{relative} screen contracts must cover applicable loading/empty/error/success/permission states",
+        )
+        require(contains_any(text, ["responsive", "breakpoint", "响应式", "断点"]), f"{relative} must include responsive acceptance")
+        require(
+            contains_any(text, ["accessibility", "a11y", "focus", "keyboard", "touch", "无障碍", "焦点", "键盘", "触控"]),
+            f"{relative} must include accessibility/focus/keyboard/touch expectations",
+        )
+
+    if visual_ui:
+        design_path = repo_path(DESIGN_MD)
+        require(design_path.exists(), "visual UI experience requires root DESIGN.md")
+        validate_design_md()
+
+    print(f"UI/UX artifacts OK: {len(docs)} experience deliverable(s)")
+
+
+def validate_design_md() -> None:
+    command = designmd_command()
+    try:
+        proc = subprocess.run(
+            command + ["lint", DESIGN_MD],
+            cwd=repo_path("."),
+            text=True,
+            capture_output=True,
+            check=False,
+        )
+    except FileNotFoundError:
+        require(False, "DESIGN.md linter not found; install @google/design.md or run npm install")
+        return
+
+    output = (proc.stdout or "").strip()
+    diagnostics = None
+    if output:
+        try:
+            diagnostics = json.loads(output)
+        except json.JSONDecodeError:
+            diagnostics = None
+
+    errors = []
+    if isinstance(diagnostics, dict):
+        summary = diagnostics.get("summary") if isinstance(diagnostics.get("summary"), dict) else {}
+        if int(summary.get("errors") or 0) > 0:
+            errors.append("DESIGN.md linter reported errors")
+        for finding in diagnostics.get("findings") or []:
+            if isinstance(finding, dict) and str(finding.get("severity") or "").lower() == "error":
+                errors.append(str(finding.get("message") or "DESIGN.md linter error"))
+    elif proc.returncode != 0:
+        errors.append((proc.stderr or proc.stdout or "DESIGN.md linter failed").strip())
+
+    if errors:
+        require(False, "; ".join(errors))
+
+
+def designmd_command() -> list[str]:
+    local_bin = repo_path("node_modules/.bin/designmd")
+    if local_bin.exists():
+        return [str(local_bin)]
+    return ["npx", "--no-install", "designmd"]
+
+
+if __name__ == "__main__":
+    run_main(main)

package/dist/commands/index.js

@@ -15,6 +15,7 @@ export const commands = {
     "validate-current": (args) => validate(["validate-current", ...args]),
     "validate-plan": (args) => validate(["validate-plan", ...args]),
     "validate-pm": (args) => validate(["validate-pm", ...args]),
+    "validate-uiux": (args) => validate(["validate-uiux", ...args]),
     "validate-design": (args) => validate(["validate-design", ...args]),
     "validate-dev": (args) => validate(["validate-dev", ...args]),
     "validate-review": (args) => validate(["validate-review", ...args]),
@@ -31,6 +32,6 @@ export function help() {
   upgrade              Run migrations and then sync
   doctor               Diagnose project configuration and drift
   validate <gate>      Run a Harness validation gate
-  validate-*           Run a named gate directly, including validate-plan/review/test/release/rfc
+  validate-*           Run a named gate directly, including validate-plan/uiux/design/dev/review/test/release/rfc
   package <subcommand> Maintain package canonical source`);
 }

package/dist/lib/init.js

@@ -7,6 +7,7 @@ import { syncDocsIndexMaintenanceSection, syncMemoryGuidanceSection } from "./us
 const DOC_DIRS = [
     ".docs/00_raw",
     ".docs/01_product",
+    ".docs/02_experience",
     ".docs/02_architecture",
     ".docs/03_tech_plan",
     ".docs/04_implementation",