FR-058 規劃完成、實作已派出 — 換 session 交接（2026-07-30）

決策者的原始需求（一字不改）

「目前的檢測工具管理 /plugin/tool-plugin-manage 還需要增加下面工具——OpenSCAP for Windows 解決方案 / Nmap / GCB / SonarQube。請幫我分析跟規劃，開成新的需求放到 Notion。」

需求的演變過程（這是理解本案的關鍵，不讀會誤解範圍）

原始四項工具，經過調研與決策者裁示後變成另外四項，過程如下：

最終四工具：ZAP（DAST 網頁動態掃描）/ InSpec·CINC Auditor（Windows + Linux 組態檢測）/ GCB（政府組態基準 TWGCB，引擎複用 CINC）/ Nmap（網路埠掃描）。

大圖定位（本案在哪一棒）

FR-056 檢測工具整合平台（v1.11.0 上線）
   └ tool-agnostic 地基：後端對具體工具零知識、前端純 schema 驅動、加工具原則上只要一條 SQL seed
        ↓
FR-057 OpenSCAP SSH connector（v1.12.0 上線，2026-07-30 全案結案）
   └ 第一個真實工具落地：補齊 SSH 連線型態、setup_guide 欄位、多檔證據回收、兩條「靜默假成功」防護通道
        ↓
FR-058（本案）一次規劃四個工具 + 補平台唯一的結構性缺口

本案要解決的兩件事

① 接入四個工具——涵蓋三種完全不同的連線型態：

② 補平台唯一的結構性缺口：任務層敏感參數（FR-058.0）——現有設計把憑證與參數分兩處放，而只有憑證那一條有加密：

若直接把被掃網站的登入帳密塞進 tool_params，會發生兩件事：① 帳密明文躺在資料庫；② FE 執行紀錄視窗會顯示任務參數——BE 現有的 secret 剝除機制是針對租戶層設定的 secret 定義寫的，任務層參數沒有這套保護，等於帳密直接顯示在畫面上。這不是 ZAP 專屬問題（Nmap 做認證掃描、GCB 每台主機帳密不同都會撞同一格），因此當成平台級能力補上，並且是 ZAP 的硬前置。

敏感參數的生命週期：資料庫為密文、僅在派工傳輸與 agent 執行期間為明文、agent 用完即丟不落地、FE 一律剝除。

本棒在大圖的位置

規劃已完成並 push，實作已派出。本棒是協調者與驗收者——等實作回報、跑端到端驗收、產第二批交接 prompt、更新討論稿。不是實作者。

0.1 🔒 先懂需求 gate（全讀，讀完才能碰任何東西）

1. 本文「🧭 原始需求 / WHY」全段——特別是「需求的演變過程」那張表，不讀會搞不清楚為何最終工具清單跟決策者原話對不上
2. /Users/chouraymond/Projects/Billows/Audit-Manager/compliance-manager-be/docs/features/FR-058-2607-detection-tools-expansion/design.md §1（需求背景與目標）+ §2（D1–D11 決策定案）全讀——D1–D11 是本案所有取捨的依據，實作 session 若回報阻礙要決策，判斷原則就在這裡

0.2 現況與待辦

3. 本文 §1（當前狀態盤點）→ §2（前次教訓）→ §3（三種情境與處理方式）→ §4（開工順位）
4. Notion 母案 CM-957：https://app.notion.com/p/3ad346da4cd081859d2ed8b21ca2697c——末段「🚀 分批出貨計畫」是本棒最重要的一段，含批次安排、session 切分、測試紀律、第一批驗收清單

0.3 需要細節才開（不要一開始就全讀，會燒 context）

5. design.md §3（現況接入點盤點，含派工鏈路四階段與技術債表）/ §4（詳細設計，四個工具各自的 param_schema 與 connector 要點）/ §5（拆分，1 橫向項 + 5 子需求 × 20 子任務）/ §6（端到端驗收九項）
6. docs/features/FR-058-2607-detection-tools-expansion/discussion.html（951 行）——含流程圖與官方資源盤點。注意：內容停在「四工具一次接入、三線並行」版本，尚未反映分批出貨安排，讀它時要知道這一點；更新它是本棒的待辦項（見 §4 第 5 步）
7. 前作交接文件（要理解 agent 部署踩過的坑時才開）：docs/features/FR-057-2607-openscap-ssh-connector/handoff/2026-07-29-fr057-arc-complete-handoff.md §2.2（跨平台 Docker build 陷阱）與 §2.4（版號第六處同步點）

0.4 ✅ 冷接自檢（五問，答不出來回去讀 §0.1，不要碰任何東西）

1. 本案要解決什麼問題？（提示：不只是「多加四個工具」，還有一個平台級的結構性缺口）
2. 為何 SonarQube 被移出本案？原本編號 D10 現在怎麼處理？
3. GCB 的驗收條件是什麼？為何刻意不是「涵蓋多少規則」？
4. 為何 _TOOL_ID_TO_CODE 解耦（D11）要排在最前面？在改成分批出貨後，這個理由換成什麼了？
5. 本棒的角色是什麼？哪些事情不該做？

第 4 題是陷阱題：原本的理由（三條線搶同一個 factory 檔）在改成序列執行後已不成立，新理由寫在 Notion 母案「分批出貨計畫」段。答錯代表沒讀到那一段。

本節取代範本的「§1 症狀」。本案不是 bug，沒有症狀，只有狀態。

1.1 規劃產出物（已完成、已 commit、已 push）

1.2 Notion 卡片全表（本棒追進度用）

母案：CM-957 — https://app.notion.com/p/3ad346da4cd081859d2ed8b21ca2697c

1.3 實作派工狀態（2026-07-30 已派出，進行中）

分批出貨安排（決策者 2026-07-30 拍板，取代原三線並行）：

第一批的兩個實作 session（已派出、並行中）：

兩者為何能並行不互卡：

• Session 2 的 T-X.2 採「有 code 用 code、無 code 退回 id」的 fallback 寫法，不會被 Session 1 的 T-X.1 擋住
• 欄位名稱已定死為 detection_tool_code（design.md §4.X 明文），兩邊照此寫即可，不需要即時協調
• Session 2 只有最後的 T-1.4（登入後掃描）真正需要等 Session 1 的解密接線（CM-963），前面的 seed、connector 骨架、被動／主動掃描都不必等

1.4 git 現況（本棒接手時要重新確認）

⚠️ 實作 session 的 commits 會陸續進來，本棒接手時務必先跑 §6 pre-flight 看實際 git log，不要拿本文的 HEAD 當現況。

2.1 subagent 一次寫大檔會中途斷線

本 session 兩次遇到同一個現象：subagent 讀完資料、正要 Write 大檔（討論稿 / design.md）時，API 在 stream 中途 stall，agent 就此陣亡。

解法：用 SendMessage 恢復該 agent 並要求分段落地——先 Write 骨架，再多次 Edit append。

對本棒的意義：下次派文件產出類 subagent（例如 §4 第 5 步要更新 discussion.html），直接在派工單就寫明「分段寫檔：先 Write 骨架再多次 Edit append，不要一次寫完整份」，不要等它斷了才補救。

2.2 subagent 一律用 1M context model

呼叫 Agent tool 時不要帶 model 參數（會繼承主 session 的 1M context model）。曾因省 context 派小模型，導致 context 爆炸（autocompact thrashing）中途陣亡要重拆重派，浪費的 token 與時間比一開始就用大 context model 更多。

純機械小任務（一條 grep、一個檔的小改）才可用小 model，猶豫時預設選 1M。

2.3 不信 subagent 自報完成，一律實際抽查

本 session 每次都實際開檔 / fetch Notion 抽查，並且抓到了問題：

• README 那一列數字寫錯——寫「16 子任務」，實際是 20
• README 排程敘述停在「三線並行」，實際已改分批出貨

兩處都是抽查才抓到的。subagent 自報「已完成」不等於內容正確。

2.4 mermaid init 字串是三次踩坑後的解

每張 mermaid 圖首行必須內嵌 %%{init:...}%%，單獨一行、不可斷行。原因：Artifact 雲端不執行頁面 script，靠頁面 JS 設定 mermaid theme 的做法在雲端完全失效，只有內嵌 init 字串有用。

discussion.html 內的圖都已照此處理，本棒更新它時不要動那些 init 行。

2.5 決策者會推翻保守建議，先理解論證再回應

D7（GCB 範圍）原本我建議「先做 Linux GCB 子集」，理由是防守 content 工程的風險。決策者從產品面指出應該雙邊一起做——客戶是混合環境，只交付一半等於交付不完整。

最終定案是把兩個層次拆開：引擎層雙邊一次到位（由 CINC connector 承擔）／content 層本案不做（只留一份 Windows 最小 Demo profile 證明鏈路）。這比原本任一方案都好。

教訓：遇到決策者提出不同角度，先理解他的論證再回應，不要固守原建議。他看的是產品與交付，我看的是技術風險，兩者疊起來才是完整判斷。

本節取代範本的「§3 Root cause 候選」。本案沒有 bug 要追根因，只有情境要判斷。

判斷起點：看 Notion 卡狀態是否已改「修正待驗證」（實作 session 完成子任務後會回寫）。

情境 A：兩個實作 session 都回報完成 → 執行第一批端到端驗收

⚠️ 前置動作很貴，先讀 §7 確認齊備再動手。

A.1 前置環境準備（順序不可顛倒）

# ① 三環境套 migration（DEV → STG → POC，一律用 cmmgr 帳號，密碼請查 .env 或部署文件）
# DEV
psql -h 192.168.50.188 -p 25432 -U cmmgr -d guidant_ai_dev \
  --single-transaction -v ON_ERROR_STOP=1 \
  -f /Users/chouraymond/Projects/Billows/Audit-Manager/compliance-manager-be/scripts/sql/<實作 session 產出的 fr058 seed 檔>.sql

# STG（同一台 server，不同 DB）
psql -h 192.168.50.188 -p 25432 -U cmmgr -d guidant_ai_stg \
  --single-transaction -v ON_ERROR_STOP=1 -f <同上檔案>

# POC（不同 server）
psql -h 192.168.50.189 -p 25432 -U cmmgr -d guidant_ai_poc \
  --single-transaction -v ON_ERROR_STOP=1 -f <同上檔案>

# ② 三環境 seed 結果對照（確認 ZAP 進去了、id 一致）
for db in "192.168.50.188 guidant_ai_dev" "192.168.50.188 guidant_ai_stg" "192.168.50.189 guidant_ai_poc"; do
  set -- $db
  echo "=== $2 @ $1 ==="
  psql -h $1 -p 25432 -U cmmgr -d $2 \
    -c "SELECT id, code, connection_type, status FROM config.detection_tools ORDER BY id"
done

# ③ 重建 agent image（⚠️ 開發機是 Mac arm64、目標主機是 Linux amd64，必須指定 --platform）
cd ~/Projects/Billows/Audit-Manager/evidence-agent
DOCKER_BUILDKIT=1 docker build --platform linux/amd64 \
  --secret id=nexus_auth,src=.secrets/nexus.env \
  -t guidant-ai-agent:<新版號> --load .
docker inspect guidant-ai-agent:<新版號> --format '{{.Os}}/{{.Architecture}}'
# 必須回 linux/amd64 才可出貨。回 arm64 就是踩到 FR-057 §2.2 那個坑

# ④ 部署三台 agent（121 POC / 122 STG / 123 DEV）
for h in 192.168.50.121 192.168.50.122 192.168.50.123; do
  docker save guidant-ai-agent:<新版號> | ssh jedi@$h docker load
  # 改該機 /opt/evidence-agent/deploy/.env 的 AGENT_IMAGE
  # 改該機 /opt/evidence-agent/deploy/docker-compose.yml 的 AGENT_VERSION（第六處版號同步點，不會隨 git pull 更新）
  ssh jedi@$h "cd /opt/evidence-agent/deploy && docker compose up -d guidant-ai-agent"
done

# ⑤ 確認三台心跳健康
for h in 192.168.50.121 192.168.50.122 192.168.50.123; do
  echo "=== $h ==="
  ssh jedi@$h "docker ps --filter name=guidant-ai-agent --format '{{.Names}}\t{{.Image}}\t{{.Status}}'"
  ssh jedi@$h "docker logs deploy-guidant-ai-agent-1 --tail 5"
done
# 預期：Up + log 有 heartbeat 200 OK

# ⑥ BE 重啟（改 service code 後必做，必先 kill -9）
cd /Users/chouraymond/Projects/Billows/Audit-Manager/compliance-manager-be
ps aux | grep -i "main_app.py" | grep -v grep | awk '{print $2}' | xargs -r kill -9
nohup python main_app.py > /dev/null 2>&1 &
sleep 5 && lsof -i :8000 | head -3

# ⑦ FE 部署（由決策者或 FE 部署流程處理）

A.2 第一批八項驗收清單

A.3 驗收紀律（決策者明確要求）

• 任務發佈後最長等 300 秒才會真的開跑——這是心跳週期造成的正常行為，不是故障。看到「按了沒反應」不要當 bug 追
• 測試一律 headless
• 主 session 不自己跑測試——跑的動作派 subagent（用 1M model），本棒只派工 + 輕量抽查
• 不要每個子任務各自跑一次端到端——一輪至少 10 分鐘起跳，重建 image + 部署三台 + 等心跳才是真成本

情境 B：只有一個 session 回報，或回報部分完成 → 等齊再驗收

不要急著驗收。 理由很直接：重建 agent image + 部署三台 + 等 300 秒心跳是整個流程最貴的動作，做一次要一小時起跳。只驗一半等於這筆成本要付兩次。

處理方式：

1. 確認已回報那一側的 Notion 卡狀態與 commit 內容（git log 看實際進來什麼）
2. 可以做的便宜檢查（不觸發昂貴前置）：import／語法檢查、對假 fixture 跑解析邏輯的單元測試、SQL 套 DEV 後 SELECT 確認 seed 進去
3. 等另一側回報後，再一次跑情境 A 的完整流程

情境 C：實作 session 回報遇到阻礙需要決策 → 本棒可直接拍板

本棒是決策角色，遇到下列常見阻礙可直接判斷，判斷原則見 design.md §2 的 D1–D11 定案理由：

遇到 D1–D11 沒涵蓋的新決策：停下來問決策者，不要自己開新方向。

1. 跑 §6 pre-flight（確認 branch / working tree / 三 repo 現況 / 服務健康）
2. 確認兩個實作 session 的回報狀態——看 Notion 卡（CM-959、CM-962〜965、CM-960、CM-967〜970）狀態是否已改「修正待驗證」，並 git log 對照三 repo 實際進來的 commits
3. 依 §3 三情境對應處理（A：跑驗收／B：等齊／C：拍板）
4. 第一批驗收通過後 → 產第二批（InSpec·CINC → GCB）交接 prompt——Notion 母案末段明寫「交接 prompt 待第一批驗收完成後才產出，屆時可能已有新的實作發現需要帶進去，先寫容易過期」
5. 更新 discussion.html 反映分批出貨安排——⚠️ 這是明確的待辦項，決策者說「等派發出去後再用 subagent 產」。現在已派出，可以做了。派 subagent 時記得帶 §2.1 的分段寫檔要求，以及「不要動 mermaid 的 %%{init:...}%% 行」

收尾類動作（SPEC / SUMMARY / memory / Notion 母案收尾）一律等決策者明確下令，plan approve 不等於自動執行收尾。

5.1 BE（/Users/chouraymond/Projects/Billows/Audit-Manager/compliance-manager-be/）

5.2 FE（~/Projects/Billows/Audit-Manager/compliance-manager-fe/）

5.3 evidence-agent（~/Projects/Billows/Audit-Manager/evidence-agent/）

本節取代範本的「§7 Verify 前一個 bug 確實 close」。本案沒有前一個 bug，取而代之的是「不要在條件不齊時付出昂貴的驗收成本」。

下列四項全部 ✅ 才啟動 §3 情境 A 的環境準備。任一項 ❌ 就走情境 B（等齊）。

額外確認（git log 抽查，不要只信 Notion 卡狀態）：

# 三 repo 各看最近 15 筆，確認實際進來的東西與 Notion 宣稱一致
for repo in compliance-manager-be compliance-manager-fe evidence-agent; do
  echo "=== $repo ==="
  cd ~/Projects/Billows/Audit-Manager/$repo
  git log -15 --format="%h %ad %s" --date=short
done

教訓來源見 §2.3：本 session 抽查抓到過 subagent 自報完成但內容有誤的情況。Notion 卡改了狀態不等於程式碼真的到位。

• 不切 branch：任何 git checkout <branch> / git switch <branch> 一律不執行，永遠在 feature/FR-058 工作。發現 branch 不對停下問決策者，不自己 fix。「為了在正確 branch commit 而切 branch」也不允許
• push 永遠等決策者明示，不自動 push
• 顯式 git add 檔名，禁用 -am——⚠️ 本案有兩個實作 session 並行，誤 add 對方未完成改動的風險特別高
• 收尾必須等決策者下令：SPEC / SUMMARY / memory / Notion 母案收尾都是。plan approve ≠ 自動執行收尾
• 憑證禁入版控：密碼、token、API key 絕不寫進任何會 commit 的檔案（含 SQL migration、docs、handoff）。需要連線資訊時只寫帳號 / host / port / db 名，密碼一律寫「請查 .env 或部署文件」
• BE 出錯先看 log，不問決策者：tail -200 log/app.log | grep -A 30 -i 'Traceback\|ERROR'。確認 log 沒線索才回頭問
• BE 起服務用 main_app.py（port 8000），main_socketio.py 是 socket（8002）不是 API 入口；重啟必先 kill -9（orphan pid 會卡住 port）
• 文件產出類工作一律派 subagent（含 §2.1 的分段寫檔要求），主 session 只做決策、派工、抽查
• 執行類工作發出去：跑測試、跑部署一律派 subagent，本棒不自己執行
• subagent 一律用 1M context model，不帶 model 參數
• SQL migration 鐵則：檔頭 -- Date:、每個語句加日期註解、新建 table 必加 GRANT ... TO cm_app + sequence 權限、收尾必 INSERT public.schema_migrations；套用一律 psql --single-transaction -v ON_ERROR_STOP=1 -f <檔> 用 cmmgr 帳號；三環境（DEV / STG / POC）都要套
• 跨 repo 各自分開 commit，commit message 對應各自 repo 的脈絡
• 不要晶晶體（中英夾雜的語法），不要用「速贏」這個詞

⚠️ 本節列的是「等命令」的動作，不要主動執行。 第一批驗收通過不等於全案完成。

分批進行中的階段性動作（每批驗收通過後）：

1. 回寫該批 Notion 子任務卡狀態
2. 產下一批的交接 prompt
3. commit（顯式 git add，不 push）

全案完成後（三批都驗收通過、決策者下令才做）：

1. 更新 docs/specs/current/ 對應頁面 spec（tool-plugin-manage.md / project-task-edit.md / my-tasks.md）+ 檔頭「變更紀錄」加一行——SOP 走 writing-feature-specs skill
2. 寫 SUMMARY 到 docs/features/FR-058-2607-detection-tools-expansion/handoff/
3. Notion 母案 CM-957 + 六張子需求卡狀態同步
4. 收尾兩項未開卡的工作（見 §10）
5. memory feedback 沉澱
6. 若要發版 → 走 version-bump skill（release note + pyproject.toml bump 成對必做 + FE 版號對齊）

⚠️ 本棒接手時務必先 git log 看實際狀況——兩個實作 session 的 commits 會陸續進來，本表只反映規劃 session 結束當下的快照。

接手 FR-058（檢測工具擴充，四工具接入）的協調與驗收工作。

先讀 docs/features/FR-058-2607-detection-tools-expansion/handoff/2026-07-30-fr058-planning-complete-handoff.md
的「🧭 原始需求 / WHY」與 §0 讀序（含 design.md §1-§2 的硬 gate），讀完先回答 §0.4 的冷接自檢五問。

答完再跑 §6 pre-flight，然後依 §3 判斷落在哪個情境（A：兩個實作 session 都回報完成 → 跑第一批端到端驗收；
B：只回報一半 → 等齊，不要付昂貴的重建部署成本；C：回報阻礙 → 你是決策角色可直接拍板）。

規劃已完成並 push，實作已派給兩個外部 session 並行中——你的角色是協調與驗收，不是實作。
不要自己下去寫 connector 或改 BE。收尾類動作一律等我下令。

📌 寫完自檢：下個 session 只看這一份，能不能答出冷接自檢五問（懂 WHY）、跑得動 pre-flight、判斷得出情境並開工？——本文所有 SQL / bash / 路徑 / Notion URL 皆可直接複製貼上，不需回頭問決策者。