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

| 項目 | 內容 |
|---|---|
| 本 session 日期 | 2026-05-24（從早上 brainstorm/plan 接續同日下午實作）|
| 涵蓋 Phase 1 進度 | Task 1 (dev path dep, no commit) + Task 2-9 全部 SHIPPED |
| Branch（兩 repo 一致）| `feature/ssp-oscal-alignment` |
| jedi-oscal 套件 commits | 17（local，未 push）：`ab66af0..ac1d860` |
| 主專案 commits | 6（local，未 push）：`95e9efd..1f944e2` |
| Pushed? | ❌ **兩 repo 都還在 local**（user 自決時機）|
| Working tree (主專案) | `M pyproject.toml` 一個（Task 1 dev-only path dep，Task 13 才還原）|
| Working tree (套件) | clean（除上層 sibling package untracked）|
| Dev DB 狀態 | 4 新表已建 + RLS + 12 leveraged + 341 components migrated + verified |
| 下個 session 工作 | Phase 1 **Tasks 10-14**（E2E / cleanup / DROP / bump+push / handoff/changelog）|

---

## TL;DR — 接手前必讀（3 分鐘）

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 前必跑：
   ```bash
   git branch --show-current   # 主專案
   cd ~/Projects/Jedicogy/module/jedi-python-package/jedi-oscal && git branch --show-current
   ```
   兩個都必須印 `feature/ssp-oscal-alignment`。否則停下問 user，不自己切。

---

## 1. 本 session 完成的 commits（總 23 commits across 2 repos）

### 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 才還原。

---

## 2. 接手前必讀文件順序

| # | 文件 | 用途 | 重要 |
|---|---|---|---|
| 1 | `docs/features/FR-028-2605-ssp-oscal-alignment/design.md` v1.2 §11 (lines ~910+) | **11 條 spec/reality reconciliation**，每條 1-2 句 + commit SHA | ⭐ MUST READ |
| 2 | `docs/features/FR-028-2605-ssp-oscal-alignment/implementation-plan-phase1.md` Task 2-9 SHIPPED 段 | 接手者重點摘要 + 對 Tasks 10-14 影響 | ⭐ MUST READ |
| 3 | 本 handoff | 接手 context + 環境狀態 | ⭐ MUST READ |
| 4 | `scripts/sql/2026-05-24-ssp-oscal-alignment-*.sql` 3 個檔 | Task 7-9 實際 SQL（不是 design.md §1.3）| 跑 Task 10 / 11 / 12 必看 |
| 5 | `docs/analysis/2026-05-24-ssp-oscal-alignment-phase1-brainstorm.md` | 6 個 Topic 拍板（dev cutover / FK warn-but-allow / type='other' 等）| skim |
| 6 | `docs/features/FR-028-2605-ssp-oscal-alignment/design.md` v1.2 §1-§8 + §1.4 | 整體 spec — 接手 Task 10+ 需懂 OSCAL alignment 大方向 | skim 含 §11 forward-pointers |

---

## 3. Dev DB 當前狀態（cmmgr@192.168.50.188:25432/guidant_ai_dev）

### 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 不全的記錄

---

## 4. Tasks 10-14 接手指南

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

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

**前置 verify**（接手 session 跑這個確認沒回退）：
```sql
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 漏網之魚
```bash
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 舊表

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

---

## 5. 重要環境 / 規範提醒（per CLAUDE.md + 本 session 教訓）

### 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：
```bash
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）

---

## 6. 不要做的事（避雷清單）

- ❌ 不要 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）

---

## 7. 對話歸檔提醒

本 session arc 收尾後（Task 14 完成），歸檔指令：
```bash
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/`。

---

## 8. 給下個 Claude 的話

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 決策題

---

## 附：路徑速查

| 用途 | 路徑 |
|---|---|
| Spec v1.2 + §11 reconciliation | `docs/features/FR-028-2605-ssp-oscal-alignment/design.md` |
| Implementation plan + SHIPPED markers | `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-tasks-2-9-shipped-handoff.md` |
| 早上 handoff（brainstorm/plan 收尾 → Tasks 2-3 開工前）| `docs/features/FR-028-2605-ssp-oscal-alignment/handoff/2026-05-24-phase1-task2-3-handoff.md` |
| Task 7-9 SQL（不是 design.md §1.3）| `scripts/sql/2026-05-24-ssp-oscal-alignment-{create-tables,migrate-data,verification}.sql` |
| 套件 root | `~/Projects/Jedicogy/module/jedi-python-package/jedi-oscal/` |
| 套件 entity reference | `jedi_oscal/domain/entity/base/oscal_party_entity.py` |
| Tasks 2-4 新 entities | `jedi_oscal/domain/entity/base/oscal_{leveraged_authorization,component,inventory_item}_entity.py` |
| Subagent skill SOP | `~/.claude/plugins/cache/claude-plugins-official/superpowers/5.0.5/skills/subagent-driven-development/` |