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

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

@@ -0,0 +1,281 @@
+#!/usr/bin/env bash
+# Wish journey state machine — 简化状态机（v2 五阶段）。
+#
+# State file: <workspace>/.sdd/journey/<spec>.env
+#
+# Usage:
+#   journey.sh --cwd <workspace> --spec <id> --status
+#   journey.sh --cwd <workspace> --spec <id> --list-phases
+#   journey.sh --cwd <workspace> --spec <id> --set <phase>            # human recovery only
+#   journey.sh --cwd <workspace> --spec <id> --transition <phase> [--reason "<why>"]
+#   journey.sh --cwd <workspace> --spec <id> --confirm --by <who>    # 需求理解确认工件（人①）
+#   journey.sh --cwd <workspace> --spec <id> --approve --by <who>    # 用户 judge 验收标记（人②）
+#   journey.sh --cwd <workspace> --spec <id> --assert write|build|lint|typecheck|deploy|claim-deliver
+#   journey.sh --cwd <workspace> --spec <id> --assert lint|typecheck [--dir <dir>]  # v2: per-slice quality gate
+#   journey.sh --cwd <workspace> --spec <id> --confirm --by <who> [--channel interactive|cli]
+#   journey.sh --cwd <workspace> --spec <id> --confirm --by <who> [--no-ui]  # 非 UI 愿望：声明豁免多视口截图
+#   journey.sh --cwd <workspace> --spec <id> [--root <dir>]  # 显式指定项目根（防 find_root 漂移）
+#
+# Gates (no --force; --set is the human recovery hatch):
+#   - acceptance-passed requires the human approval marker (--approve) AND
+#     check_spec.py --phase close exit 0 (回填: handoff + 决策/债落库)
+#   - blocked / stuck require --reason and are terminal except human --set
+set -euo pipefail
+
+CWD="."
+SPEC=""
+ACTION=""
+TARGET=""
+REASON=""
+APPROVER=""
+CHANNEL="cli"
+ASSERT_DIR=""
+ROOT_ARG=""
+NO_UI_FLAG=0
+
+usage() { sed -n '2,20p' "$0" | sed 's/^# \{0,1\}//'; }
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --cwd) CWD="${2:-}"; shift 2 ;;
+    --spec) SPEC="${2:-}"; shift 2 ;;
+    --status) ACTION=status; shift ;;
+    --list-phases) ACTION=list; shift ;;
+    --set) ACTION=set; TARGET="${2:-}"; shift 2 ;;
+    --transition) ACTION=transition; TARGET="${2:-}"; shift 2 ;;
+    --approve) ACTION=approve; shift ;;
+    --confirm) ACTION=confirm; shift ;;
+    --by) APPROVER="${2:-}"; shift 2 ;;
+    --channel) CHANNEL="${2:-}"; shift 2 ;;
+    --dir) ASSERT_DIR="${2:-}"; shift 2 ;;
+    --root) ROOT_ARG="${2:-}"; shift 2 ;;
+    --no-ui) NO_UI_FLAG=1; shift ;;
+    --reason) REASON="${2:-}"; shift 2 ;;
+    --assert) ACTION=assert; TARGET="${2:-}"; shift 2 ;;
+    -h|--help) usage; exit 0 ;;
+    *) echo "journey: unknown arg $1" >&2; exit 2 ;;
+  esac
+done
+
+[[ -n "$SPEC" ]] || { echo "journey: --spec required" >&2; exit 2; }
+[[ "$SPEC" =~ ^[A-Za-z0-9][A-Za-z0-9_-]*$ ]] || { echo "journey: --spec 非法（仅允许字母数字下划线连字符，拒绝路径穿越）" >&2; exit 2; }
+[[ -n "$ACTION" ]] || { echo "journey: need --status|--set|--transition|--approve|--confirm|--assert|--list-phases" >&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")}"
+DIR="$ROOT/.sdd/journey"
+FILE="$DIR/${SPEC}.env"
+APPROVAL="$ROOT/.sdd/acceptance/${SPEC}.approved"
+CONFIRMED="$ROOT/.sdd/acceptance/${SPEC}.confirmed"
+mkdir -p "$DIR"
+
+PHASES=(idle acceptance-passed blocked stuck)
+
+is_phase() { local p="$1" x; for x in "${PHASES[@]}"; do [[ "$x" == "$p" ]] && return 0; done; return 1; }
+
+can_transition() {
+  local from="$1" to="$2"
+  case "${from}__${to}" in
+    idle__acceptance-passed|idle__blocked|idle__stuck) return 0 ;;
+    acceptance-passed__blocked|acceptance-passed__stuck) return 0 ;;
+    *) return 1 ;;
+  esac
+}
+
+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 "journey: no sha256sum/shasum available" >&2; exit 2; fi
+}
+
+# ---- 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 "journey: MANIFEST.sha256 为空（完整性基线缺失）——重跑 gate-lock.sh" >&2
+    exit 1
+  fi
+  while read -r want f; do
+    [[ -z "$want" || "$f" == \#* ]] && continue
+    [[ -f "$GATES_DIR/$f" ]] || { echo "journey: locked file $f missing" >&2; exit 1; }
+    got="$(sha256_of "$GATES_DIR/$f")"
+    if [[ "$got" != "$want" ]]; then
+      echo "journey: gate script $f modified since lock — state machine integrity compromised (rerun gate-lock.sh)" >&2
+      exit 1
+    fi
+  done < "$MANIFEST"
+else
+  echo "journey: MANIFEST.sha256 缺失（完整性基线不存在）——先跑 gate-lock.sh" >&2
+  exit 1
+fi
+
+load() {
+  PHASE=idle; UPDATED_AT=""; LAST_REASON=""
+  if [[ -f "$FILE" ]]; then
+    p="$(grep -E '^PHASE=' "$FILE" 2>/dev/null | tail -1 | sed 's/^PHASE=//' | tr -d '\r')" || p=""
+    [[ -n "$p" ]] && PHASE="$p"
+    UPDATED_AT="$(grep -E '^UPDATED_AT=' "$FILE" 2>/dev/null | tail -1 | sed 's/^UPDATED_AT=//' | tr -d '\r')" || UPDATED_AT=""
+    LAST_REASON="$(grep -E '^LAST_REASON=' "$FILE" 2>/dev/null | tail -1 | sed 's/^LAST_REASON=//' | tr -d '\r')" || LAST_REASON=""
+  fi
+  PHASE="${PHASE:-idle}"
+}
+
+save() {
+  {
+    echo "PHASE=$PHASE"
+    echo "SPEC_ID=$SPEC"
+    [[ -n "${LAST_REASON:-}" ]] && echo "LAST_REASON=$LAST_REASON"
+    echo "UPDATED_AT=$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+  } > "$FILE"
+}
+
+need_reason() {
+  [[ -n "$REASON" ]] || { echo "journey: --reason required for -> $1" >&2; exit 2; }
+}
+
+gate_enter_acceptance_passed() {
+  local py="$GATES_DIR/check_spec.py"
+  if [[ ! -f "$py" ]]; then
+    echo "journey: cannot gate -> acceptance-passed: check_spec.py missing" >&2; exit 1
+  fi
+  if ! python3 "$py" "$ROOT" "$SPEC" --phase close >/dev/null 2>&1; then
+    echo "journey: -> acceptance-passed refused: check_spec.py --phase close failed (回填: handoff 含 wish id + 决策/债落库)" >&2
+    exit 1
+  fi
+  # v2 前置链②：机械验收证据（覆盖/截图/回放）——verify.sh；
+  #   acceptance 目录不存在且无 no-ui 豁免 → 拒绝（机械验收缺失）
+  local vsh="$GATES_DIR/verify.sh"
+  if [[ -f "$vsh" ]]; then
+    if [[ -d "$ROOT/.sdd/acceptance/$SPEC" || -f "$ROOT/.sdd/acceptance/$SPEC.no-ui" ]]; then
+      if ! bash "$vsh" --cwd "$ROOT" --spec "$SPEC" >/dev/null 2>&1; then
+        echo "journey: -> acceptance-passed refused: verify.sh FAIL（快照/覆盖/多视口截图证据不完整）" >&2
+        exit 1
+      fi
+    else
+      echo "journey: -> acceptance-passed refused: 无机械验收证据（.sdd/acceptance/$SPEC/ 或 .no-ui 豁免均缺失——先完成阶段 4）" >&2
+      exit 1
+    fi
+  fi
+  # v2 前置链③：组件白名单合规（设计类 wish）——check_whitelist.py
+  local wl="$GATES_DIR/check_whitelist.py"
+  if [[ -f "$wl" && -f "$ROOT/docs/wish/$SPEC/design-spec.md" ]]; then
+    if ! python3 "$wl" "$ROOT" "$SPEC" >/dev/null 2>&1; then
+      echo "journey: -> acceptance-passed refused: check_whitelist FAIL（实现用了白名单外组件；禁发明，须用户拍板补白名单）" >&2
+      exit 1
+    fi
+  fi
+  # v2 前置链④：per-slice lint（若 workspace 有 lint 脚本）
+  if [[ -f "$ROOT/package.json" ]] && grep -q '"lint"' "$ROOT/package.json"; then
+    if ! (cd "$ROOT" && npm run lint --silent) >/dev/null 2>&1; then
+      echo "journey: -> acceptance-passed refused: lint FAIL" >&2
+      exit 1
+    fi
+  fi
+}
+
+load
+
+case "$ACTION" in
+  list) printf '%s\n' "${PHASES[@]}"; exit 0 ;;
+  status)
+    echo "journey: spec=$SPEC phase=$PHASE file=$FILE updated_at=${UPDATED_AT:-}${LAST_REASON:+ last_reason=$LAST_REASON}"
+    exit 0 ;;
+  set)
+    is_phase "$TARGET" || { echo "journey: invalid phase $TARGET" >&2; exit 2; }
+    PHASE="$TARGET"; save; echo "journey: set $PHASE ($FILE) — human recovery"; exit 0 ;;
+  confirm)
+    case "$PHASE" in
+      idle|acceptance-passed) ;;
+      *) echo "journey: --confirm only from idle/acceptance-passed (phase=$PHASE)" >&2; exit 1 ;;
+    esac
+    [[ -n "$APPROVER" ]] || { echo "journey: --confirm needs --by <who>" >&2; exit 2; }
+    mkdir -p "$(dirname "$CONFIRMED")"
+    printf 'by=%s\nts=%s\nphase=%s\nchannel=%s\n' "$APPROVER" "$(date -u +%Y-%m-%dT%H:%M:%SZ)" "$PHASE" "$CHANNEL" > "$CONFIRMED"
+    # 原话指纹（v3 对抗修复）：确认时锁定 quote.md sha256，check_spec 凭此发现内容篡改
+    QMD="$ROOT/docs/wish/$SPEC/quote.md"
+    if [[ -f "$QMD" ]]; then
+      printf 'sha256=%s\nts=%s\nby=%s\n' "$(sha256_of "$QMD")" "$(date -u +%Y-%m-%dT%H:%M:%SZ)" "$APPROVER" > "$ROOT/.sdd/acceptance/$SPEC.quote-hash"
+      echo "journey: quote fingerprint locked ($ROOT/.sdd/acceptance/$SPEC.quote-hash)"
+    fi
+    if [[ "$NO_UI_FLAG" == "1" ]]; then
+      printf 'by=%s\nts=%s\nreason=non-UI wish\n' "$APPROVER" "$(date -u +%Y-%m-%dT%H:%M:%SZ)" > "$ROOT/.sdd/acceptance/$SPEC.no-ui"
+      echo "journey: non-UI exemption recorded ($ROOT/.sdd/acceptance/$SPEC.no-ui)"
+    fi
+    echo "journey: understanding confirmed by $APPROVER (channel=$CHANNEL) -> $CONFIRMED"
+    exit 0 ;;
+  approve)
+    case "$PHASE" in
+      idle|acceptance-passed) ;;
+      *) echo "journey: --approve only from idle/acceptance-passed (phase=$PHASE)" >&2; exit 1 ;;
+    esac
+    [[ -n "$APPROVER" ]] || { echo "journey: --approve needs --by <who>" >&2; exit 2; }
+    mkdir -p "$(dirname "$APPROVAL")"
+    printf 'by=%s\nts=%s\nphase=%s\nchannel=%s\n' "$APPROVER" "$(date -u +%Y-%m-%dT%H:%M:%SZ)" "$PHASE" "$CHANNEL" > "$APPROVAL"
+    echo "journey: human approval recorded by $APPROVER (channel=$CHANNEL) -> $APPROVAL"
+    exit 0 ;;
+  transition)
+    is_phase "$TARGET" || { echo "journey: invalid phase $TARGET" >&2; exit 2; }
+    FROM="$PHASE"
+    if ! can_transition "$FROM" "$TARGET"; then
+      echo "journey: illegal transition $FROM -> $TARGET (--set is the human recovery hatch)" >&2
+      exit 1
+    fi
+    case "$TARGET" in
+      acceptance-passed)
+        [[ -f "$APPROVAL" ]] || { echo "journey: -> acceptance-passed refused: no human approval (journey.sh --approve --by <who>)" >&2; exit 1; }
+        gate_enter_acceptance_passed ;;
+      blocked|stuck)
+        need_reason "$TARGET"
+        ;;
+    esac
+    LAST_REASON="${REASON:-}"
+    PHASE="$TARGET"; save
+    printf 'journey: %s -> %s' "$FROM" "$TARGET"
+    [[ -n "${REASON:-}" ]] && printf ' (%s)' "$REASON"
+    printf '\n'
+    exit 0 ;;
+  assert)
+    case "$TARGET" in
+      write|build)
+        if [[ "$PHASE" == "idle" ]]; then
+          echo "journey: assert $TARGET ok (phase=$PHASE)"; exit 0
+        fi
+        echo "journey: assert $TARGET FAIL (phase=$PHASE; need idle)" >&2; exit 1 ;;
+      deploy)
+        echo "journey: assert deploy FAIL (deploy requires explicit human authorization this turn)" >&2; exit 1 ;;
+      lint|typecheck)
+        d="${ASSERT_DIR:-$ROOT}"
+        if [[ -f "$d/package.json" ]] && grep -q "\"$TARGET\"" "$d/package.json"; then
+          if (cd "$d" && npm run "$TARGET" --silent) >/dev/null 2>&1; then
+            echo "journey: assert $TARGET ok ($d)"; exit 0
+          else
+            echo "journey: assert $TARGET FAIL ($d) — 修好再交付，不要 push 后指望别处不同" >&2; exit 1
+          fi
+        else
+          echo "journey: assert $TARGET ok (no $TARGET script in $d/package.json)"
+          exit 0
+        fi ;;
+      claim-deliver)
+        if [[ "$PHASE" == "acceptance-passed" ]]; then
+          echo "journey: assert claim-deliver ok"; exit 0
+        fi
+        echo "journey: assert claim-deliver FAIL (phase=$PHASE)" >&2; exit 1 ;;
+      *) echo "journey: unknown assert $TARGET" >&2; exit 2 ;;
+    esac ;;
+esac

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

@@ -0,0 +1,152 @@
+#!/usr/bin/env bash
+# project.sh — scaffold a project's product layer + wish root (once per NEW project).
+#
+# Usage:
+#   project.sh --cwd <workspace> [--force]
+#
+# Creates (never overwrites):
+#   docs/product/{PRODUCT.md, demand-pool.md, gap-register.md, gap-closed.md, decisions/}
+#   docs/wish/
+#
+# Guard: refuses to init when an existing project is detected (AGENTS.md + docs/ both present);
+# use --force to override. Existing projects attach read-only to their own docs system.
+set -euo pipefail
+
+CWD="."
+FORCE=0
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --cwd) CWD="${2:-}"; shift 2 ;;
+    --force) FORCE=1; shift ;;
+    -h|--help) sed -n '2,13p' "$0" | sed 's/^# \{0,1\}//'; exit 0 ;;
+    *) echo "project: unknown arg $1" >&2; exit 2 ;;
+  esac
+done
+
+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="$(find_root "$CWD")"
+
+# ---- existing-project guard (greenfield init only) --------------------------
+if [[ -f "$ROOT/AGENTS.md" && -d "$ROOT/docs" ]]; then
+  if [[ "$FORCE" != "1" ]]; then
+    echo "project: existing project detected (AGENTS.md + docs/ present) — refuse greenfield init" >&2
+    echo "project: attach read-only to the existing docs system instead; rerun with --force to override" >&2
+    exit 1
+  fi
+  echo "project: existing project detected, --force given — proceeding"
+fi
+
+PROD="$ROOT/docs/product"
+WISH="$ROOT/docs/wish"
+mkdir -p "$PROD/decisions" "$WISH"
+
+emit() {  # emit <path> <<'EOF' ... EOF
+  local f="$1"
+  if [[ -f "$f" ]]; then echo "project: keep $f (exists)"; return; fi
+  cat > "$f"
+  echo "project: wrote $f"
+}
+
+emit "$PROD/PRODUCT.md" <<'EOF'
+# 产品寄存器
+
+## 用户
+-
+
+## Job（用户要完成的任务）
+-
+
+## 反参考（不要做）
+-
+EOF
+
+emit "$PROD/demand-pool.md" <<'EOF'
+# 需求池（愿望 inbox）
+
+> 新愿望先进这里（`wish.sh --new`）；接走后再建 `docs/wish/<id>/`。
+
+| ID | 愿望 | 状态 | 接走日期 |
+|---|---|---|---|
+| | | new | |
+EOF
+
+emit "$PROD/gap-register.md" <<'EOF'
+# 未满足需求登记
+
+| ID | 需求 | 来源 | 状态 |
+|---|---|---|---|
+| | | | open |
+EOF
+
+emit "$PROD/gap-closed.md" <<'EOF'
+# 已满足记录（关版回填）
+
+| 愿望 ID | 关版日期 | 证据 |
+|---|---|---|
+| | | |
+EOF
+
+emit "$ROOT/AGENTS.md" <<'EOF'
+# AGENTS.md — 工程事实面
+
+> 本文件是「怎么跑 / 测 / 构建 / 部署」的唯一事实面；产品愿景在 docs/product/，愿望契约在 docs/wish/<id>/。
+
+## 项目
+- 技术栈：
+- 代码入口：
+- 默认分支：
+
+## 常用命令
+```bash
+# 安装：
+# 启动：
+# 定向测试：
+# 全量测试：
+# lint / typecheck：
+# build：
+```
+
+## 环境与入口
+| 环境 | URL / 访问方式 | 版本识别 | 日志 / 监控 |
+|---|---|---|---|
+| Local | | | |
+| Preview | | | |
+| Production | | | |
+
+## 单向门（执行前需批准）
+- 事项 / 触发条件：
+- 批准人 / 政策：
+- 风险与回滚：
+
+## 外部共享资源（并行时需领取）
+| 资源 | 冲突规则 |
+|---|---|
+| 端口 | |
+| 数据库 / 测试数据 | |
+| 测试账号 | |
+| 浏览器 / 设备 | |
+
+## 项目就绪度
+| 能力 | 状态 |
+|---|---|
+| 本地启动与定向验证 | ready / missing |
+| 用户可见页面验收 | ready / missing / n/a |
+| 日志与监控只读入口 | ready / missing / n/a |
+| 部署与回滚 | ready / missing / n/a |
+EOF
+
+echo "project ready: $ROOT/{AGENTS.md, docs/product, docs/wish}"

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

@@ -0,0 +1,65 @@
+#!/usr/bin/env bash
+# Red-green replay: an acceptance oracle must be RED on the baseline (HEAD) and GREEN on the
+# current tree. Non-destructive: the baseline half runs in a throwaway `git worktree` at HEAD.
+#
+# Usage:
+#   replay.sh --cwd <repo> --oracle '<command>' [--link <dir> ...]
+#
+# --link <dir>: symlink a dependency dir (e.g. node_modules, .venv) from the working tree into
+#               the baseline worktree so the oracle can run there. Repeatable.
+#
+# Exit: 0 = red(baseline) -> green(now), discriminating evidence.
+#       1 = green-on-baseline (nondiscriminating), not green now, or cannot run.
+set -euo pipefail
+
+CWD="."
+ORACLE=""
+LINKS=()
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --cwd) CWD="${2:-}"; shift 2 ;;
+    --oracle) ORACLE="${2:-}"; shift 2 ;;
+    --link) LINKS+=("${2:-}"); shift 2 ;;
+    -h|--help) sed -n '2,14p' "$0" | sed 's/^# \{0,1\}//'; exit 0 ;;
+    *) echo "replay: unknown arg $1" >&2; exit 2 ;;
+  esac
+done
+[[ -n "$ORACLE" ]] || { echo "replay: --oracle required" >&2; exit 2; }
+
+ROOT="$(cd "$CWD" && git rev-parse --show-toplevel 2>/dev/null || true)"
+[[ -n "$ROOT" && -d "$ROOT/.git" ]] || { echo "replay FAIL: not a git repo: $CWD" >&2; exit 1; }
+
+TMP="$(mktemp -d)"
+cleanup() {
+  git -C "$ROOT" worktree remove --force "$TMP" >/dev/null 2>&1 || true
+  rm -rf "$TMP"
+}
+trap cleanup EXIT
+
+git -C "$ROOT" worktree add --detach "$TMP" HEAD >/dev/null 2>&1 || {
+  echo "replay FAIL: cannot create baseline worktree at HEAD" >&2; exit 1
+}
+
+for d in "${LINKS[@]}"; do
+  [[ -n "$d" ]] || continue
+  if [[ -d "$ROOT/$d" && ! -e "$TMP/$d" ]]; then
+    ln -s "$ROOT/$d" "$TMP/$d"
+  fi
+done
+
+set +e
+( cd "$TMP" && eval "$ORACLE" ) >/dev/null 2>&1
+base=$?
+( cd "$ROOT" && eval "$ORACLE" ) >/dev/null 2>&1
+now=$?
+set -e
+
+if [[ $now -ne 0 ]]; then
+  echo "replay FAIL: oracle not green on the current tree (exit $now)" >&2; exit 1
+fi
+if [[ $base -eq 0 ]]; then
+  echo "replay FAIL: oracle GREEN on baseline (exit $base) — nondiscriminating, it tests nothing" >&2; exit 1
+fi
+echo "replay OK: baseline red (exit $base) -> current green (exit $now)"
+exit 0

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

@@ -0,0 +1,79 @@
+#!/usr/bin/env python3
+"""scan_drift.py — deterministic doc-vs-code drift scan.
+
+Reads a module manifest (domain → doc files) and produces a difference list:
+for each listed doc, report whether the described files/routes/sections still
+exist in the code tree; missing/moved items are drift signals.
+
+Output: <workspace>/.sdd/drift.md (overwritten each run).
+Drift items are REGISTERED ONLY (gap-register todo), never auto-fixed —
+doc fixes go through the repo's Spec/PR discipline.
+
+Usage:
+  python3 scan_drift.py <workspace> [--manifest <path>]
+Default manifest: docs/wish/.drift-manifest.md with lines:
+  domain_name | code_path_glob | doc_file
+
+Exit: 0 scan done (drift found or not), 2 usage error.
+"""
+import sys
+from pathlib import Path
+
+MANIFEST_HINT = """# drift manifest — one row per module: 域 | 代码路径(glob 或目录) | 文档
+query_gateway | backend/app/domains/query_gateway | docs/architecture/05-building-blocks/query-gateway.md
+"""
+
+
+def main():
+    if len(sys.argv) not in (2, 4):
+        print("usage: scan_drift.py <workspace> [--manifest <path>]", file=sys.stderr)
+        return 2
+    root = Path(sys.argv[1]).resolve()
+    manifest_path = root / "docs" / "wish" / ".drift-manifest.md"
+    if len(sys.argv) == 4 and sys.argv[2] == "--manifest":
+        manifest_path = Path(sys.argv[3]).resolve()
+    if not manifest_path.is_file():
+        print(f"scan_drift: no manifest at {manifest_path}; create one (rows: 域 | 代码路径 | 文档)", file=sys.stderr)
+        (root / "docs" / "wish").mkdir(parents=True, exist_ok=True)
+        (root / "docs" / "wish" / ".drift-manifest.md").write_text(MANIFEST_HINT, encoding="utf-8")
+        print("scan_drift: wrote an empty manifest hint — fill it, then rerun", file=sys.stderr)
+        return 0
+
+    findings = []
+    for line in manifest_path.read_text(encoding="utf-8").splitlines():
+        line = line.strip()
+        if not line or line.startswith("#"):
+            continue
+        parts = [p.strip() for p in line.split("|")]
+        if len(parts) != 3:
+            findings.append(f"- [manifest malformed] {line}")
+            continue
+        domain, code_glob, doc = parts
+        code_glob_path = root / code_glob
+        if not code_glob_path.exists():
+            findings.append(f"- [drift] {domain}: code path missing/moved: {code_glob} (doc: {doc})")
+            continue
+        doc_path = root / doc
+        if not doc_path.is_file():
+            findings.append(f"- [drift] {domain}: doc missing: {doc} (code: {code_glob})")
+            continue
+        doc_text = doc_path.read_text(encoding="utf-8", errors="ignore")
+        # doc must name at least one file under its code path — cheap cross-check
+        named = 0
+        for p in code_glob_path.rglob("*") if code_glob_path.is_dir() else [code_glob_path]:
+            if p.is_file() and p.name.split(".")[0] in doc_text:
+                named += 1
+        if named == 0:
+            findings.append(f"- [drift] {domain}: doc {doc} references none of the files under {code_glob} — likely stale")
+
+    out = root / ".sdd" / "drift.md"
+    out.parent.mkdir(parents=True, exist_ok=True)
+    body = "\n".join(findings) if findings else "- (no drift detected)"
+    out.write_text(f"# drift scan {domain if False else ''}\n\n{body}\n", encoding="utf-8")
+    print(f"scan_drift: wrote {out} ({len(findings)} finding(s))")
+    print(body)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())