FR-047 功能 SPEC 量產 — Lane A 續跑交接（中繼 handoff）

這套手冊給誰、解決什麼：docs/specs/v1.8.0/ 是給新手全端工程師的功能 SPEC 手冊——痛點是「查一個功能會查到天荒地老」。解法：一條 FE route = 一份 13 節 spec，markdown 是唯一 living truth（HTML 站 / docx 都是 build 產物）。

核心紀律一句話：spec 是 living truth，每個事實從 code / DB 掃出來，不憑記憶、不抄舊文件、不信探勘 agent 摘要的 schema 名。真相來源唯一：

• 表結構 / schema 名 / 欄位 → scripts/deliverables/out/db_schema.json
• endpoint 存在性 / path → scripts/deliverables/out/routes.json
• request / response 欄位 → marshmallow serializer + service 組裝碼（開檔逐條對）
• FE UI / 條件邏輯 → FE repo 實掃（~/Projects/Billows/Audit-Manager/compliance-manager-fe/）

本棒在大圖的位置：整個量產分 3 wave、9 群、47 條目。本棒完成「專案管理群」（Wave 1 第一群）。平行有其他 session 在跑別的群（#5 跑稽核執行群 = Lane B）——所以 tracker 是多 session 共寫，改前必重讀。

本棒要續的 Lane 順序（user 指定，全屬 Lane A 連續作業）：

• ② 合規框架與 SSP 群（compliance-framework/）：先 _overview，再 6 頁
• ③ 問卷群（survey/）：_overview + 3 頁
• ④ 報表與儀表板群（reporting/）：_overview + 4 頁（analysis 🔍 先驗存廢）
• ⑤ 認證群（auth/）：_overview + 登入（含 MFA OTP）+ 忘記/重設密碼

1. 🔒 先懂需求硬 gate：本檔「🧭 原始需求」+ mass-production-prompt.md（冷接自檢 3 問要答得出來）
2. 🔒 writing-feature-specs skill 全文（8 步流程 + 13 節模板 references/page-spec-template.md + 圖形化慣例）
3. 範本：docs/specs/v1.8.0/project-management/project-planning.md（pilot）+ _overview.md；本棒 project-list.md（Sonnet 合格樣貌）、project-create.md（Opus + BE bootstrap 時序圖法）
4. tracker：docs/features/FR-047-2607-feature-spec-handbook/tracker.md（認領頁面 / 看誰在寫什麼）
5. 本檔 §2 教訓（血淚，務必讀——subagent 委派會 stall、schema drift、DB 連法）

冷接自檢 4 問（答不出回去讀）：

1. spec 的事實憑什麼可信？（答：三來源 dump + 開檔，不信 agent 摘要）
2. 為什麼不能派 subagent「寫完整頁 spec」交回就好？（答：見 §2.1，它們會 stall；只能派研究、md 自己寫）
3. schema 名寫 grc.audit_rounds 對不對？（答：錯，真相是 compliance.project_audit_rounds；一律查 db_schema.json）
4. 改 tracker 前要做什麼？（答：重讀，多 session 共寫）

專案管理群 docs/specs/v1.8.0/project-management/ 7 頁全數 ✅（+ _overview 早已完成）：

🔍 已解決：project-dashboard 驗 live（ui_routes.enable=1，/project/dashboard 全域落地頁）保留；project-task-setup 驗死（FE 0 個 nav 進入點，功能 FR-038 併入規劃頁任務面板）→ tracker 除名。

每頁：13 節模板 + 3~5 張 .dot（assets/ 下，前綴 pl-/pc-/po-/pal-/ps-/pd-）。全部 build ✅ / 敏感資訊 grep 0 / 「GRC 系統」0。§5 實機截圖一律留佔位 callout（截圖另有專責 session，STG 亮色模式）。

§2.1 ⚠️ subagent 委派「寫完整頁 spec」會 STALL — 不要這樣派

本棒派了 3 個 Sonnet subagent 各寫一頁 spec，結果全部沒寫出 md 檔：它們把工作再分包給 research 孫 agent，然後idle 等孫 agent、不自己寫 md。孫 agent 的研究產出極好（開檔驗證、file:line、schema 對 dump），但 parent 沒落地。

• 正確模式：subagent 只派研究（用 Explore 或 general-purpose 明令「只回事實 manifest，不寫檔」），md + dot 由主導 session 自己寫。或直接自寫全部。
• 本棒後來救回 ap-list agent 已寫進 repo 的 4 張 dot（品質好、error code 正確），settings/dashboard 靠孫 agent 的研究報告自寫。
• 若仍要派寫檔：prompt 必加「禁止再 spawn subagent；自己 grep、自己 Write md 到指定路徑」，並在交回後自己 verify schema/endpoint + build 才 commit。

§2.2 schema drift — 一律查 db_schema.json

agent 摘要常寫錯 schema 前綴。本棒抓到的錯：grc.audit_rounds→實際 compliance.project_audit_rounds；oscal.module_frames→compliance.module_frames；cloud_integration.drive_folder_mappings→public.drive_folder_mappings；auth.users→public.users；jedi_oscal.*/jedi_flow.*→oscal.*/compliance.*；public.workflow_executions→compliance.workflow_executions。view（vw_*）不在 dump（dump 只收 table）→ 去 scripts/sql/view/ 找定義，spec 標「(VIEW)」。

§2.3 error code 開檔驗（別抄 agent）

本棒抓到 agent 把 manager 守門寫成 GRC_403001，實際 GRC_NOT_MANAGER = GRC_403002（GRC_403001 是 GRC_NOT_AUDITOR）。error code 在 common/code/grc_error_code.py，grep 確認。

§2.4 DB 連法（.env source 會失敗）

.env 的 DB_SECRET 是 JSON，source .env 帶不進來。用 python regex 抓密碼：

PW=$(python3 -c "import re
for l in open('.env'):
    if l.startswith('DB_SECRET='):
        print(re.search(r'\"rds_master_password\"\s*:\s*\"([^\"]+)\"', l).group(1)); break")
PGPASSWORD=\"$PW\" psql -h 192.168.50.188 -p 25432 -U cmmgr -d guidant_ai_dev -tA -c \"SELECT ...\"

public.ui_routes 欄位是 name / url / enable（不是 path）；驗 route live 用 enable=1。

§2.5 build 有時被別 session 的半成品擋

render_html.py 遇到缺 dot 會 sys.exit 硬停。曾被 session #3 的 audit-execution/audit-review.md（缺 ar-ui-layout.dot）擋（現已修）。若再遇：暫時把該壞 md 搬到 scratchpad → build 驗自己的頁 → 搬回。別動別人的檔本身。

§2.6 tracker 多 session 共寫

#3/#4/#5/#6 都在改 tracker。每次改前 Read 對應段（Edit 會因 stale 失敗）。只改自己那幾列 + 統計 + Session 紀錄，別動別人的列。

§2.7 FR-038 legacy 端點 drift（寫輪次 / 稽核相關頁會遇到）

FE api.js 有 GRC_CLOSE_ROUND/GRC_LAUNCH_AUDIT 組成 /grc/project/:pid/ap/:apUid/...，但這些 path 不在現行 routes.json——現行輪次生命週期在 /audit-round/{roundUid}/...。寫到相關頁在 §12 flag，別當 live endpoint。

1. tracker 認領（標 🚧，改前重讀）
2. 該群 _overview.md 不存在先寫（頁面地圖 / 共用狀態機 / 角色基調 / 核心資料模型；範本 = project-management/_overview.md）
3. 事實蒐集三來源：FE 實掃 + BE 鏈路 + db_schema.json/routes.json
4. 寫 13 節 md（模板 references/page-spec-template.md）
5. 畫 .dot 進該群 assets/（前綴用頁面縮寫；dot -Tsvg <f> -o /dev/null 驗編譯；視覺語彙照既有 dot：主色 #13294B、accent #B8873B、判斷菱形 #FFF6E5、例外 #FDEBD3、錯誤 #F8DCDC、成功 #D9E9DC）
6. build：python3 scripts/deliverables/render_html.py "docs/specs/v1.8.0" 必 ✅
7. 自查：grep -REn '192\.168\.|password\s*=|Billows@'=0、grep 'GRC 系統'=0、內部連結不斷
8. 顯式 git add <檔名> commit（禁 -am / add -A）→ 重讀 tracker → 更新該頁狀態 / commit / 日期

模型分工：tracker 標 Sonnet 的頁可派 Sonnet subagent 寫（但見 §2.1 陷阱——建議只派研究、自己落 md）；標 Opus 的自己寫。

FE 路徑 ~/Projects/Billows/Audit-Manager/compliance-manager-fe/src/。tracker Wave 2「合規框架與 SSP（compliance-framework/）」列的 6 頁：

• 合規框架管理（compliance-framework-manage / version-manage，Opus）
• 框架版本匯入 / 編輯（compliance-framework-import-version / version-edit，Sonnet）
• 範本管理 ModuleFrame（module-frame / -items / -template-edit，Opus）
• 範本匯入精靈 docx/excel（module-frame-import-* 5 條合一，Sonnet）
• SSP docx 匯入 / 更新（project-ssp-import-docx，Sonnet）
• BPMN 稽核範本管理（flow-template-manage / -create / -edit，Opus）

已知 module-frame 端點（routes.json 撈過，可信）：GET /module-frame（list）、GET /module-frame/{uid}、.../components、.../control-defaults、.../objective-defaults、.../parties、.../inventory、.../leveraged、.../ssp-resources、.../system-characteristic、.../template-ssp、.../ssp-export、.../ssp-import-template、GET /module-frame/download/{template,yaml-template} 等（增刪改各對應 POST/PUT/DELETE）。框架版本 / flow-template 端點自行 grep routes.json（pattern：framework、flow-engine/flow-templates）。ModuleFrame 領域知識 → 讀 oscal-knowledge skill + memory reference_db_schema_module_frame。compliance.module_frames 有 _trans 翻譯表（可翻譯欄位慣例見 docs/claude/translatable-fields.md）。

• 不切 branch、不 push（push 永遠等 user 明示）；顯式 git add 檔名、禁 -am
• 每頁獨立 commit + 立刻更新 tracker（改 tracker 前重讀）
• 每完成一個功能群，給 user 一句話回報然後直接繼續（不等驗收）
• §5 截圖一律留佔位 callout（截圖專責 session 另做）；一律亮色模式規格
• 憑證只寫「見 .env / 部署文件」，絕不把 IP / 密碼寫進 spec
• 不晶晶體、不用「GRC 系統」（用 Guidant AI / 合規稽核平台）、不用「速贏」
• 跨 repo 開 FE 前先讀 FE CLAUDE.md（646 行）；只讀不改 FE（spec 是掃 FE 現況，不動 FE code）
• context 快滿時：照本 SOP 在乾淨的群組邊界寫下一份中繼 handoff、更新 tracker 後停下

• 不修 code（發現的 bug / 安全缺口只寫進 spec §12，不動實作）——例：project-settings PUT 無角色守門是記錄不是修
• 不補 §5 實機截圖（專責 session）
• 不動別 session 正在寫的群（看 tracker 狀態 🚧 / Session 紀錄）
• 不重整別人已寫的頁

3b096628 docs(FR-047): tracker — 專案管理群 7 頁全完成
f0c8cdef docs(FR-047): 專案管理群收尾三頁 — 輪次清單/設定/儀表板
83fce5ac docs(FR-047): 專案管理三頁 spec — 列表/建立/總覽

（更早的 pilot / 稽核執行群 commits 見 git log；本群相關的都已 commit，working tree 對本群乾淨。）

接手 FR-047 功能 SPEC 量產（連續作業模式）。先讀
docs/features/FR-047-2607-feature-spec-handbook/handoff/2026-07-05-lane-a-continuation-handoff.md
全文（含 §2 教訓：subagent 委派會 stall、schema 一律查 db_schema.json、DB 連法、tracker 多 session 共寫），
答得出 §0 冷接自檢 4 問再開工。依 writing-feature-specs skill 8 步，
續跑 Lane ②合規框架與SSP群（先 _overview 再 6 頁）→ ③問卷 → ④報表（analysis 🔍先驗）→ ⑤認證。
每頁獨立 commit + 立刻更新 tracker（改前重讀）；每群完成給我一句話回報後直接繼續；
不切 branch、不 push、禁 -am；§5 截圖留佔位；context 快滿寫中繼 handoff 後停。

✅ Lane ② 合規框架與 SSP 群：6 頁 + _overview 全數完成（本 session #6 兩輪連續產出）：

下一棒起點 = Lane ③ 問卷群（survey/） → 之後 ④ 報表群 → ⑤ 認證群。

Lane ③ 問卷群線索（survey/，tracker Wave 2）：

• 先寫 _overview（問卷 v2 資料模型：問卷範本 / snapshot / 填答；與稽核任務的關係——任務可掛問卷，見專案規劃頁 §6.4 surveys）。
• survey-v2-manage（Sonnet）：views/survey/（grep FE survey-v2）；survey-v2-designer（Opus，問卷設計器）；survey-v2-fill / -preview（Sonnet，填答 / 預覽）。
• 端點 grep scripts/deliverables/out/routes.json 的 survey；已知 project-survey/*（answers / histories / checkpoint / patch）在 api.task_survey.routes。表 grep db_schema.json survey schema（有獨立 survey schema：survey.task_surveys 等）+ snapshot。jedi-survey 套件（~/Projects/Jedicogy/module/jedi-python-package/jedi-survey/）。
• 領域知識：memory 搜 survey；問卷 snapshot 慣例見專案規劃頁 spec §11 / §6.4。

Lane ④ 報表群（reporting/）：analysis 頁先驗 ui_routes.enable（🔍）；project-summary-report（Opus，端點 /project-summary-report*，已在 routes.json）；ai-dashboard（Sonnet，/ai-dashboard/* + /grc/dashboard/summary 已在 dashboard 頁spec）；customer-dashboard-editor（Sonnet，動態儀表板模組）。

Lane ⑤ 認證群（auth/）：login+otp-verify（Opus，MFA OTP；端點 grep login|otp|mfa|token；jedi-auth + jedi-mfa 套件；memory reference_dev_login）；forget-password/reset-password（Sonnet，grep password）。認證頁多為未登入態，§3 權限與其他頁不同（匿名可達），§5 截圖可能要登出態擷取。

共用經驗（省時）：三步匯入的 parse→預覽→confirm 模式已定型（見 _overview §4 + uc-cfi/mfi/ssi-01 dots 可參考）；envelope 成功 {"status":true,"data":…}；schema 一律查 db_schema.json（view 不在 dump，去 scripts/sql/view/）；error code 開檔驗。

fresh session prompt（更新版，複製貼）：

接手 FR-047 SPEC 量產（連續作業）。先讀 docs/features/FR-047-2607-feature-spec-handbook/handoff/2026-07-05-lane-a-continuation-handoff.md
全文（特別 §2 教訓 + §10 進度）。Lane ② 已完成；從 Lane ③問卷群（survey/，先 _overview 再 manage/designer/fill+preview）起，
→ ④報表群（analysis 🔍先驗）→ ⑤認證群（login+MFA / forget+reset，注意匿名態）。
依 writing-feature-specs skill 8 步；每頁獨立 commit + 改前重讀 tracker；schema 一律查 db_schema.json、
error code 開檔驗；不切 branch/不 push/禁 -am；§5 截圖留佔位；context 快滿寫中繼 handoff 後停。