docs(openspec): propose backfill-coordinator-webhook-and-auto-session - #84
Merged
Merged
Conversation
補 archive 2026-05-21-coordinator-ifc-ready-worker-webhook 的 spec drift （retro-audit commit a32fcd6 確認 26 個 tasks 為 documentation lag，code 從未實作）。 純 implementation backfill： - bim-review-coordinator intake 加 worker compatibility payload normalization （status / ifc_path / project_id / version / task_id → canonical event） - ingestConversionReport ready 分支接 SessionStore.create + allocateKitInstanceBindings + chooseReadyUsdc，與 callbackOutbox.enqueue 並行不耦合 - 對 correlation_id / external_model_version_id idempotent - 11 個 spec scenarios（intake 4 + auto-session 4 + webhook seam 3）對應 unit/contract test Spec delta（採 Option B — OpenSpec strict 要求 delta + Scenario）： - 3 個 MODIFIED requirement（intake-boundary / session-lifecycle / webhook-lifecycle） - 每個 requirement 末尾加「Implementation status (2026-05-21)」 backfill note - scenarios 全保留不變、語意無變動 Verification (propose phase): - openspec validate backfill-coordinator-webhook-and-auto-session --strict ✓ - 不新增 production source / dependency / 不改 code - 不解 OQ1（雲端 callback）/ OQ5（SSO） - Render tier (single_kit_render / WebRTC 49100 / browser visual) 維持 not_observed，不在本 change pass 範圍 Next：apply 階段在新 worktree (.worktrees/backfill-coordinator-webhook-and-auto-session/) 跑 tasks §0-§7。 Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Contributor
|
Warning Rate limit exceeded
You’ve run out of usage credits. Purchase more in the billing tab. ⌛ How to resolve this issue?After the wait time has elapsed, a review can be triggered using the We recommend that you space out your commits to avoid hitting the rate limit. 🚦 How do rate limits work?CodeRabbit enforces hourly rate limits for each developer per organization. Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout. Please see our FAQ for further information. ℹ️ Review info⚙️ Run configurationConfiguration used: defaults Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (7)
✨ 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 adds an OpenSpec change proposal artifact set to address spec drift identified in archive 2026-05-21-coordinator-ifc-ready-worker-webhook: worker compatibility IFC-ready intake normalization + conversion-ready → auto session handoff + callback/outbox seam classification. It is intentionally docs-only (no production code/dependency changes), and lays out tasks/design/spec deltas for a later implementation PR.
Changes:
- Add a new OpenSpec change folder (
backfill-coordinator-webhook-and-auto-session) with proposal/design/tasks and metadata. - Add “Option B” NO-OP-ish deltas: three MODIFIED requirement entries that append an Implementation status (2026-05-21) note while keeping scenarios unchanged.
- Document an implementation plan including test coverage mapping for 11 scenarios (intake 4 + auto-session 4 + webhook seam 3).
Reviewed changes
Copilot reviewed 7 out of 7 changed files in this pull request and generated 3 comments.
Show a summary per file
| File | Description |
|---|---|
| openspec/changes/backfill-coordinator-webhook-and-auto-session/.openspec.yaml | Declares the change schema + creation date. |
| openspec/changes/backfill-coordinator-webhook-and-auto-session/proposal.md | Explains rationale, gaps, and intended implementation backfill + impact. |
| openspec/changes/backfill-coordinator-webhook-and-auto-session/design.md | Maps code-level seams, decisions (D9–D11), and verification strategy. |
| openspec/changes/backfill-coordinator-webhook-and-auto-session/tasks.md | Task checklist for apply phase (intake normalization + auto-session + tests/verification/evidence). |
| openspec/changes/backfill-coordinator-webhook-and-auto-session/specs/conversion-webhook-lifecycle/spec.md | Adds implementation-status note to the relevant MODIFIED requirement; scenarios unchanged. |
| openspec/changes/backfill-coordinator-webhook-and-auto-session/specs/local-coordinator-ifc-ready-intake-boundary/spec.md | Adds implementation-status note to the relevant MODIFIED requirement; scenarios unchanged. |
| openspec/changes/backfill-coordinator-webhook-and-auto-session/specs/review-session-request-lifecycle/spec.md | Adds implementation-status note to the relevant MODIFIED requirement; scenarios unchanged. |
Comments suppressed due to low confidence (1)
openspec/changes/backfill-coordinator-webhook-and-auto-session/tasks.md:13
normalizeIntakePayloadis planned to emit a canonicalExternalIfcReadyEvent, but the mapping list omits how the requiredsource_ifc.etag(and any other required canonical fields) will be populated/validated for worker-compat payloads. Since the existing coordinator schema requiressource_ifc.etag, please add an explicit mapping/decision/task for deterministic placeholder/derivation (without misrepresenting it as a real checksum) so the plan is implementable without changing the canonical contract.
- [ ] 1.1 抽出 `normalizeIntakePayload(rawBody): ExternalIfcReadyEvent` helper（D9），覆蓋 canonical payload pass-through 與 worker compatibility mapping：`status→event`、`ifc_path→source_ifc.ref`、`version→external_model_version_id`、`task_id→external_conversion_task_id`、`task_id→fallback correlation_id/idempotency_key`、`project_id→project_id`、`tenant_id` 缺時 intranet-dev fallback。
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comment on lines
+5
to
+8
| 精確缺口（grep `bim-review-coordinator/src/app.ts`）： | ||
|
|
||
| - `ingestConversionReport`（line 566-628）terminal `ready` 分支只 `callbackOutbox.enqueue` ＋ `recordConversionOutcome`，**不呼叫** `SessionStore.create` / `allocateKitInstanceBindings` / `chooseReadyUsdc`，造成 worker-webhook 驅動的閉環走到「轉檔成功」後對本地 viewer 是死路。 | ||
| - external IFC-ready intake schema 只接 canonical `event="ifc_ready"` + `external_model_version_id` + `external_conversion_task_id`，**未支援** worker compatibility payload（`status="ifc_ready"` / `ifc_path` / `project_id` + `version` + `task_id`）。 |
|
|
||
| - [ ] 0.1 開新 worktree `.worktrees/backfill-coordinator-webhook-and-auto-session/`（branch `codex/openspec/backfill-coordinator-webhook-and-auto-session`），不可在 main 上直接實作。 | ||
| - [ ] 0.2 對 affected symbols 跑 GitNexus impact analysis（`ingestConversionReport`、`SessionStore.create`、`allocateKitInstanceBindings`、`chooseReadyUsdc`、`/api/external/ifc-ready` route handler、`ExternalIfcReadyStore`、`/api/internal/conversion-result`、`/api/internal/conversions/:id/ingest`、`/api/review-sessions`）；HIGH/CRITICAL 先回報再改。GitNexus CLI 在 worktree 有 quoting bug（memory `opsx-skill-placeholder-bug`），用 `git diff --stat` + manual symbol read 為 fallback。 | ||
| - [ ] 0.3 對 `bim-review-coordinator/src/app.ts:566-628` 與 `bim-review-coordinator/src/services/{externalIfcReadyStore,sessionStore?,kitPool}.ts` 做 baseline 讀取，記錄當前 signature；確認 archive design D7（reuse existing session-create logic）仍可行。 |
Comment on lines
+54
to
+55
| - [ ] 5.1 新增 `docs/verification/2026-05-2X-backfill-coordinator-webhook-and-auto-session.md`，記錄 §4 evidence + 11 spec scenarios 對應 test 編號 + render tier `not_observed` rationale。 | ||
| - [ ] 5.2 在 `docs/plans/AI-BIM-governance-saas-roadmap-2026-05.md` 加一段 2026-05-2X 更新：archive `2026-05-21-coordinator-ifc-ready-worker-webhook` documentation lag 已透過本 change 補齊，spec drift 收斂；HTML 鏡像同步更新（`scripts/render-roadmap-html.py`）。 |
7 tasks
monkey1sai
added a commit
that referenced
this pull request
May 21, 2026
…ready auto-session（spec drift 收斂） 補 archive 2026-05-21-coordinator-ifc-ready-worker-webhook 的 documentation lag（retro-audit commit a32fcd6 確認 spec 已 ratified、code 從未實作）。 實作（bim-review-coordinator/src/app.ts）： - normalizeIntakePayload helper：external IFC-ready intake 支援 worker compatibility payload（status="ifc_ready" / ifc_path / project_id / version / task_id），正規化為 canonical ExternalIfcReadyEvent，不洩漏 進 streaming internal contract。worker compat 缺 X-Correlation-Id / X-Idempotency-Key 時從 worker:project_id::version::task_id 派生， explicit headers 仍優先（D11）。 - autoCreateOrActivateSession helper：ingestConversionReport terminal ready 分支於 callbackOutbox.enqueue 之後並行呼叫，重用既有 SessionStore.create + allocateKitInstanceBindings + chooseReadyUsdc 邏輯，對 job.review_session_id idempotent，重入回既有 session； terminal failed 不建可串流 session；GPU/Kit 無容量回 queued_for_instance 不丟 review intent。 - ExternalIfcReadyStore.recordReviewSession() 反向綁定 + IfcReadyIntakeJob review_session_id optional 欄位（additive）。 - /api/internal/conversion-result + /api/internal/conversions/:id/ingest response 加 session / session_replay / session_reason 欄位（additive）。 11 個 spec scenarios coverage（intake 4 + auto-session 4 + webhook seam 3） 皆對應 TDD-driven test：external-ifc-ready.test.ts 新增 7 cases、 host-native-conversion-ingest.test.ts 新增 6 cases。 Spec delta：採 Option B（NO-OP-ish MODIFIED re-affirm），三份 capability （local-coordinator-ifc-ready-intake-boundary / review-session-request- lifecycle / conversion-webhook-lifecycle）各加一段 "Implementation status (2026-05-21)" backfill note，scenarios 全保留不變、語意無變動。 Verification: - coordinator npm run verify: 11 files / 165 tests passed; tsc clean - root contracts pytest: 7 passed - openspec validate backfill-coordinator-webhook-and-auto-session --strict: valid - git diff --check: clean - Affected symbols 符合 §0.2 預期，無範圍擴張（fallback git diff --stat） - Render tier (single_kit_render / WebRTC 49100 / browser visual): not_observed (Kit build + GPU host 前置；memory kit-gpu-render-needs-windows-native) - OQ1 (雲端 callback endpoint/auth) / OQ5 (SSO) 仍 pending Evidence: - docs/verification/2026-05-21-backfill-coordinator-webhook-and-auto-session.md - roadmap md + html 同步更新（2026-05-21 backfill apply 通告） 不解 / 不升等: - 不修改 archive 2026-05-21-coordinator-ifc-ready-worker-webhook/tasks.md upgrade（依賴 retro-audit PR #83 先 merge，post-merge gate） - 不啟動 / 控制 Kit 進程、不開 USD stage、不渲染 - 不新增 production dependency Predecessor: 2026-05-21-coordinator-ifc-ready-worker-webhook (archive, documentation lag) Related: PR #83 retro-audit, PR #84 propose (this change) Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
monkey1sai
added a commit
that referenced
this pull request
May 21, 2026
…ready auto-session（implement spec drift） (#85) * feat(coordinator): backfill worker compatibility intake + conversion-ready auto-session（spec drift 收斂） 補 archive 2026-05-21-coordinator-ifc-ready-worker-webhook 的 documentation lag（retro-audit commit a32fcd6 確認 spec 已 ratified、code 從未實作）。 實作（bim-review-coordinator/src/app.ts）： - normalizeIntakePayload helper：external IFC-ready intake 支援 worker compatibility payload（status="ifc_ready" / ifc_path / project_id / version / task_id），正規化為 canonical ExternalIfcReadyEvent，不洩漏 進 streaming internal contract。worker compat 缺 X-Correlation-Id / X-Idempotency-Key 時從 worker:project_id::version::task_id 派生， explicit headers 仍優先（D11）。 - autoCreateOrActivateSession helper：ingestConversionReport terminal ready 分支於 callbackOutbox.enqueue 之後並行呼叫，重用既有 SessionStore.create + allocateKitInstanceBindings + chooseReadyUsdc 邏輯，對 job.review_session_id idempotent，重入回既有 session； terminal failed 不建可串流 session；GPU/Kit 無容量回 queued_for_instance 不丟 review intent。 - ExternalIfcReadyStore.recordReviewSession() 反向綁定 + IfcReadyIntakeJob review_session_id optional 欄位（additive）。 - /api/internal/conversion-result + /api/internal/conversions/:id/ingest response 加 session / session_replay / session_reason 欄位（additive）。 11 個 spec scenarios coverage（intake 4 + auto-session 4 + webhook seam 3） 皆對應 TDD-driven test：external-ifc-ready.test.ts 新增 7 cases、 host-native-conversion-ingest.test.ts 新增 6 cases。 Spec delta：採 Option B（NO-OP-ish MODIFIED re-affirm），三份 capability （local-coordinator-ifc-ready-intake-boundary / review-session-request- lifecycle / conversion-webhook-lifecycle）各加一段 "Implementation status (2026-05-21)" backfill note，scenarios 全保留不變、語意無變動。 Verification: - coordinator npm run verify: 11 files / 165 tests passed; tsc clean - root contracts pytest: 7 passed - openspec validate backfill-coordinator-webhook-and-auto-session --strict: valid - git diff --check: clean - Affected symbols 符合 §0.2 預期，無範圍擴張（fallback git diff --stat） - Render tier (single_kit_render / WebRTC 49100 / browser visual): not_observed (Kit build + GPU host 前置；memory kit-gpu-render-needs-windows-native) - OQ1 (雲端 callback endpoint/auth) / OQ5 (SSO) 仍 pending Evidence: - docs/verification/2026-05-21-backfill-coordinator-webhook-and-auto-session.md - roadmap md + html 同步更新（2026-05-21 backfill apply 通告） 不解 / 不升等: - 不修改 archive 2026-05-21-coordinator-ifc-ready-worker-webhook/tasks.md upgrade（依賴 retro-audit PR #83 先 merge，post-merge gate） - 不啟動 / 控制 Kit 進程、不開 USD stage、不渲染 - 不新增 production dependency Predecessor: 2026-05-21-coordinator-ifc-ready-worker-webhook (archive, documentation lag) Related: PR #83 retro-audit, PR #84 propose (this change) Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * docs(openspec): closeout — upgrade archive deferred tasks to implemented (post-PR #83 merge) retro-audit PR #83 commit e8e576d 已合進 main，archive 2026-05-21-coordinator-ifc-ready-worker-webhook/tasks.md 的 26 個 deferred 標記源自該 commit。本 branch rebase onto latest main 後做 §5.3 post-merge gate 收尾。 改動: - openspec/changes/archive/2026-05-21-coordinator-ifc-ready-worker-webhook/tasks.md: 26 個 [ ] — **deferred** 升級為 [x] — **implemented** by PR #85 (was: **deferred**: ...)，原 retro-audit annotation 完整保留作為 documentation lag 證據；archive 開頭加 closeout 區塊指向 PR #85 evidence。 - openspec/changes/backfill-coordinator-webhook-and-auto-session/tasks.md: §5.3 自身狀態升 [x]。 Verification: - openspec validate backfill-coordinator-webhook-and-auto-session --strict: valid - 純文件改動，零 code 改動 Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
3 of 6 tasks
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.
Summary
補 archive
2026-05-21-coordinator-ifc-ready-worker-webhook的 spec drift。retro-audit (見另一 PR) 確認該 archive 為 documentation lag：規格已 ratified，code 從未實作。本 PR 僅是 OpenSpec change proposal artifacts（純 docs），尚未實作 code。Apply 階段另開 worktree 與 PR。
缺口（grep
bim-review-coordinator/src/app.ts）ingestConversionReport（line 566-628）terminalready分支只callbackOutbox.enqueue＋recordConversionOutcome，不呼叫SessionStore.create/allocateKitInstanceBindings/chooseReadyUsdcevent="ifc_ready"+external_model_version_id，未支援 worker compatibility payload（status="ifc_ready"/ifc_path/project_id+version+task_id）not_implementedChange artifacts
Spec delta 策略
採 Option B（NO-OP-ish MODIFIED）：
Change must have at least one delta> **Implementation status (2026-05-21)**: backfilled by ...noteNon-goals
single_kit_render/ WebRTC49100/ browser visual 升等為 passedVerification (propose phase)
npx openspec validate backfill-coordinator-webhook-and-auto-session --strict✓Change is validopenspec list顯示 1/34 tasks（4.5 已 propose 階段勾）Predecessor
2026-05-21-coordinator-ifc-ready-worker-webhook（archived 2026-05-21，documentation lag）Test plan
tasks.md§1-§3 task 編號合理🤖 Generated with Claude Code