create-wakii-stack 0.0.0-stage → 0.1.1

package/stack-template/docs/superpowers/specs/2026-10-12-sf-7-convergence-spec.md

@@ -0,0 +1,114 @@
+# SF-7 Spec — Convergence & Scaffold (FI-75)
+
+> Story FI-62 · SF-7/7 (tier 3, phase 3/3) · 2026-10-12
+> Source: epic spec rev 3 (`2026-10-12-boilerplate-microservice-mfe.md`) + context pack `docs/superpowers/contexts/sf-7.md`
+> Status: Approved — autonomous mode (epic-level đã qua spec-critic rev 3 + plan-critic; SF slice hội tụ, KHÔNG thêm quyết định mới ngoài epic). Brainstorm self-answered theo Phase 2 mandate.
+
+## 0. Root cause analysis
+
+**5 Whys**: Vì sao cần SF-7? → Vì SF-1..6 xây song song, mỗi SF chứng minh phần MÌNH. → Không artifact nào chứng minh CHUỖI 3 service chạy liền mạch như code committed. → Docs viết ở thời SF-1 đã lệch thực tế (README còn nói "khung rỗng"). → Người copy boilerplate không có đường đi từ fresh-clone đến demo chạy được. → Vấn đề thật: **hội tụ + chứng minh + bàn giao**, không phải viết thêm tính năng.
+
+Hiện trạng (dest @ec7c3d3): 6 services impl xong + CI per-stack xanh + browser e2e SF-6 verify native; thiếu: smoke script committed, copy-dir proof trong CI, health-gated compose chain, ADR/toolchain/walkthrough, scaffold, security-audit cuối.
+
+Chiến lược: **hội tụ tại chỗ** (không re-architect); mọi bug business logic thấy được ở `services/`/`frontend/` = report coordinator, KHÔNG fix (SF sở hữu fix).
+
+## 1. Problem
+
+Người mua boilerplate (dev team nội bộ) phải: (a) tin chuỗi e2e chạy được — chưa có proof committed; (b) copy 1 repo-con ra dùng riêng — chưa được chứng minh trong CI; (c) sinh project mới từ boilerplate — chưa có script; (d) đọc docs để tự chạy từ fresh-clone — docs đang stale; (e) nhận được code sạch bảo mật — chưa có audit cuối.
+
+## 2. Scope
+
+**In:**
+1. `scripts/smoke/e2e.sh` — curl API-level qua gateway: login auth-mock → POST task (node-svc, assignee validate qua spring) → GET feed (go-svc); assert task title xuất hiện trong feed + stats đúng.
+2. CI convergence workflow (file RIÊNG, không đụng template SF-1): job e2e-smoke (docker compose up + chạy e2e.sh), job copy-dir-smoke (copy ≥1 service + `frontend/shared` ra tmp → build/test pass), job scaffold-verify (chạy scaffold → output `pnpm install` + build được).
+3. `platform/docker-compose.yml`: healthcheck wget busybox `/readyz` cho **node-svc + spring-svc** (đã probe: node:22-alpine + eclipse-temurin:21-jre-alpine đều có busybox wget) + health-gated `depends_on` — CHỈ phần này được sửa trong compose. **go-svc NGOẠI LỆ có chủ đích** (P0 spec-critic): runtime distroless không shell/wget, Dockerfile READ-ONLY → healthcheck in-container bất khả; gateway gate `service_started` cho go-svc; readiness go-svc chứng minh bằng e2e.sh poll `/api/activity/stats` trước feed assert (retry). **Gateway KHÔNG thêm healthcheck** (P1 spec-critic vòng 2: nginx proxy thuần không route /readyz — probe sẽ 404 deadlock; wait đã do e2e.sh poll `/api/auth/readyz` đảm nhiệm). Exception ghi vào conventions/02 rule 3.
+4. Docs: ADR 7 quyết định (mixed stack, MF/Rspack, contract-first, readonly schema trade-off, fail-closed vs degrade, fire-and-forget events, fork-not-upgrade), toolchain doc (JDK/Go/Node/pnpm/docker cần ở đâu), fresh-clone walkthrough checklist, README sync (Mermaid + hướng dẫn chạy = kiến trúc thật).
+5. Scaffold script `scripts/scaffold/` — copy + rename + prune thuần (bash), sinh project đặt tên mới, cùng flow chạy được. Trễ = scope-flag lên user, KHÔNG auto-complete manual fallback.
+6. Xử lý 2 findings SF-1-owned — **nguồn uỷ quyền: story brief FI-62 (.story-brief.md dòng 3) chỉ đích danh SF-7 xử lý** (commit ec7c3d3 là recovery của chính brief): conventions/02 mirror rule healthcheck paths (improvements-log SF-4 finding #4); canonical DDL note tách CREATE SCHEMA khỏi tables (improvements-log SF-4 finding #5). Rà thêm các [p6-flag] conventions sync cùng nguồn uỷ quyền (dòng "rà các [p6-flag] conventions sync"): conventions/01 standalone-lockfile variant (SF-2 flag), conventions/08 requiredVersion:false singleton (SF-6 flag). Sửa compose thì cập nhật banner ownership (SF-7 convergence).
+7. Security-audit checkpoint (secrets/exec-bit/lockfile/deps OWASP surface) — 0 P0/P1 mở.
+8. Rà multi-stage + pinned base images toàn bộ Dockerfile (report, không sửa trừ khi P0).
+9. Rule 0: smoke chạy THẬT native local + evidence; browser walkthrough = human gate — ghi hướng dẫn sẵn cho user.
+
+**Out:** browser trong CI; fix business logic services/FE; merge main/PR; tính năng mới; k8s; Keycloak thật.
+
+## 3. Touch map
+
+| File | Hành động |
+|---|---|
+| `scripts/smoke/e2e.sh` | tạo [SỞ HỮU] |
+| `scripts/scaffold/**` | tạo [SỞ HỮU] |
+| `.github/workflows/convergence.yml` | tạo [SỞ HỮU — file convergence riêng] |
+| `docs/adr/**`, `docs/toolchain.md`, `docs/walkthrough.md` | tạo [SỞ HỮU] |
+| `README.md` | sửa (sync cuối) |
+| `platform/docker-compose.yml` | sửa — CHỈ healthcheck + depends_on chain |
+| `platform/conventions/02-healthcheck.md`, `01-dockerfile-pattern.md`, `08-gateway-and-remotes.md` | sửa — sync findings [p6-flag] |
+| `contracts/db/tasks-schema.sql` | sửa — note CREATE SCHEMA (comment-only, không đổi DDL) |
+| `services/*`, `frontend/*` | READ-ONLY |
+| `.github/workflow-templates/` | READ-ONLY (thiếu gì = flag) |
+
+## 4. Design
+
+### 4.1 e2e smoke script (API-level)
+- Bash thuần + curl + jq-light (grep/python-free fallback? — dùng grep + sed, tránh jq dependency; CI ubuntu có jq nhưng script phải chạy được local Git Bash). Quyết: dùng `node -e` KHÔNG — giữ curl+grep thuần; JSON assert bằng grep pattern ổn định theo contract (accessToken, title echo, feed items chứa title).
+- Env: `GATEWAY_URL` (mặc định `http://localhost:8080`), `SMOKE_EMAIL`/`SMOKE_PASSWORD` (mặc định alice@demo.local/demo-password), `SMOKE_TITLE` prefix unique theo `date +%s` để re-run được.
+- Chain assert: login 200 + accessToken → POST /api/tasks 201 (assigneeId = bob UUID để đi qua spring validate) → GET /api/activity/feed có item action `task.created` chứa title — **poll 10×1s** (P1 spec-critic: node push fire-and-forget KHÔNG await, go-svc persist async → assert ngay = flaky CI) → GET /api/activity/stats: fetch **baseline totalTasks TRƯỚC khi tạo task**, assert sau ≥ baseline+1. Exit non-zero + message rõ khi fail ở bước nào. Wait-before-assert: poll `/api/auth/readyz` QUA gateway :8080 (gateway không có /readyz riêng — P2 critic).
+- Cùng 1 script dùng cả native lẫn qua gateway: chỉ cần GATEWAY_URL trỏ đúng.
+
+### 4.2 Health-gated compose
+- Healthcheck `/readyz` (wget busybox) **CHỈ node-svc + spring-svc** — đã probe Dockerfile: cả hai runtime alpine có busybox wget.
+- **go-svc: `service_started`** (distroless, Dockerfile READ-ONLY — P0 spec-critic); readiness chứng minh ở e2e.sh poll stats.
+- **Gateway: KHÔNG healthcheck** (nginx không route /readyz — probe 404 deadlock, P1 critic vòng 2); wait do e2e.sh đảm nhiệm.
+- Chain: postgres (healthy) → auth-mock (healthy, existing) → node/spring (healthy, mới); node-svc depends_on spring-svc healthy (readyz node kiểm spring reachable); gateway depends_on auth-mock + node + spring `service_healthy`, go-svc `service_started`.
+- Validate: `docker compose --env-file platform/.env.example config -q` (KHÔNG cần Docker daemon) + CI chạy thật.
+
+### 4.3 CI convergence.yml
+- Trigger: `branches: ["**"]` + workflow_dispatch (workflow hội tụ — chạy full, không path-filter; P2 critic: tránh CI âm thầm không chạy khi branch rename).
+- Job `e2e-smoke`: checkout → `docker compose --env-file platform/.env.example up -d --build` (reuse .env.example — P2 critic, thay "sinh .env 10 biến") → poll `/api/auth/readyz` qua :8080 → `bash scripts/smoke/e2e.sh` → dump logs khi fail (compose gọi lại CÙNG `--env-file` — p6-flag SF-2).
+- Job `copy-dir-smoke`: copy `services/node-svc` + `frontend/shared` → `$RUNNER_TEMP/standalone` → node-svc: `pnpm install --ignore-workspace && pnpm test && pnpm build` (theo README standalone); fe-shared: typecheck `tsc --noEmit` (fe-shared không có scripts riêng; GHI RÕ trong job: fe-shared inert cho node-svc — proof FE copy-dir mạnh hơn = remote-tasks kèm shared, để làm follow-up nếu CI budget cho phép; Acceptance #6 context pack là "≥1 service + fe-shared").
+- Job `scaffold-verify`: chạy `scripts/scaffold/scaffold.sh --name demo-app --out $RUNNER_TEMP/demo-app` → `pnpm install --no-frozen-lockfile` + build FE shell + `docker compose config -q` trong output → pass. **Narrowing tường minh (cite context pack sf-7.md ACCEPTANCE: "CI verify scaffold output build được")**: CI chỉ chứng minh build + compose-config trên output; full e2e trên scaffold output = **human gate** cần Docker — hướng dẫn nằm trong SCAFFOLD.md + walkthrough.
+- Không browser, không secret ngoài placeholder CI.
+
+### 4.4 Scaffold
+- `scripts/scaffold/scaffold.sh <new-name> [--out dir]`: **cp/tar-based (KHÔNG rsync — không có mặc định trong Git Bash Windows, P2 critic)** trừ `.git`, `.github/workflow-templates`, `docs/superpowers`, `node_modules`, `frontend/spike`, `.story-brief.md`; **prune `.github/workflows/convergence.yml`** (pin story branch — chết trong repo mới; giữ per-service workflows + contracts.yml vì generic + path-filtered); rename: package names `@boilerplate/*` → `@<new-name>/*` (kể cả root `package.json` name — P2 critic), compose `name:`, README title; xử lý root `pnpm-lock.yaml` importers (strip spike + rename scope — probe tại task); giữ contracts + platform + services + frontend/shell + remotes + shared + scripts/smoke; ghi `SCAFFOLD.md` nguồn gốc + ngày + hướng dẫn full-e2e human gate. Không generator framework.
+- Windows dev: bash script chạy Git Bash (docs ghi rõ); CI chạy ubuntu. exec-bit không set từ Windows — CI/README gọi `bash scripts/...` (ghi vào audit).
+
+### 4.5 Docs
+- `docs/adr/README.md` index + 7 ADR ngắn (1 file/quyết định, format: Context/Decision/Consequences).
+- `docs/toolchain.md`: bảng tool × ai cần (dev native / CI / copy-user).
+- `docs/walkthrough.md`: fresh-clone checklist số bước, cả compose lẫn native, khớp đúng lệnh đã verify trong evidence.
+- README: cập nhật kiến trúc (6 services đủ), mục Chạy (compose + native + smoke), repo map mới, xoá state SF-1 stale.
+
+### 4.6 Findings + conventions sync
+- conventions/02: thêm mirror rule — service expose `/healthz`+`/readyz` naked VÀ mirror dưới prefix `/api/<svc>/*` (auth-mock precedent) để OpenAPI servers.url + schemathesis khớp.
+- tasks-schema.sql: comment note — phần CREATE SCHEMA tách Apply context (db-level CREATE privilege) khỏi table DDL (schema-level); CI apply-as-role chạy 2 phần bằng user khác nhau.
+- conventions/01: variant standalone lockfile (COPY local lockfile khi build context = thư mục con).
+- conventions/08: singleton remote khai `requiredVersion: false` tường minh (`catalog:` literal rò vào requiredVersion).
+- 04-error-envelope: note additionalProperties decision? — chỉ ghi khi quyết chung đã có ở node-svc; KHÔNG tự chốt thay 3 service (flag nếu chưa chốt).
+
+### 4.7 Security checkpoint
+- security-audit agent trên toàn diff + repo scan: secrets (gitleaks đã có CI — review kết quả), exec-bit scripts, .env không commit, lockfile sync, deps surface (OWASP theo tính năng: JWT HS256 shared secret, CORS dev-profile, gateway 401).
+- 0 P0/P1 mở mới được DONE.
+
+## 5. Implementation outline
+
+10 tasks (DAG):
+1. `docs-sync` — conventions sync + DDL note (T1) — không phụ thuộc
+2. `compose-health` — health-gated compose (T2) — phụ thuộc đọc Dockerfile 3 svc (probe trong task)
+3. `smoke-script` — e2e.sh (T3) — không phụ thuộc
+4. `ci-smoke` — convergence.yml job e2e-smoke (T4) — phụ thuộc T2+T3
+5. `ci-copydir` — job copy-dir-smoke (T5) — phụ thuộc đọc README node-svc
+6. `scaffold` — scaffold.sh (T6) — không phụ thuộc
+7. `ci-scaffold` — job scaffold-verify (T7) — phụ thuộc T6
+8. `adr-toolchain` — ADR 7 + toolchain.md (T8) — không phụ thuộc
+9. `readme-walkthrough` — README sync + walkthrough.md (T9) — phụ thuộc T8 (link ADR) + T3 (lệnh smoke)
+10. `verify-evidence` — Rule 0 native smoke + evidence + security-audit + independent review (T10) — phụ thuộc T1-T9
+
+Test strategy: smoke script chạy thật native (evidence); `docker compose config` validate compose; CI xanh sau push là gate thật cho 3 job mới; docs không có test — walkthrough phải khớp lệnh đã chạy.
+
+## 6. Risks
+
+- Dockerfile image base có/không curl/wget cho healthcheck → probe từng Dockerfile trước khi viết compose (không đoán).
+- Feed action string thật ("task.created"?) → đọc node-svc source event push (READ-ONLY) trước khi viết assert.
+- CI compose job dùng `.env` — compose `${VAR:?}` fail hard nếu thiếu → job phải sinh .env đủ 10 biến.
+- pnpm-lock trong scaffold output — copy nguyên lockfile + `pnpm install` lại (importers giữ nguyên tên workspace? rename `@boilerplate/*` phá lockfile importers → scaffold phải update importers trong lockfile hoặc chạy `pnpm install --no-frozen-lockfile` trong job verify; quyết tại T6, probe trước).
+- Native toolchain `~/Tools/sf6-e2e` phải còn sống (đã verify ✓) — start scripts tái dùng.

package/stack-template/docs/superpowers/specs/2026-10-12-sf2-node-svc-spec.md

@@ -0,0 +1,42 @@
+# SF-2 Spec — node-svc task API (FI-70)
+
+> Derived từ epic spec `2026-10-12-boilerplate-microservice-mfe.md` rev 3 (đã user-approved + spec-critic + plan-critic ở epic level) + context pack `docs/superpowers/contexts/sf-2.md`. SF dispatch 2026-10-12, worktree `__STACK_ORG__/sf-2-node-svc`. Spec-critic vòng 1: FIX-P0-FIRST → 2 P0 đã resolve + P1/P2 pinned (xem §Decisions).
+
+## Problem
+`services/node-svc/` là khung rỗng. Epic cần service task CRUD chạy được qua gateway để chứng minh acceptance #2 (tạo task → user được spring validate).
+
+## Scope (in)
+1. Scaffold Fastify + TypeScript, Node 22 LTS, pnpm (workspace entry đã khai trong `pnpm-workspace.yaml`).
+2. Codegen types từ `contracts/openapi/tasks.yaml` (`openapi-typescript`, types only) — **output commit** (`src/types/api.d.ts`, contracts/ ngoài docker build context nên không gen trong image); CI re-generate + `git diff --exit-code` chống drift.
+3. CRUD: POST/GET/GET-by-id/PATCH/DELETE `/api/tasks/*` (service tự mount prefix — gateway pass-through), port 3001. Non-uuid `taskId` → 400 `VALIDATION_ERROR`; không thấy task → 404 code `TASK_NOT_FOUND` (đúng ví dụ tasks.yaml; conventions/04 catalog là "tối thiểu").
+4. Validate user: tạo/sửa khi có `assigneeId` → gọi `GET {SPRING_SVC_URL}/api/users/{id}` timeout 2s. spring 404 → **422 UNPROCESSABLE**; spring down/timeout → **503 DEPENDENCY_DOWN fail-closed** (task KHÔNG ghi; ADR degrade ghi README).
+5. Event push fire-and-forget: sau mutate thành công → `POST {GO_SVC_URL}/api/activity/events`, payload `ActivityEventInput` (activity.yaml), action `task.created|task.updated|task.deleted`. **Không await** (đáp trả ngay sau khi DB commit), fetch có `AbortSignal.timeout(2000)` (không leak socket khi go-svc hang), `.catch` → pino warn `event push failed`, không retry.
+6. Postgres schema `tasks` + migration drizzle-orm khớp canonical DDL `contracts/db/tasks-schema.sql`. **Diff methodology (spec-critic P1): so sánh cấu trúc chuẩn hoá** — schema/columns(type/nullability/default)/CHECK definition/3 indexes (incl. `created_at DESC`) — đã implement trong `src/db/schema-diff.test.ts` (bỏ khác biệt cosmetic: quote/comment/USING btree/NULLS LAST/tên constraint). Migration `CREATE SCHEMA IF NOT EXISTS` (idempotent với schema init script 01-init.sh đã tạo sẵn). id = uuid v4 app-generated; status varchar + CHECK; bảng do role `node_svc` tạo (search_path tasks) — xem §Decisions D1 về compose bug.
+7. `/healthz` naked 200 `{"status":"ok"}`; `/readyz` naked = DB migrated + SELECT ok (503 envelope khi fail); **mirror `/api/tasks/healthz` + `/api/tasks/readyz`** (pattern auth-mock — contract fixtures theo tasks.yaml servers.url chạy được). Boot-time spring reachability check 1 lần + log warn, KHÔNG gate ready (deviation so với conventions/02 + summary tasks.yaml — cite cả hai trong README; fail-closed enforce ở request-time mục 4). Lưu ý: check này chỉ có tác dụng observability — executor KHÔNG tự invent gating.
+8. JWT: tự verify HS256 (JWT_SECRET) + exp + iss=`auth-mock` trên mọi business route; 401 envelope `UNAUTHORIZED`. healthz/readyz (cả naked lẫn mirror) không auth.
+9. JSON log pino shape conventions/03 (ts/level/service/msg/requestId từ X-Request-Id); error handler map mọi error (kể cả FST_ERR_*) sang envelope conventions/04.
+10. CORS `@fastify/cors` origin từ `CORS_DEV_ORIGIN` (deny-by-default khi rỗng), methods GET/POST/PATCH/DELETE, headers Authorization/Content-Type/X-Request-Id.
+11. Swagger UI `/api/tasks/docs` (mirror tối thiểu tasks.yaml). **Acceptance "swagger mở được" = native** `localhost:3001/api/tasks/docs` (browser-verify khi chạy local); qua gateway :8080 thì cần Bearer header (CI curl-verify được — gateway presence-check chặn browser không token).
+12. Tests vitest: unit routes (happy CRUD, 400/401/404/422/503 với fake spring inject, fire-and-forget go-svc down → vẫn 201 + warn), healthz/readyz (DB fail → 503), schema-diff. Mọi external call inject qua app factory opts (không network thật).
+13. Dockerfile multi-stage theo conventions/01 (node:22-alpine, `pnpm install --frozen-lockfile`, build dist, USER node, EXPOSE 3001) + `.dockerignore`. **Lockfile strategy (spec-critic P0-2):** local standalone `services/node-svc/pnpm-lock.yaml` (sinh bằng `pnpm install --ignore-workspace`) vì compose build context = `services/node-svc` không thấy root lockfile; root `pnpm-lock.yaml` (workspace) phục vụ dev/CI native — **root lockfile là file touched**, commit cả hai.
+14. CI `.github/workflows/services-node-svc.yml`: (a) build+test native (root `pnpm install --frozen-lockfile` + `pnpm --filter node-svc test` + build + typegen drift check); (b) docker build; (c) **boot-smoke**: `docker compose up -d --build postgres node-svc` (init thật tạo role node_svc; DATABASE_URL từ compose — GAP-ANSWER D1: coordinator đã fix @ab207d8 thành `postgres://node_svc:${NODE_SVC_DB_PASSWORD}@...`) → healthz/readyz 200 trên localhost:3001 → ký JWT CI (node crypto, không deps) → POST task **KHÔNG assigneeId** → 201 (với go-svc vắng mặt = evidence fire-and-forget) → GET list thấy → DELETE 204.
+15. README `services/node-svc/`: chạy native + docker, env vars (+ default native SPRING_SVC_URL/GO_SVC_URL `localhost:8081/8082`), API summary, failure semantics + ADR degrade, readyz deviation note (cite conventions/02 + tasks.yaml), ghi chú PATCH không thể null `assigneeId` (UpdateTaskRequest.assigneeId non-nullable trong tasks.yaml). Exit: docs đủ standalone (copy-dir là việc SF-7).
+
+## Env consumed (đã pre-seed trong compose — KHÔNG thêm biến mới vào .env.example)
+`PORT`(3001), `DATABASE_URL` (role node_svc), `JWT_SECRET`, `SPRING_SVC_URL`, `GO_SVC_URL`, `CORS_DEV_ORIGIN`, `LOG_LEVEL`.
+
+## Out of scope / boundary
+- KHÔNG sửa compose, contracts, conventions, gateway, postgres init, fe-shared, .env.example, pnpm-workspace.yaml (đụng = FLAG coordinator).
+- KHÔNG implement spring-svc/go-svc/FE. KHÔNG CORS-wide. KHÔNG docker local.
+
+## Decisions (spec-critic vòng 1, 2026-10-12)
+- **D1 (P0) compose DATABASE_URL sai credential semantics — RESOLVED**: flag đã gửi coordinator; GAP-ANSWER 2026-10-12: fix landed trên dest @ab207d8 (`postgres://node_svc:${NODE_SVC_DB_PASSWORD}@...` khớp init roles). SF-2 đã merge dest; boot-smoke dùng compose entry chuẩn, KHÔNG override.
+- **D2 (P0) lockfile vs build context**: giữ workspace membership (SF-1 seeded); thêm local standalone lockfile cho Docker path (mục 13). Đã verify root `pnpm install --frozen-lockfile` vẫn sạch với local lockfile tồn tại.
+- **D3 (P1) readyz**: ready = DB only; spring check boot-time warn-only — SF-3 song song chưa tồn tại, readyz gate cứng vào spring làm boot-smoke CI không thể xanh.
+
+## Acceptance (mirror context pack)
+- Swagger node-svc mở được (native, mục 11); tạo task với user fixture → task hiện trong list; assignee không tồn tại → 422 rõ.
+- Spring down (mocked test) → 503, không ghi nửa chừng.
+- CI xanh: build+test + docker build + boot-smoke (healthz/readyz 200, migration xong, task create/list/delete smoke, 201 khi go-svc vắng).
+- Migration khớp 100% canonical DDL (schema-diff test, methodology mục 6).
+- go-svc down → tạo task VẪN thành công (warn log) — fire-and-forget.

package/stack-template/docs/superpowers/specs/2026-10-13-kafka-outbox-saga.md

@@ -0,0 +1,111 @@
+# Epic Spec — Kafka + Transactional Outbox + Saga (mở rộng FI-62)
+
+> Story: pending epic ID · tạo 2026-10-13 · pipeline: story-workflow CREATE
+> Repo: `__STACK_ORG__/architecture-overview` (main @0785930 — boilerplate FI-62 đã merge)
+> Phase 0: analyst xong (3 P0 đã hấp thụ: CHECK constraint 2 đầu, resolver bearer, CI go-svc hard-code ingest)
+> Rev 2 — sau spec-critic (FIX-P0-FIRST): varchar(40) cho action; PATCH event matrix chốt; TaskStatus tách writable/extended; ownership activity.yaml→SF-3, DDL-node-cụm→SF-2 nguyên tử; go workflow 3 touch points pin phương án; resolver login backoff + lazy re-login; compensation UPDATE conditional
+> Rev 3 — sau plan-critic (FIX-P0-FIRST, 5 P0): SF-1 pre-add env consumers (compose+.env.example); SF-2 thêm task services-node-svc.yml kafka boot-smoke + pin schema-diff.test whitelist outbox; SF-1 golden envelope fixtures (2 đầu test load chung); FE remote-tasks badge → SF-3; SF-4 cắt false dep (tier 0 song song SF-1); checkpoint-1 convergence đỏ tạm ghi rõ; e2e assert DLQ; activity.yaml ×2 file + diff-guard
+
+## IDEA-BRIEF (8 chiều)
+
+- **Task**: Nâng luồng event của boilerplate từ REST fire-and-forget (ADR-0006 tự nhận mất-mất) lên **Kafka + Transactional Outbox + Saga choreography**; thêm demo @Transactional nhiều step cho spring-svc.
+- **Output**: Boilerplate vẫn `compose up` được (10 services), có topic `task-events` + DLQ, outbox pattern, saga compensation demo, ADR-0008; CI toàn green.
+- **Users**: Team copy boilerplate — học được: transactional outbox, at-least-once + idempotency, consumer retry/DLQ, saga compensation, @Transactional.
+- **Constraints**: Kafka single-node **KRaft** (`apache/kafka`, KHÔNG expose 9092 ra host); JSON envelope + `schemaVersion` (không Avro/Registry); outbox relay **tự viết** poll 500ms; saga **choreography**; CI-only verify (user máy yếu); không service nào `depends_on: kafka: service_healthy` (chain 9 service nguyên vẹn, connect lazy).
+- **Input**: Code main @0785930 (đã probe: node push tại `routes/tasks.ts:222-234` ×3 điểm, go ingest `internal/api/events.go`, spring chưa có service layer, compose 9 services health-gated).
+- **Context**: RAM CI 7GB — Kafka heap ~512MB; user không chạy local.
+- **Success criteria**: (1) compose up 10 services xanh; (2) tạo task → event qua outbox → Kafka → go consume → feed hiện (at-least-once + idempotent — duplicate event không nhân đôi feed); (3) saga fail path: assign cho fixture fail-user → go fail ×3 → DLQ → compensating → task status `assignment_failed` thấy trên FE; (4) spring @Transactional rollback demo test xanh; (5) CI all green gồm convergence sửa đổi.
+- **Out-of-scope**: Schema Registry/Avro; Debezium; Kafka UI; SASL/SSL (PLAINTEXT compose-internal); multi-broker; Exactly-once semantics.
+
+## Quyết định đã chốt (user, 2026-10-12/13)
+
+| # | Quyết định | Chọn |
+|---|---|---|
+| U1 | Model kết quả compensation | Giá trị mới `assignment_failed` của `tasks.status` (cascade có kiểm soát ~6 file) |
+| U2 | Saga entry point | Reuse PATCH `assigneeId` hiện có (không thêm endpoint) |
+| U3 | REST ingest `/api/activity/events` | **Xóa sạch** (việc sửa CI go-svc hard-code thuộc SF-3) |
+| U4 | Kafka image + port | `apache/kafka` KRaft, compose-internal only (không expose 9092) |
+
+Tự quyết theo conventions (ADR-0008 ghi): `schemaVersion: 1` integer; topics `task-events` + `task-events.dlq`; 1 partition; consumer groups `go-svc-activity` + `node-svc-compensation`; `auto.offset.reset: earliest`; **manual commit sau DB tx**; retry in-memory ×3 rồi DLQ; envelope JSON `{schemaVersion, id, type, occurredAt, payload}` — `id` sinh ở NODE (UUID) để go dedupe `ON CONFLICT DO NOTHING` (at-least-once + idempotent); thư viện go = `segmentio/kafka-go` (ADR ghi franz-go là path production); outbox table trong schema `tasks` (cột `published_at`, purge note); ADR-0008 supersede ADR-0006.
+
+## Thiết kế chính
+
+### Saga flow "assign task" (choreography) — event matrix CHỐT (rev 2)
+
+**Event matrix (mỗi mutation → event, envelope id do node sinh MỖI event):**
+| Mutation | Event(s) trong cùng 1 outbox tx |
+|---|---|
+| POST create | `task.created` |
+| PATCH có `assigneeId` trong body | `task.assigned` (+ `task.updated` nếu body còn có field khác đổi) |
+| PATCH không có assigneeId | `task.updated` |
+| DELETE | `task.deleted` |
+| Unassign (assigneeId=null) | **KHÔNG trong scope** — schema hiện nhận string, không null; ghi rõ để executor không bịa `task.unassigned` |
+**Trigger predicate: PRESENCE-BASED** (body có assigneeId = bắn event, kể cả same-value). Same-value re-PATCH → event mới id mới → feed 2 dòng — chấp nhận, ADR-0008 ghi "value-compare là path production". Không cần đọc row cũ trong tx (repo đổi nhẹ hơn).
+
+**Pipeline:**
+```
+PATCH /api/tasks/{id} (body có assigneeId) — node-svc:
+  [1 tx: UPDATE task + INSERT outbox(task.assigned + task.updated?)]  ← Situation A demo
+relay (500ms poll) → publish task-events
+go-svc consumer (group go-svc-activity, filter-by-type: bỏ qua task.assignment_failed):
+  [1 tx: INSERT activity (ON CONFLICT DO NOTHING bằng envelope id) + simulate notify]
+  notify fail? → retry ×3 (in-memory) → publish task.assignment_failed (vào task-events) → DLQ original
+node-svc consumer (group node-svc-compensation, CHỈ nhận task.assignment_failed):
+  [tx: UPDATE task SET status='assignment_failed' WHERE id=? AND assignee_id=<event.assigneeId>
+   AND status NOT IN ('assignment_failed')]  ← CONDITIONAL guard: chống stale compensation
+```
+Re-assign sau `assignment_failed`: PATCH assigneeId hợp lệ (writable path) → saga chạy lại từ đầu.
+
+**TaskStatus tách (U1a cascade đúng):** `contracts/openapi/tasks.yaml` tách `TaskStatus` (3 giá trị — query param + PATCH body, WRITABLE) / `TaskStatusExtended` (4 giá trị + `assignment_failed` — chỉ `Task.status` response, READ-ONLY). PATCH **KHÔNG nhận** `assignment_failed` (system-owned); route hard-code 3 giá trị giữ cho query/body, chỉ response nới.
+
+**Simulate fail hook (deterministic cho e2e):** assign cho fixture user `svc-fail` (email `fail@demo.local`, trong users.json) → go consumer cố tình fail. Fixture users thêm 2 dòng: `svc-fail` + `svc-activity` (service user —cascade users.json một file, spring seed + auth-mock đọc tự nhiên).
+
+### Resolver bearer (P0 analyst): go consumer không có HTTP request
+go-svc **login bằng fixture service user `svc-activity` (password env) — retry backoff lúc boot, KHÔNG crash nếu auth-mock chưa lên (go chỉ depends_on postgres); lazy re-login khi resolver gặp 401/expiry** → cache JWT → resolver dùng token này enrich userName. Dạy pattern service-identity. auth-mock cấp token cho mọi fixture user — không sửa auth-mock ngoài fixture (SF-1).
+
+### Status cascade `assignment_failed` (U1a — ownership NGUYÊN TỬ, rev 2)
+- **SF-2 sở hữu NGUYÊN CỤM node-side**: canonical DDL `contracts/db/tasks-schema.sql` CHECK + `schema.ts` mirror + migration CHECK + `contracts/openapi/tasks.yaml` (TaskStatus split writable/extended) — sửa một cụm để schema-diff.test không đỏ giữa chừng. SF-1 KHÔNG đụng DDL/tasks.yaml.
+- **SF-3 sở hữu NGUYÊN CỤM activity-side**: `internal/store/migrations/0002` — **`ALTER COLUMN action TYPE varchar(40)`** (`task.assignment_failed` = 22 ký tự > varchar(20) hiện tại — chỉ sửa CHECK mà quên width = InsertEvent chết runtime) + CHECK drop/recreate thêm `task.assigned`/`task.assignment_failed` + `contracts/openapi/activity.yaml` TRỌN GÓI (xóa `/events` path + `ActivityEventInput` + `EventAccepted`, sửa enum action, description, stats keys) + `store/tasks.go` status map + FE remotes tests/tile verify.
+- SF-5 verify FE tổng thể.
+
+### P0 bắt buộc (mỗi mục 1 task tường minh, không drive-by)
+1. **CHECK + column width 2 đầu**: SF-2 (tasks.status CHECK + TaskStatus split) / SF-3 (activity.action **varchar(40)** + CHECK mới).
+2. **Resolver service-token** với login backoff + lazy re-login (trên).
+3. **`services-go-svc.yml` 3 điểm chạm** (rev 2 — enumerate đủ): (a) step event→feed→stats roundtrip POST /events → **thay bằng kafka console producer publish test event** (image apache/kafka có sẵn script) + kafka vào subset boot; (b) stats assert exact-equality 3 keys → nới cho key thứ 4; (c) chấp nhận chỉ khi boot-smoke còn ≥1 proof event→feed (chống thoái hóa). SF-3 sở hữu.
+4. **Compose ownership header**: SF-1 cập nhật header (sở hữu story này).
+5. **Kafka KHÔNG vào readyz/depends_on** — connect lazy + retry; `KAFKA_HEAP_OPTS` ~512MB.
+
+## SF split (5 SF — anti-duplicate checked: không pattern lặp ≥50%; SF-4 mỏng nhất 8 tasks vẫn giữ riêng vì stack/độc lập Kafka)
+
+### Tier 0 — SF-1 · Kafka foundation + async contracts (~12 tasks)
+Kafka entry compose (apache/kafka KRaft, heap 512m, healthcheck `/opt/kafka/bin/kafka-broker-api-versions.sh` full-path, KHÔNG depend_on, KHÔNG expose 9092) + `.env.example` env mới + header ownership; **PRE-ADD env cho downstream consumers (P0 plan-critic): KAFKA_BROKERS vào node-svc + go-svc entries; AUTH_MOCK_URL + SVC_ACTIVITY_PASSWORD vào go-svc — 1 lần sửa compose duy nhất để SF-2/3 không đụng compose**; `contracts/events/task-events.md` (envelope `{schemaVersion,id,type,occurredAt,payload}`, payload shape theo event type — CẦN TRƯỚC consumer go; filter-by-type convention 2 group cùng đọc task-events; topic/DLQ naming); **golden fixtures `contracts/events/fixtures/*.json`** — mỗi event type 1 file, SF-2 relay test + SF-3 consumer test + CI console-producer ĐỀU load chung (contract machine-checkable 2 đầu); `platform/conventions/09-async-messaging.md`; fixture `svc-fail` + `svc-activity` users (users.json — roles ["user"] khớp enum; spring V2 seed + auth-mock đọc tự nhiên); ADR-0008 supersede 0006 (ghi simplifications: presence-based trigger, in-memory retry count, plaintext); README compose section. KHÔNG đụng DDL/tasks.yaml/activity.yaml.
+
+### Tier 1 — SF-2 · node-svc Outbox + Producer + compensation consumer (~12 tasks)
+**Cụm nguyên tử node-side cascade**: canonical DDL CHECK `assignment_failed` + `schema.ts` mirror + migration + `tasks.yaml` TaskStatus split (writable 3 / extended 4 — PATCH cấm assignment_failed, route hard-code 3 giữ). **Pin schema-diff.test scope (P0 plan-critic): whitelist outbox với expected-def riêng, KHÔNG thêm vào canonical DDL, index-3 assert giữ nguyên** — hướng NGƯỢC làm đỏ copy-dir. Outbox table migration (schema tasks: id UUID do node sinh, type, payload jsonb, created_at, published_at nullable) + drizzle schema; **transactional repo API** (drizzle `.transaction()` gốc — đổi interface `TaskRepo` + fake; fake có seam tiêm lỗi cho test rollback; envelope id sinh trong repo); event matrix presence-based; relay worker poll 500ms (kafkajs) publish fixture-format + mark published_at (purge note); xóa `clients/activity.ts` + 5 refs; compensation consumer (group node-svc-compensation, conditional UPDATE guard) → `assignment_failed`; **task `services-node-svc.yml` kafka boot-smoke (P0 plan-critic): `up -d postgres kafka node-svc` + assert outbox row `published_at IS NOT NULL` (relay thật, không fake)**; tests: tx rollback (seam fail giữa 2 step), relay unit (fake producer load golden fixture), consumer unit; `KAFKA_BROKERS` lazy (env đã có từ SF-1); docs: README node-svc standalone ghi dependency contracts/db (FLAG sẵn có convergence.yml:62).
+
+### Tier 1 — SF-3 · go-svc Consumer + Saga + thanh lý ingest (~12 tasks)
+**Cụm nguyên tử activity-side cascade**: migration `0002` — `ALTER COLUMN action TYPE varchar(40)` + CHECK drop/recreate (`task.assigned`, `task.assignment_failed`) + **activity.yaml ×2 FILE** (canonical `contracts/openapi/activity.yaml` + snapshot nhúng `services/go-svc/internal/api/openapi/activity.yaml` — sửa 1 bỏ 1 = docs endpoint lệch im lặng; thêm diff-guard vào go workflow theo precedent spring) TRỌN GÓI (xóa /events path + ActivityEventInput + EventAccepted; enum action; description; stats keys) + `store/tasks.go` map + **FE remote-tasks badge `assignment_failed` (P0 plan-critic: type + statusLabel map + tests — gán đích danh SF-3)** + remote-activity action labels. Consumer package (segmentio/kafka-go, group go-svc-activity, manual commit sau tx, ON CONFLICT DO NOTHING bằng envelope id, filter-by-type, test load golden fixture); retry ×3 → publish `task.assignment_failed` vào task-events → DLQ original; resolver service-token (login svc-activity backoff + lazy re-login 401); xóa `api/events.go` ingest + wiring + tests cập nhật; **`services-go-svc.yml` 3 điểm chạm + diff-guard** (console producer publish golden fixture + kafka vào subset + tạo topic tường minh + stats assert nới — giữ ≥1 proof event→feed); simulate fail hook svc-fail; tests: consumer unit, idempotency (duplicate event 1 feed row).
+
+### Tier 0 — SF-4 · spring-svc @Transactional demo (~8 tasks)
+**KHÔNG depends-on SF-1 (false dep cắt — plan-critic): trigger rollback dùng alice@demo.local có sẵn**, không đụng kafka/compose/file nào SF-1 sửa → chạy song song SF-1 từ tier 0. `service/TeamService` (mới — service layer); endpoint tạo team + members qua N step, fail giữa chừng (member trùng email alice@demo.local) → **rollback toàn bộ**; controller delegate sang service; tests: happy + rollback assert (team không tồn tại sau fail) trên postgres service container; README. KHÔNG dính Kafka.
+
+### Tier 2 — SF-5 · Convergence + ADR sync + docs (~10 tasks)
+`convergence.yml`: boot 10 services, kafka heap, poll budget nới (outbox 500ms + Kafka latency), copy-dir giữ contracts/db (outbox KHÔNG vào canonical DDL — node-internal infra); `scripts/smoke/e2e.sh`: happy path (tạo task → feed) + saga path (assign svc-fail → poll status assignment_failed **+ assert DLQ: kafka-console-consumer đọc task-events.dlq thấy event gốc** — acceptance #3 đủ 2 nửa); FE remotes verify tổng thể trên stack thật; walkthrough + README sync (+ note Flyway V2 seed 1 lần — pgdata volume CŨ thiếu svc users → hướng dẫn `down -v` sau pull); ADR-0008 consistency rà; security pass cuối (9092 không expose, secrets không vào envelope); scaffold probe (kafka entry tự flow).
+
+## Phased-release
+- Phase 1 COMPLETE = SF-1..4 merged + **services workflows** xanh (node/go có Kafka trong boot-smoke riêng) → CHECKPOINT 1. **Ghi rõ (plan-critic): convergence.yml chạy trên mọi push — giữa lúc SF-2 merged mà SF-3 chưa, convergence đỏ cấu trúc (node publish, chưa có consumer) là ĐỘNG đã biết, KHÔNG tính verify-fail; merge SF-2/SF-3 cận nhau; tiêu chí checkpoint 1 = services workflows xanh.**
+- Phase 2 COMPLETE = SF-5 merged + convergence xanh 10 services + saga e2e 2 chiều (kèm DLQ assert) → STORY-COMPLETE candidates.
+
+## Acceptance (epic-level, user-visible)
+1. `compose up` 10 services xanh (Kafka không chặn chain — connect lazy).
+2. Tạo task → activity feed hiện **qua Kafka** (outbox → topic → consumer), duplicate event không nhân đôi feed (bằng chứng: go consumer unit test idempotency — ON CONFLICT DO NOTHING bằng envelope id).
+3. Assign task cho `svc-fail` → sau retry ×3 → task status `assignment_failed` (FE/PATCH GET thấy), event gốc nằm ở `task-events.dlq`.
+4. Assign cho user thường → feed hiện bình thường (happy saga).
+5. spring: tạo team fail giữa chừng → DB không có team lẫn members (rollback test).
+6. REST `/api/activity/events` đã xóa (404), CI go-svc xanh với workflow sửa đổi.
+7. CI all green trên dest gồm convergence sửa đổi; ADR-0008 + conventions/09 tồn tại.
+
+## Boundary epic-level
+- Nhánh đích `story-<epic-id>-kafka-outbox-saga`; PR human merge.
+- CI-only verify (user máy yếu); Kafka không expose host; không đụng product code ngoài files trong touch map (bug thấy = report).
+- Historical docs (plans/specs/contexts FI-62 nhắc /api/activity/events) KHÔNG sửa.

package/stack-template/docs/superpowers/specs/2026-10-13-ui-redesign.md

@@ -0,0 +1,173 @@
+# Epic Spec — UI/UX Redesign (shell + remotes + fe-shared design system)
+
+> Story: VU-53 (epic In Progress) · tạo 2026-10-13 · pipeline: story-workflow CREATE
+> Rev 2 — sau spec-critic (GO): sửa 3 P1 (contract api-mở-rộng SF-3, assignee UUID rút gọn không resolve tên, cssFilename fact /assets/ sai) + 6 P2 (primitive props API trong hand-off, spike R2 exit criteria, quán từ SF-4/SF-2, aria-list exhaustive, env.d.ts defensive, phase-2 visual transient expected)
+> Rev 3 — sau plan-critic (GO): P1 phân rã tasks SF-2 (7→9) + SF-4 (6→9); P2 spike R2 chạy sớm sau jsx-runtime config, tests primitives ở shell/tests (fe-shared không vitest — tránh đụng lockfile), phase-gate security owner rõ, SF-3/4 rebase note (packs)
+> Repo: `__STACK_ORG__/architecture-overview` (đã chạy được: 10 services compose + e2e smoke 2 chiều PASS)
+> Input user: "design lại UI/UX" · Creativity: BALANCED (spec = khung cứng; chi tiết chưa ghi agent tự quyết theo conventions, quyết định lớn flag trong notes)
+
+## IDEA-BRIEF (8 chiều)
+
+- **Task**: Design lại toàn bộ UI/UX của micro-frontend demo: dựng design system (tokens + base + primitives dùng chung shell/remotes), restyle shell (layout/login/nav/fallback) + 2 remote (tasks/activity), đóng các khoảng trống UX nhìn thấy được **bằng API hiện có** (pagination, filter, edit, delete, assignee/createdAt, per-item busy, skeleton, nav active, responsive).
+- **Output**: Cùng repo — `docker compose up` → mở `:8080` thấy UI có visual identity nhất quán xuyên shell + 2 remote (không còn "unstyled mặc định trình duyệt"), standalone debug `:4001/:4002` có style, 3 package FE test+typecheck xanh, walkthrough mục 4 (kể cả saga 4b) chạy được trên UI mới.
+- **Users**: (a) dev nội bộ copy boilerplate — UI là "mặt tiền" phán xét khi fresh-clone walkthrough; (b) người demo e2e/saga (cần badge `assignment_failed` nhận diện được); (c) CI KHÔNG nhìn UI (e2e là curl API-level — story này không đụng CI).
+- **Constraints**: MUST — giữ toàn bộ contracts ghim (mục "Contracts ghim"); a11y không thụt lùi (WCAG AA 4.5:1 text); 0 npm dependency mới, 0 external asset/CDN (CSP chưa set — không mở), giữ system-ui font stack; pin matrix (react 19.3.0 / rspack 1.7.12 / MF enhanced 0.21.6) bất biến. MUST-NOT — không đụng BE/gateway/contracts/OpenAPI, không đổi MF registry, không thêm dark mode/i18n framework.
+- **Input**: Không Figma (story không có nguồn thiết kế 1:1) → hướng thiết kế sinh qua **designer 3-hướng mock-prototype, USER CHỌN (gate bắt buộc)**, hand-off doc là source of truth. Code hiện có: 4 package FE ~1.150 LOC src, CSS 68 dòng 1 file.
+- **Context**: Repo là boilerplate demo đã hoàn thiện (epic trước: microservice + MFE + Kafka saga). A11y baseline tốt bất thường (skip link, focus management, role=alert/status) — giữ nguyên semantics. Coupling ngầm CSS shell→remotes là nợ lớn nhất: remotes ăn global CSS của shell, standalone mất style; 11 chỗ inline style; 0 media queries.
+- **Success criteria** (binary): (1) Login `alice@demo.local` → nav → Tasks CRUD (tạo/sửa tiêu đề/xoá/đổi status/phân trang/filter) → Activity feed phản ánh — toàn bộ trên UI mới qua `:8080`. (2) Saga demo 4b: assign `fail@demo.local` → badge "Gán thất bại" nhận diện rõ. (3) Kill 1 remote → fallback đẹp + retry hoạt động. (4) Standalone `:4001`/`:4002` có style. (5) 3 package: `pnpm test` + `pnpm typecheck` xanh (38 case cũ update đồng bộ + tests mới primitives). (6) Responsive: dùng được ở 375px (không overflow ngang). (7) Không deps mới — `pnpm-lock.yaml` không đổi.
+- **Out-of-scope**: dark mode (tokens CSS vars để sẵn điểm cắm); i18n framework (giữ hardcode vi); icon library/CDN font; backend/API thay đổi; e2e browser tự động (mở rộng CI); nâng cấp bất kỳ dependency nào; scaffold script (tự thừa hưởng — verify thôi).
+
+## Quyết định đã chốt (BALANCED — agent tự quyết theo conventions, flag cho user duyệt ở STORY-READY)
+
+| # | Quyết định | Chọn | Flag |
+|---|---|---|---|
+| 1 | Phạm vi | Visual redesign + đóng UX gaps **bằng API hiện có** (limit≤100+offset, filter status, PATCH title/desc, DELETE, assignee/createdAt fields) — không tính năng ngoài contract | |
+| 2 | Nguồn thiết kế | Không Figma → designer 3 hướng (mock-prototype) → **USER GATE chọn** → hand-off `docs/superpowers/designs/ui-redesign-direction.md` = source of truth mọi SF sau. **ĐÃ XỔI 2026-10-13 lúc CREATE (front-load design gate)**: user chọn **hướng B "Linear-referenced dark"** sau khi xem 3 bản draft (`designs/drafts/`) — gate record `designs/direction-approved.md`. SF-1 còn mỗi implement | ~~USER GATE~~ ĐÃ DUYỆT |
+| 3 | Nơi đặt design system | `frontend/shared` thêm `src/styles/` (tokens.css + base.css) + `src/ui/` (React primitives) — mọi package import (giải luôn coupling standalone). **Ownership exception**: epic cấp cho SF-1 sở hữu 2 thư mục này; 4 file logic (api-client/token-storage/error-envelope/mf-bootstrap) vẫn READ-ONLY tuyệt đối | ⚠ ownership change |
+| 4 | UI library ngoài | KHÔNG — CSS thuần + tokens + class utilities, SVG inline nếu cần icon. Lý do: 0 deps mới, boilerplate dễ copy | |
+| 5 | Kiến trúc CSS | tokens.css (custom properties `:root`, idempotent — nhiều bản cùng giá trị vô hại) + base.css tối thiểu (`@layer reset,base` cùng thứ tự mọi bản) — shell import LÀM CHỦ global base; remote chỉ import tokens + scoped classes (tránh 2 bản base đè nhau) | |
+| 6 | Dark mode / i18n | Out-of-scope (điểm cắm để sẵn trong tokens) | |
+| 7 | Responsive | Include: breakpoints ≤768px / ≥1024px, nav wrap, list 1 cột mobile — verify thủ công 375px ở SF-5 (jsdom không assert media query) | |
+| 8 | Chuỗi UI text Việt | Bộ aria-label/text nguyên văn hiện có là **contract có test** — giữ nguyên максимально; designer chỉ đề xuất đổi khi cần, đổi = cùng-commit với test | |
+| 9 | Test đỏ phân mảnh | Quy tắc: SF đổi chuỗi nào thì update test chuỗi đó TRONG CÙNG SF — không để đỏ chờ SF khác | |
+
+## Contracts ghim (CHECKLIST — SF agents đối chiếu trước khi code)
+
+1. **MF registry** (conventions/08 + rspack exposes): name `tasks`/`activity`, file `remoteEntry.js`, expose `./TasksPage`/`./ActivityPage` (+ default export), URL prod `/remotes/<name>/remoteEntry.js`, env `REMOTE_TASKS_URL`/`REMOTE_ACTIVITY_URL`/`REMOTE_PUBLIC_PATH`. KHÔNG đổi.
+2. **Async boundary** `shell/src/index.tsx` = `import('./bootstrap')` — giữ nguyên (RUNTIME-006).
+3. **Singleton MF**: react/react-dom singleton; remotes `requiredVersion: false`. Pin matrix catalog bất biến.
+4. **API client interface** từ fe-shared — `ApiClient` + signature các call HIỆN CÓ không đổi; remote-local `src/api.ts` **ĐƯỢC MỞ RỘNG** (thêm query params limit/offset/status + hàm mới vd `deleteTask`) đúng contract `tasks.yaml`; không gọi endpoint ngoài `/api/auth/login`, `/api/tasks*`, `/api/activity/*` (KHÔNG resolve tên assignee qua `/api/users` — ngoài pin + sai base URL dev của remote).
+5. **A11y contracts** (có test, KHÔNG thụt lùi) — exhaustive: skip link `href="#main-content"` + text "Tới nội dung chính"; `main id="main-content" tabIndex={-1}` + focus khi đổi route; `role="alert"` mọi error banner; `role="status"` badge; aria-label nguyên văn: "Điều hướng chính", "Form đăng nhập", "Quản lý tasks", "Form tạo task", "Danh sách tasks", "Trạng thái task <title>", "Activity feed và thống kê", "Thống kê tasks", "Tổng số task", "Task Cần làm/Làm/Xong", "Sự kiện 24h qua", "Danh sách hoạt động"; `data-testid="nav-user"`.
+6. **Test harness**: vitest + Testing Library jsdom; mock tầng `../src/api`; stub `__API_BASE_URL__` trong vitest define.
+7. **Build/deploy**: Dockerfile multi-stage + nginx SPA fallback + security headers giữ cấu trúc; KHÔNG thêm asset ngoài (CSP chưa set); thêm `output.cssFilename: '[name].[contenthash].css'` prod để cache-busting khi re-deploy (CSS emit ở root path — KHÔNG nằm trong `/assets/` immutable; dời js+css vào `/assets/` = ngoài scope story này).
+8. **Read-only tuyệt đối**: `frontend/shared/src/{api-client,token-storage,error-envelope,mf-bootstrap}.ts`, `frontend/shared/package.json` trường `mfToolkit`, `contracts/**`, `platform/gateway/**`, `services/**`, `scripts/smoke/e2e.sh`, `platform/conventions/08`, `frontend/spike/**`, mọi Dockerfile/nginx.conf.
+9. **CI e2e API-level không đổi** — story này human gate = browser walkthrough mục 4 + 4b.
+
+## P0 impact — 10 chiều (tóm tắt, full trong context packs)
+
+**Rủi ro đã phán** (P0 analyst, đọc code thật):
+
+| # | Rủi ro | Sev | Mitigation (bắt buộc) | SF |
+|---|---|---|---|---|
+| R1 | Remotes rspack KHÔNG có css rule + experiments.css → import fe-shared CSS fail build ngay | **P0** | Copy y hệt rule của shell (`rspack.config.mjs:42-45,85-87`) vào 2 remote + `declare module '*.css'` vào env.d.ts ×3 | SF-1 |
+| R2 | JSX trong fe-shared → `react/jsx-runtime` ngoài shared scope → duplicate react/hooks crash runtime lúc remote mount trong shell | **P0** | Thêm `'react/jsx-runtime': {singleton:true, requiredVersion:false}` vào shared CẢ 3 config + **spike build 3 package load thật soi console** trước khi restyle; fallback: primitives class-only (không JSX) | SF-1 |
+| R3 | 2 bản base/tokens cùng load (shell + runtime remote CSS) — đè nhau / stale cache lệch version | P1 | tokens idempotent; base tối thiểu + `@layer` cùng thứ tự; shell làm chủ global base — remote chỉ tokens + scoped; cssFilename contenthash | SF-1 |
+| R4 | Standalone :4001/:4002 mất style | P1 | remote `src/index.tsx` import base+tokens (sau R1) | SF-3/4 |
+| R5 | Đổi chuỗi UI Việt → đỏ test phân mảnh | P1 | Quy tắc cùng-commit cùng-SF (quyết định #9) | mọi SF |
+| R6 | A11y thụt lùi khi restyle | P1 | 3 test a11y là hard gate; palette hand-off phải đạt AA 4.5:1 (benchmark hiện tại `#742a2a`/`#fed7d7` đạt); animation mới → `prefers-reduced-motion` | mọi SF |
+| R7 | fe-shared ownership (SF-1 cũ sở hữu) | P2 | Epic cấp ownership giới hạn `src/styles/`+`src/ui/` cho SF-1 mới; update comment pnpm-workspace.yaml + package.json description | SF-1 |
+| R8 | Phình scope font/icon CDN → mở CSP | P2 | NO-GO by design: 0 external asset, system-ui stack | tất cả |
+| R9 | Mất dấu badge `assignment_failed` (walkthrough 4b) | P2 | Badge = primitive bắt buộc trong hand-off; walkthrough chạy lại ở SF-5 | SF-5 |
+
+**Facts SF agents phải mang theo**: (f1) css rule template shell:42-45,85-87; (f2) jsx-runtime sharing + spike trước restyle; (f3) cssFilename contenthash; (f4) kiến trúc CSS đích = fe-shared base.css nguồn element defaults, remote tokens + scoped; (f5) aria-label/text Việt = contract; (f6) CI không nhìn UI; (f7) 0 deps mới; (f8) ownership giới hạn; (f9) registry pin; (f10) thứ tự designer → nền móng → restyle song song → walkthrough.
+
+## Kiến trúc đích (design system)
+
+```
+frontend/shared/src/
+  styles/tokens.css   ← custom properties :root — màu (palette hand-off, AA), spacing scale,
+  │                     type scale, radius, shadow, breakpoint vars, z-index. Idempotent.
+  styles/base.css     ← @layer reset,base — reset tối thiểu + element defaults (body font,
+  │                     form control, focus-visible, .error-banner, .skip-link…). Giống hệt
+  │                     mọi bản — copy ×3 bundle vô hại khi cùng version.
+  ui/Badge.tsx        ← status/action badge (role="status"), variant theo tokens — dùng cho
+  ui/EmptyState.tsx   ←   task status + assignment_failed + activity action
+  ui/Skeleton.tsx     ← loading skeleton (thay "Đang tải…" text-only) + aria-busy
+  ui/Spinner.tsx      ← busy indicator nhỏ (per-item, submitting)
+Consumers: shell/bootstrap.tsx import base+tokens (LÀM CHỦ global); remotes import tokens
+trong page entry + scoped classes riêng; remote standalone src/index.tsx tự import base+tokens.
+```
+
+## SF split (5 SF — rubric C1-C5/V1-V3 + anti-duplicate)
+
+**Anti-duplicate check (liệt kê tasks mọi SF trước khi chốt):** primitives/tokens/rspack-css/jsx-runtime/spike = CHỈ SF-1 (SF-2/3/4 consume — không tái hiện); restyle mỗi package = touch map disjoint (shell / tasks / activity); test updates = per-SF khu mình (Zweck); browser walkthrough = chỉ SF-5. Pattern lặp ≥2 SF: KHÔNG có. SF-2/3/4 cùng "loại" (restyle) nhưng khác surface + <50% tasks trùng loại thực tế (login/nav/fallback vs form/list/pagination vs feed/stats). SF nào cũng ≥8 tasks.
+
+### Phase 1 — nền móng (checkpoint: 3 package build xanh + spike duplicate-react sạch + primitives có test)
+
+**SF-1 · Design direction + design-system nền móng** (tier 0, ~14 tasks, design: mock-prototype — **USER GATE chọn hướng**)
+- Designer (huashu-design): 3 hướng HTML prototype (login + tasks + activity 3 màn hình chính mỗi hướng) → user chọn → hand-off `docs/superpowers/designs/ui-redesign-direction.md` (palette AA contrast values, type/spacing scale, component spec, motion tối giản)
+- `fe-shared/src/styles/tokens.css` + `base.css` (@layer reset,base) theo direction đã chọn
+- Primitives `ui/`: Badge (role=status + variants), EmptyState, Skeleton (aria-busy), Spinner
+- Barrel export + package.json exports map (chỉ đụng phần mới — 4 file logic READ-ONLY)
+- Rspack: css rule + experiments.css cho 2 remotes (template shell), `declare module '*.css'` env.d.ts ×3 (defensive — tsc hiện PASS nhờ side-effect import, thêm phòng named import), `'react/jsx-runtime'` shared ×3
+- **Spike R2 chạy SỚM** — ngay sau task config jsx-runtime ×3 với 1 JSX stub tối thiểu, TRƯỚC khi viết primitives (FAIL muộn = rewrite đắt nhất). Exit criteria: build 3 package → load shell + remote mount + 1 tương tác (đổi status) OK + console KHÔNG có "Invalid hook call"/"2 copies of React" → screenshot vào `docs/superpowers/evidence/`; FAIL → fallback primitives class-only (không JSX), hand-off ghi luôn API shape thay thế
+- Primitives props API: document TS props từng primitive trong hand-off doc (Badge variant enum phủ 4 status extended tasks + 5 action labels activity) — SF-2/3/4 consume theo đúng shape này; tests primitives sống ở `frontend/shell/tests/` (fe-shared KHÔNG có vitest — thêm vào sẽ đụng lockfile)
+- `output.cssFilename` contenthash ×3 (prod)
+- Remotes standalone `src/index.tsx` import base+tokens (fix R4 một nửa — full fix visual ở SF-3/4)
+- Tests: primitives (Badge role/status, EmptyState text, Skeleton aria-busy, Spinner label) + shell build smoke
+- Ownership notes: pnpm-workspace.yaml comment + fe-shared README + description
+- Demo: storybook-less — 1 trang demo HTML đơn giản trong hand-off hoặc standalone :4001 render primitives
+
+### Phase 2 — 3 surface song song (checkpoint mỗi SF: package đó test+typecheck xanh + dev-server xem được UI mới)
+
+**SF-2 · Shell — layout, login, nav, remote fallback** (tier 1, ~10 tasks — design theo hand-off SF-1, KHÔNG gate mock riêng)
+- Layout: container max-width + header/page structure theo direction (giữ skip link + #main-content + focus logic NGUYÊN VẸN)
+- NavBar: active state (`aria-current="page"` + visual), responsive wrap ≤768px
+- NavBar: user chip + logout/login styling (giữ `data-testid="nav-user"`)
+- HomePage: từ "Trang chủ" trống → dashboard chào + quick links 2 remote + demo hints (alice/fail@demo.local)
+- LoginPage: card giữa màn hình + error banner styling + demo hint format đẹp — behavior + tests giữ (redirect, deep-link, error messages nguyên văn)
+- RemoteSlot: Suspense fallback = Skeleton (thay `<p>Đang tải {name}…</p>` — không test nào assert chuỗi này, thay an toàn), error fallback visual (giữ text "Không tải được phần tasks…" + nút "Thử lại" — test contract)
+- `shell/src/styles.css` rewrite → scoped classes + consume tokens (xóa element selectors toàn cục đã chuyển vào base.css)
+- Tests tách theo surface: a11y 3 case giữ nguyên vẹn / login / remote-slot / integration update chuỗi nếu đổi
+- Diff-hygiene cuối SF (không secrets, không exec-bit mới — phase-gate security của coordinator)
+
+**SF-3 · Remote tasks — TasksPage redesign + UX gaps** (tier 1, ~13 tasks)
+- Tách component: TaskForm / TaskList / TaskItem / StatusSelect (giữ export default + named cho MF)
+- TaskItem: card layout responsive, StatusBadge dùng primitive Badge (giữ "Gán thất bại" role=status + text), per-item busy (Spinner + disable select) khi PATCH đang bay
+- Edit inline title/description (PATCH có sẵn — nút sửa → input inline → save/cancel)
+- Delete task (DELETE có sẵn — nút xoá + confirm dialog; task.deleted vào feed tự nhiên qua Kafka)
+- Hiển thị assignee (UUID rút gọn monospace + tooltip full — KHÔNG resolve tên qua `/api/users`) + createdAt
+- Pagination "Tải thêm" (limit ≤100 + offset — API có sẵn) + hiển thị "x/total"
+- Filter theo status (?status= — API có sẵn) — chip/toggle bộ 3 writable status
+- Loading = Skeleton list (primitive), empty = EmptyState (primitive), error banner giữ role=alert + message 503 spring
+- `src/index.tsx` standalone: banner debug đẹp + đã có CSS (kế thừa SF-1)
+- Scoped css riêng theo kiến trúc CSS đích (mục "Kiến trúc đích" — tokens từ fe-shared, KHÔNG element selectors toàn cục; SF-3∥SF-4 chạy song song nên không copy code nhau)
+- Tests: update chuỗi nếu đổi + THÊM case mới (edit inline gọi PATCH đúng, delete gọi DELETE + confirm, load-more gọi offset, filter gọi ?status=, per-item busy)
+
+**SF-4 · Remote activity — ActivityPage redesign** (tier 1, ~9 tasks)
+- Stats: grid layout responsive + StatTile cards dùng tokens (giữ nguyên bộ aria-label)
+- Feed: timeline theo nhóm ngày + item card (action badge primitive + userName/taskTitle)
+- Feed item: time vi-VN + unknown action fallback nguyên văn
+- Nút "Làm mới" styling + busy state (Spinner)
+- Loading = Skeleton (feed + stats riêng biệt — giữ Promise.allSettled independence)
+- Empty = EmptyState hướng dẫn sang Tasks
+- Scoped css riêng (theo kiến trúc CSS đích), standalone banner debug
+- Tests: update + thêm (stats card grid aria-label giữ, skeleton xuất hiện lúc loading)
+- Diff-hygiene cuối SF (phase-gate security)
+
+### Phase 3 — hội tụ (checkpoint: walkthrough người + full suite xanh)
+
+**SF-5 · Convergence — browser walkthrough + docs + security** (tier 2, ~9 tasks)
+- Rule 0 browser walkthrough trên compose `:8080`: login → nav active → Tasks CRUD (tạo/sửa/xoá/đổi status/filter/load-more) → Activity phản ánh (feed Kafka) → saga 4b (assign fail@demo.local → badge "Gán thất bại" nhận diện) → kill 1 remote dev → fallback + retry → standalone :4001/:4002 có style — screenshot evidence
+- Responsive spot-check 375px (không overflow ngang) — 3 màn hình chính
+- Full suite: `pnpm -r test` + `pnpm -r typecheck` 3 package + build prod 3 package
+- Docs sync: walkthrough mục 4/4b đối chiếu UI mới (label đổi = update), README repo-map (fe-shared thêm design system), frontend READMEs
+- Security pass: diff không chứa secrets, không exec-bit mới, không asset ngoài, CSP untouched, `.env` không commit
+- Scaffold sanity: chạy scaffold copy → output có `frontend/shared/src/styles|ui` (design system theo project mới), build được
+- Improvements-log: patterns story này
+- Báo (không fix) bug product thấy được — SF owning xử lý
+
+## Phased-release
+
+- **Phase 1** = SF-1 (shippable: design system đứng cạnh UI cũ — UI cũ vẫn chạy dùng CSS riêng; không phá gì).
+- **Phase 2** = SF-2 ∥ SF-3 ∥ SF-4 (mỗi SF shippable độc lập: package đó đã restyle, package kia vẫn cũ nhưng tokens không phá — khác surface). Visual transient GIỮA các merge trong Phase 2 là expected (shell merge trước → remotes cũ mất element styles cũ đã chuyển vào base.css tối thiểu — chấp nhận cho repo demo, tự hết khi cả 3 merge).
+- **Phase 3** = SF-5 (walkthrough + docs — chỉ有意义 khi cả 3 surface xong).
+- Release checkpoint sau mỗi phase; phase checkpoint kèm security-audit pass (P0/P1 sạch mới qua) — Phase 1/2: diff-hygiene checklist do SF cuối mỗi phase chạy (task có trong SF) + coordinator duyệt; Phase 3: security pass đầy đủ trong SF-5.
+
+## Acceptance (epic-level, user-visible)
+
+1. Mở `:8080` → login → 3 trang (Trang chủ / Tasks / Activity) nhất quán một design direction đã user-chọn — không còn mặc định trình duyệt trơ trụi.
+2. Tasks: tạo → sửa tiêu đề inline → đổi status (per-item busy) → xoá (confirm) → filter status → "Tải thêm" — tất cả phản ánh BE thật; tổng số "x/total" đúng.
+3. Activity: stats cards + timeline feed phản ánh mọi thao tác trên Tasks (qua Kafka), time vi-VN.
+4. Saga 4b: assign `fail@demo.local` → task hiện badge "Gán thất bại" rõ ràng; re-assign bob + status todo → về luồng thường.
+5. Kill remote-tasks → shell còn nguyên, slot tasks hiện fallback đẹp + "Thử lại" hoạt động; activity vẫn chạy.
+6. Standalone `:4001` / `:4002` mở trực tiếp có style (không còn trơ).
+7. 375px: 3 màn hình chính dùng được, không overflow ngang.
+8. `pnpm -r test && pnpm -r typecheck` xanh; `pnpm-lock.yaml` không đổi; e2e smoke `scripts/smoke/e2e.sh` vẫn PASS (không đụng).
+
+## Boundary epic-level
+
+- KHÔNG đụng: BE services, gateway, contracts OpenAPI/DDL, `scripts/smoke/e2e.sh`, CI workflows, `platform/conventions/08`, pin matrix, Dockerfile/nginx cấu trúc (trừ cssFilename là rspack config).
+- KHÔNG: dark mode, i18n framework, icon/font CDN, dependency mới, nâng cấp version, e2e browser tự động, đổi MF registry/exposes, đổi API call shapes.
+- fe-shared: CHỈ được thêm `src/styles/` + `src/ui/` (+ barrel/exports phần mới) — 4 file logic READ-LOCKED.
+- Design direction: chỉ user chọn (gate SF-1) — agent không tự chốt hướng cuối.

package/stack-template/docs/superpowers/specs/2026-10-14-sf-3-ui-redesign.md

@@ -0,0 +1,46 @@
+# SF-3 Spec — Remote tasks: TasksPage redesign + UX gaps (VU-56)
+
+> Story VU-53 · slice canonical: `docs/superpowers/contexts/ui-redesign/sf-3.md` (đọc THAY VÌ tổng hợp lại) · epic spec rev 3: `docs/superpowers/specs/2026-10-13-ui-redesign.md` · direction: `docs/superpowers/designs/ui-redesign-direction.md` (hướng B — user đã duyệt ở CREATE)
+> File này = brainstorm self-run (autonomous): holistic re-examination + design decisions mức SF. Epic-level questions đã trả lời hết ở epic spec — KHÔNG hỏi lại.
+
+## Design decisions (self-answered theo conventions, BALANCED)
+
+| # | Câu hỏi brainstorm | Quyết định | Lý do |
+|---|---|---|---|
+| 1 | State sống đâu? | `TasksPage` owns: `tasks[]`, `total`, `loading`, `loadingMore`, `error`, `statusFilter`. `TaskForm` owns inputs của mình; `TaskItem` owns `editing`/`confirming`/`busy` cục bộ | Decomposition spec slice #1; busy per-item là UI cục bộ (spec slice #3) |
+| 2 | `fetchTasks` signature? | `fetchTasks(params?: { limit?; offset?; status? })` — query builder clamp limit 1..100 (mặc định `TASKS_PAGE_SIZE = 10`), offset ≥ 0, status chỉ khi có. Luôn gửi `limit` + `offset` | Contract `tasks.yaml` (limit max 100, offset ≥ 0); page size 10 để "Tải thêm" hiện sớm trong demo |
+| 3 | aria-label "Tiêu đề" trùng giữa form tạo và form sửa? | Edit inputs dùng aria-label riêng: `Sửa tiêu đề task <title>` / `Sửa mô tả task <title>` | Tránh ambiguous getByLabelText trong test + accessible name rõ hơn cho màn đọc |
+| 4 | Confirm xoá: `window.confirm` hay inline? | Inline 2 bước trong item: nút "Xoá" → text "Xoá task này?" + [Xác nhận xoá] [Huỷ] | jsdom/userEvent không mô phỏng native confirm tốt; inline confirm style được theo hand-off (no-shadow, surface ladder); buttons đặt tên distinct cho test |
+| 5 | aria-label `Trạng thái task <title>` trên badge sao cho KHÔNG đụng fe-shared (đóng băng — `BadgeProps = {variant, children}`)? | Bọc `<span role="status" aria-label="Trạng thái task <title>">` quanh `<Badge>` — query role=status theo name vẫn khớp test cũ, text "Gán thất bại" nguyên văn qua children | Không sửa primitive; giữ đúng contract a11y (boundary: KHÔNG đổi aria-label bộ tasks) |
+| 6 | Per-item busy hiển thị thế nào? | Khi busy: `Spinner` (label `Đang xử lý task <title>`) THAY badge (hand-off §4 "Spinner thay dot") + disable select + disable nút Sửa/Xoá | Hand-off §4 task row; chống double-submit |
+| 7 | Skeleton lúc load-more? | KHÔNG — giữ list, nút "Tải thêm" → "Đang tải thêm…" + disabled. Skeleton chỉ cho load đầu/tiêu đổi filter | Tránh list nhảy layout; loading state rõ ràng hơn |
+| 8 | Edit payload? | Chỉ gửi field THAY ĐỔI (minProperties 1 theo contract); cả hai không đổi → thoát edit không gọi PATCH; title rỗng → không gửi | `UpdateTaskRequest` minProperties 1; description rỗng gửi `''` (contract cho phép string) |
+| 9 | Assignee hiển thị? | `null` → "Chưa gán"; có → `<code title={full}>` 8 ký tự đầu + "…" monospace; KHÔNG resolve tên (boundary) | Spec slice #6 |
+| 10 | createdAt format? | `Intl.DateTimeFormat('vi-VN', {2-digit date + hour/minute})` render trong `<time dateTime={iso}>`; test không assert chuỗi locale (ICU variance) — assert `/2026/` + dateTime attr | Hand-off §4 "thời gian vi-VN"; test bền |
+| 11 | Empty khi đang filter? | Vẫn `EmptyState` title "Chưa có task nào" (giữ semantics — boundary), description đổi theo ngữ cảnh (bỏ lọc / thử bỏ bộ lọc) | Spec slice #10 + boundary giữ text |
+| 12 | CSS scope? | File `src/styles.css` import trong `TasksPage.tsx`, mọi selector prefix `.tsk-`, KHÔNG element selector toàn cục, chỉ ăn tokens `--c-* --ink* --line* --accent* --st-* --sp-* --fs-* --r-*`; media ≤768px stack card | Spec slice #11 + epic quyết định #5 (remote chỉ tokens + scoped) |
+| 13 | `index.tsx` hay `standalone.tsx` chứa banner? | `standalone.tsx` (SF-1 đã tách render ra khỏi async boundary). `index.tsx` GIỮ NGUYÊN — boundary `import('./standalone')` là contract RUNTIME-006 | Touch map ghi "index.tsx SỬA banner debug" — thực chất banner nằm ở file render; surgical scope giữ boundary không đụng |
+| 14 | MF contract? | Giữ nguyên: `TasksPage.tsx` export named `TasksPage` + `export default`; không đổi expose/name/publicPath | Boundary: registry pin |
+| 15 | TDD? | Viết/trả test TRƯỚC theo API component mới (RED), implement tới XANH (GREEN); evidence ghi `tdd: RED→GREEN` | Gate story-verify TDD_MODE |
+
+## Component tree
+
+```
+TasksPage (state owner, error banner, filter chips, skeleton/empty/load-more)
+├── TaskForm            — tạo task (aria-label "Form tạo task" giữ nguyên)
+├── FilterChips         — inline trong TasksPage: "Tất cả" + 3 writable (aria-pressed)
+└── TaskList            — h2 "Danh sách (x/total)" + ul aria-label "Danh sách tasks"
+    └── TaskItem        — card: badge/spinner + title/desc + meta (uuid, createdAt) + actions
+        ├── StatusBadge — bọc Badge primitive (role=status + aria-label giữ nguyên)
+        ├── StatusSelect— 3 writable, aria-label "Trạng thái task <title>", disabled khi busy
+        └── edit/confirm inline UI
+```
+
+## Test kế hoạch (giữ 12 case cũ update + thêm ~10)
+
+Component: render list + "x/total" · tạo task · 503 banner · empty · đổi status · assignment_failed badge KHÔNG select · select 3 option · **sửa inline PATCH đúng payload** · **huỷ sửa không gọi PATCH** · **xoá confirm gọi DELETE** · **huỷ xoá không gọi** · **Tải thêm gọi offset** · **filter gọi ?status=** · **per-item busy (select disabled + Spinner)** · **assignee UUID rút gọn + title full + createdAt** · **skeleton khi loading**.
+API: fetchTasks default URL mới · fetchTasks đủ params + clamp · **deleteTask DELETE 204** · create/update/503/timeout giữ.
+
+## Boundary (nhắc lại — từ context pack, không đổi)
+
+KHÔNG đụng shell/**, activity/**, shared/** (đóng băng), rspack.config, env.d.ts, contracts; KHÔNG deps mới; KHÔNG merge/PR; STATUS_LABELS + aria-label bộ tasks + role=alert/status giữ nguyên văn.

package/stack-template/docs/superpowers/specs/2026-10-14-sf-5-ui-redesign.md

@@ -0,0 +1,30 @@
+# SF-5 Spec — Convergence: browser walkthrough + docs + security (VU-58)
+
+> Story VU-53 · slice canonical: `docs/superpowers/contexts/ui-redesign/sf-5.md` (đọc THAY VÌ tổng hợp lại) · epic spec rev 3: `docs/superpowers/specs/2026-10-13-ui-redesign.md` · direction: `docs/superpowers/designs/ui-redesign-direction.md` (hướng B — user đã duyệt ở CREATE, KHÔNG designer phase)
+> File này = brainstorm self-run (autonomous): holistic re-examination + quyết định mức SF. Epic-level questions đã trả lời hết ở epic spec — KHÔNG hỏi lại.
+
+## Holistic re-examination (brainstorm)
+
+SF-5 KHÔNG viết code sản phẩm — nó là vòng **hội tụ**: chứng minh 8/8 acceptance epic bằng browser walkthrough thật (Rule 0 — compose `:8080` là chuẩn duy nhất cho FLOW tier), đồng bộ docs để người MỚI đi lại được, security pass cuối story, và **chuẩn bị đủ điều kiện cho human gate**: stack sống + hướng dẫn 8 bước + screenshots + walkthrough.md mục 4/4b khớp UI mới. Phần "Người walkthrough xác nhận PASS 8/8" là gate của coordinator/user — SF-5 KHÔNG tự tick.
+
+Khác biệt với walkthrough SF-2/3/4 (isolate dev stack :3100/:4101/:4102): SF-5 đi trên **compose prod-build** (10 container) — đúng điều kiện CI convergence + đúng cái người copy boilerplate sẽ chạy. Kill-remote ở chế độ này = stop container remote (nginx proxy 502 → RemoteSlot error fallback), không phải kill dev server.
+
+## Design decisions (self-answered theo conventions, BALANCED)
+
+| # | Câu hỏi brainstorm | Quyết định | Lý do |
+|---|---|---|---|
+| 1 | "Kill 1 remote dev" trên compose :8080 nghĩa là gì? | `docker stop boilerplate-remote-tasks-1` → reload `:8080` → shell còn nguyên, slot tasks fallback lỗi + "Thử lại"; rồi `docker start` lại container → click "Thử lại" → remote mount lại OK. Cả 2 nửa (fallback + retry) đều chứng minh | Compose không có dev server — remote là container nginx static; URL remote của shell build prod = `/remotes/tasks/remoteEntry.js` qua nginx (`Dockerfile` ARG `REMOTE_TASKS_URL`, nginx `location /remotes/`). Stop container = đúng cách remote "chết" trong chế độ này |
+| 2 | "BEFORE/AFTER từng màn" cho SF convergence không restyle gì? | BEFORE/AFTER theo **trạng thái động do hành động walkthrough tạo ra** (list trước/sau tạo task; badge thường → "Gán thất bại" sau assign fail@; shell loaded → fallback sau kill remote), màn tĩnh (login/home) chụp 1 shot + so direction B. SF-2/3/4 đã có evidence old→new của từng surface | SF-5 không đổi UI — cặp old/new UI không tồn tại trên nhánh này (SF-2/3/4 đã merge); giá trị evidence của convergence là chuỗi hành động thật trên 1 build |
+| 3 | Evidence layout? | Screenshots walkthrough → `docs/superpowers/evidence/ui-redesign/` (đặt tên `conv-<n>-<bước>.png`); test-run/smoke evidence gate B1 → `docs/superpowers/evidence/sf-5-ui-redesign-conv/test-run.txt` (HEAD/HEAD~1 hash + dòng `tdd:`) | Checklist Rule 0 chỉ `evidence/ui-redesign/` cho screenshots; gate B1 story-verify neo `sf-5-*/test-run.txt` (FI-440) |
+| 4 | TDD cho SF docs-only? | `tdd: skipped-tdd: SF-5 docs/verify-only — không có unit mới để viết RED; bằng chứng = full suite + e2e smoke + walkthrough screenshot (3 tầng Rule 0)` trong test-run.txt | Gate TDD story-verify chấp nhận skipped có lý do; verification của SF-5 là browser + suite, không phải test mới |
+| 5 | Pagination "Tải thêm" cần >10 tasks — data nào? | Tạo task CRUD qua UI (bắt buộc — đó là acceptance); nếu DB chưa đủ 10 task cho load-more thì seed thêm qua `POST /api/tasks` (curl, API công khai contract) — UI vẫn phải tự phản ánh đúng | Walkthrough kiểm UI phản ánh BE thật; seed qua API không thay thế bước CRUD-trên-UI nào |
+| 6 | Saga timing? | Sau assign `fail@demo.local`: poll badge "Gán thất bại" tối đa ~60s (go consumer retry ×3 với backoff); re-assign bob + PATCH `status=todo` qua UI (edit inline + select) — đúng chuỗi walkthrough 4b | walkthrough.md mục 4b step 2-4; `assignment_failed` là system-owned, PATCH tường minh mới về luồng thường |
+| 7 | 375px responsive đo thế nào khi Orca browser không có device emulation? | Headless Chrome (`--headless --window-size=375,812`) trên **cùng build :8080** đang verify, script CDP (`--remote-debugging-port`) login + navigate + screenshot 3 màn. Đây là pixel thật của cùng bundle (fallback trung thực FI-464 — khai báo trong evidence); DOM tier kiểm `scrollWidth <= innerWidth` trên chính phiên đó | Orca tab không expose viewport override; 375px phải là ảnh pixel thật (tầng 2), không phải đo DOM thay thế |
+| 8 | Docs sync phạm vi chính xác? | `docs/walkthrough.md` mục 4 (4 bước → mở rộng theo UI mới: login card → nav → Tasks CRUD chi tiết → Activity → kill remote compose) + 4b (badge "Gán thất bại" + re-assign bob + PATCH todo + DLQ command); `README.md` repo-map dòng `shared/` + đoạn FE; `frontend/shell/README.md`, `frontend/remotes/{tasks,activity}/README.md` — thêm cách import tokens/primitives. KHÔNG đụng README khác | Touch map context pack (SF-5 sole owner docs); nhãn/badge đổi so walkthrough cũ = update đúng những chỗ đó thôi |
+| 9 | Scaffold sanity chạy thế nào cho sạch? | `bash scripts/scaffold/scaffold.sh sf5-sanity` (dir `/tmp/...` theo pack) → assert `frontend/shared/src/styles` + `src/ui` tồn tại → `pnpm install --no-frozen-lockfile` + build shell → PASS → xoá output | Context pack mục 6 — verify-only, KHÔNG sửa scaffold script |
+| 10 | Security pass đo thế nào? | Scan diff TOÀN story (`git diff <merge-base với main>..HEAD`): secret-pattern (key/secret/password/token ngoài fixture `demo-password` đã có sẵn), `.env` không được track, exec-bit mới (diff --summary), asset ngoài/CDN trong FE, CSP/nginx untouched, pnpm-lock không đổi | Context pack mục 5; OWASP surface = none-new (0 code FE/BE mới trong SF-5) → checklist diff-hygiene là đúng mức |
+| 11 | Bug thấy được trong walkthrough? | KHÔNG fix (boundary frontend/** services/** READ-ONLY) — ghi REPORT coordinator vào worktree comment + improvements-log nếu có | Context pack boundary + mục 8 |
+
+## Boundary (nhắc lại — từ context pack, không đổi)
+
+KHÔNG fix code SF-2/3/4; KHÔNG đụng `frontend/** services/** scripts/** .github/** contracts/** platform/**` (trừ docs của mình); KHÔNG merge/PR (coordinator); KHÔNG tự tick human-confirm 8/8; KHÔNG thêm tính năng.