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

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）

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 更新）

詳見 analysis 文件，這裡簡列：

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 生效的正確方式：

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

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

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 必要。

位於分支 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。

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

• ❌ 不要 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 明確列檔名

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

歸檔指令（per CLAUDE.md）：

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

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 自決