SSP OSCAL Alignment — Phase 1 COMPLETE Mini-Summary — 2026-05-24

✅ 把 OLD 單一 SspSystemImplementationItemEntity（implementation_type 區分 hardware/system/leveraged-authorization 3 族）拆成 OSCAL-correct 3 entity（LeveragedAuthorization / Component / InventoryItem + M2M join），落地到 DB + 套件 + 主專案 BE 全層。

✅ 12 leveraged_authorizations + 341 components（164 hw + 165 system + 12 service）migrate 完成且 verified。

✅ 18 個主專案 callers refactor 完成（含 6 個 write strategies + 3 個 context services + ssp_versioning clone logic）。

✅ jedi-oscal 套件 9 個舊 file 刪光、4 個 surgical clean，pytest 從 86 → 84 passed（-2 過時 type-validation tests）。

✅ 主專案 pytest 102 passed, 1 skipped, 0 failed。BE import smoke 9/9 OK。

✅ 舊表 oscal.ssp_system_implementation_items（394 rows） + 舊 M2M oscal.ssp_inventory_item_components（0 rows） 全 DROP，53 orphan dev test fixtures 一併清掉。

Task 10 (E2E)

Phase 1+2 是同一 deploy unit（per design.md §3），Phase 2 會重設計 import confirm pipeline。此時間點寫 E2E test 也是 throwaway——pytest 102 + smoke 9/9 已涵蓋 unit + import smoke 層級；DB migration 已有 3 verification gate（Task 9）。E2E 留到 Phase 2 confirm pipeline 完工後一起寫。

Task 13 (套件進版 + push)

Phase 1+2 綁定 deploy（避免「adapter 已輸出新 bundle 但 confirm path 還沒上」中間態），partial release 沒意義。繼續用 poetry path dependency 跑 Phase 2 開發，Phase 1+2 都 ship 時才 bump + push + 還原 pin。

jedi-oscal（18 commits，baseline 6f04da7）

主專案（15 commits，baseline d6fab20）

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 populates)
oscal.ssp_inventory_implemented_components    rowsecurity=t    0 rows  (M2M join)

舊表狀態：

• oscal.ssp_system_implementation_items → DROPPED ✅
• oscal.ssp_inventory_item_components (OLD M2M) → DROPPED ✅

FK linkage：12/12 service components 全綁回 leveraged_authorizations.uid。

Production / API

1. API contract 變動風險（Task 11B-2 follow-up flag）：SspImportTemplateAppService._build_info_systems 回傳 dict 把 implementation_type key 改成 component_type。Excel template 下游若依賴 "implementation_type" key，Phase 2 e2e 要驗。
2. project_device_route 410-Gone 未實作（Task 11B-3 發現）：tests/test_c3_scope_migration.py::test_gone_response_uses_grc_error_code 用 @pytest.mark.skip，需獨立任務實作 410 route。
3. Leveraged delete 後 orphan service-Component（Task 11B-2 follow-up 架構決策）：用戶從 SSP 編輯 dialog 刪 LA 時只刪 LA row，留 linked Component 變 orphan（leveraged_authorization_uid 指向已刪 LA.uid）。Phase 4 FE 重設計時要處理。
4. AbstractSspComponentWriteStrategy.write() sys_impl_main_id dead param（Task 11B-1 review minor）：caller signature compat 保留，但實際內部不用。Phase 2 完成 import pipeline 後可從 caller chain 全刪。

工程流程

5. 未 push：兩 repo 都還 local。push 等 user 明確指示（per CLAUDE.md「push 永遠要 user 明確指示」）。
6. jedi-oscal pyproject.toml 還未 bump（Task 13 延後）。主專案 pyproject.toml 還是 path dep 形式（M but unstaged）。Phase 1+2 一起 ship 才 bump + 還原。
7. 觀察開發流程（user request）：本 session 嘗試了 subagent-driven mode。後續 retrospective 討論：subagent 數量 / review loop / token / wall clock 哪邊可優化。

你接手 SSP OSCAL Alignment 開發。Phase 1 完整 SHIPPED（11/14 tasks，跳 Task 10 E2E + Task 13 進版）。請按以下順序讀文件：

1. docs/features/FR-028-2605-ssp-oscal-alignment/handoff/2026-05-24-phase1-COMPLETE-SUMMARY.md（本文件 — 5 分鐘）
2. docs/features/FR-028-2605-ssp-oscal-alignment/design.md §11 (11 條 spec/reality reconciliation)
3. docs/features/FR-028-2605-ssp-oscal-alignment/design.md §3 (5 phase 概覽) + §4「Phase 2 — Import Pipeline 對接」段
4. docs/features/FR-028-2605-ssp-oscal-alignment/implementation-plan-phase1.md SHIPPED markers（skim — 想清楚 Phase 1 留下的 followup）

開工前 pre-flight：
1. 兩 repo 都應 print `feature/ssp-oscal-alignment`：
   git branch --show-current
   git -C ~/Projects/Jedicogy/module/jedi-python-package/jedi-oscal branch --show-current
2. Dev DB 確認 Phase 1 final state 還在：
   PGPASSWORD='jedi@123!' psql -h 192.168.50.188 -p 25432 -U cmmgr -d guidant_ai_dev -c "
   SET app.is_super_admin='t';
   SELECT
     (SELECT count(*) FROM oscal.ssp_leveraged_authorizations) AS la,
     (SELECT count(*) FROM oscal.ssp_components) AS comp,
     (SELECT count(*) FROM oscal.ssp_inventory_items) AS inv,
     EXISTS (SELECT 1 FROM information_schema.tables
             WHERE table_schema='oscal' AND table_name='ssp_system_implementation_items') AS old_main_exists;"
   預期: la=12, comp=341, inv=0, old_main_exists=f
3. 主專案 + jedi-oscal pytest 都應綠：102 + 84 passed

下個任務 — Phase 2「Import Pipeline 對接」（design.md §4）：
- 2.1: ssp_excel_import_app_service 改走新 entity write path
- 2.2: docx import 對接（Stage 1 docx-import-parity 上接此處）
- 2.3: schema_version migrating logic（Phase 1+2 ship 時的中間 parse_jobs 處理）

開工模式: subagent-driven mode，每 task 派 implementer + spec reviewer + code quality reviewer（per superpowers:subagent-driven-development）。

Phase 1 跟 Phase 2 同一 deploy unit，收口要做：

1. Full changelog（Phase 1 + Phase 2 batch）：

   • docs/changelog/2026-05-XX-feat-ssp-oscal-alignment-phase1-phase2.md
   • frontmatter: type=feat, breaking=true
   • 內容包括 Phase 1 33 commits + Phase 2 commits 兩 phase 摘要

2. Conversation history extraction：

   # 把 2026-05-24（Phase 1 全部）+ Phase 2 開發日期一起跑
   poetry run python scripts/extract_claude_sessions.py \
       --date 2026-05-24 \
       --topic ssp-oscal-alignment-phase1 \
       --auto
   # Phase 2 日期再跑一次

   存到 docs/conversation-history/<date>/ssp-oscal-alignment-phase1/ 跟 .../ssp-oscal-alignment-phase2/。

3. Task 13 完整執行（Phase 1+2 ship 時）：

   • jedi-oscal: pyproject.toml bump 0.0.18 → 0.1.0 + commit + push + 推 Nexus
   • 主專案: pyproject.toml 還原 line 80 pin 新版本 + 重 comment line 91 path dep
   • poetry update jedi-oscal
   • smoke + commit pyproject.toml + poetry.lock

4. Phase 1 + Phase 2 SUMMARY：總收口報告寫到 docs/features/FR-028-2605-ssp-oscal-alignment/handoff/<YYYY-MM-DD>-phase1-phase2-FINAL-SUMMARY.md，本 mini-summary 是子集。

Phase 1 Tasks 2-9 實作過程中跟 design.md §1-§8 原始 spec 有 11 條偏差（mostly ORM style / UUID type / repo interface pattern / DB schema reality 對不上原 spec assumptions），全部記在 design.md §11。最大的 trap §11.10：design.md §1.3 寫的 migration SQL 跟實際 DB schema 大幅偏離（假設的 8+ FedRAMP columns 不存在、tenant 解析要 4-table chain、discriminator 是 implementation_type 不是 category）— Phase 2 開工者先讀 §11.10 + §11.11，避免再踩坑。