maintain
Use this to find out whether an existing dbt project or semantic layer (dbt, Ossie or SLayer) is correct against its warehouse, and if not, why. `maintain verify` checks the project as it stands; agai
SKILL.mdplugins/exmergo/dex/skills/maintain/SKILL.md
GitHubMaintain
Keep the repository correct as the world underneath it moves, on both of its
axes: the dbt project and the semantic layer. Drift is measured against a
baseline, the .dex/snapshot.json fingerprint of the warehouse map and of
each project layer. Detection is read-only; only reconcile proposes edits, and
transform apply is the one door that writes them.
Procedure
dex works in one loop: explore, transform, maintain. Every step runs one engine command, reads the single JSON envelope it prints, and decides the next step from that envelope.
- Explore before you write. Before writing or fixing SQL against a table
whose columns, types, grain, or join keys you have not verified in this
session, run
explore map(orexplore profile <tables>for a few named ones) and read its grain, keys, PII flags, and data-quality findings. Answer ad-hoc questions withexplore query, never with a raw database client. - Plan the change. Author the file content and hand it to
transform plan(orsemantic define|update|planfor the semantic layer). Nothing is written yet. Read the diffs, thewarnings, and, on a model that already exists,data.row_attribution; re-plan until they describe the change you meant. - Apply it.
transform apply <plan-id>writes the plan as a reviewable git diff. A human edit made since planning comes back asneeds_confirmation: re-plan against the current files. - Build and verify on dev. Run
transform build --target dev --verify. Readdata.verification.ranfirst, then relay the findings and anything undersuppressed. A green build says dbt ran, not that the rows are right. - Maintain.
maintain checkcompares the warehouse and the project with the.dex/snapshot.jsonbaseline, andmaintain verifychecks the project as it is now with no baseline.maintain reconcileproposes the fix as a plan, applied withtransform apply. Takemaintain snapshotafter a known-good build.
At every step: a needs_confirmation envelope waits on the user's decision (a
spend, or a dex config diff), never on yours; only a human clears a PII
flag; and you never edit the dbt project, .dex/config.yml, .dex/cache.json,
or .dex/plans/ by hand in place of the command that guards them.
Running the engine
Run commands from the user's project directory, so dex finds that project's configuration and writes its cache there. The wrapper path is absolute:
- In Claude Code,
${CLAUDE_SKILL_DIR}is supplied by the host. - In Codex or another Agent Skills host, resolve the directory containing this
installed
SKILL.mdfrom the path the host provides. Substitute that absolute directory for${CLAUDE_SKILL_DIR}in every command and reference below, including paths in the bundled reference files. Do not assume that environment variable exists, and do not change into the installed skill directory.
uv run --no-project --script "${CLAUDE_SKILL_DIR}/scripts/run.py" <subcommand> [flags]
Installed as a plugin or skill, run.py runs the exmergo-dex-core engine from
PyPI at the exact version its DEX_CORE_VERSION line pins, built from
https://github.com/exmergo/dex/tree/main/packages/dex-core.
uvis a prerequisite that Claude Code does not install. If the shell reportsuv: command not found, stop and tell the user to install it (brew install uvorpipx install uv, or the installer for their platform from the uv docs), then re-run. Tell them the command; never run an installer yourself. Never diff the warehouse against the project by hand instead: the drift axes and the baseline comparison live in the engine, so any other path is guesswork.- The first command in a fresh environment installs the engine and can take tens
of seconds. Offer
run.py --warmonce at setup to pay that up front; do not run it before ordinary commands.
Maintaining, step by step
- Pick the entry point. With a baseline, start at
maintain check: it sweeps every axis and ranks findings by blast radius. With no baseline, or on a project whose numbers were never right, start atmaintain verify, the one command here that needs no snapshot: it answers "is this right" rather than "what moved". - Read
warningsfirst, always. They carry the reasons the baseline may no longer describe the warehouse (a cache newer than the snapshot, a baseline pinned from a stale cache). That line bounds every finding above it and is never infindings. - Drill into one axis when a finding needs depth:
maintain schema(structure),maintain volume(row counts),maintain grain(key uniqueness, declared grains, fanout), ormaintain semantic(definitions and dangling references). Each takes optional<objects>. - Reconcile.
maintain reconcile [<class>]stores the proposed edits as a plan and prints aplan_id. Read each proposal'skind(rules below), then apply withtransform apply <plan-id>. A human edit made since detection comes back as a conflict, never an overwrite. - Re-baseline once the result is known-good:
explore map, thenmaintain snapshot.
Per-axis fields and finding codes are in
${CLAUDE_SKILL_DIR}/references/axes.md. Read it when a finding's code or field
is not described here.
Rules that change what you do
The baseline
- Take
maintain snapshotright after a known-good build, and tell the user to commit.dex/snapshot.jsonlike a lockfile, so the whole team diffs against one reference. - Never snapshot a state that is already drifted:
checkwould then mask the very drift that matters. To accept a change as the new normal, re-runexplore mapfirst, thenmaintain snapshot. - On a warehouse past the rank cutoff (more than 50 objects), run
explore map --fullbefore snapshotting, or the baseline cannot compare columns for the objects it never profiled. A partial snapshot is still valid; relay its coverage warning rather than calling the result clean. - After a project-only refactor (moved model files, a renamed dbt project), use
maintain snapshot --project-only. It opens no connection and carries the warehouse evidence forward unchanged, so it never launders a stale warehouse into a fresh one.
Reading findings
key_lost_uniquenessmeans the data changed: a key proven unique is not any more.declared_grain_not_uniquemeans nothing changed: the project declares a grain the data never had, so the fix is to the declaration (widen it, dedup upstream, or drop the claim), not to the data.- On
maintain semantic, readunavailablebefore hunting for an element kind. A native Ossie layer has no measures and no entities, so their absence is the format, not drift. semantic_format_changedorsemantic_vendor_changedmeans the definitions were not compared by content, because the reader changed. Re-snapshot once the upgrade is accepted, rather than reading the quiet definition diff as clean.- On a SLayer layer, a model file written in another format
versionis refused by the reader and named inwarnings, and every definition in it then comes back asdefinition_removed. Nothing was removed: the file could not be read. Never reconcile those as removals; the fix is the file rewritten in the currentversionwithsemantic slayer update(transform skill). join_cardinality_exceededmeans a join's declared arity does not hold, so measures across it are inflated. A join declaring no cardinality is inwarningsas unchecked, not passed: relay it as undetermined, and suggest declaring thecardinalitythe user expects so the next run measures it.- SLayer's own schema findings (
declared_column_missing,declared_type_conflict,declared_relation_missing,declared_dependency_dropped) are SLayer'svalidate-modelsrules run on dex's metadata. Do not runslayer validate-modelsto confirm them: it reads through SLayer's datasource credentials, and opening SLayer's storage can migrate and rewrite the model files dex owns. - On
maintain verify, readdata.suppressedbefore reading an emptydata.findingsas a clean bill. A project that does not compile suppresses every other check. Row population is conservative by design, so a quiet answer is weaker evidence than a finding, andwarningsnames the models that could not be lined up. - For a change you just made, use
transform build --verify(same sweep, scoped to that build). Usemaintain verifyfor the whole project, or when somebody else ran the build.
Reconcile proposals
- On a large
checkreport, read the ratio before the findings. Runmaintain reconcileand readmechanical_countandadvisory_countbeside the finding codes, before the findings list. Mechanical proposals exist only where dex can author the fix itself (the two cases below), so zero of them across hundreds of schema findings, with nocolumn_dropped,column_retypedortable_droppedamong the codes, usually means the baseline is behind the project rather than the warehouse having moved: every finding is additive, and most of them are the project's own recent work. Re-baseline with the discipline above (explore map --full, thenmaintain snapshot) before triaging findings one by one. A type change is advisory on every format, so read the codes for retypes rather than inferring them from the count. mechanical(schema drift): edits only the drifted columns into a staging model and into the YAML that already declares it, or into a declaration, and leaves every other line alone. Still a reviewable diff. A dropped column that hand-written logic reads comes back advisory naming the use, readers further downstream are named inwarnings, and drift the project already reflects is advisory with amaintain snapshothint.advisory(grain, volume, semantic): a decision for the user, at most backed by a test edit that makes the break visible in builds. dex cannot dedup a warehouse or decide whether a new'refunded'status belongs in a metric, so relay the decision rather than make it.- A type change is advisory on every format. The proposal names both spellings, and the edit is the user's. On ClickHouse nullability is part of the type, so a column that starts accepting nulls is reported as a retype.
- With no editable dbt project, every proposal is advisory and no plan is stored.
Authoring into a native semantic layer is
semantic ossieorsemantic slayerin the transform skill, never this command. The exception is a SLayer layer's own schema findings (declared_*): reconcile stores their removals as a second plan,data.semantic_plan_id, through thesemantic slayer updateroute. Relay both plan ids; each applies withtransform apply.
Cost
- Schema, volume, and the definition half of
semanticread metadata and are free everywhere. Grain and the dimension-cardinality half ofsemanticscan. - Asked for directly on a metered connector,
maintain grainreturnsneeds_confirmationwith an estimate. Surface it in human units, get an explicit budget from the user, and re-issue with--confirm --budget <magnitude>in the estimate's unit: bytes on BigQuery, warehouse-seconds on Snowflake and Databricks, compute-seconds on Redshift, database-seconds on Postgres and ClickHouse, cluster-seconds on Trino. On DuckDB nothing prompts. check,semantic, andverifyanswer first and offer second: they returnokwith final findings, and the price of the rest underdata.offer(data.axes_runsays what ran,data.offer.axeswhat the estimate adds). Confirming is the user's choice, not a required next step: quote the estimate, say which axes are still dark, and let them decide. A triage that stops at the free axes is complete work.- Never invent a budget. After an over-ceiling refusal, never retry with a raised budget without asking. Relay its calibration line, and point out that the ceiling binds on the estimate, so a budget set at that fraction of the estimate is refused again.
- A
suggested_session_ceilingis the project's one-time ask for a daily cap. Surface it, get the user's answer, and add--session-ceiling <value>or--no-session-ceilingto the same re-issue. Never answer it for them.
Data and authority
- Raw rows and dimension values never cross the envelope; grain and cardinality checks use aggregates only.
- Human edits to the project and to the semantic layer are authoritative. On a conflict the engine surfaces the divergence; relay it and ask, never overwrite.
References
${CLAUDE_SKILL_DIR}/references/axes.md: what each axis detects, the snapshot contents,verify's finding classes, and what each axis costs.