# FR-056 主導 session 中繼交接 v2 — 半夜自主任務鏈防斷點（orchestrator handoff）

| 項目 | 內容 |
|------|------|
| 緣由 | 主導 session context 用量偏高，半夜要跑無人值守自主任務鏈（56.4 驗收→修復→手冊），寫此保險 handoff 防 session 斷點/變笨 |
| 交接日期 | 2026-07-26 深夜（56.4 runner 已派出，預計 27 日凌晨完成） |
| Branch（BE/FE/evidence-agent 三 repo 同名） | `feature/scan-plugin-integration`（不可切 branch） |
| 本棒角色 | **主導/驗收 session**——派工 + 驗收 + 收口，**不自己實作**（實作歸 runner / 修復 subagent） |
| 現況一句話 | 56.1/56.2/56.3 全數獨立驗收放行；56.4 runner（Sonnet 5，user 另開 session）執行中；**user 已授權半夜自主鏈**（見 §NIGHT） |
| push 狀態 | BE/FE/evidence-agent 皆有未 push commits（push 永遠等 user 明示） |
| 取代 | 同資料夾 `2026-07-26-orchestrator-mid-arc-handoff.md`（前一棒交接，內容已過時但背景仍可參考） |

## 🧭 原始需求 / WHY（必讀）

**要解決什麼**：客戶目前「用檢測工具掃描 → 匯出報告 → 手動上傳當任務證據 → 手動完成任務」全程手工。FR-056 把這條線自動化：

1. **租戶自助設定檢測工具**（首接 OpenVAS）——工具目錄 DB 驅動，租戶填連線資訊+憑證（加密落庫）【56.1，已放行】
2. **任務可設為「檢測工具執行」類型**+掃描參數（BPMN userTask 同步）【56.2，已放行】
3. **按「開始執行」→ 客戶端 Agent 觸發掃描**——複用 FR-039 evidence-agent（mTLS+JWT），派工走「心跳夾帶待辦」【56.3，已放行】
4. **報告自動回收成任務證據**（source=DETECTION_TOOL，沿用 DRIVE_SYNC handler 模板）→ 發信通知 → 依 `completion_mode` flag 決定自動完成或留人工【56.4，執行中】

**完成模式（易誤解，必懂）**：`completion_mode` 只是「掃完要不要自動按完成鍵」的 flag，**不是新狀態**。auto=系統自動呼叫既有 complete_job；manual=系統不做事，任務留 PROCESSING，人工判斷證據後手動完成。**零新增 JobStatus、不動 jedi_flow_engine**。

**關鍵決策 D1–D11 在 `design.md` §3**。56.4 最相關：D11 證據用既有 FILE 型別（嚴禁新增 REPORT）/ D9 憑證雲端解密隨派工下發不落地 / D8 完成模式預設 manual。

**開發模式**：主導出 plan → user 開 Sonnet runner session 實作 → 主導派獨立 subagent 驗收（不信自報）→ Notion 三層留痕 + 執行時間紀錄（user 在收模式效率數據）。

## 🌙 §NIGHT：user 已授權的半夜自主任務鏈（2026-07-26 深夜下令，原話要旨）

> 「大約台北時間 27 號 AM 3 點檢查是不是都做完了，還沒做完隔半小時再檢查，做完了就做驗收。**驗收有問題，就你這邊派 subagent 去處理**，都完成後給一份 HTML 使用手冊（要做什麼測試、agent 要怎麼升級、任務跟檢測工具要怎麼設定），跟檢測項目做好都放到 Notion 內，交給你了。」

**授權範圍（可不經 user 直接做）**：
1. 定時查 56.4 完成狀態（未完成 → 30 分鐘後再查，用 CronCreate one-shot 續排）
2. 完成 → 派獨立 Sonnet subagent 分段驗收（照 56.1–56.3 模式）
3. 驗收缺失 → **直接派 Sonnet subagent 修復**（不返工給 runner）→ 複驗到放行
4. 全放行 → 產出：(a) HTML 使用手冊（派 subagent 寫，主 session 驗收）(b) Notion 新 case「FR-056 人工驗證測試（user 手測）」(c) 母案 CM-907 補指引一行

**授權外（仍禁止）**：push / 切 branch / 動 jedi_flow_engine / 收尾類動作（spec/SUMMARY/母案收口/memory——等 user 醒來下令）。

**已排 cron**：session 內 one-shot（27 日 02:57 台北），未完成自動續排 30 分。**cron 是 session 記憶體內的——若本 session 斷掉 cron 就消失**，接手的新 session 要自己重建（直接手動執行下方檢查即可，不必重排 cron 若已過時間）。

## §0 接手讀序（fresh session 冷接照此順序）

🔒 先懂需求 gate：
1. 本文件 🧭 + §NIGHT 全讀
2. `docs/features/FR-056-2607-detection-tool-integration/design.md` §3（D1–D11）+ §6（Agent 派工/轉證據/執行流程）
3. memory `project_fr056_detection_tool_integration.md` 開檔全讀

**冷接自檢 4 問**（答不出回去讀）：
- FR-056 要讓使用者少做哪些手工？
- completion_mode=manual 時任務狀態是什麼、系統做什麼？
- 半夜自主鏈的授權邊界在哪（哪些可直接做、哪些仍禁止）？
- 56.4 驗收若發現缺失，處理方式跟 56.2/56.3 時有什麼不同？（提示：不返工給 runner）

然後按需讀：`implementation-plan-phase4.md`（驗收 56.4 時才讀，別整讀——很大，grep 定位）。

## §1 現況快照（交接當下）

### 1.1 三子需求驗收全放行（勿重跑）

| 子需求 | 驗收結論 | 驗收報告位置 |
|--------|---------|-------------|
| 56.1（CM-908） | 16✅+1N/A 零缺失放行 | CM-908 卡內文 |
| 56.2（CM-909） | 四段全過零返工放行（BE 三段+FE 一段） | CM-909 卡內文 |
| 56.3（CM-910） | 首輪 16/17 過→返工 `ea661321`（狀態機終態防護）→複驗 9 項全過放行 | CM-910 卡內文 |

56.2 期間兩個 plan 級問題已處理完（都不是 runner 的錯）：
- **T-2.3 落點錯誤**：原 plan 指到斷頭頁 `TaskSetupView.vue`（ui_routes 無條目/無導覽/API 未註冊），裁定 revert（FE `fd2e837`）+ 在 `ProjectPlanningView.vue` 重做（FE `5914df2`）。已回寫 plan-phase2/design.md/CM-919。
- **param seed 遺漏**：`detection_tool_param_schemas` 原本零 seed，connector `params.hosts` 必填會炸。已補 seed migration（BE `8efbb6b2`），4 key（hosts/timeout_sec/scan_config_id/scanner_id）與 evidence-agent connector 逐字對齊，DEV 已驗。

### 1.2 56.4 runner（user 另開 Sonnet 5 session，執行中）

Case：T-4.1 CM-924（source 加 DETECTION_TOOL + detection_executions 表 + 轉證據 handler）/ T-4.2 CM-925（執行編排 + 完成模式分岔 + 通知）/ T-4.3 CM-926（FE 任務執行抽屜）。plan：`implementation-plan-phase4.md`。runner prompt 已含 Notion 回填鐵則（含執行紀錄段）/ 測試策略 / git 紀律（顯式 add、禁 push）。

### 1.3 Notion 座標

母案 CM-907：`3a9346da-4cd0-81a5-be6f-f0ddd6d770c6`。子需求卡：.1=`3a9346da-4cd0-810c-9544-c237066d39d4` / .2=`3a9346da-4cd0-8182-8451-f473f1bde2d5` / .3=`3a9346da-4cd0-811d-8d54-cbf81686b661` / .4=`3a9346da-4cd0-81c2-aae3-d8d6af1f8689`。T-4.x：CM-924=`3a9346da-4cd0-815c-b282-c50d5b9d9c3d` / CM-925=`3a9346da-4cd0-815c-be82-eb593a766505` / CM-926=`3a9346da-4cd0-8195-b39c-e58639d5a383`。任務清單 data source：`collection://23c346da-4cd0-8041-955e-000bb6976dd2`（查狀態 SQL：`SELECT "Case No","任務名稱","狀態" ... WHERE "需求編號"='FR-056.4'`）。

### 1.4 repo 座標

- BE：`~/Projects/Billows/Audit-Manager/compliance-manager-be`
- FE：`~/Projects/Billows/Audit-Manager/compliance-manager-fe`
- evidence-agent：`~/Projects/Billows/Audit-Manager/evidence-agent`（pytest 須 `poetry run`，系統 python 缺 gvm）
- DEV DB：`psql -h 192.168.50.188 -p 25432 -U cmmgr -d guidant_ai_dev`，密碼查 BE `.env` DB_SECRET JSON 的 rds_master_password

## §2 教訓（本棒新增，別重蹈）

1. **驗收 subagent 清單塞太重必 context 爆**：56.2 BE 段第一次派整包（8 大項）爆掉；拆三段（每段 ≤6 檢查項）後全過。**每個驗收 subagent scope 上限 ≤6 檢查項**，讀檔紀律必帶：嚴禁讀 .html/.md/docs、grep -n 定位小段 Read ≤80 行、Bash 輸出 head 截斷、pytest 只 tail、超大 vue 檔嚴禁整讀。
2. **runner 的「沒有導覽點」類主張要用 DB ui_routes 複核**：真選單在 DB 不在程式碼，grep 不到 ≠ 不存在（T-2.3 斷頭頁判定就是靠這步定案）。
3. **user 質疑「欄位夠不夠」時做三邊對照**：seed 定義 / connector 消費端 / 上游真實需求——param seed 遺漏就是這樣抓到的。
4. **BE 全量 pytest 有既有 110 failed/34 errors（既有債務，與 FR-056 無關）**：驗收跑回歸時看「FR-056 相關測試全過 + FAILED 清單 grep detection/job 零命中」即可，別被既有紅嚇到。

## §3 半夜鏈工作清單（= cron prompt 的展開版）

### 3a. 檢查 56.4 完成度
Notion SQL 查 FR-056.4 四張卡是否全「修正待驗證」+ `git log --oneline -8`（BE 應多 T-4.1/4.2 commits、FE 多 T-4.3）。未完 → 30 分後再查。

### 3b. 驗收（全完成後，分段派 Sonnet，每段 ≤6 項）
- **段1 BE migration+活庫**：detection_executions 表 migration 鐵則（-- Date:/GRANT/schema_migrations）+ DEV 活庫實查（表在/RLS 在/登記在/tenant_id+org_unit_id）+ evidence source enum 加 DETECTION_TOOL 的全 call site 掃
- **段2 BE 編排+分岔**：completion_mode 分岔正確（auto→呼叫既有 complete_job；manual→不做事）+ **嚴禁動 JobStatus/jedi_flow_engine（git show --stat grep flow_engine|job_status 應零）** + 轉證據 handler 沿用 DRIVE_SYNC 模板（source=DETECTION_TOOL、D11 用 FILE 型別非 REPORT）+ 通知沿用既有信件機制 + result 回收→轉證據的鏈路 pytest
- **段3 BE DDD+回歸**：新層 DDD/session/@transaction/幽靈 WHERE + FR-056 相關 pytest 全過（既有 110 failed 屬債務，見 §2-4）
- **段4 FE 抽屜**：任務執行抽屜 UI + i18n 繁體無簡體 + vite build 過 + 既有頁面回歸（純增量）

### 3c. 缺失 → 直接派修復 subagent（user 已授權，不返工 runner）
修復 subagent 紀律：顯式 git add 逐檔 / commit `fix(fr056): ... (T-4.x follow-up)` / migration 照鐵則套 DEV / 修完派複驗。

### 3d. 全放行 → 交付物
1. **HTML 使用手冊**（派 Sonnet subagent 寫，主 session 只驗收；繁體中文自包含單檔）存 `docs/features/FR-056-2607-detection-tool-integration/user-manual.html`，章節：
   - 檢測工具設定（平台目錄 → 租戶設定頁填 base_url/帳密/port → 憑證加密說明 → 測試連線）
   - 任務設定（規劃頁控制項實作 Tab 點 AO → 任務類型選「檢測工具執行」→ 選工具 → 掃描參數 hosts 等 → 完成模式 manual/auto 差異白話說明）
   - evidence-agent 升級部署（從 FR-039 版升級：git pull 新版 → poetry install（新增 python-gvm）→ 重啟 → capability 確認）
   - 端到端流程（開始執行 → 心跳領工 → 掃描 → 報告自動回收成證據 → 通知信 → 完成分岔）
   - **人工測試 checklist**（含真實 OpenVAS 前置：GVMd 9390 TLS 開放檢查——Docker 版常只開 Unix socket，這是已知部署陷阱）
2. **Notion 新 case**：「FR-056 人工驗證測試（user 手測）」，需求編號 FR-056、狀態 Not started、作業人員留空（user 做）、內文=checklist 摘要+指向 user-manual.html。**開卡前先搜尋防重複**。
3. 母案 CM-907 內文補一行手冊指引。
4. 每步留進度訊息給 user 睡醒看。

### 3e. user 醒來後（等下令才做）
總收尾（spec / SUMMARY / 母案收口 / memory / 執行時間彙整成本分析）。收尾待辦清單見 §10。

## §6 Pre-flight（fresh session 接手先跑）

```bash
cd ~/Projects/Billows/Audit-Manager/compliance-manager-be
git branch --show-current   # feature/scan-plugin-integration；不對停下問 user
git log --oneline -10       # 對照 §11
cd ~/Projects/Billows/Audit-Manager/compliance-manager-fe && git log --oneline -5
cd ~/Projects/Billows/Audit-Manager/evidence-agent && git log --oneline -5
```

## §8 行為規範提醒

- 不切 branch / 不 push / 收尾等 user 下令（半夜鏈授權範圍見 §NIGHT，其外仍禁止）
- 派 subagent 一律 Sonnet（或 Haiku），驗收 subagent 必帶讀檔紀律（§2-1）
- 繁體中文；Notion 先搜尋再開卡；Claude 做的作業人員填「小弟」
- BE 改 service 要 kill -9 重啟才生效（log/app.log 看錯誤）

## §10 不在本期 scope / 收尾待辦（user 醒來裁）

**不做**：Nessus/SonarQube connector / REPORT 證據型別 / jedi_flow_engine 改動 / 執行時間彙整（等收尾令）。

**收尾待辦清單（累積中）**：
1. TaskSetupView.vue 斷頭頁去留（含 fetchTree 404 既有 bug）
2. FE `fetchAOJobs()` 死碼路徑未 map tool 欄位（既有）
3. BE 全量 pytest 既有 110 failed/34 errors 債務盤點
4. 真實 OpenVAS 環境全鏈驗證（需實體 GVMd + 部署 agent 容器；9390 TLS 前置檢查）
5. STG/POC 套全部 fr056 migrations
6. 執行時間彙整成本分析（user 要的模式效率數據，各卡執行紀錄段已在收集）

## §11 關鍵 commits（交接當下；以 origin 對照為準，後段未 push）

BE（fr056 相關，新→舊）：
```
37451cd2 feat(fr056): enrich control-tree jobs with detection-tool binding (T-2.3 rework)
8efbb6b2 feat(fr056): seed OpenVAS param schema (T-2.3 step 0.5)
afdb9b44 fix(fr056): jedt RLS policy delimiter + is_super_admin bug (T-2.2 follow-up)
ea661321 fix(fr056): agent_tasks state machine reject invalid/terminal transitions (T-3.1 follow-up)
c51bd884 fix(fr056): expose detection-tool binding on job read path (T-2.2 follow-up)
d378596e feat(fr056): job-detection-tool binding + param schema read (T-2.2)
1086ee94 feat(fr056): heartbeat task dispatch + ack + result endpoints (T-3.2)
aa916792 feat(fr056): agent_tasks table + state machine + agent capabilities (T-3.1)
a5a7cf4c feat(fr056): add detection_tool job type + BPMN sync (T-2.1)
（更早 T-1.x 見前一棒 handoff §11）
```
FE：
```
5914df2 feat(fr056): rebuild detection_tool job type UI in ProjectPlanningView (T-2.3 返工)
fd2e837 Revert "feat(fr056): add detection_tool job type to task setup page (T-2.3)"
f7d4968 feat(fr056): add detection_tool job type to task setup page (T-2.3)（已被 revert）
06c1fb5 / 0d18938（T-1.5，見前一棒）
```
evidence-agent：
```
35847df feat(fr056): OpenVAS connector (T-3.4)
16f7462 feat(fr056): agent task executor skeleton (T-3.3)
```
（56.4 runner 的 commits 交接後陸續出現，屬預期）

## §12 給 fresh session 的超短 prompt

```
請讀 docs/features/FR-056-2607-detection-tool-integration/handoff/2026-07-26-orchestrator-night-chain-handoff.md 接手 FR-056 主導 session。
先過 🧭 + §NIGHT + 冷接自檢 4 問，再跑 §6 pre-flight。
你的角色是派工+驗收，不自己實作。56.4 runner 執行中；user 已授權半夜自主鏈
（檢查→驗收→subagent 修復→HTML 手冊+Notion case），授權邊界見 §NIGHT。
若已過檢查時間直接手動執行 §3a 起的清單，不必重排 cron。
```