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

package/.claude/skills/analyze-soup/SKILL.md

@@ -169,6 +169,15 @@ its folder. Otherwise write it to the project root. (The generated
 6. **Assessment**: Overall quality judgment and recommendations
 
 ### Quality Criteria
+
+These thresholds are diagnostic heuristics, not alignment acceptance criteria.
+Interpret them against the configured macro, soup, resolved window, and intentional
+hook effects. Read the [1.8.1 verification contract](../verify-dungeon/references/alignment-contract.md)
+for proof scope. Report insufficient observations separately from shape failures.
+Include empty buckets and identify partial buckets before computing distribution
+statistics; the SQL above reports observed buckets only. Sparse or partial buckets
+alone do not establish a distribution defect.
+
 - **Daily CV**: 0.2-0.6 is ideal (some variation, not flat or spiky)
 - **Max-to-avg ratio**: < 2.0 at daily level, < 3.0 at hourly level
 - **Last day spike**: < 1.5x average = PASS, < 2x = WARN, > 2x = FAIL

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

@@ -35,11 +35,12 @@ In scope here:
   - `credentials: { token, region, serviceAccount, serviceSecret, projectId }`
   - `switches: { hasLocation, hasCampaigns, hasSessionIds, hasAvatar,
     hasIOSDevices, hasAndroidDevices, hasDesktopDevices, hasBrowser,
-    isAnonymous, alsoInferFunnels, hasAdSpend, hasAttributionFlags }`
+    isAnonymous, alsoInferFunnels, hasAdSpend }`
   - `identity: { avgDevicePerUser, sessionTimeout }`
 
   Old top-level keys keep working (verbose warn nudges migration), but new
   dungeons should ship the sub-object shape.
+  `hasAttributionFlags` is derived from `events[].isAttributionEvent`; do not set it.
 - Surviving advanced entities: `personas`, `worldEvents`, `engagementDecay`,
   `dataQuality` — use sparingly
 
@@ -64,6 +65,7 @@ see `HOOKS.md` at the project root.
 
 Before writing any code, scan:
 
+- [1.8.1 verification contract](../verify-dungeon/references/alignment-contract.md) - report definitions, neutral controls, and proof limits.
 - `types.d.ts` — the complete API reference. Every Dungeon field, EventConfig
   flag, Funnel option, AttemptsConfig, and Hook meta interface is documented
   with full JSDoc. **Treat this as the source of truth.**
@@ -234,8 +236,8 @@ When using experiments, include `$experiment_started` in the events array with
 
 - First funnel: includes `isFirstEvent` AND has `isAuthEvent: true` on the
   identity-transition step.
-- Usage funnels: ordinary sequences without `isFirstFunnel`. Optionally use
-  `attempts` for repeat-usage modeling (abandon-cart pattern).
+- Usage funnels: ordinary sequences without `isFirstFunnel`. Volume and funnel
+  selection control repetitions; `attempts` applies only to born-user first funnels.
 - Pick `conversionRate` between 30 and 80; `timeToConvert` in hours.
 
 Funnel `props` stamp constant properties on all events in that funnel run.
@@ -267,9 +269,9 @@ consumed standalone instances as funnel matches. Set `isStrictEvent: false`
 explicitly only when you intend mixed funnel/standalone semantics for that
 event.
 
-**Mark hook-readable funnel-step events with `isStrictEvent: false`.** When a hook reads `event === 'X'` and `X` is also a funnel step, the validator's auto-promote turns it into `isStrictEvent: true` and the engine stops emitting standalone occurrences — cohort goes empty. Identify these candidates at schema time so `write-hooks` doesn't have to re-thread the schema. Common candidates: login, page view, search, add to cart, swap, deposit — anything that's both a funnel step AND a recurring user behavior hooks will likely cohort on.
+**Use `isStrictEvent: false` when a cohort needs standalone occurrences.** Auto-promotion removes standalone traffic but leaves funnel-generated occurrences readable. Declare the opt-out at schema time only when that extra traffic is part of the intended behavior; a hook reading an event name alone does not require it.
 
-**Funnels representing loops need `reentry: true`.** Any funnel named "X loop" / "X cycle" / "session" / per-instance recurring behavior must declare `reentry: true`. Without it, the engine emits one sequence per user and downstream "power user" / "daily active" cohorts have no behavioral signal to bin on.
+**`reentry` is verifier-only.** Usage volume, funnel selection, and the event budget control generated repetitions. Set `reentry: true` only when the intended report counts repeated histories. It does not generate loops; local totals also default to `reentry: false`.
 
 **Structural trend engineering — duplicate funnels instead of reaching for
 hooks.** Not every trend needs a hook: initial conditions can raise or lower
@@ -294,20 +296,19 @@ to architect a comparison directly into the schema:
 Prefer structure when the story is a *between-path comparison* (this path
 converts worse / slower than that one). Reach for hooks when the story is a
 *within-cohort behavior* (these users do more of X over time, this segment's
-values differ). Structural trends are cheaper to verify — the knob IS the
-expected value.
+values differ). Structural trends still need report-level proof: competing
+histories, saturation, and finite budgets can change the observed effect.
 
 ### 3. SuperProps (2–3)
 
 Properties present on EVERY event. Common picks: `Plan`, `Region`, `Platform`,
-`App Version`. Values must come from same enumerations used in `userProps` for
-consistency.
+`App Version`. Matching `userProps` enumerations only shares a value domain.
+Use `stickyEventProps` for values that must match each user's profile.
 
 ### 4. UserProps (4–8)
 
-User profile properties. Set once per user. Use enumerations whose values
-match `superProps` for any overlapping keys (so per-event Region matches per-user
-Region).
+User profile properties. Set once per user. Declare overlapping event keys in
+`superProps` and use `stickyEventProps` when profile/event equality is required.
 
 ### 5. Groups (0–2)
 
@@ -417,9 +418,9 @@ Typical ranges:
 
 - Direct-acquisition first funnels: `{ min: 0, max: 0 }` (single attempt) or omit
 - Shared-link / friction-heavy onboarding: `{ min: 0, max: 2 }` (some retry)
-- Re-engagement / abandon-cart usage funnels: `{ min: 0, max: 3 }`
+- Usage funnels do not consume this retry plan; model their repetitions through usage selection and volume.
 
-When set, `attempts.conversionRate` (optional) overrides `funnel.conversionRate`
+For a born user's first funnel, `attempts.conversionRate` (optional) overrides `funnel.conversionRate`
 on the FINAL attempt. Failed prior attempts truncate before the first
 `isAuthEvent` step (no stitch fires for those attempts).
 
@@ -504,12 +505,12 @@ intra-day rhythm). Only override when you have a specific reason:
 
 ### Macro × born% / bias compatibility (strict clamps)
 
-When you set `macro` AND `percentUsersBornInDataset` explicitly, the validator
-clamps born% to the macro's preset value: flat=12, steady=12, growth=30,
-viral=55, decline=5. Same for `bornRecentBias` outside `[-0.5, 0.5]`. If you
-need higher born% (e.g., "this app launched mid-window — every user is in the
-dataset"), switch macros first (flat → growth → viral) instead of pushing the
-preset's value. Setting born% without a macro keeps legacy behavior (no clamp).
+The per-preset born% cap applies only to a named preset (`macro: 'growth'` or
+`macro: { preset: 'growth', ... }`) with explicit `percentUsersBornInDataset`:
+flat=12, steady=12, growth=30, viral=55, decline=5. A custom macro object without
+`preset` has no per-preset cap; own and verify its shape. The global born% clamp
+to [0,100] still applies. Explicit `bornRecentBias` is separately clamped to
+[-0.5,0.5], with compound protection for high born% and bias. Preset bias is exempt.
 
 The clamp warning explains why and points to safe alternatives — read it.
 
@@ -574,18 +575,19 @@ Top-level optional knob. Shape retention via log-linear interpolation
 between waypoints. Independent of `engagementDecay`.
 
 ```js
-retentionCurve: [
-  { day: 0,  retention: 1.0 },
-  { day: 1,  retention: 0.80 },
-  { day: 7,  retention: 0.50 },
-  { day: 30, retention: 0.20 },
-]
+retentionCurve: {
+  type: 'logarithmic',
+  day1: 0.80,
+  day7: 0.50,
+  day30: 0.20,
+}
 ```
 
-Each born-in-dataset user's events get filtered based on the interpolated
-retention at the event's age-from-first-event-day. Use when you want a
-declarative retention shape at config level (analytical-style D1/D7/D30
-targets) instead of writing hook logic.
+Use `type: 'logarithmic'` (default) or `'linear'`, with `dayN` active-day
+weights; day 0 is implicitly 1. The curve weights the active-day plan and takes
+precedence over `avgActiveDaysPerUser`. It does not directly filter each event
+or guarantee report D1/D7/D30 percentages. Verify mature cohorts and account for
+funnel spill and finite event budgets.
 
 ### `userSeed` (separate distinct_id RNG seed, v1.5+)
 
@@ -601,16 +603,15 @@ userSeed: "users-v1", // user-pool RNG (stable across versions)
 
 ## SuperProp consistency rule
 
-If `superProps` and `userProps` both define a property like `Plan`, the
-enumeration must match exactly. Otherwise users with `userProps.Plan = 'pro'`
-will fire events with `superProps.Plan = 'free'` — Mixpanel will see broken
-breakdowns.
+Matching enumerations do not guarantee profile/event equality: independent draws
+can differ. Declare both keys and project the profile values with `stickyEventProps`.
 
 ```js
 const PLANS = ["Free", "Free", "Free", "Pro", "Pro", "Enterprise"];
 // ...
 superProps: { Plan: PLANS, Region: REGIONS },
 userProps:  { Plan: PLANS, Region: REGIONS, Role: ROLES, ... },
+stickyEventProps: ['Plan', 'Region'],
 ```
 
 ## Verification

package/.claude/skills/create-project/SKILL.md

@@ -16,6 +16,12 @@ This is the step after a dungeon is authored, reviewed, and tweaked. It turns a
 local dungeon into one you can actually send to Mixpanel by creating the project
 and stamping `credentials` back into the file.
 
+Follow the [1.8.1 verification contract](../verify-dungeon/references/alignment-contract.md)
+when carrying verification claims into business context. Preserve the actual report
+definition and explicit counting options. Local evidence is selected source-derived
+verification, not live Mixpanel parity. Provisioning is a separately authorized
+handoff; never run it automatically during offline verification.
+
 ## What it does
 
 All work runs through the orchestrator `provision.mjs` (this skill's directory),

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

@@ -37,10 +37,14 @@ 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,
@@ -182,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
 
@@ -260,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
 
@@ -313,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

@@ -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).
@@ -62,7 +64,9 @@ warehouse skill's manual-setup fallback; other errors must surface.
 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.
 
-GET the path for full docs. Full list: GET `/` and GET `/macro`.
+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

@@ -44,6 +44,25 @@ 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
@@ -59,12 +78,15 @@ warehouse determinism checks. Never accept an unrun or failing determinism gate.
 - 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.
-- Follow the complete handoff: author, optional hooks, verify, provision,
+- 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 the current endpoint docs and local handback.
+- 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.
@@ -85,6 +107,9 @@ whole under `plans/archived/`; leave active or ambiguous work in place.
 
 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

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

@@ -8,7 +8,7 @@ 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.
@@ -41,11 +42,18 @@ For each hook/pattern, catalog:
 - 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>
@@ -106,14 +114,19 @@ 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.** 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.
+**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)
 
@@ -129,14 +142,18 @@ 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**
 
@@ -167,7 +184,9 @@ The emulator now covers lifecycle, flows, sessions, event breakdowns, formulas,
 
 **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
@@ -200,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

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.