altimate-code 0.7.2 → 0.8.0

package/CHANGELOG.md

@@ -5,6 +5,86 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.8.0] - 2026-06-01
+
+Headlined by **dbt PR Review** — a Cloudflare-style, dbt/SQL-specialized code reviewer that emits a single **signed** verdict (`APPROVE` / `COMMENT` / `REQUEST_CHANGES`) where every *blocking* finding is backed by a deterministic `altimate-core` engine call over parsed SQL ASTs, not a model's opinion. An optional LLM lane adds advisory context but can never block. This release also adds a **native Trino driver**, the opt-in **completion-gate validators**, and reliability/cost fixes. A five-persona pre-release review drove a security hardening pass on the new `reviewer` agent (see Security).
+
+### Added
+
+- **dbt PR Review — signed, deterministic verdicts on dbt pull requests.** New `altimate review` CLI command and a composite GitHub Action (`github/review`). The deterministic engine (column-lineage / DAG blast radius, query equivalence on before/after model SQL, PII classification, A–F grade + anti-pattern lint) is the **only** layer that can block; an optional LLM reviewer is clamped to ≤ warning and excluded from the gate, so a `REQUEST_CHANGES` is always provable and replayable. Runs in CI with **zero warehouse access** (consumes `dbt compile` artifacts), and the verdict is HMAC-signable and tamper-evident. `comment` mode never blocks; `gate` mode fails the check on `REQUEST_CHANGES`. The advisory model/credentials are configured on the Action (hosted `altimate_api_key`, or bring-your-own `model` + `model_api_key`); omit them to run deterministic-only. See [dbt PR Review docs](https://docs.altimate.sh/usage/dbt-pr-review/) and the copy-paste workflow in `github/review/examples/`. Depends on `@altimateai/altimate-core` ≥ 0.4.0. (#856)
+- **Native Trino driver.** First-class Trino support over HTTP(S) with catalog/schema introspection and None / Basic / Bearer-token auth. **Migration note:** the dbt `trino` adapter previously mapped to the PostgreSQL driver; it now uses the native driver. Existing profiles are auto-aliased (`database` → `catalog`, `token` → `access_token`) and otherwise compatible. `trino-client` is an optional dependency — install it (`npm install trino-client`) to use Trino. (#795)
+- **Completion-gate validator framework.** A new opt-in harness-side check
+  that runs after the LLM declares `finish === "stop"`. Two built-in
+  validators for dbt projects: `dbt-tests-pass` (runs `altimate-dbt test`
+  against modified models) and `dbt-schema-verify` (runs `altimate-dbt
+  schema-verify` against modified models). On failure, the framework
+  injects a synthetic user turn so the agent gets one more chance to fix
+  the issue, bounded by a per-session retry budget. Two opt-in modes:
+  `ALTIMATE_VALIDATORS_ENABLED=1` (enforcement + retries) and
+  `ALTIMATE_VALIDATORS_SHADOW=1` (telemetry-only — measure "would have
+  caught" rates without blocking). Default is **off** with zero overhead.
+  Two new telemetry events (`validator_check`, `validator_retries_exhausted`).
+  Configuration via `ALTIMATE_VALIDATORS_{MAX_RETRIES,TIMEOUT_MS,CONCURRENCY,DEBUG}`.
+  See [Validators docs](https://docs.altimate.sh/data-engineering/validators/)
+  for the full reference, performance characteristics, and the phased
+  rollout plan. (#849)
+
+### Fixed
+
+- **`cancel()` race / idle-on-clean-exit.** A cancel arriving during normal loop teardown could leave a session without a `session.status:idle` event, leaving callers waiting on idle stuck. Idle is now emitted correctly on both the abort and clean-exit paths. (#845)
+- **Prompt caching on the `altimate-backend` provider.** Enabled the `cache_control` trigger for the hosted provider so the litellm Anthropic fallback caches repeated prompt prefixes — cheaper and faster repeat turns (no-op on providers that ignore the marker). (#850)
+
+### Security
+
+- **`reviewer` agent hardened to deny bash.** The v0.8.0 pre-release review found that the new `reviewer` agent — advertised as "read-only" — had a bash allowlist (`git log *`, `cat *`, `ls *`) that was bypassable: shell redirects rode *inside* a matched command (`git log -p > ~/.ssh/authorized_keys` was allowed) and `cat *` could read arbitrary files (e.g. `~/.altimate/altimate.json`) and exfiltrate them through the PR comment the agent posts. Bash is now **denied** for the reviewer (it uses the structured `read`/`grep`/`glob` tools + the verdict engine, which does its own diffing); the agent description was corrected; and the reviewer prompt now treats PR content as untrusted input. The CI Action path was never affected — its LLM lane runs with no tools. (#856)
+
+## [0.7.3] - 2026-05-24
+
+A telemetry-driven hardening release. Five P0 fixes merged from a `telemetry-analysis-2026-05-21` pass — every one tied to a measured failure number from the App Insights pipeline. The headline wins are user-visible: `finops_*` tools now work without an explicit `warehouse=` parameter (auto-pick the first compatible connection); `project_scan` no longer crashes on hosts where `git` isn't in PATH (the silent 437-user regression was masked by the PII filter collapsing the binary name to `?` in error messages); and `webfetch` caches 404/410/451 responses for up to 30 minutes so the agent stops re-asking dead URLs. Two telemetry-only fixes (build-agent name normalization, Anthropic token-count semantics) clean up dashboard mis-bucketing without changing user-visible behavior.
+
+A five-persona pre-release review drove a second hardening pass: HTTPS basic-auth credentials are now stripped from `git remote get-url origin` output before it reaches LLM-visible metadata or session transcripts; raw `git` stderr is routed through `Telemetry.maskString` to redact embedded emails and bearer tokens; `normalizeAgentName` gained C0 control-char stripping + NFKC normalization + a 64-char cap to neutralize log-injection and homoglyph-bucket attacks via custom agent configs; the webfetch failure cache now also drops auth-bearing query params (`token`, `api_key`, `signature`, `x-amz-signature`, etc.) from the cache key so presigned-URL secrets can't sit in an in-memory `Map` for 30 minutes; cache-hit error messages are prefixed with `(cached failure, Nm ago)` so an agent debugging a fast failure can tell cache vs. live network apart; and 34 adversarial tests pin every one of these regression classes plus the `warehouse_filter` / `warehouse` parameter disambiguation that caused LLM confusion.
+
+### Dashboard query change
+
+`tokens_input_total` is now **always** emitted on `generation` telemetry events (previously omitted when zero/null). Dashboards reading `tokens_input` to compute volume will under-report on Anthropic-cache-hit sessions — switch any "total input tokens consumed" queries to `tokens_input_total`. The old `tokens_input` field is preserved and reports uncached input tokens (clamped at zero so inconsistent provider counts can't produce negative cost). The two fields satisfy the invariant `tokens_input + tokens_cache_read + tokens_cache_write === tokens_input_total`.
+
+### Fixed
+
+- **`finops_*` tools auto-pick a warehouse when omitted.** All six finops tools (`finops_analyze_credits`, `finops_expensive_queries`, `finops_query_history`, `finops_role_*`, `finops_unused_resources`, `finops_warehouse_advice`) previously required an explicit `warehouse=<connection-name>` argument. Telemetry showed them at a 100% error rate because the LLM consistently guessed unconfigured warehouse names and got dead-end "Credit analysis is not available for unknown warehouses" errors with no enumeration of what *was* configured. The new `resolveFinopsWarehouse` helper centralizes resolution: if no warehouse is requested, it auto-picks the first configured connection whose driver type supports the operation (`snowflake` / `bigquery` / `databricks` for credit/sizing/usage tools; broader for query history; Snowflake-only for role-hierarchy). Errors now enumerate configured warehouse names and point at `warehouse_add` when nothing is configured. Trim is applied on the requested name (LLM whitespace edge cases) and type matching is case-insensitive (`"Snowflake"` / `"snowflake"` / `"SNOWFLAKE"` resolve identically). (#828, closes #827)
+- **`project_scan` no longer crashes when `git` is missing from PATH.** Telemetry showed a 32% failure rate across 437 users with the masked error `"Executable not found in $PATH: ?"` — the binary name was being collapsed to `?` by the PII filter, hiding the real cause for two months. `Bun.spawnSync` *throws* when a binary isn't found (not just non-zero exit), and `project_scan` was running the throw unguarded. The new `safeSpawnSync` wrapper catches it cleanly and returns `null`, and `detectGit` distinguishes three states via `GitInfo.gitAvailable` + `gitError`: `git missing` (binary not in PATH — surface install hint), `git present but degraded` (non-128 exit code — corrupted `.git`, permission denied; surfaces exit code + masked stderr), and `git present, not a repo` (clean exit 128 — render "Not a git repository"). The `metadata.degraded` array always emits even when empty, sorted and deduplicated, so dashboard queries never have to null-coalesce. (#831, closes #830)
+- **Build agent telemetry no longer reports 0% completion.** A rename from `"build"` → `"builder"` in the agent registry left three writer sites still emitting the legacy name: the TUI sent `agent: "build"` on session start, the plan-exit synthetic message wrote `lastUser.agent = "build"`, and the `agent_outcome` event read from that. The agent execution alias at `Agent.get()` masked the issue at runtime, but every dashboard saw a phantom `"build"` bucket with 0% completion alongside the real `"builder"` bucket. The new `normalizeAgentName` helper is the single source of truth — used by both `session_start` and `agent_outcome` emits so they can never drift, case-insensitive against the legacy name, plus C0-control-char strip + NFKC + 64-char cap so a malicious or hand-edited config can't inject newlines into App Insights or create a cardinality bomb. The TUI and plan tool now write `"builder"` directly. (#833, closes #832)
+- **Anthropic `tokens_input` is no longer always 0 in telemetry.** `Session.getUsage` previously assumed OpenAI-style accounting (where `inputTokens` is the inclusive total including cached) — but Anthropic returns `inputTokens` exclusive of cached, so the subtraction `inputTokens - cacheRead - cacheWrite` produced 0 (or negative) on every cache-hit session. The new branch tests `metadata.anthropic || metadata.bedrock` and skips the subtraction for those providers. `tokens_input_total` is now always emitted as the inclusive total (so dashboards have a clean denominator), and `tokens.input` is clamped at zero — inconsistent provider counts (e.g. `inputTokens=1000, cachedInputTokens=2000`) can no longer leak negative cost into App Insights or session totals. Venice metadata path (`metadata.venice.usage.cacheCreationInputTokens`) is now covered with the same treatment as Anthropic/Bedrock. (#837, closes #836)
+- **`webfetch` failure cache now persists known-bad URLs for 30 minutes (5 min for 451) and collapses LLM-generated URL variations.** Telemetry showed 486 residual webfetch 404 retries across the 14-day window (down from March's 2,222 but still meaningful) — the LLM kept fetching the same dead URL with different tracking parameters, fragments, and case variations and getting fresh 404s each time. The cache key is now the *normalized* URL: tracking params (`utm_*`, `fbclid`, `gclid`, `mc_*`, `_ga`, `_gl`, `igshid`, `mibextid`, HubSpot `_hsenc`/`_hsmi`, Marketo `mkt_tok`, Adobe `s_cid`/`s_kwcid`, Piwik/Matomo `pk_*`/`piwik_*`, `__cf_chl_*`) are stripped, query params are sorted by (key, value), the host is lowercased, the fragment is dropped, and HTTPS basic-auth userinfo (`user:pass@`) is removed. The functional `ref` param is deliberately *preserved* (GitHub raw URLs and git APIs use it to select branches/tags). Auth-bearing query params (`token`, `access_token`, `api_key`, `apikey`, `signature`, `sig`, `x-amz-signature`, `x-amz-credential`, `x-amz-security-token`, `x-goog-signature`, `x-goog-credential`) are dropped from the **cache key only** — the actual `fetch()` still uses the raw URL — so an S3 presigned URL that 404s doesn't leak its signature into the in-memory `Map` for 30 minutes. 451 uses a shorter 5-min TTL because it's observer-conditional (VPN swap unblocks). Cache-hit errors now prefix with `(cached failure, Nm ago)` so an agent debugging a fast failure can tell cache vs. live network apart. LRU re-touch on repeated failures via `delete-then-set` so a frequently-failing URL doesn't sit at the head of the FIFO and get evicted first under pressure (cache size cap is 500). (#839, closes #838)
+
+### Privacy & Security (pre-release hardening pass)
+
+- **`git remote get-url origin` output is now credential-stripped before it reaches LLM-visible metadata or session transcripts.** Pre-fix, `metadata.git.remoteUrl` shipped the URL verbatim — including embedded HTTPS basic-auth like `https://x-access-token:ghp_xxx@github.com/...` or `https://user:pass@gitlab.internal/...` — which then flowed to the LLM provider on every `project_scan` call and was preserved in the session transcript. The new `stripGitRemoteCredentials` helper sets `username` and `password` to empty on parseable URLs, preserves SSH-form remotes (`git@github.com:owner/repo.git` has no userinfo concept), and drops unparseable URLs entirely rather than risk leaking embedded creds. Flagged by the v0.7.3 compliance/chaos review.
+- **`gitError.stderr` is masked via `Telemetry.maskString` before persisting.** Git stderr on auth failures and bad-object errors contains embedded HTTPS remote URLs (with userinfo), commit emails, and `/Users/<realname>/` paths. The masker (already redacting `sk-`, `Bearer`, and `<email>` in error strings elsewhere) now runs before the stderr is sliced to 240 chars and assigned to `metadata.git.gitError.stderr`. Mask-before-slice order is pinned by adversarial test so a refactor can't reorder them and surface a half-redacted email.
+- **`normalizeAgentName` hardens against adversarial input.** Strips C0 control characters (`\x00-\x1f` + DEL) — a custom-agent config with `name: "x\nfake_event=hello"` would have split App Insights into two events; NFKC-normalizes so fullwidth/homoglyph agent names (`"ｂｕｉｌｄｅｒ"`) don't create separate telemetry buckets; caps length at 64 chars because agent names are slugs and anything larger is a cardinality bomb. Three new pinning tests guarantee each invariant.
+
+### Changed
+
+- **`warehouse_filter` parameter description disambiguated from `warehouse`.** With `warehouse` now optional, the previous description ("Filter to a specific Snowflake warehouse") was ambiguous next to the connection-name `warehouse` parameter. New description: "Filter result rows by an in-warehouse Snowflake compute name (NOT the connection name). Distinct from `warehouse`: `warehouse` picks which connection to query; `warehouse_filter` narrows which Snowflake virtual warehouse's queries are returned in the result set. Snowflake only." Applied to both `finops_analyze_credits` and `finops_query_history`. End-user persona flagged the LLM-confusion risk during pre-release review.
+- **`DEFAULT_FINOPS_TYPES` is the canonical "supported by any cloud warehouse" type list.** Pre-fix, three handlers (`credit-analyzer`, `unused-resources`, `warehouse-advisor`) each declared the same `["snowflake", "bigquery", "databricks"]` literal as a local `const`. Now exported from `warehouse-resolver.ts`; adding a fourth driver (e.g. Redshift `account_usage`) is one edit, not three.
+- **`docs/docs/data-engineering/tools/finops-tools.md` updated for the auto-pick behavior.** Pre-fix, the doc said `warehouse (required): Connection name` — directly contradicting the v0.7.3 code. Now lists `warehouse` as optional with the auto-pick semantics, includes a top-of-file `v0.7.3+` note about the change, and shows the bare (no-warehouse) invocation form in at least one example. PM persona flagged the doc/code drift as P0 pre-release.
+
+### Testing
+
+- **34 adversarial tests** in `release-v0.7.3-adversarial.test.ts` pin the regression classes:
+  - **finops auto-pick** — code/doc/tool-description alignment (no `warehouse (required)` left in docs; "Optional" appears in tool descriptions; `warehouse_filter` description disambiguates from `warehouse`; `DEFAULT_FINOPS_TYPES` is single source of truth; resolver trims whitespace; resolver auto-picks on empty/undefined/whitespace).
+  - **project_scan privacy** — `stripGitRemoteCredentials` present + sets `username`/`password` empty; `gitError.stderr` runs through `Telemetry.maskString`; mask-before-slice order; `safeSpawnSync` returns null on missing binary; `GitInfo.gitAvailable` + `gitError` distinguish three states; output line distinguishes "binary missing" from "not a repo".
+  - **normalizeAgentName** — single declaration site (single source of truth); case-folds before "build" compare; strips C0 control chars; NFKC-normalizes; length-caps at 64; both `session_start` and `agent_outcome` route through the helper.
+  - **webfetch cache key** — `AUTH_PARAMS_FOR_CACHE_KEY` enumerates `token`/`access_token`/`api_key`/`apikey`/`signature`/`sig`/`x-amz-signature`/`x-amz-credential`/`x-goog-signature`; presigned-S3 URLs with different signatures collapse; api_key/token variants all collapse; functional params (`page`, `q`) are NOT stripped; auth-param strip is case-insensitive; cache-hit error prefix wording is distinguishable; `isUrlCachedFailure` exposes `ageMs`; 451 has shorter TTL than 404/410.
+  - **URL normalization privacy invariants** — userinfo stripped from cache key; utm/fbclid/mc_ tracking collapses; normalization is idempotent; invalid URL passes through verbatim.
+  - **CHANGELOG presence** — release-skill backstop that catches a release commit without a 0.7.3 entry + all 5 merged PR numbers referenced.
+
+### Deferred to follow-up issues
+
+- [#840](https://github.com/AltimateAI/altimate-code/issues/840) Surface auto-picked warehouse name in `finops_*` tool output (currently `autoPicked: true` is computed but not rendered).
+- [#841](https://github.com/AltimateAI/altimate-code/issues/841) Audit: webfetch failure cache crosses logical sessions in `altimate serve` daemon mode.
+- [#842](https://github.com/AltimateAI/altimate-code/issues/842) Route the three compaction-summary `lastUser.agent` writes through `normalizeAgentName` (currently only the emit boundary is normalized; persisted state can still record legacy `"build"`).
+- [#843](https://github.com/AltimateAI/altimate-code/issues/843) Audit: cost telemetry retention + re-identification policy (`tokens_input_total` + `cost` are now always emitted per generation event; document TTL and TOS alignment).
+
 ## [0.7.2] - 2026-05-21
 
 A focused hotfix for v0.7.1's broken install endpoint plus a defensive pass on the upgrade fetch surface. v0.7.1 documented and embedded `https://altimate.ai/install` in the curl install path and in `altimate upgrade`'s in-place upgrader — that host is the marketing-site SPA and returns an HTML 404 for `/install`, so every curl install and every curl-installed user's `altimate upgrade` silently failed end-to-end. v0.7.2 swaps the host to `https://www.altimate.sh/install` (apex `altimate.sh` is still not routed to the Amplify Next.js app — tracked separately, drop the `www.` once apex DNS is fixed), wraps the upgrader fetch with a 15s bounded timeout, replaces the raw `AbortError: The operation was aborted` with an actionable error that names the URL, prints the manual re-install one-liner, and points at the GitHub releases fallback. Realigns the published GitHub Action (`github/action.yml`) with the v0.7.1 binary rename (`altimate-code` → `altimate`) and new install directory (`~/.altimate/bin`) — pre-fix, every Action consumer hit the broken URL on cache miss and then a missing binary even if the URL had worked. 30 adversarial tests pin the regression classes (URL eradication, cross-file host consistency, named-constant invariants, error-surface invariants, action.yml alignment, marker integrity, migration recovery surface, CHANGELOG presence).

package/README.md

@@ -175,7 +175,7 @@ Each mode has scoped permissions, tool access, and SQL write-access control.
 
 ## Supported Warehouses
 
-Snowflake · BigQuery · Databricks · PostgreSQL · Redshift · ClickHouse · DuckDB · MySQL · SQL Server (incl. Microsoft Fabric) · Oracle · SQLite · MongoDB
+Snowflake · BigQuery · Databricks · PostgreSQL · Redshift · Trino · ClickHouse · DuckDB · MySQL · SQL Server (incl. Microsoft Fabric) · Oracle · SQLite · MongoDB
 
 First-class support with schema indexing, query execution, and metadata introspection. SSH tunneling available for secure connections.
 

package/dbt-tools/dist/index.js

@@ -23515,6 +23515,117 @@ var init_compile = __esm(() => {
   init_dbt_cli();
 });
 
+// src/commands/schema-verify.ts
+var exports_schema_verify = {};
+__export(exports_schema_verify, {
+  schemaVerify: () => schemaVerify
+});
+async function schemaVerify(adapter, args) {
+  const model = flag2(args, "model");
+  if (!model)
+    return { error: "Missing --model" };
+  const parsed = await adapter.parseManifest();
+  const node = parsed?.nodeMetaMap.lookupByBaseName(model);
+  if (!node) {
+    return {
+      error: `Model '${model}' not found in manifest. Did you run \`altimate-dbt compile\` or \`altimate-dbt build\` first?`
+    };
+  }
+  const expectedEntries = Object.values(node.columns ?? {});
+  let actual;
+  try {
+    actual = await adapter.getColumnsOfModel(model);
+  } catch (e2) {
+    return {
+      error: `Failed to read actual columns for '${model}': ${e2 instanceof Error ? e2.message : String(e2)}. Build the model first: altimate-dbt build --model ${model}`
+    };
+  }
+  if (!actual) {
+    return {
+      error: `Model '${model}' is in the manifest but has no warehouse table. Build it first: altimate-dbt build --model ${model}`
+    };
+  }
+  if (expectedEntries.length === 0) {
+    return {
+      model,
+      verdict: "no-spec",
+      message: `Model '${model}' has no columns declared in schema.yml. There is no spec to verify against; the agent's column choices are unconstrained.`,
+      actual_columns: actual.map((c) => c.column)
+    };
+  }
+  const actualNames = actual.map((c) => c.column ?? "");
+  const actualLower = actualNames.map((n) => n.toLowerCase());
+  const expectedNames = expectedEntries.map((c) => c.name ?? "");
+  const expectedLower = expectedNames.map((n) => n.toLowerCase());
+  const actualSet = new Set(actualLower);
+  const expectedSet = new Set(expectedLower);
+  const columns_extra = [];
+  for (let i2 = 0;i2 < actualNames.length; i2++) {
+    const low = actualLower[i2] ?? "";
+    const orig = actualNames[i2] ?? "";
+    if (!expectedSet.has(low))
+      columns_extra.push(orig);
+  }
+  const columns_missing = [];
+  for (let i2 = 0;i2 < expectedNames.length; i2++) {
+    const low = expectedLower[i2] ?? "";
+    const orig = expectedNames[i2] ?? "";
+    if (!actualSet.has(low))
+      columns_missing.push(orig);
+  }
+  const intersection = expectedLower.filter((n) => actualSet.has(n));
+  const actualIntersection = actualLower.filter((n) => expectedSet.has(n));
+  const columns_reordered = [];
+  for (let i2 = 0;i2 < intersection.length; i2++) {
+    const expectedAtI = intersection[i2] ?? "";
+    const actualAtI = actualIntersection[i2] ?? "";
+    if (expectedAtI !== actualAtI) {
+      const colLower = expectedAtI;
+      const actualIdx = actualLower.indexOf(colLower);
+      const expectedPos = expectedLower.indexOf(colLower);
+      const original = expectedNames[expectedPos] ?? colLower;
+      columns_reordered.push({
+        column: original,
+        actual_position: actualIdx,
+        expected_position: expectedPos
+      });
+    }
+  }
+  const actualTypeByName = {};
+  for (const c of actual)
+    actualTypeByName[c.column.toLowerCase()] = c.dtype || "";
+  const type_mismatches = [];
+  for (const ec of expectedEntries) {
+    const key = ec.name.toLowerCase();
+    if (!actualTypeByName[key])
+      continue;
+    if (!ec.data_type)
+      continue;
+    if (actualTypeByName[key].toLowerCase() !== ec.data_type.toLowerCase()) {
+      type_mismatches.push({
+        column: ec.name,
+        actual_type: actualTypeByName[key],
+        expected_type: ec.data_type
+      });
+    }
+  }
+  const verdict = columns_extra.length === 0 && columns_missing.length === 0 && columns_reordered.length === 0 && type_mismatches.length === 0 ? "match" : "mismatch";
+  return {
+    model,
+    verdict,
+    expected_columns: expectedNames,
+    actual_columns: actualNames,
+    columns_extra,
+    columns_missing,
+    columns_reordered,
+    type_mismatches
+  };
+}
+function flag2(args, name) {
+  const i2 = args.indexOf(`--${name}`);
+  return i2 >= 0 ? args[i2 + 1] : undefined;
+}
+
 // src/commands/build.ts
 var exports_build = {};
 __export(exports_build, {
@@ -23524,7 +23635,7 @@ __export(exports_build, {
   build: () => build
 });
 async function build(adapter, args) {
-  const model = flag2(args, "model");
+  const model = flag3(args, "model");
   const downstream = args.includes("--downstream");
   if (!model) {
     if (downstream)
@@ -23536,10 +23647,14 @@ async function build(adapter, args) {
     modelName: model,
     plusOperatorRight: downstream ? "+" : ""
   });
-  return format(result);
+  const formatted = format(result);
+  if (!("error" in formatted)) {
+    return { ...formatted, schema_verify: await safeVerify(adapter, model) };
+  }
+  return formatted;
 }
 async function run3(adapter, args) {
-  const model = flag2(args, "model");
+  const model = flag3(args, "model");
   if (!model)
     return { error: "Missing --model" };
   const downstream = args.includes("--downstream");
@@ -23551,7 +23666,7 @@ async function run3(adapter, args) {
   return format(result);
 }
 async function test(adapter, args) {
-  const model = flag2(args, "model");
+  const model = flag3(args, "model");
   if (!model)
     return { error: "Missing --model" };
   const result = await adapter.unsafeRunModelTestImmediately(model);
@@ -23559,17 +23674,82 @@ async function test(adapter, args) {
 }
 async function project2(adapter) {
   const result = await adapter.unsafeBuildProjectImmediately();
-  return format(result);
+  const formatted = format(result);
+  if ("error" in formatted)
+    return formatted;
+  try {
+    const parsed = await adapter.parseManifest();
+    const nodes = parsed?.nodeMetaMap?.nodes ? Array.from(parsed.nodeMetaMap.nodes()) : [];
+    const verified = [];
+    const errored = [];
+    let nospec_count = 0;
+    for (const node of nodes) {
+      const resType = node.resource_type;
+      if (resType !== "model")
+        continue;
+      const name = node.name;
+      if (!name)
+        continue;
+      const cols = node.columns ?? {};
+      if (Object.keys(cols).length === 0) {
+        nospec_count++;
+        continue;
+      }
+      try {
+        const v2 = await schemaVerify(adapter, ["--model", name]);
+        if ("error" in v2) {
+          errored.push({ model: name, error: String(v2.error) });
+        } else if (v2.verdict === "no-spec") {
+          nospec_count++;
+        } else {
+          verified.push(v2);
+        }
+      } catch (e2) {
+        errored.push({ model: name, error: e2 instanceof Error ? e2.message : String(e2) });
+      }
+    }
+    const mismatches = verified.filter((r2) => r2.verdict === "mismatch");
+    const matches = verified.filter((r2) => r2.verdict === "match");
+    return {
+      ...formatted,
+      schema_verify_summary: {
+        models_checked: verified.length + errored.length,
+        match: matches.length,
+        mismatch: mismatches.length,
+        no_spec: nospec_count,
+        errored: errored.length,
+        mismatches,
+        ...errored.length > 0 && { errors: errored }
+      }
+    };
+  } catch (e2) {
+    return {
+      ...formatted,
+      schema_verify_summary: {
+        error: `Bulk schema-verify failed: ${e2 instanceof Error ? e2.message : String(e2)}. Run \`altimate-dbt schema-verify --model <name>\` per model to inspect.`
+      }
+    };
+  }
+}
+async function safeVerify(adapter, model) {
+  try {
+    return await schemaVerify(adapter, ["--model", model]);
+  } catch (e2) {
+    return {
+      error: `schema-verify failed: ${e2 instanceof Error ? e2.message : String(e2)}. Run \`altimate-dbt schema-verify --model ${model}\` manually to inspect.`
+    };
+  }
 }
 function format(result) {
   if (result?.stderr)
     return { error: result.stderr, stdout: result.stdout };
   return { stdout: result?.stdout ?? "" };
 }
-function flag2(args, name) {
+function flag3(args, name) {
   const i2 = args.indexOf(`--${name}`);
   return i2 >= 0 ? args[i2 + 1] : undefined;
 }
+var init_build = () => {};
 
 // src/commands/execute.ts
 var exports_execute = {};
@@ -23577,11 +23757,11 @@ __export(exports_execute, {
   execute: () => execute
 });
 async function execute(adapter, args) {
-  const sql = flag3(args, "query");
+  const sql = flag4(args, "query");
   if (!sql)
     return { error: "Missing --query" };
-  const model = flag3(args, "model") ?? "";
-  const raw = flag3(args, "limit");
+  const model = flag4(args, "model") ?? "";
+  const raw = flag4(args, "limit");
   const limit = raw !== undefined ? parseInt(raw, 10) : undefined;
   try {
     if (limit !== undefined && !Number.isNaN(limit))
@@ -23594,7 +23774,7 @@ async function execute(adapter, args) {
     throw e2;
   }
 }
-function flag3(args, name) {
+function flag4(args, name) {
   const i2 = args.indexOf(`--${name}`);
   return i2 >= 0 ? args[i2 + 1] : undefined;
 }
@@ -23610,7 +23790,7 @@ __export(exports_columns, {
   columns: () => columns
 });
 async function columns(adapter, args) {
-  const model = flag4(args, "model");
+  const model = flag5(args, "model");
   if (!model)
     return { error: "Missing --model" };
   try {
@@ -23624,8 +23804,8 @@ async function columns(adapter, args) {
   }
 }
 async function source(adapter, args) {
-  const name = flag4(args, "source");
-  const table = flag4(args, "table");
+  const name = flag5(args, "source");
+  const table = flag5(args, "table");
   if (!name)
     return { error: "Missing --source" };
   if (!table)
@@ -23641,15 +23821,15 @@ async function source(adapter, args) {
   }
 }
 async function values(adapter, args) {
-  const model = flag4(args, "model");
-  const col = flag4(args, "column");
+  const model = flag5(args, "model");
+  const col = flag5(args, "column");
   if (!model)
     return { error: "Missing --model" };
   if (!col)
     return { error: "Missing --column" };
   return adapter.getColumnValues(model, col);
 }
-function flag4(args, name) {
+function flag5(args, name) {
   const i2 = args.indexOf(`--${name}`);
   return i2 >= 0 ? args[i2 + 1] : undefined;
 }
@@ -23661,7 +23841,7 @@ __export(exports_graph, {
   children: () => children
 });
 async function children(adapter, args) {
-  const model = flag5(args, "model");
+  const model = flag6(args, "model");
   if (!model)
     return { error: "Missing --model" };
   try {
@@ -23674,7 +23854,7 @@ async function children(adapter, args) {
   }
 }
 async function parents(adapter, args) {
-  const model = flag5(args, "model");
+  const model = flag6(args, "model");
   if (!model)
     return { error: "Missing --model" };
   try {
@@ -23686,7 +23866,7 @@ async function parents(adapter, args) {
     throw e2;
   }
 }
-function flag5(args, name) {
+function flag6(args, name) {
   const i2 = args.indexOf(`--${name}`);
   return i2 >= 0 ? args[i2 + 1] : undefined;
 }
@@ -23705,7 +23885,7 @@ async function deps(adapter) {
   return format2(result);
 }
 async function add(adapter, args) {
-  const raw = flag6(args, "packages");
+  const raw = flag7(args, "packages");
   if (!raw)
     return { error: "Missing --packages" };
   const result = await adapter.installDbtPackages(raw.split(","));
@@ -23716,7 +23896,7 @@ function format2(result) {
     return { error: result.stderr, stdout: result.stdout };
   return { stdout: result?.stdout ?? "" };
 }
-function flag6(args, name) {
+function flag7(args, name) {
   const i2 = args.indexOf(`--${name}`);
   return i2 >= 0 ? args[i2 + 1] : undefined;
 }
@@ -23854,6 +24034,7 @@ var USAGE = {
     execute: "Execute SQL --query <sql> [--model <name>] [--limit <n>]",
     columns: "Get columns of model --model <name>",
     "columns-source": "Get columns of source --source <name> --table <name>",
+    "schema-verify": "Diff a model's actual columns against the schema.yml spec --model <name>. Returns columns_extra / columns_missing / columns_reordered / type_mismatches. verdict: match | mismatch | no-spec",
     "column-values": "Get column values --model <name> --column <col>",
     children: "Get downstream models --model <name>",
     parents: "Get upstream models --model <name>",
@@ -23863,7 +24044,7 @@ var USAGE = {
 };
 var cmd = process.argv[2];
 var rest = process.argv.slice(3);
-function flag7(args, name) {
+function flag8(args, name) {
   const i2 = args.indexOf(`--${name}`);
   return i2 >= 0 ? args[i2 + 1] : undefined;
 }
@@ -23946,7 +24127,7 @@ async function main() {
   const cfg = await read();
   if (!cfg)
     return { error: "No config found. Run: altimate-dbt init" };
-  const dirFlag = flag7(rest, "project-dir");
+  const dirFlag = flag8(rest, "project-dir");
   if (dirFlag) {
     cfg.projectRoot = resolve4(dirFlag);
   } else {
@@ -23982,13 +24163,13 @@ async function main() {
         result = await (await Promise.resolve().then(() => (init_compile(), exports_compile))).query(adapter, rest);
         break;
       case "build":
-        result = await (await Promise.resolve().then(() => exports_build)).build(adapter, rest);
+        result = await (await Promise.resolve().then(() => (init_build(), exports_build))).build(adapter, rest);
         break;
       case "run":
-        result = await (await Promise.resolve().then(() => exports_build)).run(adapter, rest);
+        result = await (await Promise.resolve().then(() => (init_build(), exports_build))).run(adapter, rest);
         break;
       case "test":
-        result = await (await Promise.resolve().then(() => exports_build)).test(adapter, rest);
+        result = await (await Promise.resolve().then(() => (init_build(), exports_build))).test(adapter, rest);
         break;
       case "execute":
         result = await (await Promise.resolve().then(() => (init_execute(), exports_execute))).execute(adapter, rest);
@@ -24002,6 +24183,9 @@ async function main() {
       case "column-values":
         result = await (await Promise.resolve().then(() => exports_columns)).values(adapter, rest);
         break;
+      case "schema-verify":
+        result = await (await Promise.resolve().then(() => exports_schema_verify)).schemaVerify(adapter, rest);
+        break;
       case "children":
         result = await (await Promise.resolve().then(() => (init_graph(), exports_graph))).children(adapter, rest);
         break;

package/package.json

@@ -14,20 +14,20 @@
   "scripts": {
     "postinstall": "bun ./postinstall.mjs || node ./postinstall.mjs"
   },
-  "version": "0.7.2",
+  "version": "0.8.0",
   "license": "MIT",
   "dependencies": {
-    "@altimateai/altimate-core": "0.3.1"
+    "@altimateai/altimate-core": "0.4.0"
   },
   "optionalDependencies": {
-    "@altimateai/altimate-code-windows-x64": "0.7.2",
-    "@altimateai/altimate-code-linux-x64": "0.7.2",
-    "@altimateai/altimate-code-linux-arm64": "0.7.2",
-    "@altimateai/altimate-code-windows-x64-baseline": "0.7.2",
-    "@altimateai/altimate-code-darwin-arm64": "0.7.2",
-    "@altimateai/altimate-code-linux-x64-baseline": "0.7.2",
-    "@altimateai/altimate-code-darwin-x64": "0.7.2",
-    "@altimateai/altimate-code-darwin-x64-baseline": "0.7.2"
+    "@altimateai/altimate-code-linux-arm64": "0.8.0",
+    "@altimateai/altimate-code-darwin-arm64": "0.8.0",
+    "@altimateai/altimate-code-linux-x64-baseline": "0.8.0",
+    "@altimateai/altimate-code-darwin-x64-baseline": "0.8.0",
+    "@altimateai/altimate-code-windows-x64-baseline": "0.8.0",
+    "@altimateai/altimate-code-darwin-x64": "0.8.0",
+    "@altimateai/altimate-code-windows-x64": "0.8.0",
+    "@altimateai/altimate-code-linux-x64": "0.8.0"
   },
   "peerDependencies": {
     "pg": ">=8",
@@ -38,7 +38,8 @@
     "mssql": ">=11",
     "oracledb": ">=6",
     "duckdb": ">=1",
-    "@clickhouse/client": ">=1"
+    "@clickhouse/client": ">=1",
+    "trino-client": ">=0.2"
   },
   "peerDependenciesMeta": {
     "pg": {
@@ -67,6 +68,9 @@
     },
     "@clickhouse/client": {
       "optional": true
+    },
+    "trino-client": {
+      "optional": true
     }
   }
 }

package/skills/dbt-develop/SKILL.md

@@ -1,6 +1,30 @@
 ---
 name: dbt-develop
-description: Create and modify dbt models — staging, intermediate, marts, incremental, medallion architecture. Use when building new SQL models, extending existing ones, scaffolding YAML configs, or reorganizing project structure. Powered by altimate-dbt.
+applyPaths:
+  - "dbt_project.yml"
+  - "**/dbt_project.yml"
+description: |
+  REQUIRED before writing or modifying ANY dbt model. Invoke this skill FIRST
+  whenever a task says "create", "build", "add", "modify", "update", "fix", or
+  "refactor" a dbt model, staging file, mart, incremental, or snapshot.
+
+  Skipping this skill is the leading cause of silent-correctness bugs —
+  models that compile and `dbt build` cleanly but produce wrong values. It
+  contains the patterns that prevent the most common such bugs encountered
+  in real dbt projects:
+
+  • Incremental high-water marks (`>=` vs `>` ties → silent row dropout)
+  • Snapshot strategy selection (timestamp vs check, `unique_key` choice)
+  • `LEFT JOIN + COUNT(*)` phantom rows from unmatched parents
+  • Type harmonization in `COALESCE` / `CASE` / `UNION` legs
+  • Date-spine completeness (every period present, even empty ones)
+  • Off-by-one window boundaries (`BETWEEN d - (N-1) AND d` for N-wide)
+  • Uniqueness enforcement when schema implies a key
+  • Window-function `LIMIT` with deterministic tiebreaker
+  • Verifying transformation correctness with dbt unit tests, not just `dbt build`
+  • Enumerating every requested deliverable and checking each exists on disk
+
+  Do not start writing SQL until this skill is loaded. Powered by altimate-dbt.
 ---
 
 # dbt Model Development
@@ -31,6 +55,12 @@ description: Create and modify dbt models — staging, intermediate, marts, incr
 
 Before writing any SQL:
 - Read the task requirements carefully
+- **Enumerate every concrete deliverable the task asks for** — write down each
+  model name, every column/test/config change mentioned, and any "create N
+  models" count. This list becomes the checklist you verify against in
+  step 4. A task asking for four models is not done if only three exist on
+  disk. If the task references a `schema.yml`, `_models.yml`, or similar
+  spec file, every entry there is a deliverable.
 - Identify which layer this model belongs to (staging, intermediate, mart)
 - Check existing models for naming conventions and patterns
 - **Check dependencies:** If `packages.yml` exists, check for `dbt_packages/` or `package-lock.yml`. Only run `dbt deps` if packages are declared but not yet installed.
@@ -98,6 +128,51 @@ altimate-dbt compile --model <name>                        # catch Jinja errors
 altimate-dbt build --model <name>                          # materialize + run tests
 ```
 
+**Verify transformation correctness with unit tests:**
+
+For models with non-trivial transformation logic — aggregations, JOINs, CASE/WHEN,
+window functions, ratio / rate / NPS calculations, COALESCE / NULL coalescing, date
+spines, incremental merge keys — generate and run dbt unit tests before declaring
+the model done. Schema checks ("table exists with the right columns") only verify
+mechanics; value-level correctness needs unit tests.
+
+Invoke the **dbt-unit-tests** skill, which will:
+- Analyze your SQL for the constructs above
+- Build typed mock input rows from the manifest
+- Compute expected outputs by running the SQL against the mocks
+- Write a `unit_tests:` block in the model's `_models.yml`
+
+Then run them:
+```bash
+altimate-dbt test --model <name>     # runs unit tests + schema tests
+```
+
+If a unit test fails, the transformation logic is wrong — **fix the SQL, do not
+weaken the test**. Skip unit tests only for genuinely trivial models: pure renames,
+simple `SELECT *` passthrough, materialization / config-only changes, format-only
+edits.
+
+**Verify every requested deliverable exists:**
+
+Walk the checklist you wrote in the Plan step. For each model the task asked
+for, confirm: (1) the `.sql` file exists in the project, (2) it appears in
+`altimate-dbt info` / the manifest, (3) `altimate-dbt columns --model <name>`
+returns the expected columns, (4) the materialization config matches the
+spec. A task that asked for N models is not complete with N-1 files on disk,
+even if those N-1 build cleanly. Use:
+
+```bash
+ls models/                                                   # confirm every requested file exists
+altimate-dbt info                                            # confirm every requested model is in the project
+```
+
+**Diff column shape against the spec — use the `dbt-schema-verify` skill.**
+For each model the task touched, run `altimate-dbt schema-verify --model
+<name>` and treat any `mismatch` verdict as "not done." Full procedure,
+output interpretation, and fallback (when `altimate-dbt` is missing) live
+in the dedicated **dbt-schema-verify** skill, which auto-loads alongside
+this one.
+
 **Verify the output:**
 ```bash
 altimate-dbt columns --model <name>                        # confirm expected columns exist
@@ -127,6 +202,203 @@ Use `altimate-dbt children` and `altimate-dbt parents` to verify the DAG is inta
 3. **Match existing patterns.** Read 2-3 existing models in the same directory before writing.
 4. **One model, one purpose.** A staging model should not contain business logic. An intermediate model should not be materialized as a table unless it has consumers.
 5. **Fix ALL errors, not just yours.** After creating/modifying models, run a full `dbt build`. If ANY model fails — even pre-existing ones you didn't touch — fix them. Your job is to leave the project in a fully working state.
+6. **Verify transformation correctness, not just mechanics.** For non-trivial models, generate and run dbt unit tests as part of the validate step (use the `dbt-unit-tests` skill). Passing `dbt build` only proves the SQL is syntactically valid — it doesn't prove the *values* are right.
+7. **Enumerate deliverables, then check them off.** The task is not done until every model, column, test, and config change explicitly requested exists on disk and in the manifest. Re-read the prompt at the end and verify each requested item — don't trust your own intermediate "done" feeling.
+8. **Match the column spec exactly — and verify it mechanically, not by inspection.** Use the dedicated **dbt-schema-verify** skill. Before declaring any model task done, run `altimate-dbt schema-verify --model <name>` and treat any `mismatch` verdict as "not done." Adding "helpful" extras (rank breakdowns, name-resolved fields, lineage metadata), reordering columns "more logically", or substituting synonyms (`supplier_id` for `supplier_company`, `transaction_type_name` for `transaction_type`) all break equality tests. The contract is what the spec says, not what you think would be useful.
+
+## Common Pitfalls in Transformation Logic
+
+When the model involves any of the following SQL constructs, watch for these
+generic bugs that mostly compile cleanly but produce wrong values:
+
+### Incremental models and snapshots
+
+- **High-water mark boundary**: in the `{% if is_incremental() %}` filter, use
+  `>=` (not `>`) when the upstream timestamp can repeat or land exactly on the
+  prior max — a strict `>` silently drops every event that ties with the most
+  recent prior load.
+- **`unique_key` choice**: must be the *natural* unique key of the row. Picking
+  a column that is not actually unique (e.g. a foreign-key like `customer_id`
+  instead of `order_id`) causes silent merges and lost rows.
+- **`on_schema_change`**: set `append_new_columns` (or `sync_all_columns` if
+  upstream evolves) so a new source column doesn't NULL-out existing data.
+- **Snapshots — strategy selection**: use `strategy='timestamp'` only when the
+  source has a reliable `updated_at` that monotonically increases on every
+  change. If `updated_at` can be NULL, be reset, or move backwards, switch to
+  `strategy='check'` with an explicit `check_cols` list. Verify by querying
+  the source for `MAX(updated_at)` and looking for repeats or NULLs.
+- **Backfilling**: `--full-refresh` rebuilds incremental tables from scratch.
+  Use it whenever you change the incremental SQL, the merge key, or
+  `on_schema_change`.
+
+### Date and time arithmetic
+
+- **"current age", "days since", "elapsed", "tenure"** — if the column is not
+  pre-computed in the source, compute it. For year-based age, account for
+  month/day so the change happens on the birthday, not on Jan 1:
+  ```sql
+  date_part('year', age(birth_date))                              -- in postgres-family
+  EXTRACT(YEAR FROM CURRENT_DATE) - EXTRACT(YEAR FROM birth_date)
+    - CASE WHEN (EXTRACT(MONTH FROM CURRENT_DATE), EXTRACT(DAY FROM CURRENT_DATE))
+              < (EXTRACT(MONTH FROM birth_date), EXTRACT(DAY FROM birth_date))
+           THEN 1 ELSE 0 END                                       -- portable form
+  ```
+- **Date spines**: when a daily/weekly/monthly model must have a row for
+  every period (even periods with zero events), build a spine first with
+  `dbt_utils.date_spine` or a recursive CTE, then LEFT JOIN the events onto
+  it. Never compute date series by `DISTINCT date_col FROM events` — that
+  silently drops empty periods.
+- **Date boundaries for windowed sums**: rolling-N-day windows expressed as
+  `BETWEEN d - (N-1) AND d` (inclusive both ends) give a width of exactly N.
+  `BETWEEN d - N AND d` gives N+1 — a classic off-by-one.
+
+### Type harmonization in `COALESCE` / `CASE` / `UNION`
+
+`COALESCE(timestamp_col, integer_col)` and `CASE WHEN ... THEN '0' ELSE 0 END`
+fail at compile or coerce silently to whatever type the engine guesses.
+Cast every branch / argument to the same explicit type:
+```sql
+COALESCE(CAST(timestamp_col AS TIMESTAMP), CAST(integer_col AS TIMESTAMP))
+CASE WHEN cond THEN CAST('0' AS NUMERIC) ELSE CAST(0 AS NUMERIC) END
+```
+Same applies to `UNION` / `UNION ALL` — column types must match across legs.
+
+### String concatenation with `NULL` operands
+
+`||` and `CONCAT()` propagate `NULL` in most engines — a single `NULL` operand
+makes the whole expression `NULL`. When the result feeds an equality join or
+surrogate-key generation, that's an invisible row-dropper:
+```sql
+-- Wrong: NULL region OR NULL segment produces NULL geo_segment
+region || '-' || segment AS geo_segment
+
+-- Right: explicit placeholder
+COALESCE(region, 'UNKNOWN') || '-' || COALESCE(segment, 'UNKNOWN') AS geo_segment
+```
+Use `CONCAT_WS()` if your dialect supports it (Snowflake, BigQuery) — it
+skips `NULL` operands instead of propagating them, which is usually safer
+than a static placeholder.
+
+### dbt model versioning (dbt 1.8+)
+
+When the task asks for a v2 of an existing model (and v1 must keep
+working — common during a rolling schema change), use dbt's **versioned
+models** feature, not a sibling `.sql` file with a `_v2` suffix:
+
+1. Create the new SQL file (e.g. `dim_accounts_v2.sql`).
+2. Add a `versions:` block to the model's entry in `_models.yml`:
+   ```yaml
+   models:
+     - name: dim_accounts
+       latest_version: 1
+       versions:
+         - v: 1
+         - v: 2
+           defined_in: dim_accounts_v2   # filename without .sql
+   ```
+3. Downstream callers reference the version with
+   `{{ ref('dim_accounts', v=2) }}`. Without the `versions:` block, dbt
+   treats `dim_accounts_v2` as an unrelated sibling model — versioning
+   tests will fail and v1↔v2 lineage won't appear in the DAG.
+
+### Refactoring a CTE into its own model — preserve row-count semantics
+
+When a task asks to extract a CTE from a larger model into its own
+intermediate model, the new model's row count must match what the CTE
+produced inside the original. Common bug: the CTE was on the parent side of
+a `LEFT JOIN` that preserved parent rows with no children; the agent's
+extracted model starts `FROM child_table` and joins back to the parent,
+silently dropping parents that have no children.
+
+**Rule of thumb:** the extracted model should start `FROM` the same table
+the CTE started from. Build the extracted model inside-out from the
+parent's perspective, not the child's.
+
+```sql
+-- Original CTE (inside the larger model):
+--   WITH agg_users AS (
+--     SELECT p.project_id, listagg(u.user_id) AS users
+--     FROM projects p
+--     LEFT JOIN project_users u ON u.project_id = p.project_id
+--     GROUP BY p.project_id
+--   )
+--
+-- Right refactor — preserves projects with no users:
+SELECT p.project_id, listagg(u.user_id) AS users
+FROM {{ ref('projects') }} p
+LEFT JOIN {{ ref('project_users') }} u ON u.project_id = p.project_id
+GROUP BY p.project_id
+
+-- Wrong refactor — drops projects with no users:
+SELECT u.project_id, listagg(u.user_id) AS users
+FROM {{ ref('project_users') }} u
+GROUP BY u.project_id                            -- projects with zero users vanish
+```
+
+**Verification** (in order of preference):
+
+```sql
+-- If dbt_utils is installed, add to schema.yml on the extracted model:
+tests:
+  - dbt_utils.equal_rowcount:
+      compare_model: ref('<parent_table>')
+
+-- If dbt-audit-helper is installed:
+{{ audit_helper.compare_relations(
+    a_relation=ref('<original_or_parent>'),
+    b_relation=ref('<extracted>'),
+    primary_key='<key>'
+) }}
+
+-- Manual fallback — always available:
+SELECT (SELECT COUNT(*) FROM {{ ref('<parent>') }})   AS parent_rows,
+       (SELECT COUNT(*) FROM {{ ref('<extracted>') }}) AS extracted_rows
+-- These must match if the original CTE was LEFT-joined to its parent.
+```
+
+If `extracted_rows < parent_rows`, the refactor is wrong — you've turned a
+LEFT JOIN into an INNER JOIN somewhere. Same trap shows up when filtering a
+right-side column in `WHERE` (silently converts the LEFT JOIN to an INNER
+JOIN); move that filter into the `ON` clause.
+
+### Uniqueness when the schema implies it
+
+If the model is named `dim_*`, has a `unique` test in `schema.yml`, or the
+task says "one row per X", the model must enforce that grain. Source data
+often has duplicates. Use one of:
+- `SELECT DISTINCT ...`
+- `QUALIFY ROW_NUMBER() OVER (PARTITION BY <key> ORDER BY <tiebreaker>) = 1`
+- `GROUP BY <key>` with explicit aggregation of all other columns
+
+### Window functions / ranking with `LIMIT` and ties
+
+`ORDER BY metric DESC LIMIT N` (and equivalently `ROW_NUMBER() / RANK() OVER
+(PARTITION BY ... ORDER BY metric)` filtered to `<= N`) over a column with
+ties returns a **non-deterministic** set — the engine can pick any N of the
+tied rows, and the choice often differs across runs, engines, or warehouse
+versions. The rest of the pipeline then sees row-count drift or different
+keys appearing in downstream joins.
+
+Always add a deterministic tiebreaker to the `ORDER BY` (a primary key, a
+surrogate id, or any column guaranteed unique within the partition):
+```sql
+-- Wrong: ties produce different "top 20" every run
+SELECT * FROM standings
+ORDER BY points DESC
+LIMIT 20
+
+-- Right: tie on points falls back to driver_id
+SELECT * FROM standings
+ORDER BY points DESC, driver_id ASC
+LIMIT 20
+
+-- Same fix inside QUALIFY / window-row-number patterns:
+QUALIFY ROW_NUMBER() OVER (
+  PARTITION BY season ORDER BY points DESC, driver_id ASC
+) <= 20
+```
+If you can't think of a tiebreaker column, the model probably doesn't yet
+have a unique key — fix that first.
 
 ## Common Mistakes
 
@@ -138,6 +410,7 @@ Use `altimate-dbt children` and `altimate-dbt parents` to verify the DAG is inta
 | Creating a staging model with JOINs | Staging = 1:1 with source. JOINs belong in intermediate or mart |
 | Not checking existing naming conventions | Read existing models in the same directory first |
 | Using `SELECT *` in final models | Explicitly list columns for clarity and contract stability |
+| `COUNT(*)` over a `LEFT JOIN` — counts unmatched parent rows as if they had one child (e.g. a `dim_parent LEFT JOIN fct_child` with no matching children still yields one row, so `COUNT(*) = 1` instead of `0`) | Use `COUNT(<child_key>)` or `COUNT(CASE WHEN <child_key> IS NOT NULL THEN 1 END)`. If you intended to exclude unmatched parents, switch to `INNER JOIN`. Same trap applies to `SUM`, `AVG`, etc. when the unmatched side contributes a "ghost" `NULL` row |
 
 ## Reference Guides
 

package/skills/dbt-pr-review/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: dbt-pr-review
+description: Cloudflare-style AI code review for dbt/SQL pull requests. Produces a signed APPROVE/COMMENT/REQUEST_CHANGES verdict where every blocking finding is backed by a deterministic engine call — column-lineage blast radius, query equivalence, PII classification, and A–F grade. Use to review a dbt PR or the working-tree changes before merge.
+---
+
+# dbt PR Review
+
+## Requirements
+**Agent:** `reviewer` (read-only) — also works from `analyst`/`builder`.
+**Tools used:** `dbt_pr_review` (primary), `impact_analysis`, `altimate_core_equivalence`, `altimate_core_check`, `lineage_check`, read-only `git`.
+
+## When to Use This Skill
+
+Use when the user wants to:
+- Review a dbt pull request (changed models) before merge
+- Get a single verdict (APPROVE / COMMENT / REQUEST_CHANGES) with evidence
+- Understand the downstream blast radius of a model/column change
+- Check whether a "refactor" actually preserves results (query equivalence)
+- Catch PII exposure, contract breaks, or warehouse-cost anti-patterns pre-merge
+
+## What makes this different from a generic AI reviewer
+
+Generic reviewers read the diff as text and guess. This review is backed by the
+Rust core: every blocking finding carries a deterministic proof (an equivalence
+counterexample, a downstream-model list, a PII classification). The verdict is
+**signed** into a replayable envelope keyed to the dbt manifest.
+
+## Workflow
+
+1. **Run the verdict engine.** Call `dbt_pr_review` once:
+   - `dbt_pr_review({})` reviews the working tree against `origin/main`.
+   - `dbt_pr_review({ base: "origin/main", head: "HEAD", manifest_path: "target/manifest.json" })`
+     for an explicit PR range.
+   - The tool reads `.altimate/review.yml` for the per-repo rubric and `mode`.
+
+2. **Read the signed envelope.** It contains the verdict, a risk tier
+   (trivial / lite / full), and findings grouped by severity
+   (critical / warning / suggestion), each with engine evidence.
+
+3. **Present the verdict** exactly as returned. Group findings by severity.
+   If the run is **degraded** (no manifest/warehouse), state that lineage,
+   equivalence, and data-impact were NOT verified — it is a lint-only review.
+
+4. **Respect the safety invariant.** An UNDECIDABLE equivalence result is a
+   WARNING, never a block. Never claim a refactor is unsafe when equivalence
+   could not be decided — recommend a data-diff instead.
+
+## Configuration (`.altimate/review.yml`)
+
+```yaml
+mode: comment            # comment (never blocks) | gate (blocks on REQUEST_CHANGES)
+severityThreshold: suggestion
+manifestPath: target/manifest.json
+dialect: snowflake
+reviewers: []            # empty = tier defaults; or pin lanes e.g. [lineage_breakage, semantic_change]
+exclude:
+  - models/legacy/**
+rubric:
+  blockOn: [lineage_breakage, contract_violation, pii_exposure, semantic_change]
+  warningPatternThreshold: 3
+  thresholds:
+    warehouseCostMinRows: 1000000
+```
+
+## Verdict rubric (defaults)
+
+- **REQUEST_CHANGES** — any blocking-category `critical` (broken lineage with
+  downstream consumers, contract violation, PII exposure, proven non-equivalent
+  rewrite), or ≥3 warnings (risk pattern).
+- **COMMENT** — only suggestions, or a single non-blocking warning.
+- **APPROVE** — no findings.
+
+In `comment` mode (default), REQUEST_CHANGES is posted as comments rather than
+blocking the merge. Switch to `gate` per-repo once you trust the false-positive rate.

package/skills/dbt-schema-verify/SKILL.md

@@ -0,0 +1,146 @@
+---
+name: dbt-schema-verify
+applyPaths:
+  - "dbt_project.yml"
+  - "**/dbt_project.yml"
+description: |
+  REQUIRED after building or modifying ANY dbt model that has columns declared
+  in `schema.yml` / `_models.yml`. Run `altimate-dbt schema-verify --model
+  <name>` to diff actual columns against the spec, and treat any `mismatch`
+  verdict as "not done."
+
+  The most common reason "the build is green but the tests still fail" is
+  that the model produces the right *data values* in the wrong *column
+  shape* — extra columns, missing columns, wrong order, wrong types. Many
+  dbt equality tests grade the column tuple `(name, type, position)`
+  exactly, and the agent's prior bias is to add "helpful" extras
+  (`p1`/`p2`/`p3` rank breakdowns, name-resolved variants, lineage
+  metadata) or reorder columns "more logically." Both break the contract.
+
+  This skill enforces the mechanical check that catches those bugs before
+  declaring done. Use it before declaring any model task complete.
+---
+
+# dbt schema-verify
+
+## When to invoke this skill — every time
+
+Run `altimate-dbt schema-verify --model <name>` before declaring any of the
+following tasks complete:
+
+- Creating a new dbt model that has (or will have) a `schema.yml` entry
+- Modifying an existing model whose `schema.yml` declares columns
+- Refactoring a CTE into its own intermediate model
+- Renaming columns or changing their order
+- Changing materialization config in a way that re-creates the table
+- Any task that says "match the schema", "produce these columns", "the
+  output should have columns X, Y, Z", or references a `_models.yml`
+- Any task with `AUTO_*_equality` or `AUTO_*_existence` tests on a model
+
+If the task touched N models, run schema-verify on **all N of them**, not
+just the last one. A `build` is not a verify.
+
+## How to run it
+
+```bash
+altimate-dbt schema-verify --model <name>
+```
+
+**Note**: `altimate-dbt build --model <name>` already runs schema-verify
+automatically after a successful build and includes the verdict in its
+response under a `schema_verify` field. You will see the diff in the same
+result that reported the build outcome — read it there before deciding
+the task is done. If you need to re-check after editing, call
+`schema-verify` directly.
+
+Returns a structured JSON result:
+
+```json
+{
+  "model": "int_asana__project_user_agg",
+  "verdict": "mismatch",
+  "expected_columns": ["project_id", "users", "number_of_users_involved"],
+  "actual_columns": ["project_id", "users"],
+  "columns_extra": [],
+  "columns_missing": ["number_of_users_involved"],
+  "columns_reordered": [],
+  "type_mismatches": []
+}
+```
+
+## How to read the verdict
+
+| verdict | meaning | what to do |
+|---|---|---|
+| `match` | actual columns match the spec exactly (case-insensitive on names) | DONE — proceed |
+| `mismatch` | one or more of `columns_extra`, `columns_missing`, `columns_reordered`, `type_mismatches` is non-empty | NOT DONE — read the diff, fix the model SQL, rebuild, re-run schema-verify |
+| `no-spec` | the model has no columns declared in `schema.yml` | DONE for shape-fidelity purposes — no contract to verify against |
+
+## How to act on a `mismatch`
+
+For each non-empty list, the fix is mechanical:
+
+| Field | What it means | What to change in the model SQL |
+|---|---|---|
+| `columns_extra` | columns in your model NOT in the spec | REMOVE them from the `SELECT` |
+| `columns_missing` | columns in the spec NOT in your model | ADD them to the `SELECT` (compute them, or rename an existing column if you used a synonym) |
+| `columns_reordered` | columns present in both but at different positions | REORDER the columns in your `SELECT` to match the spec's order |
+| `type_mismatches` | declared `data_type` in spec disagrees with the warehouse's reported type | CAST in the `SELECT` or change the upstream source |
+
+Then run `altimate-dbt build --model <name>` again, then re-run
+`altimate-dbt schema-verify --model <name>` until verdict is `match`.
+
+## Iron Rules
+
+1. **The verdict is the source of truth, not your inspection.** Reading the
+   columns yourself and concluding "looks right to me" does not count.
+   Run the command and read its output.
+2. **A `mismatch` is "not done", even if the build is green.** dbt build
+   only proves the SQL compiled and ran without errors. It does not prove
+   the column shape is correct. Equality tests grade shape AND values.
+3. **Do not reinterpret the spec to make the model right.** The spec is
+   the contract. If the spec lists `supplier_company` and your model has
+   `supplier_id`, the answer is to fix your model, not to argue that
+   `supplier_id` is more useful.
+4. **Run schema-verify on every model touched, not just the last one.**
+   The most common "almost-pass" is N-1 models passing and the Nth one
+   silently failing on column shape. Walk the list.
+5. **Skip only on `no-spec`.** Do not skip on the grounds that the model
+   is small, or trivial, or "obvious." The spec is small only because
+   the dbt project author already curated it.
+
+## Fallback when altimate-dbt is unavailable
+
+If `which altimate-dbt` returns nothing, do the same diff by hand:
+
+```bash
+# 1. Read expected columns from any YAML spec under models/
+#    dbt allows any .yml filename; common patterns include schema.yml,
+#    _models.yml, models.yml, sources.yml, etc.
+cat models/**/*.yml | grep -A 50 "name: <name>"   # or: yq eval '...' models/**/*.yml
+
+# 2. Read actual columns from the materialized table
+dbt show --select <name> --limit 0
+```
+
+Compare the two ordered lists. Produce the same four-bucket diff
+(`columns_extra`, `columns_missing`, `columns_reordered`,
+`type_mismatches`) in your head, and apply the same fix logic. The
+mechanics don't change; only the tool name does.
+
+## What this skill does NOT cover
+
+- **Value-level correctness** — passing schema-verify only proves shape;
+  whether the *values* in each column are right is a separate check
+  (`altimate-dbt test` + dbt unit tests). Generate unit tests with the
+  `dbt-unit-tests` skill when the model has non-trivial transformation
+  logic.
+- **Row count** — schema-verify compares columns, not rows. If a refactor
+  drops rows that should be preserved (common when extracting a CTE into
+  its own model — see `dbt-develop`'s "Refactoring a CTE into its own
+  model" section), schema-verify will pass while equality tests fail.
+  Check row counts separately.
+- **Custom tests** — `check_*` and other non-AUTO tests check
+  task-specific business rules, not column shape. schema-verify can pass
+  while a custom test fails. Read the custom test SQL to understand
+  what's being asserted.

package/skills/dbt-unit-tests/SKILL.md

@@ -32,6 +32,19 @@ description: Generate dbt unit tests automatically for any model. Analyzes SQL l
 3. **Use sql format for ephemeral models.** Dict format fails silently for ephemeral upstreams.
 4. **Never weaken a test to make it pass.** If the test fails, the model logic may be wrong. Investigate before changing expected values.
 5. **Compile before committing.** Always run `altimate-dbt test --model <name>` to verify tests compile and execute.
+6. **Mock data MUST exercise the failure modes of every SQL construct in the model.** A unit test that only covers the happy path validates that the model handles easy inputs — it does not validate correctness. Before writing `given:` rows, list every SQL construct in the model and the boundary case it can mishandle, then ensure at least one mock row triggers each. Universal cases to always cover when the construct appears:
+   - **`LEFT JOIN` / `LEFT OUTER JOIN`** → at least one parent row with **no matching child** (catches `COUNT(*)` phantom rows, `SUM` over `NULL`, fan-out / dropout)
+   - **`INNER JOIN`** → at least one parent row whose child is filtered out by the JOIN condition (catches missing rows)
+   - **`COUNT(*)` / `COUNT(<col>)`** → row where the counted column is `NULL` (catches `COUNT(*)` vs `COUNT(col)` divergence)
+   - **`NULLIF(x, y)`** → row where `x = y` (so the result is `NULL`, exercising downstream `NULL`-handling)
+   - **`/` division** → row where the denominator is `0` or `NULL`
+   - **`CASE WHEN`** → at least one row matching each branch, including the implicit `ELSE NULL` if no explicit `ELSE` is set
+   - **`COALESCE` / `IFNULL`** → row where every argument is `NULL`
+   - **Window functions (`OVER`)** → a partition of size 1 (single-row group exercises rank/first/last edge cases), a row at the partition boundary, and a tie-break row (two rows with the same ORDER BY key)
+   - **Date arithmetic / date spines** → a row at the start of range, end of range, and a gap day with no events
+   - **Aggregations with `GROUP BY`** → at least one group of size 1 (often masks fan-out bugs) and one group whose key is `NULL`
+   - **Incremental merge keys** → both an "insert" row and an "update" row matching an existing key
+   If you can't think of a failure mode for a construct, you don't yet understand it well enough to test it — read the SQL again before guessing inputs.
 
 ## Core Workflow: Analyze -> Generate -> Refine -> Validate -> Write