FR-089 交接現況（STATE）

這份是 living 檔：每棒就地 Edit，只描述「此刻」。歷史脈絡看同資料夾的 FR-089-LOG.md。 本 arc 是協調者級：涵蓋 FR-089（套件結構統一）母案底下三段——jedi-asset 定形（Done）／FR-090 主專案側收斂（進行中）／FR-091 18 支套用（第一批派出）。

這節寫一次，之後各棒不動。

• 決策者原話（2026-09-12）：「然後有超多 dataclass 直接寫在 plugin 裡面，這不能另外整理嗎？那隻一堆東西都沒有整理過很難閱讀」→「都做吧，這個作為範例」→「我想要全部做法都統一」→「我不想要在一堆地方設定，這樣接手的人很難上手」。
• 要解決什麼：FR-069／FR-080 把功能抽成 21 支 jedi-* 套件後，每支長得不一樣（plugin.py 塞 400 行、守門函式各叫各的、logger 五種名、註解塞滿棒號）；主專案側接一支套件要翻四五處且每支翻的地方不同。接手者無從上手。
• 目標模型：
  • 套件側：plugin/ 五檔（init／contract／runtime／assembly／migrations）；api/ 拆 guards.py（runtime()＋三個 lazy decorator）與 routing.py；logger 掛 common.jedi_<pkg>；entity 一律 dataclass；註解只留「為什麼」與「陷阱」；API 有吐 created_user_name 的才開 identity port。範例＝jedi-asset。
  • 主專案側：接一支套件三步——pyproject 一行、新建 core/plugins/<pkg>.py（adapter＋填表＋註冊三段同檔）、PLUGINS 清單加一列。只有主專案其他模組要直接用套件 domain service 才多第四步（DI）。
• 三段結構：① jedi-asset 定形（FR-089 自身，Done）→ ② 主專案側收斂（FR-090）→ ③ 18 支套用（FR-091）。DI container 瘦身排 ③ 之後（FR-090 第 6 棒）。
• 與 FR-080 的關係：FR-080 收口中，其「發版推 Nexus／pin 還原／SPEC／release note」四項 2026-09-12 移入本案，等 18 支整理完一次做（CM-1619 末段已記）。不掛回 FR-080。
• 說明文件：docs/features/FR-089-2609-package-shape-unification/plugin-anatomy.md（袋子比喻、port/adapter、DI 與 runtime、設計模式對照、harness）——工程師第一次接觸先讀這份。

0.1 🔒 先懂需求 gate

1. 本檔 🧭 WHY 節
2. docs/features/FR-089-2609-package-shape-unification/plugin-anatomy.md §「這次整理做了什麼」「新手教程」「port 與 adapter」三節（全讀）
3. docs/features/FR-069-2608-jedi-module-extraction/extraction-sop.md §4.3（plugin 分檔規格）與 §5（主專案側）

0.2 現況與待辦

4. 本檔 §1、§3
5. FR-089-LOG.md 最後 1 個 block
6. 待驗的卡 python3 scripts/notion_case.py get <id> > /tmp/x.txt（直接 pipe 會截）：CM-1736 3da346da4cd081a8af86d2a3bf50985c。母卡 CM-1690 3d9346da4cd0815280cbeb3d644cb2b8

0.3 需要細節才開

• jedi-asset 整支（範例）；core/asset_wiring.py＋infra/asset/（主專案側現況，第 5 棒會搬）
• FR-090 README docs/features/FR-090-2609-host-side-residue-cleanup/README.md；FR-091 README

0.4 ✅ 冷接自檢

1. 為什麼 adapter 最終放 core/plugins/<pkg>.py 不放 infra/？（答：一檔看完優先於分層純度，決策者裁；CM-1684 先搬 infra 再被 CM-1689 改判）
2. 哪些套件要開 identity port、哪些不要？判準是什麼？
3. 為什麼 ctx() 改叫 runtime()？
4. FR-080 剩哪些收口項、哪些移來了？
5. 能力點（capability）現在「誰宣告、誰判定、誰 seed」三件事各在哪？（答：套件 plugin/contract.py 的 CAPABILITIES 宣告；主專案 core/plugins/_host.py 填 common.authz.require_capability 判定，實體 jedi_iam.authz；seed 仍在主專案 04-seed-core.sql，主專案五條守衛比對）
6. 為什麼驗收要在該卡 commit 的 worktree 跑而不是 HEAD？（答：並行 runner 的後續 commit 會把前一張的綠跑成紅，HEAD 顏色不代表單卡成果；1733／1732 實例）

1.1／1.6 由首腦第 3 棒 2026-09-13 晚更新；1.2 commit 清單停在 09-12（之後 200＋commit 見 git log --grep="CM-17"，不再逐條列）；1.3 卡表為最新；1.4／1.5 未重跑。

1.1 兩 repo git 現況

這是兩個 repo 的 branch／領先／HEAD／working tree 狀況（git status -sb + git log），2026-09-12 18:42 查。未 commit 的檔多半是並行 runner 正在做的，照實列不判斷。

1.2 FR-089／090／091 相關 commit 清單

這是兩 repo 用 --grep="CM-16[7-9][0-9]|FR-089|FR-090|FR-091" 撈到的 commit（BE 前 40、jedi 前 30），2026-09-12 18:42 查。含少數同號段內的鄰近 arc（CM-1668～1675 FR-088、CM-1679/1681 註解收斂／修測）一併列出。

BE（新→舊）

jedi monorepo（新→舊）

1.3 Notion 卡狀態

這是 17 張卡用 scripts/notion_case.py get <id> --props-only 逐張查到的狀態，2026-09-12 18:45 查。

1.4 測試基線

這是三組測試在 BE .venv 下跑 pytest -q 的末行結果，2026-09-12 18:45 查。

1.5 DEV DB 實況（唯讀）

這是 DEV guidant_ai_dev（188:25432，cmmgr）查 pg_class／pg_policies／pg_enum 的結果，2026-09-12 18:45 查。

1.6 BE 服務

2026-09-13 晚：BE 以 python main.py 起在 8000，不需 PYTHONPATH（20 支 path dep 都指工作樹，只剩 oscal-v2 之外全 path）。/api/1.0/devices/menu 回 401 即活著。決策者正在 DEV 走一輪頁面測回歸（零行為變更的 arc，測「什麼都沒壞」）。

🔴 下一個動作（依序）：

1. 驗 CM-1736（決策者 2026-09-13 看過收 Done）；CM-1737 已收。PM 頁 for-pm.md「三個零件裝法還是舊式」段要拿掉（純文件小改，首腦順手或併 arc-review 後的文件卡）。原 1 項：驗 CM-1736（PM 白話頁 for-pm.md＋anatomy 重寫）。驗法：① 兩頁 grep CM-1|第 .* 棒|原本|收斂前|改判|後來|2026-09-12 出現即退回（決策者裁「文件只寫現況」）；② PM 頁允許 plugin／主專案／接線／能力點／守衛測試五個詞且首次出現有括號白話，不得出現 adapter／port／DI／runtime／dataclass／contract／seed；③ 有「一支 plugin 裡面有什麼」五部分表；④ 數字對現況（21 支、25 卡、80 筆、core/plugins/ 17 檔）；⑤ render_index.py 重 build 後 for-pm.html 側欄有、mermaid 沒壞。過了把 for-pm.md 全文貼給決策者轉 PM。
2. arc review＋修正卡 全收：CM-1738 報告（2C／6I／5M）＋ 1739～1744 六張 Done。乾淨 worktree HEAD 守衛族 141 passed。未開卡留存：I-5 九處 import 改指＋刪三支 ports/ 殼（1744 白名單標「I-5 收」，收完要拿掉白名單）、M-1～M-5、註解 58 條、四支既有紅測試（不掛 FR-089）、ProjectRoleGuardAdapter 兩份同名不同實作（infra/survey/adapters.py vs core/plugins/evidence_classification.py）。
3. 決策者裁（拿 review 結果一起談）：(a) FR-080 移來的發版推 Nexus／pin 還原／SPEC／release note——STG 測試的前提；(b) CM-1696 DI 瘦身規則「主專案哪些模組可直接用套件 domain service」；(c) FR-090 補卡：主專案自有 36 筆能力點申報處（三支接線那張已開 CM-1737，見 §4）；(d) migrate FR：出貨 image 不撿套件 migration＋能力點自動補 row＋Administrator 初始權限（seed 檔 127 對寫死 role_capabilities 整數）。
4. follow-up 要不要開卡：evidence-classification 3 條／ai-bot 1 條寫入 API 無 schema；issue tests/vcs_integration/ 21 紅（需外部服務）；compliance-audit／task-platform 無 testcontainers 整合測試；FlowControlJobEntity 未 dataclass（參數名≠屬性名）；report 能力點無點；task-setup/tree 500（raw SQL ap.uid 應為 uuid）。
5. 順手：CLAUDE.md「DB 環境清單」DEV 列改 localhost（188 guidant_ai_dev 標退役快照）、docs/claude/sql-migration-conventions.md 與 3-way diff 腳本同步；「說明文件只寫現況」已進 CLAUDE.md 不用再補；驗收 SOP 措辭改「驗既有紅唯一方法＝開 worktree 到開工前 commit」放最前（禁 stash 放尾巴擋不住，1727／1735 連兩張伸手）。
6. FR-089／FR-091 母卡收 Done、SUMMARY——等決策者下令收尾。

驗收 SOP（第 3 棒定型，全程在該卡 commit 的 worktree 跑）：⓪ git status 該卡目錄零 ??（1731 事故：commit -- 路徑 不納未追蹤新檔）；① 讀回寫（重導到檔再讀）；② git log 對卡；③ 殘留掃描（ctx()／施工日誌關鍵字／非 dataclass entity／logger 名／addopts／--smoke／PKG_ROOT／頂層平鋪／頂層 ports/／套件內 tests/／api 頂層只允許 init guards routing）；④ 套件 pytest 全量在該卡 commit 的 worktree、PYTHONPATH 只指 worktree（HEAD 紅要歸因到後續哪張卡；runner 報「與 baseline 相同」必看 comm 輸出，沒貼就自己比）；⑤ 版面守衛突變——突變前 git diff --stat 確認真的改到檔（BSD sed 0,/pat/s// 空替換、Nd 行號算錯都會假綠）；⑥ harness --smoke；⑦ 主專案 boundaries＋logger 守衛＋fr048；⑧ AST 掃主專案 import 逐一 importlib；⑨ BE 重啟零新 Traceback、真實 URL 從套件 routing.py 抓、先看 GET／POST 與 FE payload；⑩ 有 G 組加拔掉測試。驗收是首腦本職，不外派（決策者 2026-09-13 裁）。

⚠️ 這節是建議清單，不是執行授權。接手方讀完盤點完即停，等 user 發令。

• runner 側紀律缺口（本棒三張退回的共同根因）：並行時 HEAD 不代表單卡成果；commit -- 路徑 漏未追蹤檔；「與 baseline 相同」靠記憶不靠 comm；驗既有紅伸手 git stash。派工 prompt 尾註要固定加：收工前全量在自己 commit 的 worktree 跑、git status 看 ??、對照用 comm 貼輸出、禁 stash 改 worktree。

• 三 repo 領先 origin 未推：BE 自 56a15397 起（1737＋review＋六張修正＋docs）、jedi 自 b077ed8 起（1741／1739／1742 三顆）、FE 6b7b0f2（1741 退路）。等令。

• 發版前置：jedi-common 新 export fill_user_names，五支對 jedi-common 下限（asset≥0.0.34／iam≥0.0.23／survey≥0.0.33／compliance-audit≥0.0.33／bulletin≥0.0.34）發版時要提到含該函式那版，否則裝舊版直接 ImportError。

• 守衛 test_converged_plugin_adapters_do_not_return_to_infra 會被 __pycache__ 假紅：它用 path.exists() 判舊目錄，舊樹上殘留的 pycache 目錄會讓它紅（首腦驗 1737 撞到）。改法：判目錄內有無 .py 檔，或 git ls-files。小卡候選。

• 出貨 image 不撿套件 migration（CM-1678 runner 查證）：scripts/init/ 與升級腳本只讀主專案 scripts/sql/ manifest，套件的 migrations/ 永遠套不到客戶端。enum bug 三環境＋出貨基線都有。未開卡。

• CM-1684 守衛盲點：test_jedi_port_implementations_live_in_infra 只認繼承 jedi port ABC 的 class，duck typing 的 adapter 看不到。1689 改守衛時要一併擴。

• 1687 幾處 _enrich_nicknames 之外的補暱稱：app/flow_control/service/project_service.py:315（受評標的負責人）與 feedback_issue_dto.py 不是補審計暱稱，刻意不動，別誤收。

• admin（tenant 1）建的資料在 blsadmin 視角暱稱回 None：RLS 範圍 /1/102/ 看不到 tenant 1，不是 bug。

• 五支套件（asset／system-core／log／task-platform／bulletin）未發版：主專案走 path dependency（pyproject.toml:184 附近，不 commit），別台機器 clone 要先有 jedi 套件目錄。

• 主專案 venv 四支（issue／file-upload／flow-engine／ai-bot）仍讀 Nexus wheel——首腦 2026-09-13 裁：派 CM-1730 前一律改 path dependency（不 commit），否則守衛在主專案讀不到清單會誤判。原文：多數套件是 Nexus wheel 不是工作樹（CM-1692 runner 抓到）：pyproject.toml 只有 asset／iam 等少數走 path override，其餘是 pin。在主專案驗任何套件改動前先 python -c "import jedi_<pkg>;print(jedi_<pkg>.__file__)"，指到 site-packages 就要 PYTHONPATH=<套件目錄> 重跑，否則假綠。已通知第一批其餘四張 runner。

• 主專案 venv 的 site-packages 裝了 jedi-asset 的 tests/ 當頂層套件（path dependency 副作用）：其他套件 from tests.xxx import 被遮蔽，預設模式 pytest collection error。用 pytest --import-mode=importlib，或下批卡要求各套件 pyproject.toml 加 addopts = "--import-mode=importlib"。整理前就存在。

• 第一批三支 harness 沒有 --smoke（ai-bot／remote-agent／ai-dashboard 都是 app.run() 綁 port），首腦驗收時撞 port 撞了三次。第二批起卡上加「harness 補 --smoke（test client 不綁 port）」，並回頭給這三支開一張小卡補。

• 三支接線（ai-bot／ai-dashboard／remote-agent）已收進 core/plugins/（CM-1737，0422c5d6）：_CAPABILITY_PACKAGES_OUTSIDE_PLUGINS 清空、PLUGINS 20 支。留此行只為對照舊待辦。

• 1689 範圍外仍有 infra/ adapter：infra/{license,remote_agent,survey,detection_tools,notification,upload_file}/ 各 1～4 檔沒搬，因為那些套件不在 PLUGINS 迴圈（走 REGISTERED_APPS 或另掛）。守衛 90 passed 表示它們不繼承 jedi ABC 或已白名單。FR-091 對應批次時順手收進 core/plugins/。

• core/plugins/ 是新目錄，Nuitka 打包白名單未驗（1689 runner 列出）。出包前必查 scripts/build/。

• 並行 runner 共用工作樹時裸 git commit 會吞別人 staged 的檔（首腦 ea34a17e 吞了 1689 的 22 檔；1692 也吞了 1693 的 14 檔）。首腦與 runner 一律 git commit -- <路徑>。

• 疆界守衛 PKG_ROOT 陷阱（CM-1699 runner 發現，第 2 棒實查）：Path(<pkg>.plugin.__file__).parent 在 plugin 拆子套件後指到 plugin/，三支「不得 import 主專案」守衛只掃 5 檔仍全綠。asset／bulletin 已由 1702 修好（掃 58／42 檔，突變會紅）；第三批起開卡固定寫「PKG_ROOT 從套件頂層模組取」。

• bulletin 整合測試只套 001 不套 002，RLS 未覆蓋（runner 當場講明，首腦收下）。system-core 那支有套 002 可當範本。

• 第一批五支的 plugin.py 都能無痛拆五檔：已由 runner 回寫證實，推測撤銷。

cd ~/Projects/Billows/Audit-Manager/compliance-manager-be && git status -sb | head -3 && git log --oneline -5
cd ~/Projects/Jedicogy/module/jedi-python-package && git status -sb | head -3 && git log --oneline -5
# 待驗的卡
cd ~/Projects/Billows/Audit-Manager/compliance-manager-be
python3 scripts/notion_case.py get 3da346da4cd081a8af86d2a3bf50985c --props-only 2>&1 | grep -E "^Case No|^狀態"   # CM-1736
# 21 支全指工作樹＋能力點可讀
source .venv/bin/activate && python -c "import importlib;print(sum(len(importlib.import_module(m).CAPABILITIES) for m in ['jedi_asset.plugin','jedi_iam.plugin','jedi_detection.plugin','jedi_survey.plugin']))"   # 42
# 守衛基線
python -m pytest test/test_module_boundaries.py test/test_jedi_package_logger_names.py -q 2>&1 | tail -1   # 100 passed
# BE 在不在
curl -s -o /dev/null -w "%{http_code}\n" localhost:8000/api/1.0/devices/menu   # 401 = 活著

憑證一律查 .env，不寫明文。

• 派工＝開 Notion 卡，卡上帶母卡號；runner prompt 薄（母卡號＋卡 URL＋讀卡照做＋branch＋並行注意＋commit 回寫不等令），並標建議 model。
• 驗收不採信 runner 自報：自己跑測試、grep 殘留、重啟 BE 打端點。
• 驗守門類功能前先查清楚定義（2026-09-12 首腦教訓：以為 blsadmin 是 root admin，實際受保護的是 tenant 1 的 admin，誤把測試帳號停用後手動復原）。
• 檔案內註解只寫為什麼與陷阱；施工日誌進 commit message。
• 不發版、不推 Nexus、不 push、不切 branch、不碰 STG／POC。
• 中繼交接：STATE 就地 Edit、LOG append、在跑的子卡不動。
• commit 一律 git commit -- <路徑>，共用工作樹有並行 runner 時裸 commit 會吞別人 staged 的檔（第 1 棒踩兩次）。
• 驗收打端點前先看 route 是 GET 還是 POST：第 2 棒三條列表端點都是 POST 帶 RequestMetaSchema（pager／sort／filters），用 GET 打回 405 不是壞。上傳是 multipart 帶 json part。
• 驗收要批次：三張卡的 pytest／突變／smoke／import 掃描一次跑完再看，不要一張一張。