docs(openspec): 延後多 Kit 驗證至 GPU 部署後 - #28
Conversation
📝 WalkthroughWalkthroughThe PR updates project planning documents and OpenSpec specifications to establish GPU capacity availability as a blocking condition for dedicated multi-Kit runtime verification. Planning artifacts clarify when Phase 3 runtime validation can proceed, reorder candidate sequencing, and introduce new quality baseline candidates; OpenSpec specs define verification gates and clarify service contract boundaries. ChangesGPU Capacity Blocker and Verification Scope
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 |
There was a problem hiding this comment.
Pull request overview
This PR updates OpenSpec and planning documentation to reflect that dedicated_instance (dedicated multi‑Kit) runtime verification is deferred until GPU capacity is purchased and deployed, while also replacing several archived-spec “TBD” Purpose placeholders with concrete Purpose statements.
Changes:
- Marked dedicated multi‑Kit (
dedicated_instance) runtime verification as deferred/pending GPU capacity across relevant OpenSpec specs and workflow/roadmap docs. - Clarified evidence/task-status language to forbid labeling the dedicated tier as in-progress/passed/failed before capacity exists.
- Replaced “TBD … update after archive” Purpose sections in multiple OpenSpec capability specs with explicit scope/boundary descriptions.
Reviewed changes
Copilot reviewed 11 out of 12 changed files in this pull request and generated 4 comments.
Show a summary per file
| File | Description |
|---|---|
| openspec/specs/worker-dev-ifc-source-selection/spec.md | Replaces archived “TBD” Purpose with a concrete description of dev-only IFC source selection flow. |
| openspec/specs/worker-demo-upload-convert-ui/spec.md | Replaces archived “TBD” Purpose with a concrete description of the worker demo UI boundary. |
| openspec/specs/worker-artifact-pipeline/spec.md | Replaces archived “TBD” Purpose with a concrete description of _worker responsibilities and boundaries. |
| openspec/specs/streaming-multi-layer-payload-loading/spec.md | Replaces archived “TBD” Purpose with a concrete description of same-instance multi-binding loading behavior. |
| openspec/specs/session-first-review-viewer/spec.md | Replaces archived “TBD” Purpose with a concrete description of the session-first viewer responsibilities. |
| openspec/specs/runtime-verification-task-status/spec.md | Updates the dedicated multi-Kit routing scenario to explicitly remain deferred until GPU capacity is deployed. |
| openspec/specs/runtime-verification-evidence/spec.md | Defines/clarifies deferred evidence rules for dedicated_instance until GPU endpoints exist; updates Purpose. |
| openspec/specs/review-session-request-lifecycle/spec.md | Replaces archived “TBD” Purpose with a concrete description of lifecycle contract boundaries. |
| openspec/specs/multi-artifact-kit-routing/spec.md | Updates Purpose and requirements/scenarios to reflect dedicated multi‑Kit allocation intent vs deferred capacity. |
| docs/PROJECT_DEVELOPMENT_WORKFLOW.md | Aligns Phase 3 and evidence tables/next steps to show dedicated multi‑Kit runtime is deferred pending GPU capacity. |
| docs/plans/AI-BIM-governance-saas-roadmap-2026-05.md | Updates roadmap status, risks, and candidate prioritization to defer #2 until GPU purchase/deployment. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| #### Scenario: GPU capacity purchase and deployment is pending | ||
|
|
||
| - **WHEN** no purchased and deployed GPU capacity tier provides at least two Kit endpoints | ||
| - **THEN** dedicated_instance runtime verification is recorded as deferred pending capacity |
| #### Scenario: Root scripts coordinate multi Kit startup | ||
|
|
||
| - **WHEN** multi Kit runtime verification needs to launch or check more than one service | ||
| - **WHEN** GPU capacity has been purchased and deployed and multi Kit runtime verification needs to launch or check more than one service | ||
| - **THEN** the orchestration entrypoint MUST live under root `scripts/` while `bim-streaming-server/scripts/` may remain the low-level single-instance launcher |
|
|
||
| - **WHEN** a session requests `routing_policy=dedicated_instance` before purchased and deployed GPU capacity exposes two or more Kit endpoints | ||
| - **THEN** the coordinator records the requested dedicated topology and leaves runtime allocation evidence pending | ||
| - **AND** the workspace does not classify dedicated_instance runtime evidence as passed or failed |
| ## Purpose | ||
| TBD - created by archiving change introduce-worker-review-session-lifecycle. Update Purpose after archive. | ||
| Define `_worker` as the artifact and conversion facade for source model files, | ||
| derived USDC artifacts, indices, mapping files, versioned object layout, | ||
| conversion lineage, original filename traceability, real IFC conversion output, | ||
| and conversion quality reporting. `_worker` owns file bytes and derived | ||
| artifact bodies while publishing metadata only to `_bim-control`. |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (1)
openspec/specs/runtime-verification-evidence/spec.md (1)
55-56: 💤 Low valueConsider simplifying the scenario condition.
The condition "GPU capacity has been purchased and deployed and multi Kit runtime verification needs to launch or check more than one service" is semantically correct but verbose.
Consider:
- **WHEN** GPU capacity has been purchased and deployed and multi-Kit runtime verification is executedThis maintains the gate requirement while simplifying the action description. However, if the phrase "launch or check more than one service" is intentionally precise to distinguish multi-service orchestration, the current wording is acceptable.
🤖 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 `@openspec/specs/runtime-verification-evidence/spec.md` around lines 55 - 56, Replace the verbose WHEN condition text in the runtime-verification-evidence spec (the bullet currently starting "GPU capacity has been purchased and deployed and multi Kit runtime verification needs to launch or check more than one service") with a simpler phrase such as "GPU capacity has been purchased and deployed and multi-Kit runtime verification is executed"; if you need to preserve the multi-service intent, append a short clarifier like " (i.e., orchestrating or checking multiple services)" to the same bullet so the requirement remains explicit.
🤖 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 `@openspec/specs/multi-artifact-kit-routing/spec.md`:
- Around line 60-62: Update the statement that currently reads "the workspace
does not classify dedicated_instance runtime evidence as passed or failed" to
match the runtime-verification-evidence spec by prohibiting all three states:
"in-progress, passed, or failed"; locate the clause tied to the
`routing_policy=dedicated_instance` scenario and replace the existing phrasing
so it explicitly mirrors the requirement that the workspace MUST NOT classify
the dedicated runtime tier as in-progress, passed, or failed.
---
Nitpick comments:
In `@openspec/specs/runtime-verification-evidence/spec.md`:
- Around line 55-56: Replace the verbose WHEN condition text in the
runtime-verification-evidence spec (the bullet currently starting "GPU capacity
has been purchased and deployed and multi Kit runtime verification needs to
launch or check more than one service") with a simpler phrase such as "GPU
capacity has been purchased and deployed and multi-Kit runtime verification is
executed"; if you need to preserve the multi-service intent, append a short
clarifier like " (i.e., orchestrating or checking multiple services)" to the
same bullet so the requirement remains explicit.
🪄 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: f790501a-ce77-4bad-85b1-636206ce210a
📒 Files selected for processing (12)
docs/PROJECT_DEVELOPMENT_WORKFLOW.mddocs/plans/AI-BIM-governance-saas-roadmap-2026-05.htmldocs/plans/AI-BIM-governance-saas-roadmap-2026-05.mdopenspec/specs/multi-artifact-kit-routing/spec.mdopenspec/specs/review-session-request-lifecycle/spec.mdopenspec/specs/runtime-verification-evidence/spec.mdopenspec/specs/runtime-verification-task-status/spec.mdopenspec/specs/session-first-review-viewer/spec.mdopenspec/specs/streaming-multi-layer-payload-loading/spec.mdopenspec/specs/worker-artifact-pipeline/spec.mdopenspec/specs/worker-demo-upload-convert-ui/spec.mdopenspec/specs/worker-dev-ifc-source-selection/spec.md
| - **WHEN** a session requests `routing_policy=dedicated_instance` before purchased and deployed GPU capacity exposes two or more Kit endpoints | ||
| - **THEN** the coordinator records the requested dedicated topology and leaves runtime allocation evidence pending | ||
| - **AND** the workspace does not classify dedicated_instance runtime evidence as passed or failed |
There was a problem hiding this comment.
Inconsistency with runtime-verification-evidence spec regarding evidence states.
Line 62 states "the workspace does not classify dedicated_instance runtime evidence as passed or failed", but the corresponding requirement in runtime-verification-evidence/spec.md (line 51) says "MUST NOT classify the dedicated runtime tier as in-progress, passed, or failed" (emphasis added).
For consistency, line 62 should match all three prohibited states:
-- **AND** the workspace does not classify dedicated_instance runtime evidence as passed or failed
+- **AND** the workspace does not classify dedicated_instance runtime evidence as in-progress, passed, or failedThis ensures both specs have aligned semantics about which evidence states are prohibited when capacity is not available.
📝 Proposed fix for state consistency
- **WHEN** a session requests `routing_policy=dedicated_instance` before purchased and deployed GPU capacity exposes two or more Kit endpoints
- **THEN** the coordinator records the requested dedicated topology and leaves runtime allocation evidence pending
-- **AND** the workspace does not classify dedicated_instance runtime evidence as passed or failed
+- **AND** the workspace does not classify dedicated_instance runtime evidence as in-progress, passed, or failed🤖 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 `@openspec/specs/multi-artifact-kit-routing/spec.md` around lines 60 - 62,
Update the statement that currently reads "the workspace does not classify
dedicated_instance runtime evidence as passed or failed" to match the
runtime-verification-evidence spec by prohibiting all three states:
"in-progress, passed, or failed"; locate the clause tied to the
`routing_policy=dedicated_instance` scenario and replace the existing phrasing
so it explicitly mirrors the requirement that the workspace MUST NOT classify
the dedicated runtime tier as in-progress, passed, or failed.
![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: 8ad7173347
ℹ️ 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".
| 依當前進度（Phase 0/1/2 ✅、Phase 3 🔄 control-plane 完成 / dedicated multi-Kit runtime 等待 GPU capacity），建議優先順序： | ||
|
|
||
| ### 12.1 第一優先：解開 Phase 3 runtime blocker（對應 SaaS 路線圖 P0 候選 #1 / #2） | ||
| ### 12.1 第一優先：解開 Phase 3 runtime blocker（對應 SaaS 路線圖 #1 / #2） |
There was a problem hiding this comment.
This updated “current progress” section still points the first priority at roadmap #1, but this same commit’s roadmap now marks worker-real-conversion-quality as archived and introduces #3A as the follow-up for mapping-quality baselines. In the workflow path where someone follows §12 to choose the next OpenSpec task, the bullets immediately below still tell them to run /openspec new worker-real-conversion-quality, which would reopen an already-archived change instead of the actual remaining work.
Useful? React with 👍 / 👎.
| - **WHEN** no purchased and deployed GPU capacity tier provides at least two Kit endpoints | ||
| - **THEN** dedicated_instance runtime verification is recorded as deferred pending capacity | ||
| - **AND** the evidence MUST NOT classify the dedicated runtime tier as in-progress, passed, or failed |
There was a problem hiding this comment.
When there are no two GPU-backed Kit endpoints, this new scenario requires dedicated_instance evidence to be recorded as “deferred pending capacity”, but the earlier hardware-dependent scenario in the same spec still requires unavailable multiple Kit instances to be recorded as blocked with missing prerequisites. A verifier for the no-capacity case cannot satisfy both statuses, so downstream roadmap/status updates can keep oscillating between blocked and deferred; narrow the earlier scenario or define deferred as the status for this dedicated-capacity case.
Useful? React with 👍 / 👎.
| ### 12.4 P2.5：採用 NVIDIA reference implementation | ||
|
|
||
| > 對應 SaaS 路線圖 §12（由 MCP 結果新增）+ §13 採用決策框架。**前置條件**：#1 / #2 在 main 上 land。 | ||
| > 對應 SaaS 路線圖 §12（由 MCP 結果新增）+ §13 採用決策框架。**前置條件**：#1 已 land、GPU capacity 到位、#2 runtime evidence land。 |
There was a problem hiding this comment.
This blanket P2.5 prerequisite also applies to #1A in the list below, but the roadmap updated in this commit says streaming-collaboration-presence-layer-upgrade can be explored from Tier A with Nucleus or a self-hosted USD live transport and explicitly does not depend on #2A/#2. If someone selects #1A, this workflow would incorrectly block that collaboration-presence work until GPU capacity and dedicated multi-Kit evidence are available; keep the #2 evidence prerequisite scoped to #2A/OVAS.
Useful? React with 👍 / 👎.
| | **Single Kit GPU Render (worker-hosted renderable fixture)** | 已存在的 renderable `.usdc` fixture 經 worker 路徑載入 Kit viewport | ✅ 通過（PR #20 commit `0e94a5b`） | `docs/verification/evidence/2026-05-08-runtime-e2e/same-kit-review_session_b2d84c44ae31-kit_local_001-primary.png` | | ||
| | **Same-Kit Concurrent Stream (primary + spectator)** | 單一 Kit process 內 primary + spectator WebRTC ports（49100/47998 + 49110/48008）並行 stream，兩個 Chrome contexts 同一 `session_id` | ✅ 通過（PR #20 commit `0e94a5b`） | `same-kit-*-primary.png` / `same-kit-*_spectator_0-spectator.png` | | ||
| | **Dedicated Multi-Kit Routing (≥2 Kit processes)** | ≥2 獨立 Kit processes、不同 signaling port pair、並行 stream | 🟡 在另一分支驗證中（owner 自管，非 environment-blocked）；待對應 PR merge 進 main 並更新 `runtime-verification-evidence` §6.4 | 缺：root scripts 啟動多 Kit；對應 SaaS 路線圖 P0 候選 #2 `streaming-multi-instance-orchestration` | | ||
| | **Dedicated Multi-Kit Routing (≥2 Kit processes)** | ≥2 獨立 Kit processes、不同 signaling port pair、並行 stream | ⏸ 等待 GPU 購買與部署後執行；GPU capacity 到位前不得標為 in-progress / passed / failed | 缺：GPU-backed 多 Kit endpoints；對應 SaaS 路線圖 P0-hold 候選 #2 `streaming-multi-instance-orchestration` | |
There was a problem hiding this comment.
This evidence matrix is being updated for the #2 GPU-capacity hold, but the adjacent Single Kit GPU Render (real IFC→USDC) row still says it is blocked by placeholder model.usdc and points at P0 #1, while this same commit’s roadmap records #1 as archived with real IFC→USDC and single Kit/browser evidence. Readers using this workflow matrix will still treat the real single-Kit render as blocked and may reopen #1 unnecessarily; update the matrix in the same pass so only dedicated multi-Kit remains deferred.
Useful? React with 👍 / 👎.
| - **WHEN** a session requests `routing_policy=dedicated_instance` before purchased and deployed GPU capacity exposes two or more Kit endpoints | ||
| - **THEN** the coordinator records the requested dedicated topology and leaves runtime allocation evidence pending | ||
| - **AND** the workspace does not classify dedicated_instance runtime evidence as passed or failed |
There was a problem hiding this comment.
This no-capacity scenario only says the workspace must not classify dedicated_instance evidence as passed or failed, but the roadmap and runtime-verification-evidence scenario added in this commit also forbid marking it in-progress before GPU capacity exists. As written, a status report can mark the tier in-progress and still satisfy this capability while violating the other updated documents; add in-progress here too so all specs enforce the same hold state.
Useful? React with 👍 / 👎.
- #27(P2): _pollForKitReady 進入點改 _clearPollForKitReady(),閉合 in-mount 重入孤兒並行 chain(原僅 id=null 不 clearTimeout) - #28(P2): _resetState 參數化 connectionText,逾時訊息不再被 _resetState 的 connectionText:'' 覆寫 - #32(P2): GFN script 命中既有但全域 GFN 未就緒時補掛 load/error,避免 remount-during-load 仍 ReferenceError(用 //@ts-ignore 不引入 as any) - design.md #8: 修正捏造的 SDK 引用(實裝 5.17.0/L71/terminate(terminateApp?) 無 _force) - 補 triReady.test.ts(11 test,含 #16 spectator started+matched→yes);Decision 7 誠實揭露 structLog.test.ts defer 驗證:build + vitest 32 passed(21→32) + struct-log 10 + session-first 全綠。 Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
變更摘要
更新 OpenSpec 規格、SaaS roadmap、workflow 文件與同名 HTML 檢視版，將
multi-artifact-kit-routing/streaming-multi-instance-orchestration的 dedicated multi-Kit runtime 驗證狀態改為等待 GPU 購買與部署後執行。修改原因
原文件仍將 #2 /
dedicated_instanceruntime 描述為另一分支驗證中，容易讓 roadmap 與 OpenSpec 狀態誤判為正在執行。依最新決策，該 runtime tier 在至少兩個 GPU-backed Kit endpoints 可用前應維持 deferred pending capacity。主要變更
openspec/specs/multi-artifact-kit-routing/spec.md，加入 GPU capacity 等待語意與 allocation intent 描述。openspec/specs/runtime-verification-evidence/spec.md，明定 dedicated multi-Kit runtime evidence 在 GPU 購買部署前不得標為 in-progress / passed / failed。openspec/specs/runtime-verification-task-status/spec.md，將 dedicated multi-Kit process routing 保持 deferred。docs/plans/AI-BIM-governance-saas-roadmap-2026-05.md的 Phase 3、docs: add Cursor Cloud specific instructions to AGENTS.md #2、#2A、R2、§9.2 與 next steps。docs/plans/AI-BIM-governance-saas-roadmap-2026-05.html。docs/PROJECT_DEVELOPMENT_WORKFLOW.md的 Phase / evidence / priority 描述。驗證方式
openspec validate --all --strict：11 passed, 0 failed。另一分支驗證中、owner 自管、non-blocked、非 environment-blocked等舊語意殘留。git diff --cached --check：通過。detect_changes：docs/spec-only，無 symbol/process 影響。風險與影響
docs/plans/AI-BIM-governance-saas-roadmap-2026-05.html是由同名 Markdown 重新產生的衍生檢視版，diff 較大但 source of truth 仍是 Markdown。回滾方式
若需撤回，可 revert 此 PR 的 merge commit，或將 #2 /
dedicated_instance相關段落改回前一版 roadmap 與 OpenSpec 描述後重新驗證openspec validate --all --strict。後續建議
runtime-verification-evidence、roadmap Markdown 與 HTML 檢視版。Summary by CodeRabbit