@chenmk/superflow 0.1.0

package/assets/scripts/superflow-delivery-check.sh

@@ -0,0 +1,315 @@
+#!/bin/bash
+# SuperBridge Flow delivery closeout verifier.
+# Blocks implementation commits that forget to update the matching PXX
+# delivery documents and test evidence.
+
+set -u
+
+MODE="${1:-}"
+
+read_json_field() {
+  local field="$1"
+  python3 -c "
+import json, os, sys
+try:
+    data = json.load(sys.stdin)
+except Exception:
+    print('')
+    raise SystemExit
+tool_input = data.get('tool_input', {})
+print(tool_input.get('$field') or tool_input.get('cmd') or '')
+" 2>/dev/null
+}
+
+if [ "$MODE" = "--check-staged" ]; then
+  CWD="${2:-$(pwd)}"
+else
+  INPUT=$(cat)
+  COMMAND=$(printf '%s' "$INPUT" | read_json_field command)
+  case "$COMMAND" in
+    *"git commit"*) ;;
+    *) exit 0 ;;
+  esac
+  CWD=$(printf '%s' "$INPUT" | python3 -c "
+import json, os, sys
+try:
+    data = json.load(sys.stdin)
+except Exception:
+    print(os.getcwd())
+    raise SystemExit
+tool_input = data.get('tool_input', {})
+print(tool_input.get('cwd') or os.getcwd())
+" 2>/dev/null)
+fi
+
+REPO_ROOT=$(git -C "$CWD" rev-parse --show-toplevel 2>/dev/null)
+if [ $? -ne 0 ]; then
+  exit 0
+fi
+
+CHANGED=$(git -C "$REPO_ROOT" diff --cached --name-only)
+if [ -z "$CHANGED" ]; then
+  exit 0
+fi
+
+SDD_ACTIVE=0
+if [ -f "$REPO_ROOT/.sdd-enforced" ]; then
+  SDD_ACTIVE=1
+fi
+
+RUNTIME_CHANGED=$(printf '%s\n' "$CHANGED" | grep -E \
+  '(^|/)src/main/.*\.(java|xml|yml|yaml|properties)$|(^|/)mapper/.*\.xml$|(^|/)sql/.*\.sql$' || true)
+
+CODE_RUNTIME_CHANGED=$(printf '%s\n' "$CHANGED" | grep -E \
+  '(^|/)src/main/.*\.(java|xml|yml|yaml|properties)$|(^|/)mapper/.*\.xml$' || true)
+
+P_DIRS=$(printf '%s\n' "$CHANGED" | sed -nE \
+  's#^(.*embedded-changes/(p[0-9]+[^/]*))/.*$#\1#p' | sort -u)
+
+REPORTS=$(printf '%s\n' "$CHANGED" | grep -E \
+  '(^|/)embedded-changes/p[0-9][^/]*/test-report\.md$|(^|/)test-report\.md$' || true)
+
+AGGREGATE_DOCS=$(printf '%s\n' "$CHANGED" | grep -E \
+  '(^|/)openspec/changes/[^/]+/(tasks|test-report|traceability-matrix|sdd-quality-gate|tests)\.md$|(^|/)doc/openspec/changes/[^/]+/(tasks|test-report|traceability-matrix|sdd-quality-gate|tests)\.md$' || true)
+
+SDD_DOCS_CHANGED=$(printf '%s\n' "$CHANGED" | grep -E \
+  '(^|/)(doc/)?openspec/changes/|(^|/)embedded-changes/p[0-9]' || true)
+
+AGGREGATE_ALLOWED=0
+if [ -f "$REPO_ROOT/.sdd-aggregate-closeout" ]; then
+  AGGREGATE_ALLOWED=1
+fi
+
+if [ "$SDD_ACTIVE" -eq 0 ] && [ -z "$SDD_DOCS_CHANGED" ]; then
+  exit 0
+fi
+
+FAILED=0
+
+fail() {
+  echo "FAIL $1"
+  FAILED=1
+}
+
+ok() {
+  echo "OK   $1"
+}
+
+has_staged_file() {
+  local path="$1"
+  printf '%s\n' "$CHANGED" | grep -Fxq "$path"
+}
+
+check_no_open_placeholders() {
+  local file="$1"
+  if [ ! -f "$file" ]; then
+    fail "[$file] 文件不存在"
+    return
+  fi
+
+  if grep -Eiq '待执行|待补充|后续补测|后续测试|TODO|测试报告待更新|验证待回填' "$file"; then
+    fail "[$file] 仍包含待执行/待补充/TODO 类交付占位"
+  else
+    ok "[$file] 未发现明显交付占位"
+  fi
+}
+
+check_has_closeout_status() {
+  local file="$1"
+  if grep -Eiq 'Real integration passed|Partially verified|Partial real entry|Blocked|真实入口|真实接口|验证闭环|阻塞|部分验证' "$file"; then
+    ok "[$file] 包含交付结论"
+  else
+    fail "[$file] 缺少 Real integration passed / Partially verified / Blocked 等交付结论"
+  fi
+}
+
+check_context_drift_guard() {
+  local rel_dir="$1"
+  local abs_dir="$REPO_ROOT/$rel_dir"
+  local state_file="$abs_dir/.sdd/state.yaml"
+  local handoff_dir="$abs_dir/.sdd/handoff"
+  local hash_file="$handoff_dir/sdd-context.sha256"
+  local marker=""
+
+  if [ ! -d "$abs_dir" ]; then
+    return
+  fi
+
+  marker=$(grep -REi 'handoff_hash|sdd-context|上下文防漂移|防漂移' \
+    "$abs_dir/sdd-quality-gate.md" "$abs_dir/test-report.md" "$abs_dir/design.md" \
+    "$abs_dir/prompt" 2>/dev/null || true)
+
+  if [ -z "$marker" ] && [ ! -f "$hash_file" ]; then
+    return
+  fi
+
+  if [ ! -f "$state_file" ]; then
+    fail "[$rel_dir] 缺少 .sdd/state.yaml，上下文防漂移状态未初始化"
+    return
+  fi
+
+  if [ ! -f "$handoff_dir/sdd-context.md" ] \
+    || [ ! -f "$handoff_dir/sdd-context.json" ] \
+    || [ ! -f "$hash_file" ]; then
+    fail "[$rel_dir] 缺少 .sdd/handoff/sdd-context.{md,json,sha256}"
+    return
+  fi
+
+  local hash_value
+  hash_value=$(cat "$hash_file" 2>/dev/null | tr -d '[:space:]')
+  if [ -z "$hash_value" ]; then
+    fail "[$rel_dir] sdd-context.sha256 为空"
+    return
+  fi
+
+  if grep -Riq "$hash_value" \
+    "$abs_dir/sdd-quality-gate.md" "$abs_dir/test-report.md" "$abs_dir/design.md" \
+    "$abs_dir/prompt" 2>/dev/null; then
+    ok "[$rel_dir] handoff hash 已被质量门/报告/prompt 继承"
+  else
+    fail "[$rel_dir] handoff hash 未写入 design、quality gate、prompt 或 test-report"
+  fi
+}
+
+is_blocked_doc_freeze_report() {
+  local file="$1"
+  if [ ! -f "$file" ]; then
+    return 1
+  fi
+
+  grep -Eiq 'Blocked|阻塞' "$file" \
+    && grep -Eiq 'SDD 文档|文档阶段|范围收口|范围冻结|任务冻结|不包含代码实现|没有 Java 实现变更|未进入实现|当前报告记录可交付边界' "$file"
+}
+
+DOC_FREEZE_ALLOWED=0
+for report in $REPORTS; do
+  if is_blocked_doc_freeze_report "$REPO_ROOT/$report"; then
+    DOC_FREEZE_ALLOWED=1
+  fi
+done
+
+if [ -n "$RUNTIME_CHANGED" ] && [ -z "$REPORTS" ]; then
+  fail "检测到运行时代码/SQL 变更，但本次提交没有 staged 当前任务的 test-report.md"
+fi
+
+if [ -n "$AGGREGATE_DOCS" ] && [ "$AGGREGATE_ALLOWED" -eq 0 ] && [ "$DOC_FREEZE_ALLOWED" -eq 0 ]; then
+  fail "检测到根级汇总 SDD 文档变更，但当前不是汇总收口 worktree"
+  printf '%s\n' "$AGGREGATE_DOCS" | sed 's/^/  - /'
+  cat <<'AGGREGATE_MSG'
+
+并行研发 agent 只允许更新自己的 embedded-changes/pXX-* 目录，避免多个
+worktree 合并时反复冲突根级 test-report/tasks/traceability 文档。
+
+如果你是 Leader/集成收口 agent，需要统一汇总各 P 任务状态，请先执行：
+  touch .sdd-aggregate-closeout
+
+然后在单独的汇总提交中更新根级 SDD 文档。
+AGGREGATE_MSG
+fi
+
+if [ -n "$P_DIRS" ]; then
+  for p_dir in $P_DIRS; do
+    rel_tasks="$p_dir/tasks.md"
+    rel_report="$p_dir/test-report.md"
+    rel_gate="$p_dir/sdd-quality-gate.md"
+
+    if [ -f "$REPO_ROOT/$rel_tasks" ]; then
+      if has_staged_file "$rel_tasks"; then
+        ok "[$rel_tasks] 已 staged"
+      else
+        fail "[$rel_tasks] 未 staged，当前 P 任务交付状态可能未同步"
+      fi
+    fi
+
+    if [ -f "$REPO_ROOT/$rel_report" ]; then
+      if has_staged_file "$rel_report"; then
+        ok "[$rel_report] 已 staged"
+        check_no_open_placeholders "$REPO_ROOT/$rel_report"
+        check_has_closeout_status "$REPO_ROOT/$rel_report"
+        if [ -x "$HOME/.codex/hooks/superflow-test-report-lint.py" ]; then
+          lint_args=(--repo-root "$REPO_ROOT")
+          if [ -f "$REPO_ROOT/$p_dir/tests.md" ]; then
+            lint_args+=(--tests "$REPO_ROOT/$p_dir/tests.md")
+          fi
+          "$HOME/.codex/hooks/superflow-test-report-lint.py" \
+            "${lint_args[@]}" "$REPO_ROOT/$rel_report"
+          if [ $? -ne 0 ]; then
+            FAILED=1
+          fi
+        fi
+      else
+        fail "[$rel_report] 未 staged，当前 P 任务测试报告未同步"
+      fi
+    else
+      fail "[$rel_report] 不存在，当前 P 任务缺少独立测试报告"
+    fi
+
+    if [ -f "$REPO_ROOT/$rel_gate" ]; then
+      if has_staged_file "$rel_gate"; then
+        ok "[$rel_gate] 已 staged"
+        check_no_open_placeholders "$REPO_ROOT/$rel_gate"
+      else
+        fail "[$rel_gate] 未 staged，当前 P 任务质量门禁可能未同步"
+      fi
+    fi
+
+    check_context_drift_guard "$p_dir"
+  done
+fi
+
+VERIFY_REPORTS=$(printf '%s\n' "$REPORTS" | grep -E \
+  '(^|/)embedded-changes/p[0-9][^/]*/test-report\.md$' || true)
+
+if [ -n "$VERIFY_REPORTS" ] && [ -x "$HOME/.codex/hooks/superflow-verify-integration.sh" ]; then
+  VERIFY_ARGS=""
+  for report in $VERIFY_REPORTS; do
+    abs_report="$REPO_ROOT/$report"
+    if is_blocked_doc_freeze_report "$abs_report" && [ -z "$CODE_RUNTIME_CHANGED" ]; then
+      ok "[$report] 为 SDD 文档冻结 Blocked 报告，跳过真实集成验收脚本"
+      continue
+    fi
+    VERIFY_ARGS="$VERIFY_ARGS $abs_report"
+  done
+  if [ -n "$VERIFY_ARGS" ]; then
+    "$HOME/.codex/hooks/superflow-verify-integration.sh" $VERIFY_ARGS
+    if [ $? -ne 0 ]; then
+      FAILED=1
+    fi
+  fi
+fi
+
+ROOT_REPORTS=$(printf '%s\n' "$REPORTS" | grep -E \
+  '(^|/)openspec/changes/[^/]+/test-report\.md$|(^|/)doc/openspec/changes/[^/]+/test-report\.md$' || true)
+
+if [ -n "$ROOT_REPORTS" ] && [ -x "$HOME/.codex/hooks/superflow-test-report-lint.py" ]; then
+  for report in $ROOT_REPORTS; do
+    root_lint_args=(--warn-only --repo-root "$REPO_ROOT")
+    root_tests="${report%/test-report.md}/tests.md"
+    if [ -f "$REPO_ROOT/$root_tests" ]; then
+      root_lint_args+=(--tests "$REPO_ROOT/$root_tests")
+    fi
+    "$HOME/.codex/hooks/superflow-test-report-lint.py" \
+      "${root_lint_args[@]}" "$REPO_ROOT/$report"
+    if [ $? -ne 0 ]; then
+      FAILED=1
+    fi
+  done
+fi
+
+if [ "$FAILED" -ne 0 ]; then
+  cat <<'BLOCK_MSG'
+
+[SDD 交付完整性拦截]
+当前提交还没有形成可交付闭环。请补齐当前 P 任务的：
+  1. tasks.md 状态
+  2. test-report.md 真实验证证据
+  3. sdd-quality-gate.md 质量门禁状态（如果存在）
+
+如果确实无法验证，请在 test-report.md 中写明 Blocked 或 Partially verified
+以及具体阻塞原因，不能用“后续补测/待补充”作为完成态。
+BLOCK_MSG
+  exit 2
+fi
+
+echo "SDD 交付完整性检查通过"
+exit 0

package/assets/scripts/superflow-dependency-update-hook.sh

@@ -0,0 +1,161 @@
+#!/bin/bash
+# Session-scoped Superflow dependency update checker.
+# Default mode checks and reports updates. Set SUPERFLOW_AUTO_UPDATE=apply to install.
+
+set -u
+
+INPUT=""
+if [ ! -t 0 ]; then
+  INPUT=$(cat 2>/dev/null || true)
+fi
+
+MODE="${SUPERFLOW_AUTO_UPDATE:-check}"
+case "$MODE" in
+  0|off|false|none) exit 0 ;;
+  1|true|yes|apply) MODE="apply" ;;
+  check|"") MODE="check" ;;
+  *) MODE="check" ;;
+esac
+
+if [ "$MODE" = "0" ]; then
+  exit 0
+fi
+
+STATE_DIR="${XDG_STATE_HOME:-$HOME/.local/state}/superflow"
+mkdir -p "$STATE_DIR" 2>/dev/null || exit 0
+
+SESSION_KEY=$(printf '%s' "$INPUT" | python3 -c '
+import hashlib, json, os, sys
+raw = sys.stdin.read()
+try:
+    data = json.loads(raw) if raw.strip() else {}
+except Exception:
+    data = {}
+for key in ("session_id", "conversation_id", "thread_id", "transcript_path"):
+    value = data.get(key)
+    if value:
+        print(str(value))
+        raise SystemExit
+cwd = data.get("cwd") or os.getcwd()
+print("fallback:" + hashlib.sha256(cwd.encode()).hexdigest()[:16])
+' 2>/dev/null)
+
+[ -n "$SESSION_KEY" ] || SESSION_KEY="unknown"
+SESSION_HASH=$(printf '%s' "$SESSION_KEY" | shasum -a 256 2>/dev/null | awk '{print $1}')
+if [ -z "$SESSION_HASH" ]; then
+  SESSION_HASH=$(printf '%s' "$SESSION_KEY" | sha256sum 2>/dev/null | awk '{print $1}')
+fi
+[ -n "$SESSION_HASH" ] || SESSION_HASH="unknown"
+
+STAMP="$STATE_DIR/dependency-update-$SESSION_HASH.stamp"
+GLOBAL_STAMP="$STATE_DIR/dependency-update-last.stamp"
+LOG_FILE="$STATE_DIR/dependency-update.log"
+LOCK_DIR="$STATE_DIR/dependency-update.lock"
+
+now_epoch() {
+  date +%s
+}
+
+MIN_INTERVAL="${SUPERFLOW_UPDATE_MIN_INTERVAL_SECONDS:-21600}"
+NOW=$(now_epoch)
+
+if [ -f "$STAMP" ]; then
+  exit 0
+fi
+
+if [ -f "$GLOBAL_STAMP" ]; then
+  LAST=$(cat "$GLOBAL_STAMP" 2>/dev/null || printf '0')
+  case "$LAST" in
+    ''|*[!0-9]*) LAST=0 ;;
+  esac
+  if [ "$((NOW - LAST))" -lt "$MIN_INTERVAL" ]; then
+    printf '%s\n' "$NOW" > "$STAMP" 2>/dev/null || true
+    exit 0
+  fi
+fi
+
+if ! mkdir "$LOCK_DIR" 2>/dev/null; then
+  exit 0
+fi
+trap 'rmdir "$LOCK_DIR" 2>/dev/null || true' EXIT
+
+printf '%s\n' "$NOW" > "$STAMP" 2>/dev/null || true
+printf '%s\n' "$NOW" > "$GLOBAL_STAMP" 2>/dev/null || true
+
+run_logged() {
+  printf '\n[%s] %s\n' "$(date '+%Y-%m-%d %H:%M:%S')" "$*" >> "$LOG_FILE" 2>/dev/null || true
+  "$@" >> "$LOG_FILE" 2>&1
+}
+
+latest_npm_version() {
+  npm view "$1" version 2>/dev/null | tail -n 1
+}
+
+installed_npm_version() {
+  local json
+  json="$(npm list -g "$1" --depth=0 --json 2>/dev/null || true)"
+  printf '%s' "$json" | python3 -c '
+import json, sys
+package_name = sys.argv[1]
+try:
+    data = json.load(sys.stdin)
+except Exception:
+    raise SystemExit
+dep = (data.get("dependencies") or {}).get(package_name) or {}
+version = dep.get("version")
+if version:
+    print(version)
+' "$1"
+}
+
+update_npm_if_needed() {
+  local package_name="$1"
+  local current latest
+  command -v npm >/dev/null 2>&1 || return 0
+  latest="$(latest_npm_version "$package_name")"
+  [ -n "$latest" ] || return 0
+  current="$(installed_npm_version "$package_name")"
+  if [ "$current" != "$latest" ]; then
+    run_logged npm install -g "$package_name@latest" || true
+  fi
+}
+
+check_npm_package() {
+  local package_name="$1"
+  local current latest
+  command -v npm >/dev/null 2>&1 || return 0
+  latest="$(latest_npm_version "$package_name")"
+  [ -n "$latest" ] || return 0
+  current="$(installed_npm_version "$package_name")"
+  if [ -z "$current" ]; then
+    printf '%s latest=%s installed=missing\n' "$package_name" "$latest"
+  elif [ "$current" != "$latest" ]; then
+    printf '%s latest=%s installed=%s\n' "$package_name" "$latest" "$current"
+  fi
+}
+
+if [ "$MODE" = "apply" ]; then
+  update_npm_if_needed "@chenmk/superflow"
+  update_npm_if_needed "@fission-ai/openspec"
+
+  if command -v claude >/dev/null 2>&1; then
+    run_logged claude plugin install superpowers@superpowers-marketplace || true
+  fi
+
+  if command -v codex >/dev/null 2>&1; then
+    run_logged codex plugin add superpowers@openai-curated || true
+  fi
+else
+  STATUS_FILE="$STATE_DIR/dependency-update-status.txt"
+  {
+    printf 'checked_at=%s\n' "$(date '+%Y-%m-%d %H:%M:%S')"
+    check_npm_package "@chenmk/superflow"
+    check_npm_package "@fission-ai/openspec"
+    printf 'superpowers=run superflow update --with-package to refresh selected agent plugins\n'
+  } > "$STATUS_FILE" 2>/dev/null || true
+  if grep -Eq '^@' "$STATUS_FILE" 2>/dev/null; then
+    printf '[Superflow] 有核心依赖更新，执行 superflow update --with-package 统一更新；详情：%s\n' "$STATUS_FILE" >&2
+  fi
+fi
+
+exit 0

package/assets/scripts/superflow-enforce-hook.sh

@@ -0,0 +1,70 @@
+#!/bin/bash
+# SDD 强制门禁 Hook
+# 拦截 Edit/Write 工具调用，确保：
+# 1. 不在主工作树直接编辑（必须用 worktree）
+# 2. 数据库结构已核查（必须有 .db-verified 标记）
+#
+# 触发条件：项目根目录存在 .sdd-enforced 文件
+# 标记说明：
+#   .sdd-enforced - 由 SDD prompt 创建，表示当前有活跃的 SDD 任务
+#   .db-verified   - 由研发 agent 数据库核查后创建
+#
+# 退出码：0=允许  2=拦截
+
+INPUT=$(cat)
+
+FILE_PATH=$(echo "$INPUT" | python3 -c "
+import sys, json
+d = json.load(sys.stdin)
+print(d.get('tool_input', {}).get('file_path', ''))
+" 2>/dev/null)
+
+if [ -z "$FILE_PATH" ]; then
+    exit 0
+fi
+
+FILE_DIR=$(dirname "$FILE_PATH")
+
+REPO_ROOT=$(git -C "$FILE_DIR" rev-parse --show-toplevel 2>/dev/null)
+if [ $? -ne 0 ]; then
+    exit 0
+fi
+
+if [ ! -f "$REPO_ROOT/.sdd-enforced" ]; then
+    exit 0
+fi
+
+if [ -d "$REPO_ROOT/.git" ]; then
+    cat <<'BLOCK_MSG'
+[SDD 门禁拦截] 检测到在主工作树直接编辑，已阻止。
+
+原因：SDD 任务要求在独立 worktree 分支中开发，禁止污染主工作树。
+
+请立即执行：
+  git worktree add -b feature/{任务分支名} ../{项目}-worktree HEAD
+  cd ../{项目}-worktree
+  # 在 worktree 内重新创建门禁标记：
+  touch .sdd-enforced
+
+完成后即可继续编辑。如需取消门禁，删除主仓库的 .sdd-enforced 文件。
+BLOCK_MSG
+    exit 2
+fi
+
+if [ ! -f "$REPO_ROOT/.db-verified" ]; then
+    cat <<'BLOCK_MSG'
+[SDD 门禁拦截] 数据库结构尚未核查，编辑已阻止。
+
+原因：写业务代码前必须先确认开发环境数据库结构与设计一致。
+
+请立即执行数据库前置门禁：
+  1. 连接开发库执行 SHOW CREATE TABLE 确认表结构
+  2. 如有缺失，从汇总 SQL 文件取脚本执行
+  3. 确认后创建标记：touch .db-verified
+
+完成后即可继续编辑。如需跳过（不推荐），删除 .sdd-enforced 文件。
+BLOCK_MSG
+    exit 2
+fi
+
+exit 0

package/assets/scripts/superflow-hook-guard.sh

@@ -0,0 +1,132 @@
+#!/bin/bash
+# SDD phase-aware hook guard.
+# Blocks writes that conflict with .sdd/state.yaml when .sdd-enforced is active.
+
+set -u
+
+INPUT=""
+if [ ! -t 0 ]; then
+  INPUT=$(cat 2>/dev/null || true)
+fi
+
+FILE_PATH="${FILE_PATH:-}"
+if [ -z "$FILE_PATH" ] && [ -n "$INPUT" ]; then
+  FILE_PATH=$(printf '%s' "$INPUT" | python3 -c "
+import json, sys
+try:
+    data = json.load(sys.stdin)
+except Exception:
+    print('')
+    raise SystemExit
+tool_input = data.get('tool_input', {})
+print(tool_input.get('file_path') or '')
+" 2>/dev/null)
+fi
+
+if [ -z "$FILE_PATH" ]; then
+  exit 0
+fi
+
+FILE_PATH=$(printf '%s' "$FILE_PATH" | sed 's|\\|/|g')
+FILE_DIR=$(dirname "$FILE_PATH")
+while [ ! -d "$FILE_DIR" ] && [ "$FILE_DIR" != "." ] && [ "$FILE_DIR" != "/" ]; do
+  FILE_DIR=$(dirname "$FILE_DIR")
+done
+REPO_ROOT=$(git -C "$FILE_DIR" rev-parse --show-toplevel 2>/dev/null)
+if [ $? -ne 0 ]; then
+  exit 0
+fi
+
+if [ ! -f "$REPO_ROOT/.sdd-enforced" ]; then
+  exit 0
+fi
+
+REL=$(python3 - "$REPO_ROOT" "$FILE_PATH" <<'PY'
+import os, sys
+root = os.path.abspath(sys.argv[1])
+path = os.path.abspath(sys.argv[2])
+try:
+    print(os.path.relpath(path, root).replace(os.sep, '/'))
+except Exception:
+    print(path.replace(os.sep, '/'))
+PY
+)
+
+STATE_FILE=""
+case "$REL" in
+  *embedded-changes/*)
+    prefix=$(printf '%s\n' "$REL" | sed -nE 's#^(.*embedded-changes/[^/]+).*#\1#p')
+    [ -n "$prefix" ] && [ -f "$REPO_ROOT/$prefix/.sdd/state.yaml" ] && STATE_FILE="$REPO_ROOT/$prefix/.sdd/state.yaml"
+    ;;
+  *openspec/changes/*)
+    prefix=$(printf '%s\n' "$REL" | sed -nE 's#^(.*openspec/changes/[^/]+).*#\1#p')
+    [ -n "$prefix" ] && [ -f "$REPO_ROOT/$prefix/.sdd/state.yaml" ] && STATE_FILE="$REPO_ROOT/$prefix/.sdd/state.yaml"
+    ;;
+esac
+
+if [ -z "$STATE_FILE" ]; then
+  STATE_FILE=$(find "$REPO_ROOT" -path '*/.sdd/state.yaml' -type f 2>/dev/null | head -n 1)
+fi
+
+[ -n "$STATE_FILE" ] || exit 0
+
+PHASE=$(awk -F':' '$1=="phase"{gsub(/^[ \t]+|[ \t]+$/, "", $2); print $2}' "$STATE_FILE" 2>/dev/null)
+[ -n "$PHASE" ] || exit 0
+
+is_sdd_doc_path() {
+  printf '%s\n' "$REL" | grep -Eq '(^|/)(openspec/changes|embedded-changes)/|(^|/)\.sdd/|(^|/)prompt/|(^|/)docs/superpowers/'
+}
+
+is_root_markdown_or_config() {
+  case "$REL" in
+    */*) return 1 ;;
+    *.md|.sdd-enforced|.db-verified) return 0 ;;
+    *) return 1 ;;
+  esac
+}
+
+case "$REL" in
+  *.java|*.xml|*.sql|*.yml|*.yaml|*.properties)
+    RUNTIME=1
+    ;;
+  *)
+    RUNTIME=0
+    ;;
+esac
+
+case "$PHASE" in
+  docs)
+    if is_sdd_doc_path || is_root_markdown_or_config; then
+      exit 0
+    fi
+    if [ "$RUNTIME" -eq 1 ]; then
+      cat <<'BLOCK_MSG' >&2
+[SDD phase guard] 当前 phase=docs，禁止直接修改运行时代码。
+请先完成 SDD docs、handoff、state 和 docs guard，再进入 implement 阶段。
+BLOCK_MSG
+      exit 2
+    fi
+    ;;
+  implement|verify)
+    exit 0
+    ;;
+  archive)
+    if printf '%s\n' "$REL" | grep -Eq '(^|/)\.sdd/state\.yaml$|(^|/)\.openspec\.yaml$'; then
+      exit 0
+    fi
+    cat <<'BLOCK_MSG' >&2
+[SDD phase guard] 当前 SDD 已进入 archive，禁止继续修改运行时代码或交付文档。
+如需调整，请先执行 superflow-state.sh transition <change-dir> archive-reopen。
+BLOCK_MSG
+    exit 2
+    ;;
+  done)
+    cat <<'BLOCK_MSG' >&2
+[SDD phase guard] 当前 SDD 已进入 archive/done，禁止继续修改交付文件或代码。
+如需调整，请先执行 superflow-state.sh transition <change-dir> archive-reopen。
+BLOCK_MSG
+    exit 2
+    ;;
+esac
+
+exit 0