create-wakii-stack 0.0.0-stage → 0.1.0

package/stack-template/.claude/agents/fe-dev.md

@@ -0,0 +1,53 @@
+---
+name: fe-dev
+description: Frontend dev agent cho boilerplate MF — mọi việc trong app/ (shell host, remotes tasks/activity, fe-shared logic, ui-kit design system + Storybook, Rspack/Module Federation, vitest component tests). Dùng khi task đụng UI, MF runtime, CSS tokens, hoặc FE build.
+tools: Read, Grep, Glob, Bash, Edit, Write, NotebookEdit
+---
+
+Bạn là FE dev của boilerplate micro-frontend (Rspack + Module Federation + React 19). Làm việc CHỈ trong `app/` trừ khi task nói rõ khác.
+
+## Trước khi code — đọc
+
+1. `CLAUDE.md` (repo root) + `orca.yaml` section `app:`
+2. `docs/adr/0002-mf-rspack.md` — vì sao MF/Rspack + pins
+3. `app/ui-kit/README.md` (design system) + `app/shared/README.md` (logic) + README của package đụng đến (shell/remotes)
+4. Design system: `app/ui-kit/src/styles/tokens.css` + `base.css` + primitives `src/ui/` — UI MỚI phải consume tokens/primitives từ `@wakii/ui-kit`, không tự bịa màu/spacing
+
+## Ràng buộc cứng
+
+- **READ-LOCKED** (cấm sửa ngoài epic được duyệt): `app/shared/src/{api-client,token-storage,error-envelope,mf-bootstrap}.ts`, `package.json#mfToolkit`. Design system (`app/ui-kit`) KHÔNG locked — đổi qua story thường (ADR-0009).
+- **Pins** (catalog: trong `pnpm-workspace.yaml` — react 19.3.0, rspack 1.7.12, @module-federation/enhanced 0.21.6): nâng cấp PHẢI re-spike qua `app/spike` trước, có evidence load thật.
+- fe-shared consumed **qua source** — không thêm build step cho shared; remote **standalone tự mang tokens** (import tokens trong entry, quyết định epic VU-53 #5).
+- MF entry host cần async boundary (`import('./bootstrap')`); JSX automatic runtime (jsc.transform.react.runtime='automatic').
+- Styles scoped theo pattern sẵn có (`.tsk-*`, `.act-*`…) — không global leakage giữa remote và shell.
+- UI mới bám design direction hiện có: nền tối, 1 accent indigo, badge pill chấm-màu, không box-shadow (xem `docs/superpowers/evidence/ui-redesign/` làm mẫu).
+
+## Commands
+
+```bash
+pnpm --filter shell dev            # host :3000
+pnpm --filter "@wakii/remote-tasks" dev    # :4001 standalone
+pnpm --filter "@wakii/remote-activity" dev # :4002 standalone
+pnpm --filter shell test && pnpm --filter shell typecheck
+pnpm --filter "@wakii/remote-tasks" test   # vitest run
+pnpm --filter "@wakii/ui-kit" test         # primitives
+pnpm --filter "@wakii/ui-kit" build-storybook  # catalog — evidence khi đổi primitives
+```
+
+Install workspace từ root: `pnpm install --frozen-lockfile`.
+
+## Quy trình
+
+1. Spec/task của story là nguồn sự thật — không tự mở rộng scope UI.
+2. TDD theo pattern suite sẵn có (`tests/*.test.tsx` — vitest + testing-library, TZ pin trong vitest.config đừng bỏ).
+3. Xong = test xanh + typecheck sạch + build được (`pnpm build`). Đổi UI đáng kể → browser-verify + chụp evidence khi làm trong story workflow.
+4. Sửa shared primitives/props API → phải sync hand-off docs + báo các consumer (SF pattern: hand-off §trong `docs/superpowers/designs/`).
+
+## Đừng
+
+- Đừng thêm dependency mới vào fe-shared (giữ lockfile — consumer cung cấp types qua tsconfig paths).
+- Đừng chạy `pnpm install` không --frozen-lockfile ở root khi không đổi dependency.
+- Đừng hardcode port khác `platform/conventions/05-ports.md`.
+
+## Team protocol (2026-10-18)
+Khi chạy trong terminal Orca dưới ZCode lead: xong việc → verify → BÁO CÁO → DỪNG chờ việc mới (không tự chuyển). Phạm vi file đúng đúng brief ("CHỈ <dir> — ngoài CẤM"). Ghi file dùng đường dẫn tuyệt đối từ `app/`. Chi tiết: section "Team protocol" trong CLAUDE.md + board docs/team/TEAM.md.

package/stack-template/.claude/settings.json

@@ -0,0 +1,77 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(git *)",
+      "Bash(gh run list *)",
+      "Bash(gh run view *)",
+      "Bash(gh pr view *)",
+      "Bash(gh api *)",
+      "Bash(node *)",
+      "Bash(npx *)",
+      "Bash(pnpm *)",
+      "Bash(npm *)",
+      "Bash(python3 *)",
+      "Bash(python *)",
+      "Bash(./mvnw *)",
+      "Bash(mvn *)",
+      "Bash(go test *)",
+      "Bash(go build *)",
+      "Bash(go vet *)",
+      "Bash(go run *)",
+      "Bash(go mod *)",
+      "Bash(orca linear issue *)",
+      "Bash(orca linear list-issues *)",
+      "Bash(orca linear search *)",
+      "Bash(orca linear team *)",
+      "Bash(orca orchestration check *)",
+      "Bash(orca orchestration send *)",
+      "Bash(orca orchestration reply *)",
+      "Bash(orca orchestration task-list *)",
+      "Bash(orca terminal read *)",
+      "Bash(orca terminal list *)",
+      "Bash(orca worktree ps *)",
+      "Bash(orca tab create *)",
+      "Bash(orca tab close *)",
+      "Bash(orca snapshot *)",
+      "Bash(orca get *)",
+      "Bash(orca is *)",
+      "Bash(orca eval *)",
+      "Bash(orca file open-changed *)",
+      "Bash(~/.claude/bin/wakii-validate *)",
+      "Bash(~/.claude/bin/story-verify *)",
+      "Bash(~/.claude/bin/linear-rate-limit check*)",
+      "Bash(~/.claude/bin/story-pr-checks *)",
+      "Bash(spectral *)",
+      "Bash(cat *)",
+      "Bash(ls *)",
+      "Bash(head *)",
+      "Bash(tail *)",
+      "Bash(grep *)",
+      "Bash(find *)",
+      "Bash(diff *)",
+      "Bash(wc *)",
+      "Bash(mkdir *)",
+      "Bash(cp *)",
+      "Bash(curl http://localhost*)",
+      "Bash(sleep *)",
+      "Bash(echo *)",
+      "Bash(~/.claude/bin/linear-rate-limit run *)",
+      "Bash(orca orchestration run-list *)",
+      "Bash(orca orchestration run-show *)",
+      "Bash(orca orchestration run-current *)",
+      "Bash(orca orchestration inbox *)",
+      "Bash(docker *)",
+      "Bash(gh pr create *)",
+      "Bash(gh pr edit *)",
+      "Bash(gh pr merge *)",
+      "Bash(gh pr checks *)",
+      "Bash(go get *)",
+      "Bash(curl *)",
+      "Bash(ruby *)",
+      "Bash(sed *)",
+      "Bash(tee *)",
+      "Bash(bash scripts/*)",
+      "Bash(bash scripts/**)"
+    ]
+  }
+}

package/stack-template/.claude/settings.local.json

@@ -0,0 +1,9 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(cd platform *)",
+      "mcp__wakii-story__story_bracket_read",
+      "mcp__wakii-story__story_watchdog_status"
+    ]
+  }
+}

package/stack-template/.claude/skills/add-service/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: add-service
+description: Use when cần thêm microservice mới vào services/ của boilerplate — "tạo service", "thêm notification-svc", service consume Kafka task-events, service có DB riêng, thêm BE service. KHÔNG dùng khi sửa service có sẵn (task thường), scaffold project mới (scripts/scaffold/scaffold.sh), hay thêm FE remote (playbook FE archetype).
+---
+
+# add-service — thêm service mới vào boilerplate
+
+## Overview
+
+Thủ tục theo tầng contracts-first: **khung boot xanh TRƯỚC, impl SAU, hội tụ CUỐI**.
+Nguồn sự thật kỹ thuật là `platform/conventions/01–09` + `docs/wakii-playbook.md` (archetype
+NS) — skill này chỉ đóng khung THỨ TỰ + GATES + lệnh verify. Không copy convention vào đây.
+
+## Phase 0 — HỎI trước khi tính slice (không tự quyết)
+
+5 câu hỏi đổi hình dạng toàn bộ việc còn lại — đặt cho user/epic, kèm khuyến nghị:
+
+| Câu hỏi | Đổi gì |
+|---|---|
+| Sync hay async? | Có Kafka → conventions/09 + topic tạo tường minh trước consumer subscribe |
+| Ngôn ngữ? (Node/Spring/Go — cấm stack ngoài 3 cái, ADR-0001) | Node ngoài workspace → standalone lockfile; Go → distroless (không healthcheck shell, gate `service_started`) + drift-guard snapshot |
+| Có DB riêng? | DDL `contracts/db/` + role schema-only trong `platform/postgres/init/01-init.sh` |
+| Port mấy? | Quy tắc 4 chỗ cùng commit: conventions/05 + .env.example + compose + README |
+| FE có hiển thị? | Có → tách SF riêng (playbook NS), không gộp vào SF impl |
+
+Rồi chốt: **story mode 4 SF** (mặc định cho service mới) hay single workflow (service cực nhỏ,
+không Kafka, không DB). Phải là story được duyệt — compose/gateway/init là file dùng chung có
+boundary "đụng = flag coordinator kèm gap-answer" (header docker-compose.yml).
+
+## Công thức 4 SF — mỗi SF có checkpoint tường minh
+
+**SF-1 · Khung (tier 0) — DONE khi `docker compose up` riêng service boot + healthcheck xanh,
+impl còn rỗng:**
+1. `contracts/openapi/<svc>.yaml` (mẫu: `contracts/openapi/activity.yaml` — nhỏ nhất) — healthz +
+   readyz **mirror cả naked lẫn dưới prefix** (schemathesis 404 nếu thiếu — conventions/02 rule 6)
+   → verify: `pnpm lint:contracts`
+2. Nếu có DB: `contracts/db/<svc>-schema.sql` (mirror `tasks-schema.sql`, dedupe key là
+   envelope_id — KHÔNG taskId) + role/schema-only trong init script → verify: fresh volume
+   (`docker compose down -v && up -d postgres`) rồi `\dn <schema>` + login role
+3. Compose entry qua **gap-answer cho coordinator** (port/env/healthcheck/depends_on — KHÔNG
+   depends_on kafka, lazy-connect) → verify: `docker compose -f platform/docker-compose.yml
+   --env-file platform/.env.example config -q`
+4. `.env.example` thêm biến `:?set` fail-fast (password = placeholder `change-me-*` — gitleaks)
+5. CI copy `.github/workflow-templates/services-ci.yml.example` → `services-<svc>.yml`
+   (path filter kèm contracts path + `permissions: contents: read`) → verify: ruby YAML parse
+6. Dockerfile theo conventions/01; gateway thêm block `location = /api/<svc>` (exact!) +
+   `location /api/<svc>/` với presence-check 401 (thiếu exact-match → rơi vào `location /` nhận
+   HTML của shell)
+
+**SF-2 · Impl API (tier 1):** theo spec SF-1 đã chốt; JWT verify 2 lớp (gateway presence ≠
+enforcement); error handler map mọi lỗi sang envelope conventions/04 → verify: unit + integration
+test, `docker build`, curl healthz/readyz + 401 sai token.
+
+**SF-3 · Async + FE (tier 1, song song SF-2 nếu tách vùng file):** consumer idempotent —
+dedupe qua envelope_id, manual offset commit CHỈ sau DB tx, retry ×3 → DLQ; đăng ký consumer
+group vào `contracts/events/task-events.md` (+1 dòng, KHÔNG bịa event type mới); FE nếu có →
+SF riêng → verify: publish golden fixture từ `contracts/events/fixtures/` ×2, total không đổi
+lần 2 (idempotency chứng minh được).
+
+**SF-4 · Convergence (tier 2):** mở rộng `scripts/smoke/e2e.sh` (giữ exit-code theo bước) +
+convergence CI; docs sync **cùng commit**: conventions 02/03/05/06/08(/09) + README + CLAUDE.md +
+orca.yaml + walkthrough → verify: `bash scripts/smoke/e2e.sh` PASS + `grep -rn "<số services cũ>"
+README.md CLAUDE.md orca.yaml` = rỗng.
+
+## Bẫy đã trả giá thật (trả trước bằng CI đỏ)
+
+| Bẫy | Hậu quả | Chặn |
+|---|---|---|
+| pgdata volume cũ thiếu role/schema mới | boot fail, tưởng code sai | `docker compose down -v` 1 lần; ghi vào walkthrough |
+| Consumer subscribe trước topic tồn tại | kẹt im lặng — 0 fetch 0 error | tạo topic TRƯỚC boot consumer (conventions/09) |
+| Dedupe bằng taskId | mất event hợp lệ khi re-assign | dedupe bằng envelope_id (+recipient nếu fanout) |
+| Thiếu `location =` exact-match | GET /api/<svc> trả HTML 404 của shell | 2 block: exact + prefix |
+| Quên 1/4 chỗ của port | review fail (gotcha tường minh) | 4 chỗ trong 1 commit |
+| Commit offset trước tx | mất event khi crash | manual commit sau DB commit |
+| `.env` commit / password thật | gitleaks đỏ | chỉ `.env.example` + placeholder |
+
+## Đóng story
+
+Full suite (`test_all` trong orca.yaml + service mới) → evidence `docs/superpowers/evidence/`
+(test-run ghi HEAD tại code commit cuối) → review độc lập → `story-verify` → **coordinator
+merge** (executor không tự merge) → post-task-ritual + improvements-log.

package/stack-template/.claude/skills/sync-contracts/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: sync-contracts
+description: Use when sửa API hoặc contract của boilerplate — thêm field vào task/user/event, thêm endpoint, đổi OpenAPI spec, đổi DDL/schema, đổi event payload, "thêm trường", "sửa tasks.yaml", spec lệch code. KHÔNG dùng khi thêm service nguyên con (skill add-service), sửa UI-only không đụng API, hay fix không đổi contract.
+---
+
+# sync-contracts — sửa API theo vòng contracts-first
+
+## Overview
+
+Contract là source of truth: **spec TRƯỚC, code theo sau, verify bằng CI đã có sẵn**
+(spectral, drift-guard, schemathesis, schema-diff test — KHÔNG tự chế gate mới). Skill này
+là THỨ TỰ + QUY TẮC ĐỒNG BỘ CẶP; chi tiết convention nằm ở `platform/conventions/04` (envelope)
++ README từng service.
+
+## Bước 0 — Phân loại thay đổi (quyết story mode, không bỏ qua)
+
+| Loại | Ví dụ | Chạy qua |
+|---|---|---|
+| **Additive** (non-breaking) | field optional mới, response-only field, enum giá trị mới | single workflow được |
+| **Breaking** | field thành required, rename/xoá field, đổi shape/type, đổi enum xoá giá trị | **archetype CC** (`docs/wakii-playbook.md` §2) — SF-1 contracts là hiệp ước; chốt một: tương thích ngược có kiểm soát (token/event cũ còn verify) HOẶC đổi đồng loạt 1 SF |
+
+Breaking trên **event** → `schemaVersion` bump + golden fixtures cập nhật theo. Additive
+payload → KHÔNG bump (consumer bỏ qua field lạ — task-events.md), dùng **presence-based**
+(chỉ gửi khi có giá trị — precedent `description` trong routes/tasks.ts).
+
+## Quy tắc đồng bộ CẶP — các file này phải cùng commit
+
+| Đổi file | Phải kèm |
+|---|---|
+| `contracts/openapi/tasks.yaml` | `contracts/db/tasks-schema.sql` (comment DDL tự quy định) |
+| `contracts/openapi/tasks.yaml` | types node-svc: `pnpm --filter node-svc generate:types` → commit `src/types/api.d.ts` |
+| `contracts/events/task-events.md` | `contracts/events/fixtures/*.json` (golden cùng nguồn node/go test) |
+| `contracts/openapi/activity.yaml` | `services/go-svc/internal/api/openapi/activity.yaml` **copy bit-identical** — drift-guard CI `diff` (đổi tasks/users spec KHÔNG đụng snapshot này) |
+| `services/node-svc/src/db/schema.ts` | migration `drizzle/000N_*.sql` + nếu ALTER shape mới → **mở rộng normalizer** `schema-diff.test.ts` (thử sẵn: nó throw ở action chưa biết) |
+| DDL thêm index | sanity test đếm index sẽ vỡ — cập nhật cùng commit |
+
+## Thứ tự chuẩn (additive field làm mẫu)
+
+1. **Spec**: `contracts/openapi/<svc>.yaml` — schema + Create/Update request; endpoint mới thì
+   nhớ gateway route (`location = /api/<svc>` exact + prefix + presence 401 — skill add-service)
+   → verify `pnpm lint:contracts`
+2. **DDL + schema + migration** (nếu có DB) → verify `pnpm --filter node-svc test` (schema-diff xanh lại)
+3. **node-svc**: generate:types → repo (presence-based patch) → routes body schema
+   (`additionalProperties: false` tự 400 giá trị lạ) → event payload matrix
+4. **go-svc / spring-svc**: additive = **verify-only, KHÔNG sửa** — `go test ./...` pass không
+   edit chính là bằng chứng non-breaking. Fixture mới mà test cũ fail → sửa TEST theo fixture,
+   không sửa fixture ngược
+5. **FE mirror**: `app/remotes/<svc>/src/api.ts` types + UI; `app/shared` READ-LOCKED là
+   pass-through — KHÔNG sửa; primitives/variant mới → `app/ui-kit` (evidence build-storybook)
+6. **Docs**: README service (API table + event matrix) + walkthrough nếu UI đổi — cùng PR
+7. **Convergence**: `bash scripts/smoke/e2e.sh` PASS; optional mở rộng e2e nếu muốn e2e che field mới
+
+## Verify battery (tổng)
+
+```bash
+pnpm lint:contracts
+pnpm --filter node-svc test && pnpm --filter node-svc build   # tsc = typecheck
+cd services/go-svc && go test ./...                            # additive: phải xanh không sửa
+pnpm --filter "@wakii/remote-tasks" test && pnpm --filter "@wakii/remote-tasks" typecheck
+bash scripts/smoke/e2e.sh                                      # cần compose (SMOKE_SAGA=0 nếu không Kafka)
+```
+
+CI tự chạy theo path-trigger: `contracts` (spectral + gitleaks + **schemathesis** — spec sai
+shape so với impl sẽ đỏ ở đây, không cần tự dựng), `services-node-svc` (boot-smoke), `convergence`.
+
+## Bẫy đã gặp
+
+| Bẫy | Chặn |
+|---|---|
+| Sửa fixture để chiều test cũ | Sai chiều — fixture là golden, sửa test |
+| Đổi activity.yaml quên copy snapshot go-svc | Drift-guard đỏ 1 vòng CI vô ích — copy cùng commit |
+| PATCH `field: null` để xoá | Precedent `assigneeId`: contract non-nullable — nếu muốn xoá phải thiết kế riêng |
+| Payload đổi mà quên event matrix trong routes | Test key-set cứng trong app.test.ts sẽ bắt — đọc trước khi sửa |
+| Đổi spec xong code "tự hiểu" | Không có code-theo-suy-diễn — generate:types rồi impl theo types |

package/stack-template/.editorconfig

@@ -0,0 +1,21 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+indent_style = space
+indent_size = 2
+
+[*.java]
+indent_size = 4
+
+[*.go]
+indent_style = tab
+
+[Makefile]
+indent_style = tab
+
+[*.md]
+trim_trailing_whitespace = false

package/stack-template/.gitattributes

@@ -0,0 +1,10 @@
+# Windows dev machine — ép LF toàn repo (learned: mixed eol làm gãy shell script + docker build context)
+* text=auto eol=lf
+
+*.png binary
+*.jpg binary
+*.gif binary
+*.ico binary
+*.jar binary
+*.woff binary
+*.woff2 binary

package/stack-template/.github/pull_request_template.md

@@ -0,0 +1,26 @@
+<!-- Đủ mục dưới đây — PR thiếu evidence = review chậm. Chi tiết flow: docs/git-flow.md -->
+
+## What & Why
+
+<!-- Làm gì + vì sao. Đụng story/epic thì link Linear (FI-xx / VU-xx). -->
+
+## Thay đổi
+
+- <!-- bullet ngắn theo nhóm: code / contracts / CI / docs -->
+
+## Cách verify (bắt buộc)
+
+<!-- Lệnh đã chạy + kết quả. Ví dụ:
+- `pnpm --filter shell test` → 43/43; `pnpm --filter @wakii/ui-kit build-storybook` → PASS
+- `bash scripts/smoke/e2e.sh` → PASS 8/8 (compose 10 services)
+- Local repro bug trước fix → EXIT=1, sau fix → EXIT=0
+-->
+
+## Checklist
+
+- [ ] CI xanh trên PR (kể cả `convergence`)
+- [ ] Không đụng READ-LOCKED (`app/shared/src/*.ts` + `mfToolkit`) ngoài epic đã duyệt
+- [ ] Đụng contract → sync đủ bề mặt (node codegen / go snapshot bit-identical / fixtures 2 đầu)
+- [ ] Không đụng `frontend/` paths cũ (đã rename `app/` từ 2026-10-17 — refs `frontend/` = bug)
+- [ ] Descriptor sync (CLAUDE.md / orca.yaml / agents) nếu đổi cấu trúc, port, lệnh
+- [ ] Docs/evidence cập nhật (walkthrough, ADR nếu đổi kiến trúc, screenshot nếu đổi UI)

package/stack-template/.github/workflow-templates/services-ci.yml.example

@@ -0,0 +1,69 @@
+# ============================================================================
+# TEMPLATE CI per-service — SF-2/3/4 COPY file này thành .github/workflows/
+# services-<svc>.yml rồi điền chỗ đánh dấu <...>. KHÔNG enable nguyên bản
+# (services chưa có code — workflow sẽ fail đỏ vô nghĩa).
+#
+# Pattern bắt buộc (epic spec rev 3): path-filtered per service + boot-smoke job
+# (container up + curl /healthz + /readyz + migration chạy xong).
+# ============================================================================
+name: services-<svc>
+
+on:
+  push:
+    branches: ["**"]
+    paths:
+      - "services/<svc>/**"
+      - "platform/docker-compose.yml"   # compose entry đổi cũng phải re-test
+      - ".github/workflows/services-<svc>.yml"
+  pull_request:
+    paths:
+      - "services/<svc>/**"
+      - "platform/docker-compose.yml"
+
+jobs:
+  build-test:
+    name: build + test (<svc>)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      # --- node-svc (SF-2): pnpm + vitest
+      # - uses: pnpm/action-setup@v4
+      #   with: { version: 9 }
+      # - uses: actions/setup-node@v4
+      #   with: { node-version: 22, cache: pnpm }
+      # - run: pnpm install --frozen-lockfile
+      # - run: pnpm --filter <svc> test
+      # --- spring-svc (SF-3): mvnw trong Docker hoặc setup-java 21
+      # --- go-svc (SF-4): setup-go 1.24
+      - name: <fill in per stack>
+        run: echo "TODO SF-2/3/4"
+
+  docker-build:
+    name: docker build (<svc>)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Build image (multi-stage — platform/conventions/01)
+        run: docker build -t <svc>:ci services/<svc>
+
+  boot-smoke:
+    name: boot-smoke (<svc> + deps)
+    runs-on: ubuntu-latest
+    env:
+      JWT_SECRET: ci-smoke-secret-placeholder-not-real-32chars
+    steps:
+      - uses: actions/checkout@v4
+      - name: Boot service + postgres (+ auth-svc nếu cần JWT)
+        run: |
+          docker compose -f platform/docker-compose.yml --env-file platform/.env.example \
+            up -d --build postgres auth-svc <svc>
+      - name: Smoke — /healthz + /readyz + migration xong
+        run: |
+          # wait rồi grep '"status":"ok"' — pattern giống workflows/contracts.yml
+          for i in $(seq 1 60); do
+            curl -sf http://localhost:<PORT>/readyz >/dev/null && break
+            sleep 2
+          done
+          curl -sf http://localhost:<PORT>/healthz | grep -q '"status":"ok"'
+          curl -sf http://localhost:<PORT>/readyz | grep -q '"status":"ok"'
+          # <svc>-specific: vd node-svc tạo task rồi list lại; go-svc POST event rồi đọc feed

package/stack-template/.github/workflows/contracts.yml

@@ -0,0 +1,133 @@
+name: contracts
+
+# SF-1 (FI-64) — contract lint + compose validate + gitleaks + boot-smoke auth
+# (container up + /healthz + /readyz + login qua gateway + schemathesis).
+# SF-5 (VU-59): boot auth-svc thay auth-mock (decommission) + schemathesis FULL
+# paths (auth-svc implement đủ register/refresh/logout* — hết thời gian scope hẹp).
+on:
+  push:
+    branches: ["**"]
+    paths:
+      - "contracts/**"
+      - "platform/**"
+      - ".github/workflows/contracts.yml"
+      - ".spectral.yaml"
+  pull_request:
+    paths:
+      - "contracts/**"
+      - "platform/**"
+      - ".github/workflows/contracts.yml"
+      - ".spectral.yaml"
+
+permissions:
+  contents: read # least-privilege (P2 security-audit SF-7 — follow-up repo-wide);
+  # job gitleaks giữ permissions riêng (pull-requests: read) — job-level override repo-level
+
+jobs:
+  gitleaks:
+    name: gitleaks (secret scan)
+    runs-on: ubuntu-latest
+    # gitleaks-action đọc PR commits qua API — thiếu pull-requests:read thì 403
+    # "Resource not accessible by integration" (run 38300531175)
+    permissions:
+      contents: read
+      pull-requests: read
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: gitleaks/gitleaks-action@v2
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+  spectral:
+    name: spectral lint (openapi)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Lint contracts/openapi
+        run: npx --yes @stoplight/spectral-cli@6 lint "contracts/openapi/*.yaml"
+
+  compose-config:
+    name: compose config validate
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Validate docker-compose.yml (KHÔNG build — services khung chưa có impl)
+        run: docker compose -f platform/docker-compose.yml --env-file platform/.env.example config -q
+
+  boot-smoke-auth-svc:
+    name: boot-smoke auth-svc (+gateway) + schemathesis
+    runs-on: ubuntu-latest
+    env:
+      JWT_SECRET: ci-smoke-secret-placeholder-not-real-32chars
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Boot trio (postgres + auth-svc + gateway) — chạy postgres init script thật
+        run: |
+          docker compose -f platform/docker-compose.yml --env-file platform/.env.example \
+            up -d --build postgres auth-svc gateway
+
+      - name: Wait /healthz + /readyz (auth-svc trực tiếp — readyz = migration + seed xong)
+        run: |
+          for i in $(seq 1 30); do
+            curl -sf http://localhost:8090/healthz >/dev/null && break
+            sleep 2
+          done
+          curl -sf http://localhost:8090/healthz | grep -q '"status":"ok"'
+          curl -sf http://localhost:8090/readyz  | grep -q '"status":"ok"'
+
+      - name: Gateway routing — login + register QUA gateway :8080 (shape v2)
+        run: |
+          RES=$(curl -s -X POST http://localhost:8080/api/auth/login \
+            -H 'Content-Type: application/json' \
+            -d '{"email":"alice@demo.local","password":"demo-password"}')
+          echo "$RES" | grep -q '"user"'                     # shape v2 — decision #8
+          echo "$RES" | grep -q '"refreshToken"'             # cặp token, không còn expiresIn
+          echo "$RES" | sed -E 's/.*"accessToken":"([^"]+)".*/\1/' > /tmp/jwt
+          # register mở qua gateway (auth.yaml v2 — entry công khai, roles ["user"])
+          # P2 security-audit SF-5: nhánh fail không in body (có thể chứa token) — chỉ field names
+          CODE=$(curl -s --max-time 10 -o /tmp/reg.json -w '%{http_code}' -X POST http://localhost:8080/api/auth/register \
+            -H 'Content-Type: application/json' \
+            -d '{"email":"ci-contracts@example.com","password":"ci-password-1","displayName":"CI Contracts"}')
+          [ "$CODE" = "201" ] || { echo "register qua gateway → $CODE (expect 201) — fields: $(grep -o '"[a-zA-Z]\+":' /tmp/reg.json | tr '\n' ' ')"; exit 1; }
+          rm -f /tmp/reg.json
+
+      - name: Verify JWT claims theo token contract (sub/email/roles, TTL 30m, iss pinned)
+        run: |
+          # JWT = base64url KHÔNG padding — `base64 -d` fail (learned run 38212318058);
+          # decode qua python3 urlsafe_b64decode + tự bổ sung padding
+          PAYLOAD=$(TOKEN=$(cat /tmp/jwt) python3 -c 'import base64, os; seg = os.environ["TOKEN"].split(".")[1]; seg += "=" * (-len(seg) % 4); print(base64.urlsafe_b64decode(seg).decode())')
+          # P2 security-audit SF-5: không echo payload (JWT claims) ra CI log —
+          # các assert grep bên dưới tự in đủ context khi fail
+          echo "$PAYLOAD" | grep -q '"sub":"11111111-1111-4111-8111-111111111111"'
+          echo "$PAYLOAD" | grep -q '"email":"alice@demo.local"'
+          echo "$PAYLOAD" | grep -q '"roles":\["admin"\]'
+          # iss PINNED "auth-mock" — giá trị lịch sử CỐ Ý giữ nguyên (token-contract.md;
+          # decision #7) — KHÔNG đổi theo tên service
+          echo "$PAYLOAD" | grep -q '"iss":"auth-mock"'
+          TTL=$(echo "$PAYLOAD" | jq '.exp - .iat')
+          [ "$TTL" = "1800" ] || { echo "TTL sai: $TTL (expected 1800 = 30m — token-contract.md §1)"; exit 1; }
+
+      - name: Gateway chặn thiếu-token 401 trên /api/tasks (presence check)
+        run: |
+          CODE=$(curl -s -o /tmp/401.json -w '%{http_code}' http://localhost:8080/api/tasks)
+          [ "$CODE" = "401" ] || { echo "expected 401, got $CODE"; exit 1; }
+          grep -q '"code":"UNAUTHORIZED"' /tmp/401.json
+          # /api/auth KHÔNG bị chặn (entry login)
+          CODE2=$(curl -s -o /dev/null -w '%{http_code}' -X POST http://localhost:8080/api/auth/login \
+            -H 'Content-Type: application/json' -d '{}')
+          [ "$CODE2" != "401" ] || { echo "/api/auth bị presence check — sai routing table"; exit 1; }
+
+      - name: Schemathesis contract test (FULL paths — auth.yaml v2)
+        run: |
+          # venv path deterministic — pipx bin dir trên runner không ổn định (run 38213445973)
+          python3 -m venv /tmp/stenv
+          /tmp/stenv/bin/pip install --quiet "schemathesis==3.*"
+          # base-url kèm path /api/auth — schemathesis 3.x bỏ qua servers.url relative (run 38213876943)
+          # SF-5 (VU-64): NỚI FULL — auth-svc implement đủ mọi path spec v2
+          # (register/login/refresh/logout/logout-all/users) → bỏ exclude SF-1.
+          /tmp/stenv/bin/schemathesis run contracts/openapi/auth.yaml \
+            --base-url http://localhost:8090/api/auth \
+            --checks all --hypothesis-max-examples 25 --hypothesis-deadline 5000