xwang 0.0.1

package/assets/skills/xwang/SKILL.md

@@ -0,0 +1,112 @@
+---
+name: xwang
+description: xwang 项目主入口 skill，自动检测当前所处阶段并分发到 open、design、build、verify、archive 子流程；也支持快速路径 xwang-hotfix 与 xwang-tweak。当用户输入 /xwang 或提到启动 xwang 工作流时使用。
+---
+
+# xwang
+
+xwang 工作流包含 5 个阶段：open → design → build → verify → archive。另有快速路径：
+- `xwang-hotfix`：bug 修复，open → build → verify → archive，跳过 design
+- `xwang-tweak`：轻量小改动，open → lightweight build → light verify → archive，跳过 design
+
+## 快速开始
+
+当用户输入 `/xwang` 或想要启动 xwang 工作流时：
+
+1. **Preset 意图检测**：优先判断用户输入是否命中 `xwang-hotfix` 或 `xwang-tweak`；命中时直接调用对应快速路径，不再走普通阶段检测。
+2. 执行阶段检测（检查未完成任务与现有 change 状态）。
+3. 根据检测结果分发到对应子流程：
+   - 有未完成任务 → 进入 `xwang-open`
+   - 无未完成任务且无现有 change → **直接进入 `xwang-design`，无需用户确认**
+   - 有 design 产物但未完成 → 进入 `xwang-design` 继续
+   - design 已完成 → 进入 `xwang-build`
+   - build 已完成（`phase: verify`） → 进入 `xwang-verify`
+   - verify 已完成（`phase: archive`） → 进入 `xwang-archive` 执行归档（需用户确认）
+4. 如果无法明确判断，默认进入 `xwang-open` 阶段。
+
+## 阶段判定（待补充）
+
+按以下优先级判断当前阶段：
+
+1. **open 阶段 / Preset 入口**：项目存在未完成任务，或用户明确表示要先检查状态。`xwang-open` 自身也会先做 Preset 意图检测，命中 hotfix / tweak 时直接分发到对应快速路径。
+2. **design 阶段**：
+   - 没有未完成任务，且存在已创建、未完成的 OpenSpec / xwang design 产物；或
+   - 没有未完成任务，也没有现有 change（`start-fresh`），直接为当前需求新建 change 并进入 design。
+3. **build 阶段**：没有未完成任务，design 产物已就绪，且当前 phase 为 `build`，进入实施构建。
+4. **verify 阶段**：build 完成后，phase 为 `verify`，进入验证阶段。
+5. **archive 阶段**：verify 完成后，phase 为 `archive`，进入 `xwang-archive` 执行归档（需用户确认）。
+
+具体检测信号和规则后续补充。
+
+## 子流程分发
+
+| 阶段 | 调用 |
+|------|------|
+| open | `xwang-open`（内部可分发到 `xwang-hotfix` / `xwang-tweak`） |
+| design | `xwang-design` |
+| build | `xwang-build` / `xwang-hotfix` / `xwang-tweak` |
+| verify | `xwang-verify` |
+| archive | `xwang-archive` |
+
+快速路径：
+- `xwang-hotfix`：bug 修复，跳过 design，build 使用 direct 模式
+- `xwang-tweak`：轻量小改动，跳过 design，使用轻量 build 与轻量 verify
+
+分发时向用户简要说明检测结论，然后调用对应 skill。
+
+## 报告格式
+
+返回简洁的状态块：
+
+```
+xwang 阶段检测: <open | design | build | verify | archive>
+
+判定依据:
+- <依据项>: <简要描述>
+
+分发动作:
+- 调用 <xwang-open | xwang-design | xwang-build | xwang-verify | xwang-archive>
+
+说明:
+- 若阶段无法明确判断，默认进入 open 阶段。
+- 若当前没有未完成任务且没有现有 change，直接进入 design 阶段，无需用户确认。
+- 若用户输入命中 hotfix / tweak preset，直接调用对应快速路径。
+```
+
+## 脚本
+
+- `xwang-env.sh`（位于 `xwang/scripts/`）：脚本定位器。source 后会动态设置 `XWANG_STATE`、`XWANG_OPEN_CHECK` 与 `XWANG_GUARD` 环境变量，避免在 skill 指令中硬编码 `.claude/skills/...` 路径。示例：
+
+  ```bash
+  XWANG_ENV="${XWANG_ENV:-$(find . "$HOME"/.*/skills "$HOME/.config" -path '*/xwang/scripts/xwang-env.sh' -type f -print -quit 2>/dev/null)}"
+  if [ -z "$XWANG_ENV" ]; then
+    echo "ERROR: xwang-env.sh not found. Ensure the xwang skill is installed." >&2
+    return 1
+  fi
+  . "$XWANG_ENV"
+  # 后续使用 "$XWANG_STATE" 调用状态脚本，使用 "$XWANG_OPEN_CHECK" 调用检测脚本，使用 "$XWANG_GUARD" 调用阶段守护脚本
+  ```
+
+- `xwang-open-check.sh`（位于 `xwang-open/scripts/`）：未完成任务检测脚本。扫描活跃 xwang change、Git dirty worktree、TODO/FIXME/XXX 注释，输出 `READY` 或 `HAS-UNFINISHED-WORK` 报告。支持 `--text`（默认）和 `--json` 两种输出格式。
+
+- `xwang-guard.sh`（位于 `xwang/scripts/`）：阶段出口守护者。在修改 `.xwang.yaml` 的 `phase` 前运行，校验当前阶段所有退出条件是否满足；支持 `--apply` 自动调用 `xwang-state.sh` 推进到下一阶段。用法示例：
+
+  ```bash
+  "$XWANG_GUARD" <change-name> design --apply   # design → build
+  "$XWANG_GUARD" <change-name> build --apply    # build → verify
+  "$XWANG_GUARD" <change-name> verify --apply   # verify → archive
+  "$XWANG_GUARD" <change-name> archive          # 仅检查归档完整性
+  ```
+
+- `xwang-state.sh`（位于 `xwang/scripts/`）：xwang 变更状态管理脚本。
+  - `init <change-name> <workflow>`：在 `openspec/changes/<change-name>/.xwang.yaml` 初始化状态文件。`full` 起始 phase 为 `design`；`quick`/`tweak` 跳过 design，起始 phase 为 `build`，并默认设置 `build_mode: direct`、`tdd_mode: direct`、`isolation: branch`。
+  - `get <change-name> <field>`：读取 `.xwang.yaml` 中指定字段的值。
+  - `set <change-name> <field> <value>`：更新 `.xwang.yaml` 中指定字段，并自动更新 `updated_at`。支持字段包括 `workflow`、`phase`（design / build / verify / archive）、`design_doc`、`plan`、`base_ref`、`isolation`、`build_mode`、`build_pause`、`tdd_mode`、`subagent_dispatch`、`direct_override`、`verify_mode`、`verify_result`、`verification_report`、`branch_status`、`archived`、`created_at`、`updated_at`。
+  - 后续可扩展 `transition` 等子命令。
+
+## 说明
+
+- 当前本 skill 仅负责阶段判定和分发，不直接执行具体任务。
+- 阶段判定逻辑将在 xwang 流程模型完善后补充。
+- 子流程分别由 `xwang-open`、`xwang-design`、`xwang-build`、`xwang-verify`、`xwang-archive` skill 实现。
+- 状态管理脚本 `xwang-state.sh` 由本 skill 维护，后续按需扩展。

package/assets/skills/xwang/scripts/xwang-env.sh

@@ -0,0 +1,48 @@
+#!/bin/bash
+# xwang-env — locator for xwang management scripts
+# Usage: source this file to set XWANG_STATE and XWANG_OPEN_CHECK
+
+set -euo pipefail
+
+# Resolve the directory of this script. Support both bash (BASH_SOURCE)
+# and zsh/other shells where $0 points to the sourced file.
+SCRIPT_SOURCE="${BASH_SOURCE[0]:-$0}"
+XWANG_SCRIPT_DIR="$(cd "$(dirname "$SCRIPT_SOURCE")" && pwd)"
+
+export XWANG_STATE="${XWANG_SCRIPT_DIR}/xwang-state.sh"
+
+if [ ! -f "$XWANG_STATE" ]; then
+  echo "ERROR: xwang-state.sh not found at $XWANG_STATE" >&2
+  return 1
+fi
+
+# Locate xwang-open-check.sh dynamically without hardcoding a .claude path.
+# Prefer the sibling relative location, then fall back to a platform-agnostic search.
+if [ -z "${XWANG_OPEN_CHECK:-}" ]; then
+  XWANG_OPEN_CHECK_SIBLING="${XWANG_SCRIPT_DIR}/../xwang-open/scripts/xwang-open-check.sh"
+  if [ -f "$XWANG_OPEN_CHECK_SIBLING" ]; then
+    XWANG_OPEN_CHECK="$XWANG_OPEN_CHECK_SIBLING"
+  else
+    XWANG_OPEN_CHECK="$(find "$XWANG_SCRIPT_DIR" "$XWANG_SCRIPT_DIR/.." "$HOME" -path '*/xwang-open/scripts/xwang-open-check.sh' -type f -print -quit 2>/dev/null || true)"
+  fi
+fi
+export XWANG_OPEN_CHECK
+
+# Locate xwang-guard.sh using the same approach.
+if [ -z "${XWANG_GUARD:-}" ]; then
+  XWANG_GUARD_SIBLING="${XWANG_SCRIPT_DIR}/xwang-guard.sh"
+  if [ -f "$XWANG_GUARD_SIBLING" ]; then
+    XWANG_GUARD="$XWANG_GUARD_SIBLING"
+  else
+    XWANG_GUARD="$(find "$XWANG_SCRIPT_DIR" "$XWANG_SCRIPT_DIR/.." "$HOME" -path '*/xwang/scripts/xwang-guard.sh' -type f -print -quit 2>/dev/null || true)"
+  fi
+fi
+export XWANG_GUARD
+
+if [ -z "$XWANG_OPEN_CHECK" ] || [ ! -f "$XWANG_OPEN_CHECK" ]; then
+  echo "WARNING: xwang-open-check.sh not found" >&2
+fi
+
+if [ -z "$XWANG_GUARD" ] || [ ! -f "$XWANG_GUARD" ]; then
+  echo "WARNING: xwang-guard.sh not found" >&2
+fi

package/assets/skills/xwang/scripts/xwang-guard.sh

@@ -0,0 +1,530 @@
+#!/bin/bash
+# xwang Phase Guard — validates exit conditions before phase transitions
+# Usage: xwang-guard.sh <change-name> <phase> [--apply]
+# Phases: design, build, verify, archive (open is not recorded in .xwang.yaml)
+# Exit 0 = all checks pass, exit 1 = blocked (reasons printed to stderr)
+# shellcheck disable=SC2329  # Functions called indirectly via check() dispatch
+
+set -euo pipefail
+
+XWANG_BASH="${XWANG_BASH:-${BASH:-bash}}"
+
+red() { echo -e "\033[31m$1\033[0m" >&2; }
+green() { echo -e "\033[32m$1\033[0m" >&2; }
+warn() { echo -e "\033[33m$1\033[0m" >&2; }
+
+# --- Input validation ---
+
+validate_change_name() {
+  local name="$1"
+  if [ -z "$name" ]; then
+    red "ERROR: Change name cannot be empty" >&2
+    exit 1
+  fi
+  if [[ ! "$name" =~ ^[a-zA-Z0-9_-]+$ ]]; then
+    red "ERROR: Invalid change name: '$name'" >&2
+    red "Valid characters: a-z, A-Z, 0-9, -, _" >&2
+    exit 1
+  fi
+  if [[ "$name" =~ \.\. ]]; then
+    red "ERROR: Change name cannot contain '..' (path traversal not allowed)" >&2
+    exit 1
+  fi
+}
+
+if [ "${XWANG_GUARD_SOURCE_ONLY:-0}" = "1" ]; then
+  CHANGE="${CHANGE:-}"
+  PHASE="${PHASE:-}"
+  APPLY="${APPLY:-0}"
+  SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]:-$0}")" && pwd -P)"
+  CHANGE_DIR="${CHANGE_DIR:-}"
+else
+  validate_change_name "$1"
+
+  CHANGE="$1"
+  PHASE="$2"
+  APPLY=0
+  SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd -P)"
+  if [[ "${3:-}" == "--apply" ]]; then
+    APPLY=1
+  fi
+  CHANGE_DIR="openspec/changes/$CHANGE"
+  if [ "$PHASE" = "archive" ] && [ ! -d "$CHANGE_DIR" ] && [ -d "openspec/changes/archive/$CHANGE" ]; then
+    CHANGE_DIR="openspec/changes/archive/$CHANGE"
+  fi
+fi
+
+BLOCK=0
+check() {
+  local desc="$1"
+  shift
+  local output
+  if output=$("$@" 2>&1); then
+    green "  [PASS] $desc"
+  else
+    red "  [FAIL] $desc"
+    if [ -n "$output" ]; then
+      while IFS= read -r line; do
+        red "    $line"
+      done <<< "$output"
+    fi
+    BLOCK=1
+  fi
+}
+
+# --- Helper functions ---
+
+yaml_field_value() {
+  local field="$1"
+  local yaml="$CHANGE_DIR/.xwang.yaml"
+  if [ -f "$yaml" ]; then
+    local value
+    value=$(grep "^${field}:" "$yaml" 2>/dev/null | sed "s/^${field}: *//" || true)
+    value=$(strip_inline_comment "$value")
+    strip_wrapping_quotes "$value"
+  fi
+}
+
+strip_inline_comment() {
+  local value="$1"
+  printf '%s\n' "$value" | awk -v squote="'" '
+    {
+      out = ""
+      quote = ""
+      for (i = 1; i <= length($0); i++) {
+        c = substr($0, i, 1)
+        if (quote == "") {
+          if (c == "\"" || c == squote) {
+            quote = c
+          } else if (c == "#" && (i == 1 || substr($0, i - 1, 1) ~ /[[:space:]]/)) {
+            sub(/[[:space:]]+$/, "", out)
+            print out
+            next
+          }
+        } else if (c == quote) {
+          quote = ""
+        }
+        out = out c
+      }
+      print out
+    }
+  '
+}
+
+strip_wrapping_quotes() {
+  local value="$1"
+  case "$value" in
+    \"*\")
+      printf '%s\n' "${value:1:${#value}-2}"
+      ;;
+    \'*\')
+      printf '%s\n' "${value:1:${#value}-2}"
+      ;;
+    *)
+      printf '%s\n' "$value"
+      ;;
+  esac
+}
+
+project_config_value() {
+  local field="$1"
+  local value
+
+  value=$(yaml_field_value "$field" 2>/dev/null || true)
+  if [ -n "$value" ] && [ "$value" != "null" ]; then
+    echo "$value"
+    return 0
+  fi
+
+  for config in ".xwang.yaml" "xwang.yaml" ".xwang.yml" "xwang.yml"; do
+    if [ -f "$config" ]; then
+      value=$(grep "^${field}:" "$config" 2>/dev/null | sed "s/^${field}: *//" || true)
+      value=$(strip_inline_comment "$value")
+      value=$(strip_wrapping_quotes "$value")
+      if [ -n "$value" ] && [ "$value" != "null" ]; then
+        echo "$value"
+        return 0
+      fi
+    fi
+  done
+}
+
+file_nonempty() {
+  [ -f "$1" ] && [ -s "$1" ]
+}
+
+tasks_has_any() {
+  local tasks="$CHANGE_DIR/tasks.md"
+  [ -f "$tasks" ] && grep -q '\- \[' "$tasks"
+}
+
+tasks_all_done() {
+  local tasks="$CHANGE_DIR/tasks.md"
+  if [ ! -f "$tasks" ]; then
+    echo "tasks.md is missing at $tasks" >&2
+    echo "Next: restore or create tasks.md for this change before leaving build." >&2
+    return 1
+  fi
+  if ! grep -q '\- \[x\]' "$tasks"; then
+    echo "tasks.md has no completed tasks." >&2
+    echo "Next: complete implementation tasks and mark them with '- [x]'." >&2
+    return 1
+  fi
+  if grep -q '\- \[ \]' "$tasks"; then
+    echo "Unfinished tasks:" >&2
+    grep -n '\- \[ \]' "$tasks" >&2 || true
+    echo "Next: complete or explicitly remove unfinished tasks, then mark tasks.md with '- [x]'." >&2
+    return 1
+  fi
+  return 0
+}
+
+plan_tasks_all_done() {
+  local plan
+  plan=$(yaml_field_value "plan" 2>/dev/null || true)
+
+  if [ -z "$plan" ] || [ "$plan" = "null" ]; then
+    return 0
+  fi
+  if [ ! -f "$plan" ]; then
+    echo "plan file is missing at $plan" >&2
+    echo "Next: restore the plan file or update .xwang.yaml plan before leaving build." >&2
+    return 1
+  fi
+  if grep -q '^[[:space:]]*- \[ \]' "$plan"; then
+    echo "Unfinished plan tasks:" >&2
+    grep -n '^[[:space:]]*- \[ \]' "$plan" >&2 || true
+    echo "Next: check off corresponding completed plan tasks, then commit the plan update." >&2
+    return 1
+  fi
+  return 0
+}
+
+isolation_selected() {
+  local isolation
+  isolation=$(yaml_field_value "isolation" 2>/dev/null || true)
+  case "$isolation" in
+    branch|worktree) return 0 ;;
+    *)
+      echo "isolation must be branch or worktree, got '${isolation:-null}'" >&2
+      echo "Next: ask the user to choose branch or worktree, create the chosen isolation, then run:" >&2
+      echo "  \"\$XWANG_BASH\" \"\$XWANG_STATE\" set $CHANGE isolation <branch|worktree>" >&2
+      return 1
+      ;;
+  esac
+}
+
+build_mode_selected() {
+  local build_mode
+  build_mode=$(yaml_field_value "build_mode" 2>/dev/null || true)
+  case "$build_mode" in
+    subagent-driven-development|executing-plans|direct) return 0 ;;
+    *)
+      echo "build_mode must be selected before leaving build, got '${build_mode:-null}'" >&2
+      echo "Next: ask the user to choose an execution mode, then run:" >&2
+      echo "  \"\$XWANG_BASH\" \"\$XWANG_STATE\" set $CHANGE build_mode <subagent-driven-development|executing-plans|direct>" >&2
+      return 1
+      ;;
+  esac
+}
+
+build_mode_allowed_for_workflow() {
+  local workflow build_mode direct_override
+  workflow=$(yaml_field_value "workflow" 2>/dev/null || true)
+  build_mode=$(yaml_field_value "build_mode" 2>/dev/null || true)
+  direct_override=$(yaml_field_value "direct_override" 2>/dev/null || true)
+
+  if [ "$build_mode" != "direct" ]; then
+    return 0
+  fi
+  case "$workflow" in
+    quick|tweak) return 0 ;;
+    *)
+      if [ "$direct_override" = "true" ]; then
+        return 0
+      fi
+      echo "build_mode=direct is only allowed for quick/tweak unless direct_override: true is recorded" >&2
+      echo "Next: choose executing-plans or subagent-driven-development, or stop and ask the user for an explicit direct override." >&2
+      return 1
+      ;;
+  esac
+}
+
+subagent_dispatch_confirmed() {
+  local build_mode subagent_dispatch
+  build_mode=$(yaml_field_value "build_mode" 2>/dev/null || true)
+  subagent_dispatch=$(yaml_field_value "subagent_dispatch" 2>/dev/null || true)
+
+  if [ "$build_mode" != "subagent-driven-development" ]; then
+    return 0
+  fi
+
+  if [ "$subagent_dispatch" = "confirmed" ]; then
+    return 0
+  fi
+
+  echo "subagent_dispatch must be confirmed before using build_mode=subagent-driven-development" >&2
+  echo "Next: confirm the current platform has a real background subagent/Task/multi-agent dispatcher, then run:" >&2
+  echo "  \"\$XWANG_BASH\" \"\$XWANG_STATE\" set $CHANGE subagent_dispatch confirmed" >&2
+  echo "Or ask the user to switch to executing-plans and run:" >&2
+  echo "  \"\$XWANG_BASH\" \"\$XWANG_STATE\" set $CHANGE build_mode executing-plans" >&2
+  return 1
+}
+
+tdd_mode_selected() {
+  local workflow tdd_mode
+  workflow=$(yaml_field_value "workflow" 2>/dev/null || true)
+  tdd_mode=$(yaml_field_value "tdd_mode" 2>/dev/null || true)
+
+  case "$workflow" in
+    quick|tweak) return 0 ;;
+  esac
+
+  case "$tdd_mode" in
+    tdd|direct) return 0 ;;
+    *)
+      echo "tdd_mode must be tdd or direct for full workflow, got '${tdd_mode:-null}'" >&2
+      echo "Next: ask the user to choose TDD enforcement level, then run:" >&2
+      echo "  \"\$XWANG_BASH\" \"\$XWANG_STATE\" set $CHANGE tdd_mode <tdd|direct>" >&2
+      return 1
+      ;;
+  esac
+}
+
+verification_report_exists() {
+  local report
+  report=$(yaml_field_value "verification_report" 2>/dev/null || true)
+  [ -n "$report" ] && [ "$report" != "null" ] && [ -f "$report" ]
+}
+
+branch_status_handled() {
+  local status
+  status=$(yaml_field_value "branch_status" 2>/dev/null || true)
+  [ "$status" = "handled" ]
+}
+
+design_doc_recorded() {
+  local design_doc
+  design_doc=$(yaml_field_value "design_doc" 2>/dev/null || true)
+  if [ -n "$design_doc" ] && [ "$design_doc" != "null" ] && [ -f "$design_doc" ]; then
+    return 0
+  fi
+  echo "design_doc must point to an existing PRD for full workflow before leaving design." >&2
+  echo "Next: create the PRD and run: \"\$XWANG_BASH\" \"\$XWANG_STATE\" set $CHANGE design_doc <path>" >&2
+  return 1
+}
+
+archived_is_true() {
+  local val
+  val=$(yaml_field_value "archived" 2>/dev/null || true)
+  [ "$val" = "true" ]
+}
+
+run_command_string() {
+  local command="$1"
+  if [ -z "$command" ]; then
+    red "ERROR: build/verify command is empty" >&2
+    return 1
+  fi
+  # Basic command injection guard: reject dangerous shell metacharacters
+  if [[ "$command" =~ [\;\|\&\$\`] ]]; then
+    red "ERROR: build/verify command contains shell metacharacters: $command" >&2
+    red "Allowed: alphanumeric, spaces, hyphens, underscores, dots, colons, forward slashes, quotes" >&2
+    return 1
+  fi
+  echo "+ $command" >&2
+  "$XWANG_BASH" -lc "$command"
+}
+
+is_windows_bash() {
+  case "$(uname -s 2>/dev/null || true)" in
+    MINGW*|MSYS*|CYGWIN*) return 0 ;;
+    *) return 1 ;;
+  esac
+}
+
+build_passes() {
+  if [ "${XWANG_SKIP_BUILD:-0}" = "1" ]; then
+    return 0
+  fi
+  local configured_build
+  configured_build=$(project_config_value "build_command" 2>/dev/null || true)
+  if [ -n "$configured_build" ]; then
+    run_command_string "$configured_build"
+    return $?
+  fi
+  if [ -f "package.json" ] && grep -q '"build"' "package.json"; then
+    npm run build
+    return $?
+  fi
+  if [ -f "pom.xml" ]; then
+    if [ -x "./mvnw" ]; then
+      ./mvnw compile -q
+    elif is_windows_bash && command -v mvn.cmd >/dev/null 2>&1; then
+      mvn.cmd compile -q
+    else
+      mvn compile -q
+    fi
+    return $?
+  fi
+  if [ -f "Cargo.toml" ]; then
+    cargo build
+    return $?
+  fi
+  return 1
+}
+
+verification_command_passes() {
+  if [ "${XWANG_SKIP_BUILD:-0}" = "1" ]; then
+    return 0
+  fi
+  local configured_verify
+  configured_verify=$(project_config_value "verify_command" 2>/dev/null || true)
+  if [ -n "$configured_verify" ]; then
+    run_command_string "$configured_verify"
+    return $?
+  fi
+  build_passes
+}
+
+preflight() {
+  if [ ! -d "$CHANGE_DIR" ]; then
+    red "FATAL: change directory not found: $CHANGE_DIR"
+    exit 1
+  fi
+  if [ ! -f "$CHANGE_DIR/.xwang.yaml" ]; then
+    red "FATAL: .xwang.yaml not found in $CHANGE_DIR"
+    exit 1
+  fi
+}
+
+# --- Phase-specific guards ---
+
+guard_design() {
+  echo "=== Guard: design → build ===" >&2
+
+  local workflow
+  workflow=$(yaml_field_value "workflow" 2>/dev/null || true)
+
+  check "proposal.md exists and non-empty" file_nonempty "$CHANGE_DIR/proposal.md"
+  check "design.md exists and non-empty" file_nonempty "$CHANGE_DIR/design.md"
+  check "tasks.md exists and non-empty" file_nonempty "$CHANGE_DIR/tasks.md"
+  check "tasks.md has at least one task" tasks_has_any
+
+  if [ "$workflow" = "full" ]; then
+    check "design_doc is recorded for full workflow" design_doc_recorded
+  fi
+
+  local design_doc
+  design_doc=$(yaml_field_value "design_doc" 2>/dev/null || true)
+  if [ -n "$design_doc" ] && [ "$design_doc" != "null" ]; then
+    check "PRD file ($design_doc) exists" file_nonempty "$design_doc"
+  elif [ "$workflow" != "full" ]; then
+    warn "  [WARN] No design_doc recorded in .xwang.yaml (optional for quick/tweak)"
+  fi
+}
+
+guard_build() {
+  echo "=== Guard: build → verify ===" >&2
+
+  check "isolation selected" isolation_selected
+  check "build_mode selected" build_mode_selected
+  check "build_mode allowed for workflow" build_mode_allowed_for_workflow
+  check "subagent dispatch confirmed" subagent_dispatch_confirmed
+  check "tdd_mode selected" tdd_mode_selected
+  check "tasks.md all tasks checked" tasks_all_done
+  check "plan file all tasks checked" plan_tasks_all_done
+  check "proposal.md exists" file_nonempty "$CHANGE_DIR/proposal.md"
+  check "Build passes" build_passes
+}
+
+guard_verify() {
+  echo "=== Guard: verify → archive ===" >&2
+
+  check "tasks.md all tasks checked" tasks_all_done
+  check "Build/verify passes" verification_command_passes
+  check "verification_report exists" verification_report_exists
+  check "branch_status=handled" branch_status_handled
+}
+
+guard_archive() {
+  echo "=== Guard: archive completeness ===" >&2
+
+  check "archived is true" archived_is_true
+  check "proposal.md exists" file_nonempty "$CHANGE_DIR/proposal.md"
+  check "design.md exists" file_nonempty "$CHANGE_DIR/design.md"
+  check "tasks.md all tasks checked" tasks_all_done
+}
+
+locate_state_script() {
+  local state_sh="$SCRIPT_DIR/xwang-state.sh"
+  if [ -f "$state_sh" ]; then
+    echo "$state_sh"
+    return 0
+  fi
+  state_sh="$(find "$SCRIPT_DIR" "$SCRIPT_DIR/.." "$HOME" -path '*/xwang/scripts/xwang-state.sh' -type f -print -quit 2>/dev/null || true)"
+  if [ -n "$state_sh" ] && [ -f "$state_sh" ]; then
+    echo "$state_sh"
+    return 0
+  fi
+  return 1
+}
+
+apply_state_update() {
+  local state_sh
+  if ! state_sh=$(locate_state_script); then
+    red "FATAL: xwang-state.sh not found; cannot apply state transition"
+    exit 1
+  fi
+
+  local p="$1"
+  case "$p" in
+    design) "$XWANG_BASH" "$state_sh" set "$CHANGE" phase build ;;
+    build)
+      "$XWANG_BASH" "$state_sh" set "$CHANGE" phase verify
+      "$XWANG_BASH" "$state_sh" set "$CHANGE" verify_result pending
+      ;;
+    verify)
+      "$XWANG_BASH" "$state_sh" set "$CHANGE" phase archive
+      "$XWANG_BASH" "$state_sh" set "$CHANGE" verify_result pass
+      ;;
+  esac
+}
+
+# --- Main ---
+
+if [ "${XWANG_GUARD_SOURCE_ONLY:-0}" = "1" ]; then
+  return 0 2>/dev/null
+  red "ERROR: XWANG_GUARD_SOURCE_ONLY=1 is only for sourcing, not direct execution" >&2
+  exit 1
+fi
+
+case "$PHASE" in
+  design)   preflight ; guard_design ;;
+  build)    preflight ; guard_build ;;
+  verify)   preflight ; guard_verify ;;
+  archive)  preflight ; guard_archive ;;
+  *)
+    red "Unknown phase: $PHASE"
+    echo "Valid phases: design, build, verify, archive" >&2
+    exit 1
+    ;;
+esac
+
+if [ "$BLOCK" -eq 1 ]; then
+  echo "" >&2
+  red "BLOCKED — fix failing checks before proceeding to next phase"
+  exit 1
+else
+  echo "" >&2
+  green "ALL CHECKS PASSED — ready for next phase"
+  if [ "$APPLY" -eq 1 ]; then
+    apply_state_update "$PHASE"
+    case "$PHASE" in
+      design) green "  [APPLY] .xwang.yaml updated: phase=build" ;;
+      build)  green "  [APPLY] .xwang.yaml updated: phase=verify, verify_result=pending" ;;
+      verify) green "  [APPLY] .xwang.yaml updated: phase=archive, verify_result=pass" ;;
+    esac
+  fi
+  exit 0
+fi