@chenmk/superflow 0.1.0

package/assets/skills/superflow-pipeline/scripts/superflow-status.sh

@@ -0,0 +1,172 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+usage() {
+  cat <<'USAGE'
+Usage:
+  superflow-status.sh <repo-root> [--json]
+
+List active SDD changes under a repository.
+USAGE
+}
+
+die() {
+  printf 'superflow-status: %s\n' "$*" >&2
+  exit 1
+}
+
+repo="${1:-}"
+mode="${2:-}"
+[[ -n "$repo" && "$repo" != "-h" && "$repo" != "--help" ]] || {
+  usage
+  exit 0
+}
+[[ -d "$repo" ]] || die "repo root not found: $repo"
+[[ -z "$mode" || "$mode" == "--json" ]] || die "unknown option: $mode"
+
+repo="$(cd "$repo" && pwd)"
+state_script="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/superflow-state.sh"
+shopt -s globstar nullglob 2>/dev/null || true
+
+state_value() {
+  local file="$1"
+  local key="$2"
+  awk -F':' -v k="$key" '
+    $1 == k {
+      value = $0
+      sub("^[^:]*:[[:space:]]*", "", value)
+      gsub(/^[[:space:]]+|[[:space:]]+$/, "", value)
+      print value
+      found=1
+    }
+    END { exit found ? 0 : 1 }
+  ' "$file" 2>/dev/null || true
+}
+
+count_tasks() {
+  local dir="$1"
+  local total done
+  total="$(grep -RHE '^[[:space:]]*-[[:space:]]+\[[ xX]\]' "$dir"/*.md "$dir"/**/*.md 2>/dev/null | wc -l | tr -d ' ')"
+  done="$(grep -RHE '^[[:space:]]*-[[:space:]]+\[[xX]\]' "$dir"/*.md "$dir"/**/*.md 2>/dev/null | wc -l | tr -d ' ')"
+  printf '%s/%s' "$done" "$total"
+}
+
+task_total() {
+  printf '%s' "$1" | awk -F/ '{print $2}'
+}
+
+task_done() {
+  printf '%s' "$1" | awk -F/ '{print $1}'
+}
+
+next_reason() {
+  local phase="$1"
+  local verify_result="$2"
+  local tasks="$3"
+  local total done remaining
+  total="$(task_total "$tasks")"
+  done="$(task_done "$tasks")"
+  remaining=$((total - done))
+  [[ "$verify_result" == "fail" ]] && {
+    printf '最近一次 verify 失败，先修复验证报告中的失败项。'
+    return
+  }
+  case "$phase" in
+    docs) printf '当前处于 docs 阶段，继续生成或补齐 OpenSpec/SDD 合同文档。' ;;
+    design) printf '当前处于 design 阶段，继续生成 Superpowers 源码级技术详设。' ;;
+    implement)
+      if [[ "$remaining" -gt 0 ]]; then
+        printf '当前处于 implement 阶段，还有 %s 个任务未完成。' "$remaining"
+      else
+        printf 'implement 任务已完成，可以进入 verify 前检查。'
+      fi
+      ;;
+    verify) printf '当前处于 verify 阶段，补齐真实验证证据并运行验收门禁。' ;;
+    archive) printf 'verify 已通过后进入 archive，等待明确归档确认。' ;;
+    *) printf '当前 phase 未知，先检查 .sdd/state.yaml。' ;;
+  esac
+}
+
+print_risks() {
+  local dir="$1"
+  local workflow="$2"
+  local phase="$3"
+  local review_mode="$4"
+  local verify_result="$5"
+  local tasks="$6"
+  local total done
+  total="$(task_total "$tasks")"
+  done="$(task_done "$tasks")"
+  [[ "$phase" == "" ]] && printf '  WARNING UNKNOWN_PHASE: phase 缺失或未知。\n'
+  if [[ "$total" -eq 0 || ! -f "$dir/tasks.md" ]]; then
+    printf '  WARNING TASKS_MISSING: 缺少 tasks.md 或任务清单为空。\n'
+  elif [[ "$phase" == "implement" && "$done" -lt "$total" ]]; then
+    printf '  WARNING TASKS_INCOMPLETE: 仍有 %s 个任务未完成。\n' "$((total - done))"
+  fi
+  if [[ "${workflow:-full}" == "full" && "${review_mode:-null}" == "null" ]]; then
+    printf '  WARNING REVIEW_MODE_MISSING: full workflow 尚未选择 review_mode。\n'
+  fi
+  if [[ "$verify_result" == "fail" ]]; then
+    printf '  ERROR VERIFY_FAILED: 最近一次 verify 失败。\n'
+  elif [[ "$phase" == "verify" && ! -f "$dir/test-report.md" ]]; then
+    printf '  WARNING TEST_REPORT_MISSING: verify 阶段缺少 test-report.md。\n'
+  fi
+  for artifact in proposal.md design.md tests.md; do
+    [[ -f "$dir/$artifact" ]] || printf '  INFO ARTIFACT_MISSING: 缺少 %s。\n' "$artifact"
+  done
+}
+
+tmp="$(mktemp)"
+trap 'rm -f "$tmp"' EXIT
+
+find "$repo" -path '*/.sdd/state.yaml' -type f 2>/dev/null | sort > "$tmp"
+
+if [[ "$mode" == "--json" ]]; then
+  printf '{\n  "changes": [\n'
+  first=1
+  while IFS= read -r state; do
+    dir="${state%/.sdd/state.yaml}"
+    archived="$(state_value "$state" archived)"
+    phase="$(state_value "$state" phase)"
+    [[ "$archived" == "true" || "$phase" == "done" ]] && continue
+    workflow="$(state_value "$state" workflow)"
+    build_mode="$(state_value "$state" build_mode)"
+    review_mode="$(state_value "$state" review_mode)"
+    verify_mode="$(state_value "$state" verify_mode)"
+    verify_result="$(state_value "$state" verify_result)"
+    next="$("$state_script" next "$dir" 2>/dev/null | tr '\n' ';' || true)"
+    tasks="$(count_tasks "$dir")"
+    reason="$(next_reason "$phase" "$verify_result" "$tasks")"
+    [[ "$first" -eq 0 ]] && printf ',\n'
+    first=0
+    printf '    {"path": "%s", "workflow": "%s", "phase": "%s", "buildMode": "%s", "reviewMode": "%s", "verifyMode": "%s", "verifyResult": "%s", "tasks": "%s", "next": "%s", "reason": "%s"}' \
+      "${dir#"$repo"/}" "$workflow" "$phase" "$build_mode" "$review_mode" "$verify_mode" "$verify_result" "$tasks" "$next" "$reason"
+  done < "$tmp"
+  printf '\n  ]\n}\n'
+  exit 0
+fi
+
+printed=0
+while IFS= read -r state; do
+  dir="${state%/.sdd/state.yaml}"
+  archived="$(state_value "$state" archived)"
+  phase="$(state_value "$state" phase)"
+  [[ "$archived" == "true" || "$phase" == "done" ]] && continue
+  workflow="$(state_value "$state" workflow)"
+  build_mode="$(state_value "$state" build_mode)"
+  review_mode="$(state_value "$state" review_mode)"
+  verify_mode="$(state_value "$state" verify_mode)"
+  verify_result="$(state_value "$state" verify_result)"
+  tasks="$(count_tasks "$dir")"
+  printed=1
+  printf '%s\n' "- ${dir#"$repo"/}"
+  printf '  phase: %s | workflow: %s | build_mode: %s | review_mode: %s | verify_mode: %s | verify_result: %s | tasks: %s\n' \
+    "$phase" "$workflow" "$build_mode" "$review_mode" "$verify_mode" "$verify_result" "$tasks"
+  printf '  reason: %s\n' "$(next_reason "$phase" "$verify_result" "$tasks")"
+  print_risks "$dir" "$workflow" "$phase" "$review_mode" "$verify_result" "$tasks"
+  "$state_script" next "$dir" | sed 's/^/  /'
+done < "$tmp"
+
+if [[ "$printed" -eq 0 ]]; then
+  printf 'No active SuperBridge Flow changes.\n'
+fi

package/assets/skills/superflow-pipeline/scripts/superflow-yaml-validate.sh

@@ -0,0 +1,138 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+usage() {
+  cat <<'USAGE'
+Usage:
+  superflow-yaml-validate.sh <change-dir>
+
+Validate <change-dir>/.sdd/state.yaml structure, enums, known fields, and
+referenced paths.
+USAGE
+}
+
+die() {
+  printf 'superflow-yaml-validate: %s\n' "$*" >&2
+  exit 1
+}
+
+CHANGE_DIR="${1:-}"
+[[ -n "$CHANGE_DIR" && "$CHANGE_DIR" != "-h" && "$CHANGE_DIR" != "--help" ]] || {
+  usage
+  exit 0
+}
+
+[[ -d "$CHANGE_DIR" ]] || die "change dir not found: $CHANGE_DIR"
+CHANGE_DIR="$(cd "$CHANGE_DIR" && pwd)"
+STATE="$CHANGE_DIR/.sdd/state.yaml"
+[[ -f "$STATE" ]] || die "state not found: $STATE"
+
+ERRORS=0
+WARNINGS=0
+
+fail() {
+  printf 'FAIL %s\n' "$*" >&2
+  ERRORS=$((ERRORS + 1))
+}
+
+warn() {
+  printf 'WARN %s\n' "$*" >&2
+  WARNINGS=$((WARNINGS + 1))
+}
+
+value_of() {
+  local key="$1"
+  awk -F':' -v k="$key" '
+    $1 == k {
+      value = $0
+      sub("^[^:]*:[[:space:]]*", "", value)
+      sub("[[:space:]]+#.*$", "", value)
+      gsub(/^[[:space:]]+|[[:space:]]+$/, "", value)
+      print value
+      found=1
+    }
+    END { exit found ? 0 : 1 }
+  ' "$STATE"
+}
+
+require_field() {
+  local key="$1"
+  grep -q "^${key}:" "$STATE" || fail "missing required field '$key'"
+}
+
+validate_enum() {
+  local key="$1"
+  local allowed="$2"
+  local value
+  value="$(value_of "$key" 2>/dev/null || true)"
+  [[ -z "$value" || "$value" == "null" ]] && return
+  for item in $allowed; do
+    [[ "$value" == "$item" ]] && return
+  done
+  fail "$key='$value' is invalid; expected one of: $allowed"
+}
+
+validate_path_field() {
+  local key="$1"
+  local value
+  value="$(value_of "$key" 2>/dev/null || true)"
+  [[ -z "$value" || "$value" == "null" ]] && return
+  [[ -f "$CHANGE_DIR/$value" || -f "$value" ]] || fail "$key path does not exist: $value"
+}
+
+REQUIRED_FIELDS="workflow phase canonical_spec build_mode tdd_mode review_mode isolation verify_mode auto_transition verify_result verification_report branch_status archived handoff_context handoff_hash created_at updated_at"
+for field in $REQUIRED_FIELDS; do
+  require_field "$field"
+done
+
+validate_enum workflow "full hotfix tweak"
+validate_enum phase "docs design implement verify archive done"
+validate_enum build_mode "subagent-driven-development executing-plans team-prompt direct"
+validate_enum build_pause "plan-ready"
+validate_enum subagent_dispatch "confirmed"
+validate_enum tdd_mode "tdd direct"
+validate_enum review_mode "off standard thorough"
+validate_enum isolation "branch worktree"
+validate_enum verify_mode "light full"
+validate_enum auto_transition "true false"
+validate_enum verify_result "pending pass fail"
+validate_enum branch_status "pending handled"
+validate_enum archived "true false"
+validate_enum direct_override "true false"
+validate_enum context_compression "off beta"
+
+handoff_hash="$(value_of handoff_hash 2>/dev/null || true)"
+if [[ -n "$handoff_hash" && "$handoff_hash" != "null" && ! "$handoff_hash" =~ ^[a-f0-9]{64}$ ]]; then
+  fail "handoff_hash is not a sha256 hex digest: $handoff_hash"
+fi
+
+validate_path_field handoff_context
+validate_path_field implementation_prompt
+validate_path_field verification_report
+validate_path_field design_doc
+validate_path_field technical_design
+validate_path_field plan
+
+KNOWN="workflow phase canonical_spec context_compression design_doc technical_design plan base_ref build_mode build_pause subagent_dispatch tdd_mode review_mode isolation verify_mode auto_transition verify_result verification_report branch_status archived direct_override build_command verify_command handoff_context handoff_hash superpower_strategy implementation_prompt worktree_ports created_at verified_at updated_at"
+while IFS= read -r line; do
+  [[ -z "$line" || "$line" =~ ^[[:space:]]*# ]] && continue
+  [[ "$line" == *:* ]] || {
+    fail "malformed state line without ':' -> $line"
+    continue
+  }
+  IFS=: read -r key _ <<< "$line"
+  key="$(printf '%s' "$key" | tr -d '[:space:]')"
+  [[ -z "$key" ]] && continue
+  found=0
+  for known in $KNOWN; do
+    [[ "$key" == "$known" ]] && found=1 && break
+  done
+  [[ "$found" -eq 1 ]] || warn "unknown field '$key'"
+done < "$STATE"
+
+if [[ "$ERRORS" -gt 0 ]]; then
+  printf 'superflow state validation failed: %s error(s), %s warning(s)\n' "$ERRORS" "$WARNINGS" >&2
+  exit 1
+fi
+
+printf 'superflow state validation passed: %s warning(s)\n' "$WARNINGS"

package/assets/skills/superflow-table-impact-analysis/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: superflow-table-impact-analysis
+description: Use when an SDD/OpenSpec requirement, bug fix, sync task, migration, or test plan touches database tables, status fields, Mapper/XML queries, cross-repo shared data, or user-facing behavior driven by persisted fields.
+---
+
+# SDD Table Impact Analysis
+
+Use this skill before freezing design, writing implementation prompts, coding,
+or accepting test reports for database-backed behavior.
+
+## Core Rule
+
+Do not start from the happy-path writer only. Start from every affected
+`table.field`, then reverse-scan all code and business consumers before
+declaring the feature complete.
+
+Required impact table:
+
+```text
+表/字段 | 写入方 | 读取/过滤方 | 跨仓/外部消费方 | 真实入口 | 反向状态场景 | 验证证据
+```
+
+Required semantic table for status/enum/sync/default behavior:
+
+```text
+真源字段 | 真源枚举 | 目标字段 | 目标枚举 | 消费方解释 | 业务依据 | 不确定项
+```
+
+## Procedure
+
+1. List every affected table and field from docs, SQL, Mapper/XML, entity,
+   DTO, sync payload, logs, and DB samples.
+2. For each field, search all references. Use understand-anything only as a
+   locator when available; if it is missing, stale, incomplete, or unavailable,
+   degrade to `rg`, source reading, Mapper/XML, SQL, configuration, log
+   templates, database table names, and sibling-repo search. Cover entities,
+   Mapper/XML, SQL, services, jobs, MQ listeners, controllers, external
+   adapters, sibling repos, SDK/DTOs, and frontend/applet endpoints.
+3. Classify each reference:
+   writer, reader, filter, default-value logic, old-value retention, state
+   recovery, cross-repo sync, user-facing entry point.
+4. Add reverse-state scenarios:
+   offline -> online, disabled -> enabled, deleted -> restored, missing ->
+   reappearing, old invalid value -> valid when upstream omits a field.
+5. For status, enum, sync, derived, default, or compatibility behavior, identify
+   the source-of-truth field and the consumer-facing meaning. Do not accept
+   non-null, present, successful, or "has any value" as correct. Reject
+   fallback/default/keep-old-value/null-conversion/alternative-field logic
+   unless explicitly approved by the requirement or owner. Approved
+   compatibility must document:
+   `兜底触发条件 | 业务依据 | 会掩盖的异常 | 监控/告警/暴露方式 | 移除条件 | owner确认`.
+6. Put the impact table and semantic table into `design.md`, `tests.md`,
+   `traceability-matrix.md`, implementation prompt, and `test-report.md`.
+7. Verify at least one final business entry point, not only the sync task or
+   DB update. Examples: applet QR scan, start charge, payment/refund,
+   notification, callback, scheduled job, third-party query.
+
+## Blockers
+
+Mark the task `Blocked` when:
+
+- a consumer or real entry point is unknown;
+- only the writer/sync path is tested;
+- only the unavailable direction is tested;
+- a status field can retain an old invalid value;
+- a status/enum/sync value is treated as correct only because it is non-null,
+  present, successful, or has any value;
+- fallback/default/keep-old-value/null-conversion/alternative-field logic is
+  used without explicit business approval and exposure strategy;
+- cross-repo consumers are not enumerated;
+- `test-report.md` lacks the required impact table.
+
+## Hook
+
+`~/.codex/hooks/superflow-test-report-lint.py` enforces this for database/status
+reports that claim pass or partial pass. A report that only says "sync
+succeeded" without consumer-path evidence is blocked.

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

@@ -0,0 +1,46 @@
+---
+name: superflow-tweak
+description: Use when an SDD task is a tiny non-behavioral tweak such as wording, prompt, docs, config comments, or local process text and may use a lighter path unless runtime gates are involved.
+---
+
+# SDD Tweak
+
+Tweak is a preset workflow for small non-runtime changes. It must not weaken
+SDD evidence for code, API, database, or integration behavior.
+
+## Allowed Scope
+
+Use tweak only for:
+
+- Prompt wording
+- SDD documentation wording
+- Review checklist wording
+- Non-runtime comments
+- Local process text
+
+Do not use tweak for Java/runtime code, API behavior, SQL, Mapper/XML, DB,
+status/enum, SDK, cross-repo, frontend contract, or real integration changes.
+
+## Procedure
+
+1. Initialize state:
+   ```bash
+   ~/.codex/skills/superflow-pipeline/scripts/superflow-state.sh init <change-dir> tweak docs
+   ```
+2. Generate/update handoff so future sessions can recover exact context.
+3. Set:
+   ```bash
+   ~/.codex/skills/superflow-pipeline/scripts/superflow-state.sh set <change-dir> build_mode direct
+   ~/.codex/skills/superflow-pipeline/scripts/superflow-state.sh set <change-dir> isolation branch
+   ~/.codex/skills/superflow-pipeline/scripts/superflow-state.sh set <change-dir> tdd_mode direct
+   ~/.codex/skills/superflow-pipeline/scripts/superflow-state.sh set <change-dir> review_mode off
+   ```
+4. Run `superflow-state.sh scale <change-dir>`. If it returns `full`, stop tweak and
+   upgrade to full SDD.
+5. Verify with the relevant doc/template/script checks and run archive only
+   after user confirmation.
+
+## Upgrade Conditions
+
+Any runtime behavior, API, DB, SQL, hook, integration evidence, worktree
+parallel coding, or user-facing behavior change upgrades this to full SDD.

package/assets/skills/superflow-verify/SKILL.md

@@ -0,0 +1,112 @@
+---
+name: superflow-verify
+description: Use when an SDD/OpenSpec change is ready for verification, test-report closure, code review, branch/worktree handling, or retry decisions after implementation.
+---
+
+# SDD Verify
+
+Verification is a phase, not a final sentence. Use this skill after
+implementation work claims completion and before archive or delivery.
+
+## Entry Check
+
+Run:
+
+```bash
+~/.codex/skills/superflow-pipeline/scripts/superflow-yaml-validate.sh <change-dir>
+~/.codex/skills/superflow-pipeline/scripts/superflow-state.sh recover <change-dir>
+~/.codex/skills/superflow-pipeline/scripts/superflow-state.sh scale <change-dir>
+```
+
+If the change is still in `implement`, run:
+
+```bash
+~/.codex/skills/superflow-pipeline/scripts/superflow-guard.sh <change-dir> implement --apply
+```
+
+Do not verify from conversation memory. Reload `.sdd/handoff/sdd-context.md`,
+`api.md`, `design.md`, `tasks.md`, `tests.md`, `sdd-quality-gate.md`, and
+existing `test-report.md`.
+
+## Verification Modes
+
+Use `.sdd/state.yaml` `verify_mode` after `scale`.
+
+`light` is allowed only when all are true:
+
+- no API, DB, SQL, Mapper/XML, SDK, cross-repo, status/enum, payment, refund,
+  device, MQ, scheduler, or third-party contract change;
+- task count and changed-file count stay within the scale threshold;
+- no L3/L4 integration evidence is required by `tests.md` or quality gate.
+
+`full` is required when any SDD hard gate is touched. Full verification must
+prove the complete evidence chain: source/Mapper/XML, DB when needed, real
+entry point, interface automation, logs, SQL sync, and consumer behavior.
+
+## Required Superpowers
+
+Immediately load and apply these Superpowers when available:
+
+- `verification-before-completion` before claiming the work passes.
+- `requesting-code-review` after local verification has evidence.
+- `finishing-a-development-branch` before branch/worktree closeout.
+
+If a required Superpower is unavailable, mark the verification `Blocked` and
+ask the user to install or enable it. Do not replace it with ordinary prose.
+
+## Failure Decision
+
+When verification fails, stop at a decision point. Present:
+
+- failed check and evidence path;
+- whether failure is CRITICAL, IMPORTANT, WARNING, or SUGGESTION;
+- recommended fix path;
+- risk if the user accepts deviation.
+
+CRITICAL or IMPORTANT failures cannot be accepted silently. If the user chooses
+to fix, run:
+
+```bash
+~/.codex/skills/superflow-pipeline/scripts/superflow-state.sh transition <change-dir> verify-fail
+```
+
+Then return to `$superflow-implement` or `$superflow-docs` depending on whether the failure
+is implementation drift or design/spec drift.
+
+After three consecutive verify-fail cycles, do not auto-continue fixing. Ask
+the user whether to continue fixing or accept the remaining deviations with
+explicit recorded risk.
+
+## Pass Closure
+
+Before pass:
+
+1. `test-report.md` records commands, RED/GREEN expectations, actual output,
+   DB/log/API evidence, handoff hash, and phase state.
+2. `~/.codex/hooks/superflow-verify-integration.sh <test-report.md>` passes when the
+   report involves integration evidence.
+3. `~/.codex/hooks/superflow-test-report-lint.py --tests <tests.md> <test-report.md>`
+   passes. If `tests.md` declares L3/L4, real-entry, third-party, device,
+   database, log, or dev-tool evidence, mock-only/unit-only reports are hard
+   failures unless the report is explicitly `Blocked` or `Partially verified`
+   with the missing environment named.
+4. `~/.codex/hooks/superflow-delivery-check.sh <test-report.md>` passes before
+   delivery or branch closeout.
+5. Code review findings are either fixed or explicitly recorded with accepted
+   risk.
+6. Branch/worktree status is handled and `.sdd/state.yaml` has:
+   `branch_status: handled`.
+
+Only then run:
+
+```bash
+~/.codex/skills/superflow-pipeline/scripts/superflow-guard.sh <change-dir> verify --apply
+```
+
+This advances to `phase: archive`, sets `verify_result: pass`, and records
+`verified_at`.
+
+## Archive Boundary
+
+Passing verification does not authorize automatic archive. Enter `$superflow-archive`
+and wait for explicit user confirmation.