# FR-170 交接現況（STATE）

> **這份是 living 檔**：每棒就地 Edit，只描述「此刻」。歷史脈絡看同資料夾的 `FR-170-LOG.md`。

| 項目 | 值 |
|------|-----|
| 最後更新 | 2026-10-31 下午（第 4 棒：P1～P3 全部完成、總驗收、合回主線並推 origin） |
| 狀態 | **P0～P3 全部完成並合回三 repo 的 `feature/FR-139`、已推 origin；主系統已接契約（BE `18642c6cf`／`198074868`）、Agent 改釘正式版（`c99da8c`）。** 剩：P1～P3 的工作坊 29 結案、188 真跑一次 Nuitka 出包、BE 重啟 |
| branch | BE／Agent／jedi 皆 `feature/FR-139`，本機與 origin 一致（Agent `3ab1253`、jedi `fc67330e`、BE `052f54af3` 之後再加本棒交接 commit） |
| 母卡 | P0：CM-3232（17 張，全 Done，工作坊 28 已於 10-30 結案）／ P1～P3：**CM-3324**（16 張：CM-3319～3323、3326～3330、3332～3335、3345、3357，全部驗收通過；工作坊 29 可結案）。CM-3325／3331 是作廢的空母卡（已 Done 標「已併入」） |
| 本機 Agent | `~/guidant-agent-local/start-agent.sh` 跑主資料夾 `feature/FR-139`，venv `evidence-agent-knWYPLiu-py3.13`；agent.db v7 |
| 接手前必讀 | §0 |

## 🧭 原始需求 / WHY

- **決策者原話**（2026-10-29）：「當初的定位已經被老闆推翻了」「現在變成像 SaaS 的其中一個端點，比較像 Client」「未來難預測會不會重點功能都移到 agent 這邊」「不想再重複開發很多東西」「看起來是一坨義大利麵」。
- **要解決什麼**：evidence-agent 21,000 行平鋪在 `core/` 一層、36 支各寫 SQL、27 處全域、與主系統重複實作密碼政策／LDAP／session／事件碼。根源是 jedi-common 釘 0.0.31，什麼 jedi 套件都裝不進去只能另寫。
- **目標（已達成）**：Agent 當獨立產品看，**模組在外、層在內**（`guidant_agent/{platform,identity,sync,scan,netdiag,files,console,shared}`），五個業務模組彼此只走 port，守衛擋新程式寫錯位置。
- **決策者後續裁示**：命名 `guidant-agent`／`guidant_agent`；半夜無人值守一路跑完（P1～P3 單一工作坊批 12～23）；「很多決策其實沒那麼重要，都可以往下跑」→ 14 張卡都 append「無人值守決策表」；P4（心跳瘦身、指令類改直推 8443）**暫緩，等重構完再議，因為要改主系統**。

## §0 接手讀序

1. 本檔 §1、§2、§4
2. `FR-170-LOG.md` 第 4 棒 block（總驗收怎麼做、合回時 FR-167 衝突怎麼解、review 結論）
3. Agent repo：`docs/ARCHITECTURE.md`（憲章，P3-5 後是終局版）、`CLAUDE.md`「程式放哪裡」「資安開發規範」、`.claude/rules/security/` 六支
4. `../design.md` §2 目標結構、§5～§5.3 四期拆卡、§7 風險；`../../../analysis/2026-10-29-agent-architecture-direction.md`
5. 要開 P4 才讀：本 LOG 第 4 棒「P4 分析」段（心跳 24 鍵分三類、只有指令類該改直推、WebSocket 不做的理由）

## §1 終局現況（2026-10-31）

**目錄**：`core/`、`api/`、`di_containers/` 已刪；`guidant_agent/` 八個模組（identity 22 支、sync 34、scan 41、netdiag 23、files 19、console 18、platform 29、shared 7，約 23,600 行）。`LEGACY_MODULE_OF` 只剩 `main_app`／`config`／`common` 三個頂層 8 列（設計保留）。

**守衛（全部綠、白名單歸零）**：跨模組 import 邊 70→0、模組層全域 27→0、模組內層級方向（新）0、SQL 只在 adapters（platform 維運兩支保留）、`core/` 不存在（新）、背景元件、檔案 800／函式 60、資安規則覆蓋、只包一把鎖的類別（新）。

**行為不變的證據**：全量 **2014 綠**（P0 前 55 支測試檔全保留；新增守衛與元件測試）；主控台＋資料面 **49 條路由路徑與重構前 `d2fe93f` 完全相同**；心跳 byte 比對測試綠；demo 模式空庫升 v7、SIGTERM 兩秒內結束；本機真機連 DEV BE 心跳 200、主控台登入、API 無 session 401、8443 無憑證 TLS 層拒絕。

**review**：`ddd-compliance-reviewer`（opus）掃 310 檔 diff 結論「只搬不改」，五個最危險檔（心跳迴圈、下載通道、密碼驗證與 rehash、Fernet 金鑰、connector subprocess 參數）逐行等價。兩條阻斷首腦修在 `8a807dc`（platform 經字串 import 繞進 identity；LDAP 指紋寫入掉鎖），九項警告由 CM-3357 清完。

**套件（Nexus 正式版）**：jedi-common 1.3.7、jedi-password 0.1.0、jedi-iam 1.11.0（主線後被 FR-167 升到 1.11.1）、jedi-source-scan 0.5.1、jedi-ai-gateway 0.1.3、**jedi-agent-protocol 0.1.0**、jedi-remote-agent 1.11.0。Agent 釘 jedi-common 1.3.7、jedi-file-upload 1.5.0、jedi-password、jedi-agent-protocol 0.1.0b1（**P3-2 釘的是 beta，改釘 0.1.0 正式版併入下一張 Agent 小卡**）。

**FR-167 交會**：主線 FR-167 P8-5／P9-4（`/update/notify`、`/update/progress`、`/update` 守門、1.4.6）在合回時人工歸位到新結構，功能一個不少；`/update/*` 由 `sync.register()` 掛。**主系統不需跟著改。**

**Agent 1.4.6 是第一個新架構版**：P2-5 改了 Nuitka 編譯清單與 manifest 檔案清單但**沒在 188 真跑過**，出包前必跑一次 `build_all.sh`（已用 prompt 通知 FR-167 首腦）。

## §2 四期總表

| 期 | 母卡 | 卡 | 狀態 |
|---|---|---|---|
| P0 相依斷層＋宿主殼＋守衛 | CM-3232 | 17 | Done，合回 `8585e99`／`9044d95`，工作坊 28 已結案（10-30） |
| P1 搬 identity、sync | CM-3324 | 5（3319～3323） | 驗收通過，合回 `3ab1253` |
| P2 搬 scan／netdiag／files、console 退聚合、刪 core/ | CM-3324 | 6（3326～3330、3345） | 同上 |
| P3 抽 jedi-agent-protocol | CM-3324 | 4（3332～3335） | 同上；套件 jedi `fc67330e` |
| 收口清理 | CM-3324 | 1（3357） | 同上 |
| P4 心跳瘦身／指令類改直推 8443 | 未開 | 估 3 張 2 批 | **暫緩**，要改主系統，等決策者 |

## §3 Notion 卡索引

母卡 CM-3232（P0）、CM-3324（P1～P3）。子卡網址：`notion-cards-made.json`（P0）、`notion-cards-p1-made.json`、`notion-cards-p2-made.json`、`notion-cards-p3-made.json`、`notion-cards-p3-5-made.json`；`parent-cards.json` 列母卡對照。拆卡底表 `cards.py`／`cards_p1.py`／`cards_p2.py`／`cards_p3.py`。

## §4 下一棒要做什麼

**決策者動手**
1. P1～P3 那輪的工作坊（29，母卡 CM-3324）結案：狀態頁按，會收三 repo 的 `.worktrees/CM-3324`。P0 那輪已於 10-30 結案。
2. Agent 主資料夾 `CLAUDE.md` 有 agent-workshop 自動寫的 pointer 區塊未 commit（2026-10-31 13:20），由工作坊自己處理，首腦不碰。

**首腦（等令）**
3. **188 真跑 Nuitka**：`git pull` 到 `3ab1253`，`scripts/build/build_all.sh`，驗編得過、`startup_gate` 驗章過、smoke 起得來；壞了多半是 P2-5 清單漏檔。FR-167 首腦若先跑了就看他的結果。
4. ~~主系統接契約~~ **已做**（第 4 棒直接做，決策者「你直接做」）：BE `18642c6cf` 釘 jedi-remote-agent 1.11.0＋jedi-agent-protocol 0.1.0、EventCode 43 碼改取契約、新守衛 `test_event_code_agent_contract.py`；`198074868` 套件守衛三表登記。**BE 要重啟**。
5. ~~Agent 改釘正式版~~ **已做**：`c99da8c`。
6. **P4 裁示後開卡**（暫緩中）：分析在 LOG 第 4 棒。結論：心跳回應 24 鍵裡只有指令類 4 鍵（`pending`／`restart`／`update`／取消）該改直推 8443，設定同步類改帶版本號有變才送，對帳類不動；WebSocket 不做（落地版不需要、資安比直推差、SaaS 不開 8443 時再議）。約 Agent 一張＋主系統一張＋jedi-remote-agent 一張，建議另開 FR 因為改對外契約。
7. **拆兩支超標 connector**（`sonarqube.py` 1,711 行、`inspec.py` 1,052 行，P2-2 只搬不拆）：另開卡。
8. 收尾文件（等令）：design §8 改成「P0～P3 完成」、`docs/analysis` 補一篇「無人值守決策表」與「Done ≠ 進主線」的教訓、Agent `docs/oversized-files.md` 核對。

## §5 已定裁示（不要重問）

- 四條裁決全採建議；命名 `guidant-agent`／`guidant_agent`；套件開發卡只發 beta、結案卡轉正式。
- 三期母卡原本各自獨立（P0 結案要求子卡全 Done），後決策者裁「P2、P3 合併到 P1 卡下面半夜跑完」→ 14 張全掛 CM-3324 單一工作坊。
- 無人值守決策表（2026-10-30 晚，決策者「很多決策其實沒那麼重要」）：白名單同形直接加、版號撞號自己 bump、既有紅燈不修只記、卡上路徑與實際不符以實際為準、對方缺方法補薄方法；真的要停只有別人的未 commit 改動／branch 不對／要做卡上明寫另開卡的事。
- domain 層准用純演算法庫與零相依 kernel 庫（cryptography、PyJWT、jedi-password）；只包一把鎖的類別算全域、要收進 DI（P3-5 落實）。
- P4 暫緩，等重構完成再議（2026-10-31）。
- 主系統不因本次重構改動（心跳契約與資料面介面不變）。

## §6 pre-flight（接手先跑，唯讀）

```bash
cd ~/Projects/Billows/Audit-Manager/compliance-manager-be
for r in ~/Projects/Billows/Audit-Manager/evidence-agent ~/Projects/Jedicogy/module/jedi-python-package .; do echo "== $r"; git -C $r log --oneline -2; git -C $r status --short --untracked-files=no | head -3; git -C $r rev-list --count origin/feature/FR-139..HEAD; done
ls ~/Projects/Billows/Audit-Manager/evidence-agent/guidant_agent/; ls -d ~/Projects/Billows/Audit-Manager/evidence-agent/{core,api,di_containers} 2>&1 | grep -c "No such"
git -C ~/Projects/Billows/Audit-Manager/evidence-agent worktree list
sqlite3 ~/Projects/Jedicogy/agent-workshop/.workshop/workshop.db "select id,status,approved_stage from workshops where id in (28,29)"
lsof -nP -iTCP:8010 -sTCP:LISTEN | tail -1   # 本機 Agent
```

## §7 行為規範（本案特有）

- 首腦不開 subagent；唯一例外是母卡收口的 `ddd-compliance-reviewer`（CLAUDE.md 規定），派時帶 model／effort。
- **驗收用「合併演練＋全量測試＋路由集合 diff＋demo 起服務＋真機基本功能」一輪批次做，不逐檔讀**（決策者兩度點名「不要用沒效率的方式分析」「不要檢查的太繁瑣」）。路由比對用 `git grep -hoE '(\.route|add_url_rule)\("/[^"]*"' <ref> -- '*.py' ':!test/*'` 兩個 ref 各一份 diff。
- **Done ≠ 進主線**：工作坊把卡合進 `ws-<母卡>` 就標 Done，首腦抽查要多看一步 `ws vs feature/FR-139`。
- **合回主線前先把主線合進 ws 解衝突**，在 ws 上跑全量，再合回主線；平行 FR 在舊路徑上加的改動 git 會跟著 rename 套到新位置，但要核對，並把舊路徑 import 改掉。
- 卡工作區跑守衛可能假紅：`.worktrees` 排除要用相對路徑判（`d7bc4e6`）。
- push：`glab auth git-credential` 已設為 gitlab.com 的 credential helper，推前 `git fetch` 確認遠端無新 commit。
- 查 Nexus 版號：`curl -u jedi:$(security find-generic-password -s poetry-repository-nexus -a jedi -w) http://192.168.50.171:8082/repository/pypi-group/simple/<pkg>/`。