# Phase 1 Task 2-3 接手 Handoff — 2026-05-24

| 項目 | 內容 |
|---|---|
| 本 session 日期 | 2026-05-24（接續同日上一份 handoff）|
| Branch | `feature/ssp-oscal-alignment`（新開、本 session 切的）|
| Latest commit | `6f5be72`（plan 寫好）|
| 主專案 working tree | `pyproject.toml` 有 modified 改動但 **不 commit**（dev-only path dependency，Task 1 留下）|
| 套件 working tree | clean（除上層 .DS_Store / 其他 package CLAUDE.md，無關）|
| 套件最新 commit | `6f04da7 chore(jedi-oscal): bump 0.0.17 → 0.0.18` |
| Pushed? | ❌ ssp-oscal-alignment 新 branch **沒 push 過 origin**（user 自行決定何時 push）|
| 下個 session 工作 | Phase 1 **Task 2 + Task 3**（套件側 PR-1 LeveragedAuth + PR-2 Component 縱切片）|

---

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

1. **本 session 完成 brainstorm SOP + writing-plans SOP + Phase 1 Task 1（dev path setup）**。共 3 個 commit、1 個 analysis 文件、1 個 1646-line implementation plan
2. **下個 session 跑 Task 2 + Task 3** — 兩個都是套件側縱切片，pattern 一樣（entity + ORM + mapper + repo + service + tests），Task 3 多一個 FK 欄位 + index
3. **Path dependency 已生效**（Task 1）— 在 `~/Projects/Jedicogy/.../jedi-oscal/` 改套件 source，主專案 import 立即看到，**不必每改 bump**
4. **執行 mode**: Subagent-Driven — 每 task 派 implementer subagent + 兩 stage review（spec compliance + code quality）

---

## 1. 本 session 已完成 commits

```
6f5be72  docs(ssp-oscal-alignment): Phase 1 implementation plan (14 tasks)
6d21348  docs(ssp-oscal-alignment): apply spec-reviewer advisory tweaks
ad66d1d  docs(ssp-oscal-alignment): brainstorm v1.1 — Phase 1 內直接 cutover + 6 個 edge case 拍板
```

未 commit 的改動（dev-only，**不要 commit**）：
- `pyproject.toml` — Task 1 改動：line 80 main deps Nexus pin 註解掉 + line 91 dev-dependencies path 取消註解
- `poetry.lock` — 可能也有改（path mode resolve 後 lock 更新）

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

| # | 文件 | 用途 |
|---|---|---|
| 1 | `docs/features/FR-028-2605-ssp-oscal-alignment/design.md` v1.1 | **主要 spec**。重點看 §1.1（套件異動策略、3 PR ordering）+ §1.4（dataclass shape）|
| 2 | `docs/analysis/2026-05-24-ssp-oscal-alignment-phase1-brainstorm.md` | brainstorm 6 個 Topic 推理過程 + 反悔條件 |
| 3 | `docs/features/FR-028-2605-ssp-oscal-alignment/implementation-plan-phase1.md` | **執行 plan**。Task 2 + Task 3 在這份內，重點看 Task 2.1~2.7（PR-1）+ Task 3.1~3.6（PR-2）|
| 4 | 本 handoff | 接手 context |
| 5 | `~/Projects/Jedicogy/.../jedi-oscal/jedi_oscal/domain/entity/base/oscal_party_entity.py` | Task 2/3 entity pattern reference（套件已有的範例）|

## 3. Brainstorm 收尾的 6 個拍板決策

詳見 analysis 文件，這裡簡列：

| Topic | 決策 |
|---|---|
| 1. 套件 PR 切法 | **3 PR per entity**，ordering: LeveragedAuth → Component → InventoryItem |
| 2. Migration dedup | **取消雙讀**，dev 階段直接 cutover |
| 3. Deploy timing | Phase 1+2 合併 deploy，避免 schema_version 中間態 |
| 4. FK resolve fail | Warn but allow + `import_warnings` + idempotent re-link |
| 5. 'other' export | 直接 `type="other"`（OSCAL allow-other=yes）|
| 6. Drop 時機 | Phase 1 內一口氣 migrate + DROP，不掛 deprecate marker |

## 4. Phase 1 Task 1 — 環境設定（已完成）

### 1.1 改動內容
`pyproject.toml`:
- Line 80: `"jedi-oscal==0.0.18",` → `# "jedi-oscal==0.0.18",  # dev-only: switched to path dep below (line 91), restore on Phase 1 Task 13 with new version`
- Line 91: `#jedi-oscal = { path = ... }` → `jedi-oscal = { path = "/Users/chouraymond/Projects/Jedicogy/module/jedi-python-package/jedi-oscal", develop = true}`

### 1.2 重要 lesson learned

**Plan Step 1.2 寫法不夠精確** — 假設只有一個 `jedi-oscal` 行。實際上 main deps（PEP 621 string array, line 80）跟 dev-dependencies（Poetry-extras dict, line 91）兩處都有。Subagent 第一次只動 line 91 沒注意 line 80，Poetry 兩個都 resolve 但 site-packages 只能一個 jedi_oscal — symlink 雖然在但 Nexus pin 是隱患（重 install 可能取錯 source）。

**Verify path mode 生效的正確方式**：
```bash
ls -la .venv/lib/python3.11/site-packages/jedi_oscal  # 應 lrwxr... (symlink)
readlink .venv/lib/python3.11/site-packages/jedi_oscal  # 應指 ~/Projects/Jedicogy/.../jedi-oscal/jedi_oscal
poetry run python -c "import jedi_oscal, os; print(os.path.realpath(jedi_oscal.__file__))"
# 應顯示 ~/Projects/Jedicogy/.../jedi-oscal/jedi_oscal/__init__.py
```

注意 `jedi_oscal.__file__` **不會自動 follow symlink**，需用 `os.path.realpath()` 才能看到真實 source path。

### 1.3 Task 13 cleanup 時要做的還原（提醒未來）

當套件 bump 到 0.1.0 推 Nexus 後：
1. Uncomment line 80 + 改版號為 0.1.0
2. Re-comment line 91 dev-dependencies path
3. `poetry update jedi-oscal`
4. 跑 tests 確認 OK
5. Commit pyproject.toml + poetry.lock

## 5. Task 2 + Task 3 開工提醒

### Task 2 — jedi-oscal PR-1 LeveragedAuthorization 縱切片

**Working dir**: `~/Projects/Jedicogy/module/jedi-python-package/jedi-oscal/`

**範圍**:
1. Entity: `jedi_oscal/domain/entity/base/oscal_leveraged_authorization_entity.py` + `_query_entity.py`
2. ORM model: `jedi_oscal/infra/model/base/oscal_leveraged_authorization.py`
3. Mapper: `jedi_oscal/infra/mapper/base/leveraged_authorization_mapper.py`
4. Repo: `jedi_oscal/domain/repository/base/leveraged_authorization.py`（interface）+ `jedi_oscal/infra/repository/base/leveraged_authorization_repo_impl.py`（impl）
5. Domain service: `jedi_oscal/domain/services/base/leveraged_authorization_domain_service.py`
6. Tests: `jedi_oscal/tests/test_oscal_leveraged_authorization_entity.py`

**5 個 commit point**（per plan Task 2.2.6 / 2.3.2 / 2.4.3 / 2.5.3 / 2.6.2）：
1. entity + query entity + tests
2. ORM model
3. mapper
4. repo interface + impl
5. domain service

完整 code 在 `implementation-plan-phase1.md` Task 2.2~2.6 段內。

### Task 3 — jedi-oscal PR-2 Component 縱切片（含 FK + 14+other enum）

**範圍**: 同 Task 2 pattern，差別：
- Entity 加 `leveraged_authorization_uid: Optional[str]` 欄位
- ORM model 加 `Index("idx_ssp_components_lev", "leveraged_authorization_uid", postgresql_where=text("leveraged_authorization_uid IS NOT NULL"))` partial index
- Entity test 多 `COMPONENT_TYPE_ENUM`（14+other）+ `COMPONENT_STATUS_ENUM`（5 個）assertions

Plan Task 3 為節省篇幅在 §3.2-3.6 寫「重複 Task 2 pattern」沒展開全 code — implementer subagent prompt 要明說「PR-2 entity 內含 leveraged_authorization_uid 欄位 + 14+other enum 已在 plan §3.1 entity code 內完整展開，repo/mapper/service 直接 mirror Task 2 PR-1」。

### 6 個共通注意事項（Task 2/3 都適用）

1. **Pre-flight verify**: 先 `cat` party / module_frame 既有 entity / repo / service 作 reference，確認 Base / 命名 / import path 一致
2. **不 commit 主專案 pyproject.toml / poetry.lock** — Task 1 留下的 dev-only 改動，整個 Phase 1 期間都不要 stage
3. **不切 branch**：套件已經在 `feature/ssp-oscal-alignment` branch（user 自己切的），subagent 確認 branch 不對就停下
4. **不 push**：Task 2/3 commit 到本地就好，不要自動 push（user 自決時機）
5. **TDD pattern**：write failing test → run fail → impl → run pass → commit。test 用 `poetry run pytest jedi_oscal/tests/test_xxx.py -v` 跑（套件側用 poetry，主專案也用 poetry）
6. **套件 BaseRepositoryImpl 簽名**：repo impl 繼承時 `super().__init__(mapper=..., model=...)`。**禁** `self.session = get_session()`（會在 Singleton 早於 @transaction 開啟 scope 時炸），用 `@property` lazy 或繼承 BaseRepositoryImpl 自帶的 session property

## 6. Subagent dispatch pattern

skill 規範：**implementer → spec reviewer → code quality reviewer → mark complete**。

Implementer subagent prompt 規範 see `~/.claude/plugins/cache/claude-plugins-official/superpowers/5.0.5/skills/subagent-driven-development/implementer-prompt.md`。

Implementer 必加 hard rules:
- **NEVER** `git checkout` / `git switch`
- **NEVER** push
- **NEVER** commit 主專案 pyproject.toml / poetry.lock（dev-only）
- 寫 app service test 必加 `@pytest.fixture(autouse=True)` patch logger（CLAUDE.md feedback）
- `git add` 列明檔名，禁 `-am`（CLAUDE.md feedback subagent prompt 必加）

**Trust but verify**: implementer 報告 DONE 後，主控 controller 自己跑 git status / git log / pytest 確認實際狀態。Task 1 case study: subagent 報告 DONE 但實際 path mode 沒生效，需 main controller 介入 fix line 80 — 證明 trust but verify 必要。

## 7. 套件 working tree 細節

```
位於分支 feature/ssp-oscal-alignment
未追蹤的檔案 (上層, 無關):
  ../.DS_Store
  ../jedi-device/CLAUDE.md
  ../jedi-project/CLAUDE.md
```

上層 untracked 檔案不歸 jedi-oscal 管，不要 stage 進套件 commit。

套件側 working tree 對 jedi-oscal 本身是 clean，可直接開工 Task 2。

## 8. 環境狀態（接手前確認）

| 項目 | 狀態 |
|---|---|
| 主專案 Branch | `feature/ssp-oscal-alignment`（user 切的）|
| 主專案 working tree | `pyproject.toml` modified（**不 commit**）|
| 套件 Branch | `feature/ssp-oscal-alignment`（user 切的）|
| 套件 working tree | clean（除上層 untracked，無關）|
| Path dependency | 已生效（`.venv` 內 jedi_oscal 是 symlink → ~/Projects/Jedicogy/.../jedi-oscal/jedi_oscal）|
| Dev DB | dev DB 192.168.50.188:25432 / guidant_ai_dev — Task 7/8/9 才會跑 SQL |
| Phase 1 estimation | 5d work，跨多 session ship |
| 本 session 完成度 | 14 tasks 內第 1 task（dev setup），剩 13 tasks |
| 下 session 目標 | Task 2 + Task 3（套件側兩個 PR 縱切片）|

## 9. Task list 狀態（25 tasks，#12 是 Task 1）

```
#1-11   completed   brainstorm + plan + spec/plan review loop
#12     completed   Phase 1 Task 1: pyproject path dep
#13     pending     Phase 1 Task 2: PR-1 LeveragedAuth  ← 下 session 第一個
#14     pending     Phase 1 Task 3: PR-2 Component       ← 下 session 第二個
#15-25  pending     Phase 1 Task 4-14 (留給後續 session)
```

## 10. 不要做的事（避雷）

- ❌ **不要 commit 主專案 pyproject.toml 或 poetry.lock** — 整個 Phase 1 期間都是 dev-only path mode，Task 13 才還原
- ❌ **不要 push 任何 branch** — user 自決時機
- ❌ **不要切 branch** — 兩個 repo 都在 feature/ssp-oscal-alignment，發現不對停下問
- ❌ **不要急著刪 SspSystemImplementationItemEntity** — 那是 Task 11 (PR-4 cleanup) 的工作，Task 2-4 期間舊 entity 跟新 entity 並存
- ❌ **不要直接執行 SQL migration** — Task 7-12 才跑，Task 2/3 純粹是套件側 Python code
- ❌ **不要在套件 commit 把上層 untracked 檔案（.DS_Store / 其他 package CLAUDE.md）也帶進去** — git add 明確列檔名

## 11. 對話歸檔提醒

本 session 是「brainstorm 收尾 + writing-plans + Task 1 開工」task arc。實作 Task 2+ 的 session 結束後再一起歸檔，或本份 handoff 寫好後現在就可歸檔（user 決定）。

歸檔指令（per CLAUDE.md）：
```bash
poetry run python scripts/extract_claude_sessions.py \
    --date 2026-05-24 \
    --topic ssp-oscal-alignment-phase1-brainstorm-and-plan \
    --auto
```

存到 `docs/conversation-history/2026-05-24/ssp-oscal-alignment-phase1-brainstorm-and-plan/`。

## 12. 給下個 Claude 的話

1. **不要重做 brainstorm** — 6 個 Topic 拍板已 commit 在 analysis 文件，design.md v1.1 已 reconcile。重做浪費 token
2. **直接走 subagent-driven-development skill** — invoke skill 後讀 implementer-prompt.md template，dispatch Task 2 implementer
3. **Trust but verify**：subagent 報告 DONE 後自己跑 git status / pytest / lsof / readlink 確認實際狀態 — Task 1 已有教訓
4. **Task 2 + Task 3 估 30-45 分鐘各**，本 session 預計可跑完兩個，剩下 Task 4 (M2M complexity) 留下下 session
5. **每個 task 完成後 mark TaskUpdate completed**，記得跑 spec reviewer + code quality reviewer 兩 stage（per skill 規範）
6. **不押 push / 不切 branch / 不發版** — user 自決

---

## 附：本 session 路徑速查

| 用途 | 路徑 |
|---|---|
| Spec | `docs/features/FR-028-2605-ssp-oscal-alignment/design.md` (v1.1) |
| Brainstorm 推理 | `docs/analysis/2026-05-24-ssp-oscal-alignment-phase1-brainstorm.md` |
| Phase 1 Plan | `docs/features/FR-028-2605-ssp-oscal-alignment/implementation-plan-phase1.md` |
| 本 handoff | `docs/features/FR-028-2605-ssp-oscal-alignment/handoff/2026-05-24-phase1-task2-3-handoff.md` |
| 上一份 handoff (brainstorm/plan 開工前) | `docs/features/FR-028-2605-ssp-oscal-alignment/handoff/2026-05-24-session-handoff.md` |
| 套件 root | `~/Projects/Jedicogy/module/jedi-python-package/jedi-oscal/` |
| 套件 entity reference | `jedi_oscal/domain/entity/base/oscal_party_entity.py` |
| Subagent skill SOP | `~/.claude/plugins/cache/claude-plugins-official/superpowers/5.0.5/skills/subagent-driven-development/` |