create-wakii-stack 0.0.0-stage → 0.1.0

package/stack-template/pnpm-workspace.yaml

@@ -0,0 +1,24 @@
+packages:
+  # FE workspace — từ story VU-53 SF-1: app/shared/src/{styles,ui} do design-system
+  # SF sở hữu (SF-2/3/4 consume); 4 file logic fe-shared + mfToolkit READ-LOCKED
+  - "app/*"
+  # Spike MF/Rspack (SF-1) — xoá được sau khi pin versions chốt
+  - "app/spike/*"
+  # [FLAG coordinator duyệt] SF-6 (FI-74) thêm — remotes phải vào workspace để dùng
+  # workspace:* (fe-shared) + catalog: (singletons); REQUIREMENT-GAP đã comment epic FI-62
+  - "app/remotes/*"
+  # node-svc (SF-2 điền impl) — spring-svc/go-svc không thuộc pnpm workspace
+  - "services/node-svc"
+  # auth-svc (VU-59 SF-2 / VU-61) — standalone lockfile như node-svc
+  - "services/auth-svc"
+
+# Catalog — single source versions cho MF singletons (SF-5/6 import cùng pin).
+# Nguồn: SF-1 spike + SF-5 re-validation (GAP epic FI-62 2026-10-12). Coordinator sở hữu.
+catalog:
+  react: 19.3.0
+  react-dom: 19.3.0
+  react-router: ^7.9.0
+  "@module-federation/enhanced": 0.21.6
+  "@rspack/core": 1.7.12
+  # react-query singleton (libs adopt 2026-10-17) — share cache tasks↔activity qua MF
+  "@tanstack/react-query": ^5.0.0

package/stack-template/scripts/scaffold/scaffold.sh

@@ -0,0 +1,110 @@
+#!/usr/bin/env bash
+# ============================================================================
+# scaffold.sh — sinh project MỚI từ boilerplate (SF-7, FI-75).
+#
+# Copy + rename + prune thuần (tar-based — KHÔNG rsync, KHÔNG generator framework,
+# đúng spec epic: "copy + rename + prune"). Project mới cùng flow chạy được.
+#
+# Usage:
+#   bash scripts/scaffold/scaffold.sh <new-name> [--out <dir>]
+#     <new-name>   tên project mới (lowercase, chữ/số/dấu gạch — dùng làm scope)
+#     --out <dir>  thư mục output (default: <cwd>/<new-name>)
+#
+# Prune (không copy): .git · node_modules · target/ · dist/ · docs/superpowers ·
+#   app/spike · .github/workflow-templates · .github/workflows/convergence.yml
+#   (pin story branch — chết trong repo mới) · .story-brief.md · .env
+#
+# Rename: @wakii/* → @<new-name>/* (toàn bộ package.json + pnpm-lock.yaml) ·
+#   root package name → <new-name> · compose `name:` → <new-name> · README title.
+#
+# Lưu ý pnpm-lock: importers của thư mục bị prune (vd app/spike) còn sót
+# trong lockfile — pnpm tự reconcile ở lần `pnpm install --no-frozen-lockfile`
+# ĐẦU TIÊN (bắt buộc — đã ghi trong SCAFFOLD.md output). Không tự strip tay
+# bằng sed/awk — rủi ro corrupt lockfile lớn hơn lợi ích.
+# ============================================================================
+set -euo pipefail
+
+usage() { echo "usage: $0 <new-name> [--out <dir>]" >&2; exit 1; }
+[ $# -ge 1 ] || usage
+NAME="$1"; shift
+[ "${1:-}" = "--out" ] && { OUT="$2"; shift 2; } || OUT=""
+[ $# -eq 0 ] || usage
+
+echo "$NAME" | grep -qE '^[a-z0-9][a-z0-9-]*$' || { echo "LỖI: new-name phải lowercase [a-z0-9-]: '$NAME'" >&2; exit 1; }
+
+SRC="$(cd "$(dirname "$0")/../.." && pwd)" # repo root (script ở scripts/scaffold/)
+[ -f "$SRC/pnpm-workspace.yaml" ] || { echo "LỖI: không tìm thấy repo root tại $SRC" >&2; exit 1; }
+OUT="${OUT:-$PWD/$NAME}"
+[ ! -e "$OUT" ] || { echo "LỖI: output đã tồn tại: $OUT" >&2; exit 1; }
+# chặn OUT nằm TRONG source (tar copy-into-self ô nhiễm output — P0 code-review SF-7)
+# python3 thay realpath -m: BSD realpath (macOS) không có -m — fix portability 2026-10-17
+OUT_REAL="$(python3 -c 'import os,sys; print(os.path.realpath(sys.argv[1]))' "$OUT")"
+case "$OUT_REAL" in "$SRC"/*) echo "LỖI: --out không được nằm trong repo nguồn: $OUT" >&2; exit 1;; esac
+
+# sed -i BSD (macOS) bắt buộc tham số backup ('') — GNU không. Detect 1 lần (fix portability 2026-10-17)
+if sed --version >/dev/null 2>&1; then SED_I=(sed -i); else SED_I=(sed -i ''); fi
+
+echo "[scaffold] copy $SRC → $OUT (prune boilerplate-infra)"
+mkdir -p "$OUT"
+tar -C "$SRC" -cf - \
+  --exclude='./.git' \
+  --exclude='./node_modules' \
+  --exclude='*/node_modules' \
+  --exclude='*/node_modules/*' \
+  --exclude='./*/node_modules' \
+  --exclude='*/target' \
+  --exclude='*/dist' \
+  --exclude='./docs/superpowers' \
+  --exclude='./app/spike' \
+  --exclude='./.github/workflow-templates' \
+  --exclude='./.github/workflows/convergence.yml' \
+  --exclude='./.story-brief.md' \
+  --exclude='.env' \
+  . | tar -C "$OUT" -xf -
+
+echo "[scaffold] rename @wakii/* → @$NAME/* (package.json + source imports + Dockerfile + yml + md + lockfile)"
+find "$OUT" \( -name package.json -o -name '*.ts' -o -name '*.tsx' -o -name '*.js' -o -name '*.jsx' -o -name '*.css' -o -name '*.mjs' \
+  -o -name 'Dockerfile*' -o -name '*.yml' -o -name '*.yaml' -o -name '*.md' \) \
+  -not -path '*/node_modules/*' -not -path '*/target/*' -not -path '*/dist/*' \
+  -exec "${SED_I[@]}" "s/@wakii\//@$NAME\//g" {} +
+"${SED_I[@]}" "s/@wakii\//@$NAME\//g" "$OUT/pnpm-lock.yaml"
+
+echo "[scaffold] rename root package name + compose name + README title + orca.yaml"
+"${SED_I[@]}" "s/\"name\": \"[^\"]*\"/\"name\": \"$NAME\"/" "$OUT/package.json"
+"${SED_I[@]}" "s/^name: boilerplate/name: $NAME/" "$OUT/platform/docker-compose.yml"
+"${SED_I[@]}" "1s/^# Boilerplate Microservice + Micro-frontend/# $NAME (scaffolded từ boilerplate microservice + micro-frontend)/" "$OUT/README.md"
+"${SED_I[@]}" "s/^name: architecture-overview/name: $NAME/" "$OUT/orca.yaml"
+
+cat > "$OUT/SCAFFOLD.md" <<EOF
+# Scaffold: $NAME
+
+Sinh từ boilerplate epic FI-62 bởi \`scripts/scaffold/scaffold.sh\` ngày $(date +%F).
+
+## Đổi tên đã áp dụng
+- pnpm scope \`@wakii/*\` → \`@$NAME/*\` (package.json + pnpm-lock.yaml)
+- root package name → \`$NAME\`; compose project name → \`$NAME\`; README title
+
+## Bước tiếp theo (bắt buộc theo thứ tự)
+1. \`git init\` + commit đầu tiên.
+2. \`pnpm install --no-frozen-lockfile\` — LẦN ĐẦU PHẢI non-frozen: lockfile còn
+   giữ importers của thư mục đã prune (app/spike); pnpm tự reconcile.
+   Từ lần sau dùng \`--frozen-lockfile\` như thường.
+3. \`cp platform/.env.example platform/.env\` rồi điền JWT_SECRET + passwords.
+4. Compose (máy có Docker): \`docker compose -f platform/docker-compose.yml --env-file platform/.env up -d --build\`
+   → \`bash scripts/smoke/e2e.sh\` (login → tạo task → đọc feed qua gateway :8080).
+5. Native (không Docker): theo \`docs/walkthrough.md\`.
+
+## Boundary
+- Full e2e trên project scaffolded là **human gate** (cần Docker) — CI chỉ
+  chứng minh build + compose-config được (narrowing đã duyệt ở epic FI-62).
+- Đọc \`README.md\` + \`docs/walkthrough.md\` + \`docs/adr/\` để hiểu kiến trúc.
+
+## AI onboarding
+- \`CLAUDE.md\` — onboarding AI (nguyên tắc vàng + lệnh + gotchas).
+- \`orca.yaml\` — descriptor máy đọc cho agent (services/ports/commands/gotchas).
+- \`.claude/agents/\` — 4 agent miền: fe-dev · be-dev · e2e-runner · contracts-keeper.
+- \`.claude/skills/\` — thủ tục dự án: add-service (thêm service mới) · sync-contracts (sửa API/contract).
+EOF
+
+echo "[scaffold] DONE — project mới tại: $OUT"
+echo "[scaffold] tiếp theo: cd '$OUT' && pnpm install --no-frozen-lockfile (xem SCAFFOLD.md)"

package/stack-template/scripts/smoke/e2e.sh

@@ -0,0 +1,305 @@
+#!/usr/bin/env bash
+# ============================================================================
+# e2e smoke — SF-5 (FI-81, story FI-76) + mở rộng auth-real (SF-5 VU-64):
+# chứng minh chuỗi Kafka + Outbox + Saga + auth thật LIỀN MẠCH qua gateway
+# trên compose stack.
+#
+# 2 chiều (context pack sf-5):
+#   HAPPY: login (auth-svc) → tạo task (node-svc; event qua outbox → Kafka →
+#          go-svc consume) → đọc feed + stats (go-svc).
+#   AUTH-REAL (VU-64): register user mới → refresh rotation → reuse token cũ
+#          → 401 (revoke-all) → logout idempotent → RBAC: user roles ["user"]
+#          DELETE task → 403 FORBIDDEN, alice (admin) DELETE → 204 (tasks.yaml).
+#   SAGA : tạo task → PATCH assigneeId = svc-fail fixture → go consumer fail
+#          ×3 → compensating event `task.assignment_failed` → node compensation
+#          consumer → GET task status = `assignment_failed` → assert DLQ:
+#          kafka-console-consumer đọc `task-events.dlq` thấy event gốc.
+#
+# API-level thuần curl — chạy được mọi nơi có bash + curl (GitHub CI, Git Bash
+# Windows, Linux). Bước DLQ cần docker (exec trong container kafka) — tắt cả
+# khối saga bằng SMOKE_SAGA=0 (đường B native không Kafka). Browser walkthrough
+# KHÔNG nằm ở đây (human gate tại checkpoint — xem docs/walkthrough.md).
+#
+# Env:
+#   GATEWAY_URL        (default http://localhost:8080)
+#   SMOKE_EMAIL        (default alice@demo.local)
+#   SMOKE_PASSWORD     (default demo-password)
+#   SMOKE_SAGA         (default 1 — chạy saga path + DLQ assert; 0 = happy + auth
+#                      only, dùng cho môi trường không Kafka/docker — đường B)
+#   SMOKE_FAIL_USER_ID (default svc-fail fixture UUID — contracts/auth/users.json;
+#                      go consumer simulate fail khi assigneeId trùng user này)
+#   SMOKE_FEED_RETRIES (default 30 — outbox relay 500ms + Kafka latency; nới từ
+#                      10 của SF-7 vì chuỗi giờ qua Kafka thật, CI 10 services
+#                      cạnh tranh CPU)
+#   SMOKE_SAGA_RETRIES (default 60 — saga: relay + go retry ×3 backoff 500ms +
+#                      compensating publish + node compensation UPDATE)
+#
+# Exit 0 = PASS; exit N = fail ở bước N (in rõ bước fail).
+# Lịch sử đánh số (bảo toàn contract exit N = fail bước N): FI-81 8 bước nhãn
+# /8 (exit tới 10); VU-64 +6 bước auth-real → nhãn /15, exit = label+1 (tới 16,
+# unique từng bước) — marker
+# `SAGA_TASK_ID=` + `SMOKE_SAGA=0` exit 0 giữ nguyên (CI convergence.yml parse).
+# ============================================================================
+set -u
+
+GW="${GATEWAY_URL:-http://localhost:8080}"
+EMAIL="${SMOKE_EMAIL:-alice@demo.local}"
+PASSWORD="${SMOKE_PASSWORD:-demo-password}"
+SAGA="${SMOKE_SAGA:-1}"
+FAIL_USER="${SMOKE_FAIL_USER_ID:-55555555-5555-4555-8555-555555555555}"
+PREFIX="${SMOKE_TITLE_PREFIX:-smoke}"
+RETRIES="${SMOKE_FEED_RETRIES:-30}"
+SAGA_RETRIES="${SMOKE_SAGA_RETRIES:-60}"
+TITLE="$PREFIX-$(date +%s)-$$"
+SAGA_TITLE="$PREFIX-saga-$(date +%s)-$$"
+# user register mỗi run — email unique theo ts+pid (tránh 409 trên stack sống lâu)
+REGISTER_EMAIL="$PREFIX-auth-$(date +%s)-$$@demo.local"
+
+say() { echo "[smoke] $*"; }
+fail() { echo "[smoke] FAIL bước $1: $*" >&2; exit "$1"; }
+extract() { # extract <json-field> <body-file> — grep thuần, không jq
+  # -n + /p (POSIX) thay cho GNU-only "s/.../\1/;t;d" — BSD sed (macOS) đọc
+  # ";d" sau t thành label undefined → fail bước 3 trên máy dev macOS
+  sed -E -n "s/.*\"$1\"[: ]*\"?([^\",}]+)\"?.*/\1/p" "$2" | head -1
+}
+CURL="curl -s --max-time 5" # timeout cụ thể — hung curl = treo CI tới 6h (P1 code-review SF-7)
+
+command -v curl >/dev/null || fail 1 "curl không có trong PATH"
+
+# dọn temp files (chứa token/body) kể cả khi fail giữa chừng (P2 security-audit SF-7)
+# init rỗng TRƯỚC trap — set -u sẽ lỗi unbound khi trap fire trước khi mktemp chạy
+LOGIN_BODY=""; STATS_BEFORE=""; TASK_BODY=""; FEED_BODY=""; STATS_AFTER=""
+REGISTER_BODY=""; REFRESH_BODY=""; RBAC_403_BODY=""
+SAGA_TASK_BODY=""; SAGA_GET_BODY=""; DLQ_OUT=""; DLQ_ERR=""
+trap 'rm -f "$LOGIN_BODY" "$STATS_BEFORE" "$TASK_BODY" "$FEED_BODY" "$STATS_AFTER" "$REGISTER_BODY" "$REFRESH_BODY" "$RBAC_403_BODY" "$SAGA_TASK_BODY" "$SAGA_GET_BODY" "$DLQ_OUT" "$DLQ_ERR"' EXIT 2>/dev/null || true
+
+# compose file resolve từ vị trí script — e2e.sh chạy được từ repo root lẫn platform/
+# (script nằm ở scripts/smoke/ → lên 2 cấp mới tới platform/ — bug `../platform`
+# = scripts/platform từng làm mọi docker exec trong script fail âm thầm run 1-4)
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+COMPOSE_FILE="$SCRIPT_DIR/../../platform/docker-compose.yml"
+COMPOSE_ENV="$SCRIPT_DIR/../../platform/.env.example"
+
+# --- Bước 1: gateway + auth-svc ready (poll — gateway không có /readyz riêng,
+#            conventions/02 rule 3; /api/auth/readyz = auth-svc qua gateway) ---
+READY=0
+for _ in $(seq 1 30); do
+  if curl -sf --max-time 3 "$GW/api/auth/readyz" 2>/dev/null | grep -q '"status":"ok"'; then READY=1; break; fi
+  sleep 1
+done
+[ "$READY" = "1" ] || fail 2 "gateway/auth-svc chưa ready sau 30s ($GW/api/auth/readyz)"
+say "1/15 gateway + auth-svc ready (readyz = migration + seed xong)"
+
+# --- Bước 2: login → accessToken ---
+LOGIN_BODY="$(mktemp)"
+HTTP=$($CURL -o "$LOGIN_BODY" -w '%{http_code}' -X POST "$GW/api/auth/login" \
+  -H 'Content-Type: application/json' \
+  -d "{\"email\":\"$EMAIL\",\"password\":\"$PASSWORD\"}")
+[ "$HTTP" = "200" ] || fail 3 "login HTTP $HTTP (expect 200): $(cat "$LOGIN_BODY")"
+TOKEN="$(extract accessToken "$LOGIN_BODY")"
+# không in body login (chứa token) — chỉ báo shape field (P2 security-audit SF-7)
+[ -n "$TOKEN" ] && [ "${#TOKEN}" -gt 40 ] || fail 3 "login 200 nhưng thiếu accessToken hợp lệ (field accessToken không parse được — kiểm shape LoginResponse contract)"
+say "2/15 login OK (token ${#TOKEN} chars)"
+
+# --- Bước 3: baseline stats (go-svc) TRƯỚC khi tạo task — poll: gateway route
+#            go-svc service_started → 502 đầu là bình thường, retry KHÔNG abort ---
+STATS_BEFORE="$(mktemp)"
+GOT=0
+for _ in $(seq 1 30); do
+  HTTP=$($CURL -o "$STATS_BEFORE" -w '%{http_code}' "$GW/api/activity/stats" \
+    -H "Authorization: Bearer $TOKEN" 2>/dev/null) || { sleep 1; continue; }
+  [ "$HTTP" = "200" ] && { GOT=1; break; }
+  sleep 1
+done
+[ "$GOT" = "1" ] || fail 4 "stats baseline không 200 sau 30 lần retry (go-svc chưa sẵn sàng?) — HTTP cuối $HTTP"
+BASELINE="$(extract totalTasks "$STATS_BEFORE")"
+case "$BASELINE" in ''|*[!0-9]*) fail 4 "totalTasks baseline không parse được: $(cat "$STATS_BEFORE")";; esac
+say "3/15 stats baseline totalTasks=$BASELINE"
+
+# --- Bước 4: tạo task (node-svc; event task.created ghi outbox cùng tx) ---
+TASK_BODY="$(mktemp)"
+PAYLOAD="{\"title\":\"$TITLE\",\"description\":\"SF-5 e2e happy\"}"
+HTTP=$($CURL -o "$TASK_BODY" -w '%{http_code}' -X POST "$GW/api/tasks" \
+  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
+  -d "$PAYLOAD")
+[ "$HTTP" = "201" ] || fail 5 "tạo task HTTP $HTTP (expect 201): $(cat "$TASK_BODY")"
+TASK_ID="$(extract id "$TASK_BODY")"
+[ -n "$TASK_ID" ] || fail 5 "task id không parse được: $(cat "$TASK_BODY")"
+say "4/15 task tạo OK id=$TASK_ID title=$TITLE"
+
+# --- Bước 5: feed phản ánh QUA KAFKA (outbox relay 500ms → topic task-events →
+#            go consumer → persist; poll RETRIES×1s — nới từ SF-7 vì chuỗi giờ
+#            qua Kafka thật: relay 500ms + Kafka latency + consumer lag) ---
+FEED_BODY="$(mktemp)"
+FOUND=0
+for _ in $(seq 1 "$RETRIES"); do
+  HTTP=$($CURL -o "$FEED_BODY" -w '%{http_code}' "$GW/api/activity/feed?limit=20" \
+    -H "Authorization: Bearer $TOKEN" 2>/dev/null) || { sleep 1; continue; }
+  # non-200 (vd 502 go-svc chưa bind) → retry, KHÔNG abort (readiness poll)
+  if [ "$HTTP" = "200" ] && grep -q '"action":"task.created"' "$FEED_BODY" \
+     && grep -q "\"taskTitle\":\"$TITLE\"" "$FEED_BODY"; then
+    FOUND=1; break
+  fi
+  sleep 1
+done
+[ "$FOUND" = "1" ] || fail 6 "feed không thấy action=task.created + taskTitle=$TITLE sau ${RETRIES}s retry (kiểm: outbox relay chạy? go consumer group go-svc-activity consume?)"
+say "5/15 feed có task.created + taskTitle=$TITLE (qua outbox → Kafka → go-svc)"
+
+# --- Bước 6: stats tăng (go-svc đọc readonly schema tasks — exit criterion readonly) ---
+STATS_AFTER="$(mktemp)"
+GOT=0
+for _ in $(seq 1 30); do
+  HTTP=$($CURL -o "$STATS_AFTER" -w '%{http_code}' "$GW/api/activity/stats" \
+    -H "Authorization: Bearer $TOKEN" 2>/dev/null) || { sleep 1; continue; }
+  [ "$HTTP" = "200" ] && { GOT=1; break; }
+  sleep 1
+done
+[ "$GOT" = "1" ] || fail 7 "stats sau không 200 sau 30 lần retry — HTTP cuối $HTTP"
+AFTER="$(extract totalTasks "$STATS_AFTER")"
+case "$AFTER" in ''|*[!0-9]*) fail 7 "totalTasks sau không parse được: $(cat "$STATS_AFTER")";; esac
+[ "$AFTER" -ge $((BASELINE + 1)) ] || fail 7 "stats không tăng: before=$BASELINE after=$AFTER"
+say "6/15 stats totalTasks: $BASELINE → $AFTER"
+
+# ============================================================================
+# AUTH-REAL PATH (SF-5 VU-64): register → refresh rotation → reuse-detect →
+# logout idempotent → RBAC DELETE (user 403 / admin 200). Chạy CẢ khi
+# SMOKE_SAGA=0 — auth thật là luồng độc lập với saga (acceptance epic #2/#4).
+# ============================================================================
+# --- Bước 7: register user mới → 201 AuthSession (roles gán ["user"] — spec §Register) ---
+REGISTER_BODY="$(mktemp)"
+HTTP=$($CURL -o "$REGISTER_BODY" -w '%{http_code}' -X POST "$GW/api/auth/register" \
+  -H 'Content-Type: application/json' \
+  -d "{\"email\":\"$REGISTER_EMAIL\",\"password\":\"smoke-password-1\",\"displayName\":\"Smoke E2E\"}")
+# P2 security-audit SF-5: nhánh fail KHÔNG in body (body có thể chứa AuthSession nếu
+# service buggy trả success-code-sai) — chỉ in tên field, nhất quán policy bước login
+[ "$HTTP" = "201" ] || fail 8 "register HTTP $HTTP (expect 201) — fields: $(grep -o '"[a-zA-Z]\+":' "$REGISTER_BODY" | tr '\n' ' ')"
+grep -q '"roles":\["user"\]' "$REGISTER_BODY" || fail 8 "register response thiếu roles [\"user\"] (shape v2 — kiểm auth.yaml)"
+USER_TOKEN="$(extract accessToken "$REGISTER_BODY")"
+RT1="$(extract refreshToken "$REGISTER_BODY")"
+[ -n "$USER_TOKEN" ] && [ -n "$RT1" ] || fail 8 "register 201 nhưng thiếu cặp token (shape AuthSession — kiểm contracts/openapi/auth.yaml)"
+say "7/15 register OK $REGISTER_EMAIL (roles user — không in token)"
+
+# --- Bước 8: refresh rotation CAS → 200 cặp mới, token cũ bị revoke trong cùng tx ---
+REFRESH_BODY="$(mktemp)"
+HTTP=$($CURL -o "$REFRESH_BODY" -w '%{http_code}' -X POST "$GW/api/auth/refresh" \
+  -H 'Content-Type: application/json' -d "{\"refreshToken\":\"$RT1\"}")
+[ "$HTTP" = "200" ] || fail 9 "refresh HTTP $HTTP (expect 200) — fields: $(grep -o '"[a-zA-Z]\+":' "$REFRESH_BODY" | tr '\n' ' ')"
+RT2="$(extract refreshToken "$REFRESH_BODY")"
+[ -n "$RT2" ] && [ "$RT2" != "$RT1" ] || fail 9 "refresh 200 nhưng refreshToken không rotate (giống token cũ?)"
+say "8/15 refresh rotation OK (token mới khác token cũ)"
+
+# --- Bước 9: REUSE token đã rotate → 401 + revoke TẤT CẢ refresh của user (strict) ---
+HTTP=$($CURL -o /dev/null -w '%{http_code}' -X POST "$GW/api/auth/refresh" \
+  -H 'Content-Type: application/json' -d "{\"refreshToken\":\"$RT1\"}")
+[ "$HTTP" = "401" ] || fail 10 "reuse refresh cũ HTTP $HTTP (expect 401 — reuse-detect strict token-contract §3)"
+say "9/15 reuse-detect OK (token cũ → 401 + revoke-all)"
+
+# --- Bước 10: logout idempotent → 204 (RT2 đã bị revoke-all ở bước 9 — vẫn 204,
+#             đúng contract "token lạ/đã revoke vẫn 204, không leak") ---
+HTTP=$($CURL -o /dev/null -w '%{http_code}' -X POST "$GW/api/auth/logout" \
+  -H 'Content-Type: application/json' -d "{\"refreshToken\":\"$RT2\"}")
+[ "$HTTP" = "204" ] || fail 11 "logout HTTP $HTTP (expect 204 idempotent)"
+say "10/15 logout OK (204 — idempotent trên token đã revoke)"
+
+# --- Bước 11: RBAC — user roles ["user"] DELETE task của alice → 403 FORBIDDEN
+#             (envelope conventions/04; enforcement ở node-svc, gateway chỉ presence) ---
+RBAC_403_BODY="$(mktemp)"
+HTTP=$($CURL -o "$RBAC_403_BODY" -w '%{http_code}' -X DELETE "$GW/api/tasks/$TASK_ID" \
+  -H "Authorization: Bearer $USER_TOKEN")
+[ "$HTTP" = "403" ] || fail 12 "DELETE task bởi user thường HTTP $HTTP (expect 403 — RBAC admin-only SF-3): $(cat "$RBAC_403_BODY")"
+grep -q '"code":"FORBIDDEN"' "$RBAC_403_BODY" || fail 12 "403 nhưng thiếu envelope FORBIDDEN (conventions/04): $(cat "$RBAC_403_BODY")"
+say "11/15 RBAC OK — user thường DELETE → 403 FORBIDDEN"
+
+# --- Bước 12: alice (admin) DELETE cùng task → 204 (contract tasks.yaml —
+#             DELETE trả 204 No Content; prose plan ghi "200" là sơ sài) ---
+HTTP=$($CURL -o /dev/null -w '%{http_code}' -X DELETE "$GW/api/tasks/$TASK_ID" \
+  -H "Authorization: Bearer $TOKEN")
+[ "$HTTP" = "204" ] || fail 13 "DELETE task bởi alice HTTP $HTTP (expect 204 — tasks.yaml §delete)"
+say "12/15 RBAC OK — alice DELETE → 204 (task xoá thật)"
+
+# ============================================================================
+# SAGA PATH (2 chiều — context pack sf-5): assign svc-fail → assignment_failed
+# + DLQ assert. SMOKE_SAGA=0 để tắt (môi trường không Kafka/docker — đường B).
+# ============================================================================
+if [ "$SAGA" = "1" ]; then
+  # --- Bước 13: tạo task riêng cho saga + PATCH assigneeId = svc-fail ---
+  # (task riêng — taskId unique để assert DLQ không lẫn message khác)
+  SAGA_TASK_BODY="$(mktemp)"
+  HTTP=$($CURL -o "$SAGA_TASK_BODY" -w '%{http_code}' -X POST "$GW/api/tasks" \
+    -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
+    -d "{\"title\":\"$SAGA_TITLE\",\"description\":\"SF-5 e2e saga\"}")
+  [ "$HTTP" = "201" ] || fail 14 "tạo task saga HTTP $HTTP (expect 201): $(cat "$SAGA_TASK_BODY")"
+  SAGA_TASK_ID="$(extract id "$SAGA_TASK_BODY")"
+  [ -n "$SAGA_TASK_ID" ] || fail 14 "task saga id không parse được: $(cat "$SAGA_TASK_BODY")"
+  HTTP=$($CURL -o /dev/null -w '%{http_code}' -X PATCH "$GW/api/tasks/$SAGA_TASK_ID" \
+    -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
+    -d "{\"assigneeId\":\"$FAIL_USER\"}")
+  [ "$HTTP" = "200" ] || fail 14 "PATCH assigneeId=$FAIL_USER HTTP $HTTP (expect 200): task $SAGA_TASK_ID"
+  say "13/15 saga: PATCH task $SAGA_TASK_ID assigneeId=svc-fail OK — chờ go retry ×3 → compensating"
+
+  # --- Bước 14: poll GET task → status assignment_failed (node compensation
+  #            consumer conditional UPDATE; chuỗi: relay 500ms → go consume →
+  #            fail ×3 backoff 500ms → publish task.assignment_failed → node
+  #            consume → UPDATE — tổng có thể >10s trên CI load) ---
+  SAGA_GET_BODY="$(mktemp)"
+  GOT=0
+  for _ in $(seq 1 "$SAGA_RETRIES"); do
+    HTTP=$($CURL -o "$SAGA_GET_BODY" -w '%{http_code}' "$GW/api/tasks/$SAGA_TASK_ID" \
+      -H "Authorization: Bearer $TOKEN" 2>/dev/null) || { sleep 1; continue; }
+    if [ "$HTTP" = "200" ] && grep -q '"status":"assignment_failed"' "$SAGA_GET_BODY"; then
+      GOT=1; break
+    fi
+    sleep 1
+  done
+  [ "$GOT" = "1" ] || fail 15 "task $SAGA_TASK_ID không thành assignment_failed sau ${SAGA_RETRIES}s (kiểm: go consumer retry/DLQ? node-svc-compensation group consume? conditional UPDATE guard?) — body cuối: $(cat "$SAGA_GET_BODY")"
+  say "14/15 saga: task status = assignment_failed (compensation đã chạy)"
+
+  # --- Bước 15: assert DLQ — event gốc (task.assigned cho task saga) phải nằm
+  #            ở task-events.dlq. DLQ message shape (producer.go):
+  #            {"schemaVersion":1,"originalEvent":"{...\"taskId\":\"<uuid>\"...}",
+  #            "error":{...}} — grep taskId đủ chứng minh event gốc present.
+  #            Run 3/4 lesson: docker compose exec TỪ TRONG script này fail âm
+  #            thầm trong CI (stderr nuốt) trong khi CÙNG lệnh từ workflow
+  #            run: block đọc được DLQ message 3/3 run (dump step). → assert ở
+  #            đây là best-effort (surface stderr, đoán nguyên nhân); assert
+  #            CHÍNH THỨC nằm ở CI step "Assert DLQ" sau step này (parse marker
+  #            SAGA_TASK_ID= bên dưới). Chạy standalone (máy có compose) thì
+  #            assert ở đây vẫn là assert thật. ---
+  command -v docker >/dev/null || fail 16 "docker không có trong PATH — không assert DLQ được (set SMOKE_SAGA=0 nếu môi trường không có Kafka)"
+  DLQ_OUT="$(mktemp)"
+  DLQ_ERR="$(mktemp)"
+  DLQ_ARRIVED=0
+  for attempt in 1 2 3 4 5 6; do
+    DLQ_END="$(docker compose -f "$COMPOSE_FILE" --env-file "$COMPOSE_ENV" exec -T kafka \
+      /opt/kafka/bin/kafka-get-offsets.sh --bootstrap-server localhost:9092 \
+      --topic task-events.dlq 2>"$DLQ_ERR" | sed -E 's/.*:([0-9]+)$/\1/')"
+    case "$DLQ_END" in ''|*[!0-9]*) DLQ_END=0;; esac
+    if [ "$DLQ_END" -ge 1 ]; then DLQ_ARRIVED=1; break; fi
+    [ "$attempt" -lt 6 ] && sleep 5
+  done
+  if [ "$DLQ_ARRIVED" = "1" ]; then
+    docker compose -f "$COMPOSE_FILE" --env-file "$COMPOSE_ENV" exec -T kafka \
+      /opt/kafka/bin/kafka-console-consumer.sh --bootstrap-server localhost:9092 \
+      --topic task-events.dlq --from-beginning --timeout-ms 10000 > "$DLQ_OUT" 2>/dev/null
+    if [ ! -s "$DLQ_OUT" ]; then
+      # offset > 0 nhưng console-consumer trả output RỖNG = KHÔNG đọc được
+      # (exec/tool fail), khác với "đọc được mà không có taskId" (P2 reviewer)
+      fail 16 "DLQ có message (offset $DLQ_END) nhưng console-consumer trả output RỖNG — không đọc được (kiểm exec/tool)"
+    fi
+    if grep -q "$SAGA_TASK_ID" "$DLQ_OUT"; then
+      say "15/15 DLQ: event gốc của task $SAGA_TASK_ID có mặt ở task-events.dlq (end offset $DLQ_END) — acceptance saga đủ 2 nửa (status + DLQ)"
+    else
+      fail 16 "DLQ có message (offset $DLQ_END) nhưng không thấy taskId=$SAGA_TASK_ID — dlq output: $(head -c 400 "$DLQ_OUT")"
+    fi
+  else
+    # tool exec không trả output từ trong script (CI quirk — stderr giữ lại để
+    # chẩn đoán) → KHÔNG fail ở đây: marker dưới cho CI step assert chính thức
+    say "15/15 DLQ assert best-effort không chạy được từ trong script (stderr: $(head -c 200 "$DLQ_ERR" | tr '\n' ' ')) — ủy quyền CI step 'Assert DLQ'"
+  fi
+  # Marker cho CI step assert DLQ chính thức (convergence.yml) — LUÔN in khi saga chạy
+  say "SAGA_TASK_ID=$SAGA_TASK_ID"
+else
+  say "SMOKE_SAGA=0 — bỏ qua saga path + DLQ assert (chạy happy only)"
+fi
+
+say "PASS — chuỗi auth-svc → node-svc (outbox → Kafka) → go-svc liền mạch qua gateway $GW$( [ "$SAGA" = "1" ] && echo ' + saga compensation → assignment_failed → DLQ' )"

package/stack-template/scripts/snapshot-stack-template.sh

@@ -0,0 +1,84 @@
+#!/usr/bin/env bash
+# ============================================================================
+# snapshot-stack-template.sh — sinh app/stack-template/ từ repo hiện tại.
+# Nguồn template cho create-wakii-stack; engine prune theo stack-manifest.json.
+#
+# Thiết kế tầng 1 (brief Mission #8):
+# - rsync FULL repo trừ build-artifacts + nội bộ team — template chạy được ngay.
+# - Placeholder hoá CHỈ chỗ an toàn: root package.json "name" + README H1 +
+#   compose `name:` → __STACK_NAME__; wakii-dev trong README + docs hướng dẫn
+#   → __STACK_ORG__. KHÔNG sed trong services/ — tên compose service giữ
+#   nguyên để `docker compose up` chạy được ngay sau scaffold.
+# - Idempotent: khi template đã tồn tại phải chạy --force (xoá cũ, sinh mới).
+#   stack-manifest.json được GIỮ qua các lần regen (backup trước xoá, restore
+#   sau rsync) — nguồn chân lý prune không bao giờ mất khi refresh template.
+# ============================================================================
+set -euo pipefail
+cd "$(dirname "$0")/.."
+
+DEST="app/stack-template"
+MANIFEST="$DEST/stack-manifest.json"
+
+if [ "${1:-}" != "--force" ] && [ -e "$DEST" ]; then
+  echo "✗ $DEST đã tồn tại — chạy lại với --force để xoá và sinh mới"; exit 1
+fi
+
+# Giữ manifest qua regen
+KEPT=""
+if [ -f "$MANIFEST" ]; then
+  KEPT="$(mktemp)"
+  cp "$MANIFEST" "$KEPT"
+fi
+
+[ -e "$DEST" ] && rm -rf "$DEST"
+mkdir -p "$DEST"
+
+rsync -a \
+  --exclude='/app/stack-template/' \
+  --exclude='.git/' \
+  --exclude='node_modules/' \
+  --exclude='dist/' \
+  --exclude='storybook-static/' \
+  --exclude='coverage/' \
+  --exclude='.vercel/' \
+  --exclude='.env' \
+  --exclude='*.log' \
+  --exclude='docs/team/' \
+  --exclude='docs/superpowers/evidence/' \
+  ./ "$DEST/"
+
+# Restore manifest giữ từ lần sinh trước
+if [ -n "$KEPT" ]; then cp "$KEPT" "$MANIFEST"; rm -f "$KEPT"; fi
+
+# Placeholder hoá — python chính xác từng chỗ (không sed lan), KHÔNG vào services/
+python3 - "$DEST" <<'PY'
+import json, pathlib, sys
+
+dest = pathlib.Path(sys.argv[1])
+
+# 1) root package.json "name" → __STACK_NAME__
+pkg = dest / 'package.json'
+data = json.loads(pkg.read_text())
+data['name'] = '__STACK_NAME__'
+pkg.write_text(json.dumps(data, indent=2, ensure_ascii=False) + '\n')
+
+# 2) README.md H1 → __STACK_NAME__ (+ wakii-dev → __STACK_ORG__)
+readme = dest / 'README.md'
+lines = readme.read_text().split('\n')
+if lines and lines[0].startswith('# '):
+    lines[0] = '# __STACK_NAME__'
+readme.write_text('\n'.join(lines).replace('wakii-dev', '__STACK_ORG__'))
+
+# 3) compose name: → __STACK_NAME__ (chỉ dòng name: — không đụng service blocks)
+compose = dest / 'platform' / 'docker-compose.yml'
+compose.write_text(compose.read_text().replace('name: boilerplate', 'name: __STACK_NAME__'))
+
+# 4) wakii-dev → __STACK_ORG__ trong docs hướng dẫn (*.md dưới docs/ — hiện chỉ
+#    git-flow.md chứa; ADR/spec history không chứa nên nguyên vẹn)
+for md in (dest / 'docs').rglob('*.md'):
+    text = md.read_text()
+    if 'wakii-dev' in text:
+        md.write_text(text.replace('wakii-dev', '__STACK_ORG__'))
+PY
+
+echo "✓ $DEST sinh xong — $(find "$DEST" -type f | wc -l | tr -d ' ') files"

package/stack-template/services/auth-svc/.dockerignore

@@ -0,0 +1,5 @@
+node_modules
+dist
+coverage
+.vitest
+README.md

package/stack-template/services/auth-svc/Dockerfile

@@ -0,0 +1,32 @@
+# auth-svc — multi-stage theo platform/conventions/01-dockerfile-pattern.md
+# Lockfile: LOCAL pnpm-lock.yaml (thư mục này, pnpm install --ignore-workspace)
+# vì build context = services/auth-svc — root workspace lockfile ngoài context.
+# Build trong image (CI checkout không có dist/) — tsconfig excludes *.test.ts
+# và *.test-support.ts.
+# argon2: @node-rs/argon2 = napi prebuilt (kể cả linux-x64-musl) — KHÔNG cần
+# python/make/g++ trong image (lý do chọn thay node-argon2 native-gyp).
+# users.json KHÔNG nằm trong image — mount runtime từ contracts/auth/users.json
+# (USERS_FIXTURE_PATH, compose SF-5 + CI boot-smoke mount — sửa fixture không
+# cần rebuild, giống auth-mock).
+
+FROM node:22-alpine AS deps
+WORKDIR /app
+COPY package.json pnpm-lock.yaml ./
+RUN corepack enable && pnpm install --frozen-lockfile
+
+FROM deps AS build
+COPY tsconfig.json ./
+COPY src ./src
+RUN pnpm exec tsc -p tsconfig.json
+
+FROM node:22-alpine AS runtime
+WORKDIR /app
+ENV NODE_ENV=production
+COPY --from=deps /app/node_modules ./node_modules
+COPY --from=build /app/dist ./dist
+# migration chạy lúc boot (server.ts) — folder phải nằm cạnh dist/../drizzle
+COPY drizzle ./drizzle
+COPY package.json ./
+USER node
+EXPOSE 8090
+CMD ["node", "dist/server.js"]