讓「套件裡的東西」真的跟著版本出貨到客戶那裡

D1 — 套件 migration 進出貨線的形狀：靜態併入 vs 動態掃描

兩個方向：

• 靜態併入：build 期把 site-packages 的 <pkg>/migrations/*.sql 攤平進 /opt/guidant/sql/packages/<pkg>/，自動產一份套件子清單，stamp gate 守「wheel 裡有的＝攤平的＝stamp 清單有的」三者一致。init image 照舊只是 alpine＋psql，多 COPY 一個目錄。
• 動態掃描：init image 加一層有 Python 的 build stage，升級時現場跑 iter_migrations() 掃 site-packages。

建議：靜態併入。理由：既有 copy_pkg_data_dirs()（build_release.sh:671-683）與 build_init_image.sh 的 stamp gate（:70-83）形狀就是「build 期產物＋build 期驗證」，加一條白名單、擴一個 gate 就接上；動態掃描要把 init image 從 alpine 變成帶 Python 的 image，升級路徑多一個執行環境就多一種現場才會炸的失敗。另一個好處：攤平後的 SQL 是出貨包裡看得見的檔案，客戶端出事時工程師開包就能對。

D2 — 命名空間與排序：schema_migrations.filename 是裸檔名 PK，11 支套件全從 001- 起算必撞

schema_migrations 只有 filename text PK（02-schema.sql:16056-16061），套件檔名是 001-asset-tables.sql、001-participant-tables.sql……直接登記第二支就撞 PK。

建議：filename 記成 packages/<pkg>/NNN-xxx.sql——相對路徑本身就是命名空間，不動表結構、不加欄位。migrate.sh:86 的 grep '\.sql$' 與哨兵過濾照樣過得去。排序：主線 manifest 先跑完，再依套件名字母序、套件內序號序跑 001..NNN。跨套件依賴（如 task-platform 002 要先有 projects、002-*-rls-grants 要先有 cm_app 與租戶判定函式，jedi-asset/README.md:249-250）以「主線已把宿主生態建好」為前提，不做拓撲宣告——套件之間如果真的互相依賴表，那是套件疆界劃錯，應該回到 D3 的規則處理，不是加一層依賴解析器。配套硬規則：套件 SQL 一律冪等（CREATE ... IF NOT EXISTS、ON CONFLICT、DO $$ IF NOT EXISTS），這是階段 3 的核對目標。

D3 — 雙份 DDL 收斂責任（本案最重要的長期規則）

今天同一張套件表有兩份 DDL：主專案 scripts/sql/（41 支，已收進 02-schema.sql，是實際建表的那份）與套件 migrations/（24 支，從沒跑過，已漂移）。不定規則，「兩份會漂移」在本案接線後會變成「兩份都會被套」。

建議：往後套件疆界的表只在套件 migrations/ 改，主專案 scripts/sql/ 不再新增套件表的 migration；既有 41 支歷史 migration 保留不動（它們是已出貨基線的一部分）。FR-089 README:45 短期建議的「主專案 scripts/sql 另放一支」不採——那正是加深雙份。代價要說清楚：① 第一次上線要做既有庫一次性補登：DEV／STG／POC／已出貨客戶庫的表都在了但 schema_migrations 沒有套件檔名，新機制上線差集會算成 24 支全待套 → 大面積重放失敗；補登用 gen_stamp_sql.sh:66-70 的 converged 手法（標 converged into __init_baseline_*），先補登再上線。② 補登前要逐支核對 24 支套件 SQL 與 DEV 實況的差修到冪等（detection 已知差 7 FK；asset 002 的 RENAME VALUE 在已是小寫的庫上會炸，見風險段），這是階段 3。③ CM-1678 的 enum 修法就用這條線第一次真的套出去——它是活例也是驗收案。

D4 — 出貨 seed 的四段改成用名稱反查（不再寫死 id）

04-seed-core.sql 的 capabilities／role_capabilities／route_capabilities／ui_routes 四段是 pg_dump 產的：INSERT INTO capabilities (id, name, ...) VALUES (1, 'bulletin.create', ...) ON CONFLICT DO NOTHING（L216 起），role_capabilities 是寫死的整數對（L476 起）。gen_seed_sql.sh 用 --on-conflict-do-nothing 產不出 conflict target（L43-46）。

地雷組合：id 寫死 ＋ ON CONFLICT 無 target ＋ capability_id 無 FK。一旦 D5 的自動補 row 先跑、佔走某個 id，seed 那筆因 name unique 撞而靜默跳過，接著 role_capabilities (2, 135) 指向錯的能力點或孤兒——資料庫不擋、沒有錯誤、權限就是錯的。

建議：做。四段改 INSERT ... SELECT 以 name 反查 id（capabilities 用 ON CONFLICT (name)；role_capabilities／route_capabilities 反查 capabilities.name＋ui_routes.name；ui_routes 的 pid 分組反查 group-* 的 name），作法比照 labels 那段——在 gen_seed_sql.sh 加特案後處理，不改 pg_dump 參數。現成樣板：2026-08-01-fr059-2-detection-profile-capability.sql（name-based ＋ 參照角色法）與 2026-08-29-cm1423-security-policy-page.sql（ui_routes 反查）。附帶效果：seed 不再依賴基線庫的 id 跳號（1,2,3,4,12,13,15…）。

D5 — 能力點自動補 row 的執行點與範圍

三個可能的執行點：BE 啟動期、migrate 模式、seed 檔。

建議：在 migrate 模式加一支「宣告對照」步驟，不在 BE 啟動期寫 DB。作法：init image build 期把 21 支套件的 CAPABILITIES（80 筆）＋ CM-1748 主專案 36 筆攤平成一份 capabilities.json（或直接產 SQL），migrate 時 INSERT ... ON CONFLICT (name) DO UPDATE SET description, is_platform。理由：① 啟動期寫 DB 是多 worker 競態（gunicorn 多個 worker 同時起，誰先誰後、誰重試）＋ RLS 身分問題（BE 用 cm_app 受 RLS，系統層寫入會 silent fail——CLAUDE.md 已載明 migration 一律 cmmgr）；② migrate 模式本來就是「升級時用 cmmgr 改 DB」的唯一合法時點，能力點只是多一種要改的東西；③ 宣告對照是 build 期產物，跟 D1 的攤平同一道工序，stamp gate 一起守。範圍：只 upsert capabilities 表本體；角色授權另見 D6。

D6 — Administrator 與租戶管理員回補（升級等於自動擴權）

新能力點進了 capabilities 表還不夠，要綁到角色管理員才拿得到。兩類角色：

• root Administrator（role 2，tenant 1）：seed 給全部 127 筆，是「持有全部」不是「繞過」（探脈 B §7）。
• 租戶管理員（Billows Admin id 3、System Manager id 43/44/49/55/56/57……）：建租戶時一次性快照，之後不回補。

建議：① root Administrator 維持「持有全部」並自動補齊——改成繞過會跟設計哲學衝突（角色層 is_admin 不該有能力語意）且 UI 看不見它有什麼；持有全部的代價只是每次補 capability 同步補 role 2，這在 migrate 步驟裡是一條 INSERT ... SELECT。② 租戶管理員用**「參照角色法」（比照 fr059-2：凡持有某基準能力點的角色都補這批新能力點），不採 roles.is_admin=1 條件**——它會誤中客戶自訂的管理角色。③ 回補段必 AND NOT is_platform，否則 trg_role_capabilities_platform_guard 對非 root 租戶整批 raise。④ 比照 _add_tenant_with_defaults 三道扣除（不販售 resource_type／is_platform／licensed_modules 未授權模組，tenant_provisioning_service.py:127-133）——沒買的模組升級後不該憑空出現權限。基準能力點怎麼選（哪一筆代表「這是管理員」）是開卡時要定的細節，建議選各套件既有的核心 *.manage。

D7 — ui_routes／route_capabilities：套件契約要不要加 UI_ROUTES 宣告

選單來自 ui_routes，可見性來自 route_capabilities；缺前者沒入口、缺後者 fail-open 全員可見（ui_route_repo_impl.py:77）。要不要像 CAPABILITIES 一樣讓套件用 Python 宣告 UI_ROUTES，由本案的機制自動寫入？

建議：本案不擴契約。理由：ui_routes 有 pid 分組、sort、icon、url，這些是 FE 版面知識，用 Python 常數表達會把選單樹的一半塞進套件；而 SQL 已經有現成的 name-based 寫法（cm1423 那支）。作法：把「補 ui_routes ＋ 綁 route_capabilities」列為每支有頁面的套件 migration 的必做項，以 cm1423 為樣板（不寫 id、WHERE NOT EXISTS (name=)、pid 用 group-* 的 name 反查而非硬編 47）。並加守衛：「有 ui_routes 的套件頁面必有 route_capabilities」——擋 fail-open，做法可以是 migrate 尾端一條斷言 SQL，或主專案守衛測試對套件 SQL 靜態掃描。契約擴充留給日後有第二個消費者時再議。

D8 — 排程與 jedi 1.1.0 的關係

建議：本案主體（階段 1、2）純主專案＋build 腳本，不動套件源碼——套件 migrations/ 已在 wheel 裡、CAPABILITIES 已宣告，讀它們不需要改它們，所以不綁 1.1.0，可以在 21 支 1.0.x 上直接做。例外是 D3 的「24 支套件 SQL 修到冪等」＋ D7 的「每支套件補 ui_routes／route_capabilities」要動套件，那部分併 1.1.0 發版（走 jedi-package-dev 的 path dependency dev loop，發版等令）。順序上：階段 1 先在主專案側接線並用現有 24 支驗通（DEV 補登後差集為 0 即可驗），套件 SQL 的修正隨 1.1.0 進來時再走同一條線第一次真的套。