Repository navigation
docs(openspec): 歸檔 streaming-server-ifcopenshell-semantic-sidecar-pass - #137
Conversation
…s 並落地 capability spec PR #136 (cea66e0) merged 後同步: - 移動 openspec/changes/streaming-server-ifcopenshell-semantic-sidecar-pass/ → openspec/changes/archive/2026-05-28-streaming-server-ifcopenshell-semantic-sidecar-pass/ - 落地 spec delta 進 openspec/specs/streaming-ifc-usdc-conversion-authority/spec.md (+1 ADD requirement「HOOPS happy path SHALL be augmented by an IfcOpenShell semantic sidecar pass」+ 7 scenarios:HOOPS success → sidecar pass / filter Representation / enumeration reads sidecar / prefers prim CustomData / honest fallback / callback outbox metadata-only / backward compat / no retro-fit) Verify: - npx openspec validate --specs --strict: 32 passed / 0 failed Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
📝 WalkthroughWalkthroughThis PR adds a specification section for an IfcOpenShell-based semantic sidecar pass that augments HOOPS BIM-to-USDC conversion. The specification defines how a ChangesIfcOpenShell Semantic Sidecar Pass Requirements
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 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 syncs an already-merged OpenSpec change into the archive and lands its spec delta into the canonical capability spec (streaming-ifc-usdc-conversion-authority). It updates the documentation/spec to reflect the “IfcOpenShell semantic sidecar pass” behavior for HOOPS happy-path conversions in bim-streaming-server.
Changes:
- Adds 1 new requirement (+7 scenarios) to
openspec/specs/streaming-ifc-usdc-conversion-authority/spec.mdfor the IfcOpenShell semantic sidecar pass. - Archives the change under
openspec/changes/archive/2026-05-28-streaming-server-ifcopenshell-semantic-sidecar-pass/(proposal/design/tasks + spec delta).
Reviewed changes
Copilot reviewed 1 out of 5 changed files in this pull request and generated 1 comment.
Show a summary per file
| File | Description |
|---|---|
| openspec/specs/streaming-ifc-usdc-conversion-authority/spec.md | Lands the archived delta into the canonical capability spec (1 new requirement + scenarios). |
| openspec/changes/archive/2026-05-28-streaming-server-ifcopenshell-semantic-sidecar-pass/tasks.md | Archived tasks checklist for the change. |
| openspec/changes/archive/2026-05-28-streaming-server-ifcopenshell-semantic-sidecar-pass/specs/streaming-ifc-usdc-conversion-authority/spec.md | Spec delta snapshot for the archived change. |
| openspec/changes/archive/2026-05-28-streaming-server-ifcopenshell-semantic-sidecar-pass/proposal.md | Archived rationale and scope description. |
| openspec/changes/archive/2026-05-28-streaming-server-ifcopenshell-semantic-sidecar-pass/design.md | Archived design/approach details and risks. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| - **OR** `ifcopenshell.open()` 對 IFC source 抛例外 | ||
| - **OR** `ifcopenshell.open()` 成功但 `.by_type("IfcProduct")` 抛例外 | ||
| - **THEN** `_run_ifcopenshell_semantic_sidecar` SHALL 回傳 `None` 且不抛例外 |
![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: 2de4d64f69
ℹ️ 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".
| - **THEN** 它們 SHALL 仍能解析新 element_mapping.json 與 entity_index.json | ||
| - **AND** 新 keys SHALL 是 additive,既有 keys 不被刪除或重新命名 | ||
|
|
||
| ### Requirement: HOOPS happy path SHALL be augmented by an IfcOpenShell semantic sidecar pass |
There was a problem hiding this comment.
This commit archives the change and lands the new capability spec, but it does not update docs/plans/AI-BIM-governance-saas-roadmap-2026-05.md or the derived .html. The archive workflow explicitly requires every OpenSpec sync/archive to update those roadmap files and says an unsynced roadmap means the archive is only a file move, not a converged project closeout (docs/agents/github-workflow.md lines 27-30). I checked the roadmap and it still describes streaming-server-ifcopenshell-semantic-sidecar-pass as a next-step candidate rather than this archived/merged state, so the planning/status source remains stale.
Useful? React with 👍 / 👎.
| - **THEN** 它們 SHALL 仍能解析新 element_mapping.json 與 entity_index.json | ||
| - **AND** 新 keys SHALL 是 additive,既有 keys 不被刪除或重新命名 | ||
|
|
||
| ### Requirement: HOOPS happy path SHALL be augmented by an IfcOpenShell semantic sidecar pass |
There was a problem hiding this comment.
Adding this HOOPS happy-path requirement leaves the same capability spec internally inconsistent: the earlier fallback-fidelity scenario still says the three semantic quality fields are not required for the primary HOOPS path because HOOPS is out of scope, while this new requirement and its scenarios make the HOOPS happy path generate and consume those fields via the sidecar supplement. Consumers using this archived spec as the source of truth can now justify either behavior, so the old out-of-scope clause needs to be updated or removed as part of the archive.
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: 1
🧹 Nitpick comments (1)
openspec/specs/streaming-ifc-usdc-conversion-authority/spec.md (1)
417-417: 💤 Low valueMinor grammar: use hyphen for compound adjective.
"Backward compatible" should be "Backward-compatible" when used as a compound adjective before a noun (per static analysis hint).
📝 Proposed fix
-#### Scenario: Backward compatible mapping schema and additive quality metrics +#### Scenario: Backward-compatible mapping schema and additive quality metrics🤖 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/streaming-ifc-usdc-conversion-authority/spec.md` at line 417, Update the heading string "Backward compatible mapping schema and additive quality metrics" to use a hyphen for the compound adjective so it reads "Backward-compatible mapping schema and additive quality metrics"; locate and edit the heading text in the Scenario title (the line beginning with "#### Scenario:") to apply this change.
🤖 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/streaming-ifc-usdc-conversion-authority/spec.md`:
- Around line 365-367: Update the spec to define observable behavior for ordinal
misalignment: state that _enumerate_usd_stage and _sidecar_entry_for_mesh_index
MUST record diagnostics/logging when sidecar index is out-of-range or an entry
is skipped, require that coverage_status in quality_metrics is computed against
the total number of USD mesh prims (not just supplemented mapping_items) so
mapped_count < total_prims yields "warn"/"fail" appropriately, and specify how
semantic_mapping_fidelity values (e.g.,
"usd_enumeration_with_ifc_sidecar_supplement") should influence viewer readiness
(align with computeSemanticReady by requiring mapping_has_ifc_type and
mapping_has_ifc_name plus non-empty fidelity) and describe expected behavior for
extra/non-IFC mesh prims (they may be skipped but must be reported and reduce
coverage).
---
Nitpick comments:
In `@openspec/specs/streaming-ifc-usdc-conversion-authority/spec.md`:
- Line 417: Update the heading string "Backward compatible mapping schema and
additive quality metrics" to use a hyphen for the compound adjective so it reads
"Backward-compatible mapping schema and additive quality metrics"; locate and
edit the heading text in the Scenario title (the line beginning with "####
Scenario:") to apply this change.
🪄 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: e98c419a-bb79-4624-9b90-8b7c538df51b
📒 Files selected for processing (5)
openspec/changes/archive/2026-05-28-streaming-server-ifcopenshell-semantic-sidecar-pass/design.mdopenspec/changes/archive/2026-05-28-streaming-server-ifcopenshell-semantic-sidecar-pass/proposal.mdopenspec/changes/archive/2026-05-28-streaming-server-ifcopenshell-semantic-sidecar-pass/specs/streaming-ifc-usdc-conversion-authority/spec.mdopenspec/changes/archive/2026-05-28-streaming-server-ifcopenshell-semantic-sidecar-pass/tasks.mdopenspec/specs/streaming-ifc-usdc-conversion-authority/spec.md
| - **THEN** `_enumerate_usd_stage` SHALL 載入 sidecar,並以 USD mesh prim 順序 | ||
| vs sidecar entries 順序 best-effort ordinal 對齊補 `mapping_items[]` | ||
| - **AND** 每筆 supplemented mapping item SHALL 含五個 keys `ifc_guid`、 |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# Description: Search for ordinal alignment or mesh count validation logic
# Check for ordinal alignment implementation
rg -nP --type=py -C3 'ordinal|best.?effort|mesh.*count|prim.*count' --glob '*enumerate*' --glob '*sidecar*'
# Check for count mismatch handling
rg -nP --type=py -C3 'count.*mismatch|len.*entries|alignment.*fail' --glob '*enumerate*' --glob '*sidecar*'Repository: monkey1sai/AI-BIM-governance
Length of output: 370
🏁 Script executed:
#!/bin/bash
set -euo pipefail
# 1) Locate where the spec lines/terms appear
rg -n --hidden --no-ignore-vcs \
"_enumerate_usd_stage|best[- ]effort|sidecar|mapping_items\[\]|usd_enumeration_with_ifc_sidecar_supplement|computeSemanticReady" \
--glob 'openspec/**/spec.md' \
--glob 'openspec/**/*.md' \
--glob 'openspec/**'
# 2) Find any code (any language) that references the fidelity value
rg -n --hidden --no-ignore-vcs \
"usd_enumeration_with_ifc_sidecar_supplement" \
.
# 3) Find any code that references sidecar ordinal / mesh prim ordering / mapping alignment
rg -n --hidden --no-ignore-vcs \
"sidecar|mapping_items|ordinal|best[- ]effort|prim.*order|mesh.*order|IfcProduct" \
.
# 4) Find computeSemanticReady implementation / switch cases (any language)
rg -n --hidden --no-ignore-vcs \
"computeSemanticReady" \
.
# 5) Check for any explicit count-mismatch or fallback behavior mentions
rg -n --hidden --no-ignore-vcs \
"count mismatch|mismatch|len\\(|entries.*len\\(|alignment fail|fallback|log warning|skip supplementation" \
.Repository: monkey1sai/AI-BIM-governance
Length of output: 50385
🏁 Script executed:
#!/bin/bash
set -euo pipefail
# 1) Locate the adapter implementation file(s)
fd -a -t f 'ifc2usdc_powershell_adapter.py' . | head -n 20
# 2) Search for the specific helper / enumeration implementation
rg -n --hidden --no-ignore-vcs \
"_enumerate_usd_stage|_sidecar_entry_for_mesh_index|best[- ]effort|sidecar entries|mesh_index|sidecar_doc" \
. --glob '*.py' --glob '*.ts' --glob '*.js' --glob '*.tsx' --glob '*.md' --glob '*.spec.*' --glob '*.json' \
--max-count 200
# 3) Look for any explicit mismatch/bounds/logging behavior
rg -n --hidden --no-ignore-vcs \
"mismatch|count mismatch|len\\(|entries\\b|index out of range|out of range|bounds|warn|warning|logger\\.|log\\.|print\\(" \
. --glob '*.py' --max-count 200
# 4) Find where the fidelity string is used in code
rg -n --hidden --no-ignore-vcs \
"usd_enumeration_with_ifc_sidecar_supplement" \
. --glob '*.py' --glob '*.ts' --glob '*.js' --max-count 200Repository: monkey1sai/AI-BIM-governance
Length of output: 50384
🏁 Script executed:
#!/bin/bash
set -euo pipefail
FILE="bim-streaming-server/source/extensions/ezplus.bim_review_stream.messaging/ezplus/bim_review_stream/messaging/ifc2usdc_powershell_adapter.py"
# Helper: print a line range with context
print_range () {
local start="$1"; local end="$2"
echo "==== $FILE:$start-$end ===="
nl -ba "$FILE" | sed -n "${start},${end}p"
}
# 1) Inspect _enumerate_usd_stage ordinal join + quality_metrics assignment
print_range 820 960
print_range 980 1060
# 2) Inspect _sidecar_entry_for_mesh_index bounds behavior
print_range 1090 1165
# 3) Inspect any _load_ifc_semantic_sidecar helper near usage
rg -n "def _load_ifc_semantic_sidecar|_load_ifc_semantic_sidecar\\(" "$FILE" || true
# Try a reasonable nearby window around the found function if it exists
# (If rg output shows line numbers, you can re-run with updated ranges.)Repository: monkey1sai/AI-BIM-governance
Length of output: 293
🏁 Script executed:
#!/bin/bash
set -euo pipefail
FILE="bim-streaming-server/source/extensions/ezplus.bim_review_stream.messaging/ezplus/bim_review_stream/messaging/ifc2usdc_powershell_adapter.py"
python3 - <<'PY'
from pathlib import Path
file = Path("bim-streaming-server/source/extensions/ezplus.bim_review_stream.messaging/ezplus/bim_review_stream/messaging/ifc2usdc_powershell_adapter.py")
ranges = [
(820, 960),
(960, 1120),
(1120, 1175),
(1175, 1225),
]
lines = file.read_text(encoding="utf-8", errors="replace").splitlines()
for a,b in ranges:
print(f"\n==== {file}:{a}-{b} ====")
for i in range(a-1, min(b, len(lines))):
print(f"{i+1:5d}: {lines[i]}")
PYRepository: monkey1sai/AI-BIM-governance
Length of output: 17173
🏁 Script executed:
#!/bin/bash
set -euo pipefail
# Find computeSemanticReady implementation(s)
rg -n --hidden --no-ignore-vcs \
"function computeSemanticReady|computeSemanticReady\\(" \
. --glob '*.ts' --glob '*.tsx' --glob '*.js' --glob '*.jsx' --glob '*.py' --glob '*.md' --max-count 50
# Find semantic_mapping_fidelity usage
rg -n --hidden --no-ignore-vcs \
"semantic_mapping_fidelity" \
. --glob '*.ts' --glob '*.tsx' --glob '*.js' --glob '*.jsx' --glob '*.py' --glob '*.md' --max-count 80Repository: monkey1sai/AI-BIM-governance
Length of output: 23655
🏁 Script executed:
#!/bin/bash
set -euo pipefail
python3 - <<'PY'
from pathlib import Path
paths = [
Path("web-viewer-sample/src/utils/triReady.ts"),
Path("bim-streaming-server/tests/test_host_native_conversion_service.py"),
]
for p in paths:
print(f"\n===== {p} =====")
text = p.read_text(encoding="utf-8", errors="replace").splitlines()
# Print the most relevant window for triReady.ts
if p.name == "triReady.ts":
# find computeSemanticReady
idx = next((i for i,l in enumerate(text) if "computeSemanticReady" in l), None)
if idx is None:
print("computeSemanticReady not found")
else:
start=max(0, idx-20); end=min(len(text), idx+60)
for i in range(start, end):
print(f"{i+1:5d}: {text[i]}")
else:
# Print around the sidecar join / ordinal join notes
keys = ["ordinal join", "mesh-index", "sidecar entries", "semantic_mapping_fidelity", "entries, otherwise"]
# pick first matching line
matches = [(i,l) for i,l in enumerate(text) if any(k in l for k in keys)]
if matches:
i,_ = matches[0]
start=max(0, i-40); end=min(len(text), i+120)
for j in range(start, end):
print(f"{j+1:5d}: {text[j]}")
else:
print("No matching test comments found; dumping first 60 lines as fallback:")
for i in range(60):
if i>=len(text): break
print(f"{i+1:5d}: {text[i]}")
PYRepository: monkey1sai/AI-BIM-governance
Length of output: 9100
🏁 Script executed:
#!/bin/bash
set -euo pipefail
python3 - <<'PY'
from pathlib import Path
file = Path("bim-streaming-server/tests/test_host_native_conversion_service.py")
lines = file.read_text(encoding="utf-8", errors="replace").splitlines()
def show(a,b):
print(f"\n==== {file}:{a}-{b} ====")
for i in range(a-1, min(b, len(lines))):
print(f"{i+1:5d}: {lines[i]}")
show(1480, 1565)
show(1565, 1705)
show(1705, 1825)
PYRepository: monkey1sai/AI-BIM-governance
Length of output: 16345
🏁 Script executed:
#!/bin/bash
set -euo pipefail
FILE="openspec/specs/streaming-ifc-usdc-conversion-authority/spec.md"
python3 - <<'PY'
from pathlib import Path
file = Path("openspec/specs/streaming-ifc-usdc-conversion-authority/spec.md")
lines = file.read_text(encoding="utf-8", errors="replace").splitlines()
for a,b in [(330,420),(350,390),(410,445)]:
print(f"\n==== {file}:{a}-{b} ====")
for i in range(a-1, min(b, len(lines))):
print(f"{i+1:5d}: {lines[i]}")
PYRepository: monkey1sai/AI-BIM-governance
Length of output: 9640
Clarify ordinal alignment mismatch behavior and quality/ready semantics.
The spec’s “best-effort ordinal” mesh prim ↔ sidecar entries alignment (sidecar entries order vs USD mesh prim enumeration order) lacks defined observable outcomes for misalignment/count mismatch. In Ifc2UsdcPowershellConverterAdapter._enumerate_usd_stage, all UsdGeom.Mesh prims are used for the ordinal join, _sidecar_entry_for_mesh_index silently returns None when mesh_index is out of range, and supplementation is skipped without diagnostics/logging. If at least one entry is supplemented, quality_metrics.semantic_mapping_fidelity becomes "usd_enumeration_with_ifc_sidecar_supplement", and coverage_status resolves to "pass" because source_count is derived from len(mapping_items) (so partial coverage from ordinal mismatch can still look like full success). Add spec language defining expected behavior when:
- sidecar entries count ≠ mesh prim count (shorter/longer),
- extra/non-IFC mesh prims exist (order shift),
- mapping completeness should affect
coverage_statusand viewer"Semantic ready".
Also, the new semantic_mapping_fidelity value is handled generically by web-viewer-sample’s computeSemanticReady (non-empty string + mapping_has_ifc_type/name), so backward compatibility for the viewer does not depend on enumerating specific fidelity strings.
🤖 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/streaming-ifc-usdc-conversion-authority/spec.md` around lines
365 - 367, Update the spec to define observable behavior for ordinal
misalignment: state that _enumerate_usd_stage and _sidecar_entry_for_mesh_index
MUST record diagnostics/logging when sidecar index is out-of-range or an entry
is skipped, require that coverage_status in quality_metrics is computed against
the total number of USD mesh prims (not just supplemented mapping_items) so
mapped_count < total_prims yields "warn"/"fail" appropriately, and specify how
semantic_mapping_fidelity values (e.g.,
"usd_enumeration_with_ifc_sidecar_supplement") should influence viewer readiness
(align with computeSemanticReady by requiring mapping_has_ifc_type and
mapping_has_ifc_name plus non-empty fidelity) and describe expected behavior for
extra/non-IFC mesh prims (they may be skipped but must be reported and reduce
coverage).
PR Review Agent Summary
Blockers
Warnings
Validation Commands
Checks
Human Review Notes
|
Summary
cea66e0) merged 後同步 OpenSpec archiveopenspec/changes/archive/2026-05-28-streaming-server-ifcopenshell-semantic-sidecar-pass/openspec/specs/streaming-ifc-usdc-conversion-authority/spec.md(+1 ADD requirement「HOOPS happy path SHALL be augmented by an IfcOpenShell semantic sidecar pass」+ 7 scenarios)變更內容
Verify
npx openspec validate --specs --strictTest plan
docs/evidence/streaming-server-ifcopenshell-semantic-sidecar-pass/🤖 Generated with Claude Code
Summary by CodeRabbit