@chenmk/superflow 0.2.5 → 0.4.0

package/assets/skills-en/superflow-pipeline/scripts/superflow-guard.sh

@@ -24,6 +24,7 @@ VALIDATE="$SCRIPT_DIR/superflow-yaml-validate.sh"
 CHANGE_DIR="${1:-}"
 PHASE="${2:-}"
 MODE="${3:-}"
+CHANGE_DIR_INPUT="${CHANGE_DIR%/}"
 
 [[ -n "$CHANGE_DIR" && -n "$PHASE" ]] || {
   usage
@@ -35,6 +36,25 @@ MODE="${3:-}"
 CHANGE_DIR="$(cd "$CHANGE_DIR" && pwd)"
 issues=()
 
+require_canonical_change_layout() {
+  local suffix
+
+  if [[ -L "$CHANGE_DIR_INPUT" ]]; then
+    issues+=("symlinked OpenSpec change directory is forbidden; keep one physical openspec/changes/<change-name> directory")
+  fi
+
+  [[ "$CHANGE_DIR" == */openspec/changes/* ]] || return 0
+  suffix="${CHANGE_DIR#*/openspec/changes/}"
+  case "$suffix" in
+    archive/*|*/embedded-changes/*) return 0 ;;
+  esac
+  if [[ "$suffix" == */* ]]; then
+    issues+=("non-canonical OpenSpec change directory: encode the version in <change-name> and use openspec/changes/<change-name>")
+  fi
+}
+
+require_canonical_change_layout
+
 require_file() {
   local path="$1"
   [[ -f "$CHANGE_DIR/$path" ]] || issues+=("missing file: $path")
@@ -178,6 +198,60 @@ require_state_file() {
   require_file .sdd/state.yaml
 }
 
+require_tasks_complete() {
+  local task_count unchecked_count
+  require_file tasks.md
+  [[ -f "$CHANGE_DIR/tasks.md" ]] || return 0
+  task_count="$(grep -Ec '^[[:space:]]*-[[:space:]]+\[[ xX]\]' "$CHANGE_DIR/tasks.md" || true)"
+  unchecked_count="$(grep -Ec '^[[:space:]]*-[[:space:]]+\[[[:space:]]\]' "$CHANGE_DIR/tasks.md" || true)"
+  [[ "$task_count" -gt 0 ]] || issues+=("tasks.md has no checkbox tasks")
+  [[ "$unchecked_count" -eq 0 ]] || issues+=("$unchecked_count unchecked task(s) remain in tasks.md")
+}
+
+verification_report_path() {
+  local value
+  value="$(state_get verification_report)"
+  [[ -n "$value" && "$value" != "null" ]] || return 1
+  if [[ -f "$CHANGE_DIR/$value" ]]; then
+    printf '%s\n' "$CHANGE_DIR/$value"
+    return 0
+  fi
+  if [[ -f "$value" ]]; then
+    printf '%s\n' "$value"
+    return 0
+  fi
+  return 1
+}
+
+require_closeout_markers() {
+  local report="${1:-$CHANGE_DIR/test-report.md}"
+  if [[ ! -f "$report" ]]; then
+    issues+=("verification report path does not exist: $report")
+    return 0
+  fi
+  if ! grep -Eiq '(Verification Result)[[:space:]:|*-]*(PASS)' "$report"; then
+    issues+=("verification result PASS marker not found in verification report")
+  fi
+  if ! grep -Eiq '(Archive Readiness)[[:space:]:|*-]*(PASS|READY)' "$report"; then
+    issues+=("archive readiness PASS marker not found in verification report")
+  fi
+}
+
+require_branch_handled() {
+  local branch_status
+  branch_status="$(state_get branch_status)"
+  [[ "$branch_status" == "handled" ]] || issues+=("branch_status must be handled before verification closeout")
+}
+
+require_full_verification_fingerprint() {
+  local report="$CHANGE_DIR/test-report.md"
+  [[ "$(state_get verify_mode)" == "full" ]] || return 0
+  require_grep 'test environment|staging|sandbox' "$report" "full verification test environment"
+  require_grep 'branch|commit|tag|build|image' "$report" "full verification deployment fingerprint"
+  require_grep 'https?://|Base URL' "$report" "full verification base URL"
+  require_grep 'timestamp|verified[_ -]?at|20[0-9]{2}-[0-9]{2}-[0-9]{2}' "$report" "full verification timestamp"
+}
+
 require_spec_doc() {
   if [[ -f "$CHANGE_DIR/spec.md" ]]; then
     return
@@ -248,6 +322,42 @@ change_has_field_status_risk() {
     "$CHANGE_DIR"/*.md "$CHANGE_DIR"/**/*.md 2>/dev/null
 }
 
+change_contract_docs_without_complexity_budget() {
+  local path
+  for path in proposal.md api.md design.md tests.md spec.md; do
+    [[ -f "$CHANGE_DIR/$path" ]] || continue
+    sed -E '/New-item counts|Complexity budget/d' "$CHANGE_DIR/$path"
+  done
+  if [[ -d "$CHANGE_DIR/specs" ]]; then
+    find "$CHANGE_DIR/specs" -path '*/spec.md' -type f \
+      -exec sed -E '/New-item counts|Complexity budget/d' {} +
+  fi
+}
+
+change_all_docs_without_complexity_budget() {
+  find "$CHANGE_DIR" -maxdepth 2 -name '*.md' -type f \
+    -exec sed -E '/New-item counts|Complexity budget/d' {} +
+}
+
+change_has_external_config_risk() {
+  local content
+  content="$(change_contract_docs_without_complexity_budget)"
+  grep -Eiq \
+    'third[- ]party|external (platform|tool|integration|system)|SDK|MQ|Kafka|RocketMQ|TDMQ|callback|webhook|payment gateway|cloud service' \
+    <<< "$content"
+}
+
+change_has_concurrency_idempotency_risk() {
+  grep -RIEiq \
+    'concurren|idempoten|race condition|duplicate (request|callback|consumption|delivery)|atomic claim|batch (issue|activate|renew)' \
+    "$CHANGE_DIR/proposal.md" \
+    "$CHANGE_DIR/api.md" \
+    "$CHANGE_DIR/design.md" \
+    "$CHANGE_DIR/tests.md" \
+    "$CHANGE_DIR/spec.md" \
+    "$CHANGE_DIR"/specs/*/spec.md 2>/dev/null
+}
+
 change_has_money_precision_risk() {
   grep -RIEiq \
     '(^|[^[:alnum:]_])(amount|fee|fees|price|discount|deduction|refund|payment|invoice|balance|proration|allocation|reconciliation|residual|precision|rounding)([^[:alnum:]_]|$)|revenue sharing|profit sharing|split payment|electricity fee|service fee|package settlement|serviceFee|chargeFee|totalAmount|actualAmount|payAmount|refundAmount|discountAmount|invoiceAmount|balanceAmount' \
@@ -271,9 +381,11 @@ change_has_fx_precision_risk() {
 }
 
 change_has_architecture_boundary_risk() {
-  grep -RIEiq \
+  local content
+  content="$(change_all_docs_without_complexity_budget)"
+  grep -Eiq \
     'cross-repo|cross-service|sibling|SDK|MQ|topic|consumer|scheduler|scheduled|device|callback|third[- ]party|mini[- ]program|gateway|adapter|protocol|interconnect|call chain|entry|exit' \
-    "$CHANGE_DIR"/*.md "$CHANGE_DIR"/**/*.md 2>/dev/null
+    <<< "$content"
 }
 
 first_prompt_rel() {
@@ -335,6 +447,33 @@ require_money_precision_contract() {
   fi
 }
 
+require_external_config_contract() {
+  local path="$1"
+  local label="$2"
+  require_grep 'External Integration Configuration And Deployment Contract' "$path" "$label"
+  require_grep 'local.*test.*production|local.*staging.*production' "$path" "$label environment matrix"
+  require_grep 'provision|injection|IaC|Secret|console' "$path" "$label injection/provisioning"
+  require_grep 'provisioning owner|runtime owner|owner.*time' "$path" "$label owner and timing"
+  require_grep 'readiness|trace|health' "$path" "$label readiness evidence"
+  require_grep 'rollback|disable' "$path" "$label rollback"
+  require_grep 'secret|credential' "$path" "$label secret handling"
+  require_grep 'not.*hard.?cod|must not.*hard.?cod|do not hard.?code' "$path" "$label no hard-coded external config"
+  require_grep 'test.*production|staging.*production' "$path" "$label test-production distinction"
+}
+
+require_concurrency_idempotency_contract() {
+  local path="$1"
+  local label="$2"
+  require_grep 'Concurrency And Idempotency Ownership|application.layer atomic claim|atomic claim' "$path" "$label"
+  require_grep 'business idempotency key|business key' "$path" "$label business idempotency key"
+  require_grep 'application.layer atomic claim|atomic claim' "$path" "$label application-layer atomic claim"
+  require_grep 'short transaction|transaction boundary' "$path" "$label short transaction boundary"
+  require_grep 'pending|success|failed|state machine' "$path" "$label state machine"
+  require_grep 'retry' "$path" "$label retry contract"
+  require_grep 'external call|third.party call' "$path" "$label external-call boundary"
+  require_grep 'unique index.*not.*default|do not.*default.*unique index' "$path" "$label unique index is not the default"
+}
+
 require_money_precision_evidence() {
   local path="$1"
   local label="$2"
@@ -357,6 +496,29 @@ require_money_precision_evidence() {
   fi
 }
 
+require_minimal_design_review() {
+  local path="$1"
+  local label="$2"
+  require_grep 'Minimal Design Review|Complexity Reduction Review' "$path" "$label"
+  require_grep 'reuse|existing capability|existing module' "$path" "$label reuse evidence"
+  require_grep 'simplest|minimum design|minimal implementation' "$path" "$label simplest implementation"
+  require_grep 'removed|rejected|do not add|out of scope' "$path" "$label removed or rejected complexity"
+  require_grep 'New-item counts|Complexity budget' "$path" "$label complexity budget"
+  require_grep 'table' "$path" "$label table count"
+  require_grep 'field' "$path" "$label field count"
+  require_grep 'API' "$path" "$label API count"
+  require_grep 'service|component' "$path" "$label service/component count"
+  require_grep 'cache' "$path" "$label cache count"
+  require_grep 'MQ|event|async' "$path" "$label async/event count"
+  require_grep 'scheduled job|scheduler' "$path" "$label scheduled-job count"
+  require_grep 'compatibility layer' "$path" "$label compatibility-layer count"
+}
+
+require_minimal_design_pass() {
+  local path="$1"
+  require_grep '(Minimal Design Review|Complexity Reduction Review).*PASS|PASS.*(Minimal Design Review|Complexity Reduction Review)' "$path" "complexity reduction review PASS verdict"
+}
+
 transition_event=""
 
 if [[ -x "$VALIDATE" && -f "$CHANGE_DIR/.sdd/state.yaml" ]]; then
@@ -386,9 +548,22 @@ case "$PHASE" in
     require_grep 'RED|red-green|GREEN' tests.md "RED/GREEN test contract"
     require_grep 'curl|Postman|Newman|pytest|RestAssured|automation command' tests.md "interface automation command"
     require_grep 'handoff_hash|sdd-context|context package|anti-drift' sdd-quality-gate.md "handoff/context-drift gate"
+    workflow="$(state_get workflow)"
+    if [[ "$workflow" == "full" ]]; then
+      require_minimal_design_review design.md "complexity reduction review"
+      require_grep 'Minimal Design Review|Complexity Reduction Review' sdd-quality-gate.md "complexity reduction quality gate"
+      require_minimal_design_pass sdd-quality-gate.md
+    fi
     if change_has_money_precision_risk; then
       require_grep 'Money Precision Boundary' sdd-quality-gate.md "money precision quality gate"
     fi
+    if change_has_external_config_risk; then
+      require_external_config_contract api.md "external integration configuration contract"
+      require_external_config_contract sdd-quality-gate.md "external integration deployment gate"
+    fi
+    if change_has_concurrency_idempotency_risk; then
+      require_concurrency_idempotency_contract sdd-quality-gate.md "concurrency and idempotency ownership quality gate"
+    fi
     require_markdown_links_valid
     transition_event="docs-complete"
     ;;
@@ -410,6 +585,9 @@ case "$PHASE" in
     require_hash_recorded
     workflow="$(state_get workflow)"
     if [[ "$workflow" == "full" ]]; then
+      require_minimal_design_review design.md "complexity reduction review"
+      require_grep 'Minimal Design Review|Complexity Reduction Review' sdd-quality-gate.md "complexity reduction quality gate"
+      require_minimal_design_pass sdd-quality-gate.md
       require_optional_state_path technical_design "technical_design"
       technical_design_rel="$(state_get technical_design)"
       if [[ -n "${technical_design_rel:-}" && "$technical_design_rel" != "null" ]]; then
@@ -421,9 +599,16 @@ case "$PHASE" in
         if change_has_field_status_risk; then
           require_grep 'Field And Status Reverse Impact|Field And Status Reverse Impact|write point.*read|read/filter points|derived/sync points' "$technical_design_rel" "field/status reverse impact matrix"
         fi
+        if change_has_external_config_risk; then
+          require_external_config_contract "$technical_design_rel" "external integration configuration and deployment contract"
+        fi
+        if change_has_concurrency_idempotency_risk; then
+          require_concurrency_idempotency_contract "$technical_design_rel" "concurrency and idempotency ownership contract"
+        fi
         if change_has_money_precision_risk; then
           require_money_precision_contract "$technical_design_rel" "money precision boundary"
         fi
+        require_minimal_design_review "$technical_design_rel" "technical design minimal design review"
       fi
     fi
     require_grep 'Superpowers Technical Design Handoff|Superpowers Technical Design|technical_design|source-level HOW' design.md "Superpowers technical design handoff"
@@ -449,6 +634,12 @@ case "$PHASE" in
         if change_has_field_status_risk; then
           require_grep 'Field And Status Reverse Impact|Field And Status Reverse Impact|read/filter points|derived/sync points' "$prompt_rel" "prompt field/status reverse impact inheritance"
         fi
+        if change_has_external_config_risk; then
+          require_external_config_contract "$prompt_rel" "prompt external integration configuration inheritance"
+        fi
+        if change_has_concurrency_idempotency_risk; then
+          require_concurrency_idempotency_contract "$prompt_rel" "prompt concurrency and idempotency ownership inheritance"
+        fi
         if change_has_money_precision_risk; then
           require_money_precision_contract "$prompt_rel" "prompt money precision inheritance"
         fi
@@ -471,6 +662,7 @@ case "$PHASE" in
     ;;
   verify)
     require_state_file
+    require_tasks_complete
     require_file test-report.md
     require_grep 'RED|failure evidence' test-report.md "RED evidence"
     require_grep 'GREEN|pass evidence' test-report.md "GREEN evidence"
@@ -480,7 +672,18 @@ case "$PHASE" in
     if change_has_money_precision_risk; then
       require_money_precision_evidence test-report.md "money precision runtime evidence"
     fi
+    if change_has_external_config_risk; then
+      require_grep 'External Integration Configuration And Deployment Contract' test-report.md "external integration configuration runtime evidence"
+      require_grep 'production.*ready|provision.*verified|resource.*exists' test-report.md "external production readiness evidence"
+    fi
+    if change_has_concurrency_idempotency_risk; then
+      require_grep 'Concurrency And Idempotency Ownership|application.layer atomic claim|atomic claim' test-report.md "concurrency and idempotency runtime evidence"
+      require_grep 'concurren|duplicate|retry' test-report.md "concurrency duplicate and retry cases"
+    fi
     require_test_report_lint
+    require_closeout_markers "$CHANGE_DIR/test-report.md"
+    require_branch_handled
+    require_full_verification_fingerprint
     require_markdown_links_valid
     if [[ "$(state_get verification_report)" == "" || "$(state_get verification_report)" == "null" ]]; then
       "$STATE" set "$CHANGE_DIR" verification_report test-report.md
@@ -489,11 +692,20 @@ case "$PHASE" in
     ;;
   archive)
     require_state_file
+    require_tasks_complete
     verify_result="$(state_get verify_result)"
     [[ "$verify_result" == "pass" ]] || issues+=("verify_result must be pass before archive")
     archived="$(state_get archived)"
     [[ "$archived" != "true" ]] || issues+=("archived is already true")
     require_state_value verification_report "verification_report"
+    report_path="$(verification_report_path || true)"
+    if [[ -z "$report_path" ]]; then
+      issues+=("verification_report path does not exist")
+    else
+      require_closeout_markers "$report_path"
+    fi
+    require_branch_handled
+    require_state_value verified_at "verified_at"
     transition_event="archived"
     ;;
   *)

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

@@ -111,6 +111,14 @@ Before pass:
    complement.
 7. Branch/worktree status is handled and `.sdd/state.yaml` has:
    `branch_status: handled`.
+8. Every checkbox in `tasks.md` is checked. A completed implementation with
+   stale task documentation is a verification failure, not an archive-time
+   cleanup item.
+9. `test-report.md` ends with the machine-checkable closeout markers
+   `Verification Result: PASS` and `Archive Readiness: PASS`. For
+   `verify_mode: full`, it also records the test environment,
+   branch/commit/build or image fingerprint, Base URL, and verification
+   timestamp.
 
 Only then run: