docs: 收斂 docs/plans 開發方向 + 移除退役 graphify corpus/wiki - #203
Conversation
以兩份 prototype（ai-bim-governance-prototype.html 前端主頁 + ai-bim-geo-viewer-prototype.html 3D viewer）為開發方向，清理 worker-only runtime 之前的退役 plan 雜訊。 移除 8 份（2026-05 退役架構或已被 v2/v3 取代）：BIM_REVIEW_MVP_COMPLETION_PLAN_v0_2 與 review-mvp-v0-2-baseline（純轉址）、v0_3_DEMO_UI、BIM_REVIEW_COORDINATOR_WEB_VIEWER_EXECUTION_PLAN、IFC_TO_USDC_CONVERSION_API_IMPLEMENTATION_PLAN、phase-b-external-platform-webhook-intake-DRAFT（已升格 OpenSpec 並 archived）、AI-BIM-governance-next-burn-down-2026-05-19、fast-mvp-edge-bim-server-console-design。 納入版控（先前未追蹤）：ai-bim-geo-viewer-prototype.html（3D viewer 主檔）、ai-bim-governance-開發軌跡與執行計畫.md（v3 執行計畫）、docs-plans-README.md（導讀索引）。 保留 BIM_REVIEW_DEMO_UI_GUIDELINES.md（仍被 bim-review-coordinator/bim-streaming-server/web-viewer-sample 的 README 與程式碼、PROJECT_DEVELOPMENT_WORKFLOW.md live 引用）。graphify-corpus 與 docs/wiki/graphify 為自成一體的歷史分析快照，刪除 docs/plans 不致其產生 broken link，故本次不動。 Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
📝 WalkthroughWalkthroughThis PR reorganizes the planning documentation layer for the AI-BIM governance project by removing eight legacy execution/design plan files, consolidating the roadmap into a comprehensive v3 governance document with specifications for ten feature workstreams (A1–A10) and execution milestones, adding a planning folder README guide, and introducing an interactive HTML prototype for BIM/IFC-to-USD semantic verification visualization. ChangesPlanning Documentation Framework & Comprehensive Governance Roadmap
Interactive BIM Geometric Viewer Prototype
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 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 docstrings
🧪 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 |
There was a problem hiding this comment.
Pull request overview
This PR cleans up docs/plans/ to retain only current authoritative files, removing 8 retired plan documents from the pre-worker-only runtime era and adding 3 previously untracked files to version control, along with a README index.
Changes:
- Removes 8 obsolete planning documents (v0.2/v0.3 MVP plans, old conversion/coordinator execution plans, retired Phase B draft, burn-down, and console design docs) that reference deprecated architectures (
_worker,_bim-control,_s3_storage, ports 8002/8003). - Adds 3 new files:
ai-bim-geo-viewer-prototype.html(3D viewer prototype),ai-bim-governance-開發軌跡與執行計畫.md(v3 development trajectory + engineering specs + execution plan), anddocs-plans-README.md(directory index/guide for Claude Code). - Final
docs/plans/contains 6 files: 5 authoritative direction documents + the retainedBIM_REVIEW_DEMO_UI_GUIDELINES.md(still live-referenced by multiple sub-repos).
Reviewed changes
Copilot reviewed 11 out of 11 changed files in this pull request and generated 1 comment.
Show a summary per file
| File | Description |
|---|---|
docs/plans/BIM_REVIEW_MVP_COMPLETION_PLAN_v0_2.md |
Removed: 3-line redirect stub to v0.3 |
docs/plans/review-mvp-v0-2-baseline.md |
Removed: historical baseline + redirect to v0.3 |
docs/plans/BIM_REVIEW_COORDINATOR_WEB_VIEWER_EXECUTION_PLAN.md |
Removed: 2,218-line pre-worker-only runtime execution plan |
docs/plans/IFC_TO_USDC_CONVERSION_API_IMPLEMENTATION_PLAN.md |
Removed: 1,293-line pre-worker-only conversion API plan |
docs/plans/phase-b-external-platform-webhook-intake-DRAFT-2026-05.md |
Removed: Phase B draft, already upgraded to OpenSpec change and archived (PR #64) |
docs/plans/AI-BIM-governance-next-burn-down-2026-05-19.md |
Removed: burn-down doc self-described as superseded by design specs + prototype |
docs/plans/fast-mvp-edge-bim-server-console-design-2026-05-25.md |
Removed: consolidated into OpenSpec changes; referenced TEMP source no longer exists |
docs/plans/docs-plans-README.md |
Added: directory index with file roles, implementation rules, and acceptance criteria |
docs/plans/ai-bim-governance-開發軌跡與執行計畫.md |
Added: v3 development trajectory, A1–A10 engineering specs, M0–M8 execution plan |
docs/plans/ai-bim-geo-viewer-prototype.html |
Added: single-file 3D viewer prototype simulating post-M4 semantic verification |
Comments suppressed due to low confidence (1)
docs/plans/phase-b-external-platform-webhook-intake-DRAFT-2026-05.md:1
- The PR description claims "全 repo grep 確認：被移除的 8 份未被任何「活檔案」以 markdown 連結引用". However,
docs/agents/repo-boundary-detail.mdreferences this deleted file on lines 98 and 103 (e.g.草稿見 docs/plans/phase-b-external-platform-webhook-intake-DRAFT-2026-05.mdand完整方案見 docs/plans/phase-b-external-platform-webhook-intake-DRAFT-2026-05.md). These are live references from an active governance document, and deleting this file without updatingrepo-boundary-detail.mdwill leave broken links.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
![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: b33d610b59
ℹ️ 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".
| @@ -1,358 +0,0 @@ | |||
| # Phase B 規劃草稿 v2：客戶落地端 coordinator IFC-ready intake + 雲端 callback + mock 刪除 | |||
There was a problem hiding this comment.
This deleted plan is still referenced by the active boundary guide at docs/agents/repo-boundary-detail.md:98 and :103, including the sentence that the complete Plan B方案 is here. After this removal, agents following the root AGENTS lazy-load instructions for repo-boundary decisions hit a broken source for the control-plane/data-plane split; either keep an archival copy or repoint those live references to the OpenSpec archive/successor.
Useful? React with 👍 / 👎.
| ``` | ||
| ## 需求事實來源 | ||
| A1–A10 功能需求、UI 驗收語意與實作順序，一律以 docs/plans/ 為準： | ||
| 先讀 docs/plans/README.md，再讀 ai-bim-governance-開發軌跡與執行計畫.md（順序） |
There was a problem hiding this comment.
The suggested CLAUDE.md snippet tells agents to read docs/plans/README.md, but this commit adds the guide as docs/plans/docs-plans-README.md and there is no README.md in docs/plans. If this block is copied as intended, the first mandatory source-of-truth path is broken, so future sessions will miss the guide unless the filename or instruction is corrected.
Useful? React with 👍 / 👎.
| |---|---|---| | ||
| | coordinator | :8004 | 控制塔：session/instance 排程、EdgeConsole `/ui` 殼層 | | ||
| | governance-service | :49102 | A1 規則引擎、Issue/BCF、報表（CPU 即可） | | ||
| | conversion worker | (隨 coordinator 管理) | IFC→USD 轉檔（CPU 吃重） | |
There was a problem hiding this comment.
This new authoritative implementation plan assigns IFC→USD conversion to a coordinator-managed worker, but the active contracts define bim-streaming-server as the conversion authority (docs/contracts/bim-review-platform-boundary.md says the streaming process owns conversion authority, and docs/contracts/local-dev-runbook.md has the coordinator call that authority internally). Following this row for M2 would put the conversion queue/API in the wrong service and diverge from the current smoke tests and boundary contract, so the plan should name bim-streaming-server/:49101 as the owner instead of a coordinator worker.
Useful? React with 👍 / 👎.
| | MinIO | 內網 | 物件儲存（模型、轉檔產物、BCF 包） | | ||
| | Postgres | 內網 | 治理帳本（規則結果、Issue、稽核軌跡） | | ||
|
|
||
| **通用約定**：REST 走 `/api/v1/...`；所有會「改東西」的 API 要帶操作者身分（稽核）；每個功能的可信度標記（已實作/實測/示範/待建）由後端設定檔 `provenance.json` 驅動，前端不寫死。 |
There was a problem hiding this comment.
This plan makes /api/v1/... the general REST convention, but the current governance contract and client deliberately route browser traffic through coordinator :8004 at /api/governance/*, which proxies to governance-service's internal /api/* endpoints; the browser must not call :49102 or a new direct prefix. If agents implement A1 from this authoritative plan, they will create/use endpoints such as /api/v1/checks instead of the existing /api/governance/rule-runs proxy path, bypassing the boundary documented in docs/contracts/governance-rule-run-proxy.md and web-viewer-sample/src/console/governanceClient.ts.
Useful? React with 👍 / 👎.
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🧹 Nitpick comments (5)
docs/plans/docs-plans-README.md (2)
32-37: ⚡ Quick winAdd language specifier to fenced code block.
The code block should specify a language identifier for proper syntax highlighting and markdown compliance.
📝 Suggested fix
-``` +```markdown ## 需求事實來源 A1–A10 功能需求、UI 驗收語意與實作順序，一律以 docs/plans/ 為準： 先讀 docs/plans/README.md，再讀 ai-bim-governance-開發軌跡與執行計畫.md（順序） 與 ai-bim-governance-設計規格.md（介面）。兩份 .html 是行為示意，不是程式碼範本。</details> <details> <summary>🤖 Prompt for AI Agents</summary>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/docs-plans-README.mdaround lines 32 - 37, The fenced code block
in docs/plans/README.md is missing a language specifier; update the opening
fence fromto include a language (e.g.,markdown) so the block is
Markdown-compliant and enables proper syntax highlighting for the content shown
in the README.</details> <!-- cr-comment:v1:415b88ef3150ca029b02f1d2 --> --- `1-5`: _⚡ Quick win_ **Clarify documentation nature and source-of-truth hierarchy.** This README establishes the docs/plans/ folder positioning but should explicitly: 1. Mark the documentation nature (e.g., "規格設計與需求文件 / Spec Design & Requirements") 2. Acknowledge the source-of-truth hierarchy: when implementation diverges from these requirements, the actual source code is authoritative for current behavior (per coding guidelines: "source code > contracts > AGENTS boundaries > wiki") This clarification helps prevent confusion when implementation and documentation drift. <details> <summary>📋 Suggested addition after line 1</summary> ```diff # docs/plans/ — 給 Claude Code 的導讀（必讀） + +> **文件性質**：規格設計與執行計畫（Spec Design & Execution Plan） +> **真相順序**：實際程式碼 > 契約文件 > 本資料夾規格 > wiki（當實作與規格分歧時，以程式碼為準） ``` </details> As per coding guidelines: "Align with source of truth order: source code > contracts > AGENTS boundaries > wiki. DO NOT treat docs/ files as authority for product/API behavior; when wiki and implementation conflict, implementation is authoritative." <details> <summary>🤖 Prompt for AI Agents</summary> ``` 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/docs-plans-README.md` around lines 1 - 5, Update the docs/plans/ README to explicitly mark the folder as "規格設計與需求文件 / Spec Design & Requirements" and add a short paragraph stating the source-of-truth hierarchy (source code > contracts > AGENTS boundaries > wiki) and that implementation (source code) is authoritative if it diverges from these docs; place this clarifying sentence near the top under the existing intro header in docs/plans/ — reference the README header and the first paragraph so the new lines follow the current opening text. ``` </details> <!-- cr-comment:v1:3904c76e3b8a9bf8cc5c0c5f --> _Source: Coding guidelines_ </blockquote></details> <details> <summary>docs/plans/ai-bim-governance-開發軌跡與執行計畫.md (3)</summary><blockquote> `384-390`: _⚡ Quick win_ **Add language specifier to milestone diagram code block.** The ASCII art diagram should have a language identifier for proper rendering. <details> <summary>📝 Suggested fix</summary> ```diff -``` +```text M0 地基盤點 ──→ M1 A1 核心閉環（P0，最快見效）──→ M5 版本與疊合(A2/A3) │ ↑ └──→ M2 轉檔管線 ──→ M3 Runtime 串流 ──→ M4 3D 連動 ─┘ ``` </details> <details> <summary>🤖 Prompt for AI Agents</summary>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-開發軌跡與執行計畫.mdaround lines 384 - 390, Add a
language specifier to the ASCII-art milestone diagram code block so it renders
correctly; locate the triple-backtick fenced block containing the milestone
diagram (e.g., the lines with M0, M1, … M8) and change the opening fence from
totext (or another appropriate language like ```ansi) so the diagram is
explicitly marked as plain text.</details> <!-- cr-comment:v1:d49e190bfcc4d0ae222d9741 --> --- `75-86`: _⚡ Quick win_ **Add language specifier to MinIO structure code block.** The file tree structure should have a language identifier for proper rendering. <details> <summary>📝 Suggested fix</summary> ```diff -``` +```text bim-control/ └── {projectId} 270 / 899 / 988 └── {modelId UUID} 例 123a909a-0f28-…（邏輯上＝OpenBIM 類別） ``` </details> <details> <summary>🤖 Prompt for AI Agents</summary>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-開發軌跡與執行計畫.mdaround lines 75 - 86, The code
block showing the MinIO file-tree (starting with "bim-control/" and listing
"{projectId}", "{modelId UUID}", model.ifc, model.rvt, elements.json,
geometries.json, geometries_chunks, spatial_tree.json, model.usdc) lacks a
language specifier; update the fenced code block delimiter fromtotext
(or another appropriate language like ```bash) so the tree renders properly,
preserving the exact block content and spacing.</details> <!-- cr-comment:v1:ed250374cfbbc5b2b7869cdb --> --- `1-7`: _⚡ Quick win_ **Add explicit documentation nature classification.** While line 3 states "readonly 模式", the document should explicitly mark its nature per coding guidelines. This helps establish its position in the documentation hierarchy. <details> <summary>📋 Suggested addition</summary> ```diff # AI-BIM-Governance — 開發軌跡 · A1–A10 工程規格 · 執行計畫 -> 版本：v3 · 2026-06-10 · 本文件以 **readonly 模式**產出（兩份上傳檔完全未修改） +> **文件性質**：規格設計 / 執行計畫（Spec Design / Execution Plan） +> 版本：v3 · 2026-06-10 · 本文件以 **readonly 模式**產出（兩份上傳檔完全未修改） +> **真相順序**：當實作與本規格分歧時，實際程式碼為準（本文為規劃基準，非實作文檔） > 配套檔案：`ai-bim-governance-prototype.html`（v2 原型）、`ai-bim-governance-設計規格.md`（v2 規格） ``` </details> As per coding guidelines: "Mark documentation nature: agent boundary / contract / wiki / runbook / spec design / working note" and "when wiki and implementation conflict, implementation is authoritative." <details> <summary>🤖 Prompt for AI Agents</summary> ``` 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-開發軌跡與執行計畫.md` around lines 1 - 7, Add an explicit documentation-nature tag at the top of the file (near the header "# AI-BIM-Governance — 開發軌跡 · A1–A10 工程規格 · 執行計畫") to complement the existing "readonly 模式" note; insert a short, single-line classification such as "Documentation nature: [agent boundary | contract | wiki | runbook | spec design | working note]" (choose the appropriate category, e.g., "wiki" or "spec design") and ensure it follows the coding guideline phrasing so consumers can unambiguously determine hierarchy and precedence relative to implementation. ``` </details> <!-- cr-comment:v1:bb65d516c1eaf8e5ea9c16fd --> _Source: Coding guidelines_ </blockquote></details> </blockquote></details> <details> <summary>🤖 Prompt for all review comments with AI agents</summary>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-geo-viewer-prototype.html:
- Around line 292-293: The current sanitizeGuid -> usdPath pipeline replaces
non-alphanumerics (e.g., "$") with "_" causing collisions; change sanitizeGuid
to produce a collision-free token by encoding non-alphanumeric characters (e.g.,
percent-encoding or base64-url of the original GUID) or by appending a short
deterministic hash of the original GUID to the sanitized string so mapping is
one-to-one; update usdPath to use the new sanitizeGuid output; and update
checkSemantic to validate uniqueness of the resulting usdPath (not just source
GUID) to catch any remaining collisions. Ensure the chosen encoding is
filesystem/URL-safe for USD paths and deterministic so same GUID always maps to
same usdPath.- Around line 239-245: The tab and filter controls are implemented as
non-semantic clickableelements (e.g., elements with class "tab", "tab on"
and data-t="map"/"issue") which are not keyboard-accessible; change these to
semantic interactive elements (preferably or elements with
role="tab"/role="button"), add tabindex="0" where necessary, and implement key
event handlers to trigger the same handlers on Enter and Space as the click
handlers; also update ARIA state/labels (e.g., aria-selected, aria-controls) for
the tab set and ensure the tree/filter controls have equivalent keyboard support
and focus styles so the same interactions (switching tabs, toggling filters,
selecting items) work via keyboard.
Nitpick comments:
In@docs/plans/ai-bim-governance-開發軌跡與執行計畫.md:
- Around line 384-390: Add a language specifier to the ASCII-art milestone
diagram code block so it renders correctly; locate the triple-backtick fenced
block containing the milestone diagram (e.g., the lines with M0, M1, … M8) and
change the opening fence fromtotext (or another appropriate language
like ```ansi) so the diagram is explicitly marked as plain text.- Around line 75-86: The code block showing the MinIO file-tree (starting with
"bim-control/" and listing "{projectId}", "{modelId UUID}", model.ifc,
model.rvt, elements.json, geometries.json, geometries_chunks, spatial_tree.json,
model.usdc) lacks a language specifier; update the fenced code block delimiter
fromtotext (or another appropriate language like ```bash) so the tree
renders properly, preserving the exact block content and spacing.- Around line 1-7: Add an explicit documentation-nature tag at the top of the
file (near the header "# AI-BIM-Governance — 開發軌跡 · A1–A10 工程規格 · 執行計畫") to
complement the existing "readonly 模式" note; insert a short, single-line
classification such as "Documentation nature: [agent boundary | contract | wiki
| runbook | spec design | working note]" (choose the appropriate category, e.g.,
"wiki" or "spec design") and ensure it follows the coding guideline phrasing so
consumers can unambiguously determine hierarchy and precedence relative to
implementation.In
@docs/plans/docs-plans-README.md:
- Around line 32-37: The fenced code block in docs/plans/README.md is missing a
language specifier; update the opening fence fromto include a language (e.g.,markdown) so the block is Markdown-compliant and enables proper syntax
highlighting for the content shown in the README.- Around line 1-5: Update the docs/plans/ README to explicitly mark the folder
as "規格設計與需求文件 / Spec Design & Requirements" and add a short paragraph stating
the source-of-truth hierarchy (source code > contracts > AGENTS boundaries >
wiki) and that implementation (source code) is authoritative if it diverges from
these docs; place this clarifying sentence near the top under the existing intro
header in docs/plans/ — reference the README header and the first paragraph so
the new lines follow the current opening text.</details> <details> <summary>🪄 Autofix (Beta)</summary> Fix all unresolved CodeRabbit comments on this PR: - [ ] <!-- {"checkboxId": "4b0d0e0a-96d7-4f10-b296-3a18ea78f0b9"} --> Push a commit to this branch (recommended) - [ ] <!-- {"checkboxId": "ff5b1114-7d8c-49e6-8ac1-43f82af23a33"} --> Create a new PR with the fixes </details> --- <details> <summary>ℹ️ Review info</summary> <details> <summary>⚙️ Run configuration</summary> **Configuration used**: defaults **Review profile**: CHILL **Plan**: Pro **Run ID**: `bb2a0c22-ae82-4390-888e-64140c24f45c` </details> <details> <summary>📥 Commits</summary> Reviewing files that changed from the base of the PR and between 01893615ed38bc01a707d755f78f3b254f265124 and b33d610b5955f87bd7f0f650928436f45fbab7d1. </details> <details> <summary>📒 Files selected for processing (11)</summary> * `docs/plans/AI-BIM-governance-next-burn-down-2026-05-19.md` * `docs/plans/BIM_REVIEW_COORDINATOR_WEB_VIEWER_EXECUTION_PLAN.md` * `docs/plans/BIM_REVIEW_MVP_COMPLETION_PLAN_v0_2.md` * `docs/plans/BIM_REVIEW_MVP_COMPLETION_PLAN_v0_3_DEMO_UI.md` * `docs/plans/IFC_TO_USDC_CONVERSION_API_IMPLEMENTATION_PLAN.md` * `docs/plans/ai-bim-geo-viewer-prototype.html` * `docs/plans/ai-bim-governance-開發軌跡與執行計畫.md` * `docs/plans/docs-plans-README.md` * `docs/plans/fast-mvp-edge-bim-server-console-design-2026-05-25.md` * `docs/plans/phase-b-external-platform-webhook-intake-DRAFT-2026-05.md` * `docs/plans/review-mvp-v0-2-baseline.md` </details> <details> <summary>💤 Files with no reviewable changes (8)</summary> * docs/plans/BIM_REVIEW_COORDINATOR_WEB_VIEWER_EXECUTION_PLAN.md * docs/plans/review-mvp-v0-2-baseline.md * docs/plans/fast-mvp-edge-bim-server-console-design-2026-05-25.md * docs/plans/BIM_REVIEW_MVP_COMPLETION_PLAN_v0_2.md * docs/plans/BIM_REVIEW_MVP_COMPLETION_PLAN_v0_3_DEMO_UI.md * docs/plans/AI-BIM-governance-next-burn-down-2026-05-19.md * docs/plans/phase-b-external-platform-webhook-intake-DRAFT-2026-05.md * docs/plans/IFC_TO_USDC_CONVERSION_API_IMPLEMENTATION_PLAN.md </details> </details> <!-- This is an auto-generated comment by CodeRabbit for review status -->
| function sanitizeGuid(g){return g.replace(/[^A-Za-z0-9_]/g,'_')} | ||
| function usdPath(el){return '/World/Elements/'+el.cls+'/G_'+sanitizeGuid(el.guid)} |
There was a problem hiding this comment.
Preserve a one-to-one GUID→USD mapping (current sanitization can collide).
At Line 292-293, $ is normalized to _, so different GUIDs can produce the same usdPath. checkSemantic (Line 353) only checks source GUID uniqueness, so this collision is not detected and can corrupt mapping/picking fidelity claims.
🔧 Proposed fix
-function sanitizeGuid(g){return g.replace(/[^A-Za-z0-9_]/g,'_')}
-function usdPath(el){return '/World/Elements/'+el.cls+'/G_'+sanitizeGuid(el.guid)}
+function encodeGuidForUsd(g){
+ // Keep mapping reversible to avoid GUID collisions in path space.
+ return g.replace(/\$/g,'__DOLLAR__');
+}
+function usdPath(el){return '/World/Elements/'+el.cls+'/G_'+encodeGuidForUsd(el.guid)}
@@
-function checkSemantic(els){const set=new Set();for(const e of els){if(!e.guid||e.guid.length!==22||!e.cls||!e.name)return false;if(set.has(e.guid))return false;set.add(e.guid)}return true}
+function checkSemantic(els){
+ const guidSet=new Set(), pathSet=new Set();
+ for(const e of els){
+ if(!e.guid||e.guid.length!==22||!e.cls||!e.name)return false;
+ const p=usdPath(e);
+ if(guidSet.has(e.guid) || pathSet.has(p)) return false;
+ guidSet.add(e.guid);
+ pathSet.add(p);
+ }
+ return true;
+}Also applies to: 353-353, 617-619
🤖 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-geo-viewer-prototype.html` around lines 292 - 293, The
current sanitizeGuid -> usdPath pipeline replaces non-alphanumerics (e.g., "$")
with "_" causing collisions; change sanitizeGuid to produce a collision-free
token by encoding non-alphanumeric characters (e.g., percent-encoding or
base64-url of the original GUID) or by appending a short deterministic hash of
the original GUID to the sanitized string so mapping is one-to-one; update
usdPath to use the new sanitizeGuid output; and update checkSemantic to validate
uniqueness of the resulting usdPath (not just source GUID) to catch any
remaining collisions. Ensure the chosen encoding is filesystem/URL-safe for USD
paths and deterministic so same GUID always maps to same usdPath.
graphify-corpus 與 docs/wiki/graphify 是 worker-only runtime 之前架構的歷史分析快照（內容全是 _s3_storage / _conversion-service / bim-review-coordinator 等退役元件），且 repo 內無 sources.txt / build_graph.py 無法重生，實質為 dead 靜態快照。整包移除（corpus 11 檔 + wiki 23 檔）。 同步淨化治理文件（graphify 具名 → 中性 generated wiki，保留『wiki 墊底、不可當權威』層級規範）：docs/AGENTS.md 移除 Owns/Boundaries/Before-Editing 的 graphify-corpus 規則；根 AGENTS.md 與 CLAUDE.md 的 source-of-truth 優先序去具名；README.md 移除 graphify 區段並改目錄導覽列；openspec/config.yaml、docs/PROJECT_UNDERSTANDING.md、docs/agents/repo-boundary-detail.md 去具名。 保留 .gitignore 的 graphify-out/：graphify 這個 skill 本身未退役，該條目是其 scratch 輸出防呆。 Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
monkey1sai
changed the title
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 057523104e
ℹ️ 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".
| @@ -0,0 +1,719 @@ | |||
| <!doctype html> | |||
There was a problem hiding this comment.
When this PR adds docs/plans/ai-bim-geo-viewer-prototype.html, it violates the active documentation-source-of-truth gate: openspec/specs/documentation-source-of-truth/spec.md requires git ls-files docs/plans/*.html to contain only docs/plans/ai-bim-governance-prototype.html and says review must block any other generated HTML. I checked the current tracked set and this commit makes it list both HTML files, while .gitignore still only un-ignores the governance prototype, so this bypasses the documented source-of-truth rule.
Useful? React with 👍 / 👎.
PR Review Agent SummaryReport generation failed. |
依 PR #203 review(Codex P2 / Copilot）修正本次清理引入的 3 個真問題： 1. 移除 ai-bim-geo-viewer-prototype.html 版控：documentation-source-of-truth spec 規定 docs/plans/*.html 僅允許 ai-bim-governance-prototype.html 一個 tracked HTML（.gitignore:156 本就忽略 geo-viewer）。先前誤納入版控違反此 gate；改回 untracked（實體保留供參考）。正式納入需另開 OpenSpec change。 2. repoint phase-b broken link：docs/agents/repo-boundary-detail.md:98/103 仍引用已刪的 phase-b DRAFT；改指向其 archived OpenSpec change 2026-05-18-local-coordinator-ifc-ready-intake-boundary。 3. 修 docs-plans-README.md 自指路徑：snippet 內 docs/plans/README.md 實際檔名為 docs-plans-README.md。 Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 2f2caa02b7
ℹ️ 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".
| | 檔案 | 角色 | 照著做的部分 | 不要照抄的部分 | | ||
| |---|---|---|---| | ||
| | `ai-bim-governance-prototype.html` | 產品殼層需求原型（A1–A10 + 落地端控制台四頁） | 頁面清單、版面結構、互動語意（轉檔排程拖曳/Session 端點池/機隊重啟搬移）、誠實標記呈現 | 單檔 vanilla JS 實作。正式殼層 = **React 18 + TypeScript EdgeConsole**，由 coordinator `/ui` 提供 | | ||
| | `ai-bim-geo-viewer-prototype.html` | 3D viewer「執行計畫完成後」的驗收示意（對應 `#/viewer`、M4 成果） | 七區塊資訊架構（點選→IFC 語意→Pset/Qto→Spatial→GUID⇔USD 對應表→A1 疊加→反向跳轉）、驗證結果清單 | **自寫 canvas 3D 引擎（純示意）**。正式版 3D 畫面來自落地端 Kit 的 **WebRTC 串流**，前端只收 frame、指令走 DataChannel（`highlightPrimsRequest`） | |
There was a problem hiding this comment.
At this commit, the tracked docs/plans directory contains only ai-bim-governance-prototype.html as an HTML prototype, but this new mandatory guide tells agents to use ai-bim-geo-viewer-prototype.html as the #/viewer/M4 acceptance reference. Any viewer implementation following this source-of-truth now starts from a missing file, so either include that prototype or point the guide at an existing spec/prototype.
Useful? React with 👍 / 👎.
| } | ||
| ``` | ||
|
|
||
| 匯出 BCF 3.0 = 把 Issue 打包成 `.bcfzip`（每個 issue 一個資料夾：`markup.bcf` 描述 + `viewpoint.bcfv` 視角 + `snapshot.png` 截圖；沒有 3D 時 viewpoint/snapshot 可缺省，誠實標「無視角資訊」）。 |
There was a problem hiding this comment.
This new authoritative plan requires BCF 3.0 export, but the implemented governance path is explicitly BCF 2.1: governance-service/bcf/api.py and bcf_writer.py export BCF 2.1, the coordinator proxy comments preserve that contract, and the UI/tests label the download as “BCF 2.1”. If agents follow this line for A1, they will validate or build a different format than the shipped exporter supports, so the plan should either stay on BCF 2.1 or call out a separate migration.
Useful? React with 👍 / 👎.
PR Review Agent SummaryReport generation failed. |
目的
以
ai-bim-governance-prototype.html（前端主頁）與ai-bim-geo-viewer-prototype.html（3D viewer，實體保留供參考）為本 repo 開發方向，清理 worker-only runtime 之前的退役文件雜訊。三部分：① 收斂docs/plans/；② 移除退役 graphify corpus/wiki；③ 依 review 修正清理引入的問題。第一部分：收斂 docs/plans/（commit
b33d610）移除 8 份退役檔（2026-05 退役架構，或已被 v2/v3 取代）：
BIM_REVIEW_MVP_COMPLETION_PLAN_v0_2、review-mvp-v0-2-baseline（純轉址）、v0_3_DEMO_UI、BIM_REVIEW_COORDINATOR_WEB_VIEWER_EXECUTION_PLAN、IFC_TO_USDC_CONVERSION_API_IMPLEMENTATION_PLAN、phase-b-...DRAFT（已升格 OpenSpec archived #64）、next-burn-down-2026-05-19、fast-mvp-edge-bim-server-console-design。納入版控（先前未追蹤）：
ai-bim-governance-開發軌跡與執行計畫.md（v3）、docs-plans-README.md。保留BIM_REVIEW_DEMO_UI_GUIDELINES.md（仍被三個 sub-repo live 引用）。docs/plans/tracked 最終 = governance prototype + 設計規格 + v3 + README + DEMO_UI_GUIDELINES（5 份）；ai-bim-geo-viewer-prototype.html實體保留但依 gate 不 tracked（見第三部分）。第二部分：移除退役 graphify（commit
0575231）docs/graphify-corpus/（11 檔）與docs/wiki/graphify/（23 檔）為 worker-only runtime 之前架構的歷史快照，且 repo 內無sources.txt/build_graph.py無法重生 —— dead 靜態快照。整包移除，並同步把治理文件（docs/AGENTS.md、根AGENTS.md/CLAUDE.md、README.md、openspec/config.yaml、docs/PROJECT_UNDERSTANDING.md、docs/agents/repo-boundary-detail.md）的 graphify 具名淨化成中性generated wiki（保留 wiki 墊底層級規範）。保留.gitignore的graphify-out/。第三部分：review 修正（commit
2f2caa0）依 Codex P2 / Copilot review 修正本次清理引入的 3 個真問題：
openspec/specs/documentation-source-of-truth/spec.md:66規定git ls-files docs/plans/*.html僅允許 governance prototype 一個 tracked HTML（.gitignore:156本就忽略 geo-viewer）。先前誤納入違反 gate；改回 untracked（實體保留）。正式納入需另開 OpenSpec change。docs/agents/repo-boundary-detail.md:98/103仍引用已刪的 phase-b DRAFT → 改指 archived OpenSpec change2026-05-18-local-coordinator-ifc-ready-intake-boundary。docs/plans/README.md→docs-plans-README.md。已知 / 待決（非本 PR 範圍，不擅改規劃內容）
/api/v1vs coordinator/api/governance/*proxy。依 spec「v3 須與 contract/OpenSpec 對齊」，建議後續另開 change 對齊。驗證
git diff --cached --check乾淨grep全 repo（排除 archive）：8 個被刪 plan 零殘留活引用；graphify 僅.gitignore一處刻意保留git ls-files docs/plans/*.html僅 governance prototype（符合 documentation-source-of-truth gate）🤖 Generated with Claude Code