# 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/<feature>/design.md（不是 superpowers/specs/）| ✅ |
| Plan 在 docs/features/<feature>/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：

1. Activity Plugin versioning（同 type_name 多版本）
2. Activity timeout 通知策略
3. Diagnostic UI 細節
4. **Snapshot vs Live diff 視圖** — admin 改 live 時不知差異
5. **Builtin template v1→v2 升級 既有 snapshot 的 migration tool**
6. **Snapshot table retention policy**（GC 策略）
7. **OSCAL plugin 不純化的 retrofit path**（v2 vs config 化）
8. **AP.status schema-level 防呆**（PostgreSQL audit trigger）
9. i18n key 命名規範
10. 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 開工。