xwang 0.0.9 → 0.0.11

package/assets/manifest.json

@@ -6,6 +6,7 @@
     "xwang/scripts/xwang-state.sh",
     "xwang/scripts/xwang-guard.sh",
     "xwang/scripts/xwang-doc-lang-check.sh",
+    "xwang/scripts/xwang-create-change.sh",
     "xwang-open/SKILL.md",
     "xwang-open/scripts/xwang-open-check.sh",
     "xwang-design/SKILL.md",

package/assets/skills/xwang/scripts/xwang-create-change.sh

@@ -0,0 +1,151 @@
+#!/bin/bash
+# xwang-create-change — create an OpenSpec change directory scaffold with a given name.
+# Usage: xwang-create-change.sh <change-name> <workflow> [schema]
+# Creates openspec/changes/<change-name>/ with .openspec.yaml and minimal artifact stubs.
+# Exits 0 on success, 1 on error.
+
+set -euo pipefail
+
+name="${1:-}"
+workflow="${2:-}"
+schema="${3:-spec-driven}"
+
+if [ -z "$name" ] || [ -z "$workflow" ]; then
+  echo "Usage: $0 <change-name> <workflow> [schema]" >&2
+  exit 2
+fi
+
+# Validate name using the same rules as xwang-state/xwang-guard
+if [[ "$name" =~ \.\. ]]; then
+  echo "ERROR: Change name cannot contain '..'" >&2
+  exit 1
+fi
+if printf '%s' "$name" | perl -ne 'exit 1 if m{[/\\\s\0-\x1F\x7F;|&$`()<>{}[\]*'"'"'"!#@%^=+~]}; exit 0'; then
+  : # valid
+else
+  echo "ERROR: Invalid change name: '$name'" >&2
+  echo "Avoid: / \\ spaces control chars and shell metacharacters" >&2
+  exit 1
+fi
+
+# Determine project root
+find_project_root() {
+  if [ -n "${XWANG_PROJECT_ROOT:-}" ]; then
+    printf '%s' "$XWANG_PROJECT_ROOT"
+    return 0
+  fi
+  local git_root
+  git_root=$(git rev-parse --show-toplevel 2>/dev/null || true)
+  if [ -n "$git_root" ]; then
+    printf '%s' "$git_root"
+    return 0
+  fi
+  local dir="$PWD"
+  while [ "$dir" != "/" ]; do
+    if [ -d "$dir/openspec/changes" ]; then
+      printf '%s' "$dir"
+      return 0
+    fi
+    dir=$(dirname "$dir")
+  done
+  printf '%s' "$PWD"
+}
+
+PROJECT_ROOT=$(find_project_root)
+CHANGE_DIR="$PROJECT_ROOT/openspec/changes/$name"
+
+if [ -d "$CHANGE_DIR" ]; then
+  echo "ERROR: change directory already exists: $CHANGE_DIR" >&2
+  exit 1
+fi
+
+mkdir -p "$CHANGE_DIR"
+
+# .openspec.yaml
+cat > "$CHANGE_DIR/.openspec.yaml" <<EOF
+schema: $schema
+created: $(date -u +%Y-%m-%d)
+EOF
+
+# Minimal stubs; the caller (xwang-design/hotfix/tweak) should overwrite with real content.
+case "$workflow" in
+  full)
+    cat > "$CHANGE_DIR/proposal.md" <<'EOF'
+## Why
+
+## What Changes
+
+## Capabilities
+
+### New Capabilities
+
+无。
+
+### Modified Capabilities
+
+## Impact
+EOF
+    cat > "$CHANGE_DIR/design.md" <<'EOF'
+## Context
+
+## Goals / Non-Goals
+
+**Goals:**
+
+**Non-Goals:**
+
+## Decisions
+
+## Risks / Trade-offs
+EOF
+    cat > "$CHANGE_DIR/tasks.md" <<'EOF'
+## Tasks
+
+- [ ] Task 1
+EOF
+    ;;
+  quick|hotfix)
+    cat > "$CHANGE_DIR/proposal.md" <<'EOF'
+## Why
+
+## What Changes
+
+## Impact
+EOF
+    cat > "$CHANGE_DIR/design.md" <<'EOF'
+## Context
+
+## Solution
+
+## Risks / Trade-offs
+EOF
+    cat > "$CHANGE_DIR/tasks.md" <<'EOF'
+## Tasks
+
+- [ ] Task 1
+EOF
+    ;;
+  tweak)
+    cat > "$CHANGE_DIR/proposal.md" <<'EOF'
+## Why
+
+## What Changes
+
+## Impact
+EOF
+    cat > "$CHANGE_DIR/design.md" <<'EOF'
+## Solution
+EOF
+    cat > "$CHANGE_DIR/tasks.md" <<'EOF'
+## Tasks
+
+- [ ] Task 1
+EOF
+    ;;
+  *)
+    echo "ERROR: unknown workflow: $workflow" >&2
+    exit 1
+    ;;
+esac
+
+echo "$CHANGE_DIR"

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

@@ -76,6 +76,17 @@ if [ -z "${XWANG_DOC_LANG_CHECK:-}" ]; then
 fi
 export XWANG_DOC_LANG_CHECK
 
+# Locate xwang-create-change.sh using the same approach.
+if [ -z "${XWANG_CREATE_CHANGE:-}" ]; then
+  XWANG_CREATE_CHANGE_SIBLING="${XWANG_SCRIPT_DIR}/xwang-create-change.sh"
+  if [ -f "$XWANG_CREATE_CHANGE_SIBLING" ]; then
+    XWANG_CREATE_CHANGE="$(cd "$(dirname "$XWANG_CREATE_CHANGE_SIBLING")" && pwd)/$(basename "$XWANG_CREATE_CHANGE_SIBLING")"
+  else
+    XWANG_CREATE_CHANGE="$(locate_by_glob '*/xwang/scripts/xwang-create-change.sh' "${SEARCH_DIRS[@]}" 2>/dev/null || true)"
+  fi
+fi
+export XWANG_CREATE_CHANGE
+
 if [ -z "$XWANG_OPEN_CHECK" ] || [ ! -f "$XWANG_OPEN_CHECK" ]; then
   echo "WARNING: xwang-open-check.sh not found" >&2
 fi
@@ -87,3 +98,7 @@ fi
 if [ -z "$XWANG_DOC_LANG_CHECK" ] || [ ! -f "$XWANG_DOC_LANG_CHECK" ]; then
   echo "WARNING: xwang-doc-lang-check.sh not found" >&2
 fi
+
+if [ -z "$XWANG_CREATE_CHANGE" ] || [ ! -f "$XWANG_CREATE_CHANGE" ]; then
+  echo "WARNING: xwang-create-change.sh not found" >&2
+fi

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

@@ -343,6 +343,26 @@ branch_status_handled() {
   [ "$status" = "handled" ]
 }
 
+grilled_completed() {
+  local val
+  val=$(yaml_field_value "grilled" 2>/dev/null || true)
+  if [ "$val" = "true" ]; then
+    return 0
+  fi
+  echo "grilled must be true before leaving design; run grill-with-docs and then:"
+  echo "  \"\$XWANG_BASH\" \"\$XWANG_STATE\" set $CHANGE grilled true" >&2
+  return 1
+}
+
+domain_glossary_exists() {
+  if [ -f "$PROJECT_ROOT/CONTEXT.md" ] || [ -f "$PROJECT_ROOT/docs/glossary.md" ] || [ -f "$PROJECT_ROOT/glossary.md" ]; then
+    return 0
+  fi
+  echo "No domain glossary found (expected CONTEXT.md or docs/glossary.md)." >&2
+  echo "If this change introduces domain terms, create/update the glossary before leaving design." >&2
+  return 1
+}
+
 design_doc_recorded() {
   local design_doc
   design_doc=$(yaml_field_value "design_doc" 2>/dev/null || true)
@@ -450,6 +470,8 @@ guard_design() {
   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
+  check "grilling completed" grilled_completed
+  check "domain glossary exists" domain_glossary_exists
   check "OpenSpec artifacts language consistency" openspec_artifacts_language_consistent
 
   if [ "$workflow" = "full" ]; then

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

@@ -256,6 +256,7 @@ build_pause: null
 tdd_mode: $tdd_mode
 subagent_dispatch: null
 direct_override: false
+grilled: false
 verify_mode: null
 verify_result: pending
 verification_report: null
@@ -303,12 +304,12 @@ cmd_set() {
   fi
 
   case "$field" in
-    workflow|phase|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|build_command|verify_command)
+    workflow|phase|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|build_command|verify_command|grilled)
       # Valid field
       ;;
     *)
       red "ERROR: Unknown field: '$field'" >&2
-      red "Valid fields: workflow, phase, 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, build_command, verify_command" >&2
+      red "Valid fields: workflow, phase, 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, build_command, verify_command, grilled" >&2
       exit 1
       ;;
   esac
@@ -335,7 +336,7 @@ cmd_set() {
     subagent_dispatch)
       validate_enum "$value" "null" "confirmed"
       ;;
-    direct_override|archived)
+    direct_override|archived|grilled)
       validate_enum "$value" "true" "false"
       ;;
     verify_mode)

package/assets/skills/xwang-design/SKILL.md

@@ -9,18 +9,19 @@ description: 启动 xwang 项目阶段2：深度设计，明确需求并同步
 
 当用户触发 xwang 阶段2时：
 
-1. 调用 `/grill-with-docs` 围绕需求目标、范围、用户、约束、验收标准等逐层追问，同时对照现有领域模型和文档（CONTEXT.md、ADRs）挑战术语、澄清冲突，直到达成共识。
+1. **必须调用 `/grill-with-docs`** 围绕需求目标、范围、用户、约束、验收标准等逐层追问，同时对照现有领域模型和文档（CONTEXT.md、ADRs）挑战术语、澄清冲突，直到达成共识。**不得跳过 grilling；若用户试图跳过，必须拒绝并说明这是 design 阶段的强制入口。**
 2. **强制进行 PRD 拆分预检（阻塞点）**：`/grill-with-docs` 确认需求完成后，**必须**输出一份 `PRD 拆分预检报告`，基于已澄清信息评估是否需要拆分为多个 change。**无论是否需要拆分，都必须停下来向用户展示报告并等待明确选择**；未确认前不得生成 PRD 或创建 OpenSpec change。
 3. grilling 结束后，根据需求内容自己总结一个简洁的中文需求名称 `<name>`，用于生成 `docs/mattpocock/<name>-prd.md`。
 4. 创建 `docs/mattpocock/` 目录（如不存在）。
-5. **需求澄清完成确认（阻塞点）**：向用户输出一份结构化的需求摘要（目标、范围、用户、核心行为、边界情况、非功能性需求、依赖与限制），等待用户明确确认或提出修改；未确认前不得生成 PRD 或创建 OpenSpec change。
-6. 用户确认后，调用 `/to-prd` 基于对话上下文合成 PRD。
-7. 将生成的 PRD 内容写入 `docs/mattpocock/<name>-prd.md`。
-8. 直接调用 `/openspec-new-change`：以 `<name>` 作为 change 名称，将 PRD 的中文内容作为 change 文档/上下文创建 change，过程中无需用户确认；若 `/openspec-new-change` 流程中出现任何确认提示（如“是否继续创建 proposal.md？”），直接代为确认并继续，不得将确认问题抛给用户；**要求 `/openspec-new-change` 生成的所有文档/artifact 必须使用中文表述，包括但不限于 `proposal.md`、`design.md`、`tasks.md` 以及 `specs/*/spec.md`**。
-9. **初始化 xwang 状态**：调用 `"$XWANG_STATE" init <name> full`，在 `openspec/changes/<name>/.xwang.yaml` 创建状态文件（起始 phase 为 `design`）。
-10. **记录 design 文件**：调用 `"$XWANG_STATE" set <name> design_doc docs/mattpocock/<name>-prd.md`，将 PRD 路径写入状态。
-11. **阶段出口守护（design → build）**：调用 `"$XWANG_GUARD" <name> design --apply` 校验 design 阶段退出条件，通过后会自动将 `.xwang.yaml` 的 `phase` 推进到 `build`。
-12. **自动进入 build 阶段（full 模式）**：向用户简要汇报 PRD 保存路径、change 名称、状态文件路径后，直接调用 `/xwang-build` 继续阶段3，无需等待用户确认。
+5. **需求澄清完成确认（强制阻塞点）**：向用户输出一份结构化的需求摘要（目标、范围、用户、核心行为、边界情况、非功能性需求、依赖与限制、新增/更新术语），并确认专业术语已写入 `CONTEXT.md` 或 `docs/glossary.md`；等待用户明确确认或提出修改，未确认前不得生成 PRD。
+6. grilling 完成后，运行 `"$XWANG_STATE" set <name> grilled true` 记录 grilling 已完成。
+7. 用户确认后，调用 `/to-prd` 基于对话上下文合成 PRD。
+8. 将生成的 PRD 内容写入 `docs/mattpocock/<name>-prd.md`。
+9. 直接调用 `/openspec-new-change`：以 `<name>` 作为 change 名称，将 PRD 的中文内容作为 change 文档/上下文创建 change，过程中无需用户确认；若 `/openspec-new-change` 流程中出现任何确认提示（如“是否继续创建 proposal.md？”），直接代为确认并继续，不得将确认问题抛给用户；**要求 `/openspec-new-change` 生成的所有文档/artifact 必须使用中文表述，包括但不限于 `proposal.md`、`design.md`、`tasks.md` 以及 `specs/*/spec.md`**。
+10. **初始化 xwang 状态**：调用 `"$XWANG_STATE" init <name> full`，在 `openspec/changes/<name>/.xwang.yaml` 创建状态文件（起始 phase 为 `design`）。
+11. **记录 design 文件**：调用 `"$XWANG_STATE" set <name> design_doc docs/mattpocock/<name>-prd.md`，将 PRD 路径写入状态。
+12. **阶段出口守护（design → build）**：调用 `"$XWANG_GUARD" <name> design --apply` 校验 design 阶段退出条件，通过后会自动将 `.xwang.yaml` 的 `phase` 推进到 `build`。
+13. **自动进入 build 阶段（full 模式）**：向用户简要汇报 PRD 保存路径、change 名称、状态文件路径后，直接调用 `/xwang-build` 继续阶段3，无需等待用户确认。
 
     汇报示例：
 
@@ -45,11 +46,12 @@ fi
 . "$XWANG_ENV"
 ```
 
-### Step 1：需求澄清
+### Step 1：需求澄清（强制）
 
 - [ ] 确认用户要启动 xwang 阶段2（关键词：xwang-design、xwang 阶段2、开始 xwang）。
-- [ ] 调用 `/grill-with-docs`，从用户视角深挖：目标用户、核心问题、预期行为、边界情况、非功能性需求、依赖与限制；并对照现有 CONTEXT.md/ADRs 挑战术语、澄清冲突，必要时实时更新文档。
+- [ ] **必须调用 `/grill-with-docs`**，从用户视角深挖：目标用户、核心问题、预期行为、边界情况、非功能性需求、依赖与限制；并对照现有 CONTEXT.md/ADRs 挑战术语、澄清冲突，必要时实时更新文档。**如果 `/grill-with-docs` 没有执行或没有完成，不得进入后续步骤。**
 - [ ] grilling 过程中持续追问，直到形成清晰的需求理解。
+- [ ] grilling 完成后，**必须记录 grilling 已完成**：运行 `"$XWANG_STATE" set <name> grilled true`。
 - [ ] `/grill-with-docs` 完成需求确认后，**不得立即生成 PRD**，必须先进入 Step 1a 的强制拆分预检。
 
 ### Step 1a：PRD 拆分预检（强制阻塞点）
@@ -99,7 +101,11 @@ grilling 确认完成后、生成 PRD 前，**必须**执行 PRD 拆分预检并
 
 - [ ] grilling 结束后，根据需求核心内容自己生成一个简洁的中文名称（如 `会议周视图 UI 增强`）作为 `<name>`，直接使用无需确认。
 - [ ] 使用 `mkdir -p docs/mattpocock` 确保目录存在。
-- [ ] 向用户输出结构化的**需求确认摘要**（建议包含：目标、范围、目标用户、核心行为、边界情况、非功能性需求、依赖与限制）。
+- [ ] **领域术语守护**：梳理本次需求涉及的专业术语（尤其是新引入的、或有歧义的术语）：
+  - 若项目已有 `CONTEXT.md` 或 `docs/glossary.md`，检查这些术语是否已定义；未定义的**必须**补充进去。
+  - 若项目没有术语文件，但本次需求出现了值得固化的专业术语，**必须**创建 `CONTEXT.md` 或 `docs/glossary.md` 并写入定义。
+  - 在最终的需求确认摘要中显式列出「新增/更新术语」。
+- [ ] 向用户输出结构化的**需求确认摘要**（建议包含：目标、范围、目标用户、核心行为、边界情况、非功能性需求、依赖与限制、新增/更新术语）。
 - [ ] **必须使用当前平台可用的用户输入/确认机制暂停并等待用户确认需求澄清完成**。若用户提出修改，根据反馈调整摘要并再次确认，直到达成共识。
 - [ ] **未确认前不得调用 `/to-prd`，不得生成 PRD，不得创建 OpenSpec change**。
 
@@ -121,8 +127,17 @@ grilling 确认完成后、生成 PRD 前，**必须**执行 PRD 拆分预检并
 
 ### Step 3：创建 OpenSpec change
 
-- [ ] 直接调用 `/openspec-new-change` 创建 change：change 名称为 `<name>`，文档/描述使用 PRD 的中文内容，过程中不再询问用户确认；若其流程中出现确认提示（如“是否继续创建 proposal.md？”），直接代为确认并继续。
-- [ ] **`/openspec-new-change` 生成的所有文档/artifact 必须使用中文表述，包括但不限于 `proposal.md`、`design.md`、`tasks.md` 以及 `specs/*/spec.md`**。
+- [ ] 使用 xwang 自带脚本创建中文 change 目录和 OpenSpec 骨架（绕过 `/openspec-new-change` 的英文 kebab-case 限制，避免中文文件被删除或重命名）：
+
+  ```bash
+  XWANG_ENV="${XWANG_ENV:-$(find . "$HOME"/.*/skills "$HOME/.config" -path '*/xwang/scripts/xwang-env.sh' -type f -print -quit 2>/dev/null)}"
+  . "$XWANG_ENV"
+  "$XWANG_CREATE_CHANGE" <name> full
+  ```
+
+- [ ] 基于 PRD 内容覆盖 `openspec/changes/<name>/proposal.md`、`design.md`、`tasks.md`，确保所有 artifact 使用中文表述。
+- [ ] 如需生成 delta spec，创建 `openspec/changes/<name>/specs/<name>/spec.md`。
+- [ ] **中文名称保护**：任何情况下不得删除、重命名或迁移已创建的中文文件（包括 `openspec/changes/<中文名>/` 和 `docs/mattpocock/<中文名>-prd.md`）。如果创建过程中报错，停止并报告，而不是改为英文。
 
 ### Step 4：初始化状态并推进
 

package/assets/skills/xwang-hotfix/SKILL.md

@@ -30,13 +30,21 @@ fi
 ### Step 1：快速开启
 
 - [ ] 确认用户要触发 hotfix（关键词：xwang-hotfix、hotfix、bugfix、快速修复）。
-- [ ] 用户未提供 change 名称时，根据修复主题生成一个简洁的 kebab-case 名称 `<name>`。
-- [ ] 直接调用 `/openspec-new-change` 创建精简 change：
+- [ ] 用户未提供 change 名称时，根据修复主题生成一个简洁的中文名称 `<name>`（如 `登录按钮失效修复`）。
+- [ ] 使用 xwang 自带脚本创建中文 change 目录和 OpenSpec 骨架（绕过 `/openspec-new-change` 的 kebab-case 限制）：
+
+  ```bash
+  XWANG_ENV="${XWANG_ENV:-$(find . "$HOME"/.*/skills "$HOME/.config" -path '*/xwang/scripts/xwang-env.sh' -type f -print -quit 2>/dev/null)}"
+  . "$XWANG_ENV"
+  "$XWANG_CREATE_CHANGE" <name> hotfix
+  ```
+
+- [ ] 基于修复内容覆盖 `openspec/changes/<name>/proposal.md`、`design.md`、`tasks.md`：
   - `proposal.md`：问题描述 + 根因分析 + 修复目标
   - `design.md`：修复方案（1 个即可，无需多方案对比）
   - `tasks.md`：修复任务清单
   - 通常**无需 delta spec**（除非修复改变了已有 spec 的验收场景）
-- [ ] **`/openspec-new-change` 生成的所有文档/artifact 必须使用中文表述**。
+- [ ] **`openspec/changes/<name>/` 下的所有文档/artifact 必须使用中文表述**。
 - [ ] 调用 `"$XWANG_STATE" init <name> quick` 初始化状态（`workflow: quick`，`phase: build`，跳过 design）。
 
 ### Step 2：直接构建

package/assets/skills/xwang-tweak/SKILL.md

@@ -31,13 +31,21 @@ fi
 ### Step 1：快速开启
 
 - [ ] 确认用户要触发 tweak（关键词：xwang-tweak、tweak、小改动、局部优化）。
-- [ ] 用户未提供 change 名称时，根据变更主题生成一个简洁的 kebab-case 名称 `<name>`。
-- [ ] 直接调用 `/openspec-new-change` 创建精简 change：
+- [ ] 用户未提供 change 名称时，根据变更主题生成一个简洁的中文名称 `<name>`（如 `文案优化`）。
+- [ ] 使用 xwang 自带脚本创建中文 change 目录和 OpenSpec 骨架（绕过 `/openspec-new-change` 的 kebab-case 限制）：
+
+  ```bash
+  XWANG_ENV="${XWANG_ENV:-$(find . "$HOME"/.*/skills "$HOME/.config" -path '*/xwang/scripts/xwang-env.sh' -type f -print -quit 2>/dev/null)}"
+  . "$XWANG_ENV"
+  "$XWANG_CREATE_CHANGE" <name> tweak
+  ```
+
+- [ ] 基于变更内容覆盖 `openspec/changes/<name>/proposal.md`、`design.md`、`tasks.md`：
   - `proposal.md`：变更动机 + 目标 + 范围
   - `design.md`：简短实现说明（无需方案对比）
   - `tasks.md`：不超过 3 个任务
   - **无需 delta spec**（一旦需要，升级为完整 `/xwang`）
-- [ ] **`/openspec-new-change` 生成的所有文档/artifact 必须使用中文表述**。
+- [ ] **`openspec/changes/<name>/` 下的所有文档/artifact 必须使用中文表述**。
 - [ ] 调用 `"$XWANG_STATE" init <name> tweak` 初始化状态（`workflow: tweak`，`phase: build`，跳过 design）。
 
 ### Step 2：轻量构建

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "xwang",
-  "version": "0.0.9",
+  "version": "0.0.11",
   "description": "xwang CLI",
   "keywords": [
     "xwang",