Phase 1 Tasks 2-9 SHIPPED 接手 Handoff — 2026-05-24

1. 不要從 design.md §1.1-§1.3 / plan §Task 2-9 原文抄 code/SQL。design.md §11 是 v1.2 新加的 reconciliation 段，記錄 11 條 spec/reality 偏差，先讀那段（每條 1-2 句 + commit SHA）。plan Task 2-9 已標 ✅ SHIPPED + 接手者重點摘要。

2. 本 session 最大教訓 baked into §11.10 + §11.11：design.md §1.3 SQL 假設的 8+ column 在 DB 根本不存在 → controller pre-dispatch 沒 verify schema → implementer BLOCKED → controller 又把純技術校正包裝成 user 決策題拋出去。修正後 rule：DB-touching task 開工前 controller 親查 \d schema + sample data + tenant resolvability + verify branch on BOTH repos（IDE 會 auto-sync 切 branch，是潛在 risk source），再寫 baked-in prompt。

3. Dev DB 已 migrate：12 leveraged_authorizations + 341 components + 12 FK linked + 0 inventory_items（預期）。3 個 verification gate 全綠。53 orphan rows（8 dev test SSPs）已 skip——Task 12 DROP 舊表前要決定那 53 rows 怎麼辦（archive 還是隨表 drop）。

4. 重新驗證 branch 是接手第一步：IDE 同時管理 3 repo（BE/FE/jedi-oscal）會 auto-sync，dispatch subagent 前必跑：

   git branch --show-current   # 主專案
   cd ~/Projects/Jedicogy/module/jedi-python-package/jedi-oscal && git branch --show-current

   兩個都必須印 feature/ssp-oscal-alignment。否則停下問 user，不自己切。

jedi-oscal 套件（17 commits, branch feature/ssp-oscal-alignment）

ac1d860  fix(oscal): harden InventoryItem M2M contract — log unresolved uids + return actually-written list (PR-3 follow-up)
2162af2  feat(oscal): add InventoryItemDomainService (PR-3 part 6)
646cc38  feat(oscal): add InventoryItem repo interface + impl with M2M write path (PR-3 part 5)
1b22843  feat(oscal): add InventoryItemMapper + mapper unit tests (PR-3 part 4)
c358d8e  feat(oscal): add OscalInventoryImplementedComponent M2M join ORM (PR-3 part 3)
9d0db75  feat(oscal): add OscalInventoryItem ORM (PR-3 part 2)
1281121  feat(oscal): add InventoryItemEntity + QueryEntity (PR-3 part 1)
29b3bf0  feat(oscal): add ComponentDomainService (PR-2 part 5)
f498af1  feat(oscal): add Component repo interface + impl (PR-2 part 4)
697a460  feat(oscal): add ComponentMapper + mapper unit tests (PR-2 part 3)
fdfd317  feat(oscal): add OscalComponent ORM with partial index on leveraged_authorization_uid (PR-2 part 2)
157d2bc  feat(oscal): add ComponentEntity + QueryEntity + enums (PR-2 part 1)
a748205  feat(oscal): add LeveragedAuthorizationDomainService (PR-1 part 5)
fed9970  feat(oscal): add LeveragedAuthorization repo interface + impl (PR-1 part 4)
773c5eb  feat(oscal): add LeveragedAuthorizationMapper (PR-1 part 3)
bf12dc9  feat(oscal): add OscalLeveragedAuthorization ORM (PR-1 part 2)
ab66af0  feat(oscal): add LeveragedAuthorizationEntity + QueryEntity (PR-1 part 1)

（baseline before this session: 6f04da7 chore(jedi-oscal): bump 0.0.17 → 0.0.18）

Tests added: 36 (8 LA + 13 Component + 15 InventoryItem)。Full package pytest 129 passed 全綠。

主專案（6 commits, branch feature/ssp-oscal-alignment）

1f944e2  docs(ssp-oscal-alignment): v1.1 → v1.2 — add §11 reconciliation + plan SHIPPED markers (Phase 1 Tasks 2-9)
c5b43fb  feat(ssp-oscal-alignment): SQL migration step 3 — row count + FK integrity verification (Phase 1 Task 9)
567efe7  feat(ssp-oscal-alignment): SQL migration step 2 — migrate items → leveraged_auth + components (Phase 1 Task 8)
a9712a1  feat(ssp-oscal-alignment): SQL migration step 1 — create 4 OSCAL-correct tables + RLS (Phase 1 Task 7)
2e6849f  feat(ssp-oscal-alignment): wire LeveragedAuth/Component/InventoryItem services in OscalContainer (Phase 1 Task 6)
95e9efd  feat(ssp-oscal-alignment): restructure ParsedExcelEntityBundle for OSCAL Component/LeveragedAuth/InventoryItem split (Phase 1 Task 5)

（baseline: d6fab20 docs(ssp-oscal-alignment): Phase 1 Task 2-3 接手 handoff from earlier today AM）

Tests added: 11 (tests/test_ssp_intermediate_v2_bundle.py)。

未 commit：M pyproject.toml（Task 1 留下 dev-only path dep, line 80 main pin 註解掉、line 91 dev path 取消註解）— 永遠不 stage / commit，Task 13 才還原。

4 個新表已建 + RLS enabled

oscal.ssp_leveraged_authorizations           rowsecurity=t   12 rows
oscal.ssp_components                          rowsecurity=t  341 rows  (164 hw + 165 system + 12 service)
oscal.ssp_inventory_items                     rowsecurity=t    0 rows  (預期 — Phase 2 import 才會有)
oscal.ssp_inventory_implemented_components    rowsecurity=t    0 rows  (M2M join, parent EXISTS subquery policy)

FK linkage

12/12 service components 全部成功 link 到 leveraged_authorizations.uid（leveraged_authorization_uid IS NOT NULL = 12）

舊表保留（Task 12 才 DROP）

oscal.ssp_system_implementation_items — 394 rows, untouched

Orphan filter

Migration WHERE p.tenant_id IS NOT NULL 過濾掉 53 rows / 8 dev test SSPs（blsadmin/blsit fixtures）。Task 12 DROP 前要決策這 53 rows 命運：

• 選項 A：跟舊表一起 DROP（簡單；資料是測試 fixture，反正會丟）
• 選項 B：先 archive 到 oscal.ssp_system_implementation_items_archive（保險；占空間）
• 選項 C：手動清掉 8 個 orphan SSP 對應的 AP/project linkage 不全的記錄

Task 10 — E2E 驗證（DROP 前必跑 gate, Phase 1 最重要）

目的: DROP 舊表前確認新表能撐 Excel + docx import + GET SSP detail roundtrip。

前置 verify（接手 session 跑這個確認沒回退）：

SET app.is_super_admin='t';
SELECT count(*) FROM oscal.ssp_leveraged_authorizations;  -- 必須 12
SELECT count(*) FROM oscal.ssp_components;                 -- 必須 341
SELECT count(*) FROM oscal.ssp_components WHERE leveraged_authorization_uid IS NOT NULL;  -- 必須 12

注意點：

• GET SSP detail API 應已切到讀新表（在哪？尚未驗證，Task 10 第一步應該 grep system_implementation_item_repo 跟 SspSystemImplementationItemEntity 在哪用）
• Task 5 已 break 8 個 caller（design.md §11.10 列表 / plan Task 5 SHIPPED 段）— Task 10 e2e 可能炸這些 caller，需要先修
• Excel import path：SspExcelImportAppService._run_excel_import_pipeline 仍用舊 bundle shape → 會炸；Task 10 寫 e2e 前可能要先用 Task 11 修 caller
• 實際上 Task 10 跟 Task 11 順序可能要調換：先 Task 11 cleanup（套件 + 主專案 caller）→ 再 Task 10 e2e

Task 11 — 套件 PR-4 Cleanup（刪 SspSystemImplementationItemEntity + 改 callers）

範圍:

1. 套件側（jedi-oscal）：刪 SspSystemImplementationItemEntity / SspSystemImplementationItemQueryEntity + 對應 repo / repo impl / mapper / ORM model / domain service
2. 主專案：grep 所有 import 改用新 entity；8+ callers 已知（plan §Task 5 SHIPPED 段列出）：
   • Production: app/oscal/service/ssp_excel_import_app_service.py 6 處
   • Tests: tests/test_a4_reconciliation_orchestrator.py / tests/test_ssp_excel_import_system_characteristic_e2e.py
3. DI container：刪 system_implementation_item_repo / system_implementation_item_domain_service 兩 providers（oscal_containers.py:227, 323-326）

接手 pre-flight：grep 整 codebase 漏網之魚

grep -rn "SspSystemImplementationItem\|ssp_system_implementation_item" --include='*.py' \
  /Users/chouraymond/Projects/Billows/Audit-Manager/compliance-manager-be/ \
  ~/Projects/Jedicogy/module/jedi-python-package/jedi-oscal/

順序提醒：Task 11 跑完整 grep + 改 caller 全綠才能跑 Task 12 DROP。

Task 12 — DROP 舊表

DROP TABLE oscal.ssp_system_implementation_items CASCADE;

CASCADE 會把 FK referencing 一起拿掉，先 grep 確認沒漏。

53 orphan rows 處理（見上方第 3 段）：跑前先決策 A/B/C。

Task 13 — 套件進版 + Nexus 推送 + 主專案 pin 還原

1. 套件 pyproject.toml bump 0.0.18 → 0.1.0（major feature → minor bump per CLAUDE.md「BE/FE 版號 1:1 對齊」段也說 major 重寫才 0.x→1.0；OSCAL alignment 算大改 minor 0.0 → 0.1 reasonable）
2. 套件 commit + push (git push origin feature/ssp-oscal-alignment)
3. 推 Nexus
4. 主專案 pyproject.toml 還原 line 80（uncomment + 改新版號）+ 重 comment line 91 dev path
5. poetry update jedi-oscal
6. 跑 tests / smoke
7. Commit 主專案 pyproject.toml + poetry.lock

⚠️ 這是 push step——CLAUDE.md「push 永遠要 user 明確指示」。Task 13 開工前停下要 user 確認。

Task 14 — Changelog + Handoff/conversation history

1. docs/changelog/2026-05-XX-feat-ssp-oscal-alignment-phase1.md（type=feat，breaking=true 因為 DROP 舊表 + 套件 entity 改）
2. 對話歸檔到 docs/conversation-history/2026-05-24/ssp-oscal-alignment-tasks-2-9/（per CLAUDE.md script）
3. 收口 SUMMARY 寫到 docs/features/FR-028-2605-ssp-oscal-alignment/handoff/2026-05-XX-phase1-SUMMARY.md

Hard rules（subagent dispatch prompt 必加）

• ❌ NEVER git checkout / git switch — 兩 repo 已在 feature/ssp-oscal-alignment
• ❌ NEVER push — user 自決
• ❌ NEVER commit 主專案 pyproject.toml / poetry.lock — dev-only path dep
• ❌ NEVER write password 進 .sql / .md / commit message — 用 PGPASSWORD 環境變數
• ✅ git add 顯式列檔名 — 禁 -A / . / -am
• ✅ 寫 app service test 必加 logger patch autouse fixture（jedi DBLogHandler 對 SessionLocal=None 會炸）

Trust-but-verify 從「subagent DONE 後驗」擴到「dispatch 前 controller pre-flight」

本 session Tasks 7-9 第一輪卡 schema mismatch 的教訓：

• DB-touching task 開工前，controller 親查 \d <table> + sample data + tenant resolvability + verify branch
• Spec vs reality 偏差時，default 是 controller 親查補正 SQL/code 進 prompt，不包裝成 user 決策題
• 除非真的有 trade-off（譬如 53 orphan rows 怎麼處理）才問 user

IDE auto-sync branch 風險

User 用 IDE 一次管 3 repo（BE / FE / jedi-oscal），切 branch 是同步動作。Dispatch subagent 前 dual-repo branch check：

cd /Users/chouraymond/Projects/Billows/Audit-Manager/compliance-manager-be && git branch --show-current
cd /Users/chouraymond/Projects/Jedicogy/module/jedi-python-package/jedi-oscal && git branch --show-current

兩個都必須印 feature/ssp-oscal-alignment。否則停下問 user，不自己切。

Dev DB / cmmgr 用法

• Host / port / db: 192.168.50.188:25432 / guidant_ai_dev
• User: cmmgr (跑 SQL migration / DDL；cm_app 受 RLS 擋，會 INSERT 0 rows silently fail)
• Password: jedi@123! (cm_app + cmmgr 同密碼) — 不入版控
• SET app.is_super_admin='t'; 必跑（cmmgr 也是受 RLS）

• ❌ 不要 commit pyproject.toml/poetry.lock（Task 1 dev-only path dep）
• ❌ 不要 push 任何 branch（user 自決）
• ❌ 不要切 branch（兩 repo 都 in feature/ssp-oscal-alignment）
• ❌ 不要從 design.md §1.3 抄 migration SQL（§11.10 已標 stale；用 .sql 檔）
• ❌ 不要從 plan §Task 2-6 抄 code（§11.1-§11.7 已標 deviation；用 commits 內實際 code）
• ❌ 不要把純技術校正當 user 決策題拋出去（譬如 column 改名）
• ❌ 不要 dispatch subagent 前不 verify branch state（IDE auto-sync risk）

本 session arc 收尾後（Task 14 完成），歸檔指令：

poetry run python scripts/extract_claude_sessions.py \
    --date 2026-05-24 \
    --topic ssp-oscal-alignment-tasks-2-9-implementation \
    --auto

存到 docs/conversation-history/2026-05-24/ssp-oscal-alignment-tasks-2-9-implementation/。

1. 第一件事讀 design.md §11——尤其 §11.10（migration reconciliation）跟 §11.11（process lessons）
2. 第二件事：跑兩 repo git branch --show-current 確認在 feature/ssp-oscal-alignment
3. 第三件事：跑 dev DB spot check 確認 12 leveraged + 341 components 還在
4. 第四件事：grep SspSystemImplementationItem 看 caller 範圍（決定 Task 10 vs Task 11 順序）
5. Task 11 跟 Task 10 順序可能要調換——Task 5 已 break 8 callers，Task 10 e2e 跑前需要 Task 11 cleanup 全部改完
6. Trust but verify 雙向：dispatch 前 controller pre-flight 確認環境 + dispatch 後 trust-but-verify subagent 結果
7. 不要重做 brainstorm——docs/analysis/2026-05-24-ssp-oscal-alignment-phase1-brainstorm.md 已有 6 個 Topic 拍板
8. 任何 spec/reality 偏差——controller 親查 + baked-in prompt 修正；不要包裝成 user 決策題