Open-source Revit MCP server: let Claude and other AI assistants read and edit BIM models, with human approval on every change.
Python aecai-agentsautodeskautomationbimclaudeifcmcpmcp-servermodel-context-protocolnavisworksrevitrevit-addinrevit-apirhino
docs: add product vision, backlog, and architecture plans
A. Sam Mohammad4ccd7fc3de75
diff --git a/docs/product/AEC_MODEL_BRIDGE_PRODUCT_VISION.md b/docs/product/AEC_MODEL_BRIDGE_PRODUCT_VISION.mdnew file mode 100644index 0000000..35d5bc9--- /dev/null+++ b/docs/product/AEC_MODEL_BRIDGE_PRODUCT_VISION.md@@ -0,0 +1,83 @@+# AEC Model Bridge — Product Vision++> Canonical product name: **AEC Model Bridge** (repo `Sam-AEC/aec-model-bridge`).+> "AEC Omni-Bridge" is legacy internal branding — permitted only as the name of the *multi-app orchestration vision* (Rhino/Navisworks/PowerBI switches), never as the product name. See `DECISIONS_AND_RISKS.md` D-001.++## 1. Product definition++AEC Model Bridge is a **plugin-style AEC productivity platform** that connects live authoring tools (Revit first; Rhino, Navisworks, Power BI as switches) to AI agents through MCP — with **native BIM semantics as the source of truth** and a **human approval layer** between AI intent and model mutation.++Concretely, it is three layers that already partially exist in this repo:++1. **Switches** — thin C# add-ins inside each host app (`packages/revit-bridge-addin`, `rhino-bridge-addin`, `navisworks-bridge-addin`, `powerbi-bridge-tool`) exposing HTTP `/execute` on the host's API thread.+2. **Hub** — the Python MCP server (`packages/mcp-server-revit`, `mcp_server.py`) with a provider registry, ~170 tools, async jobs, identity mapping, semantic graph, and exporters.+3. **Surface** — Claude Code / any MCP client today; a **dockable in-Revit panel with chat, approval queue, and run log** as the MVP product surface for normal Revit users.++## 2. Target users++| Persona | Today's pain | What they get |+|---|---|---|+| **BIM coordinator / manager** (primary MVP) | Repetitive QA, parameter cleanup, sheet drudgery; Dynamo scripts nobody maintains | Ask the model questions, run health checks, approve bulk fixes from a panel — no code |+| **Façade / computational designer** (Sam's own persona) | Rhino→Revit means dumb DirectShapes or manual rebuilds | Semantic roundtrip: GH panel data → native curtain panels/adaptive components |+| **Automation engineer / BIM developer** | Every firm rebuilds the same Revit-API plumbing | Stable MCP tool surface + module SDK; script in Python against a live model |+| **Project engineer / QA lead** | Model quality invisible until clash day | Rule-based validation → issue lists → Excel/Power BI dashboards |++## 3. Core user problems++1. **BIM data is trapped.** Answering "how many fire-rated doors on level 3 lack a rating parameter?" requires a schedule, a filter, and 20 minutes — or a developer.+2. **Automation has a cliff.** Below the cliff: manual clicking. Above it: Dynamo graphs and pyRevit scripts that rot. Nothing in between speaks natural language.+3. **Cross-tool workflows are lossy.** Rhino→Revit, Revit→Navisworks, Revit→Power BI each drop semantics; every firm hand-rolls the glue.+4. **AI can't be trusted with models.** No mainstream tool lets an LLM near a production RVT because there is no approval, audit, or rollback layer. That layer *is* the product.++## 4. Why this matters / why it is different++| Alternative | What it is | Why AEC Model Bridge is different |+|---|---|---|+| **Dynamo** | Visual programming per-task | We are conversational + persistent tooling, not per-task graphs; Dynamo becomes an *integration target* (Phase 12) |+| **pyRevit** | Script framework + toolbar for Python devs | pyRevit serves scripters; we serve non-programmers via AI + approval UI, and expose a *stable machine interface* (MCP) pyRevit lacks |+| **Speckle** | Data platform / versioned object transport | Speckle moves data between apps; we *act* inside apps. Speckle is one of our transports (17 `speckle_*` tools already exist) |+| **Rhino.Inside.Revit** | Rhino/GH runtime inside Revit process | RiR is a geometry pipe; we add the semantic layer that turns GH output into *native* Revit elements, and RiR is an execution backend option (Phase 12) |+| **Ordinary Revit add-ins** | Fixed-function buttons | We are a *platform*: module registry, AI surface, cross-app orchestration |+| **Ordinary MCP servers** | Tool lists bolted to one API | We add the things production BIM needs: mutation metadata, approval queue, transaction discipline, identity mapping across apps, semantic graph, audit trail |++**Moat in one sentence:** the only tool where an AI agent can safely *read, reason about, and — with human approval — modify* a live Revit model using native elements, and carry those semantics across Rhino, Navisworks, IFC, Speckle, and Power BI.++## 5. The plugin-style app vision++Not a script collection. The user experience:++- **Ribbon tab "AEC Bridge"** (exists today with Connection/Tools panels) grows to ~5 product commands: *Open Panel, Run Health Check, Review Pending Actions, Reports, Settings*.+- **Dockable panel** (WPF + WebView2): chat with the model, see proposed actions as structured cards (element counts, parameter diffs), **Approve / Reject / Approve-all-similar**, live run log.+- **Modules** (see `PLUGIN_MODULE_SYSTEM.md`): Model Inspector, QA/QC Checker, Parameter Manager, Report Generator… discovered from a registry, each declaring its commands, permissions, and schemas.+- **Everything auditable**: every mutation is a logged, transaction-named, reversible action tied to the approving user.++## 6. Role of each layer++- **AI agents** — intent → plan → tool calls. Agents *propose*; they never mutate silently. Long tasks run through the existing `JobManager` (`job_status`/`job_cancel`).+- **MCP tools** — the stable contract. Today: 100 `revit_*`, 19 `rhino_*`, 7 `ifc_*`, 7 `graph_*`, 17 `speckle_*`, 12 `autodesk_*`, 3 `aec_*` mapper, 3 exporter, 2 job tools. Gap to close: `is_mutating`/`execution_mode` metadata on the Python side (C# already has it via `[BridgeCommand]`).+- **Revit-native automation** — all mutations happen as native elements inside named `Transaction`s on the API thread via the existing `ExternalEvent`/`CommandQueue` path. **DirectShape only for preview or explicit fallback** — never the deliverable.++## 7. Top daily-dependence workflows++Ranked by (frequency × pain × feasibility) — full specs in `AEC_WORKFLOW_CATALOG.md`:++1. **Ask the model** — natural-language Q&A over elements/params/levels/views (read-only; builds trust).+2. **Model health check** — one click → rule-based QA report with clickable element IDs.+3. **Bulk parameter ops with approval** — preview diff → approve → transactional apply → rollback available.+4. **Sheet/view automation** — batch sheets from CSV, renumber, apply templates (tools already exist: `revit_batch_create_sheets_from_csv`, `revit_renumber_sheets`, `revit_apply_view_template`).+5. **BIM report export** — model → SQLite/Excel/Power BI (exporter + PowerBI switch).+6. **Façade roundtrip** (flagship, post-MVP) — GH diagrid → semantic panels → native curtain panels.++## 8. MVP direction++Ship the **three data workflows** (inspect → validate → fix) on **one semantic layer** with the **approval panel**, targeting Revit 2024 (net48) + 2025/26 (net8) — multi-targeting already exists in `RevitBridge.csproj`. Detail in `MVP_EXECUTION_PLAN.md`.++Explicitly **not** MVP: façade configurator, Navisworks/PowerBI registration fixes beyond health, orchestrator/recipes, cloud/remote MCP, marketplace.++## 9. Long-term direction++- **Phase-2 flagship:** façade configurator roundtrip (Rhino/GH → semantic panel schema → native Revit), proving the semantic layer publicly.+- **Orchestrator** (roadmap Phase C): YAML recipes spanning switches — "export Revit → clash in Navisworks → dashboard in Power BI".+- **Data plane** (roadmap Phase D): Parquet/DuckDB, `.pbit` templates, IDS validation.+- **Open-core:** GPL platform + commercial modules/enterprise features (dual license already in `LICENSING.md`; strategy details stay in the private strategy doc, not here).+- **Ecosystem:** module marketplace, switch SDK for third-party hosts (Archicad, Tekla — roadmap Phase G).diff --git a/docs/product/AEC_WORKFLOW_CATALOG.md b/docs/product/AEC_WORKFLOW_CATALOG.mdnew file mode 100644index 0000000..ebd7e20--- /dev/null+++ b/docs/product/AEC_WORKFLOW_CATALOG.md@@ -0,0 +1,170 @@+# AEC Workflow Catalog++Each workflow lists: user story · input → output · Revit objects · MCP tools (existing tool names verbatim; **[NEW]** = to build) · modules · UI · safety · failure cases · validation · MVP vs advanced. Modules refer to `PLUGIN_MODULE_SYSTEM.md`; safety gate refers to `PLUGIN_APP_ARCHITECTURE.md` §4.++Tiers: **T1** = MVP (read + gated write), **T2** = flagship/post-MVP, **T3** = later phases.++---++## W1 — Ask AI about the current model (T1)++- **Story:** "As a BIM coordinator I ask 'how many doors on Level 3 have no fire rating?' and get an answer with clickable element IDs in under a minute."+- **In:** natural-language question. **Out:** answer + element UniqueId list + optional saved query.+- **Revit objects:** any FilteredElementCollector-reachable element; Levels, Categories, Parameters.+- **Tools:** `revit_get_document_info`, `revit_list_elements`, `revit_get_elements_by_type`, `revit_get_element_parameters`, `revit_list_levels`, `revit_get_categories`, `snapshot_query` **[NEW]** (query the semantic snapshot instead of N round-trips).+- **Module:** Model Inspector. **UI:** panel chat; results as element chips → click = `revit_set_selection` + zoom.+- **Safety:** read-only — no gate. Token guard: cap result payloads; large queries via snapshot, not element-by-element.+- **Failures:** no doc open (`revit_health` first); stale snapshot (show snapshot age, offer refresh); param name ambiguity (ask user).+- **Validation:** cross-check counts against a Revit schedule on the test model.+- **MVP:** count/filter/list on snapshot. **Advanced:** multi-hop questions via `graph_query_relations`, saved queries as QA rules.++## W2 — Inspect selected elements (T1)++- **Story:** "I select elements and ask 'what is this and what's wrong with it?'"+- **In:** live selection. **Out:** type/family/host/level/params card + rule findings.+- **Tools:** `revit_get_selection`, `revit_get_element_parameters`, `revit_get_element_type`, `revit_get_element_bounding_box`, `revit_get_warnings`.+- **Module:** Selection Tools + Model Inspector. **UI:** ribbon "Inspect Selection" + panel card. **Safety:** read-only.+- **Failures:** empty selection; view-specific elements; huge selections (summarize, don't enumerate).+- **Validation:** matches Revit Properties palette on test model.+- **MVP:** property card. **Advanced:** per-selection QA findings, "fix" suggestions feeding W5.++## W3 — Extract model groups (T1)++- **Story:** "List all model groups, members, and instance counts so I can audit group hygiene."+- **In:** none/filter. **Out:** group table (name, instances, member categories, nesting).+- **Revit objects:** `Group`, `GroupType`. **Tools:** `revit_list_elements` (OST_IOSModelGroups), `revit_get_group_members`.+- **Module:** Model Inspector. **UI:** panel table + CSV export. **Safety:** read-only.+- **Failures:** nested groups (recurse with depth cap); groups in links (out of scope, flag).+- **MVP:** table. **Advanced:** duplicate-group detection, group-vs-group diff.++## W4 — Manipulate model groups safely (T1, gated)++- **Story:** "Rename/ungroup/convert selections to groups in bulk without corrupting instances."+- **In:** group selection + operation. **Out:** applied changes + audit entries.+- **Tools:** `revit_create_group`, `revit_ungroup`, `revit_convert_to_group`, `revit_move_element`, `plan_actions` **[NEW]**.+- **Module:** Selection Tools. **UI:** plan cards in approval queue. **Safety:** ActionPlan required; ungroup flagged destructive; per-plan TransactionGroup.+- **Failures:** group instances in other views/phases (report affected count in plan); attached details lost on ungroup (warn).+- **Validation:** instance counts before/after; Revit undo restores exactly.+- **MVP:** rename/ungroup with plan preview. **Advanced:** re-group after edit, group content sync.++## W5 — Read & update parameters (T1, gated — killer workflow #3)++- **Story:** "Set `FireRating='60'` on all EI-60 doors; I see the before/after diff, approve, and can roll back."+- **In:** filter + param + value (or CSV mapping). **Out:** diff table → applied plan → audit + inverse plan.+- **Tools:** `revit_get_element_parameters`, `revit_get_parameter_value`, `revit_set_parameter_value`, `revit_batch_set_parameters`, `revit_batch_set_parameters_by_filter`, `revit_get_type_parameters`, `revit_set_type_parameter`, `plan_actions` **[NEW]**.+- **Module:** Parameter Manager. **UI:** diff grid (element, param, before → after) with per-row/all approve.+- **Safety:** capture before-values (enables inverse plan); read-only params and type-vs-instance mismatches blocked at plan time; storage-type validation (string/double/ElementId); unit handling via spec type.+- **Failures:** param not bound on category; workshared element owned by other user (report, skip, list); formula-driven params (read-only).+- **Validation:** re-read after apply == intended; undo restores before-values on test model.+- **MVP:** filter-based batch set with diff+approval. **Advanced:** CSV/Excel roundtrip, shared-param creation (`revit_create_shared_parameter`), rule-driven fixes from W7.++## W6 — Validate families & types (T1)++- **Story:** "Flag families that break our standard: naming, duplicate types, oversized, in-place."+- **In:** ruleset (naming regex, size caps, banned categories). **Out:** findings list per family/type.+- **Tools:** `revit_list_families`, `revit_get_type_parameters`, `revit_get_elements_by_type`, `revit_edit_family` (advanced), `snapshot_query` **[NEW]**.+- **Module:** Family/Type Mapper + QA/QC Checker. **UI:** findings table, severity-grouped. **Safety:** read-only (fixes route through W5/W9 plans).+- **Failures:** family size requires doc extraction (defer to advanced); in-place families lack types (special-case).+- **MVP:** naming + duplicate-type + in-place count checks. **Advanced:** type-catalog compliance, `revit_replace_family_type` remediation plans.++## W7 — Model health checks: walls/doors/windows/rooms/levels/views/sheets/schedules (T1 — killer workflow #2)++- **Story:** "One click, model health report in 2 minutes: unplaced rooms, unnamed views, doors without hosts, duplicate marks, views-not-on-sheets…"+- **In:** ruleset id (YAML rule packs). **Out:** findings report (severity, rule, elements, suggested fix).+- **Revit objects:** Walls, Doors, Windows, Openings, Rooms, Levels, Views, ViewSheets, Schedules, Warnings.+- **Tools:** snapshot + `revit_get_warnings`, `revit_list_views`, `revit_list_sheets`, `revit_get_schedule_data`, `revit_list_levels`, `graph_audit_disconnected`, `graph_audit_clashes`; `run_qa_ruleset` **[NEW]**.+- **Module:** QA/QC Checker. **UI:** ribbon "Run Health Check" → progress (JobManager) → report in panel; export via W8.+- **Safety:** read-only; suggested fixes become ActionPlans only on user click.+- **Failures:** huge models → async job with progress (`job_status`); rules referencing unbound params → rule skipped + noted, not crash.+- **Validation:** seeded test model with known defects → rule pack finds exactly those (golden findings file in CI).+- **MVP:** ~15 core rules (unplaced/unenclosed rooms, unnamed/duplicate views, views not on sheets, doors/windows without host, duplicate marks, untagged doors, warning count by type, empty schedules, model group count sanity, unused families threshold). **Advanced:** firm-custom rule packs, IDS-based checking, scheduled runs, trend tracking across snapshots.++## W8 — Generate BIM reports / export structured data (T1)++- **Story:** "Export model + QA findings to SQLite/Excel; my Power BI dashboard refreshes from it."+- **In:** snapshot + findings. **Out:** `.sqlite` / `.xlsx` / (later `.parquet`).+- **Tools:** `exporter_to_sqlite`, `exporter_graph_to_sqlite`, `exporter_db_health`, `export_excel` **[NEW]** (openpyxl), `revit_get_schedule_data`.+- **Module:** Report Generator + Data Exporter. **UI:** ribbon "Reports" → format + destination (workspace-sandboxed paths).+- **Safety:** writes only inside workspace sandbox (exists); redaction on paths/PII (exists).+- **Failures:** file locked by Excel/PBI (retry w/ timestamped name); schema drift between exports (schema_version column).+- **MVP:** SQLite + Excel with fixed schema. **Advanced:** Parquet/DuckDB, `.pbit` template auto-refresh, scheduled exports.++## W9 — QA/QC issue lists (T1)++- **Story:** "Findings become a tracked issue list I can assign, mark resolved, and re-check."+- **In:** W7 findings. **Out:** issue records (id, rule, elements, status, assignee) persisted per document GUID; re-run auto-resolves fixed issues.+- **Tools:** `run_qa_ruleset` **[NEW]**, issue store **[NEW]** (SQLite in workspace), `autodesk_data_create_issue` (advanced → ACC), `speckle_send_object` (advanced).+- **Module:** QA/QC Checker. **UI:** issues tab in panel; click issue → select+zoom elements.+- **Safety:** issue store is external metadata — no model writes.+- **Failures:** elements deleted since finding (mark orphaned via UniqueId miss); doc SaveAs changes GUID (re-anchor prompt).+- **MVP:** local issue store + re-check lifecycle. **Advanced:** ACC Issues / BCF export, assignment via email.++## W10 — Automate view/sheet workflows (T1, gated)++- **Story:** "Create 40 sheets from CSV, place plans, populate title blocks, renumber — as one approved plan."+- **Tools (all exist):** `revit_batch_create_sheets_from_csv`, `revit_create_sheet`, `revit_place_viewport_on_sheet`, `revit_populate_titleblock`, `revit_list_titleblocks`, `revit_renumber_sheets`, `revit_duplicate_sheet`, `revit_create_floor_plan_view`, `revit_apply_view_template`, `revit_get_view_templates`.+- **Module:** View/Sheet Automator. **UI:** CSV picker + preview table (sheet number/name/view/titleblock) → approve.+- **Safety:** duplicate-sheet-number pre-check at plan time; deletes (`revit_delete_sheet`) always destructive-flagged.+- **Failures:** titleblock family missing (halt plan with fix hint); viewport placement collisions (grid heuristic + report).+- **Validation:** sheet count/numbers match CSV exactly; undo removes all created sheets (TransactionGroup).+- **MVP:** CSV → sheets + titleblock params. **Advanced:** auto viewport layout, revision management (`revit_get_revision_sequences`), print/export sets.++## W11 — Façade configurator (T2 — flagship)++- **Story:** "I tune a diagrid façade in Rhino/GH; approved panel layout lands in Revit as native curtain panels/adaptive components with type mapping and parameters — not DirectShape."+- **In:** GH/Rhino panel geometry + `facade_zone` semantic spec (see `SEMANTIC_BIM_DATA_MODEL.md` §facade). **Out:** native Revit elements + identity mappings + variant record.+- **Revit objects:** Curtain systems/panels, adaptive component families, mullions, reference points.+- **Tools:** `rhino_run_python`, `rhino_generate_diagrid_tower`, `rhino_get_scene`, `aec_register_mapping`, `aec_translate_id`, `revit_place_family_instance`, `revit_batch_set_parameters`, `facade_apply_zone` **[NEW]** (semantic spec → placement plan); preview via DirectShape **only** with visible "PREVIEW" marker + auto-cleanup.+- **Modules:** Façade Configurator + Rhino Bridge. **UI:** variant cards (panel counts, type breakdown, deltas vs current) → approve variant.+- **Safety:** variant apply = one TransactionGroup; re-apply diffs against mapped identities (update/create/delete sets shown before approval); deletes always itemized.+- **Failures:** adaptive family missing (block with load instruction); panel outside tolerance of host face (report skipped panels — never silently skip: count must reconcile, cf. the 1476-panel discipline in CLAUDE.md); unit mismatches (metres end-to-end, exists in Rhino bridge).+- **Validation:** panel count Rhino == Revit == mapping table; roundtrip re-export matches within tolerance.+- **MVP(T2):** one zone, one adaptive family, apply + re-apply diff. **Advanced:** multi-zone, type optimization (panel similarity clustering), GH live-link via `g1_*`/Rhino.Inside.++## W12 — Rhino.Inside.Revit workflows (T2)++- **Story:** "Run GH definitions against live Revit geometry inside the Revit process; results land as native elements through the same approval gate."+- **Method:** RiR as *execution backend* — GH definition emits our semantic spec (JSON), hub turns it into an ActionPlan. Custom GH components **[NEW]** wrap hub endpoints.+- **Tools:** `facade_apply_zone` **[NEW]**, `aec_*` mapper; RiR-side components **[NEW]**.+- **Safety:** identical gate — RiR gets no write bypass. **Failures:** RiR version/Rhino version matrix (document supported pairs); unit system differences.+- **MVP(T2):** one exemplar GH definition → semantic spec → native elements. **Advanced:** bidirectional (Revit selection → GH input).++## W13 — Grasshopper/Dynamo workflows (T2/T3)++- **GH (T2):** via Rhino bridge `rhino_run_python` + existing MCP `g1_*` canvas tools; GH exports semantic spec, not meshes. Existing scratch assets (`facade_gh_builder.py`, `facade_system.gh`) become the exemplar.+- **Dynamo (T3):** Dynamo package **[NEW]** with ZeroTouch nodes calling hub HTTP endpoints; same spec, same gate. `scratch/facade_dyn_builder.py` is prior art.+- **Failures:** graph solves mid-edit producing partial specs → spec must carry `complete: true` flag; version pinning of node packages.+- **MVP(T2):** GH exemplar. **Advanced:** Dynamo node package, graph-as-module registration.++## W14 — Semantic roundtrip back to Revit (T2 — the differentiator)++- **Story:** "External tools edit *data about* elements (a JSON of walls/panels/params); the bridge reconciles it into the live model as native edits."+- **In:** semantic delta document (schema §roundtrip). **Out:** reconciliation plan (create/update/delete/skip) → approved apply → updated mappings.+- **Tools:** `snapshot_export` **[NEW]**, `snapshot_diff` **[NEW]**, `plan_actions` **[NEW]**, `aec_translate_id`, all relevant `revit_create_*`/`revit_set_*`.+- **Safety:** three-way awareness — delta vs snapshot vs live model; if live model changed since snapshot, conflicting actions are flagged, never auto-overwritten.+- **Failures:** UniqueId misses (element deleted) → orphan report; type not loadable → blocked action with hint.+- **Validation:** apply → re-export → diff == empty.+- **MVP(T2):** parameters + placement of known families. **Advanced:** geometry-bearing types (walls by curve, floors by boundary), variant management.++## W15 — IFC / Navisworks / Speckle workflows (T2/T3)++- **IFC (T1-adjacent, tools exist):** open IFC alongside RVT — `ifc_get_spatial_structure`, `ifc_query_elements`, `ifc_get_properties`, `ifc_validate`; map to Revit via `aec_register_mapping` (GlobalId ↔ UniqueId, mapper exists). MVP: IFC Q&A + Revit-vs-IFC param comparison.+- **Navisworks (T2):** register `NavisworksProvider` in shipped hub **[fix]**, widen provider to the 16 C# commands (model tree, viewpoints, `navis.run_clash_test`, `navis.get_clash_results`); clash results → identity mapper → Revit element selection ("show me clash #12 in Revit"). Failure: clash GUID ↔ Revit UniqueId mapping fidelity — validate on test pair.+- **Speckle (T2, 17 tools exist):** publish semantic snapshots as Speckle versions (`speckle_publish_version`), receive external edits → W14 reconciliation. Failure: OAuth expiry mid-job (refresh flow exists).++## W16 — Excel / Power BI workflows (T1 Excel, T2 PBI)++- **Story:** "Model data and QA trends in the tools management already uses."+- **Excel (T1):** `export_excel` **[NEW]** — elements/params/findings sheets; CSV param roundtrip back through W5 plans.+- **Power BI (T2):** wire orphaned `PowerBIProvider` **[fix]** → `powerbi_execute_dax` against live PBI Desktop (:3006 external tool exists in C#); or file-based: SQLite/Parquet + provided `.pbit` template (roadmap Phase D).+- **Failures:** ADOMD connection lifetime (PBI restarts change server/db args — re-handshake); Excel file locks.+- **MVP:** Excel export. **Advanced:** DAX Q&A ("ask your dashboard"), auto-refresh pipeline, DuckDB layer.++---++## Cross-cutting requirements++1. Every T1 write workflow goes through **ActionPlan → approval → named transaction → audit → inverse plan** without exception.+2. Every workflow must work on the **canonical test model** (Phase 17) with golden outputs in CI.+3. Every workflow's tool calls appear in `tools-generated.md` with correct mutation metadata.+4. Payload discipline: snapshot-first querying; never stream 50k elements through chat context.diff --git a/docs/product/AI_AGENT_SWARM_PLAN.md b/docs/product/AI_AGENT_SWARM_PLAN.mdnew file mode 100644index 0000000..b7c1292--- /dev/null+++ b/docs/product/AI_AGENT_SWARM_PLAN.md@@ -0,0 +1,48 @@+# AI Agent Swarm Plan++How Claude Code agents build this product in parallel without stepping on each other. Ground rules first, then the roster.++## Ground rules (all agents)++- **Source of truth:** `docs/product/*` (this package) for *what to build*; `docs/system-blueprint-and-workflows.md` + ADRs for *how the system works*; `SCAFFOLDING_TASK_LIST.md` for *task ownership*.+- **Conflict avoidance = ownership by path.** Each agent has "allowed edit areas"; editing outside them requires the orchestrating session's sign-off. Two agents never own the same path in the same phase.+- **Worktrees** (`EnterWorktree` / `isolation: worktree`): mandatory for any agent touching code in parallel with another code agent; unnecessary for single-agent doc work. C# and Python agents can share a branch only if their paths are disjoint (`packages/revit-bridge-addin` vs `packages/mcp-server-revit`).+- **Handover format (uniform):** every agent ends with: *changed files · commands run + results (build/test output verbatim) · contracts touched (tool names, schemas) · open questions · next task recommendation*. Written to the task's phase section or `NEXT_AGENT_HANDOVER.md`.+- **Required checks before "done":** Python — `pytest` + `ruff`; C# — `dotnet build -c Release` for **net48 and net8** targets; docs — no broken relative links; contract changes — regenerate `docs/tools-generated.md`.+- **Human approval required for:** deleting/archiving any existing file (audit §9 list), changing a shipped tool's name/schema (breaking change), flipping runtime defaults (LegacyMode, approval_mode), anything touching `LICENSES/`, `LICENSING.md`, `TRADEMARKS.md`, publishing/pushing, and any git history rewrite.+- **Model/effort:** exploration and doc-summarization agents run cheap (Explore/haiku-class); architecture and Revit-API-threading work runs at highest reasoning. Don't spawn an agent for work smaller than its briefing.++## Roster++| Agent | Responsibility | Inputs | Outputs | Allowed edit areas |+|---|---|---|---|---|+| **Repo Audit** | Keep `CURRENT_REPO_AUDIT.md` true; verify claims vs code after each phase; regen tool docs | whole repo (read) | audit doc updates, drift reports | `docs/product/CURRENT_REPO_AUDIT.md`, `docs/tools-generated.md` |+| **Product Architect** | Guard vision/architecture coherence; arbitrate cross-agent contract disputes; own ADRs | product package, ADRs | ADR updates, decision entries | `docs/product/*`, `docs/000*.md`, `DECISIONS_AND_RISKS.md` |+| **Revit API** | C# add-in: snapshot extraction command, transaction discipline, Contract v2 default, dockable pane host, dead-tree resolution | `PLUGIN_APP_ARCHITECTURE.md`, `SEMANTIC_BIM_DATA_MODEL.md`, `BridgeCommandFactory.cs` | C# code + `docs/revit-addin-lifecycle.md` updates | `packages/revit-bridge-addin/**` |+| **MCP Tooling** | Hub: tool metadata, approval-gate tools, module provider adapter, retire legacy `server.py`/`tools/`, register Navisworks | hub source, module spec | Python code + tests | `packages/mcp-server-revit/src/**`, `tests/**` |+| **Plugin App** | Module registry, built-in MVP modules (inspector, params, qaqc, reports, sheets, selection) | `PLUGIN_MODULE_SYSTEM.md`, workflow catalog | `modules/**` + manifests + tests | `packages/mcp-server-revit/src/revit_mcp_server/modules/**` |+| **Semantic BIM Data** | Snapshot/delta/zone schemas, diff engine, reconciliation, mapper extensions | `SEMANTIC_BIM_DATA_MODEL.md` | JSON schemas, `semantic/` package, tests | `packages/mcp-server-revit/src/revit_mcp_server/semantic/**`, `schemas/**` |+| **UI/UX** | WebView2 panel app (chat, plan cards, findings, run log), ribbon layout | architecture §2, workflow UI specs | panel HTML/JS/CSS + C# pane host (coordinate w/ Revit API agent) | `packages/revit-bridge-addin/src/UI/**`, `panel/**` |+| **Integration** | Speckle/APS/IFC/PowerBI wiring per `INTEGRATION_STRATEGY.md`; Excel exporter | strategy doc, provider code | provider updates, `export_excel` | `providers/cloud.py`, `providers/ifc.py`, `providers/powerbi.py`, `providers/exporter.py` |+| **Rhino/Grasshopper** | Façade zone spec exporter, bridge Contract v2, RiR exemplar, GH `g1_*` playbooks | `rhino-bridge-addin`, W11–W13, `/rhino-skills` | C# bridge updates, GH defs, scratch→product promotion | `packages/rhino-bridge-addin/**`, `modules/facade_configurator/**` |+| **QA/QC BIM** | Rule engine + core rule pack, issue store, golden findings; the domain expert for what rules matter | W7/W9, rule format | `rules/core/**`, rule engine in qaqc module | `modules/qaqc_checker/**` |+| **Testing** | Canonical test model script, e2e harness (extends `test_e2e.py`), CI matrix, contract tests for module metadata | all contracts | `tests/**`, `.github/workflows/**`, fixtures | `tests/**`, `.github/**`, `fixtures/**` |+| **Documentation** | User docs, tutorials, rewrite stale `docs/security.md`, fix README links/CLAUDE.md ports, MkDocs site | audit §4 stale list | docs | `docs/**` (not `docs/product/` — Architect owns), `README.md`, `CLAUDE.md` |+| **Release** | Version reconciliation (1.1.0→CHANGELOG parity), installers, `server.json`, marketplace listings | `docs/build-and-install-scripts.md`, `marketplaces.md` | scripts, installer defs, release notes | `scripts/**`, `dist/` config (not artifacts), `server.json`, `CHANGELOG.md` |+| **Security/Safety** | Approval gate review, permission enforcement tests, redaction coverage, bearer-token default flip, threat model refresh | ADR 0002, gate code | security tests, `docs/security.md` (with Documentation agent), threat notes | `tests/test_security*.py`, review-only elsewhere |++## Parallelization map++- **Wave 1 (independent):** Revit API (snapshot command, C#) ∥ MCP Tooling (metadata + gate, Python) ∥ Documentation (stale-doc cleanup) ∥ Testing (test model script). Different path ownership → same branch or worktrees, no conflicts.+- **Wave 2 (after gate + snapshot):** Plugin App (modules) ∥ UI/UX (panel) ∥ Semantic BIM Data (diff/reconcile) — modules mock the panel; panel mocks modules via the command-list endpoint contract fixed in Wave 1.+- **Wave 3:** QA/QC rules ∥ Integration wiring ∥ Release packaging.+- **Contract freeze points:** tool metadata shape (end W1), `module.json` schema (start W2), snapshot schema (start W2). After a freeze, changes go through Product Architect + human approval.+- **Merge order:** hub contracts → C# → modules → UI. The orchestrating session (main Claude Code context) merges; agents never merge to `development` themselves.++## When human (Sam) must decide++1. Audit §9 deletions/archival (260 MB binaries, private strategy doc, dead C# tree, legacy server).+2. LegacyMode/auth default flip (breaks existing local setups).+3. Any tool rename on the shipped ~170-tool surface.+4. Installer signing, marketplace publishing, license/pricing surfaces.+5. Approving each phase's Definition of Done in `SCAFFOLDING_TASK_LIST.md`.diff --git a/docs/product/CURRENT_REPO_AUDIT.md b/docs/product/CURRENT_REPO_AUDIT.mdnew file mode 100644index 0000000..b7298fd--- /dev/null+++ b/docs/product/CURRENT_REPO_AUDIT.md@@ -0,0 +1,127 @@+# Current Repo Audit — aec-model-bridge++Audited 2026-07-08 on branch `development`. **Nothing was deleted or moved.** Files flagged for consolidation/archival are listed in §9 pending approval.++## 1. Identity++Four names in circulation — the single biggest branding problem:++| Name | Where | Verdict |+|---|---|---|+| **AEC Model Bridge** | README, LICENSING, `pyproject.toml` (`aec-model-bridge`), `server.json`, `Server("aec-model-bridge")`, logo | **Canonical** (decision D-001) |+| AEC Omni-Bridge | CLAUDE.md title, ecosystem-strategy doc, blueprint | Legacy narrative brand — migrate |+| Autodesk-Revit-MCP-Server | Local folder name only | Stale; remote is already `Sam-AEC/aec-model-bridge` |+| RevitBridge / AECModelBridge | C#: namespace `RevitBridge`, assembly `AECModelBridge`, both `dist/RevitMCP/` and `dist/AECModelBridge/` exist | Mid-flight rename; reconcile |++Also: `server.json`/`pyproject.toml` descriptions still say "for Autodesk Revit" despite multi-platform positioning; package `mcp-server-revit` / module `revit_mcp_server` are Revit-centric names for a multi-provider hub.++## 2. Packages++### `packages/mcp-server-revit` (Python hub) — mature, with dead weight+- Python ≥3.11; deps: `mcp`, `pydantic`, `httpx`, `ifcopenshell`, `networkx`, `specklepy>=3,<4`.+- **Shipped server:** `src/revit_mcp_server/mcp_server.py` — MCP stdio, registers **9 providers**: Revit, IFC, AECMapper, SQLiteExporter, Job, Rhino, SemanticGraph, Speckle, AutodeskData. Proxy via `MCP_PROXY_TARGETS`.+- **Legacy server (dead-parallel):** `server.py` — line-JSON protocol, registers Navisworks (shipped server doesn't), uses different env var `MCP_PROXY_URL`, and calls `proxy._connect()` **which does not exist** on `McpProxyProvider`. Several tests target this server, not the shipped one.+- **Orphaned legacy tool system:** `tools/handlers.py`, `tools/document.py`, `tools/health.py`, `schemas.py` — the pre-provider 25-tool system that `docs/security.md` still documents.+- Providers dir: `base.py`, `registry.py`, `revit.py`, `ifc.py`, `identity_mapper.py`, `rhino.py`, `navisworks.py`, `graph.py`, `cloud.py`, `job_provider.py`, `exporter.py`, `proxy.py`, `powerbi.py` (orphaned), `fake.py` (test-only).+- Tests: 14 modules incl. provider-contract and perf; good breadth but partly aimed at legacy code.++### `packages/revit-bridge-addin` (C#) — flagship, operational+- Multi-target **net48 / net8.0-windows / net10.0-windows** (Revit 2024/2025-26/2027). Serilog, IronPython, Revit API via local DLLs or Nice3point NuGet fallback.+- `App.cs` (IExternalApplication) → `CommandQueue` → `ExternalEvent` → `RevitCommandExecutor` → `BridgeCommandFactory`. Correct API-thread discipline.+- `BridgeServer.cs`: `/health`, `/tools`, `/capabilities`, `POST /execute`; semaphore(10); 5 MB cap. **Contract v2 (dynamic port + bearer token + registry file) implemented but OFF by default** — `LegacyMode` defaults true → fixed port 3000, no auth, unless `MCP_REVIT_LEGACY_PORT=false`.+- **Real surface: 110 `[BridgeCommand("revit.*")]` handlers** in `BridgeCommandFactory.cs` (~4,300 lines), attribute carries `IsMutating`/`ConfirmationRequired`.+- **Dead tree:** `src/Commands/Core|Advanced|Specialized|Enhancements/**` (Family/Geometry/MEP/Stairs/Structural/Worksharing commands, `Phase*CommandRegistry`) — `<Compile Remove>`d in `RevitBridge.csproj:67-73`, zero `[BridgeCommand]` attributes, never in the shipped DLL.++### `packages/rhino-bridge-addin` (C#) — built ✓+- net48, RhinoCommon 7.16, hardcoded port **3004**, `switch`-based routing (not the attribute pattern).+- ~18 commands: doc/scene/layers, primitives, booleans, materials, transforms, `run_python` (IronPython), `generate_diagrid_tower`, reflection trio.++### `packages/navisworks-bridge-addin` (C#) — routing infra only+- net48, port **3002** (or Contract-v2 dynamic). **16 attribute-registered commands** incl. model tree, viewpoints, clash tests.+- **But:** Python `NavisworksProvider` exposes only 4 tools and is registered **only in legacy `server.py`** → the entire C# surface is unreachable through the shipped hub.++### `packages/powerbi-bridge-tool` (C#) — stub, fully orphaned+- External-tool console app (`AdomdClient`, port **3006**), `.pbitool.json` configs, root `deploy_pbi.ps1`.+- `providers/powerbi.py` (5 tools incl. `powerbi_execute_dax`) is **imported/registered nowhere**. No PowerBI tool is reachable.++## 3. MCP tool inventory (shipped hub, ~170 tools)++| Provider | Count | Tools |+|---|---|---|+| Revit | 100 | `revit_*`: doc/health (7), modeling (12), elements (21), views/sheets (15), parameters (11), annotation (5), materials/QA (4), exports (5), groups/worksharing (9), schedules/phasing (7), escape hatches `revit_invoke_method` / `revit_reflect_get` / `revit_reflect_set` / `revit_execute_python` |+| Rhino | 19 | `rhino_*` incl. `rhino_run_python`, `rhino_generate_diagrid_tower` |+| Speckle | 17 | OAuth-PKCE + projects/models/versions/publish/merge |+| Autodesk/APS | 12 | OAuth + hubs/projects/items/issues |+| IFC | 7 | metadata, spatial structure, query, properties, bbox, validate |+| Semantic graph | 7 | `graph_compile`, relations, clash/disconnected/load audits |+| Mapper | 3 | `aec_translate_id`, `aec_register_mapping`, `aec_map_workspace_path` |+| Exporter | 3 | SQLite model + graph export |+| Jobs | 2 | `job_status`, `job_cancel` |++**Defined but NOT reachable:** Navisworks (4 tools, legacy server only), PowerBI (5 tools, nowhere), `fake_tool` (tests), proxy tools (env-gated).++## 4. Docs inventory++| File | Verdict |+|---|---|+| `README.md` | Good landing, but **broken links** to nonexistent `docs/tools.md`, `docs/architecture.md`, `docs/integration-expansion-handover.md`; describes Rhino via SSE :9876 (as-built is HTTP :3004); presents Navisworks as shipped |+| `CHANGELOG.md` | At 1.2.0 while `pyproject.toml`/`RevitBridge.csproj`/`server.json` say **1.1.0** |+| `CLAUDE.md` | Titled "Omni-Bridge"; **wrong Navisworks port (3005 vs 3002)**; points to nonexistent `docs/agent-task-plan.md` as "canonical backlog" |+| `docs/0001-multi-provider-architecture.md` | Accurate ADR, status still "Proposed" though built — flip to Accepted |+| `docs/0002-switch-contract-v2.md` | Accurate; note v2 is opt-in at runtime |+| `docs/0007-hub-performance-posture.md` | Current |+| `docs/system-blueprint-and-workflows.md` | **Most valuable doc** (36 KB, self-auditing §0), but references deleted docs and gone `providers/speckle.py` |+| `docs/roadmap-and-plans.md` | Real roadmap (Phases A–I); overstates Navisworks/PowerBI as shipped; overlaps blueprint §10 |+| `docs/security.md` | **Most stale doc**: documents the dead 25-tool system and config keys (`allow_destructive`, `allowed_tools`, `destructive_confirm`) that **don't exist in `config.py`**; contradicts ADR 0002 on auth |+| `docs/tools-generated.md` | Auto-generated; lists Navisworks/PowerBI tools the hub doesn't register; `Mutating?` columns all "?" (metadata gap) |+| `docs/ecosystem-strategy-and-monetization.md` | Flagged private, **currently committed to a public-destined repo — exposure risk** |+| `configuration-reference.md`, `install.md`, `build-and-install-scripts.md`, `marketplaces.md`, `revit-addin-lifecycle.md`, `logging-and-audit.md` | Current and accurate |+| `target-frameworks-and-dependencies.md` | Mostly current; dependency list omits `mcp`, `ifcopenshell`, `networkx`, `specklepy` |+| CONTRIBUTING / LICENSING / SECURITY / TRADEMARKS / NOTICE | Current; licensing hygiene is genuinely mature |++## 5. As-documented vs as-built divergences++1. Navisworks switch advertised; provider unregistered in shipped hub.+2. PowerBI advertised (badges, CHANGELOG, commit 949d2e5); provider orphaned.+3. README says Rhino = SSE :9876/Rhino.Compute; reality = HTTP :3004 provider.+4. Two hub servers; tests split across them; `server.py` has the `_connect()` bug.+5. Source tree advertises MEP/stairs/structural command modules that are compile-excluded.+6. `security.md` says "no auth" while ADR 0002 + code implement bearer tokens — but LegacyMode default makes "no auth" the *runtime* truth. Both docs need one story.+7. Approval/destructive-action config documented but not implemented → this is the MVP's core build item, not a config fix.+8. Version drift 1.2.0 vs 1.1.0; port drift (CLAUDE.md Navis 3005 vs 3002).++## 6. Strong++- Provider abstraction (`AECProvider` + registry) — adding an integration is one class.+- 110 working Revit commands with correct ExternalEvent threading + IronPython escape hatch.+- Async jobs, PII/path redaction, workspace sandboxing, semantic graph, SQLite exporter, OAuth-PKCE cloud connectors.+- 14-module test suite incl. contract + perf tests; mock mode for CI.+- ADRs + self-auditing blueprint; mature dual-licensing/trademark hygiene; multi-target C# build already in place.++## 7. Weak++- Naming chaos (§1). Two servers + legacy tool system obscure the real surface.+- Doc drift everywhere a user would look first (README links, security.md, tool catalog).+- Advertised-but-unreachable connectors erode trust in all other claims.+- No mutation metadata on Python tools; no approval layer; no UI beyond ribbon stub.+- ~260 MB stray Rhino binaries in `docs/` (`Untitled*.3dm/.3dmbak/.rhl`); stray `Omni_LiveGeometryStats.csv`; tracked caches (`.pytest_cache/`, `.ruff_cache/`); committed `dist/` incl. legacy `dist/RevitMCP/`.++## 8. Missing++- Approval/undo layer (the product's core promise). Dockable panel UI. Module registry. Semantic BIM schema (identity mapper exists; no element-level roundtrip schema). Orchestrator/recipes (Phase C). Parquet/DuckDB + `.pbit` (Phase D). MkDocs site. `.env.example` covering `SPECKLE_CLIENT_ID`, `APS_CLIENT_ID`, `MCP_PROXY_TARGETS`, `MCP_REVIT_LEGACY_PORT`, etc.++## 9. Consolidation / archival candidates — **approval required before touching**++**Delete (accidental binaries):** `docs/Untitled.3dm`, `docs/Untitled2.3dm`, `docs/Untitled.3dmbak`, `docs/Untitled2.3dmbak`, `docs/Untitled.3dm.rhl` (~260 MB), `Omni_LiveGeometryStats.csv`.++**Untrack:** `dist/` (both trees; CONTRIBUTING says don't commit), `.pytest_cache/`, `.ruff_cache/`, empty `metrics/`.++**Move to private repo:** `docs/ecosystem-strategy-and-monetization.md`.++**Retire after test migration:** `revit_mcp_server/server.py`, `tools/{handlers,document,health}.py`, legacy parts of `schemas.py`, `providers/fake.py` (or move under `tests/`).++**Delete or revive (decide):** `packages/revit-bridge-addin/src/Commands/**` dead tree.++**Rewrite:** `docs/security.md` (against as-built), README links, CLAUDE.md port table + backlog pointer; regenerate `docs/tools-generated.md` after mutation-metadata work.++**Keep, reconcile:** `roadmap-and-plans.md` vs blueprint §10 overlap → roadmap stays strategy, blueprint stays architecture, this `docs/product/` package becomes the buildable plan; version bump artifacts to match CHANGELOG.diff --git a/docs/product/DECISIONS_AND_RISKS.md b/docs/product/DECISIONS_AND_RISKS.mdnew file mode 100644index 0000000..7645c31--- /dev/null+++ b/docs/product/DECISIONS_AND_RISKS.md@@ -0,0 +1,72 @@+# Decisions & Risks Log++Append-only. Decisions carry status: **Decided** (by Sam) / **Proposed** (needs Sam) / **Open**.++## Decisions++| ID | Decision | Status | Rationale |+|---|---|---|---|+| D-001 | Product name = **AEC Model Bridge**; "Omni-Bridge" = legacy/ecosystem narrative only | **Decided** 2026-07-08 | Matches repo slug, PyPI, server.json; ends 4-name chaos |+| D-002 | MVP = inspect (W1) → QA/QC (W7/W9) → parameters (W5); **façade roundtrip deferred** to Phase-2 flagship | **Decided** 2026-07-08 | Three workflows share one semantic layer; façade proves it publicly afterwards |+| D-003 | MVP audience = **normal Revit users**; dockable WebView2 panel + approval queue in first release | **Decided** 2026-07-08 | Product differentiation is the safety UX, not the tool count |+| D-004 | One hub server: `mcp_server.py`; retire `server.py` + legacy `tools/`/25-tool system after test migration | Proposed | Two servers with divergent providers/env vars confuse everything; `server.py` has a known `_connect()` bug |+| D-005 | Revit targets: **net48 (2024) + net8 (2025/26)** shipped; net10 (2027) experimental | **Decided** 2026-07-08 | Multi-target already in csproj; broadest firm reach |+| D-006 | Contract v2 (dynamic port + bearer) becomes **runtime default**; legacy :3000 opt-in | Proposed | Unauthenticated default contradicts the safety story; ADR 0002 already accepted |+| D-007 | Approval gate enforced in the **hub** (single choke point), C# `ConfirmationRequired` stays defense-in-depth | Proposed | One enforcement point across all switches; direct-HTTP callers still guarded |+| D-008 | Panel UI = WebView2-hosted web app, WPF only as pane chrome | Proposed | Iteration speed; reusable across hosts; spike memory/load-order in P16.1 first |+| D-009 | Power BI: **file lane first** (SQLite→.pbit); live ADOMD lane wired health-only until pulled | Proposed | External-tool session handshake is fragile; file lane delivers value now |+| D-010 | Hub install for non-programmers: bundled Python runtime in installer (pipx as expert path) | Open | Decide at P19; bundled ≈ +80 MB but zero-friction |+| D-011 | Dead C# tree `src/Commands/**`: delete after per-subsystem salvage review | Open — needs Sam | 0 registered commands, compile-excluded; keeping it misleads every future agent |+| D-012 | CI Revit e2e: self-hosted runner vs scripted-local-only | Open | Depends on Sam's hardware/licensing; goldens must run *somewhere* nightly |+| D-013 | Git history rewrite to purge 92 MB binaries (BFG) vs plain `git rm` | Open — needs Sam | Rewrite breaks clones/forks; rm leaves history heavy |+| D-014 | Docs package lives in `docs/product/`, monetization content excluded (private doc moves out, P0.2) | **Decided** 2026-07-08 | Public-repo hygiene |++## Risks++### Revit API+- **R1 Threading/deadlock:** all writes must ride the existing ExternalEvent queue; any new code path that touches the API off-thread crashes Revit. *Mitigation:* single choke point (`RevitCommandExecutor`), reviewed by Security/Safety agent; no async API access ever.+- **R2 Snapshot perf on big models:** 100k+ elements × params is minutes, not seconds. *Mitigation:* incremental extraction via `DocumentChanged` dirty-list (P3.4), category filtering, measure before optimizing (ADR 0007 budgets).+- **R3 Multi-target drift:** net48 vs net8 API differences (nullable, some API changes 2024→2025). *Mitigation:* CI builds both; `#if` islands kept minimal; Nice3point packages per version.+- **R4 Worksharing:** writes to elements owned by others fail mid-plan. *Mitigation:* ownership check at plan time; partial-apply policy = report-and-continue with explicit summary (never silent).++### MCP+- **R5 Tool-count bloat (~170+):** agents pick wrong tools. *Mitigation:* metadata + module namespacing; curated tool subsets per surface; snapshot-first querying reduces call volume.+- **R6 MCP SDK churn** (`mcp>=0.9.0`): breaking spec changes. *Mitigation:* pin + contract tests; adapter layer is thin.+- **R7 Breaking the shipped surface:** renames strand existing users. *Mitigation:* additive-only within 1.x; renames need human approval (swarm rule).++### Plugin app+- **R8 WebView2 in Revit process:** memory pressure, runtime missing, load-order clashes with other add-ins. *Mitigation:* P16.1 spike before committing; WPF fallback documented as plan B.+- **R9 Installer/AV friction:** unsigned DLLs + local HTTP server look suspicious. *Mitigation:* code-signing cert (P19), loopback-only listener, clear firewall docs.++### Semantic data+- **R10 Schema churn after freeze:** downstream (rules, panel, exporters) all break. *Mitigation:* append-only within major; `schema_version` everywhere from first byte.+- **R11 UniqueId edge cases:** SaveAs, detach, IFC re-export change identity anchors. *Mitigation:* doc-guid anchoring + re-anchor prompt (W9); mapper keeps provenance.++### AI agents+- **R12 Silent mutation = product death.** One incident of an AI changing a model without approval kills trust permanently. *Mitigation:* gate default-on, `approve_plan` not callable by agents on panel surface, audit ledger, `agent_reviewer` second-model check (P2 tier). **This is the risk the whole architecture exists to kill.**+- **R13 Query hallucination:** wrong answers about the model are almost as bad. *Mitigation:* DSL-validated `snapshot_query` is the only query path; answers cite element uids; golden Q&A tests.+- **R14 Swarm merge conflicts / context loss:** *Mitigation:* path ownership, contract freezes, worktrees, handover format (swarm plan).++### Integrations+- **R15 Version matrices** (Rhino×RiR×Revit, Dynamo×Revit, PBI sessions): support cost explodes. *Mitigation:* pinned supported matrix per release; everything else "community-tested".+- **R16 OAuth secrets/tokens** (Speckle/APS) on disk. *Mitigation:* existing redaction + OS credential store at P20; never in workspace exports.++### Performance+- **R17 Chat context flooding:** dumping element lists into LLM context. *Mitigation:* payload caps, snapshot files + summaries, uid-chip pattern.++### Security+- **R18 Unauthenticated legacy port** during transition (today's default!). *Mitigation:* D-006 flip early (P3.1); loopback-only binding already in place.+- **R19 `*_execute_python` / reflection escape hatches** bypass all semantics. *Mitigation:* `python.host` permission, expert-mode only, off by default, always audited.+- **R20 Third-party modules run arbitrary code.** *Mitigation:* trust-model doc, explicit enable per module dir, firm allowlist (P20.1).++### Adoption+- **R21 "Another automation tool" skepticism + AI-in-production fear.** *Mitigation:* the demo arc leads with approval/rollback, not with AI magic; read-only workflows first in every firm rollout.+- **R22 Solo-maintainer bus factor / burnout.** *Mitigation:* the swarm plan and this package *are* the mitigation — any capable agent session can resume from `NEXT_AGENT_HANDOVER.md`.++## Open questions++1. D-010/D-011/D-012/D-013 need Sam's call (installer runtime, dead tree, CI runner, history rewrite).+2. Which Revit version is on Sam's machine right now? (Determines the first e2e loop; multi-target can compile blind but e2e cannot.)+3. Panel LLM plumbing for non-Claude-Code users: MVP assumes Claude Code/desktop as the agent host — does v1.3.0 need an embedded API-key client, or is "bring Claude" acceptable for first release?+4. Rule pack authorship: which 15 rules does Sam's project experience rank highest? (P10.2 review gate.)+5. Canonical test model style: generic office tower vs façade-heavy tower (dual-purpose for P11 demo)?diff --git a/docs/product/INTEGRATION_STRATEGY.md b/docs/product/INTEGRATION_STRATEGY.mdnew file mode 100644index 0000000..52c337d--- /dev/null+++ b/docs/product/INTEGRATION_STRATEGY.md@@ -0,0 +1,98 @@+# Integration Strategy++Priorities: **P0** = MVP, **P1** = flagship/next, **P2** = after P1, **Future**. "Exists" reflects the audit in `CURRENT_REPO_AUDIT.md`.++| # | Integration | Priority | Exists today |+|---|---|---|---|+| 1 | Revit API | P0 | 110 C# commands / 100 MCP tools ✓ |+| 2 | MCP | P0 | hub + 9 providers ✓ |+| 3 | Claude Code | P0 | via MCP stdio ✓ |+| 4 | VS Code | P0 | via MCP config ✓ |+| 5 | GitHub | P0 | repo/CI workflows ✓ |+| 6 | Excel | P0 | ✗ (SQLite exists; xlsx new) |+| 7 | IFC | P0 | 7 tools ✓ |+| 8 | Rhino / Grasshopper | P1 | 19 tools + bridge :3004 ✓ |+| 9 | Rhino.Inside.Revit | P1 | ✗ |+| 10 | Speckle | P1 | 17 tools ✓ (OAuth) |+| 11 | Navisworks | P1 | C# 16 cmds ✓ / provider unregistered ✗ |+| 12 | Power BI | P1 | C# tool :3006 partial / provider orphaned ✗ |+| 13 | Dynamo | P2 | scratch prototypes only |+| 14 | DuckDB / Parquet | P2 | ✗ (roadmap Phase D) |+| 15 | APS / ACC | P2 | 12 tools ✓ (OAuth) |+| 16 | Local AI agents (BYO-LLM) | P2 | ✗ (roadmap Phase H) |+| 17 | MS Graph | Future | ✗ |+| 18 | Cloud / remote MCP | Future | ✗ (roadmap Phase H) |++---++### 1. Revit API — P0+- **Purpose/value:** the product's substrate; native reads/writes. **Data:** elements, params, views, sheets, transactions.+- **Method:** existing add-in (`HttpListener` → `ExternalEvent` → `BridgeCommandFactory`), Contract v2 flipped to default. Multi-target net48 (2024) + net8 (2025/26); net10 (2027) stays experimental.+- **SDK:** RevitAPI.dll local or `Nice3point.Revit.Api.*` (both wired).+- **MVP:** stabilize 110 commands, add snapshot extraction command, mutation metadata parity. **Advanced:** revive/kill dead `Commands/**` tree per subsystem; worksharing-aware writes.+- **Risks:** API-thread deadlocks (mitigated by existing queue); version drift across targets. **Test:** e2e against canonical model per Revit version (CI matrix where licensable; else scripted local runs).++### 2. MCP — P0+- **Purpose:** stable machine contract for all agents/clients. **Data:** tool schemas, results, job refs.+- **Method:** `mcp_server.py` only (retire `server.py`); `ProviderTool` gains `is_mutating`/`destructive`/`execution_mode`/`permissions`; regenerate `tools-generated.md`.+- **MVP:** metadata + approval-gate tools (`plan_actions`, `approve_plan`, `list_pending_plans`). **Advanced:** MCP resources for snapshots, prompts for common workflows.+- **Risks:** spec evolution (`mcp>=0.9.0` pin — track SDK releases); tool-count bloat degrading agent tool choice (group via module namespacing). **Test:** existing `test_provider_contract.py` extended to assert metadata on every tool.++### 3. Claude Code — P0+- **Purpose:** expert surface + the swarm that builds the product. **Method:** `server.json` MCP config; project skills (`/rhino-god-mode` exists); `CLAUDE.md` corrections (ports, backlog pointer).+- **MVP:** clean install docs + working config. **Advanced:** packaged workflow skills (`/model-health`, `/param-batch`). **Risk:** none structural. **Test:** fresh-clone smoke script.++### 4. VS Code — P0+- **Purpose:** developer/automation-engineer surface. **Method:** same MCP server via VS Code MCP config; no bespoke extension for MVP (Future: status/log viewer extension). **Test:** documented setup walkthrough.++### 5. GitHub — P0+- **Purpose:** CI, releases, module distribution. **Method:** existing repo + Actions: pytest + `dotnet build` matrix (net48/net8), DLL license scan (exists per LICENSING), release artifacts (installer + wheel). **MVP:** CI green on both stacks. **Advanced:** module marketplace via releases/registry repo. **Risk:** Revit API DLLs not redistributable — CI uses Nice3point NuGet fallback (already supported).++### 6. Excel — P0+- **Purpose:** the report format management actually opens. **Data:** element/param/finding tables; CSV param roundtrip.+- **Method:** `openpyxl` in hub (`export_excel` tool). **MVP:** 3-sheet workbook (elements, parameters, findings). **Advanced:** formatted QA dashboards, roundtrip validation. **Risks:** file locks; huge sheets (row cap + link to SQLite). **Test:** golden workbook diff on canonical model.++### 7. IFC — P0+- **Purpose:** open-standard read/validation lane; non-Revit data QA. **Data:** GlobalId, spatial tree, psets.+- **Method:** `ifcopenshell` provider (exists, 7 tools) + mapper (GlobalId↔UniqueId). **MVP:** IFC Q&A + Revit-vs-IFC comparison. **Advanced:** IDS validation (Phase D), IFC export QA (`revit_export_ifc` then re-validate). **Risks:** ifcopenshell wheel/platform pinning. **Test:** sample IFC fixtures in repo.++### 8. Rhino / Grasshopper — P1+- **Purpose:** computational design lane; façade flagship. **Data:** panel geometry, semantic zone specs, preview meshes.+- **Method:** existing C# bridge :3004 (`run_python` is the workhorse) + MCP `g1_*` GH canvas tools; GH emits semantic spec JSON, not meshes.+- **MVP(P1):** façade zone spec exporter GH definition. **Advanced:** live-link, `CurtainWallDetailer`/`DiagridGenerator` productization. **Risks:** RhinoCommon v7 vs v8 API drift (reflection helpers exist); hardcoded port (move to Contract v2). **Test:** scripted Rhino headless run → spec → golden diff.++### 9. Rhino.Inside.Revit — P1+- **Purpose:** GH against live Revit geometry, in-process. **Method:** custom GH components wrapping hub endpoints; RiR emits semantic specs → ActionPlans (no write bypass).+- **SDK:** RiR nuget/SDK; supported version matrix documented. **MVP(P1):** one exemplar definition. **Advanced:** Revit-selection-driven GH inputs. **Risks:** RiR/Rhino/Revit version triangle; load order with our add-in. **Test:** manual matrix checklist + exemplar run.++### 10. Speckle — P1+- **Purpose:** versioned transport + web viewing + external collaborators. **Data:** semantic snapshots as Speckle objects.+- **Method:** 17 existing tools (`specklepy>=3`); publish snapshot → receive delta → W14 reconciliation. **MVP(P1):** publish/receive snapshot roundtrip. **Advanced:** branch-per-variant façade workflow. **Risks:** Speckle v3 API churn; OAuth token lifetime (refresh exists). **Test:** `test_cloud_providers.py` extended with mock server (exists) + live smoke.++### 11. Navisworks — P1+- **Purpose:** coordination/clash results back into the loop. **Data:** model tree, clash tests/results, viewpoints.+- **Method:** **register `NavisworksProvider` in `mcp_server.py`** and widen it to the 16 C# commands (`navis.run_clash_test`, `navis.get_clash_results`, viewpoints, tree); clash GUIDs → mapper → Revit selection.+- **MVP(P1):** health + model tree + clash results → Revit element selection. **Advanced:** auto-viewpoint per QA finding; NWD export pipeline from `revit_export_navisworks` (exists). **Risks:** Navisworks COM quirks; GUID mapping fidelity. **Test:** RVT+NWF fixture pair.++### 12. Power BI — P1+- **Purpose:** live dashboards; "ask your dashboard" DAX Q&A. **Data:** DAX queries/results; exported tables.+- **Method (two lanes):** (a) file lane — SQLite→(later Parquet) + shipped `.pbit`; (b) live lane — wire orphaned `PowerBIProvider` to the :3006 ADOMD external tool.+- **MVP(P1):** file lane + provider registration with health. **Advanced:** DAX Q&A, auto-refresh. **Risks:** external-tool launch args change per PBI session (re-handshake needed); ADOMD licensing/runtime deps. **Test:** DAX smoke against a fixture PBIX.++### 13. Dynamo — P2+- **Purpose:** meet Revit users where they are. **Method:** ZeroTouch node package calling hub HTTP; nodes = thin wrappers over the same semantic spec + gate. **MVP(P2):** 5 nodes (connect, snapshot, query, plan, apply). **Risks:** Dynamo versioning per Revit release. **Test:** sample graph in repo.++### 14. DuckDB / Parquet — P2 (roadmap Phase D)+- **Purpose:** analytics-grade data plane; multi-model portfolio queries. **Method:** exporter grows Parquet writer; DuckDB for local SQL; PBI reads Parquet. **MVP(P2):** Parquet mirror of SQLite schema. **Risks:** schema evolution discipline (`schema_version` from day one — see W8). **Test:** row-count parity SQLite↔Parquet.++### 15. APS / ACC — P2+- **Purpose:** cloud model/issue integration for enterprise. **Method:** 12 existing `autodesk_*` tools; QA findings → ACC Issues (`autodesk_data_create_issue` exists). **MVP(P2):** findings→Issues. **Risks:** APS app provisioning/scopes; rate limits. **Test:** mocked + sandbox hub.++### 16. Local AI agents / BYO-LLM — P2 (roadmap Phase H)+- **Purpose:** firms that can't send model data to cloud LLMs. **Method:** hub is client-agnostic already (MCP); document Ollama/LM Studio MCP-client setups; approval gate matters *more* here. **Risk:** small-model tool-choice quality → provide curated tool subsets per module.++### 17. MS Graph — Future+- Teams notifications of QA runs, SharePoint report drops, Planner tasks from findings. Method: Graph SDK in hub; requires tenant app registration. Park until enterprise pull.++### 18. Cloud / remote MCP — Future+- REST/OpenAPI facade + hosted hub (roadmap Phase H). Blockers: auth story beyond localhost bearer, multi-tenant workspace isolation. Do not start before packaging (Phase 19) is done.diff --git a/docs/product/MVP_EXECUTION_PLAN.md b/docs/product/MVP_EXECUTION_PLAN.mdnew file mode 100644index 0000000..d4170ef--- /dev/null+++ b/docs/product/MVP_EXECUTION_PLAN.md@@ -0,0 +1,80 @@+# MVP Execution Plan++Locked decisions (2026-07-08): audience = **normal Revit users first** (dockable panel + approvals); killer workflows = **inspect → validate → fix** (façade roundtrip deferred to Phase-2 flagship); targets = **Revit 2024 (net48) + 2025/26 (net8)**, multi-target already in `RevitBridge.csproj`.++## Build first (in order)++1. **Phase 0 cleanup** — the repo must stop contradicting itself before anything ships (README links, security.md, ports, 260 MB binaries, version drift).+2. **Approval gate + tool metadata** (P4) — the product's core promise; everything else hangs off it.+3. **Snapshot extraction** (P3.3 + P6) — one data layer that all three workflows query.+4. **Three killer workflows** as modules (P7, P10, P9 — in that order: read → validate → write).+5. **Dockable panel** (P16, parallel from step 3 behind fixed endpoint contracts).+6. **Installer** (P19 minimal) — a BIM manager must install without pip knowledge.++## Delay (explicitly)++Façade configurator (P11 — flagship demo *after* MVP proves the layer), RiR/GH components (P12), Speckle/Navisworks workflows beyond provider registration (P13), Power BI live lane, Parquet/DuckDB (P14 partial), orchestrator/recipes (P15), Dynamo, APS, remote MCP, marketplace.++## Do not overbuild++- **Module system:** discovery + manifest + permissions only; no marketplace, no sandboxing beyond the trust-model doc, no hot reload.+- **Panel:** chat + plan cards + findings + log. No dashboards, no settings sprawl, no theming.+- **QA rules:** 15 curated rules that are *right*, not 100 that are noisy.+- **Rollback:** undo + inverse-for-parameters. No general time-travel.+- **Snapshot:** bbox-level geometry refs only; no mesh pipelines in MVP.+- **Auth:** localhost bearer (Contract v2). No user accounts, no cloud.++## First 3 killer workflows++1. **W1 Ask the model** — NL question → snapshot query → answer with clickable element chips.+2. **W7 Model health check** — one click → 15-rule findings report → exportable, trackable (W9-lite issue list).+3. **W5 Batch parameters with approval** — filter → diff grid → approve → apply → rollback.++Demo arc (one sitting, canonical model): *ask "how many doors lack fire ratings?" → run health check, see it as a finding among others → fix all 37 via approved batch-set → re-check shows resolved → export Excel report → hit Undo/rollback to prove safety.*++## First 10 MCP tools (new/changed; the ~170 existing stay)++| # | Tool | Phase |+|---|---|---|+| 1 | `snapshot_take` | P6 |+| 2 | `snapshot_query` | P6 |+| 3 | `snapshot_diff` | P6 |+| 4 | `plan_actions` | P4 |+| 5 | `list_pending_plans` | P4 |+| 6 | `approve_plan` (panel-only surface; agents may not self-approve) | P4 |+| 7 | `rollback_plan` | P4 |+| 8 | `qaqc_run_health_check` | P10 |+| 9 | `qaqc_list_issues` | P10 |+| 10 | `export_excel` | P14.1 (pulled into MVP) |++Plus metadata backfill on all existing tools (P4.1) and `revit.extract_snapshot` on the C# side (P3.3).++## First 5 plugin UI commands (ribbon)++1. **Open Bridge Panel** 2. **Run Health Check** 3. **Review Pending Actions** (badge = pending count) 4. **Inspect Selection** 5. **Export Report**++## First semantic data schema++`amb.snapshot/1` exactly as `SEMANTIC_BIM_DATA_MODEL.md` §2 — ElementRecord + Relations (hosts/bounds/on_level/in_group/on_sheet) + TypeRecord. Delta/zone/variant schemas are frozen on paper but implemented post-MVP.++## First test model++Generator script (P17.1), not a binary: 5 levels, ~200 walls, 60 doors (12 missing FireRating), 40 windows, 25 rooms (3 unplaced, 2 unenclosed), 30 views (6 unnamed, 8 not on sheets), 10 sheets (2 duplicate numbers), 4 model groups, 2 in-place families, seeded warnings. Every seeded defect maps to exactly one core rule → golden findings file.++## First demo scenario++The demo arc above, recorded on the canonical model, driven entirely from the panel (no code visible) — this is also tutorial 2 and the flagship-pitch opener.++## First release checklist (v1.3.0)++- [ ] Phase 0 complete: no doc/code contradictions, versions reconciled, binaries purged (with Sam's approval)+- [ ] Contract v2 default; unauthenticated :3000 requires explicit opt-in+- [ ] All tools metadata-complete; `tools-generated.md` regenerated without "?"+- [ ] Approval gate: mutating call without approved plan is rejected (test-proven)+- [ ] 3 killer workflows green on canonical model goldens (CI or scripted local e2e)+- [ ] Panel drives all 3 workflows; hub-down/no-doc states handled+- [ ] Installer on clean Windows 11 + Revit 2024 and 2025 → tutorial 1 in <15 min+- [ ] Audit ledger records every mutation with plan/action ids; rollback demo passes+- [ ] Docs: quickstart, 3 tutorials, security model rewrite, module authoring stub+- [ ] `LICENSES/` DLL scan green; no `Co-Authored-By` trailers anywhere in release history+- [ ] Sam sign-off on demo recordingdiff --git a/docs/product/NEXT_AGENT_HANDOVER.md b/docs/product/NEXT_AGENT_HANDOVER.mdnew file mode 100644index 0000000..c387b4f--- /dev/null+++ b/docs/product/NEXT_AGENT_HANDOVER.md@@ -0,0 +1,31 @@+# Next Agent Handover++**Session:** 2026-07-08, planning/scaffolding only — **no production code written, nothing deleted.**++## What was inspected+Full repo audit (delegated to an Explore subagent): all root + `docs/` markdown, all 5 packages (hub providers/servers/tests, Revit add-in incl. `BridgeCommandFactory.cs` and csproj exclusions, Rhino/Navisworks bridges, PowerBI tool), `scripts/`, `dist/`, `server.json`, git log vs CHANGELOG. Findings preserved in `CURRENT_REPO_AUDIT.md`.++## What was created (all new, in `docs/product/`)+`AEC_MODEL_BRIDGE_PRODUCT_VISION.md` · `CURRENT_REPO_AUDIT.md` · `PLUGIN_APP_ARCHITECTURE.md` · `AEC_WORKFLOW_CATALOG.md` (W1–W16) · `INTEGRATION_STRATEGY.md` (18 integrations, P0–Future) · `PLUGIN_MODULE_SYSTEM.md` · `SEMANTIC_BIM_DATA_MODEL.md` · `AI_AGENT_SWARM_PLAN.md` (14 agents) · `SCAFFOLDING_TASK_LIST.md` (Phases 0–21) · `MVP_EXECUTION_PLAN.md` · `DECISIONS_AND_RISKS.md` · this file.++## What was NOT changed+No existing file edited or deleted. CLAUDE.md still has the wrong Navisworks port (3005→3002) and dead backlog pointer; README links still broken; `docs/security.md` still stale; 260 MB stray `.3dm*` binaries still in `docs/`; private strategy doc still in repo; versions still 1.1.0 vs CHANGELOG 1.2.0. All of that is **Phase 0** work awaiting Sam's approval of the deletion list (`CURRENT_REPO_AUDIT.md` §9).++## Main findings (from the audit)+1. Shipped hub = `mcp_server.py`, 9 providers, ~170 tools; a **legacy parallel server** (`server.py` + 25-tool `tools/` system) confuses tests and docs, and has a real bug (`proxy._connect()` doesn't exist).+2. **Navisworks provider is not registered** in the shipped hub; **PowerBI provider registered nowhere** — both are advertised as working.+3. Revit add-in is solid (110 attribute-registered commands, correct ExternalEvent threading), but `src/Commands/**` is a compile-excluded dead tree, and **Contract v2 auth exists but LegacyMode (port 3000, no auth) is the runtime default**.+4. The approval/destructive-action layer documented in `docs/security.md` **was never implemented** — it is the MVP's core build item.+5. Four competing product names; D-001 fixes it as **AEC Model Bridge**.++## Decisions locked with Sam (see DECISIONS_AND_RISKS.md)+D-001 name · D-002 MVP = inspect/QA-QC/parameters, façade deferred to flagship · D-003 normal-Revit-user audience with dockable panel + approvals · D-005 net48+net8 targets · D-014 docs in `docs/product/`, strategy-free.++## Biggest risks+R12 (silent AI mutation — the gate must be default-on and agent-unapprovable), R2 (snapshot perf on large models), R8 (WebView2-in-Revit spike unproven), D-013 (92 MB binaries may warrant history rewrite — needs Sam).++## Recommended next task+**Phase 0** (`SCAFFOLDING_TASK_LIST.md`): present the §9 deletion list to Sam, then execute the doc/version cleanup. It's low-risk, unblocks everything, and makes the repo stop contradicting itself. First *code* task after that: **P4.1 tool metadata + P4.2 approval gate** (pure Python, testable without Revit open).++## Exact next prompt+> Read docs/product/NEXT_AGENT_HANDOVER.md and docs/product/SCAFFOLDING_TASK_LIST.md. Execute Phase 0: first show me the deletion/untrack/move list from CURRENT_REPO_AUDIT.md §9 for approval, then apply approved items, fix CLAUDE.md (port 3002, backlog pointer → docs/product/SCAFFOLDING_TASK_LIST.md, retitle AEC Model Bridge), fix README broken links and the Rhino transport description, rewrite docs/security.md against the as-built provider system, and reconcile versions to CHANGELOG. Commit in logical chunks on development, no Co-Authored-By trailers.diff --git a/docs/product/PLUGIN_APP_ARCHITECTURE.md b/docs/product/PLUGIN_APP_ARCHITECTURE.mdnew file mode 100644index 0000000..d5d4e0b--- /dev/null+++ b/docs/product/PLUGIN_APP_ARCHITECTURE.md@@ -0,0 +1,86 @@+# Plugin App Architecture++Builds on what exists: `revit-bridge-addin` (110 commands, ExternalEvent path), the Python hub (9 providers, ~170 tools), ADR 0001/0002. New layers are marked **[NEW]**.++## 1. Layer map++```+┌─ Surface ──────────────────────────────────────────────────────────┐+│ Revit dockable panel [NEW] Ribbon tab (exists, grows) │+│ Claude Code / MCP clients (exists) VS Code (exists via MCP) │+├─ AI agent layer ───────────────────────────────────────────────────┤+│ Claude via MCP stdio (exists) · agent proposes ActionPlans [NEW] │+├─ Hub (Python, packages/mcp-server-revit) ──────────────────────────┤+│ mcp_server.py · ProviderRegistry (exists) │+│ Approval Gate [NEW] · Module Registry [NEW] · Audit log (extend) │+│ Semantic BIM layer [NEW] · IdentityMapper/Graph/Exporter (exist) │+│ JobManager async (exists) · Redaction/workspace sandbox (exist) │+├─ Switches (C# HTTP, Contract v2) ──────────────────────────────────┤+│ Revit :3000/v2 (exists) · Rhino :3004 · Navis :3002 · PBI :3006 │+├─ Host APIs ────────────────────────────────────────────────────────┤+│ Revit API (ExternalEvent+Transaction) · RhinoCommon · Navis .NET │+└────────────────────────────────────────────────────────────────────┘+```++## 2. Revit add-in layer (C#)++Keep the proven pipeline: `BridgeServer` (HttpListener) → `CommandQueue.Enqueue` → `ExternalEvent.Raise()` → `RevitCommandExecutor` on API thread → `BridgeCommandFactory`.++Changes:+- **Contract v2 becomes default** (flip `LegacyMode`): dynamic loopback port, registry file `%LOCALAPPDATA%\AECModelBridge\registry\revit-<pid>.json`, bearer token on `/execute`. Kill unauthenticated :3000 default. (D-006)+- **Transaction discipline [NEW policy]:** every mutating handler wraps exactly one named `Transaction` (`"AMB: <module>.<command> #<action_id>"`). Multi-step actions use `TransactionGroup` and assimilate. Name = the undo entry the user sees; `action_id` links Revit undo history to the audit log.+- **Dockable panel [NEW]:** `IDockablePaneProvider` hosting **WebView2**; panel UI is HTML/JS talking to the add-in over the WebView2 message bridge, and to the hub via localhost. WPF only for the pane chrome. Rationale: web UI iterates fast, reuses across hosts later.+- **Ribbon:** existing `AEC Bridge` tab grows to: Open Panel · Run Health Check · Review Pending Actions · Reports · Settings.+- **Dead tree decision:** `src/Commands/**` (compile-excluded) is deleted or revived per subsystem — audit item, human call (D-011).++## 3. MCP server layer (Python hub)++- **One server.** `mcp_server.py` is canonical; `server.py` + legacy `tools/` retire after test migration (D-004).+- **Register the strays:** NavisworksProvider into `mcp_server.py`; PowerBIProvider wired or explicitly parked.+- **Tool metadata [NEW]:** extend `ProviderTool` with `is_mutating: bool`, `destructive: bool`, `execution_mode: sync|async`, `permissions: [str]` — mirrored from the C# `[BridgeCommand]` attributes so `tools-generated.md` stops printing "?".++## 4. Safety & approval layer [NEW — the core product build]++The keystone. `docs/security.md` documents `allow_destructive`/`destructive_confirm` keys that were never implemented; this replaces them.++- **ActionPlan:** agents that want to mutate call `plan_actions` (new hub tool) with a list of intended tool calls + args. Hub validates schemas, dry-runs read-side (element counts, parameter before-values), returns a plan with `plan_id` and per-action diffs.+- **Approval Gate:** mutating tools called without an approved `plan_id` are rejected when `approval_mode=required` (default in panel mode; `auto` available for headless/expert use, off by default). Pending plans surface in the dockable panel as cards → Approve / Reject / Approve-all-similar.+- **Execution:** approved plan executes through the normal provider path; each action's transaction carries the `action_id`.+- **Rollback:** per-action = Revit undo (named transaction); per-plan = `TransactionGroup` rollback while open, otherwise a generated inverse plan (e.g. restore captured before-values for parameter writes) — inverse plans only for reversible action types; others marked `irreversible: true` and require explicit confirm.+- Enforcement lives in the **hub** (single choke point for all switches); the C# `ConfirmationRequired` attribute stays as defense-in-depth for direct HTTP callers.++## 5. Logging & audit++Extend the existing two-layer logging (`docs/logging-and-audit.md`): add an **audit ledger** (JSONL, `%LOCALAPPDATA%\AECModelBridge\audit\<doc-guid>\*.jsonl`): `{ts, user, agent, plan_id, action_id, tool, args_redacted, element_uids, before, after, result, transaction_name}`. Panel run-log reads this. Redaction pipeline (exists) applies before write.++## 6. Data extraction & semantic BIM layer++- **Extraction (exists):** `revit_list_elements`, `revit_get_element_parameters`, exporter → SQLite; IFC provider; graph provider.+- **Semantic layer [NEW]:** typed element snapshots keyed by **Revit UniqueId**, with category/type/host/level/room relations — schema in `SEMANTIC_BIM_DATA_MODEL.md`. Built on `IdentityMapper` (exists) for cross-app identity. This is what QA rules, diffs, reports, and the façade roundtrip all consume — build once.++## 7. Module registry & tool execution [NEW]++Modules = manifest (JSON) + Python module class exposing commands that compose existing MCP tools; C# only when a new host-side primitive is needed. Discovery: `modules/` dir + entry points. Full spec: `PLUGIN_MODULE_SYSTEM.md`. Execution routes through the same registry → approval gate → provider path; long tasks via `JobManager`.++## 8. Integration & reporting layers++- Integration: providers (exist) + identity mapper + Contract v2 registry discovery. Strategy per system: `INTEGRATION_STRATEGY.md`.+- Reporting: semantic snapshot → SQLite (exists) → Excel (openpyxl [NEW]) → Power BI (switch DAX or file-based). DuckDB/Parquet later (roadmap Phase D).++## 9. Packaging & installer++- Per-host add-in MSI/EXE (WiX or Inno) installing `.addin` + multi-target DLLs into version folders (build scripts exist: `docs/build-and-install-scripts.md`).+- Hub via `pipx install aec-model-bridge` or bundled runtime in the installer (decide at Phase 19; bundled favors non-programmers).+- MCP client config via existing `server.json` / marketplace listing (`docs/marketplaces.md`).++## 10. What belongs where++| Concern | Home |+|---|---|+| Anything touching Revit API objects, transactions, ExternalEvent, dockable pane hosting | **C# add-in** |+| Providers, approval gate, module registry, semantic layer, identity, jobs, exporters, QA rules, report generation | **Python hub** |+| Stable, schema'd, metadata-rich contract for agents; one tool = one capability | **MCP tools** |+| Chat, plan cards, approve/reject, run log, report viewer (WebView2 HTML/JS) | **Plugin UI** |+| Multi-step reasoning, repo/dev automation, orchestration recipes | **Claude Code / agent layer** |+| OAuth'd cloud data (Speckle/APS), file formats (IFC), BI (DAX) | **External integrations via providers** |+| Preview meshes only — GH previews, Navis overlay. **Never** deliverable geometry; native elements or explicit fallback with user consent | **DirectShape / dumb geometry** |diff --git a/docs/product/PLUGIN_MODULE_SYSTEM.md b/docs/product/PLUGIN_MODULE_SYSTEM.mdnew file mode 100644index 0000000..71ee495--- /dev/null+++ b/docs/product/PLUGIN_MODULE_SYSTEM.md@@ -0,0 +1,149 @@+# Plugin Module System++A **module** is the unit of product functionality: a manifest + a Python class in the hub that composes existing MCP tools into user-facing commands, plus optional UI cards and QA rules. C# changes are needed only when a module requires a new host-side primitive.++## 1. Discovery++Three sources, merged by the **ModuleRegistry** (new hub component, sibling of `ProviderRegistry`):++1. **Built-in:** `revit_mcp_server/modules/<name>/` shipped with the wheel.+2. **User/firm:** `%LOCALAPPDATA%\AECModelBridge\modules\<name>\` (workspace-sandbox rules apply).+3. **Entry points:** `[project.entry-points."aec_model_bridge.modules"]` for pip-installed third-party modules.++Load order: built-in → entry points → user (user wins on id collision, with a logged warning). A module = directory with `module.json` + `module.py` (+ `rules/*.yaml`, `ui/*.html`, `templates/`).++## 2. Manifest format (`module.json`)++```json+{+ "id": "qaqc_checker",+ "name": "QA/QC Checker",+ "version": "0.3.0",+ "schema_version": 1,+ "min_hub_version": "1.3.0",+ "description": "Rule-based model health checks and issue tracking.",+ "author": "AEC Model Bridge",+ "license": "GPL-3.0-or-later",+ "requires_providers": ["revit", "graph"],+ "requires_tools": ["revit_get_warnings", "graph_audit_disconnected"],+ "permissions": ["model.read", "workspace.write"],+ "commands": [+ {+ "id": "run_health_check",+ "title": "Run Health Check",+ "surface": ["ribbon", "panel", "mcp"],+ "mcp_tool": "qaqc_run_health_check",+ "execution_mode": "async",+ "is_mutating": false,+ "destructive": false,+ "input_schema": {+ "type": "object",+ "properties": {+ "ruleset": {"type": "string", "default": "core"},+ "categories": {"type": "array", "items": {"type": "string"}}+ }+ },+ "output_schema": {"$ref": "schemas/findings.json"}+ },+ {+ "id": "apply_fixes",+ "title": "Apply Suggested Fixes",+ "surface": ["panel", "mcp"],+ "mcp_tool": "qaqc_apply_fixes",+ "execution_mode": "async",+ "is_mutating": true,+ "destructive": false,+ "requires_plan": true,+ "permissions": ["model.write"]+ }+ ],+ "ui": {"panel_card": "ui/findings_card.html", "icon": "assets/icon.svg"},+ "hooks": {"validate": "module:QaqcModule.validate", "on_result": "module:QaqcModule.log_summary"}+}+```++## 3. Command exposure++- **To users:** `surface: ["ribbon"|"panel"]` → the add-in queries the hub's `module_list_commands` at panel startup and renders buttons/cards. Ribbon slots are limited; modules mark at most one command `ribbon_priority`.+- **To MCP:** every command with `"mcp"` surface registers as tool `<module_id>_<command_id>` through a `ModuleProvider` adapter, indistinguishable from provider tools and carrying the same metadata (`is_mutating`, `destructive`, `execution_mode`, `permissions`).++## 4. Permissions++Declared in manifest, enforced by the hub at call time; the panel shows them at install/enable time (consent screen).++| Permission | Grants |+|---|---|+| `model.read` | read-only provider tools |+| `model.write` | mutating tools — **always through ActionPlan gate** |+| `model.delete` | destructive-flagged tools (separate consent) |+| `workspace.write` | file output inside workspace sandbox (exists) |+| `net.local` | other local switches (rhino/navis/pbi) |+| `net.cloud` | speckle/aps/graph-API tools |+| `python.host` | `revit_execute_python` / `rhino_run_python` escape hatches — expert-mode only, off by default |++No permission → tool call rejected with a structured error naming the missing grant.++## 5. I/O schema, validation & logging hooks++- **Schemas:** JSON Schema per command (inline or `schemas/*.json`). Hub validates input before dispatch and output before return — a module that returns off-schema fails loudly in CI (contract test iterates all modules, same pattern as `test_provider_contract.py`).+- **`validate` hook:** runs at plan time — semantic checks beyond schema (e.g. "sheet numbers unique"). Returns `ok | warnings[] | blockers[]`; blockers stop the plan before approval.+- **`on_result` hook:** post-execution — audit summary lines, issue-store updates, notifications. Hooks are sync, budgeted (fail-open with logged warning on timeout).++## 6. Rollback strategy++Modules never implement rollback themselves. They declare per command:++- `reversible: "undo"` — single named transaction; Revit undo suffices (default).+- `reversible: "inverse"` — module's `build_inverse(plan, before_state)` produces a counter-plan (e.g. parameter restore).+- `reversible: "none"` — irreversible (file exports are trivially none; model deletes need `model.delete` + explicit confirm).++The approval gate persists `before_state` captured at plan time for inverse-capable commands.++## 7. Versioning++- Module semver + `schema_version` (manifest format) + `min_hub_version` gate.+- Hub refuses to load incompatible modules with a clear panel message, never a crash.+- Command input schemas are append-only within a major version (add optional fields only) — same discipline as switch Contract v2 (ADR 0002).++## 8. Example modules (target roster)++| id | Tier | Composes | New host primitives needed |+|---|---|---|---|+| `model_inspector` | MVP | snapshot query, `revit_list_*`, `revit_get_element_*` | `revit.extract_snapshot` (C#) |+| `selection_tools` | MVP | `revit_get/set_selection`, filters, save/restore selections | — |+| `parameter_manager` | MVP | `revit_batch_set_parameters*`, diff grid, CSV roundtrip | — |+| `qaqc_checker` | MVP | rules → findings → issue store → fix plans | — |+| `report_generator` | MVP | `exporter_*`, `export_excel`, templates | — |+| `viewsheet_automator` | MVP | 10 existing sheet/view tools | — |+| `familytype_mapper` | P1 | family audit, `revit_replace_family_type` mapping tables | family metadata extraction |+| `facade_configurator` | P1 | zone spec → placement plans, variant mgmt | adaptive-component batch placement |+| `rhino_bridge` | P1 | 19 `rhino_*` tools, spec import | — |+| `speckle_ifc_bridge` | P1 | `speckle_*`, `ifc_*`, mapper | — |+| `data_exporter` | P1 | SQLite/Excel/Parquet lanes | — |+| `agent_reviewer` | P2 | second-model review of pending ActionPlans (flags risky plans before human sees them) | — |++## 9. QA rule format (used by `qaqc_checker`)++```yaml+# rules/core/rooms.yaml+- id: room.unplaced+ title: Unplaced rooms+ severity: warning # info | warning | error+ category: Rooms+ query: { source: snapshot, filter: { category: "OST_Rooms", placed: false } }+ message: "{count} unplaced room(s)"+ fix: null # or a command ref: { command: "qaqc.apply_fixes", args_template: {...} }++- id: door.no_fire_rating+ title: Doors missing fire rating+ severity: error+ category: Doors+ query:+ source: snapshot+ filter: { category: "OST_Doors", parameter: { name: "FireRating", empty: true } }+ fix:+ command: parameter_manager.batch_set+ args_template: { parameter: "FireRating", value_prompt: true }+```++Rule packs are versioned directories (`core`, firm packs under user modules dir); a rule that fails to evaluate is reported as `rule_error`, never crashes the run (cf. W7 failure cases).diff --git a/docs/product/SCAFFOLDING_TASK_LIST.md b/docs/product/SCAFFOLDING_TASK_LIST.mdnew file mode 100644index 0000000..b6fbaad--- /dev/null+++ b/docs/product/SCAFFOLDING_TASK_LIST.md@@ -0,0 +1,204 @@+# Scaffolding Task List++Buildable backlog for the agent swarm (roster + rules in `AI_AGENT_SWARM_PLAN.md`). Every phase carries: Epic · Subtasks · Owner · Files · Notes (technical / Revit-BIM concepts / integration points) · Tests · Acceptance / DoD · Dependencies · Risks. Task IDs `P<phase>.<n>`. MVP = Phases 0–10 + 16–19 subset (see `MVP_EXECUTION_PLAN.md`).++Global DoD (applies to every phase): builds green (pytest+ruff; `dotnet build` net48+net8), no broken doc links, `tools-generated.md` regenerated if the tool surface changed, handover block written, human sign-off on the phase.++---++## Phase 0 — Repository audit & documentation consolidation+**Epic:** make the repo tell one true story before building on it. **Owner:** Documentation + Repo Audit + Release. **Deps:** none — start immediately.+- P0.1 Present audit §9 deletion list to Sam; on approval remove stray binaries (`docs/Untitled*.3dm*`, `Omni_LiveGeometryStats.csv`), untrack `dist/`, caches, empty `metrics/`; extend `.gitignore`. ⚠ human approval; consider `git rm --cached` vs history rewrite (92 MB files — recommend BFG later, separate decision).+- P0.2 Move `docs/ecosystem-strategy-and-monetization.md` to private repo; leave stub pointer. ⚠ human approval.+- P0.3 Fix `CLAUDE.md`: Navisworks port 3005→3002, replace dead `docs/agent-task-plan.md` pointer with `docs/product/SCAFFOLDING_TASK_LIST.md`, retitle to AEC Model Bridge.+- P0.4 Fix README broken links (`docs/tools.md`, `docs/architecture.md`, `docs/integration-expansion-handover.md`) → real targets; correct Rhino transport description (HTTP :3004, not SSE :9876); mark Navisworks/PowerBI "in progress" honestly.+- P0.5 Rewrite `docs/security.md` against as-built (provider system, ADR 0002, no phantom config keys). Flip ADR 0001 status Proposed→Accepted.+- P0.6 Version reconciliation: bump `pyproject.toml`, `RevitBridge.csproj`, `server.json` to match CHANGELOG 1.2.0 (or re-cut CHANGELOG; Release agent proposes).+- **Tests:** link checker over docs; grep for "3005", "agent-task-plan", "Omni-Bridge" (outside legacy-note contexts) returns nothing.+- **Acceptance/DoD:** fresh reader gets zero contradictions between README, CLAUDE.md, docs/, and code. **Risk:** deleting something Sam wanted (mitigated: list-first rule).++## Phase 1 — Product definition+**Epic:** lock the product package. **Owner:** Product Architect. **Deps:** P0 readable repo.+- P1.1 Review `docs/product/*` (this package) with Sam; resolve open questions in `DECISIONS_AND_RISKS.md`.+- P1.2 Reconcile `docs/roadmap-and-plans.md` with this package (roadmap = strategy narrative; this = buildable plan; add cross-links, delete duplicated phase tables from roadmap).+- P1.3 Update README positioning to the vision doc's one-liner.+- **Acceptance:** Sam signs decisions D-001…D-012; no competing roadmaps. **Risk:** scope re-litigating — timebox.++## Phase 2 — Plugin-style app architecture+**Epic:** freeze contracts so waves can parallelize. **Owner:** Product Architect + MCP Tooling + Revit API. **Deps:** P1.+- P2.1 ADR-0008: approval gate + ActionPlan lifecycle (states: draft→validated→pending→approved/rejected→executed→rolled-back).+- P2.2 ADR-0009: module system (manifest schema v1 frozen from `PLUGIN_MODULE_SYSTEM.md` §2).+- P2.3 ADR-0010: snapshot schema v1 frozen from `SEMANTIC_BIM_DATA_MODEL.md` §2.+- P2.4 ADR-0011: panel architecture (WebView2, message bridge, hub endpoints the panel calls).+- **Acceptance:** four ADRs Accepted; contract-freeze points from swarm plan in force. **Risk:** over-designing before contact with Revit reality — ADRs stay ≤2 pages each.++## Phase 3 — Revit-native foundation+**Epic:** the C# add-in becomes a safe, modern substrate. **Owner:** Revit API (+ Security/Safety review). **Files:** `packages/revit-bridge-addin/src/**`. **Deps:** P2.+- P3.1 Flip Contract v2 to default (LegacyMode opt-in via `MCP_REVIT_LEGACY_PORT=true`); hub discovery via registry files already exists — verify end-to-end. ⚠ human approval (breaks old setups).+- P3.2 Transaction discipline: audit all 110 handlers in `BridgeCommandFactory.cs`; enforce named `Transaction`/`TransactionGroup` pattern (`"AMB: <cmd> #<action_id>"`); thread `action_id` through `/execute` payload.+- P3.3 New command `revit.extract_snapshot` (full + `dirty_only` incremental using the existing `DocumentChanged` hook) emitting ElementRecords per schema; streams to workspace file, returns path + counts (never inline 50k elements).+- P3.4 New command `revit.get_snapshot_delta` (dirty-list since snapshot_id).+- P3.5 Dead-tree resolution: per-subsystem verdict on `src/Commands/**` (revive as `[BridgeCommand]`s or delete). ⚠ human approval on deletes.+- **Revit concepts:** FilteredElementCollector perf, ElementMulticategoryFilter, UniqueId vs ElementId, DocumentChanged, workshared ownership. **Integration:** feeds Phase 6.+- **Tests:** e2e snapshot on canonical model (Phase 17 model, early script version); handler transaction-name audit is a unit test over reflection metadata.+- **Acceptance/DoD:** snapshot of 10k-element model < 30 s full / < 2 s incremental (ADR 0007 spirit); v2 auth on by default; all handlers carry named transactions. **Risks:** perf on huge models (mitigate: parallel param reads are NOT thread-safe — single-thread extraction, measure first); regressions across net48/net8 (CI matrix).++## Phase 4 — MCP tool foundation+**Epic:** one hub, honest metadata, approval gate. **Owner:** MCP Tooling (+ Security/Safety). **Files:** `packages/mcp-server-revit/src/revit_mcp_server/**`. **Deps:** P2 (can start parallel to P3).+- P4.1 Extend `ProviderTool` with `is_mutating/destructive/execution_mode/permissions`; backfill all ~170 tools (mirror C# `[BridgeCommand]` attrs via `/capabilities`).+- P4.2 Approval gate: `plan_actions`, `list_pending_plans`, `approve_plan`, `reject_plan`, `rollback_plan` tools + `ApprovalGate` middleware rejecting un-planned mutating calls when `approval_mode=required`; persist plans + before-state in workspace.+- P4.3 Register `NavisworksProvider` in `mcp_server.py`; widen to the 16 C# commands.+- P4.4 Retire legacy: migrate tests off `server.py` + `tools/` + old `schemas.py`, then archive. ⚠ human approval. Fix or delete the `proxy._connect()` bug with it.+- P4.5 Wire or park `PowerBIProvider` (decision D-009); if wired: register + health-only for now.+- P4.6 Regenerate `docs/tools-generated.md` — no more "?" columns; document gate tools.+- **Tests:** `test_provider_contract.py` asserts metadata on every tool; new `test_approval_gate.py` (mutating-without-plan rejected, plan lifecycle, rollback restores before-state via mock provider).+- **Acceptance/DoD:** single server; every tool metadata-complete; gate enforced; Navisworks reachable. **Risks:** breaking existing users' tool list (additive only; renames need approval), plan-store corruption (atomic writes).++## Phase 5 — Plugin module registry+**Epic:** modules as first-class citizens. **Owner:** Plugin App. **Files:** `revit_mcp_server/modules/__init__.py`, `module_registry.py`, `ModuleProvider` adapter. **Deps:** P4.+- P5.1 ModuleRegistry (discovery: built-in, entry points, user dir; id-collision policy; version gates).+- P5.2 `module.json` validation (JSON Schema), permission enforcement at dispatch, validate/on_result hooks with timeout budget.+- P5.3 `ModuleProvider` exposing module commands as MCP tools; `module_list_commands` endpoint for the panel.+- P5.4 Hello-world module + module-author guide (`docs/module-authoring.md`).+- **Tests:** contract test iterating all discovered modules (schema-valid manifests, schemas resolve, permissions known); hostile-manifest fixtures.+- **Acceptance/DoD:** drop-in module dir appears as tools + panel commands with zero hub code changes. **Risk:** entry-point security (user modules run arbitrary code — document trust model; firm dir requires explicit enable).++## Phase 6 — Semantic BIM data layer+**Epic:** the snapshot/diff/reconcile engine. **Owner:** Semantic BIM Data. **Files:** `revit_mcp_server/semantic/**`, `schemas/amb.snapshot.v1.json` etc. **Deps:** P3 (extract command) + P4.+- P6.1 Pydantic models + JSON Schemas for snapshot/delta/zone/variant (from `SEMANTIC_BIM_DATA_MODEL.md`).+- P6.2 `snapshot_take` (calls `revit.extract_snapshot`, stores, indexes to SQLite via existing exporter), `snapshot_query` (filter DSL used by rules + W1), `snapshot_diff`.+- P6.3 Delta reconciliation → ActionPlan (three-way conflict detection per §5).+- P6.4 Mapper integration: every snapshot registers uids → `amb_uid`.+- **BIM concepts:** UniqueId stability, phase/design-option filtering, workset ownership, storage types + spec units.+- **Tests:** golden snapshot on canonical model; diff of known edit script == expected; conflict fixtures.+- **Acceptance/DoD:** W1 questions answerable from snapshot alone; diff correct on 20-edit scenario. **Risk:** schema churn after freeze (append-only rule).++## Phase 7 — Model inspection workflows (W1–W3)+**Epic:** killer workflow #1 ships. **Owner:** Plugin App (+ QA/QC BIM for query DSL review). **Files:** `modules/model_inspector/**`, `modules/selection_tools/**` (read side). **Deps:** P5+P6.+- P7.1 `model_inspector` module: `ask` (NL → snapshot_query via agent), `summarize_model`, `list_groups`, element chips payload (uid, label, category) for panel.+- P7.2 Selection inspect: `inspect_selection` (W2 card: type/host/level/params/warnings).+- P7.3 Saved queries (named, per-doc, re-runnable).+- **Tests:** query results == Revit schedule counts on canonical model (golden numbers).+- **Acceptance/DoD:** the W1 user story demo runs end-to-end in Claude Code (panel comes in P16). **Risk:** LLM query hallucination → `snapshot_query` DSL is the only query path; agent must emit DSL, hub validates it.++## Phase 8 — Selection & model group workflows (W2 write side, W4)+**Epic:** first gated writes. **Owner:** Plugin App. **Deps:** P7 + gate (P4).+- P8.1 `selection_tools` write side: set/save/restore selections; select-by-query.+- P8.2 Group ops as plans: rename/ungroup/convert (W4) with affected-instance counts in plan preview.+- **Revit concepts:** Group/GroupType semantics, attached details, view-specific membership.+- **Tests:** ungroup plan on canonical model → undo restores; plan preview counts == actual.+- **Acceptance/DoD:** W4 demo with approval + rollback. **Risk:** group edge cases (nested, mirrored) — document unsupported cases explicitly rather than half-support.++## Phase 9 — Parameter / family / type workflows (W5, W6)+**Epic:** killer workflow #3. **Owner:** Plugin App + Revit API (type params edge cases). **Files:** `modules/parameter_manager/**`, `modules/familytype_mapper/**`. **Deps:** P8.+- P9.1 `parameter_manager`: filter → diff grid → plan → apply → inverse plan (before-values). CSV import/export lane.+- P9.2 Plan-time validation: storage type, readonly, binding, type-vs-instance, unit conversion via spec (SI internal).+- P9.3 `familytype_mapper` read side: family audit (W6 core rules), type mapping tables (feeds W11 later).+- **Tests:** batch-set 500 params → re-read == intended; rollback == original; workshared-owned element skip path (mock).+- **Acceptance/DoD:** W5 user story end-to-end incl. rollback; wrong-type writes impossible (blocked at plan). **Risks:** formula/readonly params, shared-param GUID collisions.++## Phase 10 — QA/QC validation workflows (W7, W9)+**Epic:** killer workflow #2. **Owner:** QA/QC BIM. **Files:** `modules/qaqc_checker/**`, `rules/core/**`. **Deps:** P6 (+P9 for fixes).+- P10.1 Rule engine: YAML rule packs (format in `PLUGIN_MODULE_SYSTEM.md` §9) over `snapshot_query` + `graph_*` audits + `revit_get_warnings`; rule failure = reported, never fatal.+- P10.2 Core pack (~15 rules from W7 MVP list) with severities + fix templates.+- P10.3 Issue store (SQLite, per doc-guid): lifecycle open→resolved(auto on re-check)→orphaned(uid miss).+- P10.4 Async run via JobManager with progress.+- **Tests:** seeded-defect canonical model → golden findings file byte-diffed in CI.+- **Acceptance/DoD:** one-click health check < 2 min on canonical model; findings clickable (uid list). **Risk:** rule quality = product reputation — every core rule reviewed by Sam against real-project intuition.++## Phase 11 — Façade configurator workflows (W11) — post-MVP flagship+**Epic:** the differentiator demo. **Owner:** Rhino/Grasshopper + Semantic BIM Data + Revit API. **Files:** `modules/facade_configurator/**`, `packages/rhino-bridge-addin/**`, adaptive family templates in `fixtures/families/`. **Deps:** P6, P9; Rhino bridge exists.+- P11.1 Zone spec exporter: GH definition + `rhino_run_python` script emitting `amb.facade_zone/1` (promote `scratch/glass_diamond.py` conventions — gpt/cc, counts_expected).+- P11.2 `facade_apply_zone`: spec → type mapping → adaptive placement plan (batch `revit_place_family_instance` or new batched C# command if perf demands).+- P11.3 Variant management: spec-hash variants, re-apply as diff (update/create/delete itemized).+- P11.4 Preview lane: DirectShape with PREVIEW marker + auto-cleanup, behind explicit user opt-in.+- **BIM concepts:** adaptive components, curtain systems, family loading, panel count reconciliation (no silent skips).+- **Tests:** 1476-panel golden case — Rhino count == plan count == placed count == mapping rows.+- **Acceptance/DoD:** tune-in-Rhino → approve variant → native panels in Revit → re-tune → diff-apply. **Risks:** placement perf (batch command likely needed — measure at 500 panels first), family availability UX.++## Phase 12 — Rhino.Inside.Revit / Grasshopper bridge (W12, W13-GH)+**Epic:** meet computational designers in-process. **Owner:** Rhino/Grasshopper. **Deps:** P11.+- P12.1 GH components (`AMB Connect`, `AMB Snapshot`, `AMB Zone Out`, `AMB Plan Preview`) wrapping hub HTTP.+- P12.2 RiR exemplar definition + supported version matrix doc.+- P12.3 Rhino bridge hardening: Contract v2 (dynamic port + token) replacing hardcoded :3004.+- **Tests:** exemplar runs scripted; version matrix manually checklisted per release.+- **Acceptance/DoD:** W12 story demo; no write path bypasses gate. **Risk:** RiR/Rhino/Revit version triangle — pin and document, don't chase.++## Phase 13 — Speckle / IFC / Navisworks bridge (W15)+**Epic:** coordination loop closes. **Owner:** Integration. **Deps:** P4 (Navis registration), P6.+- P13.1 Speckle: snapshot publish/receive (`speckle_publish_version` lane) → delta → reconciliation.+- P13.2 IFC: Revit-vs-IFC comparison report (mapper GlobalId↔UniqueId); `ifc_validate` surfaced in qaqc pack.+- P13.3 Navisworks: clash results → mapper → Revit selection + issue-store import; viewpoint per finding.+- **Tests:** RVT+IFC+NWF fixture triple; mocked Speckle server (exists) + live smoke.+- **Acceptance/DoD:** "show clash #12 in Revit" works; IFC comparison report on fixtures. **Risk:** GUID mapping fidelity across export paths — validate early with the fixture triple.++## Phase 14 — Excel / Power BI / DuckDB reporting (W8, W16)+**Epic:** management-grade outputs. **Owner:** Integration + Report Generator module (Plugin App). **Deps:** P6, P10.+- P14.1 `export_excel` (openpyxl): elements/params/findings workbook + formatted QA summary sheet.+- P14.2 `report_generator` module: templates, destinations (sandboxed), schedule-able via jobs.+- P14.3 Power BI file lane: SQLite (exists) + shipped `.pbit` template; live lane per D-009 (DAX health + `powerbi_execute_dax`).+- P14.4 Parquet mirror + DuckDB queries (P2 priority — can slip).+- **Tests:** golden workbook diff; `.pbit` refresh smoke (manual checklist); SQLite↔Parquet row parity.+- **Acceptance/DoD:** W8 demo: health check → Excel + PBI dashboard refresh. **Risk:** schema evolution — `schema_version` column enforced from first export.++## Phase 15 — AI agent orchestration+**Epic:** multi-step, multi-app recipes (roadmap Phase C, scoped down). **Owner:** MCP Tooling + Product Architect. **Deps:** P10, P13.+- P15.1 Recipe format (YAML: steps = tool calls with arg templating + conditionals) + run records.+- P15.2 `recipe_run/status/list` tools; recipes respect the gate (mutating steps produce plans).+- P15.3 Three shipped recipes: nightly-health-check→Excel; export→clash→issue-import; snapshot→Speckle publish.+- P15.4 `agent_reviewer` module (P2): second-model review of pending plans.+- **Acceptance/DoD:** the three recipes run end-to-end. **Risk:** building a workflow engine — keep it linear steps + conditionals, no DAG until pulled.++## Phase 16 — UI/UX & plugin command surface+**Epic:** the product face (runs parallel from P5 behind endpoint contracts). **Owner:** UI/UX + Revit API (pane host). **Files:** `packages/revit-bridge-addin/src/UI/**`, `panel/**`. **Deps:** P2 ADR-0011; integrates against P4/P5/P7/P10 endpoints.+- P16.1 Dockable pane host (`IDockablePaneProvider` + WebView2 + message bridge).+- P16.2 Panel app: chat view, plan cards (approve/reject/approve-similar), findings tab, run log (audit tail), settings.+- P16.3 Ribbon: 5 product commands (Open Panel, Health Check, Pending Actions, Reports, Settings); keep existing Connection panel.+- P16.4 Empty/error states: hub down, no doc, stale snapshot, offline LLM.+- **Tests:** panel↔hub contract tests (endpoint fixtures); manual UX checklist per release; WebView2 runtime absence fallback message.+- **Acceptance/DoD:** the W7+W5 stories fully driven from the panel by a non-programmer. **Risks:** WebView2 in Revit process (memory, load order — spike first in P16.1); UI scope creep (card set is fixed for MVP).++## Phase 17 — Testing & sample models+**Epic:** trust through goldens. **Owner:** Testing (starts Wave 1 — the model script is a P3 dependency!). **Files:** `fixtures/**`, `tests/e2e/**`, `.github/workflows/**`.+- P17.1 Canonical test model **generator script** (idempotent: builds the RVT via bridge tools — levels, 200 walls, doors/windows, rooms incl. seeded defects, views/sheets, groups, families). Script, not binary, so it's diffable and per-version buildable.+- P17.2 Seeded-defect register (which rule catches what) → golden findings.+- P17.3 e2e harness extending `test_e2e.py`: hub+add-in round trip, gate paths, snapshot goldens.+- P17.4 CI: pytest+ruff; dotnet matrix net48/net8 (Nice3point NuGet); doc link check; e2e nightly on self-hosted runner with Revit (or scripted local `make e2e` if no runner). ⚠ decide runner story (D-012).+- **Acceptance/DoD:** every MVP workflow has a golden; CI green gate on PRs. **Risk:** Revit-in-CI licensing → local scripted fallback documented.++## Phase 18 — Documentation & tutorials+**Epic:** docs a firm can adopt from. **Owner:** Documentation. **Deps:** MVP features stable.+- P18.1 MkDocs site (roadmap Phase F): install, quickstart, workflows (one page per W#), module authoring, tool reference (generated), security model.+- P18.2 Three tutorials: "Ask your model", "Health check + fix", "Batch parameters from Excel".+- P18.3 Video/demo script for the flagship demo (P11).+- **Acceptance/DoD:** cold-start user completes tutorial 1 in <15 min without help.++## Phase 19 — Packaging, installer, release+**Epic:** double-click install. **Owner:** Release (+ Security for signing). **Deps:** P16.+- P19.1 Add-in installer (WiX/Inno): `.addin` + multi-target DLLs into per-version folders; WebView2 runtime bootstrap.+- P19.2 Hub packaging decision D-010 (pipx vs bundled runtime) implemented; `server.json`/marketplace listings updated (`docs/marketplaces.md`).+- P19.3 Release pipeline: tag → build matrix → DLL license scan (exists) → artifacts → CHANGELOG cut. Code-signing cert acquisition. ⚠ human: signing + publishing.+- **Acceptance/DoD:** clean Windows machine → installer → tutorial 1 works. **Risk:** unsigned binaries = SmartScreen friction (budget for cert).++## Phase 20 — Enterprise readiness+**Epic:** what firms ask before rollout. **Owner:** Security/Safety + Release.+- P20.1 Central config (firm-managed settings file: approval_mode lockdown, module allowlist, telemetry off switch).+- P20.2 Audit-ledger export + retention policy; threat model doc refresh.+- P20.3 Workshared/BIM360 model behavior matrix (ownership, sync etiquette: never `revit_sync_to_central` without explicit plan).+- P20.4 License enforcement for commercial modules (open-core seam — mechanism only, pricing stays private).+- **Acceptance/DoD:** enterprise checklist doc answerable "yes" line-by-line.++## Phase 21 — Future roadmap+**Epic:** parked, explicitly. **Owner:** Product Architect. Contents: remote MCP/REST facade (roadmap H), BYO-LLM guides, Dynamo package (W13-D), APS Issues at scale, MS Graph, additional switches (Archicad/Tekla — roadmap G), marketplace, IDS full support, BCF. Each graduates only via a `DECISIONS_AND_RISKS.md` entry with a pull signal (user request, revenue, demo need).++---++## Dependency spine++```+P0 → P1 → P2 ─┬→ P3 (C#) ──┐+ ├→ P4 (hub) ─┼→ P5 → P6 → P7 → P8 → P9 → P10 ─┬→ P11 → P12+ └→ P17.1 ────┘ (P16 UI parallel from P5)├→ P13 → P15+ └→ P14+P16+P17+P18 → P19 → P20 P21 parked+```diff --git a/docs/product/SEMANTIC_BIM_DATA_MODEL.md b/docs/product/SEMANTIC_BIM_DATA_MODEL.mdnew file mode 100644index 0000000..6d7905d--- /dev/null+++ b/docs/product/SEMANTIC_BIM_DATA_MODEL.md@@ -0,0 +1,152 @@+# Semantic BIM Data Model++The shared data layer that W1/W7/W5 (MVP) and W11/W14 (roundtrip) all consume. Builds on the existing `IdentityMapper` (`aec_translate_id`, `aec_register_mapping`) and `SemanticGraph` provider; adds the element-level **snapshot** and **roundtrip** schemas that don't exist yet.++## 1. Identity strategy++- **Primary key: Revit `UniqueId`** (episode GUID + id — stable across sessions, survives central/local roundtrips). Every record, finding, mapping, and audit entry keys on it.+- **`ElementId` is a cache, never persisted as identity** — it can change (workshared reassignments, audit ops). Stored alongside for fast API calls within a session, always re-resolvable from UniqueId.+- **Cross-app identity** via the existing mapper: `(app, native_id) ↔ amb_uid`. Revit UniqueId, IFC GlobalId, Speckle object id, Rhino object GUID, Navisworks item GUID all register against one `amb_uid` (ULID).+- **Document identity:** Revit `Document.CreationGUID` + `WorksharingCentralGUID` when workshared; SaveAs detection prompts re-anchor (cf. W9 failure case).++## 2. Snapshot schema (JSON, one document per extraction)++```json+{+ "schema": "amb.snapshot/1",+ "snapshot_id": "01J...ULID",+ "taken_at": "2026-07-08T14:02:11Z",+ "source": {+ "app": "revit", "app_version": "2025.2",+ "doc_guid": "...", "central_guid": "...", "doc_title": "Tower_A.rvt",+ "units": "SI", "phase_map": {"3": "Existing", "4": "New Construction"}+ },+ "elements": [ { ...ElementRecord... } ],+ "relations": [ { ...Relation... } ],+ "types": [ { ...TypeRecord... } ],+ "counts": {"by_category": {"OST_Doors": 214}}+}+```++**ElementRecord:**++```json+{+ "uid": "revit-uniqueid-string",+ "amb_uid": "01J...",+ "element_id": 316221,+ "category": "OST_Doors",+ "class": "FamilyInstance",+ "type_uid": "type-uniqueid",+ "family": "Door_Single_Flush", "type_name": "0915 x 2134mm",+ "level_uid": "…", "phase_created": 4, "phase_demolished": null,+ "design_option": null, "workset": "Shell",+ "group_uid": null, "host_uid": "wall-uniqueid",+ "room_uids": {"from": "…", "to": "…"},+ "location": {"kind": "point", "xyz": [12.4, 3.1, 0.0], "rotation": 1.5708},+ "bbox": {"min": [..], "max": [..]},+ "params": {+ "Mark": {"v": "D-104", "storage": "String", "instance": true, "readonly": false},+ "FireRating": {"v": null, "storage": "String", "instance": true, "readonly": false},+ "Width": {"v": 0.915, "storage": "Double", "spec": "Length", "instance": false}+ },+ "geometry_ref": {"kind": "none|bbox|mesh_uri", "uri": null},+ "materials": ["mat-uid-1"]+}+```++Notes:+- **Units: SI internally everywhere** (metres/radians), matching the Rhino bridge convention; converters at the edges only.+- `params` carries storage type + spec + writability → plan-time validation for W5 needs no extra round-trip.+- `geometry_ref` keeps snapshots light: geometry is *referenced* (bbox by default; mesh exported on demand to workspace files), never inlined. BIM semantics travel; dumb geometry stays home.++**Relations** (edges, feeding/mirroring the existing `graph_*` provider):++```json+{"kind": "hosts", "from": "wall-uid", "to": "door-uid"}+{"kind": "bounds", "from": "room-uid", "to": "wall-uid"}+{"kind": "on_level", "from": "door-uid", "to": "level-uid"}+{"kind": "in_group", "from": "elem-uid", "to": "group-uid"}+{"kind": "opening_in", "from": "opening-uid","to": "wall-uid"}+{"kind": "on_sheet", "from": "view-uid", "to": "sheet-uid"}+{"kind": "references_grid", "from": "col-uid", "to": "grid-uid"}+```++Wall/opening/window/door chains are thus first-class queryable: `door —hosted_by→ wall ←opening_in— opening`, room adjacency via shared `bounds` walls.++**TypeRecord:** `{uid, category, family, type_name, params{...}, family_source: "system|loadable|inplace"}` — feeds W6 family validation and W11 type mapping.++## 3. Domain specifics++- **Model groups:** `group_uid` on members + `GroupRecord {uid, group_type_uid, member_uids[], instance_count}`; W3/W4 read this, never raw geometry.+- **Rooms/spaces:** placed/unplaced/unenclosed state captured at extraction (`placed: bool`, `area: m²`, `bounding: [wall_uids]`) — the W7 room rules run on snapshot alone.+- **Levels/grids:** always extracted (cheap, universally referenced); elements carry `level_uid` + optional grid refs.+- **Materials/layers:** `MaterialRecord {uid, name, class, appearance_hash}`; wall compound structure as ordered layer list on the TypeRecord — needed for façade/IFC comparisons.+- **Façade zones (W11):**++```json+{+ "schema": "amb.facade_zone/1",+ "zone_id": "tower-a-south",+ "host": {"kind": "loft_surface|curtain_system|mass_face", "ref": "rhino:guid|revit:uid"},+ "grid": {"u_divs": 20, "v_divs": 36, "seam": "v0"},+ "panels": [+ {"pid": "A_03_17", "panel_type": "A", "corners_m": [[x,y,z],[..],[..],[..]],+ "target_family": "AMB_GlassPanel_Adaptive", "type_map": "glass-clear",+ "params": {"Area": 2.31}, "amb_uid": null}+ ],+ "counts_expected": {"A": 720, "B": 684, "bot": 36, "top": 36}+}+```++`counts_expected` enforces the no-silent-skip rule (the 1476-panel discipline from CLAUDE.md); `amb_uid` fills on placement → re-apply becomes a diff, not a rebuild.++- **Design variants:** `VariantRecord {variant_id, zone_id, spec_hash, applied_at, plan_id, element_uids[]}` — variants are compared by spec, applied as plans, and reversible as plan inverses.++## 4. Change tracking++- Snapshots are immutable, ULID-ordered. `snapshot_diff(a, b)` → `{added[], removed[], modified[{uid, param_changes{...}, moved: bool}]}`.+- The add-in already hooks `DocumentChanged` — extend it to append touched ElementIds to a session dirty-list, so incremental snapshot refresh extracts only dirty elements (big-model performance, ADR 0007 budgets).+- Audit ledger entries reference `snapshot_id` at plan time → every approved change is anchored to what the user actually saw.++## 5. Roundtrip format (W14)++A **delta document** — the only thing external tools (GH, Excel, Speckle apps) send back:++```json+{+ "schema": "amb.delta/1",+ "base_snapshot": "01J...",+ "actions": [+ {"op": "update", "uid": "door-uid", "set": {"FireRating": "60"}},+ {"op": "create", "temp_id": "t1", "class": "FamilyInstance",+ "family": "AMB_GlassPanel_Adaptive", "type_name": "glass-clear",+ "placement": {"kind": "adaptive_points", "points_m": [[..],[..],[..],[..]]},+ "set": {"Mark": "P-0317"}},+ {"op": "delete", "uid": "old-panel-uid", "reason": "variant re-apply"}+ ]+}+```++Reconciliation (hub): resolve uids against **live** model → three-way check vs `base_snapshot` (conflict = live changed since base → flag, never overwrite) → produce ActionPlan → approval gate → apply → register created `temp_id → UniqueId` mappings.++## 6. What is needed to recreate native Revit elements++Per creatable class, the delta must carry (validated at plan time, blocked with hints if missing):++| Class | Required |+|---|---|+| Wall | level_uid, wall type (or type_map), location curve (m), height/top constraint, structural flag |+| FamilyInstance (hosted) | family+type loadable in doc, host_uid, placement point/face ref, level_uid |+| FamilyInstance (adaptive) | family+type, N adaptive points in order |+| Floor/Roof | level_uid, type, boundary loops (m), slope data |+| Room | level_uid, phase, location point (placed) — geometry comes from bounding walls |+| Sheet/View | titleblock type / view template uid, number+name (uniqueness pre-checked) |+| Group instance | group_type_uid, insertion point |++Type-mapping tables (`familytype_mapper` module) translate external names → loaded Revit types; unresolvable mappings are plan blockers, **never** DirectShape fallbacks unless the user explicitly opts in (`fallback: "directshape_preview"`).++## 7. Storage++- Snapshots/deltas: JSON (gzip) in workspace `snapshots/`; latest also mirrored to SQLite via existing `exporter_to_sqlite` schema for SQL querying (one schema, documented, `schema_version` column).+- Mappings: existing mapper store. Issues: `issues.sqlite` (W9). Audit: JSONL ledger (architecture §5).