Date: 2026-06-21 Status: canonical execution spec for CSM app + fixed 12d macro alignment Purpose: replace fragmented interpretation with one build contract for agents working on CSM.

This document consolidates the current CSM vision and macro architecture from:

• docs/cm_csm_adac_aspec_product_vision.md
• docs/CSM_ONE_VISION.md
• docs/CSM_VISION_IMPLEMENTATION_AUDIT_2026-06-20.md
• docs/MACRO_ARCHITECTURE_AND_PLAN.md
• docs/CSM_Macro_Vision_Explainer.html
• docs/TWO_FILE_CONVERTER_SETTINGS_ARCHITECTURE.md

When this document and an older dated note disagree, follow this document and then update the older note only if it is still actively used.

CSM is the Client Schema Manager for custom-attribute client delivery. It is the Stage 2 system that stores the client schema, Veris mapping, runtime profile, executable rule plan, and delivery evidence.

CM owns the Veris master codelist and Veris-native clients. CSM owns custom client schemas and produces the full CSM export stack from its own DB plus synced CM reference data.

The boundary is:

CM: Veris master code/attribute/choice truth + client-code to Veris-code bridge.
CSM: client schema, attribute mapping, value maps, rules, runtime profile, exports, evidence.
12d macro: one fixed runtime/apply engine that reads CSM data and writes attributes in 12d.

CSM must not become a set of per-client 12d macros. CSM generates data and runtime packages; the production macro remains fixed.

The supported workflow is:

new client onboarding
  -> schema intake
  -> sync Veris master DB from CM
  -> Step 1: client feature/code -> Veris code bridge
  -> Step 2: client attribute -> Veris/client attribute source
  -> Step 3: client choice value maps
  -> Step 4: conditional rules and formulas
  -> Workstation human review/approval
  -> Project Runtime Profile values/references
  -> export runtime package and surveyor field-capture files
  -> 12d fixed macro reads saved profile and applies rules to selected source model
  -> validation/evidence
  -> delivery

Order is not optional. Do not map attributes before an approved feature/code bridge exists. Do not run macro/export work without a saved Project Runtime Profile for real jobs.

Current phase is still CSM app perfection and Vida-first pipeline proof.

Priority order:

• Perfect the CSM app workflow and validation gaps.
• Prove Vida full pipeline end-to-end through the fixed macro.
• Prove UnityWater.
• Treat MRBC and WAADAC as later focus clients unless a specific gate is being closed.

Only these surveyor export formats are primary for CSM:

• .12dfieldcodes
• Leica XML
• Trimble FXL

A-SPEC/GIS export paths are out of scope for CSM unless Abdullah explicitly changes the product boundary.

Every client attribute must state where its value comes from. This controls both the CSM app and the macro panel.

Client choice-backed attributes must use pickers. Free text is not permitted where a client choice list exists.

The CSM app Workstation must make the mapping chain visible, not hidden in dialogs:

• selected client/schema/feature context
• client feature/code and approved Veris bridge
• qualifier / match attribute key when one exists
• client attributes and Veris/source state
• requirement flags: client, field, profile, office
• source/value assignment state
• choice lists and per-code overrides
• value-map editor with global and per-feature tiers
• conditional rules and formula capability status
• validation issues with fix routes back to the relevant row

Batch operations are valid only when they preserve the same contract:

• bulk source-kind changes on selected attributes
• bulk attribute add/seed for selected features with approved bridges
• global value-map propagation only when value map scope is explicit
• no cross-client propagation

There is one production macro:

• source: exports/CSM_Apply_Profile.4dm
• compiled: exports/CSM_Apply_Profile.4do

The macro is a fixed UI + runtime engine. It reads CSM-authored data files and a project sub-profile; it does not receive generated client-specific 12dPL as the production path.

The macro panel must use native 12d controls:

• File_Box for CSM settings sidecar
• File_Box for Project Sub-Profile
• Source_Box for source model selection
• Choice_Box for client selection
• GridCtrl_Box for seeded groups, selected attributes, elements, evidence, and project values
• compact horizontal action rows
• Go to element based on stored model UID + element UID, not grid text alone

The panel tabs are:

Tree-first and flat-grid navigation are not competing visions. They are alternate navigation views over the same scanned grouped data. The editing surface is the right-pane grid/details, not the tree labels.

The group manager idea is core architecture, not a demo-only feature.

The safe order is:

resolve first
group second
bulk apply third
validate/report last

Do not group directly by raw Veris code, raw client code, feature name only, attribute count only, or choice list only.

The grouping key must include the resolved client identity and required writable attribute signature:

• client
• schema version
• client feature code
• Veris/field code
• geometry type
• discriminator/match attribute
• discriminator/match value
• required attribute paths
• attribute types
• choice-set IDs
• source kind
• runtime/reference requirements
• field/office/manual/derived classification

The macro/app must distinguish:

• bulk manual entry
• per-element manual entry
• field captured
• office entered
• project default
• fixed default
• value mapped
• geometry/reference derived
• formula/conditional
• blocked/unknown

Only bulk-manual or explicitly group-safe values may be written across every element in a group. Unique per-element values must be preserved unless the operator explicitly uses the per-element override path.

Each scan/apply run should produce or preserve evidence equivalent to:

• CSM_Group_Report.csv
• CSM_Group_Apply_Log.csv
• CSM_Missing_Required_Attributes.csv
• CSM_Blocked_Attributes.csv
• runtime evidence CSV from the fixed macro
• Output Window XML when live 12d proof is being claimed

At the operator boundary there are two files:

The settings sidecar is usually project_runtime_profile.12d_runtime.txt plus sibling CSV/JSONL runtime files. The sub-profile is usually CSM_client_subprofile.txt.

The macro must save entered values and selected references back to the sub-profile so reruns do not depend on unsaved UI state.

ADAC is not only an XML export target. It is a capture and asset-registration workflow. CSM must therefore prepare, validate, and evidence the 12d source data before claiming an ADAC-ready macro run.

External current/reference points:

• IPWEA-QNT lists ADAC as the public-works asset data standard and a source of truth for automated asset data management. Source: https://www.ipwea-qnt.com/Web/Web/Resources/Asset-Design-As-Constructed-ADAC.aspx
• IPWEA-QNT identifies ADAC 6.00 as the current version, but also tells suppliers to understand the organisation's capture guidelines. CSM must record the required version per client/project and not assume one national version fits every job.
• Council dates differ. Moreton Bay says the accepted schema version is detailed in its submission guideline and lists Version 4.2 as a former version; Sunshine Coast accepts ADAC 6.00 or 5.02 from 1 March 2026 and only ADAC 6.00 after 1 September 2026; Gold Coast uses date-based guideline/version windows, with ADAC 6.0 from 1 July 2026 and ADAC 5.01 until 30 June 2026.
• 12d describes ADAC as vendor-independent XML for 3D asset design and as-constructed data, managed by IPWEA, and identifies the ADAC XML as the source-of-truth exchange file. Source: https://www.12d.com/product/adac.html
• 12d's ADAC workflow treats data preparation as a first-class step before XML generation: establish company procedures, set up ADAC user menu/map files, create project header data, prepare data, assign ADAC asset types, run design/survey chains, validate, report, then write XML. 12d's manual also states that user attributes collected in the field or added during the Data Prep step are loaded into the required ADAC attributes, and that validation/report/write are separate proof steps. Source: https://downloads.12dmodel.com/v11/Documentation/12d_ADAC.pdf
• In 12d, producing ADAC XML requires one header string plus zero or more ADAC asset strings. ADAC asset creation depends on geometry family: the available asset choices are filtered by whether the selected string is point, line, or polygon-style geometry. CSM therefore cannot treat code grouping alone as ADAC proof; it must resolve group identity, geometry family, ADAC asset path, mandatory attributes, and the attribute placement path before XML validation is meaningful.
• 12d ADAC data-prep examples include project/header information, lot/plan/area creation, and extra asset attribute editors. The editor writes values as string attributes first, then ADAC chains move them into the ADAC attribute structure. CSM should mirror this separation: simple Project Values / group edits first, then controlled ADAC/client attribute placement.
• Council guidance, including Moreton Bay, Sunshine Coast, and Gold Coast, treats ADAC XML as part of the as-constructed handover package and expects real survey-accurate geometry, mandatory attribution, datum correctness, and client-specific capture rules, not only a schema-valid XML shell. The local MRBC fixture remains useful ADAC 4.2 evidence, but it must not be treated as proof of the current Moreton Bay live submission version without an explicit project/client decision. Sources: https://www.moretonbay.qld.gov.au/Services/Building-Development/DA-Process/ADAC, https://www.moretonbay.qld.gov.au/files/assets/public/services/building-development/development/adac-submission-guideline-5.0.pdf, https://www.sunshinecoast.qld.gov.au/development/development-tools-and-guidelines/infrastructure-guidelines-and-standards/as-constructed-data-standards-and-guidelines, https://www.goldcoast.qld.gov.au/Planning-building/Development-applications/Post-development-approvals-appeals/As-constructed-data-standards-and-guidelines

CSM's practical rule is:

client capture guideline + ADAC dictionary
  -> CSM schema/bridge/source-kind setup
  -> field/source data prepared in 12d with real asset geometry and attributes
  -> macro group scan and value application
  -> independent ADAC/attribute validation
  -> XML/export evidence

The CSM app now enforces this distinction in client_scope_items: confirmed ADAC-delivery scope rows must carry both standard_version and capture_guideline_source. Draft rows can remain incomplete during intake, but a row cannot be treated as confirmed production scope without those two fields.

For 12d source data, the macro must assume:

• there is a real selected source model, not fake shell rows
• grouped elements have stable feature/code identity and geometry type
• every ADAC-relevant group has an intended ADAC asset path, geometry family (Point, Polyline, or Polygon), mandatory attribute list, choice-value set, and client-specific additional mandatory attributes before it can be called ready
• ADAC/client attributes may live in 12d hierarchical attributes / vertex attribute bags, not only flat display text
• an ADAC-ready output eventually needs a valid header/project context, asset strings, geometry, required attributes, choice values, and client-specific additional requirements
• client capture guidelines can add requirements beyond the base ADAC dictionary
• polygon/area assets need sequential, valid geometry; a schema-valid output with incorrect polygon ordering or missing asset rows is not accepted
• project-level data such as owner/receiver, works approval, drawing number, construction date, coordinate datum, and vertical datum must be captured from the Project Runtime Profile where the client requires it
• runtime references such as cadastral lot models, road centreline strings, TINs, sewer mains, and polygon containment sources are operator-selected project data and must be saved back to the Project Sub-Profile
• validation evidence must distinguish base XSD validity, client capture-rule validity, and 12d project-data readiness; a zero-asset XML shell can prove the XSD path but not ADAC data readiness
• group bulk writes in the macro are allowed only as explicit operator actions and must record evidence rows with group, attribute, value, and affected element count because ADAC acceptance depends on proving what was written

CSM already has a raw ADAC dictionary parser for V501/V600 .xls dictionaries in csm/importers/adac_dictionary.py; use docs/adac_dictionary_parser.md when dictionary-driven schema/choice evidence is needed.

ADAC-specific CSM clients currently include at least MRBC, NswAdac, QLDADAC, WAADAC, and other explicitly ADAC-named clients. Vida/UnityWater can still teach the macro workflow, but ADAC acceptance must be proven on an ADAC client or an ADAC-shaped fixture.

Current MRBC proof matrix: docs\MRBC_ADAC_DATA_PREP_MATRIX_2026-06-21.md.

A claim is not accepted because code compiles or a UI opens. Acceptance requires proof at the right level:

• app change: focused tests, relevant full/partial pytest, QML lint where QML changed, and screenshot/click evidence when user-facing flow changed
• export change: export audit and generated files checked
• macro change: 12d call audit, clean compile, and live proof or explicit blocked-live status
• independent inspector claim: inspector evidence must read the 12d vertex Attributes bag and report vertex coverage such as checked_vertices; first-vertex-only or element/result-text proof is not enough for group/bulk apply
• live 12d macro claim: actual input/output comparison plus Output Window XML check

Current non-human acceptance blockers are tracked in docs/CSM_CANONICAL_GAP_REGISTER_2026-06-21.md.

• Do not generate per-client production macros.
• Do not fake seeded rows or accept fake shell data as proof.
• Do not call a visible 12d panel proven unless it has fresh visible-panel evidence.
• Do not use Draw_Box for the CSM review tables; use GridCtrl_Box.
• Do not use free text for known client choice values.
• Do not treat Attribute Manipulator or MetaConnex as the required runtime. They are adapters/reference patterns.
• Do not store project/job-specific values as permanent client-schema defaults.
• Do not apply one client's value maps or overrides to another client.
• Do not ignore Output\Vida and Output\<Client>; these are live CSM outputs and fixtures.
• Do not skip CSM Graphify before app/macro architecture claims.
• Do not claim ADAC readiness from generic CSM mapping alone; prove data-prep, 12d attribute placement, validation, and client capture-guideline alignment.

For any future CSM agent:

• Run python scripts\build_csm_knowledge_graph.py from the CSM root.
• Read this file and docs/CSM_CANONICAL_GAP_REGISTER_2026-06-21.md.
• Verify current state from disk.
• Patch the app/macro/tests/docs together when the workflow contract crosses boundaries.
• Rebuild the graph after meaningful Python/QML/exporter changes.
• Record evidence and update PROJECT_STATE.md when a gap is closed.