Project Flow Engine Setting — Final Summary

Task arc：2026-05-07 ~ 2026-05-08 Branch：feature/project-flow-engine（領先 origin 3 commits 已 user 手動 push） 核心需求：把固定 5 phase OSCAL 稽核流程改造成 BPMN 驅動的可配置流程，並新增「通用流程」project type 支援問卷調查等不掛 OSCAL 概念的場景。產品未上線，採統一架構（無雙路徑）。產出：spec + plan，未實作。User 確認 N1-N6 修完即 archive，下個 session 啟動 M0 Spike。

1. Commits 清單

Hash	主題	行數變化
`ed72ae7`	Phase 0/1/3 brainstorm 產出 design + implementation plan	+6421
`d67237e`	plan amend — 補 4 個管理 UI + Review 策略明確化	+138 / -17
`029b2b4`	外部 reviewer Pass 1 — 11 條設計缺口修正	+601 / -45
`c8a394e`	audit-lifecycle/state-tracking-guide（順帶 commit）	+264
`e04255c`	外部 reviewer Pass 2 — N1-N6 修正	+113 / -14

2. 改動範圍 / 規範文件齊全度

主交付（docs/features/project-flow-engine-setting/）

檔	最終行數	用途
`design.md`	1630 行	Spec — 17 個 section，通過 3 輪 reviewer + 2 輪外部 AI
`implementation-plan.md`	1889 行	Implementation plan — 7 milestone / 50+ task / 通過 plan reviewer
`architecture.html` + `.pdf`	—	概念視覺化（Activity Registry + 三 use case BPMN flow + 兩決策軸）
`design.html`	—	spec markdown 暗色 HTML 版本（pandoc + 自訂 CSS）

Changelog（docs/changelog/）

2026-05-08-tweak-project-flow-engine-spec-and-plan.md
2026-05-08-tweak-project-flow-engine-plan-amend.md
2026-05-08-tweak-project-flow-engine-external-review-fixes.md
2026-05-08-tweak-project-flow-engine-reviewer-pass2.md
2026-05-07-tweak-audit-lifecycle-state-tracking-guide.md（順帶）

Conversation History（本資料夾，gitignored）

part-01-of-05-brainstorm-architecture-decision.md — 200 訊息
part-02-of-05-spec-and-internal-reviewer.md — 200 訊息
part-03-of-05-implementation-plan-writing.md — 150 訊息
part-04-of-05-plan-amend-and-external-reviewer-pass1.md — 130 訊息
part-05-of-05-external-reviewer-pass2-and-archive.md — 66 訊息
本檔 SUMMARY.md

3. 行為差異（為什麼這樣設計）

3.1 採用的設計

設計決策	為何
γ Activity Registry + Plugin 化	對比硬編 step type 維護會崩；plugin 化讓加新流程 = 加 plugin，不改核心
OSCAL 拆 5+1 個 activity（preparing / active / internal_review / external_audit / remediation + kickoff + close）	User 實際遇到 A/B/C 三家公司不同流程組合需求 — 拆 2 段不夠（B 公司要跳過 internal_review）
6 個固定 phase（setup / execute / review / audit / remediation / close）	跨 tenant 視覺一致 + 跨 template 可比；tenant 自訂 phase 留 Phase 2 deferred
Role Catalog 兩層分離（系統 RBAC + Project Role）	業界標準（Atlassian / GitHub / Salesforce）；project role 可自訂、系統 RBAC 不被污染
Snapshot-on-start	admin 改 template 不影響跑中 project；既有 OSCAL AO 也是這個 pattern
AP.status 降級為 OSCAL 內部 sub-state	外部用 BPMN current_node + phase；AP.status 仍是既有 OSCAL service 內部判斷分支用
雙寫 audit log（activity_logs 主 + jedi-common SystemLog 同步重要事件）	activity_logs 給 ops 查進度 / 除錯；SystemLog 給 admin audit dashboard。用途不同
統一架構，不做 legacy_oscal 雙路徑	產品未上線，dev/staging 測試資料可清，省一週工程量
Phase 1 不做 sub-flow library	User 直覺指出「實體獨立 + 狀態觸發」比 sub-flow 嵌套更乾淨；OSCAL AP / Survey / POA&M 各 aggregate 獨立

3.2 排除的選項

排除選項	原因
Sub-flow callActivity 嵌套全流程	強耦合、跨 entity context 複雜、跟既有 OSCAL aggregate 設計衝突
Phase 動態 catalog（tenant 自訂）	YAGNI — 6 個 enum 涵蓋既有業務；未來真有客製需求再升級（Phase 2 deferred）
OSCAL 拆到最細（5 個獨立 activity 不含 close）	過度；POA&M 跨 round 邏輯拆細會奇怪
Builtin v1 → v2 自動升級既有 snapshot	違反 snapshot-on-start 設計初衷；Phase 2 評估 PM 主動觸發升級
Schema-level audit trigger（防 UPDATE assessment_plans）	Phase 2 deferred — 程式紀律 + code review 為 Phase 1 兜底

4. 規範文件清單對照

規範要求	狀態
Changelog（每個 task arc 一份）	✅ 5 份
Spec 在 docs/features//design.md（不是 superpowers/specs/）	✅
Plan 在 docs/features//implementation-plan.md	✅
對話歷程歸檔到 docs/conversation-history/	✅ 本資料夾（gitignored）
Activity 階段對應中文翻譯來自 FE i18n grc-shared.json	✅（reuse 自 audit-lifecycle 章節）
SQL migration 加日期 comment + GRANT cm_app + 用 cmmgr 跑	✅（spec § 5）
重大決策落地 docs/analysis/ 推理過程	⚠️ 未做 — brainstorm 過程過大，已濃縮在 spec 各段 + 本 SUMMARY

5. 已知 Follow-up（Phase 2+）

依 spec §16 Open Questions：

Activity Plugin versioning（同 type_name 多版本）
Activity timeout 通知策略
Diagnostic UI 細節
Snapshot vs Live diff 視圖 — admin 改 live 時不知差異
Builtin template v1→v2 升級既有 snapshot 的 migration tool
Snapshot table retention policy（GC 策略）
OSCAL plugin 不純化的 retrofit path（v2 vs config 化）
AP.status schema-level 防呆（PostgreSQL audit trigger）
i18n key 命名規範
BPMN editor palette 排序 / 分類

每項在 §16 都有 Phase 1 / Phase 2 取捨說明。

6. 部署 / Handover 準備

6.1 啟動實作的 prerequisite（依 plan）

Branch feature/project-flow-engine 已 push（user 手動完成）
M0 Spike 必驗 4 項已寫進 plan：@transaction / context mapping / SQLAlchemy session / run_no SoT
M3 deploy gate 已寫：FK 驗證 + cleanup script

6.2 啟動 prompt（給下個 session 的新 Claude）

我要開始實作 BPMN flow engine。先讀以下兩份：
- docs/features/project-flow-engine-setting/design.md
- docs/features/project-flow-engine-setting/implementation-plan.md

依 plan header 的 REQUIRED SUB-SKILL，用 superpowers:subagent-driven-development 啟動。
從 M0 OSCAL Spike 開始。

review 策略（plan header 有寫）：只 M4 結束 user review 一次，
其他 milestone agent 自測 + smoke 即可，不打擾 user。

6.3 Estimate

11-13 週（單人 senior FE+BE，含 4 個管理 UI + 11 條外部 reviewer 修正）。

Milestone	週
M0 OSCAL Spike	1
M1 Core Infrastructure	1-2
M2 Activity Plugins (12 個)	3-5
M3 Templates + Snapshot + DB Seed	6
M4 API + Role Catalog（★ user review gate）	6-7
M5 FE + 4 個管理 UI	7-9
M6 Test + Regression + UAT	10-11

7. Reviewer 軌跡

輪	結果	主要修正
Internal Pass 1	Approved	0 條
Internal Pass 2	4 issues	start_mode / @transaction / external_audit relaunch / review_loop_gateway 等
Internal Pass 3	Approved	—
Plan Pass 1	9 issues	is_pure_gateway / phase_progress / cascade / dual-write / extra_check / entity_counter / eager init / OSCAL E2E rewrite / activity_logs ordering
Plan Pass 2	Approved	3 minor（schema 確認 / SystemLogEmitter / TRUNCATE flow_engine 表）
External Pass 1	11 issues	A 狀態機 / B Plugin 介面 / C UX / D API filter / E Open Questions
External Pass 2	設計層面已無阻擋性問題	N1-N6 polish 全修

下個 session 啟動實作前，先 /clear 清掉本 session 的 brainstorm 雜訊，新 session 只讀 design.md + plan.md 開工。