@ak--47/dungeon-master 1.7.0 → 1.8.1

package/.claude/skills/headless-build/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: headless-build
 description: Use after a dungeon's data is loaded into a real Mixpanel project — builds the full demoable environment with mixpanel-headless (dashboards, charts, Lexicon, cohorts, custom properties, behaviors/metrics/formulas, annotations) targeted at that dungeon's engineered stories, then verifies the stories still read live. Final step after create-dungeon / write-hooks / verify-dungeon / create-project.
-argument-hint: [dungeon path, e.g. dungeons/user/nyc-dcp/nyc-dcp.js]
+argument-hint: '[dungeon path, e.g. dungeons/user/nyc-dcp/nyc-dcp.js]'
 model: claude-opus-4-6
 effort: max
 ---
@@ -14,16 +14,37 @@ Last step of the pipeline:
 /create-dungeon → /write-hooks → /verify-dungeon → /create-project → /headless-build
 ```
 
+For `warehouseMetrics`, insert `/warehouse-metrics` after verification and project
+provisioning, before this build. Use the verified local disk artifact prefix.
+Ordinary event import loads `standaloneEvents` but does not deploy warehouse tables.
+
+Keep cadence and warehouse metrics separate from people analyses. Synthetic
+standalone `distinct_id` values identify series; never count them as users or
+include them in funnels, retention, or identity stitching. Build aggregate reports
+from their declared numeric properties and dimensions.
+
+For warehouse-backed charts, read the manifest and saved metric ids from the
+warehouse handoff. `history` may extend the metric window before the user-event
+window; preserve that range and label synthetic backfill. Check saved definitions
+and `previewWarehouseMetric` results before narrating values. A successful
+`refreshWarehouseMetric` only invalidates cache; it does not execute the query.
+Use the existing `/macro/setup-bq-warehouse` flow through `/warehouse-metrics`
+for source setup. Do not reimplement source creation or IAM grants in build code.
+
 The project already has data. This skill builds everything a human sees: themed
 dashboards whose narrative is computed from the live data, an annotated Lexicon,
 saved cohorts and custom properties, saved behaviors/metrics/formulas, and
 annotations that explain the engineered moments. Then it re-measures the hook
 stories **against the live project** and fails if they no longer read.
 
-That last step is the point. Local story verification passes on the generated
-array in memory; it never sees what survived ingest. A build can render five
+Local story verification uses generated records in memory or retained disk
+artifacts. It does not establish what survived ingest. A build can render five
 perfect dashboards on top of a story that silently collapsed on the way in.
 
+Apply the [1.8.1 verification contract](../verify-dungeon/references/alignment-contract.md)
+when translating local stories into live reports. This build requires authorized
+online work; it is never an automatic step of offline verification.
+
 ## Scope
 
 In scope: dashboards + charts, Lexicon enrichment, cohorts, custom properties,
@@ -165,13 +186,14 @@ size, require each bucket to be observed END TO END (`(b+1)*unit - 1` days of hi
 not `b*unit`), and cap the cohort date. Put both numbers on the board — the diluted
 one is what the chart shows, and naming why is a better demo than hiding it.
 
-**Time-to-convert is a MEAN, and means are tail-dominated.** Funnel frames carry
+**These funnel response fields report means.** Funnel frames carry
 `avg_time` and `avg_time_from_start` (seconds; not monotonic across steps — each is
 over that step's own survivors). A dungeon knob expressed as a median ratio will not
 reproduce: Square's designed 13x median gap measured 1.95x as a mean over a 30-day
-window. Use the **speed curve** instead — run the same funnel at 1/3/7/14-day
+window. A **speed curve** can supplement the report: run the same funnel at 1/3/7/14-day
 conversion windows and read what share of each segment's eventual conversions had
-landed by then. Same effect, expressed in a statistic Mixpanel actually computes.
+landed by then. Preserve the requested real report and its statistic. A speed
+curve cannot silently replace its acceptance check.
 
 ### 3. Auto-detect the data window
 
@@ -243,10 +265,14 @@ filters have to move into `show[i].behavior.filters`.
 - **structure** — every registered entity still exists.
 - **stories** — re-measure each hook effect live and compare to the knob.
 
-Report MATCH / DIRECTIONAL / MISS per story and exit non-zero on any MISS.
-Use a wider tolerance than the dungeon's own ±10% bar (~25%): Mixpanel's cohort
-membership is computed over the whole window, not the dungeon's internal binning,
-so depth-band style cohorts will not line up exactly.
+Report MATCH / DIRECTIONAL / MISS / INSUFFICIENT_EVIDENCE per story. Exit non-zero
+on a MISS or unresolved evidence gap; insufficient eligible users or converters
+are neither a pass nor a measured miss. Use each story's declared tolerance.
+Document report-semantic differences separately rather than widening tolerances.
+Preserve explicit counting options: local totals default to `reentry: false`.
+Derive local sessions from the full user stream before HPC partitioning; local
+defaults are UTC, 30-minute idle timeout, and 24-hour maximum. Project exclusions
+and timezone variants remain outside the source-derived proof.
 
 ### 7. Report
 
@@ -296,8 +322,9 @@ every build. Prefer one report with N metrics wherever the chart allows it.
 **`ws._api_client` is lazy** — None immediately after construction. Force it via
 `ws._get_api_client()` before patching request headers.
 
-**Idempotency.** Dashboards: delete-by-title then recreate. Everything else:
-look up by name and reuse. Re-running must never duplicate.
+**Idempotency.** Dashboards: create the replacement first, then retire only the
+recorded old ids after confirmation. Everything else: look up by name and reuse.
+Re-running must never duplicate.
 
 ## Commands
 

package/.claude/skills/powertools/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: powertools
 description: Use when any task needs the Mixpanel Power Tools API ("use powertools") — schema export (get-schema), event volumes, project CRUD, query methods, macros, or snapshotting a prod project's schema to copy it into a dungeon. Companion to create-project (which handles provisioning specifically).
-argument-hint: [what to do, e.g. "get schema for project 12345" or "copy project 12345 into a dungeon"]
+argument-hint: '[what to do, e.g. "get schema for project 12345" or "copy project 12345 into a dungeon"]'
 ---
 
 # Power Tools API
@@ -10,7 +10,9 @@ Base URL: `https://mixpanel-power-tools-api-lmozz6xkha-uc.a.run.app`
 
 ## Auth model — read this first
 
-- **GET any endpoint path = documentation, no auth.** Always `curl -s GET <base><path>` before first use of an unfamiliar endpoint — docs include exact body params and response shapes.
+- **GET any endpoint path = documentation, no auth.** For authorized online work,
+  GET an unfamiliar endpoint's docs before use. During offline verification, use
+  local references and report unavailable documentation; make no network calls.
 - **POST = execute.** `Authorization: Bearer <oauth-token>` (employee OAuth from repo `.env` `BEARER_TOKEN`, or a customer's OAuth token) or `Basic base64(service_acct:secret)`.
 - **Customer OAuth tokens are accepted** (verified 2026-07-06): `/auth` and `/macro/get-schema` work with a customer token on projects that token can access. `ai_endpoints_allowed: false` for non-employees — the `ai-*` family stays employee-only.
 - **Every POST body** should include `client_id: "dungeon-master"` and `region` (`US` default).
@@ -43,7 +45,28 @@ node .claude/skills/powertools/snapshot-project.mjs <project_id> --bearer <token
 
 ## Endpoint catalog (the useful subset)
 
-GET the path for full docs. Full list: GET `/` and GET `/macro`.
+### Warehouse handoff (v1.8.0)
+
+For a dungeon with `warehouseMetrics`, use `/warehouse-metrics` after local
+verification produces disk tables and a manifest, and `/create-project` writes
+the project id. Pass the explicit verified `--data-prefix`; preserve those files.
+That skill owns load, source setup, SQL preview, and metric create-or-skip.
+Reuse `/macro/setup-bq-warehouse` through `pt.mjs`; do not reimplement its
+source creation, GCP IAM grant, or dataset ACL handling here.
+
+Warehouse metric endpoints include `getWarehouseMetrics`, `previewWarehouseMetric`,
+`createWarehouseMetric`, and `refreshWarehouseMetric` in the `/crud` family.
+Read endpoint docs before live use. Preview executes the read query; create does
+not validate SQL, and refresh only invalidates cache. A docs-route 404 uses the
+warehouse skill's manual-setup fallback; other errors must surface.
+
+`standaloneEvents` imports as a separate event stream through the ordinary sender.
+Its synthetic ids are series keys, so schema snapshots and dashboard counts must
+distinguish cadence telemetry from user `events[]`. It is not a warehouse source.
+
+During authorized online work, GET the path for full docs. Full list: GET `/`
+and GET `/macro`. Preserve explicit report options when comparing local and live
+queries; see the [1.8.1 verification contract](../verify-dungeon/references/alignment-contract.md).
 
 **crud** — 187 endpoints. GET `/crud` for the full list.
 

package/.claude/skills/release-check/SKILL.md

@@ -0,0 +1,124 @@
+---
+name: release-check
+description: "Use before a dungeon-master release to audit versioned docs, skills, tests, determinism, package contents, and Git state; report release blockers and prepare an explicitly authorized PR and merge handoff."
+argument-hint: "[version, e.g. 1.8.0] [optional base branch]"
+---
+
+# Release check
+
+Check the current checkout before release. Read `AGENTS.md`, `package.json`,
+the target changelog entry, and its upgrade guide. Default to validation only.
+Never publish to npm unless the user gives explicit authorization for npm publishing.
+An instruction to merge a PR is not permission to publish a package.
+
+## Establish the release scope
+
+1. Inspect `git status --short`, the current branch, remotes, and recent history.
+   Preserve unrelated changes. Never reset or clean the worktree to make checks pass.
+2. Confirm the requested version matches `package.json`, the lockfile, changelog,
+   and guide. Do not invent a release date or bump a version without authorization.
+3. Compare the release diff against the base branch. Check exports, dependencies,
+   config defaults, compatibility notes, examples, and migration instructions.
+4. Inspect test setup before running it. This repo's suite prunes `data/` and `tmp/`.
+   If pending deployment artifacts exist, preserve them outside those directories
+   or obtain consent before running the suite. Do not silently delete verified inputs.
+
+## Run executable gates
+
+Use `set -o pipefail` for every piped command. Keep all Vitest output behind
+`2>&1 | tail -50`; a successful tail command alone is not passing evidence.
+
+```bash
+set -o pipefail
+npm test 2>&1 | tail -50
+npm run typecheck
+git diff --check
+npx vitest run tests/unit/engine-shape-canary.test.js 2>&1 | tail -50
+RUN_FULL_SWEEP=1 npx vitest run tests/e2e/engine-shape-full-sweep.test.js 2>&1 | tail -50
+node tests/engine/smoke-test-all.mjs
+npm pack --dry-run --json
+```
+
+Run commands separately or chain with `&&` so a failure cannot disappear behind
+a later success. Record exit codes, pass/skip counts, and the tested commit/diff.
+The smoke script discovers vertical dungeons only. Verify changed technical or
+customer fixtures separately with the existing verification runners.
+
+`npm test` excludes alignment. Run its independent gates separately:
+
+```bash
+node tests/alignment/run.mjs
+node tests/alignment/run.mjs --sweep --timeout-ms=600000
+```
+
+Run the sweep when required by release scope. Both commands enforce macOS network
+denial and a ten-minute maximum. If editor tasks are unavailable, use these
+repository commands. If the runner or platform is unavailable, report NOT RUN;
+do not substitute unsandboxed execution. Offline checks must use installed
+dependencies, OS network denial, and empty global/setup-file lists. The default
+suite above is not the offline audit route: do not run pruning setup, customer
+evaluations, imports, or industry-generation scripts during an offline docs audit.
+For a skills-only audit, run only `tests/e2e/skills-contract.test.js` with
+`configFile: false`, that exact include, `globals: true`, `globalSetup: []`,
+`setupFiles: []`, `fileParallelism: false`, and `sequence.concurrent: false`
+through programmatic Vitest under `sandbox-exec` network denial.
+
+For generation changes, require the event-stream determinism test. Compare runs
+with the same seed, pinned window, and `concurrency: 1`; strip only `insert_id`.
+Use sequential test cases because the RNG is shared. Include warehouse noise in
+warehouse determinism checks. Never accept an unrun or failing determinism gate.
+
+## Audit docs and skills
+
+- Run `tests/e2e/skills-contract.test.js`. Parse YAML frontmatter rather than
+  guessing from appearance: names match folders, descriptions are strings, and
+  `argument-hint` is a quoted string.
+- The canonical skills live in `.claude/skills`. Verify `.agents/skills` and
+  `.github/skills` resolve to that directory. Do not duplicate skill content.
+- Check README, HOOKS, type comments, changelog, and guide against actual code.
+  Do not carry stale test counts, old skill paths, or historical operational
+  failures forward as current release claims.
+- Audit the documented order of the complete handoff: author, optional hooks, verify, provision,
+  generate/import, optional `/warehouse-metrics`, then headless build.
+  Offline release verification does not execute provisioning, imports, warehouse
+  deployment, or headless builds.
+- Distinguish user events, identity-less `standaloneEvents`, and warehouse rows.
+  Synthetic IDs are not people. Standalone hooks return retained records;
+  warehouse hooks mutate rows and ignore returns. Preserve deployment artifacts.
+- If API integrations changed, read local endpoint docs and handback evidence
+  during offline checks. Fetch endpoint docs only during authorized online work.
+  Distinguish docs discovery, mocked execution, dry-run, and live verification.
+  Live writes require explicit authorization. Never claim an endpoint GET proves
+  authenticated write permission or end-to-end deployment.
+
+## Inspect the package and internal files
+
+Read the file list from `npm pack --dry-run --json`. Confirm new runtime modules,
+dependencies, scripts, and canonical skill files ship. Reject credentials,
+customer data, `plans/`, `research/`, `.superpowers/`, or obsolete skill paths.
+Check symlink handling in the package separately from workspace discovery.
+
+Verify `git ls-files .superpowers` is empty and `.gitignore` covers the directory.
+Ignoring an already tracked file does not untrack it. Obtain authorization before
+removing index entries; preserve local reports. Archive completed plan folders
+whole under `plans/archived/`; leave active or ambiguous work in place.
+
+## Report and optional shipping handoff
+
+Report blockers first, then evidence, skipped checks, compatibility changes,
+and remaining operational limits. Do not fix unrelated failures or weaken tests.
+Apply the [1.8.1 verification contract](../verify-dungeon/references/alignment-contract.md):
+report source-derived scope and remaining gaps, separate insufficient evidence
+from passes and measured failures, and preserve actual deployment reports.
+
+Only when explicitly requested: inspect all staged files for secrets, commit the
+authorized changes, push the feature branch, create or reuse its PR, and inspect
+CI and mergeability. Require successful completed checks for the current PR head
+before squash merge. If no CI checks are configured, report that explicitly and
+use recorded local release gates; do not describe absent CI as passing. A failed
+release gate requires investigation and an explicit operator decision before shipping.
+Never bypass protections or use admin merge
+to hide a failing check. Confirm the PR is merged before switching local branches.
+Fetch, switch to `main`, and pull with `--ff-only`; stop rather than discard local
+changes or divergent commits. Report the PR URL, merge SHA, current branch, and
+working-tree status. Leave npm publishing to the operator unless separately authorized.

package/.claude/skills/verify-dungeon/SKILL.md

@@ -1,14 +1,14 @@
 ---
 name: verify-dungeon
-description: Use when a dungeon's hooks need verification before pushing data to Mixpanel — runs the dungeon at full scale, evaluates the dungeon's `stories` export with the mechanical story runner (verify-stories.mjs), validates schema integrity (catches flag-stamping), and reports per-hook NAILED/STRONG/WEAK/NONE/INVERSE verdicts. LLM investigation is reserved for failures and duckdb-type assertions.
-argument-hint: [dungeon path(s), e.g. dungeons/vertical/gaming/gaming.js or dungeons/vertical/fintech/fintech.js]
+description: Use when a dungeon needs verification before import or warehouse deployment, including standaloneEvents cadence streams and warehouseMetrics tables. Runs full-scale story checks, schema validation, and automatic warehouse audits even without stories. Reports per-hook NAILED/STRONG/WEAK/NONE/INVERSE verdicts; investigates failures and duckdb assertions.
+argument-hint: '[dungeon path(s), e.g. dungeons/vertical/gaming/gaming.js or dungeons/vertical/fintech/fintech.js]'
 model: claude-opus-4-6
 effort: max
 ---
 
 # Verify Dungeon
 
-Verify a dungeon at full scale: run the story runner (`scripts/verify-stories.mjs`) as the primary mechanical check, validate schema integrity, investigate only what the runner can't settle (failures + `duckdb`-type assertions), write a single consolidated `hook-results.md`.
+Verify a dungeon at its configured scale: run `scripts/verify-stories.mjs`, validate schema, and review report semantics and evidence sufficiency for every story. Investigate misses, bespoke SQL, and semantic gaps, then write one consolidated `hook-results.md`.
 
 **Dungeon file(s):** `$ARGUMENTS` — single path, multiple space-separated paths, or glob pattern. In batch mode, process each dungeon sequentially through Steps 1–5, then write one consolidated report in Step 7. Use a unique `name` prefix per dungeon (e.g., `verify-fintech`, `verify-gaming`) so output files don't collide.
 
@@ -16,6 +16,7 @@ Verify a dungeon at full scale: run the story runner (`scripts/verify-stories.mj
 
 Load these on demand:
 
+- [references/alignment-contract.md](references/alignment-contract.md) - required 1.8.1 proof contract: independent report specification, neutral controls, sufficient populations, and source-derived limits.
 - [references/counting-semantics.md](references/counting-semantics.md) — Mixpanel counting rules, when to use the emulator vs DuckDB, emulator analysis types, identity-model verification, time-series, common gotchas.
 - [references/sql-recipes.md](references/sql-recipes.md) — every DuckDB query template (schema validation, identity / experiment invariants, hook archetype queries, pitfalls, TTC verification, dataset-window computation).
 - [references/report-format.md](references/report-format.md) — single + multi-dungeon report templates, per-hook detail block, verdict criteria, query log format, mandatory verification SQL file for user dungeons.
@@ -35,17 +36,24 @@ Read the dungeon at `$ARGUMENTS`. If it's a bare filename (no `/`), check `dunge
 
 For each hook/pattern, catalog:
 - Hook number and name (e.g., "Hook #1: Compass users have 3x quest completion")
-- Hook type (`event`, `everything`, `funnel-pre`, `funnel-post`, `user`, `scd-pre`)
+- Hook type (`event`, `everything`, `funnel-pre`, `funnel-post`, `user`, `scd-pre`, `standalone`, `warehouse`)
 - Mechanism — what the code actually does
 - Expected signal — specific, measurable outcome (e.g., "compass_user=true events should have ~1.5x reward_gold")
-- Which output file the signal lives in (events, users, groups)
+- Which output file the signal lives in (user events, users, groups, standalone cadence shards, warehouse tables)
 - Mixpanel report instructions — flag missing/vague ones for the report
 
+Before running, write the independent report specification from the intended
+analysis, then compare the assertion's actual options and defaults with it.
+Plan paired baselines and neutral controls using the shared contract.
+
 ### Step 2: Run the dungeon
 
 The runner already exists at `scripts/verify-runner.mjs`. Use it — do NOT recreate.
 
-**ALWAYS run at full fidelity. Never use `--small` for verification.** `--small` runs (1K users, 100K events) compress per-cohort populations and shift ratios within ±25%, hiding real bugs and flagging fake ones. They exist in the runner only as a developer-troubleshooting escape hatch.
+**Run at full fidelity for acceptance.** `--small` is for troubleshooting only.
+Configured scale does not guarantee sufficient eligible users or converters.
+Report `INSUFFICIENT_EVIDENCE` when actual independent populations or observation
+horizons cannot support the claim; do not classify sparse data as a measured miss.
 
 ```bash
 node scripts/verify-runner.mjs <dungeon-path> <run-name>
@@ -59,16 +67,25 @@ node scripts/verify-runner.mjs dungeons/vertical/gaming/gaming.js verify-gaming
 Full-fidelity runs can take minutes (50K+ user dungeons). Plan accordingly — kick off the run, do other reading, return when the file lands. If a run takes longer than your budget, report that as a finding ("dungeon too large to verify in current session") rather than falling back to `--small`.
 
 **Expected output files** (in `./data/`, prefixed by `<run-name>`):
-- `<run-name>-EVENTS.json` — all events (JSONL)
+- `<run-name>-EVENTS.json` — user events only (JSONL)
 - `<run-name>-USERS.json` — user profiles
 - `<run-name>-*-GROUPS.json` — group profiles (if dungeon has groups)
 - `<run-name>-*-SCD.json` — SCD data (if dungeon has SCDs)
+- `<run-name>-STANDALONE*.json` — `standaloneEvents` cadence records, separate from users
+- `<run-name>-WAREHOUSE-<metric>.*` — `warehouseMetrics` tables; use manifest paths and formats
+- `<run-name>-WAREHOUSE-MANIFEST.json` — table columns, grain, paths, SQL, and deployment metadata
+
+Use local disk output, `format: 'json'`, `gzip: false`, and sending disabled
+(`token: ''`) for this verification path. The existing runner supplies these
+overrides. Record the exact prefix, for example `data/verify-gaming`, and pass
+it explicitly to every downstream command. Preserve table files and their
+matching manifest for `/warehouse-metrics`; do not regenerate silently.
 
 For batched output (>2M events), the runner writes `<run-name>-EVENTS-part-*.json`. See [sql-recipes.md "Multi-part EVENTS files"](references/sql-recipes.md#multi-part-events-files-batch-mode).
 
 ### Step 3: Run the story runner (primary mechanical check)
 
-For any dungeon with a `stories` export, the runner — not the LLM — computes the verdicts:
+Run this for any dungeon with a `stories` export or `warehouseMetrics`:
 
 ```bash
 node scripts/verify-stories.mjs <dungeon-path> --data-prefix <run-name>
@@ -77,28 +94,66 @@ node scripts/verify-stories.mjs <dungeon-path> --data-prefix <run-name> --json
 
 The runner streams the shards from Step 2, evaluates every assertion against its declared `target` / `floor` / `minCohort`, substitutes `{{PREFIX}}` into `duckdb`-type assertions and shells them out, enforces hook coverage (every numbered hook in the HOOK STORIES comment block must be targeted by at least one story), and prints a five-tier verdict table. Exit code is non-zero when any story lands WEAK / NONE / INVERSE or coverage is incomplete.
 
-**Verdicts are computed, not judged.** They include the population floor: a cohort smaller than the assertion's `minCohort` caps at WEAK — a 12-user cohort can no longer score NAILED regardless of how clean its ratio looks. See [report-format.md "Verdict criteria"](references/report-format.md#verdict-criteria-5-tier) for the mechanical definitions.
+When the dungeon declares `warehouseMetrics`, the runner also performs an automatic warehouse shape audit even if the dungeon exports no `stories`: it checks declared-column integrity, dense-gap absence, monotonic time ordering, empty numeric cells, sparse repeated-value suppression, and row-count sanity against the dataset window. Audit failures are reported alongside story verdicts and fail the CLI.
+
+Warehouse stories support `warehouse` row assertions and `warehouse-stats`
+summary assertions in the story schema. Automatic audits do not replace engineered story
+assertions, and an audit-only dungeon must not be reported as having passing stories.
+
+If a request calls these checks `rawStats`, translate that intent into supported
+`warehouse-stats` fields or disk DuckDB. There is no `rawStats` breakdown type
+in the local story schema or dispatcher. Inspect `lib/verify/warehouse.js` and
+`lib/verify/story-runner.js` for the available summary fields; never invent one.
+
+For `standaloneEvents`, use disk-backed `duckdb` assertions with
+`read_json_auto('{{PREFIX}}-STANDALONE*.json', union_by_name=true, sample_size=-1)`.
+The CLI's emulator input contains user EVENTS shards only. `--in-memory` skips
+disk-only DuckDB assertions; it cannot prove standalone stories. The disk CLI
+also requires nonempty user EVENTS shards. For a standalone-only artifact set
+without those shards, run the same SQL directly and report that CLI limitation.
+A standalone-only config without stories does not receive an automatic cadence
+audit; perform the explicit schema, tick, dimension, and identity checks below.
+
+**Verdicts are computed, not judged.** `minCohort` caps verdicts when supported
+selected-row population fields fall below the floor. It does not validate every
+denominator or establish full proof. Check actual eligible users/converters and
+mature observation windows separately. See [report-format.md "Verdict criteria"](references/report-format.md#verdict-criteria-5-tier).
 
-**What the LLM investigates after this step — and nothing else:**
-1. **Stories below STRONG** (WEAK / NONE / INVERSE) — root-cause via Step 5's decision table. A miss means fixing the hook or the assertion's derivation, never relaxing the number to match output.
-2. **`duckdb`-type assertions** — the runner executes them but can't interpret bespoke shapes; sanity-check their output against the story narrative.
-3. **Dungeons without a `stories` export** — legacy fallback: full per-hook flow (Step 5) for every documented hook.
+**What to review after this step:**
+1. **Every story, including passing targets** - check its options against the independent report specification and inspect neutral controls and population sufficiency. An inherited default can verify the wrong report.
+2. **Stories below STRONG** (WEAK / NONE / INVERSE) - root-cause via Step 5. Distinguish insufficient evidence from an effect failure; never relax a target to match output.
+3. **`duckdb`-type assertions** - the runner executes them but cannot validate the bespoke query's report semantics.
+4. **Dungeons without a `stories` export** - legacy fallback: Step 5 for every documented hook.
 
-Do NOT re-derive verdicts the runner already computed as passing. `hook-results.md` (Step 7) renders the runner's JSON.
+Preserve computed verdicts in `hook-results.md`. Add separate semantic and evidence
+statuses; a passing runner verdict alone does not establish acceptance.
 
 ### Step 4: Validate schema (BEFORE per-hook checks)
 
 Catches hooks that introduce undeclared columns (flag stamping). For each unique event type, compare actual columns against config-declared properties. See [sql-recipes.md "Schema validation queries"](references/sql-recipes.md#schema-validation-queries) for the SQL and the expected-schema source table.
 
+Keep schemas separate. User-event checks use `events[]`, superProps, and enabled
+SDK fields. Standalone checks use only core `event`, `time`, `insert_id`,
+`distinct_id`, plus that spec's dimensions and properties. Require no `user_id`
+or `device_id`; synthetic ids never count as people. Check one row per cadence
+tick and dimension tuple unless a documented hook intentionally changes it.
+Warehouse checks use the manifest's fixed columns and the metric's time column,
+group keys, value column, and declared extras. Never apply user superProp or
+identity requirements to cadence records or warehouse rows.
+
 **Schema verdicts:**
-- **SCHEMA-PASS** — added column appears on 100% of events of this type (uniform enrichment, acceptable)
-- **SCHEMA-FAIL** — added column appears on <100% (flag stamping; conditional property creates inconsistent schema)
+- **SCHEMA-PASS** - every output property is declared or a recognized enabled engine/SDK field for this stream.
+- **SCHEMA-FAIL** - any undeclared property, even at 100% coverage. Uniform flag stamping still violates schema-first authorship.
+
+If the runtime validator permits uniform enrichment, record that result separately
+and enforce this stricter authorship gate explicitly.
 
 If any event type has SCHEMA-FAIL, flag it prominently in the report header with specific remediation: which hook line adds the property and how to remove it while preserving the intended pattern.
 
 ### Step 5: Investigate failures (and legacy no-stories dungeons)
 
-Applies only to the investigation targets from Step 3 — failing stories, `duckdb`-type assertions, and dungeons with no `stories` export.
+Applies to Step 3's targets: failed stories, semantic or evidence gaps (including
+passing targets), bespoke SQL, and dungeons with no `stories` export.
 
 **Decision: emulator vs DuckDB**
 
@@ -121,12 +176,17 @@ Applies only to the investigation targets from Step 3 — failing stories, `duck
 | Identity-model invariants | DuckDB |
 | Experiment invariants | DuckDB |
 | True bespokes (no emulator analysis fits) | DuckDB |
+| Standalone cadence values, dimensions, tick counts | Disk DuckDB on `{{PREFIX}}-STANDALONE*.json` |
+| Warehouse value stories | `warehouse` or `warehouse-stats` assertion |
+| Warehouse schema, gaps, ordering, numeric cells | Automatic warehouse audit, with or without stories |
 
 The emulator now covers lifecycle, flows, sessions, event breakdowns, formulas, and compounded retention — DuckDB's remit is schema / identity / experiment invariants plus true bespoke shapes. If a "bespoke" check is really a funnel, frequency, path, or breakdown in disguise, it belongs in the emulator.
 
 **Hand-written DuckDB funnel SQL diverges from Mixpanel — never hand-roll.** If you find yourself writing `WITH step1 AS ..., step2 AS ...` for a funnel, STOP — use `emulateBreakdown` with `funnelFrequency` instead.
 
-For emulator details, identity-model dungeons (must pass `profiles`), and time-series breakdown via `timeBucket`, see [counting-semantics.md](references/counting-semantics.md). For DuckDB query templates by hook archetype, pitfalls, and standard checks, see [sql-recipes.md](references/sql-recipes.md).
+For emulator options, emitted-evidence identity maps, profile segments, and
+time-series breakdown via `timeBucket`, see [counting-semantics.md](references/counting-semantics.md).
+For DuckDB diagnostics and standard checks, see [sql-recipes.md](references/sql-recipes.md).
 
 **Always run for every dungeon** (before per-hook checks):
 - Standard identity-model invariants (stitch counts, pre-existing user stamping) when the dungeon uses the identity model
@@ -142,9 +202,9 @@ generated artifacts into `dungeons/user/<name>/`:
 - `hook-query-log.txt` (Step 6)
 - `<name>-verifications.sql` (Step 7b)
 
-The ONLY exception is the throwaway verification data the run writes to
-`./data/` (`verify-*` event/user files) — that stays in `./data/` and is
-deleted in Step 8.
+The exception is run data under `./data/`, including cadence shards, warehouse
+tables, and the manifest. Keep it under its explicit prefix until verification
+and deployment finish. Step 8 requires consent before any scoped cleanup.
 
 For non-user dungeons (technical/vertical) or batch runs across many dungeons,
 fall back to `./research/` for `hook-results.md` / `hook-query-log.txt`.
@@ -159,7 +219,7 @@ Format and conventions: see [report-format.md "Query log format"](references/rep
 
 ### Step 7: Write `hook-results.md`
 
-Write to `dungeons/user/<name>/hook-results.md` for a user dungeon, else `./research/hook-results.md`. For story-backed dungeons, **the report renders the runner's JSON** (`verify-stories.mjs --json`): the hook summary table comes straight from the runner's per-story verdicts (story id, hook, archetype, observed vs target, verdict), and detailed blocks exist only for the Step-3 investigation targets. Use the templates in [report-format.md](references/report-format.md):
+Write to `dungeons/user/<name>/hook-results.md` for a user dungeon, else `./research/hook-results.md`. Preserve the runner's JSON verdicts alongside independent semantic and evidence statuses, eligible populations, neutral controls, and source-derived scope. Add details for Step 3's investigation targets. Use [report-format.md](references/report-format.md):
 - Single-dungeon report structure
 - Multi-dungeon report structure (when batch mode)
 - Per-hook detail block
@@ -171,22 +231,25 @@ Write to `dungeons/user/<name>/hook-results.md` for a user dungeon, else `./rese
 
 When verifying a dungeon in `dungeons/user/`, also write a standalone DuckDB SQL file alongside the dungeon in its folder at `dungeons/user/<name>/<name>-verifications.sql`. Vertical dungeons already have their SQL co-located at `dungeons/vertical/<name>/<name>.sql`. Format: see [report-format.md "Verification SQL file"](references/report-format.md#verification-sql-file-mandatory-for-user-dungeons).
 
-### Step 8: Cleanup
+### Step 8: Preserve artifacts and hand off
 
-```bash
-rm -f ./data/verify-* ./verify-*
-```
+Record the exact verified prefix and retained files in the report. If warehouse
+tables are present, provision with `/create-project`, then hand off to
+`/warehouse-metrics` using `--data-prefix <verified-prefix>`. Provisioning and
+ordinary event import do not deploy these tables.
 
-Remove ALL files matching `verify-*` in `./data/` and project root. Also remove any temporary runner scripts.
+Do not run blanket prune or delete `verify-*` globs. Only after deployment is
+complete, list files for this exact run and obtain user consent for scoped
+cleanup. Keep reports and reproducible SQL. Do not delete files during an audit.
 
 ## Hook execution model
 
 Per user, hooks fire in this order:
 
 1. `"user"` — profile created (mutate in-place; return ignored)
-2. `"scd-pre"` — SCD entries created (mutate in-place OR return new array)
+2. `"scd-pre"` — SCD entries created (mutate in-place; return ignored)
 3. For each funnel: `"funnel-pre"` → `"event"` (per step) → `"funnel-post"`
-4. `"event"` — for non-funnel standalone events (return value REPLACES the event)
+4. `"event"` — for non-funnel user events from `events[]` (return value REPLACES the event)
 5. `"everything"` — array of ALL the user's events (return array to replace)
 6. **Storage phase** — data written to disk. Hooks for `event`, `user`, `scd` do NOT re-fire (already applied above). Hooks for `mirror`, `ad-spend`, `group`, `lookup` fire only in storage.
 
@@ -195,6 +258,15 @@ Return-value behavior:
 - `everything` hook: return value IS used if it's an array (replaces event list)
 - `user`, `scd-pre`, `funnel-post`: return value IGNORED — only in-place mutations work
 - `funnel-pre`: return value IGNORED — mutate the `record` object in-place (e.g., `record.conversionRate = 0.9`)
+- `standalone`: runs before the user loop. Return an object or array; `undefined`
+	drops the record. `meta.spec` and `meta.config` describe the cadence stream.
+- `warehouse`: runs after the user loop. Mutate the row; return value is ignored.
+	Meta includes `spec`, `config`, `metricName`, bucket fields, `grain`,
+	`seriesKey`, `isBackfill`, and `raw` source aggregates.
+
+Neither `standalone` nor `warehouse` receives person metadata or passes through
+`everything`. Their generation phases differ even though both hooks fire on
+storage push. Other storage-only types return objects or arrays to retain rows.
 
 ## Final output
 
@@ -204,5 +276,7 @@ Tell the user:
 3. Query log path (if written): alongside the report (`dungeons/user/<name>/hook-query-log.txt`, else `./research/hook-query-log.txt`)
 4. Verdict counts from the story runner (per dungeon if batch mode), plus which stories needed LLM investigation
 5. One-line summary of the most interesting finding
+6. Separate standalone checks and `warehouseAudits`, including audit-only runs,
+   skipped assertions, retained artifact prefix, and warehouse deployment handoff
 
 If hooks failed, note that `hook-results.md` can be used as context for fixing them: "read hook-results.md and fix the failing hooks in <dungeon-file>".

package/.claude/skills/verify-dungeon/references/alignment-contract.md

@@ -0,0 +1,84 @@
+# 1.8.1 verification contract
+
+Use this contract when authoring, verifying, provisioning, or presenting a dungeon.
+The [1.8.1 guide](../../../../docs/guides/1.8.1-upgrade-guide.md) describes the
+release. The local repository's `tests/alignment/REPORT.md` and
+`tests/alignment/API-COMPATIBILITY.md` retain the audit evidence; those test
+artifacts are not shipped in npm.
+
+## Define the report before measuring
+
+Write an independent report specification before choosing assertions. Record
+events, filters, identity rules, cohort definition, denominator, statistic,
+window, timezone, ordering, reentry, session settings, and property selection.
+Compare every assertion with that specification, including passing assertions.
+An inherited default can pass the wrong report. Do not replace funnel TTC with
+a numeric property, a mean with a median, or conversion with event volume to
+rescue a failed story. Supplementary diagnostics must keep their own labels.
+
+Local checks prove selected source-derived contracts, not universal Mixpanel
+parity. The audit read analytics source without compiling or executing it. It
+did not run live differential queries. Macro/soup interactions, table surfaces,
+arbitrary hooks, parallel execution, and several counting variants remain gaps.
+
+## Separate a measured effect from enough evidence
+
+Retain the story runner's computed verdict. Report semantic correctness and
+evidence sufficiency separately. Full-fidelity scale does not guarantee enough
+independent eligible users, mature retention cohorts, or converters. Inspect the
+actual denominator on each side; event count is not independent user count.
+`minCohort` checks supported selected-row population fields, not every bespoke
+denominator. Meeting it alone is not full proof. Label unresolved acceptance
+`INSUFFICIENT_EVIDENCE`; do not count it as a pass or a measured effect failure.
+
+For engineered effects, measure a paired baseline with the same seed, window,
+and report options. Add a neutral control (factor one, zero injection, or hook
+disabled) and an unaffected control cohort where applicable. A factor-one
+control must be measured, not inferred from two differently modified groups.
+Report baseline, treatment, eligible users/converters, and paired lift. Keep
+targets and tolerances fixed before the run; disclose any revised criterion
+and preserve its original failed evidence.
+
+## Preserve the local counting boundaries
+
+- `Funnel.reentry` is verifier-only. Generated repetitions depend on usage
+  selection and event budget. Local `reentry` defaults to `false`, including
+  `countMode: 'totals'`; repeated histories require explicit `reentry: true`.
+- Funnel histories include ordered restart/shared-edge behavior and inclusive
+  2000ms completion grace. TTC uses completed histories under the requested
+  options, not independent first occurrences of each event. First/last segment
+  selection merges reached-step properties with defined fallback values;
+  explicit-step selection is separate.
+- Derive sessions from the full resolved user stream before HPC partitioning.
+  Local defaults are UTC, a 30-minute idle timeout, and a 24-hour maximum.
+  `session_id` is a diagnostic or explicit legacy mode, not the default truth.
+  Non-UTC projects, list-valued HPC, and project-specific hidden/excluded session
+  events remain outside this proof.
+- Profile device pools alone establish no identity mapping evidence. The public
+  `buildIdentityMap(profiles)` helper retains profile-based compatibility behavior.
+  For emitted-identity proof, derive links from valid ordinary both-ID events,
+  including later Login events, and pass that explicit `identityMap` to the
+  verifier. Earlier device-only rows can resolve retrospectively. Report ID
+  conflicts and validation limits; generator auth policy is not ingestion parity.
+- `applyPathBias` is append-only. `share` selects eligible injection recipients;
+  it does not promise exact visible branch share. Measure appended payloads,
+  competing events, observed path share, and paired lift separately.
+- `applySessionShape` preserves records. Pass known `datasetStart`/`datasetEnd`
+  bounds when clipping matters. Explicit bounds reject insufficient capacity
+  before mutation; unbounded placement can cross an unknown dataset end.
+- `retentionCurve` weights active-day plans. Budget, funnel spill, and observation
+  horizon can prevent literal requested retention percentages. Usage anchors do
+  not accumulate previous funnel TTC; retries belong to born-user first funnels.
+
+## Keep schema and operational gates independent
+
+Undeclared output properties fail schema review even at 100% coverage. Accept
+only config-declared properties or recognized engine/SDK fields enabled for that
+stream. A permissive runtime schema summary cannot override this authorship rule.
+Keep user events, standalone cadence, and warehouse schemas separate.
+
+Offline verification stops at local evidence and a deployment handoff. Do not
+automatically provision, import, probe endpoints, deploy warehouse tables, or run
+headless builds. Retain exact artifact prefixes and actual deployment reports.
+Dry-run output is a plan, not evidence of a live outcome; preserve existing reports
+before a dry run writes local files. Live work requires separate authorization.