FR-056 收官後交接 — 下一棒：release（進版 + push + STG/POC 部署收口）

項目	內容
緣由	FR-056 全案收官（手測 + 收尾工作包 + STG/POC DB 全就緒），user 下令「準備先 release」，主導 session 交棒
Branch（三 repo 同名）	`feature/scan-plugin-integration`（不可切 branch；release 若需併回 main 由 user 決定與操作）
角色	首腦：主導 release 流程 + 派 case 給 runner + 陪 user 部署驗證；執行類工作發出去
現況一句話	FR-056 全部 Done（CM-927~935 九張卡收口），三環境 DB schema 對齊，三 repo 全未 push；下一棒任務 = 進版（version-bump skill）→ 等 user 明示 push → 部署收口
預估時間	進版 1~2 小時；部署驗證看 user 節奏

🧭 原始需求 / WHY（先讀，別跳）

FR-056 檢測工具整合平台：讓客戶「檢測工具（OpenVAS 等）掃描 → 報告自動變任務證據 → 通知 → 任務完成」全自動化。四子需求（56.1 工具設定 / 56.2 任務類型 / 56.3 Agent 執行 / 56.4 編排+轉證據）+ 手測期挖出的 10 個 bug 修復（CM-929~934）已全部驗收完成：2026-07-27 user 親測整條鏈路（同批多任務派工零撞名、auto/manual 完成模式、PDF 證據+發現統計、取消機制真中斷）全過，Notion CM-927~935 全 Done。

本棒（你）的任務：把這包成果 release 出去。具體 = ①主專案進版（走 version-bump skill：release note + pyproject bump + FE 版號對齊 + specs 凍結快照）②等 user 明示後 push 三 repo（push 同時會觸發 spec 站 Cloudflare Pages 上線）③陪 user 把 STG / POC 的服務部署收口（DB 已就緒，差 BE/FE 程式部署與 agent 出貨）。

你在大圖的位置：FR-056 開發已 100% 結束，不要再動功能 code。這一棒是純 release 工程 + 部署陪跑。開發期留下兩張新 case（CM-936/937）是 release 後的事，除非 user 說要塞進本版。

🧭 冷接自檢（答不出來回去讀對應章節）

為什麼現在 release？（FR-056 全案手測驗收完成，user 拍板；STG/POC DB migration 已套完等程式部署）
進版走什麼 SOP？必做哪兩步？（version-bump skill；release note docs/release_notes/v<X.Y.Z>.md + pyproject.toml bump，FE package.json 對齊同版號，specs current 複製凍結快照）
目前版號多少、這次大概進到多少？（BE/FE 皆 1.10.1；FR-056 是大型新功能 → 照慣例 minor bump = 1.11.0，最終由 user 拍板）
為什麼 push 前要等 user？push 會觸發什麼副作用?（規範鐵則 push 永遠等明示；push main 且動到 docs/specs/ 會自動部署 spec 站到 Cloudflare Pages——但目前在 feature branch，推 feature branch 不觸發）
STG/POC 現在各缺什麼？（見 §3 環境矩陣——DB 全就緒；STG 缺 BE/FE 部署 + agent 已 0.2.8；POC BE code 已最新但 agent 還 0.1.0）

§0 接手讀序

🔒 先讀（懂 WHY）：

本文件全文
docs/features/FR-056-2607-detection-tool-integration/handoff/2026-07-27-fr056-manual-test-arc-SUMMARY.md — 全 arc 收口 SUMMARY（commits 全清單 / 10 bug 鏈 / 行為差異 / follow-up）

接著（開工前查座標）： 3. §3 環境矩陣 + §5 commits 現況 4. version-bump skill（user 說進版時 invoke，不要憑記憶走） 5. docs/claude/docs-conventions.md 「SPEC 版本模型」段（凍結快照怎麼切）

§1 現況事實（全部已驗證，可直接信）

1.1 功能與 Notion

CM-927（手測主戰場，雷門）+ CM-929~934（六張子修正，小弟）+ CM-935（收尾工作包，小弟）全部 Done（2026-07-27）
收尾工作包產物：使用手冊正式化（user-manual.html，刪修正敘事、對齊 0.2.8、與 discussion.html 雙向連結）、6 頁 spec 更新 + current html 重 build、arc SUMMARY、STG migration

1.2 版號座標

Repo	HEAD	版本	備註
compliance-manager-be	`12436bb8`	pyproject 1.10.1	距上版 43 commits
compliance-manager-fe	`5a2d2b5`	package.json 1.10.1	⚠️ HEAD 是 CM-928（agent 在線狀態改健康檢查即時結果）——主導 session 交接前才出現的 commit，未經本 session 驗收，進版前抽查一眼 diff
evidence-agent	`e59c9fc`	0.2.8（獨立版號線，不跟主專案）	已部署 123（DEV）；agent 版號進版不歸 version-bump skill 管

三 repo working tree 乾淨、全部未 push（唯一例外：BE 有幾個 untracked 的 docs/handoff 檔屬正常）。

1.3 Notion 待辦 case（release 後的事，不擋版）

CM-936：agent 管理頁隱藏「類型」欄位（純 FE，已開卡未派工）
CM-937（FR-056.9）：agent 心跳自報 capabilities + 手冊環境開通 checklist 章 + detection_probe_no_agent 錯誤文案改善（已開卡未派工）
未開 case 的口頭 follow-up：OpenVAS target/task 殘留清理策略、agent 對外暴露防火牆收緊、BE main_app.py 加 load_dotenv()（user 已同意方向：兩行改動 + override=False，.bashrc 環境變數逐步搬 .env——2026-07-27 傍晚 POC/STG 連環踩「.bashrc 變數服務讀不到」的坑後拍板，尚未開卡）

§2 前次教訓（本棒別重蹈）

migration 檔名字母序 ≠ 依賴序：POC 套 fr056 時 2-jedt-fix-rls-delimiter 排在建表的 2-job-execution-detection-tools 前，先跑炸「表不存在」——--single-transaction 保命後調序重套即過。未來批次套要按依賴排。
環境開通三連坑（STG/POC 都踩）：BE .env 缺 DRIVE_TOKEN_ENCRYPTION_KEY / DETECTION_TOOL_ENCRYPTION_KEY（心跳/工具頁直接 500）+ agent capabilities 要手動 UPDATE 加 detection_scan（CM-937 做完前的過渡）。POC/STG 都已補完，未來新環境照 CM-937 卡內 checklist。
舊 compose 部署機的標準重啟式：docker compose --profile full up -d --remove-orphans --force-recreate——不帶 --profile full 會把 nginx 當 orphan 砍掉；不帶 --remove-orphans 舊改名前容器佔 port；network 接線錯亂靠 --force-recreate。.env 的 AGENT_IMAGE 要先改 guidant-ai-agent:0.2.8（image 已改名，舊名 evidence-agent 會去 Docker Hub pull 然後 access denied）。永遠不加 -v。 3b. 部署機 repo 要先切對 branch（POC 實踩，2026-07-27 晚）：agent 機 /opt/evidence-agent 若停在舊 branch，compose 檔就是舊的（AGENT_VERSION: "0.1.0" env 蓋掉程式 fallback → 心跳謊報 0.1.0，image 引用也是舊名）。部署前先在 agent 機 git fetch && git checkout feature/scan-plugin-integration && git pull（部署機切 branch 是 user 自己操作，不受「Claude 不切 branch」限制），再走標準重啟式。STG@122 大概率同樣要做。版號謊報的根治（importlib.metadata 自報 + 刪 compose env）已併入 CM-937。
.env 是 root 擁有時 jedi 帳號寫不進（POC 189 實況）——sudo 要密碼，密碼類操作一律請 user 自己打，不代打。
agent 版號 bump 五處同步（pyproject / config.py / compose image tag + AGENT_VERSION env / .env.example / rebuild.sh）——runner 連三輪只改 pyproject，要驗。

§3 環境矩陣（release 部署的起點）

環境	DB schema	BE code	FE code	agent	Fernet keys	備註
DEV（本機+123）	✅ HEAD	✅ `3a9a9c05`+（本機跑 12436bb8 亦可）	✅ dev server	✅ 0.2.8 @123，capabilities 已含 detection_scan	✅	全功能可測
STG（188 + agent@122）	✅ 11 支已套 + fr048 記帳補齊	⚠️ 需部署（機器是 `auditmanager-stg-01`）	⚠️ 需部署	✅ 0.2.8 @122，capabilities 已補	✅ 已補兩把	user 已在 STG 測過測試連線（過了 no_agent 關）
POC（189 + agent 另一台）	✅ 11 支已套	✅ 已同步 `12436bb8`（user 自行 rsync/pull 的，git safe.directory 已加）	❓ 未查	✅ 0.2.8 已升級（2026-07-27 21:05 心跳確認；當時卡在 agent 機 repo 舊 branch，切 branch + 標準重啟式後解決）；capabilities 已含 detection_scan	✅ 已補兩把（user 以 sudo 補）	tool-plugin-manage 頁已可開；剩工具設定+測試連線+真掃描抽測未做

POC agent 升級是部署收口最大缺口：agent 機座標問問 user（雲端 DB 在 189，agent 是另一台），流程照 §2 教訓 3。

§4 開工順位

Pre-flight（§6）跑一遍，確認環境沒被動過
FE HEAD 5a2d2b5（CM-928）抽查：git show 5a2d2b5 --stat + 看 diff 是否影響 release（是 agent 管理頁在線狀態顯示邏輯，理論上獨立小改）
user 下「進版」令後：invoke version-bump skill 走完整 SOP——release note（彙整 FR-056 全部 + CM-928 等零星 fix）→ pyproject bump → FE package.json 對齊 → specs current/ 複製凍結快照 v<新版號>/ → 兩個目錄各自重 build html
push 等 user 明示：三 repo 分開推；推完提醒 user spec 站上線條件（要 main 才觸發 Pages）
部署陪跑：STG BE/FE 部署 → POC agent 升 0.2.8 → 各環境功能抽測（測試連線 → 派一次真掃描）
release 後：問 user CM-936 / 937 / load_dotenv 三件要不要排下一輪

§5 三 repo commits 現況

BE：12436bb8（docs 收尾）← 28188b4d（spec 6 頁）← 102f6194（手冊）← 3a9a9c05（CM-931）…共 43 commits 未發版，全未 push
FE：5a2d2b5（CM-928，未經本 session 驗收）← e986b88（CM-931）…未 push
agent：e59c9fc（0.2.8 版號補齊）← 703b59a（CM-934）…未 push

§6 Pre-flight Command（必跑）

# 三 repo branch + HEAD + working tree
for r in compliance-manager-be compliance-manager-fe evidence-agent; do
  cd ~/Projects/Billows/Audit-Manager/$r && echo "== $r ==" && git branch --show-current && git log --oneline -1 && git status --short | grep -v '^??' | head -3
done

# 三環境 DB fr056 對齊快查（應各回 11）
cd ~/Projects/Billows/Audit-Manager/compliance-manager-be
export PGPASSWORD=$(grep '^#DB_SECRET' .env | sed 's/^#DB_SECRET=//' | python3 -c "import json,sys; print(json.loads(sys.stdin.read())['rds_master_password'])")
for t in "guidant_ai_dev 188" "guidant_ai_stg 188" "guidant_ai_poc 189"; do set -- $t; \
  psql -h 192.168.50.$2 -p 25432 -U cmmgr -d $1 -t -A -c "SELECT '$1: ' || count(*) FROM public.schema_migrations WHERE filename LIKE '%fr056%';"; done

# agent 心跳（DEV id=8 應 0.2.8；POC 在 guidant_ai_poc id=3，release 期間升級後應變 0.2.8）
psql -h 192.168.50.188 -p 25432 -U cmmgr -d guidant_ai_dev -t -A -c "SELECT 'DEV agent: ' || agent_version || ' ' || status FROM compliance.remote_agents WHERE id=8;"

§7 驗證上一棒工作已 close

CM-927~935 全 Done 已核實（本 session 親自抽查 CM-935 四工作包：STG 11 支 migration + 手冊 grep 驗證 + spec 6 頁變更行 + SUMMARY/CLOSED 標頭，全過）。無須重驗，直接開工。

§8 行為規範重要提醒

不切 branch；push 永遠等 user 明示；收尾類動作等 user 下令
進版 = version-bump skill，別憑記憶；specs 凍結快照切版時機 = version-bump 完成那一刻
派 subagent 一律 1M context model（不帶 model override）；執行類工作發給 runner
繁體中文；Notion 先搜尋再開卡；Claude 作業填「小弟」、user 親測填「雷門」
SSH：jedi@192.168.50.189（POC）、jedi@192.168.50.123（DEV agent）免密可進；jedi@192.168.50.122（STG agent）本機無 key，操作請 user 代跑；sudo 密碼一律 user 自己打
密碼/token 絕不寫入任何會 commit 的檔案

§9 不在本期 scope

CM-936（隱藏類型欄）/ CM-937（capabilities 自報）——release 後排程，除非 user 說塞本版
main_app.py load_dotenv() 改動——已拍板方向但未開卡，release 後處理
OpenVAS 殘留清理、agent 防火牆收緊——未開 case
jedi-* 套件發版（本輪無套件異動）

§10 給下一棒的超短 Prompt

請讀 docs/features/FR-056-2607-detection-tool-integration/handoff/2026-07-27-fr056-release-prep-handoff.md
接手 FR-056 release 棒。角色是首腦：主導進版 + 部署陪跑 + 派工給 runner，不自己實作功能。

先過交接文件「🧭 原始需求 / WHY」+ 冷接自檢 5 題，再跑 §6 pre-flight。

現況一句話：FR-056 全案 Done（Notion 九張卡收口）、三環境 DB 對齊、三 repo 未 push、
BE/FE 版號停在 1.10.1。本棒任務：version-bump skill 進版 → 等 user 明示 push →
STG/POC 部署收口（POC agent 還在 0.1.0 要升 0.2.8）。

FE HEAD 5a2d2b5（CM-928）是交接前新出現的 commit、未經驗收，進版前先抽查 diff。