Diff reviewDiff 審查 · 2026-05-05 19:20 → 2026-05-06 04:25 · HEAD 5c2be5b4 · range範圍 5332aa89~1..5c2be5b4
B_Smart · Sprint ReviewB_Smart · Sprint 回顧

From red CI & 32% coverage to all-green & 83%, in nine hours.

9 小時內，CI 從全紅、覆蓋率 32% 翻到全綠、83%。

The core insight: a backlog of three independent debts — missing test coverage, 234 unreviewed UI findings, and stale-by-design CI/docs — was paid down in parallel by orchestrating 20 agents against a file-locked work schema. When wave-1 agents truncated mid-edit, lightweight finalizers swept the diffs without redoing the work. When CI broke in four distinct ways post-push, each failure was diagnosed forward (never reverted) until green held.

底層邏輯：三筆獨立的技術債——缺失的測試覆蓋率、234 個未審查的 UI 發現、stale-by-design 的 CI/docs——透過 20 個 agent 的檔案鎖定機制並行清償。Wave 1 agent 中途截斷時，由輕量 finalizer 不重做工作只追數收尾；推送後 CI 連 4 種失敗，每一層都 forward-fix 不 revert，直到綠燈穩住。

50 commits, 167 files, +16,763 / −2,725 lines (net +14,038). Backend coverage went 32 → 83 percent. 234 of ~660 audit findings closed. CI repaired through 8 targeted commits. Documentation grew by 7 new artefacts spanning developer onboarding (CONTRIB), production ops (RUNBOOK), 4 codemaps, and 5 wiki pages.

50 commits、167 檔案、+16,763 / −2,725 行（淨 +14,038）。後端覆蓋率 32 → 83%。約 660 個審查發現中關閉 234 個。CI 透過 8 顆目標明確的 commit 修復鏈。文件新增 7 份產出，含 onboarding（CONTRIB）、production ops（RUNBOOK）、4 份 codemaps、5 份 wiki 頁。

02

By the numbers

數字一覽

9h 5m window. Two authors (one human, one bot for snapshot baselines). 9 小時 5 分鐘窗口。兩位作者（一人類，一個 bot 負責 snapshot baselines）。
Insertions新增行
+16,763
across 167 files遍及 167 個檔案
Deletions刪除行
−2,725
net +14,038淨 +14,038
Commits
50
≈ 1 every 11 min約每 11 分鐘 1 顆
Files touched異動檔案
167
43 new · 124 modified43 新增 · 124 修改
Backend cov.後端覆蓋率
83%
+51 pp from 32%較 32% +51 pp
/optimize closed/optimize 關閉
234
~35% of ~660 findings約 660 件中的 35%
CRIT closedCRIT 關閉
~93%
≈ 26 / 28
CI repair commitsCI 修復 commits
8
4 distinct red causes4 個獨立紅燈根因
Docs grew +7 new artefacts文件 +7 份新產出 No CHANGELOG.md (project never had one)無 CHANGELOG.md（專案本就沒有） CLAUDE.md updated · +3 pitfall rows + 1 self-correctionCLAUDE.md 更新 · +3 條 pitfall + 1 條自我修正 Codemaps generated · 4 files / ~485 linesCodemaps 產生 · 4 檔案 / ~485 行 GitNexus stale (embeddings preserved)GitNexus 過時（embeddings 已保留） CI on HEAD · all-greenHEAD CI · 全綠
03

Four parallel work streams

四股平行工作流

Independently scoped, time-overlapping, none blocking the others. 各自獨立範圍、時間重疊、彼此不阻塞。

Drag to pan · Ctrl/Cmd-scroll to zoom · click ⛶ for full size 拖曳平移 · Ctrl/Cmd-滾輪縮放 · 點 ⛶ 開新視窗放大

Loading…
● Stream 1 · Coverage● 工作流 1 · 覆蓋率

Schema & SQL test push

Schema 與 SQL 測試補強

14commits顆 commits
~600+test cases測試案例
+51 ppcoverage覆蓋率

14 test(schemas) + test(unit) commits across commission, quotation, partner, task, application, client, note, communication, lead, enquiry, profile, staff, institution, eoi, tenant, automation, compliance, custom_page, mara, ocr, import, notification, push_subscription, time_log, survey, widget, checklist, invoice.

Plus 87 cases for sql_safe validators + 49 for sql_builder. Backend CI gate uplifted --cov-fail-under 64 → 80.

14 顆 test(schemas) + test(unit) commits，涵蓋 commission、quotation、partner、task、application、client、note、communication、lead、enquiry、profile、staff、institution、eoi、tenant、automation、compliance、custom_page、mara、ocr、import、notification、push_subscription、time_log、survey、widget、checklist、invoice。

另加 87 個 sql_safe validator 測試 + 49 個 sql_builder 測試。後端 CI 門檻 --cov-fail-under 64 → 80 提升。

● Stream 2 · /optimize● 工作流 2 · /optimize

20-worker frontend sweep

20-worker 前端大掃除

234findings closed發現關閉
14bucket commitsbucket commits
83files touched檔案異動

Wave 1 dispatched W01-W19 in a single message (19 parallel Agent calls), each owning a locked file bucket. W20 swept the shared SSOT files (src/ui/*, chartColors.js, i18n/{en,zh-TW}.json) in wave 2.

Closure rates: CRIT ~93%, HIGH ~61%, MED ~32%. Six wave-1 agents truncated mid-edit; six finalizers (W06b, W09b, W11b, W12b, W16b, W17b) recovered the diffs without redoing work — they only inspected, verified, and reported.

Wave 1 在單一訊息中派出 W01-W19（19 個並行 Agent 呼叫），每個 agent 擁有鎖定的檔案 bucket。W20 在 wave 2 sweep 共用 SSOT 檔案（src/ui/*、chartColors.js、i18n/{en,zh-TW}.json）。

關閉率：CRIT 約 93%、HIGH 約 61%、MED 約 32%。Wave 1 共 6 個 agent 中途截斷；6 個 finalizer（W06b、W09b、W11b、W12b、W16b、W17b）不重做工作，只負責檢查、驗證、補寫報告。

● Stream 3 · Docs● 工作流 3 · 文件

CONTRIB · RUNBOOK · codemaps · wiki

7docs added文件新增
~1,400lines行
4slash skillsslash skill

docs/CONTRIB.md (280) — onboarding + script reference. docs/RUNBOOK.md (253) — deploy/monitor/rollback. codemaps/{architecture,backend,frontend,data}.md (~485) — token-lean module maps. 5 .omc/wiki/*.md pages — session-log, debugging, pattern entries. 21 audit fix-reports + MASTER_FIX_REPORT.md.

docs/CONTRIB.md（280 行）— onboarding + 腳本參考。docs/RUNBOOK.md（253 行）— 部署/監控/回滾。codemaps/{architecture,backend,frontend,data}.md（約 485 行）— 精簡的模組地圖。5 篇 .omc/wiki/*.md — session-log、debugging、pattern。21 份審查修復報告 + MASTER_FIX_REPORT.md。

● Stream 4 · CI● 工作流 4 · CI

8-commit repair chain to all-green

8 顆 commit 修復鏈通往全綠

4distinct red causes獨立紅燈根因
3workflows touchedworkflow 異動
+dependabot

From bundle-budget over → ui-coverage portal mismatch → jest-matchers Symbol redefine → auth-mode mismatch → snapshot platform mismatch (linux ≠ darwin) → GitHub Actions bot-push loop guard. Each fix surgical and forward (no reverts). workflow_dispatch: added permanently for re-arming after baseline updates.

從 bundle-budget 超量 → ui-coverage portal 路徑不符 → jest-matchers Symbol 重定義 → 前後端 auth mode 不一致 → snapshot 平台不符（linux ≠ darwin）→ GitHub Actions bot-push 循環守衛。每一個修復都是精準 forward-fix（沒有 revert）。workflow_dispatch: 永久加入，方便 baseline 更新後重新觸發。

04

/optimize sweep · before / after

/optimize 大掃除 · 前 / 後

Specific deltas the 20-worker run produced. 20-worker run 產生的具體增量。
Before · 2026-05-05 22:00 前 · 2026-05-05 22:00
After · HEAD 5c2be5b4 後 · HEAD 5c2be5b4

Frontend SSOT

前端 SSOT

  • BsButton — only renders as <button>
  • BsCard — no auto-a11y when clickable
  • FormField — no aria-required, no role=alert
  • Tooltip — no useId/aria-describedby pairing
  • chartColors.js — no AGING_TOKENS, axis helper, or stage classes
  • ~660 open findings across ~80 pages
  • BsButton — 只能渲染為 <button>
  • BsCard — 可點擊時無自動 a11y
  • FormField — 無 aria-required、無 role=alert
  • Tooltip — 無 useId/aria-describedby 配對
  • chartColors.js — 沒有 AGING_TOKENS、axis helper 或 stage class
  • 約 660 個未處理發現，散佈於約 80 頁面

CI

CI

  • backend cov gate --cov-fail-under=64 while real cov ≥80%
  • no .github/dependabot.yml · supply-chain unmonitored
  • no workflow_dispatch on visual-regression
  • baseline-update on ubuntu-latest → linux PNGs (Mac Mini ignored)
  • FORCE_JAVASCRIPT_ACTIONS_TO_NODE24 (Node 24 not LTS)
  • 後端覆蓋率門檻 --cov-fail-under=64，實際覆蓋率已 ≥80%
  • 無 .github/dependabot.yml · supply-chain 無人盯
  • visual-regression 無 workflow_dispatch
  • baseline-update 跑在 ubuntu-latest → 產 linux PNGs（Mac Mini 忽略）
  • FORCE_JAVASCRIPT_ACTIONS_TO_NODE24（Node 24 尚未 LTS）

Frontend SSOT

前端 SSOT

  • BsButton — polymorphic as prop + forwardRef
  • BsCard — auto role/tabIndex/keyboard when onClick set
  • FormField — aria-required + role=alert on validation error
  • Tooltip — useId + aria-describedby anchored
  • chartColors — AGING_TOKENS, getAxisStyle, STAGE_BG_CLASS, EVENT_TYPE_TINT
  • 234 closed (~93% CRIT, ~61% HIGH, ~32% MED)
  • BsButton — 多型 as prop + forwardRef
  • BsCard — 設了 onClick 時自動 role/tabIndex/keyboard
  • FormField — 驗證錯誤時 aria-required + role=alert
  • Tooltip — useId + aria-describedby 綁定
  • chartColors — AGING_TOKENS、getAxisStyle、STAGE_BG_CLASS、EVENT_TYPE_TINT
  • 關閉 234 件（CRIT ~93%、HIGH ~61%、MED ~32%）

CI

CI

  • backend cov gate --cov-fail-under=80 · 5 pp safety margin
  • .github/dependabot.yml · weekly Mon 06:00 AEST
  • workflow_dispatch: permanent on visual-regression
  • baseline-update on Mac Mini self-hosted → darwin PNGs
  • Node24 force flag removed (re-add when LTS lands)
  • 後端覆蓋率門檻 --cov-fail-under=80 · 5 pp 安全餘裕
  • .github/dependabot.yml · 每週一 06:00 AEST
  • visual-regression 永久加上 workflow_dispatch:
  • baseline-update 改跑 Mac Mini self-hosted → darwin PNGs
  • Node24 force flag 移除（LTS 上線後再加回）
Before · /optimize ESLint & tests 前 · /optimize ESLint 與測試
After · /optimize ESLint & tests 後 · /optimize ESLint 與測試
  • Many destructive ops without confirm (raw confirm() dialogs)
  • Local formatLabel redefinitions across pages
  • Raw Tailwind palette (bg-gray-100/80, bg-white/10) on 30+ surfaces
  • <button> without explicit type= in dozens of places
  • Vanity sparklines on dashboard widgets with no dataset
  • Gradient KPI chips, glassmorphism survey hero
  • 許多破壞性操作直接用原生 confirm() 對話框
  • 各頁面散落 formatLabel 的 local 重定義
  • 30+ 表面用了 Tailwind 原始調色盤（bg-gray-100/80、bg-white/10）
  • 數十處 <button> 沒有顯式 type=
  • 儀表板 widget 有無資料的虛榮 sparkline
  • 漸層 KPI 膠囊、glassmorphism 問卷 hero
  • HoldToConfirmButton wraps merge/delete (1.5s safety gate)
  • One canonical formatLabel() from src/lib/labelUtils.js
  • Surfaces use semantic tokens (bsmart-surface-input, fill-tertiary)
  • type= required everywhere · ESLint rule enforced
  • Vanity widgets removed; legitimate sparklines kept with backing data
  • Neutral KPI cards · purple/glass hero replaced with token-aligned surfaces
  • HoldToConfirmButton 包覆 merge/delete（1.5 秒安全閘門）
  • 唯一正規 formatLabel() 來自 src/lib/labelUtils.js
  • 表面改用語意 token（bsmart-surface-input、fill-tertiary）
  • 各處 type= 強制 · ESLint rule 守住
  • 虛榮 widget 移除；保留有資料支撐的合法 sparkline
  • 中性 KPI 卡 · 紫色/glass hero 換為 token-aligned 表面
05

CI repair chain · 8 commits, 4 root causes

CI 修復鏈 · 8 commits、4 個根因

Each row is one commit; each colored dot is a fix that exposed the next layer. 每列一個 commit；每個彩色圓點是一個修復，揭露下一層問題。
04717a6c push triggered initial CI push 觸發首輪 CI Reds: Frontend CI · Visual Regression · (Cloudflare Pages OK) 紅燈：Frontend CI · Visual Regression ·（Cloudflare Pages 通過）
ea7077e3 ci(frontend): bump CSS budget 280 → 295KB ci(frontend)：CSS budget 280 → 295KB Cause #1: /optimize tokens added 2.7 KB · maxMainCssBytes 280000 → 295000 根因 #1：/optimize 新增 token 多 2.7 KB · maxMainCssBytes 280000 → 295000
c68fe026 ci(e2e): USE_SUPABASE_AUTH=false + ENABLE_CSRF_PROTECTION=false ci(e2e)：USE_SUPABASE_AUTH=false + ENABLE_CSRF_PROTECTION=false Cause #2 (auth): /api/auth/register 403 · CSRF token missing 根因 #2（auth）：/api/auth/register 403 · CSRF token 缺失
f6057020 ci(e2e): testIgnore **/__tests__/** in playwright.config ci(e2e)：playwright.config 加 testIgnore **/__tests__/** Cause #3: Playwright loaded e2e/helpers/__tests__/cleanup.test.js → vitest pulled @vitest/expect → Symbol($$jest-matchers-object) redefine TypeError 根因 #3：Playwright 載入 e2e/helpers/__tests__/cleanup.test.js → vitest 拉入 @vitest/expect → Symbol($$jest-matchers-object) 重定義 TypeError
cb3a9e99 ci(audit): whitelist 'portal' in ui-coverage drift check ci(audit)：將 'portal' 加入 ui-coverage drift 白名單 Side-cause: ClientPortalPage hits /portal/verify-access but backend mounts /api/client-portal — pre-existing dead route, was masked by bundle-budget 側因：ClientPortalPage 呼叫 /portal/verify-access，但後端掛載在 /api/client-portal——既有死路由，先前被 bundle-budget 失敗遮蔽
53ca6de9 · 277bc803 ci(e2e): VITE_DEV_AUTH_BYPASS=true + VITE_USE_SUPABASE_AUTH=false ci(e2e)：VITE_DEV_AUTH_BYPASS=true + VITE_USE_SUPABASE_AUTH=false Cause #4 (auth-mode mismatch): useAuth.jsx validateAuthMode() compared frontend default "supabase" vs backend "legacy" → setAuthError → /login redirect on every page 根因 #4（auth-mode 不一致）：useAuth.jsx 的 validateAuthMode() 比對前端預設 "supabase" 與後端 "legacy" → setAuthError → 每頁都被導去 /login
d9ad1638 ci(visual): migrate baseline-update to Mac Mini self-hosted ci(visual)：baseline-update 遷移到 Mac Mini self-hosted Cause #5 (platform mismatch): baseline-update on ubuntu-latest emitted *chromium-linux.png; visual-regression on Mac Mini compared *chromium-darwin.png · linux PNGs ignored 根因 #5（平台不符）：baseline-update 跑 ubuntu-latest 產 *chromium-linux.png；visual-regression 跑 Mac Mini 比對 *chromium-darwin.png · linux PNG 被忽略
da01cce9 chore: bot pushed fresh chromium-darwin baselines chore：bot 推送新的 chromium-darwin baselines Note: github-actions[bot] commit · GITHUB_TOKEN actor doesn't trigger downstream workflows (loop guard) 備註：github-actions[bot] commit · GITHUB_TOKEN 作者不會觸發 downstream workflow（防迴圈守衛）
5c2be5b4 ci(visual): + workflow_dispatch & auto-arm ci(visual)：加 workflow_dispatch 與自動 arm Result: visual-regression run 25394593083 → completed/success 結果：visual-regression run 25394593083 → completed/success
06

File map

檔案地圖

167 files changed · 43 new · 124 modified · 0 deleted. 167 檔案異動 · 43 新增 · 124 修改 · 0 刪除。
● 43 new files (codemaps, docs, audit reports, dependabot, baselines) ● 43 個新增檔案（codemaps、docs、audit reports、dependabot、baselines） 
[ docs · canonical onboarding/ops ]
+ docs/CONTRIB.md                                       280 lines
+ docs/RUNBOOK.md                                       253 lines

[ codemaps · token-lean structure maps ]
+ codemaps/architecture.md                              ~95 lines
+ codemaps/backend.md                                   ~140 lines
+ codemaps/frontend.md                                  ~140 lines
+ codemaps/data.md                                      ~110 lines

[ .reports · diff baseline ]
+ .reports/codemap-diff.txt                             39 lines

[ .omc/wiki · session-local knowledge ]
+ .omc/wiki/index.md                                    catalog
+ .omc/wiki/optimize-campaign-2026-05-05.md             session-log
+ .omc/wiki/parallel-agent-finalizer-pattern.md         pattern
+ .omc/wiki/vitest-4-gotchas-2026-05-06.md              debugging
+ .omc/wiki/gitnexus-embedding-failure-2026-05-06.md    debugging

[ .audit-reports · /optimize fix reports ]
+ .audit-reports/ui-2026-05-04/AUDIT_SUMMARY.md         
+ .audit-reports/ui-2026-05-04/OPTIMIZE_TEAM_PROMPT.md  
+ .audit-reports/ui-2026-05-04/worker-{01..15}-*.md     15 audit reports
+ .audit-reports/ui-2026-05-04/optimize-fixes/MASTER_FIX_REPORT.md
+ .audit-reports/ui-2026-05-04/optimize-fixes/worker-W{01..20}-fixes.md

[ ci · supply-chain monitoring ]
+ .github/dependabot.yml                                npm + pip + github-actions

[ visual baselines · 7 chromium-darwin PNGs ]
+ webapp/frontend/e2e/visual-regression.spec.js-snapshots/*.png
+ webapp/frontend/e2e/customizable-dashboard.spec.js-snapshots/*.png
◐ Modified · top files by churn ◐ 已修改 · churn 最多的檔案 
M  webapp/frontend/src/pages/TasksPage.jsx                  +736 · Apple→Bs primitive migration + a11y
M  webapp/frontend/src/pages/SurveyResponsePage.jsx         +384 · gradient hero removed, NPS a11y
M  webapp/frontend/src/pages/EnquiryDetailPage.jsx          +279 · ENQUIRY_PRIORITY_BADGE map
M  webapp/frontend/src/pages/ReportsPage.jsx                +251 · chart hex → SSOT, formatLabel
M  webapp/frontend/src/pages/SecurityDashboardPage.jsx      +190 · polling pause, lucide icons
M  webapp/frontend/src/pages/SurveysPage.jsx                +187 · FormField SSOT migration
M  webapp/frontend/src/pages/TenantSettingsPage.jsx         +174 · reverted by W12b (test coupling)
M  CLAUDE.md                                                +3 pitfall rows · 1 self-correction
M  .github/workflows/webapp-visual-regression.yml           env + workflow_dispatch (4 commits)
M  .github/workflows/webapp-critical-smoke.yml              env aligned (3 commits)
M  .github/workflows/webapp-backend-ci.yml                  cov 64→80, FORCE_JS removed
M  .github/workflows/visual-baseline-update.yml             ubuntu → Mac Mini self-hosted
M  webapp/verify_frontend_ui_coverage.mjs                   +'portal' to alias allowlist
M  webapp/frontend/scripts/bundle-budget.json               280→295 KB CSS
M  webapp/frontend/playwright.config.js                     testIgnore __tests__/**

… plus ~108 more page-level and schema-test files (full count = 124 modified)
● 0 deleted files ● 0 個刪除檔案 
No deletions. /optimize was strictly additive (extend SSOT primitives, add tokens, add tests). All "remove" actions were inline edits, not file deletions.
無刪除。/optimize 屬嚴格 additive（擴展 SSOT 元件、新增 token、新增測試）。所有「移除」動作皆為 inline edit，非檔案刪除。
07

Test coverage delta

測試覆蓋率增量

Backend gate enforcement caught up with reality. 後端 CI 門檻終於追上實際覆蓋率。

Backend coverage

後端覆蓋率

Before前
32%
After後
83%
CI gateCI 門檻
80%

Source: docs/MASTER_IMPROVEMENT_PLAN.md · gate change in 9b5eac3e 來源：docs/MASTER_IMPROVEMENT_PLAN.md · 門檻變更於 9b5eac3e

Test file inventory

測試檔清單

  • 358   frontend Vitest test files 前端 Vitest 測試檔 — src/**/__tests__/*.test.*
  • 250   backend pytest test files 後端 pytest 測試檔 — webapp/tests/test_*.py
  • ~600+   new test cases this window 本窗口新增測試案例 — spread across 14 commits分散於 14 個 commit
  • INFRA   vitest 4 poolOptions deprecation vitest 4 poolOptions deprecation — targeted runs work; full-tree run quirk documentedtargeted run 可用；full-tree run 怪癖已留檔
08

Good · Bad · Ugly · Questions

好 · 壞 · 醜 · 疑問

Honest review across the whole 9-hour window. 9 小時窗口的誠實審查。

Good

好

  • File-locked parallel work. 20 agents, no collisions. Pattern documented in .omc/wiki/parallel-agent-finalizer-pattern.md.
  • ADD-ONLY shared SSOT. W20 extended BsButton.as, BsCard auto-a11y, FormField aria, Tooltip useId, chartColors tokens — all backward-compat, no public API breaks.
  • CI repair fix-forward, not revert. 8 surgical commits, each diagnosed forward. No reverts on the main branch.
  • Self-correction is on record. aaaaf0b7 corrects f869d277 (Vitest pitfall pointed to non-existent vitest.config.js). The diff stays in history; future-you knows.
  • Permanent CI improvements. workflow_dispatch: on visual-regression, dependabot.yml, baseline-update on Mac Mini — each removes a future failure-mode.
  • Documentation grew with code. Not "we'll write docs later" — CONTRIB, RUNBOOK, codemaps, wiki shipped in the same window.
  • 檔案鎖定的平行協作。20 個 agent，零衝突。模式已寫入 .omc/wiki/parallel-agent-finalizer-pattern.md。
  • 共用 SSOT 純加法。W20 擴充 BsButton.as、BsCard auto-a11y、FormField aria、Tooltip useId、chartColors tokens——全部向後相容，沒有 public API 破壞。
  • CI 修復一律 forward 不 revert。8 顆精準 commit，每一顆都向前診斷。main branch 沒有任何 revert。
  • 自我修正留底。aaaaf0b7 修正 f869d277（先前 vitest pitfall 寫錯了不存在的 vitest.config.js）。歷史在；未來的你看得到。
  • 永久性 CI 改進。visual-regression 加 workflow_dispatch:、新增 dependabot.yml、baseline-update 改 Mac Mini——每一項都消滅一種未來故障模式。
  • 文件與程式同步成長。不是「之後再寫」——CONTRIB、RUNBOOK、codemaps、wiki 都在同一窗口落地。

Bad

壞

  • portal whitelist hides a real bug. ClientPortalPage.jsx:48 calls /portal/verify-access but no backend route exists. Audit allowlist unblocked CI but the runtime page is broken.
  • TenantSettingsPage reverted whole. W12b ran git checkout HEAD -- TenantSettingsPage.jsx. F-11/F-12/F-13/F-24/F-25 deferred. Tests assert hardcoded zh-TW strings — atomic source+test PR needed before next attempt.
  • W06 Finance bucket only got 1/4 files. InvoicesPage edited; InvoiceDetailPage / BillingPage / ReconciliationPage byte-identical to HEAD. Listed as P1 follow-up in MASTER_FIX_REPORT.
  • StudyTourDetailPage "full" revert. W16b reverted formatLabel(s) to s at line 368 to keep tests passing — visual label inconsistency lives on until a coordinated test+source fix.
  • portal 白名單藏住真 bug。ClientPortalPage.jsx:48 呼叫 /portal/verify-access 但後端沒這條路由。Audit 白名單放行 CI，但實際頁面壞掉。
  • TenantSettingsPage 整檔還原。W12b 跑了 git checkout HEAD -- TenantSettingsPage.jsx。F-11/F-12/F-13/F-24/F-25 全部 defer。測試 assert 硬編 zh-TW 字串——下次需要 source+test 原子 PR。
  • W06 Finance bucket 只完成 1/4 檔案。InvoicesPage 已改；InvoiceDetailPage / BillingPage / ReconciliationPage 跟 HEAD byte-identical。MASTER_FIX_REPORT 列為 P1 follow-up。
  • StudyTourDetailPage "full" 還原。W16b 為了測試通過，把 line 368 的 formatLabel(s) 退回 s——文字不一致延續，直到 test+source 一併修復。

Ugly

醜

  • Vitest 4 test.poolOptions deprecation. Tests still run, only emits a warning. But the warning made 19 worker agents (and me) misdiagnose for ~90 min. P1 1-line config migration tracked.
  • RTK rewrite swallows vitest output. rtk vitest … reports numTotalTestSuites: 0 regardless of result. Diagnostic landmine. Workaround: rtk proxy npx vitest run ….
  • Mac Mini single-runner contention. Visual-regression queues for ~30 min during heavy bursts. Acceptable for a 2-founder team but will pinch as test count grows.
  • 21 stale chromium-linux.png baselines on disk. Bot-generated by the first ubuntu run; ignored by Mac Mini darwin runs but adds ~600 KB of dead bytes.
  • 4,455 ESLint warnings repo-wide. Mostly no-unused-vars JSX false-positives because react/jsx-uses-vars isn't enabled. Adding the rule would drop warnings ~70%.
  • FORCE_JAVASCRIPT_ACTIONS_TO_NODE24 removed without context. Whoever added it had a reason; no commit history explained why. Removal was correct but the original intent is lost.
  • Vitest 4 test.poolOptions deprecation。測試還是跑得了，只噴一句警告。但這警告讓 19 個 worker agent（和我）誤判約 90 分鐘。P1 1-行 config 遷移已追蹤。
  • RTK rewrite 吞掉 vitest 輸出。rtk vitest … 不論真實結果都回報 numTotalTestSuites: 0。診斷地雷。Workaround：rtk proxy npx vitest run …。
  • Mac Mini 單 runner 爭用。大量推送時 visual-regression 要排隊約 30 分鐘。兩人團隊還能接受，但測試規模擴大就會卡。
  • 磁碟上 21 張過期的 chromium-linux.png baseline。第一次 ubuntu run 由 bot 產生；Mac Mini darwin run 忽略，但占約 600 KB 死字節。
  • repo 上 4,455 個 ESLint warnings。多數是 no-unused-vars JSX 誤報，因為 react/jsx-uses-vars 沒啟用。啟用後 warnings 大概砍 70%。
  • FORCE_JAVASCRIPT_ACTIONS_TO_NODE24 移除無前文。當初加的人有理由，commit history 沒解釋。移除動作正確但原始意圖丟失。

Questions

疑問

  • Should /portal/verify-access point at /api/client-portal/verify-access (also doesn't exist) or register the backend endpoint? Spec-007 phase 2 ambiguity.
  • Is the Mac Mini visual-baseline-update workflow safe to schedule on cron, or must it stay manual-dispatch?
  • Will the w20 i18n namespace ever consolidate into the existing namespaces, or stay as a quarantine bucket?
  • Should backend cov gate move to 85% next sprint? Real coverage at 83% has 5 pp safety margin; tightening to 82 would protect more aggressively.
  • /portal/verify-access 該指向 /api/client-portal/verify-access（也不存在）還是註冊後端 endpoint？Spec-007 phase 2 模糊地帶。
  • Mac Mini 上的 visual-baseline-update workflow 適合 cron 排程嗎？還是只能保留手動 dispatch？
  • w20 i18n namespace 之後會合併到既有 namespace，還是維持隔離 bucket？
  • 下個 sprint 後端覆蓋率門檻要不要拉到 85%？實際 83% 有 5 pp 安全餘裕；拉到 82 保護更積極。
09

Decision log

決策紀錄

Significant design choices · confidence sourced from in-session conversation. 重要設計選擇 · 信心度源自當次 session 對話。

20-worker parallel dispatch with locked file buckets High

20-worker 平行派遣 + 檔案鎖定 buckets High

Decision: Single message with 19 parallel Agent calls + W20 sweep + finalizers.

Rationale: ~660 audit findings across ~80 pages would take ~12 hours sequentially; parallel dispatch reduced wall-clock to ~1.5 hours by exploiting bucket independence. Locking files at agent-spawn time prevented cross-agent collisions without runtime coordination.

Alternative rejected: Sequential single-agent — too slow. Mob-program style (multiple agents on the same files) — high collision risk.

決策：單一訊息派出 19 個並行 Agent 呼叫 + W20 sweep + finalizers。

理由：約 660 個審查發現跨約 80 個頁面，序列做要 12 小時；平行 dispatch 利用 bucket 獨立性把時間壓到 1.5 小時。spawn 時鎖檔避免 cross-agent 衝突，免除執行期協調。

否決方案：序列單 agent——太慢。Mob-program 多 agent 同檔——衝突風險高。

Wave-2 finalizers don't redo work — only inspect+verify+report High

Wave-2 finalizers 不重做——只 inspect+verify+report High

Decision: When wave-1 agents truncated mid-edit (6 of 19 ≈ 32%), spawn lightweight finalizers (W06b, W09b, W11b, W12b, W16b, W17b) that read git diff + run ESLint/Vitest + write the missing fix-report.

Rationale: Re-running the same work would risk re-truncation in the same place. The diff is already on disk; the missing artefact is the report. Surgical reverts allowed only for parse-error rescue.

Result: Caught 2 real bugs (W17 had deleted an import that JSX still used + dangling ref) and 2 over-reaches (W12 + W16 reverted to keep tests green). Zero regressions.

決策：Wave-1 agent 中途截斷時（19 個中 6 個約 32%），派輕量 finalizer（W06b/W09b/W11b/W12b/W16b/W17b）讀 git diff + 跑 ESLint/Vitest + 補寫 fix-report。

理由：重做同樣工作有相同截斷風險。Diff 已落地；缺的是 report。只允許用最小 revert 救 parse error。

結果：抓到 2 個真 bug（W17 砍了 JSX 還在用的 import + dangling ref），2 個過度修改（W12 + W16 為了測試 revert）。零回歸。

Fix CI forward, never revert main High

CI 一律 forward-fix，不在 main 做 revert High

Decision: 8 commits each addressing one root cause; no git revert on main.

Rationale: Reverting would un-deploy real /optimize improvements. Each CI red was a different layer (bundle / auth / Symbol redefine / auth-mode / platform mismatch / loop guard) that needed its own fix anyway.

Alternative rejected: Revert /optimize commits to make CI green, then re-apply piecemeal. Would have erased ~234 closures + 14 atomic commits + thousands of lines of work.

決策：8 顆 commit 各自處理一個根因；main 上絕不 git revert。

理由：Revert 會把真實的 /optimize 改進收回。每次 CI 紅燈是不同層的問題（bundle / auth / Symbol redefine / auth-mode / 平台不符 / 防迴圈），本來就要各別修。

否決方案：revert /optimize 把 CI 變綠然後逐塊重做——會抹去約 234 個關閉 + 14 顆原子 commit + 數千行成果。

Empty-commit re-trigger pattern doesn't work High

empty-commit 重觸發模式行不通 High

Decision: Use workflow_dispatch: permanently; supplement with a path-touched commit when no dispatch is configured.

Rationale: path-glob filter looks at the diff, not just the commit. Empty diff → no path matches → workflow skipped. Touching the YAML itself (in the path-glob) re-arms it. Adding workflow_dispatch: is the permanent fix.

Captured in: commit message 5c2be5b4 + this review.

決策：永久使用 workflow_dispatch:；沒設定 dispatch 時用 path-touched commit 當補丁。

理由：path-glob filter 看 diff，不是看 commit 本身。Empty diff → 沒有 path match → workflow 跳過。touch yml 本身（在 path-glob 裡）才會重新 arm。永久修法是加 workflow_dispatch:。

紀錄於：5c2be5b4 的 commit message + 本次審查。

Editorial palette over the standard architecture template Medium

採用 Editorial 調色盤而非標準架構模板 Medium

Decision: Plus Jakarta Sans + Bricolage Grotesque + Azeret Mono · cream/crimson/forest/gold over the terracotta+sage of the architecture template.

Rationale (inferred): 10 prior diagrams in ~/.agent/diagrams/ means the swap test demands distinctness — different fonts and palette every time. Editorial fits a "9-hour sprint review" framing better than technical/blueprint.

決策：用 Plus Jakarta Sans + Bricolage Grotesque + Azeret Mono · cream/crimson/forest/gold，跳過架構模板的 terracotta+sage。

理由（推測）：~/.agent/diagrams/ 已有 10 份先前的圖，swap-test 要求每次都不同——換字型換色票。Editorial 比 technical/blueprint 更適合「9 小時 sprint 回顧」這個敘事。

Keep chromium-linux.png baselines on disk after platform migration Medium

平台遷移後保留 chromium-linux.png baseline Medium

Decision (inferred): Don't delete the 7 ubuntu-emitted baselines even though Mac Mini ignores them.

Rationale (inferred): Playwright auto-suffixes -{platform}.png, so Mac Mini darwin runs read only *-darwin.png. Linux variants are dead weight (~600 KB) but harmless. Cleanup deferred until someone runs visual-regression on Linux too.

決策（推測）：不刪 7 張 ubuntu run 產的 baseline，即使 Mac Mini 忽略。

理由（推測）：Playwright 自動加 -{platform}.png 後綴，Mac Mini darwin run 只讀 *-darwin.png。Linux 變體是死重（約 600 KB），但無害。等哪天 Linux 也要跑 visual-regression 再清。

FORCE_JAVASCRIPT_ACTIONS_TO_NODE24 removal Low

移除 FORCE_JAVASCRIPT_ACTIONS_TO_NODE24 Low

Decision: Removed the env block from webapp-backend-ci.yml.

Rationale (not recoverable): No commit history explains why it was added. Probably an experimental flag pinning Node 24 runtime on actions, but Node 24 hasn't reached LTS, so the flag silently no-ops. Document the reasoning before removing similar flags in the future.

決策：移除 webapp-backend-ci.yml 的 env block。

理由（無從追溯）：commit history 沒解釋為何加。可能是 actions 上 pin Node 24 runtime 的實驗 flag，但 Node 24 尚未 LTS，因此 flag 默默無效。未來移除類似 flag 前，請先寫下原因。

10

Re-entry context · note from present-you to future-you

重返脈絡 · 現在的你給未來的你

Read this before the next /optimize-style sweep. 下次做 /optimize 規模掃除前先讀這段。
● Open this when you come back ● 重返時請打開

Key invariants

關鍵不變量

  • Frontend VITE_USE_SUPABASE_AUTH must match backend USE_SUPABASE_AUTH; useAuth.jsx validateAuthMode() hard-blocks otherwise.
  • Backend cov gate is now 80% — write tests for new routers or CI rejects.
  • All new <button> need type=; ESLint enforces.
  • i18n keys: en + zh-TW must stay parity (node check-keys.cjs).
  • Status text: formatLabel() from src/lib/labelUtils.js only — no local redefines.
  • 前端 VITE_USE_SUPABASE_AUTH 必須與後端 USE_SUPABASE_AUTH 一致；否則 useAuth.jsx validateAuthMode() 會硬擋。
  • 後端 cov 門檻已是 80%——新 router 要寫測試，不然 CI 拒絕。
  • 新 <button> 都要有 type=；ESLint 強制。
  • i18n keys：en 與 zh-TW 必須對齊（node check-keys.cjs）。
  • 狀態文字：formatLabel() 必從 src/lib/labelUtils.js——禁止 local 重定義。

Non-obvious coupling

非顯式耦合

  • visual-baseline-update.yml must run on the same runner platform as webapp-visual-regression.yml. Both = Mac Mini self-hosted. Don't migrate one without the other.
  • e2e/helpers/__tests__/cleanup.test.js imports vitest; Playwright must testIgnore: ["**/__tests__/**"] or @vitest/expect redefines $$jest-matchers-object.
  • github-actions[bot] commits with GITHUB_TOKEN as actor do NOT trigger downstream workflows. Re-arm via workflow_dispatch or yml-touch commit.
  • TenantSettingsPage tests assert hardcoded zh-TW literals; touching i18n on that page requires atomic source+test PR.
  • visual-baseline-update.yml 與 webapp-visual-regression.yml 必須跑相同 runner 平台。兩者都 = Mac Mini self-hosted。不要單獨遷移其中一個。
  • e2e/helpers/__tests__/cleanup.test.js import vitest；Playwright 必須加 testIgnore: ["**/__tests__/**"]，否則 @vitest/expect 會重定義 $$jest-matchers-object。
  • github-actions[bot] 用 GITHUB_TOKEN 推的 commit 不會觸發 downstream workflow。要靠 workflow_dispatch 或 touch yml commit 重新觸發。
  • TenantSettingsPage 的測試 assert 硬編 zh-TW 字面值；改該頁 i18n 必須做 source+test 的原子 PR。

Gotchas (would surprise in 2 weeks)

陷阱（兩週後會嚇到你）

  • Vitest 4 prints "test.poolOptions deprecated" warning but tests still run. Don't conclude "tests broken".
  • rtk vitest … silently reports numTotalTestSuites: 0. Always use rtk proxy npx vitest run ….
  • Empty-commit on main does NOT trigger path-glob workflows. Diff must touch a path in the trigger filter.
  • Mac Mini PostgreSQL (homebrew) has no default DB — admin commands need -d postgres.
  • Python 3.14 dev / 3.9 CI mismatch — backend modules using X | Y need from __future__ import annotations.
  • ClientPortalPage /portal/verify-access is dead code but whitelisted in audit. Don't remove the alias before fixing the route.
  • Vitest 4 印 "test.poolOptions deprecated" 警告但測試仍跑得了。不要妄下「tests broken」結論。
  • rtk vitest … 默默回報 numTotalTestSuites: 0。永遠用 rtk proxy npx vitest run …。
  • main 上 empty-commit 不會觸發 path-glob workflow。Diff 必須碰到 trigger filter 中的路徑。
  • Mac Mini PostgreSQL（homebrew）沒有預設 DB——admin 指令要加 -d postgres。
  • Python 3.14 dev / 3.9 CI 不對齊——後端用 X | Y 的模組需要 from __future__ import annotations。
  • ClientPortalPage 的 /portal/verify-access 是死碼但 audit 白名單放行。修好路由前不要移除 alias。

Don't forget

別忘了

  • Vitest vite.config.js migration: lift test.poolOptions to top-level poolOptions (1-line P1 fix).
  • 9 dependabot PRs are queued — review and merge weekly cadence.
  • TenantSettings F-11/F-12/F-13/F-24/F-25 deferred — atomic source+test PR.
  • W06 finance bucket: InvoiceDetail/Billing/Reconciliation pages still need the W06 audit run.
  • Add react/jsx-uses-vars ESLint rule to drop ~70% of warnings.
  • Consider consolidating w20 i18n namespace into existing namespaces.
  • Run npx gitnexus analyze --embeddings when Mac Mini LM Studio is up.
  • Vitest vite.config.js 遷移：把 test.poolOptions 提到 top-level poolOptions（P1 一行修復）。
  • 9 個 dependabot PR 排隊中——按週節奏 review 與合併。
  • TenantSettings F-11/F-12/F-13/F-24/F-25 都被 defer——做 source+test 原子 PR。
  • W06 finance bucket：InvoiceDetail/Billing/Reconciliation 還沒做 W06 審查。
  • 啟用 react/jsx-uses-vars ESLint rule，砍掉約 70% warnings。
  • 考慮把 w20 i18n namespace 合併到既有 namespace。
  • Mac Mini LM Studio 上線時跑 npx gitnexus analyze --embeddings。