docs(openspec): 批次歸檔 #178/#179/#180 archive 對齊 + roadmap sync - #181
Merged
Merged
Conversation
…-06-04） 歸檔三個已 merged change： - agent-ship-cycle-automation：ship-cycle 自動化（agent-operability-governance +1 req） - edge-console-p2-p4-buildout：P2-P4 前端補齊（edge-console-operator-frontend +5 req） - unified-governance-console：統一治理控制台北極星，純規格（新 capability unified-governance-console +5 req，openspec/specs/ 40→41） 補 unified-governance-console/spec.md Purpose（原 TBD）。 修正 3 個 spec.md EOF 空行（perl strip）。 roadmap update-log 加 2026-06-04 批次歸檔條目。 npx openspec validate --all --strict = 41 passed / 0 failed。 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Contributor
📝 WalkthroughWalkthroughThis PR documents the governance console architecture and agent automation specifications for AI-BIM across four specification files: roadmap archival, agent operability, edge console operator frontend, and a new unified governance console specification. ChangesGovernance Console and Agent Automation Specifications
Estimated code review effort🎯 2 (Simple) | ⏱️ ~12 minutes Possibly related PRs
Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
Contributor
There was a problem hiding this comment.
Pull request overview
This PR performs a docs-only OpenSpec archive + roadmap sync: it adds the archived artifacts for three previously-merged OpenSpec changes, updates the live capability specs to reflect those changes, and records the batch in the 2026-05 SaaS roadmap update log.
Changes:
- Added a new live capability spec:
unified-governance-console(north-star spec, requirements + scenarios). - Updated live capability specs for
edge-console-operator-frontend(+5 requirements) andagent-operability-governance(+1 requirement). - Added archive artifacts under
openspec/changes/archive/2026-06-04-*and updateddocs/plans/AI-BIM-governance-saas-roadmap-2026-05.mdwith the 2026-06-04 batch entry.
Reviewed changes
Copilot reviewed 4 out of 14 changed files in this pull request and generated 1 comment.
Show a summary per file
| File | Description |
|---|---|
| openspec/specs/unified-governance-console/spec.md | Adds the new “unified governance console” north-star capability spec (purpose + requirements/scenarios). |
| openspec/specs/edge-console-operator-frontend/spec.md | Extends Edge Console operator frontend spec with P2–P4 requirements (honest endpoints, fake-vs-real mapping, vision pages, review room). |
| openspec/specs/agent-operability-governance/spec.md | Adds requirement formalizing buffered per-item ship-cycle automation for agents. |
| openspec/changes/archive/2026-06-04-unified-governance-console/proposal.md | Archived proposal artifact for unified governance console spec-only change. |
| openspec/changes/archive/2026-06-04-unified-governance-console/design.md | Archived design summary + decisions + invariants for the north-star capability. |
| openspec/changes/archive/2026-06-04-unified-governance-console/tasks.md | Archived tasks/checklist and verification notes for the change. |
| openspec/changes/archive/2026-06-04-unified-governance-console/specs/unified-governance-console/spec.md | Archived spec delta capturing the added requirements for the new capability. |
| openspec/changes/archive/2026-06-04-edge-console-p2-p4-buildout/proposal.md | Archived proposal for Edge Console P2–P4 frontend buildout change. |
| openspec/changes/archive/2026-06-04-edge-console-p2-p4-buildout/tasks.md | Archived tasks/checklist for Edge Console P2–P4 buildout and verification. |
| openspec/changes/archive/2026-06-04-edge-console-p2-p4-buildout/specs/edge-console-operator-frontend/spec.md | Archived spec delta for the +5 edge-console-operator-frontend requirements. |
| openspec/changes/archive/2026-06-04-agent-ship-cycle-automation/proposal.md | Archived proposal for per-item ship-cycle automation workflow/spec change. |
| openspec/changes/archive/2026-06-04-agent-ship-cycle-automation/tasks.md | Archived tasks/checklist for ship-cycle workflow/spec change. |
| openspec/changes/archive/2026-06-04-agent-ship-cycle-automation/specs/agent-operability-governance/spec.md | Archived spec delta for the added buffered ship-cycle automation requirement. |
| docs/plans/AI-BIM-governance-saas-roadmap-2026-05.md | Roadmap update-log entry for the 2026-06-04 archive batch and capability deltas. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
|
|
||
| - **WHEN** 操作員在 A1–A10 overlay 對一個帶有效 `usd_prim_path` 的治理失敗構件按「在 3D 標示」 | ||
| - **THEN** HighlightBridge SHALL 以該 `usd_prim_path` 組成 `highlightPrimsRequest` | ||
| - **AND** SHALL 經 primary viewer 既有的 WebRTC DataChannel（`Window._sendStreamMessage`，client 主動拉）送至 Kit runtime |
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 4dfe050616
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
|
|
||
| ### Requirement: 前端 SHALL 只經 coordinator :8004，SHALL NOT 直連 :49102；誠實 provenance + 後端離線 502 | ||
|
|
||
| 統一治理控制台前端（含 A1–A10 overlay、三個 operator 頁、HighlightBridge / MappingCache 的資料存取）SHALL 只經 coordinator `:8004`（`/api/governance/*` proxy、`/api/external/ifc-ready`、`/api/review-sessions`、stream-config 等已驗證端點），SHALL NOT 直連 `governance-service` 的 `127.0.0.1:49102`，亦 SHALL NOT 直連 `bim-streaming-server` 的 `49100/47998`。前端 SHALL 對每塊資料與每顆動作標誠實 provenance（`asbuilt` / `artifact` / `demo` / `p1` / `p15`），待建項 SHALL 標 `p1` / `p15` 並 `disabled`。當 coordinator / 後端不可達時，前端 SHALL 誠實顯示 502（後端離線），SHALL NOT 偽裝成功、SHALL NOT 顯示捏造數值、SHALL NOT 殘留舊結果假裝成功。 |
There was a problem hiding this comment.
For the unified overlay path, this blanket ban also covers the Kit signaling/media endpoints that the primary viewer must use for live 3D and DataChannel actions: the same spec requires highlightPrimsRequest to go through the primary viewer WebRTC DataChannel, and the repo boundary has web-viewer-sample -> bim-streaming-server over WebRTC/DataChannel on the Kit runtime ports. If implemented literally for the primary viewer overlay, the UI could call coordinator for governance data but would be forbidden from opening the 49100/47998 stream, so there is no live 3D or highlight channel to attach the overlay to. Narrow this requirement to governance/control-plane HTTP data access, not the viewer’s WebRTC streaming connection.
Useful? React with 👍 / 👎.
|
|
||
| ### Requirement: A4–A10 vision 詳頁 SHALL 整段標願景，scenario SHALL 標範例情境且 SHALL NOT 當真實實測 | ||
|
|
||
| AppsPage 的 A4–A10 roadmap 卡 SHALL 可點並導向泛用 vision 詳頁（`app/<slug>`）。每個 vision 詳頁 SHALL 顯示 DB schema / REST api / UI 面板 / MVP 驗收 / sprint steps / risks，且 SHALL 明確標示「後端未建」（願景，prov `p3`/`p4`：A5=p3、其餘 p4）。詳頁的 scenario SHALL 標示為「範例情境（願景敘事，非真實 run）」，SHALL NOT 將 RM_APPS 內具體數字呈現為本系統真實實測。詳頁的 api 區 SHALL 標示為「願景 API 設計（非已實作 route）」，SHALL NOT 呈現為可呼叫的真實端點。vision 詳頁 SHALL NOT 顯示任何捏造的成功數字（如 99.1% / 92.4%）。 |
There was a problem hiding this comment.
This new requirement mandates prov values of p3 and p4, but the same capability still defines the authoritative provenance set as only asbuilt | artifact | demo | p1 | p15 in the earlier provenance-type requirement. In the A4–A10 vision-page scenario, implementers now have two contradictory spec requirements: either mark roadmap cards as p3/p4 or restrict components to the old enum, which can reintroduce the exact type/provenance drift this spec is meant to prevent. Update the earlier authority list to include p3/p4 when adding these phase markers.
Useful? React with 👍 / 👎.
|
|
||
| ### Requirement: operator 頁 SHALL 分離於三條獨立路由，SHALL NOT 混入 A1–A10 治理 overlay | ||
|
|
||
| 統一治理控制台 SHALL 提供三個**獨立 operator 頁**（非 viewer overlay）：`/console/coordinator`（Coordinator 控制台：sessions / control，參考 bim-desigin-arich「02 Coordinator 控制台」設計）、`/console/intake`（模型進件 / 版本，A1）、`/console/runtime`（Kit / WebRTC runtime 狀態）。這三頁 SHALL NOT 混入 A1–A10 業務治理 overlay；A1–A10 治理 SHALL 僅疊在 primary viewer overlay。`/console/intake` 的 A1 進件 SHALL 讓操作員從現成模型清單選取，SHALL NOT 要求手填模型路徑。 |
There was a problem hiding this comment.
These new operator URLs are path routes, but the current console entry point only switches to EdgeConsole for /console paths and then routes pages from window.location.hash, defaulting to overview when the hash is empty. As a result, opening /console/coordinator, /console/intake, or /console/runtime currently lands in the console shell with the Overview page rather than the requested operator page, so E2E tests or users following this spec will not reach the intended screens. Either specify the existing hash routes or require updating the router to parse these path segments.
Useful? React with 👍 / 👎.
Contributor
PR Review Agent Summary
Blockers
Warnings
Validation Commands
Checks
Human Review Notes
|
…ciliation） 1. unified-governance-console §highlightPrimsRequest：明確指 `web-viewer-sample/src/Window.tsx` React 元件 private method `_sendStreamMessage`，非 browser global Window。 2. unified-governance-console §前端禁令：限縮為「governance / 資料 API 禁直連 :49102」，明確 carve-out primary viewer ↔ Kit WebRTC 串流 + DataChannel（含 highlightPrimsRequest / focusPrimRequest）為既有合法 runtime 通道，對齊 AGENTS.md §3.5/§6 boundary。 3. unified-governance-console §operator 頁路由：改為 `/console#coordinator` / `#intake` / `#runtime` hash 路由，與既有 EdgeConsole.tsx 零依賴 hash 路由一致，不捏造後端 path router。 4. edge-console-operator-frontend §provenance 型別：補全權威集合為 `asbuilt | artifact | demo | p1 | p15 | p3 | p4`，與 data.ts Prov 型別及 A4–A10 roadmap 標示一致，消除 p3/p4 不一致。 validate: 41 passed, 0 failed Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Contributor
PR Review Agent Summary
Blockers
Warnings
Validation Commands
Checks
Human Review Notes
|
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 795ff1cd8e
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
|
|
||
| ### Requirement: 前端 SHALL 只經 coordinator :8004，SHALL NOT 直連 :49102；誠實 provenance + 後端離線 502 | ||
|
|
||
| 統一治理控制台前端（含 A1–A10 overlay、三個 operator 頁、HighlightBridge / MappingCache 的**治理 / 資料 API** 存取）SHALL 只經 coordinator `:8004`（`/api/governance/*` proxy、`/api/external/ifc-ready`、`/api/review-sessions`、stream-config 等已驗證端點）取得治理資料，SHALL NOT 直連 `governance-service` 的 `127.0.0.1:49102`，亦 SHALL NOT 以治理 / 資料 API 目的直連 `bim-streaming-server` 的 `49100/47998`。**例外 carve-out（既有合法 runtime 通道）**：primary viewer（`web-viewer-sample`）與 Kit 之間的 WebRTC 視訊串流及 DataChannel JSON command（含 `highlightPrimsRequest` / `focusPrimRequest`）是既有的 client-主動 runtime 通道（`:49100` signaling / media），不在此禁令範圍內；HighlightBridge 透過此 DataChannel 推送高亮指令屬合法用途，與 AGENTS.md §3.5/§6 viewer↔streaming-server boundary 一致。前端 SHALL 對每塊資料與每顆動作標誠實 provenance（`asbuilt` / `artifact` / `demo` / `p1` / `p15`），待建項 SHALL 標 `p1` / `p15` 並 `disabled`。當 coordinator / 後端不可達時，前端 SHALL 誠實顯示 502（後端離線），SHALL NOT 偽裝成功、SHALL NOT 顯示捏造數值、SHALL NOT 殘留舊結果假裝成功。 |
There was a problem hiding this comment.
Fresh evidence beyond the earlier provenance comment: this newly archived unified spec still narrows every data/action provenance badge to asbuilt / artifact / demo / p1 / p15, while the same commit’s edge-console spec and web-viewer-sample/src/console/data.ts make A4–A10 roadmap/vision items authoritative as p3/p4. Implementers following this line for the A1–A10 overlay would either reject those valid roadmap badges or downgrade them back to p1/p15, recreating the provenance drift the archive is trying to resolve.
Useful? React with 👍 / 👎.
|
|
||
| ### Requirement: MVP 垂直切片 SHALL 強制 identity profile，coverage 不足 SHALL 依既有 spec 誠實降級 | ||
|
|
||
| MVP 垂直切片（A1 進件 → A2 轉檔 / 語意映射 → A3 規則檢核 → A4 治理分 → 點 failed 構件在 3D 標紅 → A8 開 BCF issue）SHALL 強制 identity profile 為 `guid_exact` 且 coverage 為 `1.0`。當 coverage < 90%（低覆蓋 fallback 觸發）時，系統 SHALL 依既有 spec 誠實降級：依 `host-native-conversion-authority-service` 把未對映 entity 報為 `unmapped` / `sidecar-only` / `omitted` 且 SHALL NOT 建立假 GUID→prim mapping 灌水 coverage；依 `runtime-verification-evidence` 採 measure-first（誠實報 coverage、低覆蓋 warn 不 fail、threshold lock 後 `minimum_coverage_ratio=1.0`、`coverage_denominator=source_ifc_entity_count`）；依 `governance-rule-run-authority` SHALL NOT 把非 `guid_exact` 的 mapping 當作 `guid_exact`，且 fake / smoke mapping（`mock` / `allow_fake_mapping` / `fake_mapping_count>0` / `mapping_method=fake_for_smoke_test`）SHALL NOT 被當作真實覆蓋率。MVP SHALL 只使用已驗證的 coordinator / governance 端點，SHALL NOT 引入新引擎以滿足 fallback。 |
There was a problem hiding this comment.
This MVP flow assigns the product codes to the wrong capabilities: the repo contract maps A1 to BIM governance/rule-run, A2 to version diff, A3 to federation, A4 to semantic search, and A8 to synthetic data, but this line describes A1 as intake, A2 as conversion/mapping, A3 as rule check, A4 as governance score, and A8 as BCF issue creation. If implementers use this archived north-star spec as the acceptance path, they will build or test the overlay against the wrong A1–A10 modules instead of the authoritative product map.
Useful? React with 👍 / 👎.
**修正 1（provenance 集合補 p3/p4）** - Requirement「前端 SHALL 只經 coordinator…誠實 provenance」原窄化為 `asbuilt / artifact / demo / p1 / p15`，但同 commit 的 `edge-console-operator-frontend` spec 與 `web-viewer-sample/src/console/data.ts` 已含 `p3` / `p4` - 補成完整集合並加說明：p3/p4 為 RM phase 3/4 願景項， 與上述兩份 artifact 的 Prov 型別定義一致 **修正 2（A1–A10 新治理工作流編號明確註記）** - MVP 流程描述中的 A1–A10 非舊 roadmap-data.jsx RM_APPS 誤植， 而是 2026-06-04 使用者拍板的新治理工作流編號 - 加入 HTML comment 明確說明新舊編號的刻意差異， 並聲明本 capability spec 為新編號的權威對映 validate: 41 passed, 0 failed Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Contributor
PR Review Agent Summary
Blockers
Warnings
Validation Commands
Checks
Human Review Notes
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/plans/AI-BIM-governance-saas-roadmap-2026-05.md`:
- Line 11: The roadmap archive entry increments openspec/specs from 40 to 41 but
downstream summaries still show 39; update the inventory counts in this same
document by synchronizing all references (e.g., the §1.2 and §1.4 summary lines
and any other occurrences) to reflect openspec/specs = 41 and adjust any derived
totals or parentheses so the document is internally consistent with the new
archive entry (search for "openspec/specs/ 39", "39", and the §1.2/§1.4 blocks
and replace with 41 where appropriate).
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: c2eb30c2-62ec-4938-bb63-bd761d991906
📒 Files selected for processing (14)
docs/plans/AI-BIM-governance-saas-roadmap-2026-05.mdopenspec/changes/archive/2026-06-04-agent-ship-cycle-automation/proposal.mdopenspec/changes/archive/2026-06-04-agent-ship-cycle-automation/specs/agent-operability-governance/spec.mdopenspec/changes/archive/2026-06-04-agent-ship-cycle-automation/tasks.mdopenspec/changes/archive/2026-06-04-edge-console-p2-p4-buildout/proposal.mdopenspec/changes/archive/2026-06-04-edge-console-p2-p4-buildout/specs/edge-console-operator-frontend/spec.mdopenspec/changes/archive/2026-06-04-edge-console-p2-p4-buildout/tasks.mdopenspec/changes/archive/2026-06-04-unified-governance-console/design.mdopenspec/changes/archive/2026-06-04-unified-governance-console/proposal.mdopenspec/changes/archive/2026-06-04-unified-governance-console/specs/unified-governance-console/spec.mdopenspec/changes/archive/2026-06-04-unified-governance-console/tasks.mdopenspec/specs/agent-operability-governance/spec.mdopenspec/specs/edge-console-operator-frontend/spec.mdopenspec/specs/unified-governance-console/spec.md
| > **撰寫技能組合**：`openspec-explore` → `planner` → `incremental-implementation` → `spec-driven-development` | ||
| > **回覆語言**：繁體中文 | ||
| > | ||
| > **2026-06-04 更新（批次歸檔 #178/#179/#180 archive 對齊）**：本批三個 change 已合併進 `origin/main`（PR #178 `agent-ship-cycle-automation` / #179 `edge-console-p2-p4-buildout` / #180 `unified-governance-console`），於本輪一次 `npx openspec archive` 歸檔（archive folder `openspec/changes/archive/2026-06-04-*/`）。Capability 影響：① `agent-ship-cycle-automation`（ship-cycle 自動化）— `agent-operability-governance` +1 requirement（agent 對每個完成 work item 走 buffered ship-cycle 自動化）；② `edge-console-p2-p4-buildout`（P2-P4 前端補齊）— `edge-console-operator-frontend` +5 requirements（P2 OverviewPage 三 Panel + SemanticViewerPage + CoordinatorPage/IntakePage/RuntimePage、P3 A4-A10 vision 詳頁 + 右欄 Agent/FlowBar/Tweaks、P4 Review Room v1）；③ `unified-governance-console`（統一治理控制台北極星，純規格/文件）— 新建 capability `unified-governance-console` +5 requirements（A1-A10 overlay 疊在 primary viewer / spectator 唯讀 / operator 頁路由分離 / 點 3D ↔ IFC GUID 雙向 + HighlightBridge / MVP 強制 identity profile + 誠實降級 / 前端只經 coordinator + 誠實 502）。`openspec/specs/` **40 → 41**（unified-governance-console 新增）。`npx openspec validate --all --strict` = **41 passed / 0 failed**。**誠實聲明**：archive 僅代表規格已併入現行 `openspec/specs/` + 程式已於各 PR merge 前過 CI；本批未取得新的 runtime / E2E evidence，不把任何 §1.3 閉環或 runtime tier 標為 passed（unified-governance-console 為純規格，無任何實作；edge-console-p2-p4-buildout 為純前端接線，需 host-native runtime + browser E2E 補充；agent-ship-cycle-automation 為 docs/tooling，無 runtime 行為）。本 archive 不升等 Docker GPU launcher、dedicated multi-Kit、OQ1 callback auth 或 OQ5 SSO。 |
Contributor
There was a problem hiding this comment.
Synchronize capability totals across the roadmap after this archive entry.
This line updates openspec/specs/ to 40 → 41, but later sections in the same document still state 39 as the current capability total. Please update the downstream inventory sections (especially §1.2/§1.4 summaries) in the same PR to keep the roadmap internally consistent.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/plans/AI-BIM-governance-saas-roadmap-2026-05.md` at line 11, The roadmap
archive entry increments openspec/specs from 40 to 41 but downstream summaries
still show 39; update the inventory counts in this same document by
synchronizing all references (e.g., the §1.2 and §1.4 summary lines and any
other occurrences) to reflect openspec/specs = 41 and adjust any derived totals
or parentheses so the document is internally consistent with the new archive
entry (search for "openspec/specs/ 39", "39", and the §1.2/§1.4 blocks and
replace with 41 where appropriate).
Owner
Author
|
判斷合併（judgment-merge，依 ship-item.md 判斷層次）：官方 gate 全綠（pr-review-agent + CodeRabbit pass）。3 輪已修全部 substantive findings（Window 措辭 / WebRTC carve-out / hash 路由 / provenance p3·p4 / A1-A10 新編號權威）。剩 1 個 CodeRabbit 🟡 Minor（capability 總數跨文件數字同步）為 cosmetic—— |
monkey1sai
added a commit
that referenced
this pull request
Jun 4, 2026
…perator 頁 + 點3D↔GUID + 誠實降級） (#182) * docs(plan): 統一治理控制台 MVP 垂直切片 bite-sized TDD 實作計畫 writing-plans 方法產出：21 個 bite-sized TDD task（RED→GREEN→commit），涵蓋 - Phase A 純邏輯單元：MappingCache（雙向 ifc_guid↔usd_prim_path、拒 fake、誠實 coverage）、 GovPanelState（spectator 唯讀）、HighlightBridge（client 主動拉 highlightPrimsRequest，未對映誠實回拒）、 govEndpoints（guid_exact + coverage gate 誠實降級） - Phase B overlay/operator UI：GovernanceOverlay（A2/A3/A4/A8 + A5/A6/A9/A10 願景 disabled）、 IntakeSelectPage（選現成模型不手填）、OperatorConsole（三頁獨立殼不含 overlay） - Phase C 漸進式接 viewer（main.tsx 路由 + Window.tsx 最小掛載，逐步可跑） - Phase D E2E 驗收（兩份真 IFC identity 轉檔→primary viewer A2/A3/A4→點 failed 構件 3D 標紅→A8 issue/BCF + 截圖） - Phase E self-review（spec coverage / placeholder scan / type consistency） 零後端改動、只打 coordinator :8004、誠實 provenance、不復活 server-push。純計畫文件，未實作 code。 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * docs(plan): 修正 north-star 引用為 live spec（#181 已歸檔該 change） Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * chore(console-mvp): 建 governance 元件目錄 + 記錄 baseline Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * feat(console-mvp): MappingCache 雙向 ifc_guid↔usd_prim_path（鎖單一 model version） Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * feat(console-mvp): MappingCache 拒 fake mapping + 誠實 coverage%（denominator=source_ifc_entity_count） Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * feat(console-mvp): GovPanelState spectator 唯讀 + 等待 viewer（誠實 disabled） Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * feat(console-mvp): HighlightBridge failed→highlightPrimsRequest（client 主動拉，未對映誠實回拒） Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * feat(console-mvp): MVP guid_exact + coverage gate（誠實降級，引用既有 spec 門檻） Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * feat(console-mvp): GovernanceOverlay A2/A3/A4/A8 骨架 + A5/A6/A9/A10 願景 disabled Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * feat(console-mvp): GovernanceOverlay spectator 唯讀 disabled + 等待 viewer 文案（誠實非隱藏） Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * feat(console-mvp): overlay failed 構件清單→3D 標紅 + 未對映/降級誠實顯 coverage% Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * feat(console-mvp): IntakeSelectPage A1 進件選現成模型（不手填路徑，只打 :8004） Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * feat(console-mvp): OperatorConsole 三頁獨立殼（coordinator/intake/runtime，不含治理 overlay） Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * fix(console-mvp): highlightBridge.test.ts 型別修正（HighlightResult union narrowing + summary 型別） Phase A 的 A4 測試檔有 4 個 tsc 型別錯誤（source_ifc_entity_count excess prop + res.reason 未對 discriminated union narrowing）。npm run build=vite build 不做型別檢查故漏掉；改用 toEqual({ok:false,reason}) 斷言（更強、免 narrowing）+ summary intersection 型別。 npx tsc --noEmit 全專案 0 error，vitest 85 passed 不變。 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * feat(console-mvp): main.tsx 路由分流掛 OperatorConsole（保留既有 viewer <App/>） Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * feat(console-mvp): Window.tsx 疊 GovernanceOverlay（spectator 唯讀，保留既有 viewer 子樹） Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * feat(console-mvp): Window 餵 MappingCache（鎖 model version）+ 點 3D 反查 ifc_guid Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * test(console-mvp): Phase A–C 全套件回歸通過（build + test + struct-log） Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * fix(console-mvp): 接線 overlay 清除標示鈕 + spectator 防禦縱深 + 刪 dead HighlightBridge.clear() 對抗驗證（5-lens）唯一反覆點名的非阻斷 finding：onClearHighlight 傳入 GovernanceOverlay 卻從未被呼叫（dead wiring），且 HighlightBridge.clear() 無任何 caller。 - GovernanceOverlay：失敗構件 Panel 加「清除 3D 標示」鈕（disabled when !canOperate）→ onClearHighlight 上線。 - handleHighlight 加 !canOperate 早退（防禦縱深，對齊 spec「spectator SHALL NOT 觸發」；按鈕已 disabled，這是第二道）。 - 移除無 caller 的 HighlightBridge.clear()（YAGNI）。 tsc --noEmit 0 error，vitest 91 passed（含新增 clear 鈕斷言）。 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * docs(openspec): 新增 unified-console-mvp 實作 change（北極星 spec-only change 預期的實作交付） pr-review-agent gate 要求 code 變更須對應 active OpenSpec change id（branch=codex/openspec/unified-console-mvp 卻無 openspec/changes/unified-console-mvp/）。archived 2026-06-04-unified-governance-console 為純規格 change， 明文「後續實作 change 依本 capability 為北極星」；本 change 即該預期的實作交付。 - proposal/tasks：MVP 垂直切片 client-only 實作（A/B/C phase + 驗證 + 對抗 + E2E）。 - spec delta：ADD 一項 frontend-operable 交付驗收 requirement（對齊 AGENTS.md §0.1，不改既有 5 行為要求）。 npx openspec validate unified-console-mvp --strict → valid；--all --strict → 42 passed/0 failed。 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * fix(console-mvp): 修正 CodeRabbit PR #182 複審 findings（F1–F9） - F1 govEndpoints：coverage gate 修正降級閾值——locked 1.0 才 pass， fallback（degraded）只在 ratio<0.9 觸發；0.9≤r<1.0 為 warnOnly 不降級。 補 0.95 warn band 邊界測試（fake/null 仍保守降級）。 - F2 routing：pathname 限根層 /console（^/console(/|$)），/foo/console 不再誤判； 保留 hash 分支。補巢狀路徑測試。 - F3 GovernanceOverlay：導入 rowKey=rule_code::ifc_guid 穩定 key，避免相同 ifc_guid 不同 rule_code 之 React key 與 lastResult 碰撞；補多筆同 guid 去碰撞測試。 - F4 IntakeSelectPage：radio 補 aria-label（選取 ${ifc_ready_job_id}）可及性名稱。 - F5 Window.tsx render：overlay coverage 一律走 evaluateCoverageGate， null mapping → degraded:true（與 gate null 語意一致，誠實顯「coverage 未知」）。 gitnexus_impact(render, upstream)=LOW（0 callers / 0 processes）。 - F6 穩定選取子：GovernanceOverlay/IntakeSelectPage/OperatorConsole 補 data-testid （gov-*/intake-*/op-*）；Btn 新增選用 data-testid 轉發（對既有呼叫者零行為變更）。 - F7 overlay.css：font-family Consolas 去引號（stylelint font-family-name-quotes）。 - F8 OperatorConsole：readPage 改 named export + 補純函式單元測試 （空/intake/runtime/unknown）；hashchange/nav 互動由 browser E2E 覆蓋（不引入 @testing-library）。 - F9 計畫文件：將「北極星 source of truth」改為 supporting references（權威為 live spec + code contracts，對齊 documentation-source-of-truth policy）；table cell 內 inline code 的 | 跳脫（MD056）。 驗證：npx tsc --noEmit=0 errors；npm run verify 通過（build + 102 tests + struct-log 10）。 note-only #6：intake 非同步流程沿用 renderToString smoke，full async 由 E2E + data-testid 覆蓋，不加 @testing-library。 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * feat(coordinator): 新增 POST /api/governance/rule-runs/for-session/:sessionId（以 session_id 解析 server-side IFC 路徑後透傳 A3 rule-run） 瀏覽器 review viewer 只持有 session_id，不知 server-side IFC path。新增的 coordinator-only 端點從自己的 SessionStore + ExternalIfcReadyStore 解析出 host-side IFC 路徑（job.host_local_path，fallback job.local_path）與 model_version_id，再 reuse 既有 forward helper + GOVERNANCE_API_BASE 透傳給 governance-service POST /api/rule-runs，回 { rule_run_id, status }。 解析鏈：session_id → SessionStore.get → ReviewSession.model_version_id； externalIfcReadyStore.list().filter(job.review_session_id === sessionId) （由 conversion-ready auto-session 的 recordReviewSession 寫入反向參照）→ job.host_local_path（markDownloaded 於 /api/external/ifc-ready 同步下載完成時 寫入 storage/ifc-cache/<jobId>/source.ifc 的 host 視角絕對路徑）。 邊界與誠實：coordinator 只解析 + 透傳，不跑 rule-run、不是新資料權威； 可選 override body { ids_path?, rule_set? } 一併透傳，ifc_source_path / model_version_id 不可被瀏覽器覆寫；不注入 element_mapping_path（coordinator 不持有 host-side mapping 檔，mapping 為 streaming artifact URL）。 400 不合法 session id；404 session/IFC 路徑無法解析；502 governance 不可達 （reuse forward 既有 502 path）；絕不偽造 path 或成功。 - governanceProxy.ts：registerGovernanceProxy 接受 deps（resolver + isSafeSessionId）；GOVERNANCE_API_BASE 改為 per-request 讀取以利測試覆寫。 - app.ts：注入只讀 SessionStore + ExternalIfcReadyStore 的 resolver。 - docs/contracts/governance-rule-run-proxy.md：新契約文件（含解析鏈與回應表）。 - tests：resolve+forward / override 透傳 / 404x2 / 400 / 502 共 6 例。 npm run verify GREEN：build 無 TS error；22 test files / 279 tests passed。 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * feat(console): 統一治理控制台 overlay 9 項 live wiring（A3→failed→3D→A8 閉環） 把 web-viewer-sample 的治理 overlay 從靜態骨架接成真正可從前端操作： - W1 A3：governanceClient.createRuleRunForSession；overlay 新增 gov-run-rulecheck， Window._runGovernanceRuleCheck 起 rule-run→輪詢 60×1s→succeeded 取 failed 結果 映成 FailedElement 餵 govFailedElements；誠實表態 running/error/succeeded。 - W2 標示誠實：成功只顯示「已送出 3D 標示請求（待 Kit 確認）」；Window 用獨立 _pendingGovHighlights 追蹤 requestId，highlightPrimsResult 回來後依 selected/missing 寫 govHighlightConfirm 覆寫文案（不破壞既有 mapping-verify pending 路徑）。 - W3 A8：overlay 加 gov-a8-issue（須 rule-run succeeded）+ gov-a8-bcf 下載連結； Window._createGovIssues 打 issuesFromRuleRun；BCF 走 bcfExportUrl(model_version_id)， 無 model version 時誠實提示不捏造 URL。 - W4 點 3D→GUID：抽 _reverseLookupGuid，_onSelectUSDPrims 與 live stageSelectionChanged 共用（DRY），反查 ifc_guid 寫 govSelectedGuid + 記事件。 - W5 coverage 來源校正：改讀 streamConfig.quality_metrics_summary.coverage_ratio（原樣， viewer 不自算）；移除 MappingCache.coverageRatio()/summaryMappedCount/sourceEntityCount （真實 summary 無分母，wrong-sourced），保留 isFake + 雙向 index + belongsTo。 - W6 進件前進：IntakeSelectPage 加 intake-open，依 job.viewer_url 開啟既有 viewer， 缺 viewer_url 則 disabled + 誠實說明（不假導航）。 - W7 overlay token：把 edge-console.css .ec-root 的 --ec-* 移植到 .gov-overlay， 讓掛在 .ec-root 之外的巢狀 .ec-panel/.ec-btn 正確上色。 - W8 短 hash 路由：isOperatorConsolePath 支援 #coordinator/#intake/#runtime，但僅在 query 無 session= 時生效（viewer ?session= 進件優先）；main.tsx 傳入 location.search。 - W9 cache 重建：_loadElementMapping 改以 model version + mapping_url 雙鍵判定重建 （_mappingCacheUrl），避免同版本換 artifact 時讀到舊對映。 測試：GovernanceOverlay 9→17、routing 3→6、IntakeSelectPage 3→4、mappingCache 調整為 6 （移除 coverage-ratio 測試）。tsc --noEmit 0 errors；npm run verify（build+111 tests+struct-log）green。 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * docs(openspec): unified-console-mvp 誠實反映 coordinator 端點 + live 接線（非 client-only） 完整 live 接線需 1 個最小 coordinator session-scoped rule-run 端點（governance-service rule-run 需 server IFC 路徑、瀏覽器不持有）。更新 proposal/spec delta：從「client-only 零後端」誠實改為 「client 元件 + 1 個 coordinator resolve+forward 端點，前端只經 :8004、不改 data shape」。 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * fix(console): round-3 reviewer 修復 R1–R8（治理 overlay 強健性／安全／誠實） 統一治理控制台 MVP overlay live-wiring 的第三輪 CodeRabbit + Codex review 修復，frontend-only： - R1 Window._runGovernanceRuleCheck：running 中重入直接 return（不重疊輪詢）；開新 run 前清空殘留 state（govFailedElements/govHighlightConfirm/govIssueCreate/govRuleRunId）與 _pendingGovHighlights。 - R2 Window._createGovIssues：creating 中重入直接 return（防連點重複開 issue）。 - R3（安全）IntakeSelectPage：viewer_url 導航前過 isSafeViewerUrl（僅 http(s) 絕對 URL 或同源相對 路徑），拒 javascript:/data:/open-redirect；canOpen 以此 gate，不安全顯示誠實警示「viewer_url 非 安全 http(s)/同源路徑，拒絕導航」。isSafeViewerUrl 匯出為純函式。 - R4 governanceClient.createRuleRunForSession：sessionId 以 encodeURIComponent 包覆。 - R5 GovernanceOverlay：gov-run-rulecheck 於 ruleCheck.status==="running" 時 disabled（配對 R1）， 標籤維持「檢核中…」。 - R6（誠實）Window highlightPrimsResult gov-confirm：confirmed 另要求 fallbackPaths.length===0 （Kit 用 fallback 不算真確認，鏡像 mapping-verify predicate）。 - R7 sub-100% coverage warnOnly 透傳 overlay：coverage ∈ [0.9,1.0) 顯示 gov-coverage-warn 「coverage <100%（未達 MVP 鎖定 1.0；measure-first 警示，非 fallback 降級）」；不改 evaluateCoverageGate 邏輯。 - R8 MappingCache.guidForPrimPathOrAncestor + Window._reverseLookupGuid：child mesh prim 往父層 解析到 mapped ancestor 的 guid；guidForPrimPath 維持 exact。 測試：+7（R3 驗證器/不安全 URL 拒導航 mount、R5 running-disabled、R7 warn×3、R8 ancestor）。 驗證：npx tsc --noEmit=0；npm run verify 綠（build + 118 tests + struct-log 10/10）。 R9 確認：mappingCache 已不讀 element_mapping summary 算 coverage（W5）；routing isOperatorConsolePath 已支援 #coordinator/#intake/#runtime（W8，session= 時讓位）—— 皆已解決，無需改動。 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * fix(console): round-4 reviewer 修復 T1–T6（治理 overlay 誠實性／lifecycle gating／自動載入 mapping） 修復 Codex round-4 P2 findings（統一治理控制台 MVP，frontend-only）： - T1 清除 3D 標示重設狀態：Window.onClearHighlight 一併清 govHighlightConfirm 與 _pendingGovHighlights；overlay 加 handleClearHighlight 重設本地 lastResult， 避免殘留「已送出／已在 3D 標示」誤導（按鈕 testid gov-clear 不變）。 - T2 顯示反查到的 ifc_guid：Window 透傳 selectedGuid={govSelectedGuid ?? null}， overlay 新增 selectedGuid prop，非 null 時誠實顯示「點選 3D 構件 → ifc_guid=…」 （testid gov-selected-guid；無對映時 Window 設 null 不顯示假 guid）。 - T3 一般檢視自動載入 element_mapping：_completeStageLoad 尾端呼叫新增的 _maybeAutoLoadMapping()，僅在有 mapping_url 且該 url 未載入（_mappingCacheUrl）時 reuse _loadElementMapping()，補齊非 debug 場景 _mappingCache 恆 null → overlay 永遠 unmapped 的真實功能缺口。無 mapping_url 時誠實不做事；不動既有 stage-load 流程與 debug onLoadMapping 路徑。 - T4 失敗構件 >50 誠實標註：保留 50 列上限，>50 時加 gov-failed-truncated 標註 「顯示前 50 筆／共 N 筆失敗構件（其餘未列出）」，不靜默截斷。 - T5 BCF 範圍誠實：gov-a8-bcf 旁加 gov-a8-bcf-scope 說明 BCF 匯出為本 model version 所有正式 issue（非僅本次 rule-run）；端點無 run filter，不捏造。 - T6 非 active lifecycle 停用治理動作：govPanelState/windowOverlayGlue 接受 lifecycleActive，新增 disabledReason "session_not_active" + 文案；Window 由 reviewLifecycleStatus 計算 lifecycleActive（僅 active/created 視為 active， queued/blocked/failed/closing/closed/dropped 唯讀）。 測試：govPanelState +5、windowOverlayGlue +3、GovernanceOverlay +7（含 T1 jsdom 互動測試）。npx tsc --noEmit=0；npm run verify 綠（14 files / 133 tests + struct-log 10）。 gitnexus_impact：_completeStageLoad upstream=HIGH（中央 stage-ready 匯流點，4 processes）， 但本次為純附加 fire-and-forget 呼叫，不改既有控制流；_loadElementMapping=LOW。 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * fix(unified-console): round-5 reviewer P2 修正（F1–F4，前端） F1 治理標示確認改以 rowKey（rule_code::ifc_guid）索引：同一 ifc_guid 多筆 不同 rule_code 的失敗列不再共用 / 互相覆蓋確認狀態。 - Window.tsx：_pendingGovHighlights 一併記 rowKey；highlightPrimsResult gov 分支以 govPending.rowKey 寫 govHighlightConfirm。 - GovernanceOverlay.tsx：highlightConfirm 改讀 rowKey(f)（與 lastResult 一致）。 F2 A8 開 issue 鈕在 issueCreate.status==="created"（與 "creating"）時 disabled， 避免連點重複開 issue 集；succeeded 後仍顯示「已從 rule-run 開 N 筆 issue」。 F3 stageSelectionChanged 取消選取（prims 為空）時一併清 govSelectedGuid=null， 避免 overlay gov-selected-guid 行殘留舊 guid。 F4 highlightBridge.ts 新增純函式 normalizeSeverity（大小寫不敏感）： critical/high/error→error、medium/warning→warning、其餘原樣透傳； highlightFailed 以其結果呼叫 severityToColor（不改 severityToColor 本身）。 驗證：npx tsc --noEmit = 0；npm run verify 綠（vitest 141 passed / 14 files + struct-log 10 PASS）。新增 GovernanceOverlay 3 測（F1×2、F2×1）、 highlightBridge 4 測（F4 high→紅 + normalizeSeverity×3）；調整 1 既有 W2 測 （highlightConfirm key 改 rowKey）。 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * fix(console): round-6 修復 CodeRabbit 2 Major（open-redirect 收斂 + 未載入 mapping 視為 degraded） - isSafeViewerUrl 從「只查 protocol」收緊為「同源或 coordinator origin」，擋掉導向任意 https origin 的 open-redirect / phishing（viewer_url 雖由 coordinator 提供仍防禦縱深）；openViewer 改導向正規化 URL。 - Window coverage gate：_mappingCache 為 null（未載入/未知）時 isFake 視為 true → degraded， 不在 client 無法標示時仍顯示有把握的 coverage%（誠實保守）。 - 更新 isSafeViewerUrl 測試：跨來源 https 改判 false（open-redirect 拒）。 tsc 0 / verify 綠。 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Co-authored-by: monkey1sai <xshiujj@gmail.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
摘要
純 OpenSpec archive + roadmap sync，無 production code 變更。
歸檔 3 個 change（
npx openspec archive <id> -y）：agent-ship-cycle-automation（PR feat(agents): per-item ship-cycle 自動化 workflow（buffered auto-merge gate） #178，ship-cycle 自動化）→archive/2026-06-04-agent-ship-cycle-automation/edge-console-p2-p4-buildout（PR feat(console): Edge Console P2–P4 前端建置（真實後端頁 + A4–A10 vision + Review Room v1） #179，P2-P4 前端補齊）→archive/2026-06-04-edge-console-p2-p4-buildout/unified-governance-console（PR docs(openspec): 統一治理控制台北極星設計 + OpenSpec change（純規格） #180，統一治理控制台北極星，純規格）→archive/2026-06-04-unified-governance-console/Capability 影響：
agent-operability-governance+1 requirement（buffered ship-cycle 自動化）edge-console-operator-frontend+5 requirements（P2/P3/P4 誠實前端）unified-governance-console新建（40 → 41 specs）+5 requirements（北極星：overlay / operator 路由 / 雙向 3D ↔ IFC / MVP identity profile / 誠實 502）Purpose 補寫：
unified-governance-console/spec.md（原 archive TBD → 真實繁中 Purpose）EOF 修正：3 個 spec.md 尾部空行（
perlstrip）roadmap sync：
docs/plans/AI-BIM-governance-saas-roadmap-2026-05.mdupdate-log 加2026-06-04條目驗證
誠實聲明
openspec/specs/+ 程式於各 PR merge 前已過 CIunified-governance-console為純規格，無任何 production 實作不適用
Frontend / Deploy / Runtime 驗證表不適用（無 code 變更，純 OpenSpec archive + roadmap doc）。
🤖 Generated with Claude Code
Summary by CodeRabbit