@dsh-cove/dsh-web-all 0.0.0-stage → 0.4.4

package/presets/code-vibe/skills/wish-programming/scripts/verify.sh

@@ -0,0 +1,169 @@
+#!/usr/bin/env bash
+# Wish 机械验收门 — 只核对「产生真实质量后果」的证据，不搞文档仪式。
+#
+# Usage:
+#   verify.sh --cwd <workspace> --spec <id> [--root <dir>]
+#
+# Checks:
+#   1. .sdd/acceptance/<id>/coverage.tsv 存在 且 coverage_check.py 通过（存量功能落点完整）
+#   2. .sdd/acceptance/<id>/shots/ 下存在三个视口的真实渲染截图（1280 / 1440 / narrow 各 ≥1 张，
+#      文件名含对应视口标记；多视口 = 用户可见验收）。非 UI 愿望：存在
+#      .sdd/acceptance/<id>.no-ui 豁免文件（用户在确认阶段显式声明）→ 跳过截图要求，其余照查。
+#   3. live 重跑（保留）：旧格式测试证据 TSV 若存在，unit/integration/health 命令自己重跑
+#
+# Gate integrity: scripts/MANIFEST.sha256 中锁定的全部脚本（gate-lock.sh FILES 列表）必须
+# 与当前哈希一致，任一不匹配即拒绝（证据不可信）。改动后重跑 gate-lock.sh。
+set -euo pipefail
+
+CWD="."
+SPEC=""
+ROOT_ARG=""
+RERUN_SCRIPT=""
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --cwd) CWD="${2:-}"; shift 2 ;;
+    --spec) SPEC="${2:-}"; shift 2 ;;
+    --root) ROOT_ARG="${2:-}"; shift 2 ;;
+    --rerun) RERUN_SCRIPT="${2:-}"; shift 2 ;;
+    -h|--help) sed -n '2,15p' "$0" | sed 's/^# \{0,1\}//'; exit 0 ;;
+    *) echo "verify: unknown arg $1" >&2; exit 2 ;;
+  esac
+done
+
+[[ -n "$SPEC" ]] || { echo "verify: --spec required" >&2; exit 2; }
+[[ "$SPEC" =~ ^[A-Za-z0-9][A-Za-z0-9_-]*$ ]] || { echo "verify: --spec 非法（仅允许字母数字下划线连字符，拒绝路径穿越）" >&2; exit 2; }
+
+find_root() {
+  local d
+  d="$(cd "$1" && pwd)"
+  while true; do
+    if [[ -f "$d/AGENTS.md" || -d "$d/.sdd" || -d "$d/docs" ]]; then
+      printf '%s\n' "$d"; return
+    fi
+    local parent; parent="$(dirname "$d")"
+    [[ "$parent" == "$d" ]] && break
+    d="$parent"
+  done
+  cd "$1" && pwd
+}
+
+trim() { local s="$1"; s="${s#"${s%%[![:space:]]*}"}"; s="${s%"${s##*[![:space:]]}"}"; printf '%s' "$s"; }
+
+sha256_of() {
+  local f="$1"
+  if command -v sha256sum >/dev/null 2>&1; then sha256sum "$f" | awk '{print $1}'
+  elif command -v shasum >/dev/null 2>&1; then shasum -a 256 "$f" | awk '{print $1}'
+  else echo "verify: no sha256sum/shasum available" >&2; exit 2; fi
+}
+
+ROOT="${ROOT_ARG:-$(find_root "$CWD")}"
+
+# ---- gate integrity（校验面 = MANIFEST 全条目，不只是子集）--------------------------
+GATES_DIR="$(cd "$(dirname "$0")" && pwd)"
+MANIFEST="$GATES_DIR/MANIFEST.sha256"
+if [[ -f "$MANIFEST" ]]; then
+  nlocked="$(grep -vcE '^#|^$' "$MANIFEST" || true)"
+  if [[ "${nlocked:-0}" -lt 1 ]]; then
+    echo "verify FAIL: MANIFEST.sha256 为空（完整性基线缺失）——重跑 gate-lock.sh 再验收" >&2
+    exit 1
+  fi
+  while read -r want f; do
+    [[ -z "$want" || "$f" == \#* ]] && continue
+    [[ -f "$GATES_DIR/$f" ]] || { echo "verify FAIL: locked file $f missing" >&2; exit 1; }
+    got="$(sha256_of "$GATES_DIR/$f")"
+    if [[ "$got" != "$want" ]]; then
+      echo "verify FAIL: gate script $f modified since lock — evidence untrustworthy (rerun gate-lock.sh after legitimate edits)" >&2
+      exit 1
+    fi
+  done < "$MANIFEST"
+else
+  echo "verify FAIL: MANIFEST.sha256 缺失（完整性基线不存在）——先跑 gate-lock.sh" >&2
+  exit 1
+fi
+
+# ---- 存量功能落点映射 + 机械数数 -------------------------------------------
+COVER_TSV="$ROOT/.sdd/acceptance/$SPEC/coverage.tsv"
+[[ -f "$COVER_TSV" ]] || { echo "verify FAIL: no coverage.tsv at $COVER_TSV (阶段 4 存量功能落点映射)" >&2; exit 1; }
+
+COVER_PY="$GATES_DIR/coverage_check.py"
+[[ -f "$COVER_PY" ]] || { echo "verify FAIL: coverage_check.py missing next to verify.sh" >&2; exit 1; }
+if ! python3 "$COVER_PY" "$ROOT" "$SPEC"; then
+  echo "verify FAIL: coverage_check.py failed (存量功能落点不完整)" >&2
+  exit 1
+fi
+
+# ---- 多视口真实渲染截图（1280 / 1440 / narrow 三视口；no-ui 豁免）-----------------
+NO_UI="$ROOT/.sdd/acceptance/$SPEC.no-ui"
+if [[ -f "$NO_UI" ]]; then
+  echo "verify: non-UI wish exempts screenshots (no-ui marker present)"
+else
+  SHOTS="$ROOT/.sdd/acceptance/$SPEC/shots"
+  [[ -d "$SHOTS" ]] || { echo "verify FAIL: no screenshots dir at $SHOTS (阶段 4 多视口截图；非 UI 愿望需 .no-ui 豁免文件)" >&2; exit 1; }
+  # 视口断言：每个前缀至少一张 PNG，且 PNG 实际像素宽度落在该视口的物理范围
+  # （1280-* ≥1200px / 1440-* ≥1366px / narrow-* ≤1000px，容差覆盖 retina 2x）；
+  # 同图三命名（复制一张 1280 图冒充三视口）必然在某前缀的宽度断言上失败。
+  png_width() {
+    python3 -c '
+import struct, sys
+try:
+    d = open(sys.argv[1], "rb").read(26)
+    if d[:8] != b"\x89PNG\r\n\x1a\n":
+        print(-1); sys.exit(0)
+    print(struct.unpack(">I", d[16:20])[0])
+except FileNotFoundError:
+    print(-2)
+' "$1"
+  }
+  missing=""
+  for v in 1280 1440 narrow; do
+    hits="$(find "$SHOTS" -maxdepth 1 -type f -iname "${v}-*.png" 2>/dev/null)"
+    if [[ -z "$hits" ]]; then
+      missing="$missing $v"; continue
+    fi
+    w="$(png_width "$(echo "$hits" | head -1)")"
+    case "$v" in
+      1280) ok_rule(){ [[ "$1" -ge 1200 ]]; } ;;
+      1440) ok_rule(){ [[ "$1" -ge 1366 ]]; } ;;
+      narrow) ok_rule(){ [[ "$1" -le 1000 ]]; } ;;
+    esac
+    if [[ "$w" == "-1" ]]; then
+      echo "verify FAIL: $v 视口截图不是有效 PNG（可用浏览器真实渲染导出 PNG；文件：$(echo "$hits" | head -1)）" >&2; exit 1
+    fi
+    if ! ok_rule "$w"; then
+      echo "verify FAIL: ${v}-* 截图宽度 $w px 不在 ${v} 视口物理范围（1280-*≥1200 / 1440-*≥1366 / narrow-*≤1000）——疑似复制图冒充多视口" >&2; exit 1
+    fi
+  done
+  if [[ -n "$missing" ]]; then
+    echo "verify FAIL: shots/ 缺少视口截图，文件名须以前缀标记视口：$missing（1280-* / 1440-* / narrow-* 各 ≥1 张 PNG，如 1280-home.png、1440-home.png、narrow-home.png；非 UI 愿望用 .no-ui 豁免）" >&2
+    exit 1
+  fi
+fi
+
+# ---- old-format evidence tsv：不再自动执行 cmd 列（v3 对抗修复）---------------
+# 旧格式 .sdd/acceptance/<id>.tsv 的 cmd 列曾是 `bash -c` 任意执行面（红队 S4e：证据→代码执行）。
+# 现默认不执行：仅统计存在并提示；需要 live 重跑请显式 `--rerun <script>`（白名单脚本名）。
+OLD_EVID="$ROOT/.sdd/acceptance/$SPEC.tsv"
+live="no"
+if [[ -f "$OLD_EVID" ]]; then
+  live="yes"
+  echo "verify: 旧格式证据 tsv 发现于 $OLD_EVID（v3 起 cmd 列不再自动执行；live 重跑需显式 --rerun <script>）"
+  if [[ -n "${RERUN_SCRIPT:-}" ]]; then
+    if [[ ! -f "$ROOT/$RERUN_SCRIPT" ]]; then
+      echo "verify FAIL: --rerun 脚本不存在: $ROOT/$RERUN_SCRIPT" >&2; exit 1
+    fi
+    log="$ROOT/.sdd/acceptance/$SPEC/rerun/$RERUN_SCRIPT.log"
+    mkdir -p "$(dirname "$log")"
+    set +e
+    ( cd "$ROOT" && timeout "${RERUN_TIMEOUT:-180}" bash "$RERUN_SCRIPT" ) >"$log" 2>&1
+    rc=$?
+    set -e
+    if [[ $rc -ne 0 ]]; then
+      echo "verify FAIL: --rerun $RERUN_SCRIPT exited $rc (log $log)" >&2; exit 1
+    fi
+    echo "verify: --rerun $RERUN_SCRIPT ok (exit 0, log $log)"
+  fi
+fi
+
+echo "verify OK: coverage=pass shots=$(if [[ -f "$NO_UI" ]]; then echo exempt; else find "$SHOTS" -maxdepth 1 -type f \( -iname '*.png' -o -iname '*.jpg' -o -iname '*.jpeg' -o -iname '*.webp' -o -iname '*.gif' \) | wc -l | tr -d ' '; fi) live_rerun=$live"
+exit 0

package/presets/code-vibe/skills/wish-programming/scripts/verify_preset_budgets.py

@@ -0,0 +1,218 @@
+#!/usr/bin/env python3
+"""verify_preset_budgets.py — 预设内容预算 × skill 引用完整性门禁。
+
+检查（全部可负对照验证）：
+1. persona prefix ≤ 3000 字符（解析 bundle 根目录的 `code-vibe.patch.yml` 或旧目录的 `agent.cordis.yml`）
+2. 每个 skills/*/SKILL.md ≤ 200 行
+3. 每个 SKILL.md 的 description：> 540 字符 ERROR / > 300 WARN（DSH catalogDescriptionMaxLength=300
+   渲染截断点——截断后触发契约必须在前 300 字符，故 WARN 提醒；540 是脚本自定义的绝对上限）
+4. skill 引用完整性（persona 文本 + 全部 SKILL.md 全文）：
+   a. 反引号 token：`` `xxx-yyy` `` 短横线连写（技能名判别特征：catalog 13 名全部含 `-`，
+      而命令/路径/变量类反引号词如 `journey.sh`/`--assert`/`vN` 天然不满足）→ 必须命中 catalog；
+   b. 字面互引：`../<name>/SKILL.md` → <name> 必须在 catalog；
+   c. 跨 skill 路径：`../<name>/references/…` 等 → <name> 必须在 catalog，且跟随的
+      references/scripts 子路径必须真实存在于 skills/<name>/ 下；
+   d. 措辞引用（兼容旧版）：`load the X skill` / `X skill` / `X/SKILL.md` 格式 → X 必须在 catalog。
+   全部不满足 → exit 1（TEST 负向：把 persona/SKILL.md 里技能名改错、删 references 目录必须被拒）。
+
+用法：python3 verify_preset_budgets.py [preset_root]（默认从脚本位置解析包内 code-vibe）
+      python3 verify_preset_budgets.py --help
+Exit: 0 ok, 1 违例, 2 usage.
+超限时按 relocate → condense → raise 处理：先删/移内容，仍不够才 raise（raise 须用户确认并记录于对应 Issue 或 pull request）。
+"""
+import re
+import sys
+from pathlib import Path
+
+PERSONA_LIMIT = 3000
+SKILL_LINES_LIMIT = 200
+DESC_LIMIT = 540        # 绝对上限（>540 ERROR）
+DESC_WARN = 300         # DSH catalog 渲染截断点（>300 WARN）
+
+# 预设自有流程词（journey 状态机 / delivery target / 豁免标记等）：反引号内出现但非技能名。
+# 新增流程词必须在此登记（对应 MAINTENANCE 规则），否则会被 4a 误报。
+FLOW_WORDS = {
+    "acceptance-passed", "blocked", "stuck", "idle", "claim-deliver",
+    "code-ready", "dev-effective", "production-delivered", "no-ui",
+}
+
+USAGE = """verify_preset_budgets.py — 预设预算 × skill 引用完整性门禁
+用法：python3 verify_preset_budgets.py [preset_root]（默认从脚本位置解析包内 code-vibe）
+      python3 verify_preset_budgets.py --help
+检查：persona ≤3000 字符；SKILL.md ≤200 行；description ≤540（>300 WARN）；
+      反引号技能名 / ../<name>/SKILL.md 互引 / ../<name>/references 路径 / 措辞引用 全部必须命中 catalog。
+Exit: 0 ok, 1 违例, 2 usage."""
+
+
+def parse_persona_prefix(agent_yml: Path):
+    """提取 `prefix: |-` 块文本；无则返回 ''。"""
+    if not agent_yml.is_file():
+        return ""
+    text = agent_yml.read_text(encoding="utf-8")
+    m = re.search(r"prefix:\s*\|-([ \t]*\n)?", text)
+    if not m:
+        return ""
+    start = m.end()
+    lines = text[start:].split("\n")
+    body = []
+    indent = None
+    for line in lines:
+        if not line.strip():
+            body.append("")
+            continue
+        lead = len(line) - len(line.lstrip(" "))
+        if indent is None:
+            indent = lead
+        if line.startswith("- id:") and lead <= (indent or 0):
+            break
+        if lead >= (indent or 0):
+            body.append(line[indent:])
+        else:
+            break
+    return "\n".join(body)
+
+
+def skill_names(root: Path):
+    return {p.name for p in root.iterdir() if (p / "SKILL.md").is_file()}
+
+
+def check_references_in_text(text: str, name: str, skills_dir: Path, catalog: set, errs: list, ctx: str):
+    """引用检查 d：`../…` 相对路径引用必须真实可解析。
+
+    从 SKILL.md（skills/<name>/SKILL.md）出发：
+    - 首段命中 catalog 且带子路径 → 跨 skill 引用：skills/<target>/<rest> 必须存在；
+    - 首段未命中 catalog → 同 skill 引用（写作 `../x.md` 意图是 skills/<name>/x.md…，
+      但 `..` 实际解析到 skills/ 根，故按「skills/<name>/<完整路径>」与「skills/<完整路径>」
+      两处存在性判定，均不存在则为断裂引用（如 ../critique-format.md）。
+    """
+    ref_re = re.compile(r"\.\./([^\s\\)\]`,，。；:+]+)")
+    for m in ref_re.finditer(text):
+        path = m.group(1)
+        segs = path.split("/")
+        head = segs[0]
+        head_m = re.fullmatch(r"[a-z][a-z0-9-]*", head)
+        if head_m and head in catalog:
+            rest = "/".join(segs[1:])
+            cand = (skills_dir / head / rest).resolve() if rest else skills_dir / head
+            if not cand.exists():
+                errs.append(f"{ctx}: 跨 skill 引用 ../{path} 不存在（skills/{head}/ 下无此路径）")
+        else:
+            # 同 skill 内部引用：先按写作意图（skills/<name>/…），再按字面（skills/…）
+            cand1 = skills_dir / name / path
+            cand2 = skills_dir / path
+            if not cand1.exists() and not cand2.exists():
+                errs.append(f"{ctx}: ../{path} 断裂——skills/{name}/{path} 与 skills/{path} 均不存在")
+
+
+def default_preset_root():
+    """Return the packaged code-vibe asset root from this script's location."""
+    return Path(__file__).resolve().parents[3]
+
+
+def main():
+    if len(sys.argv) > 1 and sys.argv[1] in ("-h", "--help"):
+        print(USAGE)
+        return 0
+    preset_root = Path(sys.argv[1]).resolve() if len(sys.argv) > 1 else default_preset_root()
+    skills_dir = preset_root / "skills"
+    if not skills_dir.is_dir():
+        print(f"verify_preset_budgets: no skills dir at {skills_dir}", file=sys.stderr)
+        return 2
+
+    errs = []
+    warns = []
+
+    # 1. persona prefix 字符数。0.2 bundle patch 优先，旧目录格式仅作显式路径兼容。
+    agent_yml = preset_root.parent / "code-vibe.patch.yml"
+    if not agent_yml.is_file():
+        agent_yml = preset_root / "agent.cordis.yml"
+    persona = parse_persona_prefix(agent_yml)
+    if persona:
+        if len(persona) > PERSONA_LIMIT:
+            errs.append(f"persona prefix {len(persona)} chars > {PERSONA_LIMIT}（relocate→condense→raise：先删重复与指针化，仍超再 raise）")
+        else:
+            print(f"persona prefix: {len(persona)} chars (≤{PERSONA_LIMIT})")
+    else:
+        warns.append(f"{agent_yml.name} 未找到 persona prefix 块（跳过该项）")
+
+    catalog = skill_names(skills_dir)
+    print(f"catalog: {len(catalog)} skills — {', '.join(sorted(catalog))}")
+
+    # 4a-0. FLOW_WORDS 防滥用：豁免表登记了 catalog 内的技能名 = 试图绕过引用检查 → ERROR
+    flow_conflicts = sorted(FLOW_WORDS & catalog)
+    if flow_conflicts:
+        for t in flow_conflicts:
+            errs.append(f"FLOW_WORDS 登记了 catalog 内的技能名: {t}（禁止把技能名加入豁免表——引用检查必须生效）")
+
+    # 2-3. 每个 SKILL.md 行数与 description 长度
+    sk_texts = {}
+    for name in sorted(catalog):
+        sk = skills_dir / name / "SKILL.md"
+        sk_texts[name] = sk.read_text(encoding="utf-8")
+        lines = sk_texts[name].splitlines()
+        if len(lines) > SKILL_LINES_LIMIT:
+            errs.append(f"{name}/SKILL.md {len(lines)} lines > {SKILL_LINES_LIMIT}")
+        dline = next((l for l in lines if l.startswith("description: ")), None)
+        m = re.match(r"^description: (.*)$", dline) if dline else None
+        if m:
+            desc = m.group(1).strip().strip('"')
+            if len(desc) > DESC_LIMIT:
+                errs.append(f"{name} description {len(desc)} chars > {DESC_LIMIT}")
+            elif len(desc) > DESC_WARN:
+                warns.append(f"{name} description {len(desc)} chars > {DESC_WARN}（catalog 渲染截断点；触发契约主体在前 300 字符即可）")
+
+    # 4a. 反引号短横线 token（persona + 全部 SKILL.md）：技能名判别特征 = 字母开头 + 含至少一个 `-`
+    backtick_re = re.compile(r"`([a-z][a-z0-9-]*-[a-z0-9][a-z0-9-]*)`")
+    for ctx, text in [("persona", persona)] + [(f"{n}/SKILL.md", t) for n, t in sk_texts.items()]:
+        for m in backtick_re.finditer(text):
+            target = m.group(1)
+            if target not in catalog and target not in FLOW_WORDS:
+                errs.append(f"{ctx} 反引号技能名不在 catalog: `{target}`（引用即失效——修复须与 catalog 一致，或登记进 FLOW_WORDS）")
+
+    # 4b. 字面互引 ../<name>/SKILL.md
+    inter_ref = re.compile(r"\.\./([A-Za-z0-9-]+)/SKILL\.md")
+    for name in sorted(catalog):
+        for m in inter_ref.finditer(sk_texts[name]):
+            target = m.group(1)
+            if target not in catalog:
+                errs.append(f"{name}/SKILL.md 互引指向不存在的 skill: ../{target}/SKILL.md")
+
+    # 4c. 措辞引用（兼容旧版）：`load the X skill` / `X skill`（X/SKILL.md 无 .. 前缀的裸引用）
+    name_re = re.compile(r"(?:load(?:ing)?\s+the\s+|skill\s*[:：]?\s*)([a-z][a-z0-9-]+)\s+skill")
+    bare_ref = re.compile(r"(?<![.\w])/([a-z][a-z0-9-]+)/SKILL\.md")
+    for ctx, text in [("persona", persona)] + [(f"{n}/SKILL.md", t) for n, t in sk_texts.items()]:
+        for m in name_re.finditer(text):
+            target = m.group(1)
+            if target not in catalog:
+                errs.append(f"{ctx} 点名的 skill 不在 catalog: {target}")
+        for m in bare_ref.finditer(text):
+            target = m.group(1)
+            if target not in catalog:
+                errs.append(f"{ctx} 互引指向不存在的 skill: /{target}/SKILL.md")
+
+    # 4d. 跨 skill 路径存在性（references/scripts 等）
+    for name in sorted(catalog):
+        check_references_in_text(sk_texts[name], name, skills_dir, catalog, errs, f"{name}/SKILL.md")
+
+    # 4e. 同 skill 内部路径引用（references/scripts/templates/roles 前缀，反引号或链接目标）存在性
+    local_re = re.compile(r"`((?:references|scripts|templates|roles)/[^`\s]+)`|\(((?:references|scripts|templates|roles)/[^)\s]+)\)")
+    for name in sorted(catalog):
+        for m in local_re.finditer(sk_texts[name]):
+            p = (m.group(1) or m.group(2)).split("#")[0]  # 去掉 # 锚点片段
+            cand = skills_dir / name / p
+            if not cand.exists():
+                errs.append(f"{name}/SKILL.md 引用缺失: {p}（skills/{name}/ 下不存在）")
+
+    for w in warns:
+        print(f"WARN: {w}", file=sys.stderr)
+    if errs:
+        for e in errs:
+            print(f"ERROR: {e}", file=sys.stderr)
+        print(f"verify_preset_budgets FAIL: {len(errs)} violation(s)", file=sys.stderr)
+        return 1
+    print("verify_preset_budgets OK")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/presets/code-vibe/skills/wish-programming/scripts/wish.sh

@@ -0,0 +1,150 @@
+#!/usr/bin/env bash
+# wish.sh — manage wishes: add to the demand pool, then start one into docs/wish/<id>/.
+#
+# Usage:
+#   wish.sh --cwd <workspace> --new --title "<标题>" [--quote "<用户原话>"]
+#                                       # append to demand pool + create quote.md (原话最高优先级工件)
+#   wish.sh --cwd <workspace> --start <id>             # create docs/wish/<id>/{contract.md,plan.md}
+#
+# `--start` also flips the pool row's status new -> active (best effort).
+set -euo pipefail
+
+CWD="."; ACTION=""; WISH=""; TITLE=""; QUOTE=""; ROOT_ARG=""
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --cwd) CWD="${2:-}"; shift 2 ;;
+    --root) ROOT_ARG="${2:-}"; shift 2 ;;
+    --new) ACTION=new; shift ;;
+    --start) ACTION=start; WISH="${2:-}"; shift 2 ;;
+    --title) TITLE="${2:-}"; shift 2 ;;
+    --quote) QUOTE="${2:-}"; shift 2 ;;
+    -h|--help) sed -n '2,10p' "$0" | sed 's/^# \{0,1\}//'; exit 0 ;;
+    *) echo "wish: unknown arg $1" >&2; exit 2 ;;
+  esac
+done
+
+[[ -n "$ACTION" ]] || { echo "wish: need --new or --start" >&2; exit 2; }
+
+find_root() {
+  local d
+  d="$(cd "$1" && pwd)"
+  while true; do
+    if [[ -f "$d/AGENTS.md" || -d "$d/.sdd" || -d "$d/docs" ]]; then
+      printf '%s\n' "$d"; return
+    fi
+    local parent; parent="$(dirname "$d")"
+    [[ "$parent" == "$d" ]] && break
+    d="$parent"
+  done
+  cd "$1" && pwd
+}
+
+ROOT="${ROOT_ARG:-$(find_root "$CWD")}"
+POOL="$ROOT/docs/product/demand-pool.md"
+DOC="$ROOT/docs/wish"
+
+emit() {  # emit <path> <<EOF ... EOF
+  local f="$1"
+  if [[ -f "$f" ]]; then echo "wish: keep $f (exists)"; return; fi
+  cat > "$f"
+  echo "wish: wrote $f"
+}
+
+if [[ "$ACTION" == "new" ]]; then
+  [[ -n "$TITLE" ]] || { echo "wish: --new needs --title" >&2; exit 2; }
+  if [[ "$TITLE" == *$'\n'* || "$TITLE" == *$'\r'* || "$TITLE" == *'|'* ]]; then
+    echo "wish: --title 含换行或管道符（需求池注入防护；标题须为单行文本）" >&2; exit 2
+  fi
+  if [[ -n "$QUOTE" && ( "$QUOTE" == *$'\n'* || "$QUOTE" == *$'\r'* ) ]]; then
+    QUOTE="$(printf '%s' "$QUOTE" | tr '\r\n' '  ')"
+    echo "wish: --quote 换行已压平为空格（原话应逐字转录，换行请直接编辑 quote.md）" >&2
+  fi
+  [[ -f "$POOL" ]] || { echo "wish: no demand pool at $POOL — run project.sh first" >&2; exit 1; }
+  last=$(grep -oE '^\| *W[0-9]+' "$POOL" | tail -1 | grep -oE '[0-9]+' || echo 0)
+  next=$(( ${last:-0} + 1 ))
+  printf '| W%d | %s | new | |\n' "$next" "$TITLE" >> "$POOL"
+  mkdir -p "$DOC/W$next"
+  if [[ -n "$QUOTE" ]]; then
+    printf '# 用户原话（最高优先级 · 逐字转录 · 不可改写）\n\n> quote 版本：v1\n\n%s\n\n> 记录：%s（原话正文一字不改；本节与任何下游转述冲突时以本节为准；quote 更新到 vN+1 时下游一并重新对齐）\n' \
+      "$QUOTE" "$(date -u +%Y-%m-%dT%H:%M:%SZ)" > "$DOC/W$next/quote.md"
+    echo "wish: wrote $DOC/W$next/quote.md (原话已落盘, quote v1)"
+  else
+    emit "$DOC/W$next/quote.md" <<'EOF'
+# 用户原话（最高优先级 · 逐字转录 · 不可改写）
+
+> quote 版本：v1
+
+<待补录：用户原话逐字原文（最高优先级工件，必须补录；check_spec 会拦截占位）>
+
+> 记录：（原话正文一字不改；本节与任何下游转述冲突时以本节为准；quote 更新到 vN+1 时下游一并重新对齐）
+EOF
+    echo "wish: quote.md 为占位 — 请逐字补录用户原话（最高优先级）"
+  fi
+  echo "wish: added W$next to $POOL"
+  echo "  next: wish.sh --cwd . --start W$next"
+  exit 0
+fi
+
+# start
+[[ -n "$WISH" ]] || { echo "wish: --start needs <id>" >&2; exit 2; }
+[[ "$WISH" =~ ^[A-Za-z0-9][A-Za-z0-9_-]*$ ]] || { echo "wish: --start 非法 id（仅允许字母数字下划线连字符，拒绝路径穿越）" >&2; exit 2; }
+mkdir -p "$DOC/$WISH"
+
+emit "$DOC/$WISH/contract.md" <<EOF
+# $WISH
+
+## 用户与主结果
+- 用户：
+- 主结果（可观察）：
+
+## MVP 边界
+- In：
+- Out：
+
+## 权威数据源
+- （真实数据 / API / 账号；示例数据必须标注 example）
+
+## 事实映射（仅 Verified 进 P0 / 实施阻断）
+| 入口 | actor | 实体/表关系 | 可信路径 | 代码调用点 | 越权反例 | 证据级 |
+|---|---|---|---|---|---|---|
+| | | | | | | Verified/Unverified |
+EOF
+
+emit "$DOC/$WISH/plan.md" <<EOF
+# $WISH
+
+## 纵向切片（一切片 = 一入口 + 成功/失败路径 + Oracle）
+| 切片 ID | 入口 | 完成定义（链 T-xxx） | 触及路径 | 依赖 | Oracle 强度 |
+|---|---|---|---|---|---|
+| S1 | | | | | unit/machine/browser |
+
+## Workspace
+- 模式：local | git-worktree
+- 分支：sdd/<id>
+
+## 单向门
+- 不可逆操作 / 批准人：
+EOF
+
+emit "$DOC/$WISH/review.md" <<EOF
+# $WISH — 代码评审
+
+> 由**非实现者**的独立 subagent 在 merge / Verify 前填写。
+
+## 结论
+- 结论：（待填：pass 或 fail）
+- 评审人：
+- 日期：
+
+## 问题清单
+- （无则写「无」）
+EOF
+
+if [[ -f "$POOL" ]]; then
+  sed -i -E "s/^(\| *$WISH *\| [^|]*\|) new( *\|)/\1 active\2/" "$POOL" 2>/dev/null || true
+fi
+# NOTE: phase stays idle — design-ready must be reached through the GATED transition
+# (journey.sh --transition design-ready: requires .confirmed artifact + check_spec --phase design).
+# Never --set here: it is the human recovery hatch and would bypass every gate.
+echo "wish: started $WISH -> $DOC/$WISH (phase idle; design-ready via gated journey transition)"