Project Flow Engine — 實作 Task Arc 收尾報告

Arc 範圍：2026-05-08 10:47 ~ 2026-05-09 05:11（連續 ~18 小時，含長段 subagent 平行 dispatch） Branch：feature/project-flow-engine HEAD 0393613 — 62 commits ahead of main / 57 ahead of origin（未 push、未 merge main，user 自行手動 push） Working tree：乾淨 承前：docs/conversation-history/2026-05-07-project-flow-engine/（spec + plan 撰寫階段，已歸檔） 承後：M5 FE（12-14 週）/ M6 Test + UAT（10-11 週）/ 5 個 deferred issues（pending）

期間：~30 個 subagent dispatch + ~10 輪重大架構討論。

本 arc 起點為 e04255c（前 5 個 commits 屬上一個 spec 撰寫 arc，ed72ae7 ~ e04255c，已記在 2026-05-07 arc）。

M0 — OSCAL Spike + spec 回灌（2 commits）

M1 — 核心基礎建設 / Activity Protocol & Registry & Dispatcher（13 commits）

M2 — Plugin Scaffolding（6 commits）

M3 — Template schema + Snapshot + 5 Builtin templates（6 commits）

M4 — Role Catalog / API / Template CRUD / 廢除舊 OSCAL endpoints（10 commits）

M4 Closure — Critical Fixes C1-C4 + Wiring + Truncate + E2E Smoke（14 commits）

A1 / D1 / B1 — Spec Amendment + Complete-time Fix + 任務類 plugins（6 commits）

234 files changed, 27,121 insertions(+), 359 deletions(-)

新增模組（主要）

• app/flow_engine/ — Activity Protocol / Registry / Dispatcher / Engine adapter
• app/flow_engine/plugins/ — 12 plugins（M2.A 通用 4 / M2.B 問卷 3 / M2.C OSCAL 5）+ B1 任務類 5
• app/flow_engine/strategies/ — entity strategies（OSCAL AP / Survey / POAM / Task / etc）
• app/compliance/role/ — Role Catalog + RoleCatalogSeedingService + UserDeletionService
• app/compliance/template/ — TemplateSnapshotService + TemplateStaticAnalyzer
• api/flow_engine/ — Project Flow API + Template CRUD API
• domain/flow_engine/ + infra/flow_engine/ — repo interface + impl
• di_containers/flow_engine/

新增 SQL Migrations（schema 策略：既有 jedi-flow-engine 表保留 public，新表進 flow_engine；新 enum 進 compliance）

• 2026-05-08-flow-engine-execution-contexts.sql
• 2026-05-08-flow-engine-activity-logs.sql
• 2026-05-08-flow-engine-template-extensions.sql
• 2026-05-08-flow-engine-role-catalog.sql
• 2026-05-08-truncate-legacy-oscal-data.sql（截除 140 個 legacy projects 對齊 spec §11.4）

新增 BPMN Templates

• oscal-full-audit.bpmn
• oscal-internal-only.bpmn
• oscal-execute-only.bpmn
• survey-with-review.bpmn
• survey-fill-only.bpmn
• task-execute-only.bpmn（B1 新增）
• task-with-approval.bpmn（B1 新增）
• task-recurring.bpmn（B1 新增）

→ 共 8 個 builtin templates，E2E smoke PASS。

廢除（M4.4）

• 既有 OSCAL phase-switching endpoints（已被 BPMN flow + ActivityDispatcher 取代；保留 read-only 統計用 endpoints）

新增能力

• 從固定 5-phase OSCAL flow → 任意 BPMN flow 驅動
• 新增 4 種 project type 分類：OSCAL（稽核）/ 問卷 / 任務 / 混合
• 新增「Project Flow」(/projects/<uid>/flow) — current_node / activity log / phase / completion
• 新增「Template CRUD」(/templates/...) — admin 自訂 BPMN flow（含 static analysis 攔錯）
• 新增「Role Catalog」(/role-catalogs/...) — tenant 內 4 個 builtin role + custom role；project_role_assignments 取代既有 OSCAL participant 角色硬編
• 新增 8 個 builtin templates 涵蓋常用 case
• 新增 node_config_overrides 機制（解決 complete-time config gap — 同 plugin 不同節點可改 config 而不需另開 plugin variant）
• 新增 plugin runtime guard（Plugin Type 違規 → 500 with typed exception）

廢除能力

• OSCAL phase-switching endpoints（如「manual 切到 internal_review」）— 統一走 BPMN flow advance
• AP.status 不再是 user-facing 主狀態 — 降級為 OSCAL service 內部 sub-state；外部用 current_node + phase

Breaking Change

• 既有 140 個 legacy projects 已 truncate（dev / staging）
• 既有 assessment_plans.status、assessment_results.status 在 user-facing 不再有意義
• 既有 OSCAL phase-switching endpoints 移除

Changelog（33 份在 docs/changelog/2026-05-08-*.md）

依 type 分類：

feat (20)：

• feat-flow-engine-activity-logs.md
• feat-flow-engine-b1-task-plugins.md
• feat-flow-engine-builtin-templates.md
• feat-flow-engine-completion-checker.md
• feat-flow-engine-di-container.md
• feat-flow-engine-dispatcher.md
• feat-flow-engine-generic-plugins.md
• feat-flow-engine-m3-schema.md
• feat-flow-engine-m4-milestone-summary.md
• feat-flow-engine-oscal-plugins.md
• feat-flow-engine-plugin-runtime-guard.md
• feat-flow-engine-project-flow-api.md
• feat-flow-engine-review-mark-verdict.md
• feat-flow-engine-role-catalog.md
• feat-flow-engine-survey-plugin-wiring.md
• feat-flow-engine-survey-plugins.md
• feat-flow-engine-template-api.md
• feat-flow-engine-template-snapshot.md
• feat-flow-execution-contexts-table-and-repo.md
• feat-project-flow-engine-oscal-plugin-wiring.md

fix (4)：

• fix-flow-engine-c1-c2-i2-repo-abstraction.md（C1+C2+I2 — DDD 層級違規）
• fix-flow-engine-c3-audit-nicknames.md（C3 — DTO 加 user nickname）
• fix-flow-engine-c4-typed-exceptions.md（C4 — typed exception）
• fix-flow-engine-d1-complete-time-config.md（D1 — node_config_overrides）

tweak (9)：

• tweak-flow-engine-deprecate-oscal-routes.md（M4.4 廢除 OSCAL endpoints）
• tweak-flow-engine-spec-amendment-4-types.md（A1 spec amendment）
• tweak-project-flow-engine-external-review-fixes.md
• tweak-project-flow-engine-plan-amend.md
• tweak-project-flow-engine-reviewer-pass2.md
• tweak-project-flow-engine-schema-strategy.md
• tweak-project-flow-engine-spec-and-plan.md
• tweak-project-flow-engine-spike-findings.md
• tweak-truncate-legacy-oscal-data.md

Analysis Docs（3 份在 docs/analysis/2026-05-08-*）

• 2026-05-08-template-static-analyzer-fixpoint-lattice.md — Template static analyzer 演算法選型分析（intersection vs union；lattice 選擇；spec 演算法直譯會 fail，改為 union semantics + per-loop-iteration verification）
• 2026-05-08-project-type-comparison.html — 4 種 project type 對照表（流程、UI、資料、適用場景）
• 2026-05-08-user-flow-comparison.html — User flow / FE 互動細節對照（建專案 / 設定流程 / 執行 / 結案）

Pending Issues（3 份在 docs/issues/pending/2026-05-08-*）

• 2026-05-08-flow-engine-schema-migration-deferred.md — 現有 jedi-flow-engine 表保留 public schema；統整搬到 flow_engine deferred 到 Phase 2/3（影響 ~30 主專案檔 + 16+ jedi-flow-engine 檔）
• 2026-05-08-tenant-create-role-catalog-hook.md — 新 tenant 建立時自動 seed 4 個 builtin role catalog（M4 暫時手動跑 seeding service）
• 2026-05-08-user-delete-cascade-hook.md — User force-delete 時 cascade 清 project_role_assignments（M4 寫 wrapper service 但 jedi-auth delete_user 沒攔到）

Spec / Plan Updates

• docs/features/project-flow-engine-setting/design.md — A1 amendment 加 4 type 分類框架（§4.2 + §11.x）
• docs/features/project-flow-engine-setting/implementation-plan.md — D1 + B1 task entry + node_config_overrides + builtin template list 更新

Conversation History（本資料夾）

• README.md
• SUMMARY.md（本檔）
• part-01-of-09-m0-spike-and-spec-amend.md ~ part-09-of-09-spec-amend-and-handover.md（9 parts，總 ~648KB）

D1：M0 spike 5 條 finding 修正

Spike 發現 design v1.0 假設 flow_engine schema 既有 → 實況 staging DB 上 workflow_* / element_variables 都在 public（11K+ rows）。決策：採 C 方案修 spec（既有套件表保留 public，新表進 flow_engine），不去搬遷既有 jedi-flow-engine 表（搬一次要碰套件 + 主專案 ~30 檔，性價比低）。Schema 搬遷另開 deferred issue。

D2：Schema 策略 — 不搬 jedi-flow-engine 既有表

留 issue（2026-05-08-flow-engine-schema-migration-deferred.md）。理由：架構整潔度問題不影響功能 / 安全 / 資料一致性；要動就要連動 jedi-flow-engine 套件。

D3：M2 採 Scaffolding-First 策略

M2 階段先把 12 plugins 全部建骨架，留 TODO；wiring 到 OSCAL service 留到 M4 closure 統一處理。理由：先確認 protocol shape 站得住、不要早期花時間在每個 OSCAL service 對接。事後 wiring 驗證 protocol，補進 OSCAL plugin。

D4：4 Type 分類框架（最關鍵的架構演進）

從原本「OSCAL vs Survey 二分」 → 演化成 OSCAL / 問卷 / 任務 / 混合 4 type，type = project type（不是 plugin type）。觸發點：user 在 22:44 ~ 03:45 期間舉「半年歲修重開機」、「每月意見調查」、「資安掃描」等場景，發現現有 OSCAL/Survey 二分 cover 不到「純任務派發」case。

決策過程：

1. 先試圖把任務硬塞進 OSCAL catalog → user 質疑「每月不同問卷都要新 catalog 太重」
2. 再試圖把任務塞進 Survey → 質疑「掃描報告場景不適合」
3. 最終定案：新增 4 個任務類 plugins + 3 個任務類 templates，type 是 project-level 而非 plugin-level，underlying 仍走相同 BPMN runtime
4. 產出 2 個 HTML 對照表給 PM / 開發者看（docs/analysis/2026-05-08-*.html）

D5：Truncate 既有 140 legacy projects 而非 migrate

決策依據：產品未上線（dev/staging only）；migrate 路徑要寫 backfill SQL 對齊新 BPMN flow + project_role_assignments，~1-2 週工程；truncate 是 1 行 SQL。Spec §11.4 統一架構（無雙路徑）授權此選項。

D6：D1 — complete-time config gap 用 node_config_overrides 解

Wiring 階段發現 plugin config 是 plugin-level，但同一個 plugin 在不同節點可能要不同 config（如 approval plugin 在「審核」vs「複覈」用不同 reviewer pool）。三個方案：

• (a) plugin variant — 開太多近似 plugins 維護爆炸
• (b) BPMN extension element 帶 inline config — schema 不在 BPMN 標準內
• (c) node_config_overrides JSONB column on workflow node — 採用

理由：config 是 BPMN-aware 但不在 BPMN spec；存資料庫 + 編輯器顯示，比 BPMN inline 易維護。

D7：B1 — 任務類 plugins 完成 (5 plugins + 3 templates)

5 plugins：task_assign / task_execute / task_recurring_trigger / task_aggregate / task_complete 3 templates：task-execute-only / task-with-approval / task-recurring

任務類專屬 entity strategy（不共用 OSCAL AP / Survey）— task 是輕量 entity，不掛 catalog/profile/AP 完整鏈。

D8：Template 去 OSCAL 化命名

Builtin templates 命名從早期 audit-full / audit-execute-only 改為 oscal-full-audit / oscal-execute-only 等明確區分。新增的 task / survey templates 也比照命名（survey-fill-only, task-recurring），讓 admin 一眼看出 type。

Phase 1 完工但 deferred 的 issues（3 個）

1. flow-engine-schema-migration-deferred — 既有 jedi-flow-engine 表保留 public，整潔度問題（Low）
2. tenant-create-role-catalog-hook — 新 tenant 自動 seed 4 個 builtin role 待整合 jedi-auth add_tenant（Low）
3. user-delete-cascade-hook — User force-delete cascade 清 assignments；M4 寫 wrapper 但 jedi-auth delete_user 沒攔（Low）

Plugin / Code TODO（M5+ / M6+）

• 6 個 TODO(M5+/M6+) 在 plugin code 內（部分通知 / dashboard 整合 / 進階審核流程）
• M5 FE：12-14 週工程（BPMN editor、template manager、role catalog UI、project flow viewer 等）
• M6 Test + UAT：10-11 週工程

測試相關

• Test isolation 修復（部分既有 OSCAL test 因 truncate 後 fixture 失效）
• Pre-existing test maintenance（M4 改動波及的舊 test）

Spec / Architecture follow-up

• BPMN editor 互動細節（M5 FE 範圍）
• Template versioning / migration upgrade path（snapshot-on-start 設計下，admin 改 template 不影響跑中 project；但跑完後升不升舊 project？— Phase 2 評估）
• Activity timeout / 卡住 dashboard（spec §16 open question）

Branch 狀態

• feature/project-flow-engine HEAD 0393613
• 62 commits ahead of main
• 57 commits ahead of origin/feature/project-flow-engine
• Working tree 乾淨
• 未 push、未 merge main

Push / Merge 指示

User 在 05:07 明確說：「不用回 main, 留在此 branch 就好, 我這邊手動 push」

→ 不要自動 push。User 自己手動 git push origin feature/project-flow-engine。

Staging / Test DB

• 已 truncate 既有 OSCAL/project 資料（d32ce43）
• 已 apply 4 個 migrations（execution-contexts / activity-logs / template-extensions / role-catalog）
• DB：192.168.50.188:25432 / guidant_ai_stg

接手者 Onboarding 順序

1. 看 docs/features/project-flow-engine-setting/design.md（spec，已含 A1 amendment）
2. 看 docs/analysis/2026-05-08-user-flow-comparison.html（4 type 視覺化對照）
3. 看 docs/analysis/2026-05-08-project-type-comparison.html（4 type 對照）
4. 看 SUMMARY.md（本檔）
5. 看 docs/changelog/2026-05-08-feat-flow-engine-m4-milestone-summary.md（M4 milestone 概覽）
6. 隨需求查 docs/changelog/2026-05-08-*.md 各細項

• 下個 session 重點：修 5 個 deferred issues（如果優先序拉到前面）、或進 M5 FE
• 不該再動的：4 type 分類框架已定案，不要重新 design；spec §11.x 已記錄所有 deviation
• 可以動的：plugin code 內 6 個 TODO(M5+/M6+) 對應通知 / dashboard 整合 / 進階審核流程
• Test 整理：truncate 後既有 OSCAL test fixture 部分壞掉，需要 isolation 修復
• 架構約束：本 arc 採 unified architecture（不做 legacy_oscal 雙路徑），dev/staging 既有資料已清，PROD 上線前要對齊 staging schema state

未納入：

• f77de22c-...jsonl（spec/plan 撰寫階段） — 已歸檔在 2026-05-07-project-flow-engine/
• ceeabdcb-...jsonl（3 msgs project status lookup） — peripheral，不影響 arc 內容

SUMMARY §1-§10 截止於 05-09 05:11（user 說「不用回 main, 留在此 branch 就好」）。本段為後續延伸 — user 把 branch 給另一個 AI 跑 5-agent code review (code-reviewer × 2 / silent-failure-hunter / pr-test-analyzer / type-design-analyzer / comment-analyzer)，找出 20 條 finding，user 選 (c) 全套修完進 M5。

11.1 Review findings 統計

11.2 6 Waves 執行（17 commits + 1 final summary）

11.3 累計成果（PR review 修補後）

• 17 個 fix commits + 1 final summary = 75 → 77 commits ahead of main
• 8 個新 GRC error code（GRC_400038-041 / GRC_412028-032）
• ~100 個新 test（Wave 2 +25 / Wave 3 +17 / Wave 4 +16 / Wave 6 +51 / 其他 ~10）
• 0 個 production code regression

11.4 規範遵循狀態（PR review 修補後）

11.5 Final regression（post Wave 6）

• Unit (test/): 326 passed
• E2E smoke (8 templates): 8/8 PASS（補 test DB task_assignees.is_approver schema drift 後）

11.6 Push 完成（2026-05-09 ~16:00）

User 主動 push branch 到 origin（先前 §8 「自己手動 push」 fulfilled）。

11.7 M5 FE Handoff 寫到 FE repo

compliance-manager-fe/docs/handover/2026-05-09-from-be-flow-engine-arc.md — 新 session 在 FE repo 開啟即可看到 onboarding pack：必讀文件清單、4 type 框架、API 摘要、M5 task breakdown（12-14 週）、BE 留下的 10 個雷區、PrimeVue 3.53 quirks、suggested first prompt。

11.8 References

• PR review prompt 存檔：docs/analysis/2026-05-08-code-review-prompt.md
• Final summary changelog：docs/changelog/2026-05-09-tweak-flow-engine-pr-review-final-summary.md
• 6 個 wave 各自 changelog 散在 docs/changelog/2026-05-08-fix-flow-engine-pr-review-wave-*.md + 2026-05-09-tweak-flow-engine-pr-review-wave*-*.md

真 End of Summary — 2026-05-09 ~16:00