create-wakii-stack 0.0.0-stage → 0.1.0

package/stack-template/docs/superpowers/plans/2026-10-17-auth-real-plan.md

@@ -0,0 +1,112 @@
+# Auth Real — Implementation Plan (epic auth thật thay auth-mock) — rev 2
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Thay auth-mock bằng auth-svc thật — register/login/refresh(rotation CAS)/logout + RBAC demo, giữ nguyên surface `:8090 /api/auth/*`.
+
+**Architecture:** CC archetype (wakii-playbook §2): SF-1 contracts là hiệp ước → SF-2/3/4 song song theo vùng file → SF-5 hội tụ + decommission + **CI swap**. auth-svc mirror node-svc patterns.
+
+**Tech Stack:** Fastify 5 · TypeScript · Drizzle (Postgres) · argon2 · HS256 verify giữ nguyên (`iss` **PINNED `"auth-mock"`** — đổi = follow-up riêng) · vitest/node-test.
+
+**Spec:** `docs/superpowers/specs/2026-10-17-auth-real-design.md` **rev 2** — ĐỌC TRƯỚC: 10 decision points (7-10 thêm từ spec-critic + plan-critic: iss pinned, response shape v2, giữ GET /users drop openid, password default demo-password).
+
+---
+
+### Task 1 = SF-1 (tier 0): Contracts + hiệp ước + gap-answer ĐẦY ĐỦ
+
+**Files:**
+- Modify: `contracts/openapi/auth.yaml` (v2 — 5 endpoint mới + giữ `GET /users` + **xoá `/.well-known/openid-configuration`** + response shape v2)
+- Modify: `contracts/auth/token-contract.md` (v2 — chi tiết dưới)
+- Modify: `platform/.env.example` (+`AUTH_DEV_PASSWORD` default **`demo-password`** theo pattern `${VAR:-demo-password}`; +`ACCESS_TOKEN_TTL=30m`; **rename `AUTH_MOCK_PORT`→`AUTH_PORT`, `AUTH_MOCK_DEV_PASSWORD`→`AUTH_DEV_PASSWORD`**)
+- Modify: `.github/workflows/contracts.yml` — **schemathesis scope hẹp lại**: chỉ chạy paths auth-mock đang implement (paths mới thêm sẽ 404 → job đỏ oan). Exclude `register|refresh|logout` khỏi include-path đến SF-5
+- Prepare (KHÔNG commit — gap-answer doc cho coordinator duyệt, SF-5 thực thi): compose entry `auth-mock`→`auth-svc` + key `gateway.depends_on.auth-mock`→`auth-svc` + nginx upstream + go-svc env `AUTH_MOCK_URL` value → `http://auth-svc:8090` + users.json volume mount cho auth-svc + init 01-init.sh thêm role `auth_svc`/schema `auth` + `AUTH_SVC_DB_PASSWORD`
+
+- [x] **Step 1: auth.yaml** — schemas `RegisterRequest{email,password(minLength 8,maxLength 72),displayName}`, `TokenPair{accessToken,refreshToken}`, `RefreshRequest{refreshToken}`; paths `POST /register|/login|/refresh|/logout|/logout-all`; **response login/register = `{user: UserRef, accessToken, refreshToken}` — DROP `tokenType`/`expiresIn` (decision #8, KHÔNG thuần additive)**; `GET /users` giữ (description: serve từ schema auth); xoá discovery stub + cập nhật disclaimer header.
+- [x] **Step 2: mirror healthz/readyz** dưới prefix `/api/auth/` (conventions/02 rule 6).
+- [x] **Step 3: token-contract.md v2** — access TTL `30m`; refresh: opaque 256-bit, **lưu sha256 hash**, TTL **7d**, rotation **CAS atomic** (`UPDATE ... WHERE id=$old AND revoked_at IS NULL RETURNING` — 0 rows = reuse), **reuse → revoke TẤT CẢ refresh_tokens của user + 401** (strict; FE single-flight giảm xác suất — documented); `iss` **PINNED `"auth-mock"`** (3 service + CI hardcode — đổi tên là follow-up riêng); `localStorage['bp.rt']` rationale pin (accepted-for-demo, httpOnly-cookie = upgrade path); ghi "RS256/JWKS = path OIDC, claims không đổi".
+- [x] **Step 4: .env.example** — như Files ở trên (default `demo-password` — KHÔNG `change-me-*`: e2e + svc-activity + seed cùng một nguồn, acceptance #3 phụ thuộc).
+- [x] **Step 5: soạn gap-answer doc đầy đủ** (list ở Files — 8 mục) → FLAG coordinator duyệt. KHÔNG commit compose/nginx/init trong SF-1.
+- [x] **Step 6: Verify** — `pnpm lint:contracts` xanh; CI `contracts` xanh với schemathesis SCOPED (verify job không 404).
+
+### Task 2 = SF-2 (tier 1, song song — vùng `services/auth-svc/**` mới + 2 shared files 1 dòng): auth-svc
+
+**Files:**
+- Create: `services/auth-svc/` (mirror node-svc: src/{db,plugins,routes}, drizzle/, Dockerfile, README, `.github/workflows/services-auth-svc.yml` từ workflow-templates)
+- Modify: `pnpm-workspace.yaml` (+`- "services/auth-svc"` — 1 dòng, SF-3/SF-4 không đụng file này → an toàn song song)
+- Modify: `pnpm-lock.yaml` (install sinh)
+
+- [x] **Step 1: khung boot** — mirror node-svc: env/logger/JWT plugin (**verify issuer giữ literal `"auth-mock"`**)/envelope (HttpError.statusCode, pino cast) + `/healthz` `/readyz` naked+prefix. `drizzle.config.ts` schema `auth`.
+- [x] **Step 2: migration 0000 + seed** — SQL như spec §Kiến trúc (`roles text[] NOT NULL DEFAULT '{"user"}'`); seed từ users.json giữ UUID, `password_hash = argon2id(AUTH_DEV_PASSWORD)`, idempotent `ON CONFLICT (id) DO NOTHING`.
+- [x] **Step 3: TDD rotation/reuse (RED trước)** —
+
+```ts
+// refresh lần 1 (CAS): old.revoked_at != null + cặp mới + replaced_by=old.id
+// 2 request CAS cùng old id: 1 thắng, 1 về 0-rows → reuse-detect
+// reuse old sau rotate: 401 + TẤT CẢ refresh_tokens user bị revoked_at != null
+// logout trên token đã revoked: 204 (idempotent)
+```
+   Rotation query: `UPDATE auth.refresh_tokens SET revoked_at=now(), replaced_by=$new WHERE id=$old AND revoked_at IS NULL RETURNING *` — 0 rows → reuse-detect: `UPDATE ... SET revoked_at=now() WHERE user_id=$u AND revoked_at IS NULL` + 401. Hash sha256, KHÔNG lưu raw.
+- [x] **Step 4: 5 endpoints** — register (argon2id; email lowercase-normalize; 409 UNIQUE; password 8–72), login (sign HS256 TTL `ACCESS_TOKEN_TTL`, iss `"auth-mock"`, + refresh `crypto.randomBytes(32)`), refresh (CAS + reuse-detect), logout (204 idempotent), logout-all (Bearer sub). Envelope conventions/04; không log password/refreshToken.
+- [x] **Step 5: Verify** — `pnpm --filter auth-svc test` 37/37 (27 unit + 10 integration postgres thật, XANH trên DB fresh ×2 — executor + reviewer tự chạy); `docker build` OK; boot-smoke chuỗi register→refresh→reuse→401→logout PASS **trên image**. ⚠️ "Workflow xanh trên nhánh": GitHub Actions **disabled repo-wide** (`gh api …/actions/permissions → enabled:false`, 10/10 workflows `disabled_manually` — không push nào fire CI) → chứng minh = 3 jobs chạy tương đương local; coordinator enable Actions (hoặc để SF-5 CI swap) → re-run để có run xanh thật. Chi tiết `docs/superpowers/evidence/sf-2-auth-real/test-run.txt`.
+
+### Task 3 = SF-3 (tier 1, song song — vùng `services/node-svc/**`): RBAC demo
+
+**Files:**
+- Modify: `services/node-svc/src/plugins/auth.ts` (verify request.user có roles — decode hiện có)
+- Modify: `services/node-svc/src/routes/tasks.ts` (DELETE guard)
+- Test: `services/node-svc/src/app.test.ts`
+
+- [x] **Step 1: RED** — test DELETE với token roles `["user"]` → 403 `{code:"FORBIDDEN"}`; alice (admin) → 200. Chạy FAIL.
+- [x] **Step 2: guard** — preHandler DELETE: `if (!user.roles?.includes('admin')) throw createError(403, 'FORBIDDEN', 'Chỉ admin được xoá task')`.
+- [x] **Step 3: GREEN** — suite node xanh (e2e.sh hiện tại KHÔNG có bước DELETE — compat mặc nhiên đúng, không cần assert gì thêm ở SF-3).
+- [x] **Step 4: Verify** — `pnpm --filter node-svc test && pnpm --filter node-svc build`.
+
+*(SF-3 nhỏ hơn chuẩn 8-15 steps — giữ riêng vì vùng file tách bạch là trục song song với SF-2/4; chạy tier co-giãn Standard.)*
+
+### Task 4 = SF-4 (tier 1, song song — vùng `app/shared/src/refresh-client.ts` mới + `app/shell/**`): FE refresh wrapper
+
+**Files:**
+- Create: `app/shared/src/refresh-client.ts` + export qua `index.ts`
+- Modify: `app/shell/src/pages/LoginPage.tsx` (+tab Register; response v2 shape — không còn tokenType/expiresIn) · `app/shell/src/api.ts`
+- Test: `app/shell/tests/` (mock fetch)
+
+- [x] **Step 1: refresh-client API** —
+
+```ts
+export interface AuthSession { accessToken: string; refreshToken: string; }
+export async function login(email: string, password: string): Promise<AuthSession>;
+export async function register(email: string, password: string, displayName: string): Promise<AuthSession>;
+// 401 → refresh ĐÚNG MỘT LẦN (single-flight promise lock) → retry
+export async function withRefresh<T>(fn: (token: string) => Promise<T>): Promise<T>;
+export async function logout(): Promise<void>; // revoke + clear 2 key
+```
+   Access → `tokenStorage` (API có sẵn); refresh → `localStorage['bp.rt']` (rationale pin token-contract.md).
+- [x] **Step 2: tests** — mock fetch: login/register lưu cặp đúng key; 401 → /refresh đúng 1 lần → retry OK; refresh cũng 401 → clear 2 key + throw Unauthorized; logout revoke + clear.
+- [x] **Step 3: LoginPage** — tab Login/Register; response v2 shape; lỗi 401/409 theo messages contract.
+- [x] **Step 4: Verify** — `pnpm --filter shell test && typecheck`; **coverage gate đúng ngưỡng config (lines/statements/branches 90, functions 80)**; **a11y test** (tab/form mới phải qua suite a11y sẵn có).
+
+### Task 5 = SF-5 (tier 2): Convergence + decommission + CI swap + docs
+
+**Files:**
+- Modify: `scripts/smoke/e2e.sh` (+bước auth-real: register→refresh→reuse→401→logout; đánh số lại — **bảo toàn contract: exit N = fail bước N (<255), marker `SAGA_TASK_ID=`, `SMOKE_SAGA=0` vẫn exit 0**)
+- Modify: `platform/docker-compose.yml` + `platform/gateway/nginx/nginx.conf` + `platform/postgres/init/01-init.sh` + go-svc env — **thực thi gap-answer SF-1 đã duyệt** (8 mục)
+- Modify: `.github/workflows/contracts.yml` (boot auth-svc thay auth-mock; nới schemathesis full) + `services-go-svc.yml` + `services-spring-svc.yml` (boot auth-svc)
+- Modify: docs — `walkthrough.md` (+register/refresh flow + gotcha `down -v` + sync "số bước PASS"), `CLAUDE.md` (auth-mock → auth-svc), `orca.yaml` (services entry auth-svc + gotcha down-v + test_all + auth-svc), `README.md`, `docs/toolchain.md`
+- Delete: `platform/auth-mock/`
+- Modify: `platform/.env.example` (đồng bộ rename đã làm ở SF-1 — nếu conflict thì merge)
+
+- [x] **Step 1: decommission** — xoá `platform/auth-mock/` + entry compose (kèm `depends_on` key) + upstream nginx + go-svc env value; boot compose (volume MỚI hoặc `down -v`): auth-svc healthcheck xanh thay vị trí cũ.
+- [x] **Step 2: e2e mở rộng** — sau login: register `smoke-<ts>@demo.local` → refresh → reuse old → 401 → logout → register user roles `["user"]` DELETE task → 403; alice DELETE → 200.
+- [x] **Step 3: CI swap** — 3 workflow boot auth-svc; contracts.yml nới schemathesis full paths; **toàn bộ CI main phải xanh sau merge** (acceptance #9).
+- [x] **Step 4: docs sync CÙNG commit** — list ở Files; grep `auth-mock` = rỗng trên: docs/*.md, CLAUDE.md, orca.yaml, README.md, .env.example, .github/workflows/ (token-contract.md + users.json $comment giữ note lịch sử nếu muốn — ghi rõ).
+- [x] **Step 5: Full suite + security pass + human walkthrough 2 tab** (register→login→tab 2→logout-all→tab 1 chết ở request kế tiếp) — evidence `docs/superpowers/evidence/auth-real/`.
+
+---
+
+## Ràng buộc xuyên suốt (rev 2)
+
+- Contracts TRƯỚC code; `iss` **PINNED `"auth-mock"`** — mọi verify/serving giữ nguyên giá trị; drift-guard activity.yaml không liên quan.
+- users.json: KHÔNG thêm password; UUID không đổi; `$comment` ghi mapping password → `AUTH_DEV_PASSWORD` (update $comment thuộc SF-5 docs).
+- Gateway/compose/init/workspace/CI = shared files: SF-1 soạn gap-answer → coordinator duyệt → SF thực thi đúng mục sở hữu; KHÔNG 2 SF cùng đụng 1 shared file trong 1 tier.
+- Mỗi SF: evidence `docs/superpowers/evidence/auth-real/sf-N/` + test-run.txt ghi HEAD tại code-commit cuối; story-verify B1–B3; executor không merge — dest → main qua PR (git-flow).
+- TDD: RED→GREEN từng behavior; `tdd: skipped-tdd: CI-only <lý do>` nếu cần.

package/stack-template/docs/superpowers/plans/2026-10-17-ui-kit-split-plan.md

@@ -0,0 +1,18 @@
+# Plan: ui-kit split + Storybook Phase 1
+
+Spec: `docs/superpowers/specs/2026-10-17-ui-kit-split.md` · Nhánh: `__STACK_ORG__/ui-kit-split` · 2026-10-17
+
+| # | Task | Exit criteria |
+|---|------|---------------|
+| T1 | Spec + plan (docs này) | Được duyệt trong chat, committed |
+| T2 | `app/ui-kit`: git mv `src/ui` + `src/styles` từ shared; package.json (qua source, exports `.` + `./styles/*.css`); src/index.ts barrel; env.d.ts; tsconfig; vitest.config + tests/setup; **move** `primitives.test.tsx` từ shell/tests; README | `pnpm --filter @wakii/ui-kit test && typecheck` PASS |
+| T3 | `app/shared` slim: package.json bỏ exports `./ui` + `./styles/*`; index.ts bỏ re-export ui; README rewrite (logic-only, pointer ui-kit); 4 file logic KHÔNG đụng (READ-LOCKED) | shared typecheck đứng yên OK; không còn `src/ui` |
+| T4 | Consumers đổi imports: shell (bootstrap css, RemoteSlot Skeleton, pages nếu có, tests, package.json +dep), remote-tasks (TasksPage EmptyState/Skeleton + tokens.css, TaskItem Spinner, standalone.tsx, api.test? chỉ UI imports, package.json), remote-activity (tương tự) | grep `fe-shared` còn đúng logic-only; suites shell 43/tasks 36/activity 22 PASS; typecheck + build ×3 OK |
+| T5 | `pnpm install` (lockfile: importer ui-kit + deps consumers) → frozen PASS sau đó | install --frozen-lockfile PASS |
+| T6 | Dockerfiles ×3: COPY app/ui-kit (package.json trước, full sau) | `docker compose build shell tasks activity` PASS |
+| T7 | convergence copy-dir: typecheck standalone fe-shared + ui-kit (mini workspace catalog + @types/react + --jsx) | local repro EXIT=0 cả hai |
+| T8 | CI `ui-kit.yml`: typecheck + test + build-storybook, paths `app/ui-kit/**` | workflow yaml parse + chạy xanh trên push |
+| T9 | Storybook: `.storybook/{main,preview}.ts` (react-vite + addon-docs, preview import tokens+base); stories: Badge 9 variants, EmptyState/Skeleton/Spinner states, Tokens docs page; script `build-storybook` | `pnpm --filter @wakii/ui-kit build-storybook` PASS; dev screenshot evidence |
+| T10 | ADR-0009 + sync descriptor: CLAUDE.md (READ-LOCKED + docs map + CI bảng), orca.yaml (frontend.shared/ui-kit), agents/fe-dev, scaffold SCAFFOLD.md, README root | descriptor khớp thực tế; review pass |
+
+Thứ tự: T2→T3→T4→T5 (core, verify mỗi bước) → T6/T7/T8 (infra) → T9 (storybook) → T10 (docs). Merge main sau khi toàn bộ xanh + CI收敛.

package/stack-template/docs/superpowers/reviews/2026-10-18-data-display-coverage.md

@@ -0,0 +1,52 @@
+# Case-coverage audit — Data Display cluster (2026-10-18)
+
+Worker V2 · đối chiếu benchmark antd / MUI / PrimeReact cho 20 component data-display.
+Hành động: **bổ API + stories EN + tests hành vi** cho case benchmark quan trọng còn thiếu.
+Verify: vitest cluster **23 file / 240 tests PASS** · eslint cụm **0 errors** · tsc: 0 lỗi ở file sửa.
+
+## Bảng tổng hợp
+
+| Component | Case benchmark (antd/MUI/PrimeReact) | Đã có trước | Đã bổ đợt này | Còn tồn + lý do |
+|---|---|---|---|---|
+| Avatar | src fallback onError, size/shape, icon | children/initials, src, alt, size, shape | **onError fallback** — src fail → initials (API + test `fireEvent.error` + story `BrokenSrcFallback`) | icon prop riêng (initials đủ) |
+| AvatarGroup | max +N tooltip, overlap, per-avatar tooltip | đầy đủ benchmark lite | — | — |
+| Badge | count, overflowCount 99+, showZero, dot, offset, status×5 + text | variant pill ×9 (task/activity) | **count mode**: `count`·`overflowCount`·`showZero`·`dot`·`offset`·`status`+`text` (API + 8 tests + 4 stories EN) | color preset tùy ý (variant map đủ hệ tokens) |
+| Card | cover, actions, hoverable, loading, size, type inner, Meta | cover, actions, hoverable, bordered, extra | **`loading`** (skeleton body, aria-busy) + **`size="small"`** (dense padding) — tests + 2 stories EN | `type="inner"` (Card lồng + className đạt được), `Meta` composite — backlog |
+| Carousel | autoplay, dots, navigators, keyboard, vertical, per-view, pauseOnHover | đầy đủ benchmark lite | — | effect `fade` (chỉ slide) — backlog |
+| Collapse | accordion, disabled item, controlled keys, ghost | items, defaultActiveKeys | **`accordion`** + per-item **`disabled`** (tests + 2 stories EN) | controlled `activeKeys` (uncontrolled đủ recipe) · ghost/extra — backlog |
+| Descriptions | bordered, colon, size, column, layout, span | bordered, title, items | **`size="small"`** + **`colon`** (tests + 1 story EN) | `column` nhiều cột + layout vertical + span — backlog lớn (ghi trong file) |
+| Divider | type, dashed, orientation left/right | type, dashed, children-center | **`orientation="left|right|center"`** (tests + 1 story EN) | `plain` — giá trị thấp |
+| EmptyState | title/description/action/custom image | đầy đủ benchmark lite | — | — |
+| Galleria | indicators, thumbnails, fullscreen, caption, autoplay | images + dot indicators cơ bản | — | thumbnails/fullscreen/autoplay — heavy backlog |
+| Image | preview, fallback onError, placeholder, group | preview overlay ✓ | — KHÔNG ĐỤNG (W8 đang viết lại stories) | fallback onError + PreviewGroup — chờ W8 xong |
+| List | renderItem, pagination, loading, grid, actions/meta | renderItem, pagination, loading+EmptyState | — KHÔNG ĐỤNG (S đang thêm virtual) | grid mode — backlog |
+| Segmented | options disabled, size, block | options/value/onChange | **per-option `disabled`** (test hành vi; stories bị giữ — không thêm story) | `size`/`block` — backlog nhỏ |
+| Skeleton | variant×5, count, active, compose | variant×5 + count + classNames slots | — | — |
+| Statistic | precision, separator, loading, countdown | title/value/prefix/suffix/valueStyle | — | `precision`/`separator` (cần quyết format locale) · countdown — component riêng |
+| Table | fixed header, summary, frozen cols, virtual, expandable, selection | fixed header ✓ (scrollHeight + sticky — story 7 + test có sẵn), frozen ✓, virtual ✓, filter/sort/pagination ✓ | — KHÔNG ĐỤNG index/types (worker khác đang WIP `expandable`) | **`summary` row** — cần API mới, bị chặn tranh chấp file; làm ngay sau khi expandable merge |
+| Tabs | type card, position, closable, disabled tab | items, activeKey, classNames slots | — KHÔNG ĐỤNG stories (session khác giữ) | disabled tab + type card + closable — backlog |
+| Tag | color preset, closable, Checkable, icon | closable, Checkable, icon ✓ | — | color preset mở rộng — cần quyết design tokens |
+| Timeline | mode left/right/alternate, pending, reverse, label | items color/label (label dưới content) | **`mode`** ×3 (label column, alternate parity antd) + **`pending`** (hollow dot) — 5 tests + 2 stories EN | `reverse` — nhỏ, đợt sau |
+| Tree | showLine, checkable, draggable, selectedKeys | data/expand/click | **`showLine`** connector borders (API + 2 tests + 1 story EN) | checkable + draggable + selectedKeys — backlog lớn (ghi rõ trong comment file) |
+
+## File tranh chấp — tôn trọng trong đợt này
+
+- `list/index.tsx` — S (virtual WIP) · `image/image.stories.tsx` — W8 (ảnh thật) · `select.stories.tsx` — L
+- `table/index.tsx` + `table/types.tsx` — worker khác đang thêm `expandable` (phát hiện qua git status, không có trong cảnh báo ban đầu)
+- `segmented/skeleton/tabs.stories.tsx` — M bởi session khác → chỉ bổ API + test, không đụng stories
+
+## Verify (paste)
+
+```
+ Test Files  23 passed (23)
+      Tests  240 passed (240)
+   Duration  4.82s
+   (vitest run: badge card timeline tree avatar avatar-group collapse divider
+    descriptions segmented table statistic tag tabs skeleton empty-state
+    carousel galleria list image)
+
+npx eslint <cụm>  → 0 errors
+npx tsc --noEmit  → 0 lỗi ở mọi file đợt này
+  (còn 6 lỗi TS ở src/KitchenSink.stories.tsx — file untracked tạo 16:51 bởi
+   session khác: thiếu import Paragraph/Slider, onChange setState — không thuộc đợt)
+```

package/stack-template/docs/superpowers/reviews/code-reviewer-sf-5-r1.md

@@ -0,0 +1,65 @@
+# Code Review round 1 — SF-5 (VU-64) (outbox từ code-reviewer agent, 2026-10-17)
+
+Scope: ce9ce7e..560694d (a494dab chính + b64d872 comment + 560694d security). 43 files, +282/-1337.
+Coverage 43/43 file (bảng đầy đủ trong transcript agent); các vị trí position-verified tại HEAD.
+
+## P1 (1)
+- [P1][high] e2e.sh exit-code collision — vi phạm contract "exit N = fail bước N" mà commit tự
+  tuyên bố bảo toàn: fail 7 ×6 (bước 6 stats VÀ bước 7 register), fail 8 (refresh VÀ saga
+  create/PATCH), fail 9 (reuse VÀ saga poll), fail 10 (logout VÀ DLQ); header claim "exit tới 15"
+  sai (max thực tế 12). Fix đề xuất: exit = nhãn + 1 tới 16 + sửa header.
+
+## P2 (5)
+- walkthrough.md:50 "alice 200" — script assert 204 (tasks.yaml)
+- .claude/agents/e2e-runner.md:36 "PASS = 8 bước" — giờ 15
+- app/shell/README.md:13 env cũ AUTH_MOCK_DEV_PASSWORD (đã rename AUTH_DEV_PASSWORD từ SF-1)
+- README.md:21 mermaid authsvc còn trong subgraph platform; :7 header "6 services" không nhắc auth
+- contracts.yml:91-93 register curl thiếu --max-time (pattern-consistent, không chặn)
+
+## Deterministic (reviewer tự chạy lại)
+bash -n SYNTAX-OK · compose config -q OK · init set -euo pipefail + đủ env ở 3 CI caller ·
+Dockerfile node:22-alpine có wget · ci.compose.override.yml không tham chiếu auth-mock ·
+token extraction shape-v2-safe (spring jq/go json.load/contracts sed) · convergence pipefail có ·
+repo-wide auth-mock residue đúng ranh giới (iss-pinned + historical + services README stale
+[go README:37 AUTH_MOCK_DEV_PASSWORD, spring README:12 TTL 8h — follow-up coordinator]).
+
+## CHECKLIST-4Q
+Q1 PASS (0 dòng service code; init SQL thuần 1 heredoc) · Q2 PASS (e2e CURL --max-time 5;
+contracts register thiếu max-time = P2) · Q3 PASS (DLQ best-effort in stderr + ủy quyền CI qua
+marker; logout-204-on-revoked là contract chủ đích) · Q4 PASS (user smoke-<ts> tồn lại by-design;
+không partial-fail mới).
+
+VERDICT: CHANGES-REQUESTED — P1: e2e.sh exit codes trùng — renumber unique + sửa header.
+
+## Disposition (executor, commit 4cb0912)
+P1: renumber theo rule exit = label+1 (register→8 … DLQ→16), header "exit = label+1 (tới 16,
+unique từng bước)". Meta-test: grep fail N — mỗi code đúng 1 block; e2e re-run 15/15 PASS.
+Cả 5 P2 fix cùng commit. → re-review round 2.
+
+---
+
+# Code Review round 2 — RE-REVIEW (2026-10-17)
+
+Scope delta: 560694d..4cb0912 (9 files). Full story diff: ce9ce7e..4cb0912.
+
+## P1 r1 — ĐÃ ĐÓNG (position-verified tại HEAD)
+Mapping exit-code unique đúng rule exit = nhãn+1: 1=prereq · 2=ready · 3=login · 4=baseline ·
+5=create · 6=feed · 7=stats · 8=register · 9=refresh · 10=reuse · 11=logout · 12=RBAC-user ·
+13=RBAC-alice · 14=saga · 15=poll · 16=DLQ. Header đúng sự thật. Meta-test reviewer tự chạy:
+grep uniq per block ✓ + e2e 15/15 exit 0.
+
+## P2 r1 — cả 5 ĐÃ ĐÓNG (walkthrough 204 / e2e-runner 15 bước / shell README env /
+README mermaid+header / contracts --max-time 10).
+
+## 3 file thêm trong 4cb0912 soi riêng: improvements-log (learnings đúng format) ·
+plan.md (CHỈ tick, KHÔNG rewrite prose sai — audit-trail sạch) · evidence walkthrough (out of scope code).
+
+## CHECKLIST-4Q (round 2)
+Q1 PASS · Q2 PASS (--max-time 5 + 10; poll 3) · Q3 PASS (DLQ best-effort + marker CI) · Q4 PASS.
+
+Follow-up ngoài SF-5 (coordinator): services/{go,spring,node}-svc README stale
+(AUTH_MOCK_DEV_PASSWORD / TTL 8h / auth-mock) — ngoài touch map READ-ONLY; gom cụm iss-rename
+hoặc docs-hygiene.
+
+VERDICT: APPROVED — P1 + 5 P2 đã đóng đều position-verified, mapping exit-code unique đúng
+rule, không finding mới trong 4cb0912.

package/stack-template/docs/superpowers/reviews/security-audit-sf-5-auth-real.md

@@ -0,0 +1,39 @@
+# Security Audit — SF-5 auth-real VU-59/VU-64 (outbox từ security-audit agent, 2026-10-17)
+
+## Executive Summary
+**Overall Risk**: Low · **Vulnerabilities Found**: 4 (0 Critical, 0 High, 4 P2 hygiene/defense-in-depth)
+**Kết luận acceptance**: **PASS** — **0 P0 / 0 P1**. Diff là thuần expose/swap (auth-mock → auth-svc):
+compose entry, postgres init role, nginx upstream, CI swap, e2e mở rộng 15 bước, docs sync.
+Không có code auth-svc trong diff (của SF trước, đúng phạm vi). 5 quyết định đã-accepted
+(localStorage bp.rt / iss pinned / AUTH_DEV_PASSWORD default / gateway presence-check /
+schemathesis full) đều verify đúng ghi nhận — không reopen.
+
+## A1–A6
+- **A1 heredoc injection (01-init.sh:24)**: vector cú pháp CÓ, không attacker-reachable (input = .env operator
+  + CI hardcode); password chứa `'` → ON_ERROR_STOP fail-closed. Pattern tiền-existing ×5 role → P2-1.
+- **A2 temp files + leak**: trap ĐỦ (REGISTER_BODY/REFRESH_BODY/RBAC_403_BODY init trước trap, đủ trong rm -f);
+  bước 9/10 `-o /dev/null`; say không in token. Lỗ hẹp: fail-branch cat body register/refresh nếu service
+  buggy trả success-code-sai kèm token → **P2-2** (cùng pattern contracts.yml:93).
+- **A3 secret leak trong log/healthcheck**: sạch — healthcheck probe không secret, không shell tracing,
+  login response không in. `echo "$PAYLOAD"` in JWT claims (không signature) ra CI log → **P2-3**.
+- **A4 docs mở lỗ**: walkthrough 4a hướng dẫn dán token vào curl → shell history (bp.rt dài hạn) → **P2-4**.
+- **A5 RBAC assert**: ĐỦ — 403 status + envelope FORBIDDEN + alice 204; CI coverage qua convergence e2e.
+- **A6 exposure auth_svc/cross-schema**: sạch — GRANT chỉ schema auth, search_path auth, users.json :ro
+  không password, PG16 thu hồi CREATE public khỏi PUBLIC.
+
+## P2 (đề xuất fix)
+| ID | Issue | Location |
+|---|---|---|
+| P2-1 | SQL literal breakout qua password chứa `'` (fail-closed, operator-controlled) | platform/postgres/init/01-init.sh:24 |
+| P2-2 | Fail-branch cat body register/refresh có thể in token nếu service buggy | scripts/smoke/e2e.sh:172,183 + contracts.yml:93 |
+| P2-3 | echo JWT claims ra CI log (không signature — hygiene) | contracts.yml:100 |
+| P2-4 | Docs demo dán token vào curl → shell history | docs/walkthrough.md:111-114 |
+
+Repo-hygiene: 0 .env/pem/key trong diff; exec-bit 0; không chmod/sudo/curl|sh; lockfile chỉ XOÁ (auth-mock).
+
+## Disposition (executor, commit 560694d)
+Cả 4 P2 đã fix: P2-2 fail-branch in field-names thay body (e2e.sh + contracts.yml, + rm /tmp/reg.json);
+P2-3 bỏ echo payload; P2-4 mẫu read -rs + unset; P2-1 comment ràng buộc quote (psql :'var' binding cho
+cả 5 role = follow-up — fix 1/5 role thôi sẽ lệch style trong cùng file).
+
+VERDICT: FINDINGS — P0: 0 · P1: 0 · P2: 4 — sạch cho acceptance SF-5

package/stack-template/docs/superpowers/specs/2026-10-12-boilerplate-microservice-mfe.md

@@ -0,0 +1,110 @@
+# Epic Spec — Boilerplate Microservice + Micro-frontend
+
+> Story: pending epic ID · tạo 2026-10-12 · pipeline: story-workflow CREATE
+> Rev 2 — sau spec-critic vòng 1 (NO-GO): sửa 2 P0 (fe-shared ownership, activity event flow) + 7 P1 (auth claims, seed users, failure semantics, schema grants, standalone-copy, gateway topology, smoke/scaffold semantics)
+> Rev 3 — sau plan-critic (NO-GO): P0 canonical tasks DDL + edge SF-7→SF-3; P1 compose pre-seed (không 3 SF cùng sửa compose), boot-smoke CI per service, event-push fire-and-forget, CORS dev có chủ, spike fe-shared ở SF-1, grant qua default privileges, users fixture chung, smoke = script committed, exit criteria CI-verifiable
+> Repo: `__STACK_ORG__/architecture-overview` (greenfield — chỉ README, 1 commit)
+
+## IDEA-BRIEF (8 chiều)
+
+- **Task**: Phát triển boilerplate (khung mẫu copy-able) cho kiến trúc microservice + micro-frontend: contracts → platform → 3 services polyglot → FE shell + remotes → convergence + scaffold.
+- **Output**: Cây thư mục code trong repo này — `docker compose up` (hoặc chạy native từng service) cho demo end-to-end qua browser; CI GitHub Actions xanh.
+- **Users**: Dev team nội bộ — copy boilerplate để khởi tạo dự án mới; fresh-clone walkthrough checklist phải chạy được từ đầu đến cuối (SF-7).
+- **Constraints**: Mixed-stack (Node/TS + Spring Boot + Go, mỗi stack 1 service); Module Federation 2.0 (Rspack, KHÔNG trộn bundler); multi-repo convention trong 1 repo (mỗi thư mục con = repo-con độc lập tooling, contract = OpenAPI contract-first); mock JWT + điểm cắm OIDC (không Keycloak thật); Docker Compose + CI cơ bản, k8s out-of-scope.
+- **Input**: Không Figma, không code cũ. Domain sample: **task management**.
+- **Context**: README hiện tại chỉ có docs Mermaid; Docker KHÔNG có trên dev machine (verify docker build qua CI; local demo chạy native); GH Actions enabled, quyền ADMIN.
+- **Success criteria**: (1) `docker compose up` (trên CI/máy có Docker) → mở shell → login mock → CRUD task → activity feed — xuyên 3 service qua nginx gateway. (2) CI path-filtered xanh (build + test + docker build per stack). (3) Mỗi repo-con copy ra dùng độc lập được (kèm `frontend/shared` nếu nó import shared). (4) Scaffold script sinh project mới từ boilerplate, cùng flow chạy được.
+- **Out-of-scope**: k8s/Helm; Keycloak thật; sản phẩm task management thật (chỉ sample đủ demo); message broker (Kafka…) — inter-service dùng REST sync; mobile app; i18n.
+
+## Quyết định đã chốt (user, 2026-10-12)
+
+| # | Quyết định | Chọn |
+|---|---|---|
+| 1 | Mục đích | Template nội bộ + sample e2e |
+| 2 | Stack BE | Mixed: Node/TS + Spring Boot + Go (mỗi stack 1 service) |
+| 3 | Micro-frontend | Module Federation (Rspack + @module-federation/enhanced) |
+| 4 | Layout | Multi-repo convention — FE một phía, services một phía |
+| 5 | Infra | Docker Compose + GitHub Actions CI; k8s out-of-scope |
+| 6 | Nơi đặt | Repo này (mỗi thành phần = thư mục con = repo-con) |
+| 7 | Auth | Mock JWT + điểm cắm OIDC |
+
+Tự quyết theo conventions (ADR ghi ở SF-7): JDK 21 + Spring Boot 3.x (Web MVC, không reactive); Node 22 LTS + pnpm; Go 1.24.x + chi; React 19; Rspack (không Vite-MF); drizzle-orm (node-svc); Flyway (spring-svc); go-svc serve OpenAPI spec + swagger-ui static; Postgres 16 dùng chung (mỗi service 1 schema + migration); nginx gateway-lite; sample domain = task management; 1 story 7 SF, phased-release 3 phase.
+
+## Kiến trúc sample (e2e flow chứng minh)
+
+```
+Browser → nginx gateway :8080
+  ├─ /            → shell static (MF host)
+  ├─ /remotes/*   → remote static (mỗi remote 1 nginx container riêng, remoteEntry.js)
+  └─ /api/*       → services
+       ├─ /api/tasks/*    → node-svc :3001 (task CRUD, Postgres schema `tasks`)
+       │    └─ sau khi mutate task: POST /api/activity/events → go-svc (event "task.created")
+       ├─ /api/users/*    → spring-svc :8081 (users + teams CRUD, Postgres schema `users`)
+       │    └─ node-svc gọi REST validate user (timeout 2s; spring down → 503 fail-closed, ADR ghi phương án degrade)
+       └─ /api/activity/* → go-svc :8082 (feed + stats; OWNS schema `activity` migration;
+            ĐỌC-ONLY schema `tasks` qua postgres readonly role — grants cấp bởi compose init script SF-1)
+Auth: auth-mock cấp JWT HS256 (claims: sub = user id spring, email, roles; TTL 8h; secret chia qua
+compose env .env không-commit). Enforcement 2 lớp: gateway chặn thiếu-token (401), từng service
+TỰ verify signature + expiry (không tin gateway). Token contract file trong contracts/.
+```
+
+Contract-first: `contracts/openapi/*.yaml` (tasks, users, activity, auth) là source of truth duy nhất cho API surface; **`contracts/db/tasks-schema.sql` là canonical DDL cho bảng `tasks`** — interface chung thật sự giữa node-svc (migration phải sinh ra đúng DDL) và go-svc (stats query theo đúng DDL); **`contracts/auth/users.json` là fixture users chung** — auth-mock và seed migration spring đọc CÙNG file. Mỗi service codegen models từ OpenAPI (không gen full client); CI lint (spectral) + contract test (schemathesis). Event push node→go là **fire-and-forget**: fail → JSON log warn, KHÔNG chặn mutation task, KHÔNG retry (ADR ghi trade-off).
+
+## SF split (7 SF — rubric C1-C5/V1-V3, anti-duplicate áp dụng)
+
+### Phase 1 — backend demo được (checkpoint: compose/CI build xanh + swagger + contract test)
+
+**SF-1 · Contracts & Platform Foundation** (tier 0, ~16 tasks — deliberate bottleneck, trade-off ghi ADR: tách fe-shared thành SF riêng không đáng thêm 1 handoff)
+- OpenAPI specs (tasks, users, activity — **event payload + feed response chứa đủ user-display fields FE cần render**, auth) + spectral rules + contract-test scaffold (schemathesis)
+- **Canonical DDL** `contracts/db/tasks-schema.sql` (bảng `tasks` — nguồn cho migration node-svc và query go-svc)
+- **Users fixture** `contracts/auth/users.json` (auth-mock + seed spring đọc chung)
+- **Auth token contract file**: claims (sub/email/roles), TTL, secret phân phối, enforcement 2 lớp — commit trong `contracts/`
+- Conventions pack: Dockerfile multi-stage pattern, healthcheck `/healthz`+`/readyz`, JSON log shape, error envelope, **port table (đủ: 3 svc + auth-mock + shell + 2 remotes dev + prod)**, env config qua env-var, **CORS dev-profile rule**
+- **Gateway routing table** (`/` shell, `/remotes/*`, `/api/*`) + **remote registry** (tên MF remote + URL dev/prod, env-configurable)
+- docker-compose **PRE-SEED đủ khung 3 services + postgres + nginx + auth-mock** (env inventory đầy đủ trong `.env.example`; **SF-2/3/4 KHÔNG sửa compose — chỉ điền impl**); postgres init script: tạo schemas + readonly role go-svc dùng **`ALTER DEFAULT PRIVILEGES IN SCHEMA tasks`** (grant vẫn hiệu lực khi bảng sinh sau bởi migration)
+- nginx gateway config; auth-mock service (đọc users fixture)
+- **`frontend/shared` (fe-shared)**: api client wrapper, MF bootstrap helper, token storage; kèm **spike tối thiểu hello-world remote load được** để pin React 19 + @module-federation/enhanced + Rspack CÓ CĂN CỨ ở tier 0; `pnpm-workspace.yaml` globs khai báo đủ `frontend/*`
+- `.gitignore`/`.gitattributes` (eol=lf)/`.editorconfig`
+- CI templates: path-filtered per service + **boot-smoke job pattern (container up + curl `/healthz` + `/readyz` + migration chạy xong)** + gitleaks
+- README cập nhật kiến trúc thật
+
+**SF-2 · node-svc — task API** (tier 1, ~9 tasks): Fastify+TS, codegen models, CRUD tasks, validate user qua spring-svc (timeout 2s, fail-closed 503), migration sinh đúng canonical DDL (exit: diff schema vs `contracts/db/tasks-schema.sql` = 0), push event fire-and-forget (log warn khi go-svc down), healthcheck, JSON logging, CORS dev-profile, tests (unit + contract), Dockerfile, **boot-smoke CI job**, swagger, README standalone (exit: docs đủ — chứng minh copy-dir là việc SF-7).
+
+**SF-3 · spring-svc — user API** (tier 1, ~9 tasks): Spring Boot 3 Web MVC, users + teams CRUD, **seed migration đọc `contracts/auth/users.json`** (exit: id trùng khớp fixture), Postgres schema `users` + Flyway, healthcheck (actuator + `/readyz`), logback JSON shape chung, CORS dev-profile, tests (@SpringBootTest + contract), Dockerfile multi-stage với mvnw, **boot-smoke CI job**, swagger, README standalone.
+
+**SF-4 · go-svc — activity API** (tier 1, ~9 tasks): Go 1.24 + chi, activity feed + stats (query theo canonical DDL), schema `activity` MÌNH migrate, nhận `POST /activity/events` (contract activity), healthcheck, slog JSON shape chung, CORS dev-profile, tests (unit + contract), Dockerfile multi-stage distroless, **boot-smoke CI job**, swagger-ui static, README standalone. **Exit criterion chứng minh readonly đọc được: seed rows bằng owner role → stats trả về đúng.**
+
+### Phase 2 — FE demo được (checkpoint: shell chạy, 2 remote load, gọi service thật qua gateway)
+
+**SF-5 · FE shell — MF host** (tier 2, ~9 tasks): Rspack + @module-federation/enhanced host; **task đầu: re-validation spike của SF-1 + fe-shared fit-check** (export API đủ dùng cho shell chưa — lệch phát hiện sớm, không giữa run); pnpm catalog ép singleton deps; routing + layout + nav; login mock JWT (dùng token-storage + api client từ `frontend/shared`); a11y baseline **có test**: route focus + skip link (vitest); error boundary + fallback khi remote load fail; tests; Dockerfile (nginx static); compose entry đã pre-seed — SF-5 chỉ điền impl + **boot-smoke CI job**; README standalone.
+
+**SF-6 · FE remotes — tasks + activity** (tier 2, ~10 tasks): 2 remote apps cùng pattern; remote `tasks`: danh sách + tạo/sửa task (gọi node-svc qua gateway `/api/tasks`, đính JWT); remote `activity`: feed + stats (`/api/activity`); **cả hai import shared utilities từ `frontend/shared` (READ-ONLY với SF-6 — SF-1 sở hữu, sửa = flag)**; shared singletons theo catalog; mỗi remote tests + Dockerfile + compose impl (pre-seeded) + **boot-smoke CI job** + README standalone. Remote URLs đọc từ remote registry (env); dev server proxy theo conventions (native mode không cần CORS mở vì đi qua dev proxy). *Lưu ý vận hành: SF-5 ∥ SF-6 cùng regenerate root `pnpm-lock.yaml` — coordinator resolve theo checklist (lấy 1 phía + `pnpm install` lại), không gộp tay.*
+
+**`frontend/shared` (fe-shared)**: package riêng, repo-con thứ 7, **SF-1 sở hữu** (api client wrapper, MF bootstrap helper, token storage, catalog). Standalone-copy định nghĩa: remote/shell copy KÈM fe-shared. — Đây là sửa P0-1 (spec-critic): không còn import chéo shell↔remote, không có dependency edge ẩn trong tier 2.
+
+### Phase 3 — convergence (checkpoint: STORY-COMPLETE candidates)
+
+**SF-7 · Convergence & Scaffold** (tier 3, ~10 tasks; **depends-on: SF-5, SF-6, VÀ TƯỜM MINH SF-2, SF-3, SF-4** — smoke chain login→tạo task→đọc feed cần đủ 3 service sống): compose e2e smoke **API-level qua gateway — script committed `scripts/smoke/e2e.sh` + CI job** (curl: login → tạo task → đọc feed), không ad-hoc tại checkpoint; browser walkthrough là human gate tại checkpoint, không vào CI; CI hoàn chỉnh (path-filter + docker build per stack + contract test + gitleaks + copy-dir standalone smoke: copy 1 service + fe-shared ra tmp → build/test); docs đồng bộ (README Mermaid = kiến trúc thật + ADR các quyết định + toolchain doc + fresh-clone walkthrough); scaffold script `scripts/scaffold/` (copy + rename + prune, không generator framework) — **Acceptance #7 yêu cầu script chạy được; nếu trễ thì scope-flag lên user, KHÔNG auto-complete bằng manual fallback**; security-audit checkpoint (secrets/exec-bit/lockfile); rà multi-stage + pinned base images.
+
+## Phased-release
+
+- Phase 1 COMPLETE = SF-1..4 merged + compose build xanh (CI) + swagger demo + contract test pass → **RELEASE CHECKPOINT 1** (security-audit gồm trong checkpoint).
+- Phase 2 COMPLETE = SF-5..6 merged + shell demo 2 remote (local native dev servers nếu chưa có Docker) → **CHECKPOINT 2**.
+- Phase 3 COMPLETE → STORY-COMPLETE candidates.
+
+## Acceptance (epic-level, user-visible)
+
+1. Mở shell trong browser → login (mock user) → thấy nav + 2 remote render.
+2. Tạo task mới → hiện trong danh sách (đi qua node-svc, user được spring-svc validate).
+3. Mở activity → thấy feed/stats phản ánh task vừa tạo (node-svc push event sang go-svc).
+4. Toàn bộ request đi qua nginx gateway :8080 một cổng duy nhất; gateway chặn thiếu-token; service tự verify JWT (sai/hết hạn → 401 từ service).
+5. Push → CI xanh: lint contract, test per service, build docker image per stack, **smoke e2e API-level**.
+6. Copy một repo-con (service hoặc FE kèm `frontend/shared`) ra dùng riêng được theo README của nó — **CI có job copy-dir smoke chứng minh**.
+7. Scaffold script sinh project mới (đổi tên) chạy được cùng flow e2e.
+
+## Boundary epic-level
+
+- Không merge vào `main` — mọi thứ trên nhánh đích `story-<epic-id>-micro-boilerplate`, PR do NGƯỜI merge.
+- Docker không có trên dev machine: mọi verify docker qua CI; local demo = native per-service. Nếu user cài Docker Desktop giữa chừng → verify lại compose local trước checkpoint.
+- Thiếu JDK/Go local: build/test Java+Go chạy trong Docker (CI) hoặc toolchain-in-Docker local; mvnw đi kèm spring-svc.
+- `frontend/shared` chỉ SF-1 sửa; SF-5/6 tiêu thụ READ-ONLY (đụng = flag lên coordinator).

package/stack-template/docs/superpowers/specs/2026-10-12-sf-3-spring-svc-design.md

@@ -0,0 +1,160 @@
+# Spec — SF-3 spring-svc — user API (Spring Boot 3) (FI-71)
+
+> Story FI-62 · epic spec rev 3 · slice: `docs/superpowers/contexts/sf-3.md` · impact: `docs/superpowers/plans/2026-10-12-sf-3-spring-svc-impact.md`
+> Status: Approved — brainstorm autonomous (brief FI-62: decisions đã chốt ở epic, KHÔNG hỏi lại; SF slice của spec rev 3 đã qua spec-critic + plan-critic 2 vòng ở epic level).
+
+## 0. Root cause / strategy
+
+Không có service nào sở hữu users/teams → node-svc không validate được assignee (acceptance #2 gãy),
+JWT service-side enforcement (acceptance #4) chưa chứng minh. Chiến lược: **contract-first slice** —
+impl đúng `contracts/openapi/users.yaml`, seed đọc file fixture thật, verify bằng CI (không Docker/JDK local).
+
+## 1. Problem
+
+spring-svc = source-of-truth users/teams cho toàn hệ thống. Auth-mock cấp JWT với `sub` = id fixture;
+mọi consumer tin rằng id đó tồn tại trong DB của spring-svc. Thiếu spring-svc → 2 acceptance gãy.
+
+## 2. Scope
+
+**In**: scaffold Spring Boot 3 Web MVC + mvnw; codegen models (maven plugin, types); CRUD users + teams
+đúng contract; Flyway (DDL + seed Java migration đọc `USERS_FIXTURE_PATH`); JWT HS256 service-side verify;
+healthz/readyz + actuator liveness; logback JSON; error envelope; CORS dev-profile; tests
+(@SpringBootTest trên Postgres thật trong CI + seed-id-match assert); Dockerfile multi-stage;
+CI workflow (build-test + docker-build + boot-smoke + drift-guard); README; snapshot `users.yaml` trong build context.
+
+**Out**: node-svc/go-svc/FE; Keycloak; compose/conventions/contracts edits; DELETE endpoints (contract không có);
+copy-dir proof (SF-7); scaffold script.
+
+**Success criteria (CI-verifiable)**:
+1. CI `services-spring-svc` xanh: build-test (mvnw verify trên Postgres service container), docker-build, boot-smoke (up + healthz/readyz 200 `{"status":"ok"}` + login auth-mock → GET fixture user 200 + no-token/garbage-token → 401 TỪ SERVICE direct :8081).
+2. Seed-id-match test: DB ids == fixture ids 100% (assert trong test, đọc cùng file contracts/auth/users.json).
+3. Swagger UI mở được qua host port 8081 (`/swagger-ui/index.html`); api-docs JSON chứa đúng FINAL path
+   table §4.5 (`/api/users/users`, `/api/users/teams`, …) — chứng minh mount khớp contract.
+4. mvnw wrapper hoạt động trong CI Linux (toolchain path chính); README ghi rõ.
+
+## 3. Touch map
+
+Xem impact doc mục 2. Sở hữu: `services/spring-svc/**`, `.github/workflows/services-spring-svc.yml`,
+`docs/superpowers/evidence/sf-3/**`, snapshot `services/spring-svc/src/main/resources/openapi/users.yaml`.
+
+## 4. Design
+
+### 4.1 Stack & layout
+- Spring Boot **3.5.x** (Web MVC, không reactive), **Java 21**, Maven wrapper 3.3.x (script-only, tự tải).
+- Package: `com.example.springsvc` (template-neutral, copy-able).
+- Deps: web, data-jpa, validation, actuator, flyway (+flyway-database-postgresql), postgresql (runtime),
+  jjwt 0.12.x (api/impl/jackson), logstash-logback-encoder, springdoc-openapi 2.8.x, openapi-generator-maven-plugin.
+- Tên bảng/cột snake_case khớp DDL tự viết (Hibernate `ddl-auto: none` — Flyway là schema owner).
+
+### 4.2 Codegen + snapshot drift-guard
+Docker context = `services/spring-svc` (compose `build: ../services/spring-svc`) — không thấy `contracts/`.
+→ commit **snapshot BIT-IDENTICAL** `src/main/resources/openapi/users.yaml` — KHÔNG thêm comment/header
+trong file YAML (thêm = drift-guard fail ngay run đầu); provenance + quy tắc sync ghi ở README.md.
+Plugin: generatorName `spring`, `interfaceOnly=true, skipDefaultInterface=true, useSpringBoot3=true,
+useTags=true, openApiNullable=false, useBeanValidation=true` → models (`api.model`) + API interfaces (`api`)
+— controllers implement interface → compile-error nếu lệch contract signature. (ADR 1 dòng: slice viết
+"types only" — interfaceOnly là supersét, models + interface mapping, giữ contract-sync compile-time;
+base-path mặc định `${openapi.usersAPI.base-path:/api/users}` verify lúc task 1 context-load.)
+
+### 4.3 Schema & seed
+```sql
+-- V1__init.sql (schema users qua role search_path — init script SF-1 đã SET search_path = users)
+CREATE TABLE users (id uuid PRIMARY KEY, email varchar(255) NOT NULL UNIQUE,
+                    display_name varchar(255) NOT NULL, roles text[] NOT NULL);
+CREATE TABLE teams (id uuid PRIMARY KEY DEFAULT gen_random_uuid(), name varchar(255) NOT NULL);
+CREATE TABLE team_members (team_id uuid NOT NULL REFERENCES teams(id) ON DELETE CASCADE,
+                           user_id uuid NOT NULL, PRIMARY KEY (team_id, user_id));
+```
+- **V2__SeedUsers.java** (Flyway `BaseJavaMigration`): đọc env `USERS_FIXTURE_PATH` (compose mount
+  `/app/contracts/auth/users.json`; native `../../contracts/auth/users.json`), parse Jackson với
+  `FAIL_ON_UNKNOWN_PROPERTIES=false` (fixture có key `$comment`), insert
+  qua JDBC (`createArrayOf("text")` cho roles). Thiếu/sai file → fail migration → fail boot (fail-fast, conventions/06).
+  Fixture evolution: thêm user vào fixture SAU khi V2 đã applied → V3 migration riêng (README ADR ghi quy trình).
+- Compose entry đã inject mọi env cần (verified) — KHÔNG sửa compose.
+
+### 4.4 JWT enforcement (lớp 2 — token-contract §4)
+- `JwtVerifier`: jjwt — HS256, `SecretKeySpec(JWT_SECRET UTF-8 bytes)` (khớp node `jsonwebtoken`),
+  tự check `exp`, `requireIssuer("auth-mock")`. `JWT_SECRET` thiếu → fail-fast lúc boot.
+- `JwtAuthFilter` (OncePerRequestFilter): mọi route TRỪ `/healthz`, `/readyz`, `/actuator/**`,
+  `/v3/api-docs/**`, `/swagger-ui/**`, VÀ mọi `OPTIONS` preflight (preflight không mang Authorization —
+  chặn = CORS native gãy hoàn toàn; có test). Business data không lộ qua swagger docs (chỉ schema tài
+  liệu; auth-mock precedent).
+  Fail bất kỳ (missing/bad-format/bad-sig/expired/wrong-iss) → **401 envelope** `{error:{code:"UNAUTHORIZED",
+  message, requestId}}` — 401 TỪ SERVICE, không tin gateway.
+- ADR (README): filter tự viết thay spring-security resource server — mock 1 secret HS256, điểm cắm OIDC
+  = đổi filter sang JWKS/RS256, claims giữ nguyên.
+
+### 4.5 API surface — FINAL PATH TABLE (P0 fix spec-critic: OpenAPI servers.url + path = full path)
+Contract-resolved (khớp gateway pass-through `/api/users/*` + codegen base-path default `/api/users`):
+
+| Method | FINAL path (mounted) | Ghi chú |
+|--------|---------------------|---------|
+| GET/POST | `/api/users/users` | list (limit/offset) / create |
+| GET/PATCH | `/api/users/users/{userId}` | get / update |
+| GET/POST | `/api/users/teams` | list / create |
+| GET | `/api/users/teams/{teamId}` | kèm memberIds |
+| GET | `/healthz`, `/readyz` | **naked, hand-written** (conventions/02) — generated `getHealthz/getReadyz` mirror cùng handler (qua gateway sẽ 401 khi thiếu token — bình thường, probe dùng naked) |
+
+- ⚠️ `/api/teams` (spec-literal) KHÔNG tồn tại: gateway không route → mọi consumer đi đúng contract path trên.
+- Users behavior: POST thiếu `roles` → default `["user"]` server-side (contract default — codegen không apply
+  khi deserialize; test case riêng); PATCH minProperties 1 → 400 nếu body rỗng; `limit` ngoài [1,100] → 400
+  (`@Validated` method-validation); POST teams `memberIds` dedupe trước insert (tránh PK violation 500);
+  email uniqueness case-sensitive (DB UNIQUE — ghi README; auth-mock login lowercase là đủ demo).
+- Error envelope (conventions/04) qua `@RestControllerAdvice`: 400 VALIDATION_ERROR / 401 UNAUTHORIZED /
+  404 NOT_FOUND / 409 CONFLICT / 500 INTERNAL (không lộ stack); echo `X-Request-Id` vào `requestId` + MDC log.
+
+### 4.6 Health & logging & CORS
+- `/healthz` → `{"status":"ok"}` (shape CỐ ĐỊNH — CI grep); `/readyz` → thật: query `SELECT 1` trên
+  DataSource + Flyway applied, fail → 503 envelope; actuator liveness `/actuator/health/liveness` (probes enabled).
+- Logback: `LogstashEncoder` fieldNames `timestamp=ts, message=msg`, customFields `service=spring-svc`,
+  MDC `requestId`; `LOG_LEVEL` env → `logging.level.root` (relaxed binding). **Level lowercase** —
+  LogstashEncoder mặc định emit `INFO` uppercase, conventions/03 bắt buộc `info`: custom
+  `LowercaseLevelJsonProvider` (provider class tự viết ~10 dòng, đăng ký trong logback-spring.xml).
+  Không log token; email mask.
+- CORS: `WebMvcConfigurer` bean `@Profile("dev")` — đọc `CORS_DEV_ORIGIN` (comma list), methods
+  GET/POST/PATCH, headers Authorization/Content-Type/X-Request-Id. Compose (default profile) → list rỗng →
+  không emit ACAO (deny-by-default, conventions/07).
+
+### 4.7 Test strategy (CI = Postgres thật, KHÔNG H2)
+- CI service container `postgres:16-alpine` **mount `platform/postgres/init/`** → init script chạy thật
+  — container env PHẢI ĐỦ cho `set -euo pipefail` init: `POSTGRES_USER/PASSWORD/DB` + 4 password
+  `NODE_SVC_DB_PASSWORD, SPRING_SVC_DB_PASSWORD, GO_SVC_DB_PASSWORD, GO_READONLY_DB_PASSWORD`, ports 5432:5432.
+  Datasource test: `SPRING_DATASOURCE_URL=jdbc:postgresql://localhost:5432/boilerplate`,
+  `SPRING_DATASOURCE_USERNAME=spring_svc`, `SPRING_DATASOURCE_PASSWORD=<giá trị SPRING_SVC_DB_PASSWORD env>`.
+- `@SpringBootTest` (webEnvironment MOCK, MockMvc): seed-id-match (đọc `contracts/auth/users.json` thật
+  qua `USERS_FIXTURE_PATH`); JWT filter 5 case (valid/expired/garbage/missing/wrong-iss) + OPTIONS preflight
+  skip; users API (list/get/post/patch/404/409/400 + POST-no-roles default); teams API (list/get/post +
+  duplicate memberIds); healthz/readyz shape; envelope shape.
+- **Test isolation**: CRUD/PATCH tests `@Transactional` (rollback sau mỗi test) → không làm bẩn bảng
+  `users`/`teams`; seed-id-match test KHÔNG transactional + chạy độc lập (assert bảng users == fixture).
+- Local không JDK → test chỉ chạy CI (README ghi rõ; toolchain-in-Docker là đường chính theo brief).
+
+### 4.8 Docker & CI
+- Dockerfile theo conventions/01 nguyên văn (deps `dependency:go-offline` → build `package -DskipTests`
+  → runtime temurin-21-jre-alpine, USER 1001, EXPOSE 8081). `.dockerignore`: target, .git, test artifacts.
+- `.github/workflows/services-spring-svc.yml` từ template: (1) build-test `./mvnw -B verify` + postgres
+  service container (env đủ 4 DB password — §4.7) + init mount + `USERS_FIXTURE_PATH` tuyệt đối;
+  (2) docker-build; (3) boot-smoke compose up postgres+auth-mock+spring-svc+gateway → naked healthz/readyz
+  → login auth-mock qua gateway → GET `/api/users/users/{aliceId}` 200 → direct :8081 no-token/garbage-token
+  → 401; (4) drift-guard snapshot diff.
+- **Path-filter** (`on.push.paths` + `pull_request.paths`): `services/spring-svc/**`, compose entry,
+  workflow file, **`contracts/openapi/users.yaml`** (template không có — thêm, để drift-guard không mù khi
+  đổi contract mà không đụng spring-svc).
+
+## 5. Impl outline
+
+9 tasks: (1) scaffold+pom+wrapper+codegen; (2) V1 DDL+entities+repos; (3) V2 seed+match-test;
+(4) JWT filter+tests; (5) users API+tests; (6) teams API+tests; (7) health/logging/CORS+tests;
+(8) swagger+Dockerfile+README; (9) CI workflow+evidence. Commit atomically per task, `feat(sf-3): …`.
+
+## 6. Risks & unverified assumptions
+
+| # | Risk/assumption | Xử lý |
+|---|-----------------|-------|
+| 1 | Version pin (Boot 3.5.x, springdoc 2.8.x, ogp 7.x) không tồn tại trên Maven Central | Chỉ dùng version đã release trước 6/2026; sai → CI fail rõ ràng, bump 1 lần |
+| 2 | openapi-generator spring + useSpringBoot3 + jjwt/jackson conflict | Generator chỉ emit POJO + annotation; verify ở task 1 (compile green gate) |
+| 3 | Hibernate + `text[]` mapping | `@JdbcTypeCode(SqlTypes.ARRAY)` Hibernate 6.6; seed test chặn ngay task 3 |
+| 4 | Flyway Java migration reflection (no-arg ctor, không thấy Spring beans) | Dùng System.getenv + plain JDBC qua `Context.getConnection()` — đúng API BaseJavaMigration |
+| 5 | JWT interop với auth-mock | Verified: node jsonwebtoken HS256 = UTF-8 bytes; boot-smoke login thật là proof cuối |
+| 6 | CI-only verify loop chậm | Gom test đủ dày mỗi commit; escape-hatch 2-fail-same-cause của workflow |
+| 7 | Codegen base-path không khớp FINAL path table | Verify ngay task 1 (context-load + api-docs paths assertion ở test) |