agent-project-sdlc 0.1.24 → 0.1.26

package/assets/templates/REVIEW_TEMPLATE.md

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

package/assets/templates/RFC_TEMPLATE.md

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

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
+
+- TBD

package/assets/tools/harness_utils.py

@@ -12,6 +12,8 @@ from typing import Any
 
 
 ROOT = Path(__file__).resolve().parents[1]
+DEFAULT_HARNESS_ROOT = ".agent"
+HARNESS_JSON_CONFIG_PATH = "sdlc-harness.config.json"
 
 TASK_STATUSES = {
     "pending",
@@ -28,6 +30,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 +38,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 +51,7 @@ PARALLEL_PROTECTED_WRITE_PATTERNS = {
 TASK_ID_PATTERN = re.compile(r"^[A-Z]+-(\d+)$")
 TASK_PHASES = {
     "REQUIREMENT_GATHERING",
+    "UI_UX_DESIGNING",
     "ARCHITECTING",
     "SPRINTING",
     "REVIEWING",
@@ -68,7 +72,67 @@ def repo_path(relative: str | Path) -> Path:
     return ROOT / relative
 
 
+def normalize_harness_folder_name(value: str) -> str:
+    normalized = value.strip().replace("\\", "/").rstrip("/")
+    if not normalized or normalized in {".", ".."}:
+        raise HarnessError("harnessFolderName must be a non-empty relative directory")
+    if Path(normalized).is_absolute() or ".." in normalized.split("/"):
+        raise HarnessError("harnessFolderName must not be absolute or contain '..'")
+    return normalized
+
+
+def folder_name_from_object(value: Any) -> str | None:
+    if not isinstance(value, dict):
+        return None
+    folder_name = value.get("harnessFolderName") or value.get("harnessFloderName")
+    if isinstance(folder_name, str) and folder_name.strip():
+        return folder_name
+    return None
+
+
+def read_json_config(relative: str) -> Any:
+    path = repo_path(relative)
+    if not path.exists():
+        return None
+    return json.loads(path.read_text(encoding="utf-8"))
+
+
+def harness_root() -> str:
+    package_json = read_json_config("package.json")
+    package_config = package_json.get("sdlcHarness") if isinstance(package_json, dict) else None
+    package_value = folder_name_from_object(package_config)
+    if package_value:
+        return normalize_harness_folder_name(package_value)
+
+    explicit_config = read_json_config(HARNESS_JSON_CONFIG_PATH)
+    explicit_value = folder_name_from_object(explicit_config)
+    if explicit_value:
+        return normalize_harness_folder_name(explicit_value)
+
+    return DEFAULT_HARNESS_ROOT
+
+
+def harness_path(*segments: str) -> str:
+    return (Path(harness_root()).joinpath(*segments)).as_posix()
+
+
+def resolve_harness_relative(relative: str | Path) -> str:
+    value = str(relative).replace("\\", "/")
+    root = harness_root()
+    if value == "<harnessRoot>":
+        return root
+    if value.startswith("<harnessRoot>/"):
+        return f"{root}/{value.removeprefix('<harnessRoot>/')}"
+    if root != ".codex":
+        if value == ".codex":
+            return root
+        if value.startswith(".codex/"):
+            return f"{root}/{value.removeprefix('.codex/')}"
+    return value
+
+
 def read_text(relative: str | Path) -> str:
+    relative = resolve_harness_relative(relative)
     path = repo_path(relative)
     if not path.exists():
         raise HarnessError(f"Missing required file: {relative}")
@@ -76,6 +140,7 @@ def read_text(relative: str | Path) -> str:
 
 
 def load_yaml(relative: str | Path) -> Any:
+    relative = resolve_harness_relative(relative)
     path = repo_path(relative)
     if not path.exists():
         raise HarnessError(f"Missing required YAML file: {relative}")
@@ -112,6 +177,7 @@ def parse_yaml_text(text: str) -> Any:
 
 
 def dump_yaml(data: Any, relative: str | Path) -> None:
+    relative = resolve_harness_relative(relative)
     path = repo_path(relative)
     path.write_text(to_simple_yaml(data).rstrip() + "\n", encoding="utf-8")
 
@@ -328,7 +394,8 @@ def require(condition: Any, message: str) -> None:
 
 def require_paths(paths: list[str]) -> None:
     for relative in paths:
-        require(repo_path(relative).exists(), f"Missing required path: {relative}")
+        resolved = resolve_harness_relative(relative)
+        require(repo_path(resolved).exists(), f"Missing required path: {resolved}")
 
 
 def combined_text(paths: list[Path]) -> str:
@@ -842,13 +909,13 @@ def is_testing_runtime_boundary_change(path: str) -> bool:
 
 
 def load_lifecycle() -> dict[str, Any]:
-    data = load_yaml(".codex/state/lifecycle.yaml")
+    data = load_yaml(harness_path("state", "lifecycle.yaml"))
     require(isinstance(data, dict), "lifecycle.yaml must be a mapping")
     return data
 
 
 def load_phase_contract_data() -> dict[str, Any]:
-    data = load_yaml(".codex/pjsdlc_managed/policies/phase_contracts.yaml")
+    data = load_yaml(harness_path("pjsdlc_managed", "policies", "phase_contracts.yaml"))
     require(isinstance(data, dict) and isinstance(data.get("phases"), dict), "phase_contracts.yaml must contain phases")
     return data
 
@@ -1019,11 +1086,12 @@ def phase_transition_contract_errors(contract_data: dict[str, Any], require_tran
     return errors
 
 
-def load_plan(path: str = ".codex/state/plan.yaml") -> dict[str, Any]:
-    data = load_yaml(path)
-    require(isinstance(data, dict), f"{path} must be a mapping")
+def load_plan(path: str | None = None) -> dict[str, Any]:
+    plan_path = path or harness_path("state", "plan.yaml")
+    data = load_yaml(plan_path)
+    require(isinstance(data, dict), f"{resolve_harness_relative(plan_path)} must be a mapping")
     tasks = data.get("tasks", [])
-    require(isinstance(tasks, list), f"{path} must contain a tasks list")
+    require(isinstance(tasks, list), f"{resolve_harness_relative(plan_path)} must contain a tasks list")
     return data
 
 
@@ -1172,7 +1240,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"')
 
@@ -1245,28 +1313,34 @@ def validate_parallel_worker_path_lock(data: dict[str, Any], worker: dict[str, A
             require(not glob_patterns_overlap(owned, forbidden), f"{prefix}.owned_paths must not overlap forbidden paths: {owned} vs {forbidden}")
 
 
-def glob_prefix(pattern: str) -> str:
-    normalized = pattern.replace("\\", "/").replace("<harnessRoot>", ".codex")
+def normalize_harness_pattern(pattern: str, root: str | None = None) -> str:
+    actual_root = root or harness_root()
+    return pattern.replace("\\", "/").replace("<harnessRoot>", actual_root)
+
+
+def glob_prefix(pattern: str, root: str | None = None) -> str:
+    normalized = normalize_harness_pattern(pattern, root)
     wildcard_positions = [pos for pos in (normalized.find("*"), normalized.find("["), normalized.find("?")) if pos >= 0]
     if wildcard_positions:
         normalized = normalized[: min(wildcard_positions)]
     return normalized.rstrip("/")
 
 
-def glob_patterns_overlap(left: str, right: str) -> bool:
-    left_clean = left.replace("\\", "/").replace("<harnessRoot>", ".codex")
-    right_clean = right.replace("\\", "/").replace("<harnessRoot>", ".codex")
+def glob_patterns_overlap(left: str, right: str, root: str | None = None) -> bool:
+    left_clean = normalize_harness_pattern(left, root)
+    right_clean = normalize_harness_pattern(right, root)
     if fnmatch.fnmatch(left_clean, right_clean) or fnmatch.fnmatch(right_clean, left_clean):
         return True
-    left_prefix = glob_prefix(left_clean)
-    right_prefix = glob_prefix(right_clean)
+    left_prefix = glob_prefix(left_clean, root)
+    right_prefix = glob_prefix(right_clean, root)
     if not left_prefix or not right_prefix:
         return left_prefix == right_prefix
     return left_prefix.startswith(right_prefix + "/") or right_prefix.startswith(left_prefix + "/") or left_prefix == right_prefix
 
 
-def expand_harness_root(patterns: list[str], root: str = ".codex") -> list[str]:
-    return [str(pattern).replace("<harnessRoot>", root) for pattern in patterns]
+def expand_harness_root(patterns: list[str], root: str | None = None) -> list[str]:
+    actual_root = root or harness_root()
+    return [str(pattern).replace("<harnessRoot>", actual_root) for pattern in patterns]
 
 
 def task_by_id(plan_data: dict[str, Any], task_id: str) -> dict[str, Any] | None:

package/assets/tools/transition.py

@@ -2,6 +2,7 @@
 from harness_utils import (
     dump_yaml,
     find_phase_transition,
+    harness_path,
     load_lifecycle,
     load_phase_contract_data,
     make_arg_parser,
@@ -51,7 +52,7 @@ def main() -> None:
         str(lifecycle.get("suspended_phase") or ""),
     )
 
-    dump_yaml(lifecycle, ".codex/state/lifecycle.yaml")
+    dump_yaml(lifecycle, harness_path("state", "lifecycle.yaml"))
     print(f"Transitioned {current} -> {target}")
     if args.reason:
         print(f"Note: {args.reason}")

package/assets/tools/validate_allowed_paths.py

@@ -18,7 +18,7 @@ def main() -> None:
     tasks = [task for task in data.get("tasks", []) if isinstance(task, dict)]
     open_tasks = [task for task in tasks if task.get("status") in OPEN_TASK_STATUSES]
 
-    policies = load_yaml(".codex/pjsdlc_managed/policies/allowed_paths.yaml")
+    policies = load_yaml("<harnessRoot>/pjsdlc_managed/policies/allowed_paths.yaml")
     lifecycle = load_lifecycle()
     current_phase = lifecycle.get("current_phase") or "SPRINTING"
     phase_policy = ((policies.get("phases") or {}).get(current_phase) or {})
@@ -29,7 +29,7 @@ def main() -> None:
         task = task_by_id(data, current_task_id) if current_task_id else None
         require(task, "current_task_id must point to the task being validated")
         require(task.get("status") in OPEN_TASK_STATUSES, "current_task_id must point to an open task for path validation")
-        allowed = list(task.get("allowed_paths") or []) + list(always_allow)
+        allowed = expand_harness_root(list(task.get("allowed_paths") or [])) + list(always_allow)
     else:
         print("Allowed paths skipped: no open task")
         return

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,19 +69,20 @@ 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]:
-    draft = load_plan(".codex/state/plan.draft.yaml")
+def validate_draft_task_tech_plan_refs(tech_plan_docs: list, experience_docs: list) -> list[dict]:
+    draft = load_plan("<harnessRoot>/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")
     tasks = draft.get("tasks", [])
     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_dev_state.py

@@ -3,7 +3,7 @@ from harness_utils import load_plan, require, run_main
 
 
 def main() -> None:
-    draft = load_plan(".codex/state/plan.draft.yaml")
+    draft = load_plan("<harnessRoot>/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")
     tasks = [task for task in draft.get("tasks", []) if isinstance(task, dict)]