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

| 項目 | 內容 |
|---|---|
| Phase | **Phase 1 / 5 — COMPLETE** |
| 日期區間 | 2026-05-24 全日（早上 brainstorm/plan + 下午 Tasks 2-9 + 晚上 Tasks 11-12-14）|
| Branch（兩 repo 一致）| `feature/ssp-oscal-alignment` |
| 完成 Tasks | 1, 2, 3, 4, 5, 6, 7, 8, 9, 11, 12, 14（11 / 14）|
| 跳過 Tasks | 10（E2E）、13（套件進版+push）— 詳見下方「為何跳過」段 |
| 主專案 local commits | **15**（全 local，未 push）|
| jedi-oscal local commits | **18**（全 local，未 push）|
| 主專案 working tree | `M pyproject.toml`（Task 1 dev-only path dep，**永遠不 stage**，Task 13 才還原；併入 Phase 2 收尾）|
| jedi-oscal working tree | clean |
| Dev DB | 4 新 OSCAL 表 + RLS + 12 LA + 341 components + 12 FK linked；舊表 + 舊 M2M 全 DROP |
| 下一步 | **Phase 2 — Import Pipeline 對接**（6d 預估）|

---

## TL;DR — Phase 1 達成

✅ 把 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 一併清掉。

---

## 1. Phase 1 Tasks 最終狀態

| # | Task | Status | Notes |
|---|---|---|---|
| 1 | 主專案 pyproject.toml path dep | ✅ 落地（dev-only, M pyproject.toml）| Task 13 還原前一直留 |
| 2 | jedi-oscal PR-1 LeveragedAuth | ✅ SHIPPED | 5 commits |
| 3 | jedi-oscal PR-2 Component | ✅ SHIPPED | 5 commits + partial index |
| 4 | jedi-oscal PR-3 InventoryItem + M2M | ✅ SHIPPED | 6 commits + 1 follow-up |
| 5 | 主專案 ParsedExcelEntityBundle restructure | ✅ SHIPPED | `95e9efd` |
| 6 | DI container wire 3 services | ✅ SHIPPED | `2e6849f` |
| 7 | DB Step 1 — 建 4 表 + RLS | ✅ SHIPPED | `a9712a1` |
| 8 | DB Step 2 — migrate data | ✅ SHIPPED | `567efe7` |
| 9 | DB Step 3 — verification gates | ✅ SHIPPED | `c5b43fb` |
| 10 | E2E 測試 | ⏭ **SKIPPED**（user 拍板）| Phase 2 會重設計 confirm pipeline，現寫 throwaway |
| 11A | jedi-oscal 套件 cleanup + 主專案 DI 移除 | ✅ SHIPPED | jedi-oscal `ebadfe8` / 主專案 `2776d15` + `f9e6de7` |
| 11B-1 | Domain write strategies refactor | ✅ SHIPPED | `8a81c22` + `5eaee30` (review fix) |
| 11B-2 | App services refactor（含 follow-up 3 BLOCKED 解決）| ✅ SHIPPED | `7d1d0a7` + `176c977` |
| 11B-3 | Tests refactor + backward-compat shims 清理 | ✅ SHIPPED | `94891eb` |
| 12 | DROP 舊表 + 53 orphan + 舊 M2M | ✅ SHIPPED | `af3b095` |
| 13 | jedi-oscal bump 0.0.18 → 0.1.0 + Nexus + 主專案 pin 還原 | ⏭ **DEFERRED** to Phase 1+2 ship | user 自決時機 |
| 14 | Mini-handoff（本文件）| ✅ SHIPPED | full changelog 延到 Phase 1+2 ship |

---

## 2. 為何跳過 Task 10 / 13（user 拍板）

### 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。

---

## 3. 兩 repo commits 全清單

### jedi-oscal（18 commits，baseline `6f04da7`）

| Commit | 摘要 |
|---|---|
| `ebadfe8` | refactor(oscal): remove deprecated SspSystemImplementationItem (Task 11A) |
| `ac1d860` | fix(oscal): harden InventoryItem M2M contract (PR-3 follow-up) |
| `2162af2` | feat(oscal): add InventoryItemDomainService (PR-3 part 6) |
| `646cc38` | feat(oscal): add InventoryItem repo + M2M write path (PR-3 part 5) |
| `1b22843` | feat(oscal): add InventoryItemMapper + tests (PR-3 part 4) |
| `c358d8e` | feat(oscal): add OscalInventoryImplementedComponent M2M 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 + impl (PR-2 part 4) |
| `697a460` | feat(oscal): add ComponentMapper + tests (PR-2 part 3) |
| `fdfd317` | feat(oscal): add OscalComponent ORM with partial index (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 + 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) |

### 主專案（15 commits，baseline `d6fab20`）

| Commit | 摘要 |
|---|---|
| `af3b095` | **Task 12** — SQL step 4 DROP 舊表 + 舊 M2M |
| `f9e6de7` | Task 11A 收尾 — chore stale comment update |
| `2776d15` | **Task 11A** — 移除主專案 DI 舊 providers |
| `94891eb` | **Task 11B-3** — 移 3 shims + migrate 11 tests |
| `176c977` | **Task 11B-2 follow-up** — 3 context services props JSONB 收尾 |
| `7d1d0a7` | **Task 11B-2** — app services + project layer refactor |
| `5eaee30` | Task 11B-1 review fix — LeveragedWriteStrategy tighten except scope |
| `8a81c22` | **Task 11B-1** — domain write strategies refactor |
| `af0ea33` | docs — Phase 1 Tasks 2-9 SHIPPED handoff |
| `1f944e2` | docs — design.md v1.1 → v1.2 §11 reconciliation |
| `c5b43fb` | Task 9 — SQL verification |
| `567efe7` | Task 8 — SQL migrate data |
| `a9712a1` | Task 7 — SQL create tables + RLS |
| `2e6849f` | Task 6 — DI wire 3 services |
| `95e9efd` | Task 5 — ParsedExcelEntityBundle restructure |

---

## 4. Dev DB 最終狀態（cmmgr@192.168.50.188:25432/guidant_ai_dev）

```
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。

---

## 5. 規範文件齊全度 / 沒齊全的

| 項目 | 狀態 |
|---|---|
| design.md v1.2 + §11 reconciliation（11 條 deviations） | ✅ |
| implementation-plan-phase1.md + SHIPPED markers | ✅ |
| handoff（本文件） | ✅ |
| changelog | ⏸ **延後** — 跟 Phase 2 ship 一起 batch 寫（CLAUDE.md「收尾才 batch 寫」+ Phase 1+2 同一 deploy unit）|
| conversation-history JSONL extract | ⏸ **延後** — 同上 |
| analysis 文件 | ✅ design.md §11 已涵蓋本 session 重大決策（不另寫）|

---

## 6. 已知 follow-ups（Phase 2 開工前注意）

### 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 哪邊可優化。

---

## 7. 給 Phase 2 接手 session 的 prompt（直接複製貼）

```
你接手 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）。
```

---

## 8. 提醒 — Phase 2 收尾時要做的事（changelog / conversation history）

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**：
   ```bash
   # 把 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 是子集。

---

## 附錄 A — 為何 §11 reconciliation 是必讀

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**，避免再踩坑。

## 附錄 B — 路徑速查

| 用途 | 路徑 |
|---|---|
| Spec v1.2 + §11 reconciliation | `docs/features/FR-028-2605-ssp-oscal-alignment/design.md` |
| Implementation plan | `docs/features/FR-028-2605-ssp-oscal-alignment/implementation-plan-phase1.md` |
| Brainstorm 6 Topic 拍板 | `docs/analysis/2026-05-24-ssp-oscal-alignment-phase1-brainstorm.md` |
| 本 handoff | `docs/features/FR-028-2605-ssp-oscal-alignment/handoff/2026-05-24-phase1-COMPLETE-SUMMARY.md` |
| 早段 handoff（brainstorm 收尾 → Tasks 2-3 開工前）| `docs/features/FR-028-2605-ssp-oscal-alignment/handoff/2026-05-24-phase1-task2-3-handoff.md` |
| Tasks 2-9 SHIPPED handoff（中段）| `docs/features/FR-028-2605-ssp-oscal-alignment/handoff/2026-05-24-phase1-tasks-2-9-shipped-handoff.md` |
| SQL migration（Task 7-9 + 12）| `scripts/sql/2026-05-24-ssp-oscal-alignment-*.sql` 4 個檔 |
| 套件 root | `~/Projects/Jedicogy/module/jedi-python-package/jedi-oscal/` |
| 新 entities | `jedi_oscal/domain/entity/base/oscal_{leveraged_authorization,component,inventory_item}_entity.py` |