create-wakii-stack 0.0.0-stage → 0.1.0

package/stack-template/docs/ai/table-Theming.md

@@ -0,0 +1,25 @@
+# Theming & Hooks — when to use
+
+Group: theming-hooks (worker F). Source of truth: `app/ui-kit/src/provider/` + `app/ui-kit/src/hooks/`.
+Merge target: AGENTS.md (coordinator-owned — do not edit AGENTS.md directly).
+
+| Component | Use when | Power props/combo |
+|---|---|---|
+| `UiKitProvider` | Scope a theme subtree — dark mode or runtime token overrides with zero re-render | `theme`: `'dark'` or object `{ accent, accentHi, canvas, s1/s2/s3, ink/ink2/ink3, line, done/doing/fail }` (13 keys → CSS vars cascade to descendants) · `accent`/`accentHover` shorthand for one-line brand swap · wrap app root or a single panel |
+| `useForm` | Form state + zod validation with a minimal RHF-style API | `schema` (zod = source of truth) · `mode`: `'onSubmit' \| 'onBlur' \| 'onChange'` · errors land on `errors.field`, auto-focus first `[name]` invalid · combo: `Field` + `Input` + `Button` |
+| `useClickAway` | Close on outside interaction — dropdown, popover, menu | returned `ref` attaches to the "inside" element · handler via ref (no re-bind) · combo: `Dropdown`/`Menu`/custom popover |
+| `useFocusTrap` | Lock Tab focus inside a dialog; restore focus to trigger on close | `(ref, active)` — focuses first focusable (or container), cycles Tab, restores on deactivate · combo: `Modal`/`Drawer` (built in) or any custom `role="dialog"` |
+| `useCopyToClipboard` | Copy-to-clipboard with user feedback | returned `[copiedText, copy]` — `copy(text)` → boolean success · combo: `Button` + "Copied!" flash, input copy affordance |
+| `useCountdown` | Ticking countdown — OTP resend, cooldown lock | `initialSeconds` (+ `intervalMs`) → `{ remaining, restart, … }` · combo: `Button` disabled while counting |
+| `useDebounce` | Delayed value — search-as-you-type, expensive derivations | `delayMs` (default 500) · combo: `Input` search → `Table`/`List` filter, API calls |
+| `useThrottle` | Rate-limited value — scroll/resize/infinite-scroll handlers | `intervalMs` (default 500) · combo: `useWindowSize` consumers, scroll triggers |
+| `useTimeout` | Component-safe timeout effect | `callback` + `delayMs` → `{ start, clear, … }` · combo: toast auto-dismiss, tooltip delays |
+| `useToggle` | Boolean on/off state | `initialValue` → `[value, toggle]` · combo: `Collapse` custom triggers, sidebar collapsed, any show/hide |
+| `useDefault` | State that falls back to a default when value is undefined | `defaultValue` · combo: controlled/uncontrolled bridge, form field fallbacks |
+| `usePrevious` | Value from the previous render | single arg · combo: change detection in effects, transition diffs |
+| `useHover` | Hover state without CSS — JS-driven visuals | returned `ref` · combo: drag handles, canvas-like interactions CSS can't express |
+| `useKeyPress` | Reactive "is key pressed" + optional callback | `targetKey` (`'Escape'`, `'Enter'`…) + `onPress` · combo: ESC-close handlers (dialogs have it built in), shortcut hints |
+| `useLockBodyScroll` | Prevent background scroll while open | `locked` (default true) · combo: `Modal`/`Drawer` (built in), fullscreen previews |
+| `useMediaQuery` | Reactive matchMedia boolean, updates in real time | `query` (e.g. `'(min-width: 768px)'`) · combo: responsive JS behavior, `prefers-reduced-motion` branches |
+| `useWindowSize` | Live viewport width/height | no args · combo: virtualized lists, breakpoint-adjacent JS logic |
+| `useLocalStorage` / `useSessionStorage` | Persistent (tab) / session state without effect boilerplate | `key` + `initialValue` · combo: theme preference, drafts, wizard step memory |

package/stack-template/docs/ai/table-datadisplay-mz.md

@@ -0,0 +1,20 @@
+# Data Display m–z — when to use
+
+> Group G slice (components `m`→`z`). Merged into `AGENTS.md` "Data Display" section by the coordinator.
+> APIs verified against source during the full-case-matrix audit (stories 56→59, tests 95→110 in this group).
+
+| Component | Use when | Power props / combo |
+|---|---|---|
+| `Schedule` | Month calendar (FullCalendar dayGrid) for date-driven events — sprints, deadlines, bookings | `events` + `onEventClick` · `fallback` node for missing peer-dep `@fullcalendar/*` · heavy: subpath `@wakii/ui-kit/schedule` · wrap in `Card` |
+| `Segmented` | Compact single-choice switcher with no panels — view period, density, sort mode | `options` + controlled `value`/`onChange` · swap for `Tabs` when you don't need content panels · toolbar/filter-bar headers |
+| `Skeleton` | Loading placeholder mirroring the real layout before data lands | `variant` (text/row/card/circle/button) + `count` · stack `circle`+`text`+`row` to compose a card · prefer `Table loading` for grids · `classNames` slots (`wrapper`/`bone`) |
+| `Statistic` | Big-number KPI readout — title + value + prefix/suffix | `value` + `prefix`/`suffix` · `valueStyle` to color by status · tabular-nums built in · `Card` dashboards |
+| `Steps` | Horizontal wizard progress header (done/current/waiting) | `current` (prop-driven, no internal state) · `aria-current="step"` built in · `Button` next/back beneath it (recipe 4) |
+| `Table` | Data grid — sort/filter/paginate/select for CRUD backbones | `columns` (`sortable`/`filterable`/`render`/`align`) · recipe 2 CRUD · `virtual` for 5k+ rows · `selectionMode` bulk actions · `globalFilter` · `classNames` slots (`wrapper`/`header`/`row`/`cell`) |
+| `Tabs` | Switch between content panels in place — settings, detail views | `items` + controlled `activeKey`/`onChange` · settings pages (recipe 9) · swap for `Segmented` when panels aren't needed · `classNames` slots (`wrapper`/`tablist`/`tab`/`panel`) |
+| `Tag` | Tiny label chip — statuses, metadata; `Tag.Checkable` for filter chips | `closable`+`onClose` (consumer removes) · Checkable: `checked`+`onChange` · `Table` status cells · `Checkable` chip groups in filter bars |
+| `Timeline` | Vertical activity feed — dot + text + time per entry | `items` (per-item `color` dot, `label` time) · `Card` body feeds · audit/history panels (recipe 6) |
+| `Tree` | Expand/collapse hierarchy — file trees, category nav | `data` + `defaultExpandedKeys` · uncontrolled expand state · side navigation panels · use `TreeSelect` when a value must be picked |
+| `TreeSelect` | Pick one leaf from a hierarchy — searchable `Parent / Child` path | `treeData` + `searchable` (label or path match) · `clearable` in filter bars · leaf-only selection · `ariaLabel` required — wrap in `Field` |
+
+> Note: `Pagination` also falls in the m–z range but is **not** part of group G's slice — needs an owner before merging.

package/stack-template/docs/ai/table-feedback.md

@@ -0,0 +1,20 @@
+# Feedback & Overlay — when to use (group H)
+
+Source: `app/ui-kit/src/ui/*` real props. 14 components. Merge target: `AGENTS.md` section "Feedback & Overlay — khi nào dùng".
+
+| Component | Use when | Power props/combo |
+|---|---|---|
+| `Alert` | Inline status banner that stays in the page flow (not transient) — filled by default, `outlined` for the tinted look | `type` (`success\|info\|warning\|error`) · `variant="outlined"` · `description` detail line · `closable`+`onClose` dismissible · `classNames` slots (antd v5) |
+| `BlockUI` | Lock a region in place while it is busy — scrim + centered label over the wrapped content | `blocked` toggle · `message` label on the scrim · wrap `Table`/`Card` during fetch · pair with `Spinner` outside the lock |
+| `ContextMenu` | Right-click menu on a region — positioned at the pointer | `items` (key `'---'` = divider, `danger`/`disabled` per item) · `onItemClick` switch by key · arrow-key nav + ESC + outside-click built-in |
+| `Drawer` | Side panel for detail/form without leaving the page (portal, focus trap, scroll lock) | `open`+`onClose` (ESC, mask click, × wired) · `width` (default 378 antd) · `footer` action row · `classNames` slots |
+| `Dropdown` | Button-triggered action menu — role=menu with full keyboard nav | `items` + `onItemClick` · `trigger` = `Button` · `'---'` divider · `danger`/`disabled` per item · ArrowUp/Down/Home/End built-in |
+| `Message` | Transient global toast — static API, 3s auto-dismiss, no React state needed | `message.success\|info\|warning\|error(content)` · `classNames` slots (wrapper/icon/content) |
+| `Modal` | Blocking confirm/dialog on top of the page (portal, focus trap, scroll lock) | `open` + `onOk`/`onCancel` (ESC + mask + × all cancel) · `danger` red OK · `confirmLoading` locks both buttons · `okText`/`cancelText` · `classNames` slots |
+| `Notification` | Rich toast with title + description — static API, 4.5s, manual × close | `notification.success(title, description?)` · `classNames` slots (wrapper/title/content) |
+| `Popconfirm` | Confirm bubble anchored to a trigger (delete guard) — ESC = cancel, role=dialog | `open` (controlled) + `onConfirm`/`onCancel` · `danger` red icon/OK · `title` + `description` · `okText`/`cancelText` |
+| `Progress` | Line progress bar with % readout — values clamped to 0–100 | `percent` · `status="exception\|success"` recolors bar (red/green) · `showInfo={false}` hides % |
+| `Result` | Full-area status page — icon + color + default title per status | `status` (`success\|error\|info\|warning\|404\|500`) · `title`/`subTitle` override · `extra` action buttons |
+| `Skeleton` | Loading placeholder bones with shimmer wave | `variant` (`text\|row\|card\|circle\|button`) · `count` repeats a bone · compose circle+text+row for a loading card · `classNames` slots (wrapper/bone) |
+| `Spinner` | Inline busy indicator — 3 variants, label is the required accessible name | `label` (REQUIRED aria-label) · `variant` (`ring\|dots\|bars`) · `size` sm/md/lg · `color` (`inverse` on dark surfaces) |
+| `Tooltip` | Hover/focus hint bubble (top/bottom) — portal-free, wraps the trigger in place | `title` (bubble content) · `placement="top\|bottom"` · `aria-describedby` auto-wired · ESC dismisses |

package/stack-template/docs/ai/table-forms.md

@@ -0,0 +1,26 @@
+# Forms — when to use (group E)
+
+Source: `app/ui-kit/src/ui/*` real props. 20 components. Merge target: `AGENTS.md` section "Forms — khi nào dùng".
+
+| Component | Use when | Power props/combo |
+|---|---|---|
+| `AutoComplete` | Free-text input with type-to-filter suggestions (search-as-type) | `suggestions` · `onChange` raw text + `onSelect` picked value · empty `suggestions` → dropdown never opens · `Field` wrap |
+| `Calendar` | Month grid for inline date browsing/picking (no trigger field) | `value` + `onChange` controlled day · `locale="vi"\|"en"` · `range` + `onDayHover` (drives DatePicker) · `bare` inside panels |
+| `CascadeSelect` | Hierarchical pick (region → city → ward) through expanding panel columns | `options` nested `children` define levels · `value` is a path array `["hn","bd"]` · keyboard ↑↓/Enter/Esc built into the trigger |
+| `Checkbox` | Single on/off decision with a visible label | `checked` + `onChange(bool)` · `disabled` · inside `Field` — prefer `Switch` for instant-apply settings |
+| `Chips` | Multi-value tag input — Enter adds, × removes, Backspace pops the last | `value: string[]` + `onChange` · `placeholder` hint · `disabled` hides input + remove buttons · duplicates ignored |
+| `ColorPicker` | Color choice: swatch + preset grid + native picker + hex field | `presets` curated palette (`[]` = native + hex only) · `value` hex · `onChange` fires from preset/native/hex alike |
+| `DatePicker` | Date pick through a trigger + calendar panel | `range` + `showTime` + `locale` vi/en · `value: Date \| [Date, Date]` · `now` injectable for tests · `prefix` icon · footer "Today"/OK |
+| `Inplace` | Click-to-edit inline value (read mode → edit form → close) | `display` + `children` (the edit form) · `onClose` after closing · pair `Input`/`Textarea` inside |
+| `InputMask` | Constrained format typing — `9`=digit, `a`=letter, `*`=alnum, others literal | `mask` · `placeholder` showing the format · `ariaLabel` for accessible name · typing past an invalid char just stops |
+| `InputNumber` | Numeric input with vertical stepper + ↑↓ + min/max clamp | `min`/`max`/`step` · `invalid` red border · blur snaps the display to the clamp · `value` is read at mount (uncontrolled internal) |
+| `InputOTP` | N single-char cells with auto-advance + multi-cell paste | `length` · `value`/`onChange` as one joined string · `ariaLabel` per cell ("code 1…") · digits only · Backspace walks back |
+| `Mention` | Textarea with @-triggered mention list | `suggestions` filtered by the text after @ · ↑↓ + Enter/Esc keyboard pick · picks insert `"@Name "` · `value`/`onChange` is the full text |
+| `Password` | Password field with show/hide toggle (+ optional strength meter) | `showStrength` meter with --st-* colors · `ariaLabel` · `value`/`onChange` · wraps `Input` |
+| `PickList` | Two-column transfer (source ⇄ target) | `source`/`target` + `onChange(source, target)` · multi-pick then chevron move · each listbox keyboard-navigable (↑↓ + Enter/Space) · `aria-multiselectable` |
+| `Radio`/`RadioGroup` | Single choice among a few always-visible options | `RadioGroup options` + `value` · per-option `disabled` · standalone `Radio` for one-offs · prefer `Select` when options are many |
+| `Slider` | Numeric pick on a track — single value or a range | `range: [lo, hi]` + `onRangeChange` · `step` snapping · keyboard ←↓/→↑ clamped · `ariaLabel` required (`role="slider"`) |
+| `Switch` | Instant on/off setting toggle | `checked` + `onChange` · `size="small"` for dense rows · inside `Field`/settings `Tabs` · `role="switch"` + `aria-checked` built-in |
+| `TimePicker` | HH:mm pick via stepper panel (+ "Now" shortcut) | `value` Date keeps its date-part on change, string `"HH:mm"` emits epoch-day · `locale` vi/en · `now` injectable for tests · pairs with `DatePicker` `showTime` |
+| `ToggleButton` | Button with a pressed state (on/off action) | `checked` exposed as `aria-pressed` · `disabled` · clusters of toggles (filters/view switches) · unchecked = default variant look |
+| `TreeSelect` | Pick a LEAF from a hierarchy, with search + clear | `treeData` nested `children` (parents are headers, not pickable) · `searchable` filters by label/path · `clearable` × resets · trigger shows the `"A / B"` path |

package/stack-template/docs/git-flow.md

@@ -0,0 +1,70 @@
+# Git flow — architecture-overview
+
+Quy ước nhánh + merge cho repo boilerplate. Mục tiêu: `main` luôn xanh CI + deployable,
+mọi thay đổi đi qua PR để có evidence + review trail (CI chạy trên PR trước khi vào main).
+
+## Nhánh
+
+| Loại | Tên | Từ | Vào |
+|---|---|---|---|
+| Story (epic/SF) | `__STACK_ORG__/story-<slug>` hoặc `__STACK_ORG__/sf-N-<slug>` | `main` | PR → `main` |
+| Fix | `__STACK_ORG__/fix-<slug>` | `main` | PR → `main` |
+| Docs/chore nhỏ | `__STACK_ORG__/docs-<slug>` / `__STACK_ORG__/chore-<slug>` | `main` | PR → `main` |
+
+Quy tắc:
+
+1. **Nhánh mới luôn từ `main` mới nhất** (`git fetch origin && git checkout -b <tên> origin/main`) — tránh mâu thuẫn với các merge đang lơ lửng.
+2. **Không push thẳng `main`.** Từ 2026-10-17: thay đổi vào main qua PR (CI gates chạy trên PR). Ngoại lệ thực tế khẩn (CI infra chết) — merge trực tiếp + nêu rõ trong commit message.
+3. **Một nhánh = một chủ đề.** Rename/chore lớn (vd `frontend/ → app/`) là commit riêng, không trộn với feature.
+4. Worktree song song (Orca/Claude sessions): mỗi session một nhánh riêng; **đọc `git log` nhánh TRƯỚC khi commit** — branch có thể đã được session khác đẩy tiến.
+
+## PR
+
+- Mở bằng `gh pr create` — template tự áp dụng (`.github/pull_request_template.md`).
+- **CI phải xanh trên PR trước merge** (convergence chạy mọi push; các workflow khác theo paths).
+- **Merge = `--no-ff`**, message theo convention: `merge(<loại>): <tóm tắt>` + ghi rõ nguồn
+  (vd `merge(feat): ui-kit — tách design system + Storybook 9 (ADR-0009)`).
+- Sau merge: xoá nhánh remote (`git push origin --delete <nhánh>`) + local khi không còn dùng.
+- Self-merge cho phép với docs/chore nhỏ; feature/fix đụng runtime cần ≥1 approve (reviewer
+  là agent `code-reviewer` hoặc người).
+
+## Commit message
+
+- Convention: `<type>(<scope>): <mô tả>` — type: `feat|fix|refactor|docs|test|chore|merge`.
+- Body ghi **root cause + evidence** khi là fix (mẫu: `fix(ci): convergence...` — nêu run ID,
+  local repro); ghi **verified gì** khi là refactor/feat (số test, build PASS).
+- Đổi behavior + story workflow → chụp evidence vào `docs/superpowers/evidence/`.
+
+## Rule được ENFORCE (husky pre-push + commit-msg)
+
+⚠️ 2026-10-17: GitHub Actions DISABLE (billing) → **hooks là lớp chính**. `.husky/pre-push`
+chặn push vi phạm 2 rule sau + chạy FE checks (typecheck/vitest/build) cho package bị đổi:
+
+1. **Branch name**: `__STACK_ORG__/<story|sf|fix|docs|chore|feat>-<slug-kebab>`
+   (vd `__STACK_ORG__/fix-gosvc-recent-events`, `__STACK_ORG__/sf-5-ui-redesign-conv`)
+2. **Commit message**: `<type>(<scope>): <mô tả>` với type ∈
+   `feat|fix|refactor|docs|test|chore|style|perf|build|ci|revert`
+   (merge commits "Merge pull request #N" được ngoại lệ)
+
+pre-push CHẠY THÊM FE checks (typecheck/vitest/build-storybook) cho package có file đổi
+(so với origin/main) — thay thế lớp CI shell/remotes/ui-kit đã tắt.
+
+Feedback sớm ngay tại máy — **husky** tự cài khi `pnpm install` (root `prepare` script
+chạy `husky`, guard `test -d .git` để không chết trong docker/CI không có .git):
+
+- `.husky/commit-msg` — validate conventional commit TRƯỚC khi commit tạo (mirror
+  git-guard; merge commits được ngoại lệ; thoát khẩn `git commit --no-verify` — CI vẫn chặn)
+- CI `git-guard` vẫn là lớp enforce cuối cùng (hook chỉ là feedback sớm, ai tắt hook
+  cũng không qua nổi PR)
+
+Worktree (Orca/Claude session): `pnpm install` trong worktree cũng chạy root `prepare`
+→ husky tự active theo worktree đó. Bỏ qua khẩn: `git push --no-verify` (tự chịu trách
+nhiệm — KHÔNG có lớp CI phía sau cho đến khi billing được khôi phục).
+
+## Checklist nhanh trước merge
+
+- [ ] Suite local xanh (xem bảng lệnh trong CLAUDE.md — `test_all:` của orca.yaml)
+- [ ] CI xanh trên nhánh/PR (kể cả `convergence`)
+- [ ] Không đụng READ-LOCKED (`app/shared/src/*.ts` logic + `mfToolkit`) nếu chưa có epic duyệt
+- [ ] Đụng contract → sync đủ bề mặt (xem agent `contracts-keeper`)
+- [ ] Descriptor đồng bộ (CLAUDE.md / orca.yaml / agents) nếu đổi cấu trúc, port, lệnh

package/stack-template/docs/parity-matrix.md

@@ -0,0 +1,102 @@
+# Parity matrix — benchmark → ui-kit
+
+Bảng đối chiếu component/benchmark gốc ↔ bản token hoá trong `app/ui-kit`.
+"Đủ dùng" = đủ surface chính của benchmark, không đuổi 100% API. Cập nhật mỗi
+batch ship (cột "Mức" ý kiến review, không phải cam kết API).
+
+| Component | Benchmark | Mức | Ghi chú parity |
+|---|---|---|---|
+| Button | antd | đủ dùng | variant `type` + `htmlType` tách (type của antd = htmlType), size, danger, loading |
+| Input / Textarea | antd | đủ dùng | h-8, status error = prop `invalid`, prefix/suffix affix, allowClear, size small/middle/large |
+| InputNumber | PrimeReact | đủ dùng | stepper icon XẶP DỌC trong mép phải, keyboard ↑↓, clamp min/max |
+| Select / MultiSelect | PrimeReact | đủ dùng | filterable, multiple chips + select-all, option groups, loading, showClear |
+| AutoComplete / CascadeSelect | PrimeReact | đủ dùng | cùng ngôn ngữ Select |
+| DatePicker / TimePicker | antd | đủ dùng | range + showTime, locale vi/en, TimePicker stepper Giờ/Phút |
+| Calendar | PrimeReact ô vuông → ngôn ngữ nút chung | đủ dùng | states theo pagination: outline thường / accent selected / ring today / adjacent disabled; locale vi/en + range |
+| Table (DataTable) | PrimeReact | đủ dùng | client-side data grid + filter + Skeleton shimmer |
+| List | antd | đủ dùng | items + renderItem, loading→Skeleton, empty→EmptyState, pagination client |
+| Pagination | antd | đủ dùng | item vuông 32 outline, active accent đặc + fontWeightStrong, SVG chevron, ellipsis `···` jump ±5 |
+| Alert | antd | đủ dùng | **filled mặc định** (WCAG AA), `variant="outlined"` giữ look cũ |
+| Menu (đa cấp) | antd | đủ dùng | vertical/horizontal, submenu ∞ cấp, auto-open selectedKey, animate grid-rows, a11y menu/menuitem |
+| Menubar / ContextMenu / PanelMenu / TabMenu / SplitButton | PrimeReact | đủ dùng | họ menu navigation; ContextMenu right-click + separator |
+| Sidebar | antd Layout.Sider | đủ dùng | collapsible 200↔80 icon-only, brand/footer slot, `MenuCompactContext` |
+| Dropdown / Toolbar / SpeedDial / Splitter | PrimeReact | đủ dùng | navigation phụ |
+| Tabs | antd/PrimeReact | đủ dùng | ARIA tabs pattern |
+| Upload / UploadDropzone | antd | đủ dùng | hidden input + beforeUpload guard, drag-drop, danh sách file |
+| Field | antd Form.Item (lite) | đủ dùng | label + error(role=alert)/hint, id `aria-describedby` suy từ htmlFor |
+| useForm | React Hook Form (lite) + zod | đủ dùng | values/errors/touched, mode onSubmit/onBlur/onChange, focus-first-invalid; zod peer-dep |
+| Icon | primeicons 7.0.0 | đủ dùng | 48 icon path data gốc, viewBox 24, fill currentColor, tree-shake import thẳng |
+| Modal / Drawer / Notification / Message / Popconfirm | antd | đủ dùng | feedback family; Message static API `message.success()` |
+| Tooltip | antd | đủ dùng | placement top/bottom, trigger hover + focus |
+| Progress / Statistic / Result / Steps / Space / Divider / Descriptions / Collapse / Card / Breadcrumb / Image / Tag / Badge / Avatar | antd | đủ dùng | display family; Result 404/500, AvatarGroup max "+N" |
+| Carousel | PrimeReact API + Swiper engine | đủ dùng | peer-dep swiper qua subpath `@wakii/ui-kit/carousel`; nút nav direct slide API (v14-safe) |
+| Chart | Chart.js | đủ dùng | subpath `@wakii/ui-kit/chart` |
+| Schedule | FullCalendar | đủ dùng | subpath `@wakii/ui-kit/schedule`; peer optional (fallback khi chưa cài) |
+| Editor | Tiptap | đủ dùng | subpath `@wakii/ui-kit/editor` |
+| TreeSelect | antd TreeSelect (lite) | đủ dùng | data cây đệ quy, chỉ chọn leaf, trigger hiện đường dẫn |
+| AvatarGroup | antd Avatar.Group | đủ dùng | stack overlap `-ml-2` + ring, max → pill "+N" tooltip |
+| Hooks ×16 | usehooks.com | đủ dùng | useDebounce/useThrottle/useToggle/useLocalStorage/useSessionStorage/useMediaQuery/useWindowSize/useHover/useClickAway/useKeyPress/useTimeout/useCountdown/useCopyToClipboard/usePrevious/useDefault/useLockBodyScroll |
+| Skeleton / Spinner / BusyBox / EmptyState / BlockUI / ScrollTop / Segmented / Knob / Inplace / Rating / Slider / Switch / Checkbox / Radio / ToggleButton / Password / InputMask / InputOTP / Mention / Galleria / Timeline / OrderList / PickList / ColorPicker / Knob | PrimeReact | đủ dùng | Tier 1–4 (xem story từng comp) |
+| Typography | antd | đủ dùng | Title level 1–5, Text type, code/keyboard/copyable; metrics antd |
+
+## Gap vs antd + MUI + PrimeReact — kế hoạch OCD-completion (2026-10-18)
+
+Đối chiếu catalog 3 thư viện chuẩn; "đủ dùng" ở bảng trên nghĩa là surface CHÍNH, chưa phải
+toàn bộ case. Danh sách dưới = còn thiếu thật, xếp theo giá trị usage thực tế:
+
+### P0 — dùng gần như mọi app (làm trước)
+
+| Thiếu | Benchmark | Ghi chú |
+|---|---|---|
+| `Grid` (Row/Col) + `Flex` | antd Grid/Flex, MUI Grid/Stack | layout primitive nền tảng — hiện chỉ có `Space`; responsive span/gutter |
+| `Popover` | antd Popover, MUI Popover, PrimeReact OverlayPanel | panel neo trigger nội dung tự do — Tooltip chỉ text, Popconfirm chỉ confirm |
+| `Input.Search` | antd | variant input + nút search bên phải; filter-bar dùng liên tục |
+| `Link` | MUI Link, antd Typography.Link | typography hiện KHÔNG có Link (đã verify grep) |
+| `Affix` | antd | sticky wrapper cho toolbar/filter-bar |
+| `Table` expandable rows | antd Table | row mở rộng chi tiết — CRUD hay dùng (đã verify chưa có) |
+
+### P1 — app thật hay cần
+
+| Thiếu | Benchmark | Ghi chú |
+|---|---|---|
+| `Timesheet` | KHÔNG có sẵn ở antd/MUI/Prime (phải tự ghép DataGrid) | **user yêu cầu 2026-10-18** — domain composite: grid tuần × task, cell giờ InputNumber, tổng hàng/cột/grand, weekend shading, locale vi/en, week nav · làm được = hơn cả 3 benchmark |
+| `DragDrop` + `KanbanBoard` | antd/MUI KHÔNG có (tự ghép dnd-kit) · PrimeReact chỉ DragDrop thô | **user yêu cầu 2026-10-18** — primitives Draggable/DropZone native 0-deps (desktop) + keyboard-move a11y · KanbanBoard composite (columns/cards/onCardMove/WIP-limit/renderCard) · touch = hạn chế đã ghi (hướng nâng cấp: peer-dep dnd-kit nếu app cần) |
+| `Parallax` + `Reveal` + `CountUp` | KHÔNG component nào của 3 benchmark có (phải tự viết / react-spring) | **user yêu cầu 2026-10-18** — họ motion-effects 0-deps: Parallax scroll-linked transform (rAF) · Reveal enter-on-scroll (IntersectionObserver + keyframes sẵn) · CountUp số đếm animate · tôn trọng prefers-reduced-motion · differentiator "làm hơn đối thủ" |
+| `Anchor` | antd | scroll-spy nav cho trang docs/long-form |
+| `QRCode` | antd | link thanh toán / chia sẻ (bối cảnh VN dùng nhiều) |
+| `Watermark` | antd | chống copy nội dung nhạy cảm |
+| `Tour` | antd | onboarding sản phẩm; kết hợp `useFocusTrap` |
+| `ToggleButtonGroup` | MUI | cluster `ToggleButton` hiện chỉ đơn lẻ |
+| `VirtualScroller` | PrimeReact | `Table virtual` đã có — standalone cho List dài |
+
+### P2 — niche, chỉ làm khi có app tiêu thụ
+
+`Dock` (PrimeReact) · `MegaMenu` (PrimeReact) · `OrganizationChart` · `TreeTable` ·
+`Terminal` · `Fieldset/Panel` (Card phủ phần lớn) · `DeferredContent` · motion primitives
+(`<Fade>/<Zoom>` wrapper — keyframes đã có trong tokens).
+
+### P2-CHUẨN-HÓA 2026-10-18 (user: "vẫn chưa đủ") — full-catalog diff, sóng xây mới
+
+| Thiếu | Benchmark | Giá trị | Owner |
+|---|---|---|---|
+| `Layout` (Header/Content/Footer/Sider wiring) | antd Layout | CAO — app shell thật | W7 |
+| `Form.List` (Field.Array dynamic add/remove) | antd Form.List | CAO — form động | W6 |
+| `TreeTable` | PrimeReact | medium — cây dữ liệu bảng | D |
+| `OrgChart` + `TriStateCheckbox` | PrimeReact | medium + nhỏ | V2 |
+| `MegaMenu` + `SlideMenu` | PrimeReact | medium — nav advanced | W9 |
+| `Fade/Zoom/Collapse` transitions + `Backdrop` | MUI transitions | medium — motion composable | W8 |
+| `BottomNavigation` + `FloatButton` + `Fieldset` + `Terminal` + `DeferredContent` | MUI/antd/PrimeReact | nhỏ — mobile/utility | V1 (sau taxonomy) |
+
+### Case-coverage OCD (song song component mới)
+
+Mỗi component hiện có: đối chiếu trang docs antd/MUI/PrimeReact tương ứng, liệt kê
+case/variant còn thiếu (vd Button `block`? Table `expandable`; Modal `centered`?) rồi bổ
+sung stories EN + tests hành vi. Nguồn chân lý: docs của benchmark, KHÔNG đoán.
+
+## Nguyên tắc token (áp cho mọi hàng)
+
+1. **Màu**: chỉ token `--c-*`/`--ink*`/`--line*`/`--accent`/`--st-*` — không hex cứng trong component.
+2. **Radius**: `rounded-lg` (8) cho control vuông; `rounded-pill` cho pill; một radius mỗi khối.
+3. **Ngôn ngữ nút thống nhất** (2026-10-17): thường = transparent + `hover:bg-s3`; active/selected = `bg-accent text-white font-medium`; disabled = `text-ink3/ink4` + `cursor-not-allowed` không hover.
+4. **Motion**: CSS thuần + motion tokens (`--motion-*`, `--ease-*`); animation height qua `grid-template-rows 0fr↔1fr`.
+5. **Z-index**: scale token `--z-*` (dropdown < popover < modal < toast < tooltip) — không số cứng.

package/stack-template/docs/superpowers/contexts/auth-real/gap-answer.md

@@ -0,0 +1,195 @@
+# Gap-answer — 8 mục đổi shared files (epic auth-real VU-59)
+
+> Soạn bởi SF-1 (VU-60) theo context pack `sf-1.md` mục "Gap-answer doc (8 mục)".
+> Trạng thái: **PROPOSAL — chờ coordinator APPROVED-reply trên epic VU-59** trước khi
+> SF thực thi. SF-1 KHÔNG commit compose/nginx/init/workspace (boundary).
+> Mỗi mục ghi: file đích · giá trị HIỆN TẠI (đọc từ main 2026-10-17) → GIÁ TRỊ ĐÍCH ·
+> SF thực thi · lý do. Tất cả anchor đã grep-verify trên tree SF-1.
+
+## ① Compose entry `auth-mock` → `auth-svc`
+
+**File:** `platform/docker-compose.yml` (block `auth-mock:` — dòng 75–94 hiện tại)
+
+Đổi key service `auth-mock:` → `auth-svc:` + nội dung entry:
+
+```yaml
+  auth-svc:
+    build: ../services/auth-svc        # ← đổi từ ./auth-mock (service mới ở services/)
+    environment:
+      PORT: 8090 # container port CỐ ĐỊNH (conventions/05) — giữ nguyên surface :8090
+      DATABASE_URL: postgres://auth_svc:${AUTH_SVC_DB_PASSWORD:?set in .env}@postgres:5432/${POSTGRES_DB:?set in .env}
+      JWT_SECRET: ${JWT_SECRET:?set in .env}
+      ACCESS_TOKEN_TTL: ${ACCESS_TOKEN_TTL:-30m}     # token-contract.md §1
+      AUTH_DEV_PASSWORD: ${AUTH_DEV_PASSWORD:-demo-password}   # decision #10
+      USERS_FIXTURE_PATH: /app/users.json
+      CORS_DEV_ORIGIN: ${CORS_DEV_ORIGIN:-}
+      LOG_LEVEL: ${LOG_LEVEL:-info}
+    volumes:
+      - ../contracts/auth/users.json:/app/users.json:ro   # ← mục ⑤
+    ports:
+      - "${AUTH_PORT:-8090}:8090"                          # ← mục ⑦
+    depends_on:
+      postgres:
+        condition: service_healthy
+    healthcheck:
+      # wget /readyz (KHÔNG /healthz như auth-mock cũ) — readyz auth-svc kiểm DB
+      # thật (spec v2: "không hardcode 200") → service_healthy = đã migrate+seed.
+      test: ["CMD", "wget", "-qO-", "http://127.0.0.1:8090/readyz"]
+      interval: 5s
+      timeout: 3s
+      retries: 12
+      start_period: 20s   # chờ migration + seed fixture lúc boot
+```
+
+**SF thực thi:** SF-5 (decommission — xoá entry `auth-mock` + `platform/auth-mock/` cùng commit).
+**Lý do:** giữ surface `:8090 /api/auth/*` (decision #2) — gateway/port-table/FE-flow không đổi.
+
+## ② Key `gateway.depends_on.auth-mock` → `auth-svc`
+
+**File:** `platform/docker-compose.yml` (dòng 102–104 hiện tại)
+
+```yaml
+    depends_on:
+      auth-svc:            # ← đổi từ auth-mock
+        condition: service_healthy
+```
+
+**SF thực thi:** SF-5 (cùng commit với ① — cùng file).
+**Lý do:** gateway gate trên service_healthy; healthcheck auth-svc dùng `/readyz` (kiểm DB)
+→ gateway chỉ nhận traffic khi auth-svc đã migrate + seed xong.
+
+## ③ nginx upstream `auth-mock:8090` → `auth-svc:8090`
+
+**File:** `platform/gateway/nginx/nginx.conf` (dòng 100–102 hiện tại)
+
+```nginx
+        # ---------- API: auth → auth-svc (MỞ — entry login + register + swagger) ----------
+        location /api/auth {
+            set $up http://auth-svc:8090;   # ← đổi từ http://auth-mock:8090
+```
+
+**SF thực thi:** SF-5.
+**Lý do:** pass-through giữ nguyên (conventions/08); chỉ hostname upstream đổi theo tên
+service compose mới. Route rules + presence-check `/api/tasks|/api/users|/api/activity`
+KHÔNG đổi.
+
+## ④ go-svc env `AUTH_MOCK_URL` — đổi VALUE, giữ KEY
+
+**File:** `platform/docker-compose.yml` (entry `go-svc`, dòng 186 hiện tại)
+
+```yaml
+      AUTH_MOCK_URL: http://auth-svc:8090   # ← chỉ đổi VALUE từ http://auth-mock:8090
+```
+
+**File kèm:** `platform/.env.example` (dòng 53 hiện tại: `AUTH_MOCK_URL=http://auth-mock:8090`)
+— cùng swap VALUE → `http://auth-svc:8090` trong cùng commit SF-5 (compose dùng literal nên
+không phụ thuộc dòng này, nhưng native-dev consumer đọc `.env` sẽ trỏ host chết sau
+decommission nếu quên; **KEY `AUTH_MOCK_URL` giữ nguyên** — go-svc đọc theo tên env này).
+
+**SF thực thi:** SF-5.
+**Lý do:** KEY giữ nguyên `AUTH_MOCK_URL` — go-svc đọc env này ở
+`services/go-svc/internal/config/config.go:42` (`getenv("AUTH_MOCK_URL")`); đổi key =
+sửa code go-svc (ngoài phạm vi gap-answer, không SF nào được brief sửa go-svc trừ
+verify-code). Value-only swap = zero code change, zero risk cho go-svc.
+**⚠️ Note cho follow-up:** `config.go:67` hardcode default `http://auth-mock:8090` khi
+env unset — compose + CI luôn set env nên không lộ runtime; default stale này gom vào
+follow-up "đổi tên auth-mock" cùng cụm iss-rename (spec decision #7).
+
+## ⑤ Volume mount `users.json` cho auth-svc
+
+**File:** `platform/docker-compose.yml` — đã embed trong entry ở mục ①; tách riêng để
+review rõ:
+
+```yaml
+    volumes:
+      - ../contracts/auth/users.json:/app/users.json:ro
+    environment:
+      USERS_FIXTURE_PATH: /app/users.json
+```
+
+**SF thực thi:** SF-5 (đi kèm ①).
+**Lý do:** auth-svc seed idempotent từ fixture GIỮ UUID (`ON CONFLICT (id) DO NOTHING`,
+token-contract.md §5) — mount trực tiếp từ `contracts/` như auth-mock cũ: sửa fixture
+không cần rebuild image. `GET /users` serve từ DB (schema `auth`), KHÔNG đọc fixture
+mỗi request.
+
+## ⑥ Init script + role `auth_svc` / schema `auth` / `AUTH_SVC_DB_PASSWORD`
+
+**File 1:** `platform/postgres/init/01-init.sh` — thêm block sau block role go_readonly:
+
+```sql
+CREATE SCHEMA IF NOT EXISTS auth;
+CREATE ROLE auth_svc   LOGIN PASSWORD '${AUTH_SVC_DB_PASSWORD}';
+GRANT USAGE, CREATE ON SCHEMA auth TO auth_svc;
+ALTER ROLE auth_svc SET search_path = auth;
+```
+
+**File 2:** `platform/docker-compose.yml` — entry `postgres.environment` thêm 1 dòng
+(cạnh GO_READONLY_DB_PASSWORD, dòng 35 hiện tại):
+
+```yaml
+      AUTH_SVC_DB_PASSWORD: ${AUTH_SVC_DB_PASSWORD:?set in .env}
+```
+
+**File 3:** `platform/.env.example` — thêm 1 dòng vào block Postgres:
+
+```
+AUTH_SVC_DB_PASSWORD=change-me-auth
+```
+
+**SF thực thi:** SF-5 (cả 3 file; `.env.example` SF-5 đồng bộ cùng commit theo plan Task 5).
+**Lý do:** auth-svc owns schema `auth` riêng (decision #3 — pattern per-service schema +
+LOGIN role như 3 service cũ); init chỉ chạy trên volume MỚI → **gotcha: volume postgres cũ
+phải `docker compose down -v` 1 lần** (epic acceptance #6 — gotcha vào orca.yaml +
+walkthrough ở SF-5 docs sync).
+
+## ⑦ `.env` renames (phần compose-side)
+
+**Đã xong bởi SF-1** (commit này): `platform/.env.example` — `AUTH_MOCK_PORT=8090` →
+`AUTH_PORT=8090`; `AUTH_MOCK_DEV_PASSWORD=demo-password` → `AUTH_DEV_PASSWORD=demo-password`
+(+ comment nguồn chung e2e/svc-activity/seed); **+ `ACCESS_TOKEN_TTL=30m`**.
+
+**Phần compose-side — SF-5 thực thi** (cùng commit ①):
+
+| Vị trí trong compose (hiện tại) | Đổi thành |
+|---|---|
+| `ports: - "${AUTH_MOCK_PORT:-8090}:8090"` (dòng 88) | `"${AUTH_PORT:-8090}:8090"` |
+| `AUTH_MOCK_DEV_PASSWORD: ${AUTH_MOCK_DEV_PASSWORD:-demo-password}` (dòng 81) | `AUTH_DEV_PASSWORD: ${AUTH_DEV_PASSWORD:-demo-password}` (decision #10 — default `demo-password` KHÔNG đổi) |
+| comment dòng 78/90 nhắc `${AUTH_MOCK_PORT}` | nhắc `${AUTH_PORT}` |
+
+**Lý do:** decision #10 — `${AUTH_DEV_PASSWORD:-demo-password}` (KHÔNG `change-me-*`):
+e2e + go-svc svc-activity + seed cùng một nguồn, acceptance epic #3 phụ thuộc.
+`SVC_ACTIVITY_PASSWORD=demo-password` trong `.env.example` KHÔNG đổi (đã khớp nguồn chung).
+
+## ⑧ `pnpm-workspace.yaml` + `services/auth-svc`
+
+**File:** `pnpm-workspace.yaml` — thêm 1 dòng vào block `packages:`, cạnh
+`- "services/node-svc"` (dòng cuối block hiện tại):
+
+```yaml
+  # auth-svc (SF-2 epic VU-59 điền impl) — standalone lockfile như node-svc
+  - "services/auth-svc"
+```
+
+**SF thực thi:** SF-2 (plan Task 2 — Files: Modify `pnpm-workspace.yaml`; SF-2 là SF duy
+nhất đụng file này trong tier 1 → an toàn song song).
+**Lý do:** auth-svc là workspace member (mirror node-svc); install bằng
+`pnpm install --frozen-lockfile --ignore-workspace` trong thư mục service đến khi vào
+workspace chính thức (gotcha CLAUDE.md).
+
+---
+
+## Tóm tắt ma trận thực thi
+
+| Mục | File | SF thực thi |
+|---|---|---|
+| ① compose entry | `platform/docker-compose.yml` | SF-5 |
+| ② depends_on key | `platform/docker-compose.yml` | SF-5 |
+| ③ nginx upstream | `platform/gateway/nginx/nginx.conf` | SF-5 |
+| ④ go-svc env value | `platform/docker-compose.yml` + `.env.example:53` | SF-5 |
+| ⑤ users.json mount | `platform/docker-compose.yml` | SF-5 |
+| ⑥ init + role + env password | `platform/postgres/init/01-init.sh` + compose + `.env.example` | SF-5 |
+| ⑦ .env renames | `.env.example` (SF-1 **đã xong**) + compose refs (SF-5) | SF-1 ✓ / SF-5 |
+| ⑧ workspace line | `pnpm-workspace.yaml` | SF-2 |
+
+Không mục nào cho 2 SF đụng cùng 1 shared file trong 1 tier (ràng buộc plan rev2).

package/stack-template/docs/superpowers/contexts/auth-real/sf-1.md

@@ -0,0 +1,21 @@
+# SF-1 Context Pack — Contracts + hiệp ước + gap-answer
+> Đọc file này THAY VÌ tự tổng hợp. Epic spec: docs/superpowers/specs/2026-10-17-auth-real-design.md (rev2) · Plan Task 1: docs/superpowers/plans/2026-10-17-auth-real-plan.md · Bracket: docs/superpowers/mindmaps/auth-real.wakii · Linear: VU-60.
+
+## Spec slice (chỉ phần SF-1 chịu trách nhiệm)
+1. `contracts/openapi/auth.yaml` v2: schemas `RegisterRequest{email, password(8-72), displayName}`, `TokenPair{accessToken, refreshToken}`, `RefreshRequest`; paths `POST /register|/login|/refresh|/logout|/logout-all`; response login/register = `{user: UserRef, accessToken, refreshToken}` (DROP tokenType/expiresIn — decision #8); **giữ `GET /users`**; **xoá `/.well-known/openid-configuration`** + disclaimer header.
+2. `contracts/auth/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Ả token user + 401 (strict)**; `iss` **PINNED "auth-mock"** (3 service + CI hardcode — đổi là follow-up riêng); `localStorage['bp.rt']` rationale (accepted-for-demo, httpOnly = upgrade path); RS256/JWKS = path OIDC.
+3. `platform/.env.example`: +`AUTH_DEV_PASSWORD` default **`${AUTH_DEV_PASSWORD:-demo-password}`** (KHÔNG change-me-* — e2e/svc-activity/seed cùng nguồn), +`ACCESS_TOKEN_TTL=30m`, rename `AUTH_MOCK_PORT`→`AUTH_PORT`, `AUTH_MOCK_DEV_PASSWORD`→`AUTH_DEV_PASSWORD`.
+4. `.github/workflows/contracts.yml`: schemathesis scope HẸP — chỉ paths auth-mock đang implement (paths mới sẽ 404 → job đỏ oan). Exclude register|refresh|logout đến SF-5.
+5. **Gap-answer doc (8 mục, KHÔNG commit compose/nginx/init)**: ① compose entry auth-mock→auth-svc (:8090, healthcheck wget /readyz) ② key `gateway.depends_on.auth-mock`→`auth-svc` ③ nginx upstream auth-mock:8090→auth-svc:8090 ④ go-svc env `AUTH_MOCK_URL` value→`http://auth-svc:8090` ⑤ users.json volume mount cho auth-svc ⑥ init 01-init.sh + role `auth_svc`/schema `auth`/`AUTH_SVC_DB_PASSWORD` ⑦ .env renames (mục 3) ⑧ `pnpm-workspace.yaml` +`services/auth-svc`. FLAG coordinator duyệt — SF-5 thực thi.
+
+## Touch map (SF-1 sở hữu)
+`contracts/openapi/auth.yaml` · `contracts/auth/token-contract.md` · `platform/.env.example` · `.github/workflows/contracts.yml` (chỉ schemathesis scope) · gap-answer doc `docs/superpowers/contexts/auth-real/gap-answer.md`.
+READ-ONLY: compose, nginx, init, pnpm-workspace (SF-5/SF-2 thực thi theo gap-answer đã duyệt).
+
+## ACCEPTANCE (user-visible)
+- `pnpm lint:contracts` xanh; CI `contracts` xanh với schemathesis SCOPED (không 404).
+- token-contract.md v2 đọc được thành hiệp ước đầy đủ: TTLs, rotation CAS, reuse strict, iss pinned, bp.rt rationale — không còn câu nào nói TTL 8h / không refresh.
+- Gap-answer 8 mục materialize thành file, coordinator comment APPROVED trên epic.
+
+## Boundary (KHÔNG làm)
+KHÔNG code runtime auth-svc (SF-2); KHÔNG commit compose/nginx/init/workspace (SF-5/SF-2 theo gap-answer); KHÔNG đụng node/go/spring verify code; KHÔNG đổi users.json (chỉ đọc để ghi contract).

package/stack-template/docs/superpowers/contexts/auth-real/sf-2.md

@@ -0,0 +1,21 @@
+# SF-2 Context Pack — auth-svc: schema + seed + 5 endpoints
+> Epic spec: docs/superpowers/specs/2026-10-17-auth-real-design.md (rev2) · Plan Task 2: docs/superpowers/plans/2026-10-17-auth-real-plan.md · Bracket: docs/superpowers/mindmaps/auth-real.wakii · Linear: VU-61. Depends on: SF-1 (contracts đã merge — code theo auth.yaml v2 ĐÚNG rev đó).
+
+## Spec slice
+1. Service `services/auth-svc/` mirror node-svc: Fastify+TS+Drizzle, env/logger/JWT plugin (**verify issuer literal "auth-mock"** — PINNED), envelope handler (HttpError.statusCode, pino cast — improvements-log 2026-10-12), `/healthz`+`/readyz` naked+prefix. `pnpm-workspace.yaml` +`services/auth-svc` (1 dòng — shared file duy nhất SF-2 đụng, không ai khác đụng trong tier).
+2. Migration 0000: 2 bảng theo spec §Kiến trúc (`roles text[] NOT NULL DEFAULT '{"user"}'`). Seed từ `contracts/auth/users.json`: giữ UUID/displayName/roles, `password_hash=argon2id(AUTH_DEV_PASSWORD)`, idempotent `ON CONFLICT (id) DO NOTHING`.
+3. 5 endpoints: register (argon2id; email lowercase; 409 UNIQUE; password 8-72), login (sign HS256 TTL ACCESS_TOKEN_TTL iss "auth-mock" + refresh `crypto.randomBytes(32)`), refresh (**CAS rotation**: `UPDATE auth.refresh_tokens SET revoked_at=now(), replaced_by=$new WHERE id=$old AND revoked_at IS NULL RETURNING *` — 0 rows → reuse-detect: revoke tất cả user + 401), logout (204 idempotent), logout-all (Bearer sub). Envelope conventions/04; KHÔNG log password/refresh.
+4. `.github/workflows/services-auth-svc.yml` mới từ `.github/workflow-templates/services-ci.yml.example` (path filter + permissions contents:read).
+5. Local verify KHÔNG dùng compose (entry auth-svc chưa commit — SF-5 mới commit): postgres local tạo schema auth thủ công → `pnpm --filter auth-svc test` (unit + integration) → `docker build` → curl chuỗi health + register→login→refresh→reuse→401.
+
+## Touch map (SF-2 sở hữu)
+`services/auth-svc/**` (toàn bộ) · `.github/workflows/services-auth-svc.yml` (mới) · 1 dòng `pnpm-workspace.yaml` + lockfile.
+READ-ONLY: `contracts/**` (SF-1), compose/nginx/init (SF-5), node/go/spring.
+
+## ACCEPTANCE (user-visible)
+- curl register→login→refresh→refresh-lại-token-cũ (401 + mọi refresh token của user chết)→logout (204, idempotent)→logout-all — chạy được đầu-cuối trên auth-svc boot local.
+- 5 user fixture login được bằng AUTH_DEV_PASSWORD (alice roles admin, bob user — claims đúng từ seed).
+- Workflow services-auth-svc.yml xanh trên nhánh (build + test + docker build + boot-smoke).
+
+## Boundary (KHÔNG làm)
+KHÔNG đụng node/go/spring/FE (SF-3/SF-4); KHÔNG commit compose/nginx/init (SF-5); KHÔNG đổi iss; KHÔNG đụng auth-mock (còn sống đến SF-5); RBAC (SF-3).

package/stack-template/docs/superpowers/contexts/auth-real/sf-3.md

@@ -0,0 +1,17 @@
+# SF-3 Context Pack — node-svc RBAC: DELETE admin-only
+> Epic spec: docs/superpowers/specs/2026-10-17-auth-real-design.md · Plan Task 3: docs/superpowers/plans/2026-10-17-auth-real-plan.md · Bracket: docs/superpowers/mindmaps/auth-real.wakii · Linear: VU-62. Depends on: SF-1 (contracts; kỹ thuật có thể đứng độc lập — roles claim đã có trong token hiện tại). Tier Standard (SF nhỏ).
+
+## Spec slice
+1. `services/node-svc/src/plugins/auth.ts`: xác nhận request.user mang `roles` (decode từ claims — đã có).
+2. `services/node-svc/src/routes/tasks.ts`: preHandler DELETE `/tasks/:id` — reject 403 envelope `{code:"FORBIDDEN"}` khi `!user.roles?.includes('admin')` (message: 'Chỉ admin được xoá task').
+3. Tests (RED trước): DELETE token roles `["user"]` → 403 envelope; alice admin → 200; missing roles → 403.
+
+## Touch map (SF-3 sở hữu)
+`services/node-svc/src/plugins/auth.ts` · `services/node-svc/src/routes/tasks.ts` · `services/node-svc/src/app.test.ts`.
+READ-ONLY: mọi thứ khác.
+
+## ACCEPTANCE (user-visible)
+- Bob (roles user) thử xoá task qua API → 403 envelope rõ ràng; Alice (admin) xoá → 200. (e2e user-visible assert ở SF-5.)
+
+## Boundary (KHÔNG làm)
+KHÔNG đụng auth-svc (SF-2), FE (SF-4), e2e.sh (SF-5 thêm assert RBAC), PATCH/POST tasks (chỉ DELETE).

package/stack-template/docs/superpowers/contexts/auth-real/sf-4.md

@@ -0,0 +1,20 @@
+# SF-4 Context Pack — FE refresh-client + LoginPage register
+> Epic spec: docs/superpowers/specs/2026-10-17-auth-real-design.md · Plan Task 4: docs/superpowers/plans/2026-10-17-auth-real-plan.md · Bracket: docs/superpowers/mindmaps/auth-real.wakii · Linear: VU-63. Depends on: SF-1 (auth.yaml v2 — response shape `{user, accessToken, refreshToken}`, DROP tokenType/expiresIn).
+
+## Spec slice
+1. `app/shared/src/refresh-client.ts` (FILE MỚI + export qua index.ts — token-storage.ts READ-LOCKED không đụng): `login/register/withRefresh/logout`. Access → tokenStorage (API có sẵn: setToken/clearToken); refresh → `localStorage['bp.rt']` (rationale pin token-contract v2). 401 → refresh single-flight (promise lock) đúng 1 lần → retry; refresh fail → clear 2 key + throw Unauthorized.
+2. `app/shell/src/pages/LoginPage.tsx`: tab Login/Register (response v2 shape — LoginPage hiện đọc tokenType/expiresIn phải bỏ); lỗi 401/409 theo messages contract. **Tailwind v4 đã trên main (PR #13) — UI mới theo pattern Tailwind hiện hành, KHÔNG css-scoped cũ.**
+3. `app/shell/src/api.ts`: login/register đi qua wrapper.
+4. Tests (mock fetch): login/register lưu cặp đúng key; 401 → refresh đúng 1 lần → retry OK; refresh 401 → clear + Unauthorized; logout revoke + clear. Coverage gate 90/90/80/90 giữ; a11y suite (tab/form mới) giữ.
+
+## Touch map (SF-4 sở hữu)
+`app/shared/src/refresh-client.ts` (mới) · `app/shared/src/index.ts` (export) · `app/shell/src/pages/LoginPage.tsx` · `app/shell/src/api.ts` · `app/shell/tests/*`.
+READ-ONLY: `app/shared/src/{api-client,token-storage,error-envelope,mf-bootstrap}.ts` (READ-LOCKED), `app/ui-kit/**` (consume primitives), remotes.
+
+## ACCEPTANCE (user-visible)
+- User đăng ký tài khoản mới từ UI → login → thấy nav user chip.
+- Access token hết hạn (giả lập TTL ngắn/mock) → request kế tiếp tự refresh — UI KHÔNG thấy 401.
+- Logout → 2 key sạch, về login.
+
+## Boundary (KHÔNG làm)
+KHÔNG sửa READ-LOCKED; KHÔNG đụng remotes tasks/activity (chỉ shell); KHÔNG làm cross-tab sync (SF-5 human walkthrough); KHÔNG đụng auth-svc/node (SF-2/SF-3).

package/stack-template/docs/superpowers/contexts/auth-real/sf-5.md

@@ -0,0 +1,21 @@
+# SF-5 Context Pack — Convergence + decommission + CI swap + docs
+> Epic spec: docs/superpowers/specs/2026-10-17-auth-real-design.md · Plan Task 5: docs/superpowers/plans/2026-10-17-auth-real-plan.md · Bracket: docs/superpowers/mindmaps/auth-real.wakii · Linear: VU-64. Depends on: SF-2 + SF-3 + SF-4 (đã merge về dest).
+
+## Spec slice
+1. **Thực thi gap-answer 8 mục** (SF-1 soạn, coordinator APPROVED — đọc `docs/superpowers/contexts/auth-real/gap-answer.md` + epic comment): compose entry auth-mock→auth-svc (+depends_on key) · nginx upstream · go-svc env value `http://auth-svc:8090` · users.json mount · init role auth_svc · .env renames · workspace line (đã có từ SF-2).
+2. **Xoá `platform/auth-mock/`** (thư mục + mọi tham chiếu sống).
+3. **CI swap**: `contracts.yml` boot auth-svc + nới schemathesis full paths (bỏ scope SF-1); `services-go-svc.yml` + `services-spring-svc.yml` boot auth-svc. Node workflow không đổi (iss pinned). **Acceptance: TOÀN BỘ CI main xanh sau merge.**
+4. **e2e.sh mở rộng** (bảo toàn: exit N = fail bước N, marker `SAGA_TASK_ID=`, SMOKE_SAGA=0 exit 0): +register `smoke-<ts>@demo.local` → refresh → reuse old → 401 → logout; +RBAC: register user roles ["user"] DELETE task → 403, alice → 200.
+5. **Docs sync CÙNG commit**: walkthrough (+register/refresh + gotcha `down -v` 1 lần — volume cũ thiếu role auth_svc + sync số bước PASS), CLAUDE.md (auth-mock → auth-svc), orca.yaml (services entry + gotcha + test_all), README, toolchain, grep `auth-mock` = rỗng trên docs/CLAUDE.md/orca.yaml/README/.env.example/.github (token-contract/users.json $comment giữ note lịch sử).
+6. **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/`.
+
+## Touch map (SF-5 sở hữu)
+compose · nginx · init · 3 CI workflows · e2e.sh · platform/auth-mock/ (xoá) · docs toàn bộ liên quan.
+READ-ONLY: services/auth-svc, node, go, spring, app/** (code SF trước — bug thấy được = REPORT coordinator, KHÔNG fix — SF hội tụ).
+
+## ACCEPTANCE (user-visible)
+- Fresh clone + `down -v` → compose up → login alice bằng UI mới → saga demo fail@demo.local VẪN chạy (badge Gán thất bại) → bob tạo task, xoá bị chặn 403, alice xoá được.
+- e2e mở rộng PASS; toàn CI main xanh; auth-mock không còn tồn tại trong repo.
+
+## Boundary (KHÔNG làm)
+KHÔNG fix bug miền service/FE (report); KHÔNG đổi contracts (rev2 là final); KHÔNG đụng Linear state epic (coordinator).