# Handoff Prompt — A4 Session E → F（T6 + T7 + T8 ship → T9 + T10 + T11 開工）

> **使用方式**：把下方「交接 prompt 本體」整段貼到新 session 即可接手。
> **前置狀態**：A4 Session E BE shipped（T6 / T7 / T8 三 commit + 1 docs 收尾 commit）；working tree 乾淨（除 pre-existing pyproject.toml dev-path + 2 zip）。

---

## 交接 prompt 本體（從此貼到新 session）

```
我要進 SSP 匯入匯出 Phase 2 / A4 Session F — T9 + T10 + T11（unit/integration test 補齊 + cucumber regression + 收尾 SUMMARY）。

執行策略
========

Session F 是 A4 task arc 的收口 session。重點：
1. T9 BE unit + integration test 補齊（plan §Task 9 要求 ~110-140 個 A4 test；Session E 累計 ~155 個已超過下限，視 acceptance 缺哪幾種 boundary case 補齊）
2. T10 cucumber regression（跨 repo — compliance-manager-test）
3. T11 收尾：design §11 補齊（如有 T9/T10 階段新偏差）+ tracker README + 對話歷史 dump（task arc 收口）+ summary 報告

可以用 subagent 平行 T9（unit test 補齊）跟 T10（cucumber，跨 repo）— 兩段完全獨立。T11 收尾必須 sequential 等 T9/T10 ship 後。

前置狀態
========

Branch: feature/ssp-import-export-phase2（BE，48 commits 未 push 待 user 手動推）

A4 Session 進度：
- Session A (design-A4.md) shipped：1de5f51
- Session B (implementation-plan-A4.md) shipped：57bcb2e
- Session C T0+T1+T2 (base + 5 reconciler skeleton + orchestrator + DI) shipped：57a9567 + 72ef229
- Session D T3+T4+T5 (reconciler full algo + A3 retroactive + A2 §15.3 整併) shipped：7c2b860 + 8936aab + 9d7c102
- Session E T6+T7+T8 (SSP shell + 5 WriteStrategy + 8-step pipeline) shipped：40c4a12 + 579eb76 + 78118eb
- Session E 收尾 docs shipped：<E.收尾 commit hash 待填>

A4 BE 累計 8 個 feat commit + 1 個 docs 收尾 commit；test 累計 250+ a4 test 全綠（含 a3 67 + a2 ssp_excel 29）。

jedi-oscal 仍 path-dep；pyproject.toml dev-path 改動仍未 commit（feature 整體完工後 user 拍板才一次性 bump 版本）。

design §11.1.10-11.1.16 已補 Session E 7 條偏差紀錄（E1: GRC_412066→412026 / E2: SspSysImpl link 走 scope_type/scope_id / E3: DI 名 main / E4: ModuleFrame 無 oscal_profile_id → profile_domain 兩段式 / E5: base class 加速策略 / E6: by-key 對齊 helper / E7: dep 從 11→12）。

Session F 範圍
==============

T9 — Unit + Integration Test 補齊（implementation-plan-A4.md §Task 9）

目標：補到 design §8 acceptance（A4 累計 ~110-140 個 test）。Session E 累計 ~155 個已過下限，但缺幾種 boundary case：

- 9.1 reconciler 邊界 case：
  - Device：雙欄不同 ip / IP 空 / multiple match / 純 fallback 三階段排序
  - InfoSystem：system_owner_label 解析失敗仍 set matched_info_system_id / abbr 配對 / name 空
  - Leveraged：candidate cache lifecycle / fuzzy 多 candidate 取第一 / suffix 無剔除 → UNMATCHED
  - CatalogControl / AssessmentObjective：catalog_id missing / parent 配不到 AO unmatched
- 9.2 WriteStrategy 邊界 case：5 strategy 各加 3 個（batch 寫入 / domain service exception swallow / empty list 不 fail）
  - 注意：Session E 寫 T7 時，Device/InfoSys/Leveraged 共用 base class 已涵蓋 batch + exception 在 test_a4_write_strategy_base.py，subclass 不需重測；Control/AO 跨兩張獨立 table 才需個別補
- 9.3 integration test：5 個 entity 從 Excel → reconcile → write 全鏈跑通（mock 各層）
  - 注意：Session E test_a4_write_all_data_pipeline.py 已有 4 個 pipeline test（superset / update / skip when dep None / AO sci_id 注入）— 9.3 補的是「Excel → reconciler → write 端到端」整段串通的全鏈整合，比 pipeline test 更上層

Commit：`test(oscal): A4 T9 unit + integration tests`

T10 — Cucumber Regression（compliance-manager-test repo）

跨 repo work — 在 `~/Projects/Billows/Audit-Manager/compliance-manager-test/` 開 branch。

新建 `features/regression/module-frame/06-ssp-excel-import-entity-match.feature` 含 5 scenarios：
- control_id 對到 catalog 內 control (exact)
- device matched_device 下拉選定 (user_selected)
- info_system name 對到 tenant entity (exact)
- leveraged provider fuzzy 對到 Party (fuzzy_name_prefix)
- AO objective_id 父 control 配到後自身配到 (exact)

step + page object 沿 A3 cucumber regression pattern（compliance-manager-test/feature/a3-ssp-party-match-regression 已 ship 在 commit 27e52fe）。

Cucumber 跑通 → ship。Env 未配齊（需 fixture seed device/info_system/Party）允許 partial ship — 沿 A1/A2/A3 partial ship 先例。

Commit (test repo)：`test(compliance-manager-test): A4 T10 cucumber entity match regression`

T11 — A4 task arc 收尾（implementation-plan-A4.md §Task 11）

完整收尾流程（按 CLAUDE.md「做 summary 觸發完整收尾」）：

1. 跑全 pytest 確認 0 regression（Session E 已驗，T9 ship 後再驗一次）
2. 規範文件齊全度：
   - changelog：Session E 已寫 `docs/changelog/2026-05-20-feat-ssp-excel-import-phase2-a4-write-pipeline.md`；T9/T10 可合併補一個 `2026-05-XX-test-a4-tests-and-cucumber.md` 或併入 final 收尾 changelog
   - design §11.1：Session E 已補 7 條（11.1.10-11.1.16）；T9/T10 若有新偏差再補 11.1.17~
   - issue：若 T9/T10 發現新 root cause bug，開 `docs/issues/pending/<...>.md`
3. 對話歷史歸檔（cross-session task arc 收口）：
   - `docs/conversation-history/<YYYY-MM-DD>/ssp-import-export-phase2-A4/` 目錄
   - 依 phase 拆 `part-NN-of-NN-<sub-topic>.md`（A 設計 / B plan / C reconciler / D reconciler-details / E write-pipeline / F test-cucumber）
   - **不做格式化 / 不過濾 / 不二次加工** — 使用者匯出的原始對話直接寫入
4. 產 SUMMARY 報告 → `docs/features/FR-011.2-2605-ssp-import-export-phase2/handoff/2026-05-XX-a4-SUMMARY.md`
   - commits 清單（A4 全 phase 8+ commits）+ test 累計 / 改動範圍 / 行為差異
   - 規範文件清單（changelog / design §11 / tracker / cucumber feature）
   - 已知 follow-up（A5 phase / F-A4-cucumber-extra / F-A4-refactor）
   - 部署 handover：jedi-oscal 仍 path-dep；feature 整體 ship → user 拍板 → bump jedi-oscal 版本 → 推 Nexus → 主專案 pin 新版本
5. Tracker README.md 更新：
   - A4 row 狀態改 **「BE shipped ✅ + Cucumber 視 env 配齊」**（Session E 已標 BE shipped；T10 ship 後再標 cucumber 段）
   - 整段 task arc 收口在 ledger

Session F 三 task 全 ship 後，產 handoff F→A5 prompt（如果接 A5；或者整個 A4 收口進 archived 狀態）。

開工 SOP
========

第一步：必讀文件（順序）

1. 本 handoff prompt（你正在看）
2. docs/features/FR-011.2-2605-ssp-import-export-phase2/implementation-plan-A4.md §Task 9 / §Task 10 / §Task 11
3. docs/features/FR-011.2-2605-ssp-import-export-phase2/design-A4.md §11.1.10-11.1.16（Session E 落地偏差）
4. docs/changelog/2026-05-20-feat-ssp-excel-import-phase2-a4-write-pipeline.md（Session E 完整 ship 紀錄）
5. A3 cucumber pattern 參考：compliance-manager-test commit 27e52fe（branch feature/a3-ssp-party-match-regression）
6. tests/test_a4_*.py 既有 9 個 test file 看 boundary case 覆蓋現況

讀完後給「我看完了，準備 T9 開工」確認。

第二步：T9 開工（可走 subagent 平行）

不要 subagent 平行：T9 只動 tests/，全在主 session 順做更快（每個 test 1-2 個 file，加上不需 reconciler 演算法的細節 context）。
要 subagent 平行：T9 + T10 兩條獨立工作 — T9 在主 repo / T10 跨 repo。可以 dispatch 2 個 subagent 同時做。

但 T9 跟 T10 都有 user 拍板的步驟（feature 寫法 / commit message 樣板），subagent 平行需先把 prompt 寫清楚。建議：**T9 順做（30-60 min）→ T10 平行（subagent dispatch 給 compliance-manager-test repo）→ T11 收尾**。

第三步：T10 開工（跨 repo）

切 cd ~/Projects/Billows/Audit-Manager/compliance-manager-test/，工作完整指引在 plan §Task 10。

切回 BE：cd ~/Projects/Billows/Audit-Manager/compliance-manager-be/。

第四步：T11 收尾

按上方收尾 5 步驟做。

鐵律（沿用 A0.1 + A1 + A2 + A3 + A4 全部）
==========================================

1. 顯式 git add <file>，禁 -am / -A — commit 前 git status --short 確認
2. jedi-oscal 維持 path-dep，不 bump 版本不推 Nexus（feature 整體完工才 bump）
3. pyproject.toml dev-path 改動不該 commit
4. BE 重啟必 lsof -ti:8000 | xargs kill -9（T9 補 test 不需重啟；T10/T11 cucumber 跑 e2e 才需要）
5. 改 BE service code 後必提醒 user 重啟 — BE 沒 hot reload
6. DDD 嚴格分層 — Route 不碰 DB，App Service @transaction
7. 不寫 docstring / 註解除非真有 non-obvious 的 why
8. Test 用 mock 包 logger 避開 jedi DBLogHandler 撞 SessionLocal=None；@transaction 用 patch_session_scope
   - patch path: `app.oscal.service.ssp_excel_import_app_service.logger`
9. T9/T10 若發現新偏差 → 補 design §11.1.17~
10. 跨 repo 切換時提醒 user：cucumber 在 compliance-manager-test repo，commit / branch 分開
11. 重大決策 → docs/analysis/YYYY-MM-DD-<topic>.md
12. 重型 bug / 跨域問題 → docs/issues/pending/YYYY-MM-DD-<title>.md
13. Handoff 文件統一放 docs/features/<feature>/handoff/
14. 階段性 commit 不用問
15. Subagent dispatch prompt 必加「git add 顯式檔名，禁用 -am」
16. 套件異動需 user 拍板（jedi-* 加欄位 / 改 service 簽章前必先提）

Session F 預估規模
==================

- T9: 0.5d（~20-30 個 boundary case 補齊；累計 a4 ~155 → ~180 個）
- T10: 0.5-1d（5 scenarios feature + step + page object；跨 repo work）
- T11: 0.5d（changelog / design §11 / 對話歷史 / SUMMARY / tracker 更新）

總計：~1.5-2d / 3 commit (BE T9) + 1 commit (test repo T10) + 1 commit (BE T11 docs)。

不在 Session F 範圍
====================

- A5 phase（預覽 UI + Confirm 寫入；用 Session E ship 的 _update_parsed_result_with_reconcile 回填的 matched_*_id / match_method）
- jedi-oscal 版本 bump + Nexus 發版（user 拍板才做）
- BE / FE / test 跨 repo merge 到 main（user 手動推）

謝謝。
```

---

## 收口清單（A4 E → F 端）

本 handoff prompt commit 後，新 session 接手即可：

1. 讀 6 個必讀文件（handoff + plan-A4 §Task 9-11 + design §11.1.10-16 + changelog + a3 cucumber pattern + existing test 覆蓋現況）
2. T9 BE unit + integration test 補齊（plan §Task 9 範圍）
3. T10 cucumber regression（compliance-manager-test repo）
4. T11 A4 task arc 收尾（規範文件齊全度 + SUMMARY + 對話歷史 + tracker）
5. Session F 完成 → A4 task arc 收口；準備接 A5（UI 預覽配對）或進 Track B（SSP 匯出）