@ak--47/dungeon-master 1.4.5 → 1.5.0

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

@@ -0,0 +1,157 @@
+---
+name: verify-dungeon
+description: Use when a dungeon's hooks need verification before pushing data to Mixpanel — runs the dungeon at full scale, validates schema integrity (catches flag-stamping), queries with DuckDB using Mixpanel-accurate counting semantics, and reports per-hook NAILED/STRONG/WEAK/NONE/INVERSE verdicts.
+argument-hint: [dungeon path(s), e.g. dungeons/gaming.js or dungeons/fintech.js]
+model: claude-opus-4-6
+effort: max
+---
+
+# Verify Dungeon
+
+Verify a dungeon at full scale: validate schema integrity, query the output with the Mixpanel emulator (preferred) or DuckDB, write a single 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–3, then write one consolidated report in Step 4. Use a unique `name` prefix per dungeon (e.g., `verify-fintech`, `verify-gaming`) so output files don't collide.
+
+## Reference files
+
+Load these on demand:
+
+- [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.
+
+Also: `HOOKS.md` (recipe encyclopedia) and `types.d.ts` (source of truth for hook meta interfaces).
+
+## Pipeline
+
+### Step 1: Read & catalog the hooks
+
+Read the dungeon at `$ARGUMENTS`. If it's a bare filename (no `/`), check `dungeons/`. Find:
+
+1. **The `hook:` function** — read the full body
+2. **The documentation comment block** describing engineered patterns
+3. **Module-level closure state** (Map / Set / tracking variables defined outside the hook function but used inside)
+
+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`)
+- 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)
+- Mixpanel report instructions — flag missing/vague ones for the report
+
+### 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.
+
+```bash
+node scripts/verify-runner.mjs <dungeon-path> <run-name>
+```
+
+Example:
+```bash
+node scripts/verify-runner.mjs dungeons/vertical/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>-USERS.json` — user profiles
+- `<run-name>-*-GROUPS.json` — group profiles (if dungeon has groups)
+- `<run-name>-*-SCD.json` — SCD data (if dungeon has SCDs)
+
+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: 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.
+
+**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)
+
+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 4: Verify each hook
+
+**Decision: emulator vs DuckDB**
+
+| Pattern | Use |
+|---|---|
+| Funnel completion / step conversion | `emulateBreakdown({type: 'funnelFrequency'})` |
+| Insights frequency-distribution | `emulateBreakdown({type: 'frequencyByFrequency'})` |
+| Avg(prop) by per-user count(B) | `emulateBreakdown({type: 'aggregatePerUser'})` |
+| Funnel TTC by segment | `emulateBreakdown({type: 'timeToConvert'})` |
+| First/last touch attribution | `emulateBreakdown({type: 'attributedBy'})` |
+| Retention curves | `emulateBreakdown({type: 'retention'})` |
+| Per-session metrics | `emulateBreakdown({type: 'sessionMetrics'})` |
+| Schema integrity / column coverage | DuckDB |
+| Identity-model invariants | DuckDB |
+| Experiment invariants | DuckDB |
+| Bespoke time-window patterns | DuckDB |
+
+**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).
+
+**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
+- Experiment invariants (variant distribution, exposure timing, deterministic assignment) when any funnel uses `experiment:`
+- SuperProp consistency, SuperProp/UserProp mirror, Mixpanel default-property casing, funnel-pre dilution
+
+### Step 5: Stash query log (optional)
+
+If `./research/` exists locally, write every DuckDB query execution to `./research/hook-query-log.txt`. Format and conventions: see [report-format.md "Query log format"](references/report-format.md#query-log-format). If `./research/` does not exist, skip — do not create the directory.
+
+### Step 6: Write `./research/hook-results.md`
+
+Use the templates in [report-format.md](references/report-format.md):
+- Single-dungeon report structure
+- Multi-dungeon report structure (when batch mode)
+- Per-hook detail block
+- Verdict criteria (5-tier)
+
+**Order failures first** within each dungeon section: INVERSE → NONE → WEAK → STRONG → NAILED. Sort the summary table the same way. Actionable issues at the top.
+
+### Step 6b: Write verification SQL (mandatory for user dungeons)
+
+When verifying a dungeon in `dungeons/user/`, also write a standalone DuckDB SQL file at `dungeons/user/<name>-verifications.sql`. Vertical dungeons already have their SQL in `verification/verticals/`. Format: see [report-format.md "Verification SQL file"](references/report-format.md#verification-sql-file-mandatory-for-user-dungeons).
+
+### Step 7: Cleanup
+
+```bash
+rm -f ./data/verify-* ./verify-*
+```
+
+Remove ALL files matching `verify-*` in `./data/` and project root. Also remove any temporary runner scripts.
+
+## 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)
+3. For each funnel: `"funnel-pre"` → `"event"` (per step) → `"funnel-post"`
+4. `"event"` — for non-funnel standalone 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.
+
+Return-value behavior:
+- `event` hook: return value IS used (replaces the event)
+- `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`)
+
+## Final output
+
+Tell the user:
+1. Report path: `./research/hook-results.md`
+2. Verification SQL path (for user dungeons): `dungeons/user/<name>-verifications.sql`
+3. Query log path (if written): `./research/hook-query-log.txt`
+4. Pass/weak/fail counts (per dungeon if batch mode)
+5. One-line summary of the most interesting finding
+
+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/counting-semantics.md

@@ -0,0 +1,161 @@
+# Counting Semantics — Mixpanel-Accurate Verification
+
+Mixpanel does NOT count the way naive SQL does. The verifier (and any DuckDB query you write) must match Mixpanel's rules.
+
+## Core rules
+
+| Concept | Mixpanel rule | Wrong SQL → Right SQL |
+|---------|--------------|----------------------|
+| Frequency / cohort by event count | Distinct calendar days, NOT total events | `COUNT(*)` → `COUNT(DISTINCT date_trunc('day', time::TIMESTAMP))` |
+| Funnels | Greedy single-pass, strict order, 2-second grace | NEVER hand-roll funnel SQL — use `emulateBreakdown` |
+| AVG / SUM / MIN / MAX | Skip null and non-numeric from BOTH num and denom | Always wrap in `TRY_CAST(prop AS DOUBLE)` |
+| Attribution | Cap at 10 touchpoints in lookback | Use `emulateBreakdown` with `attributedBy` |
+| Conversion window | Strict `<` boundary | Read `Funnel.conversionWindowDays` and respect it |
+
+Full rules: see [HOOKS.md Section 2](../../../../HOOKS.md#2-how-mixpanel-counts-things).
+
+## When to use the emulator vs DuckDB
+
+The emulator (`emulateBreakdown` from `@ak--47/dungeon-master/verify`) implements Mixpanel's rules natively. **ALWAYS use the emulator for funnel, frequency, aggregate, TTC, and attribution patterns.** Hand-written DuckDB queries for these pattern types diverge from what Mixpanel shows in reports — even when they look correct.
+
+Use DuckDB ONLY for:
+- Schema integrity checks (column coverage, flag detection)
+- Identity-model invariants (stitch counts, pre-existing user stamping)
+- Experiment invariants (variant distribution, exposure timing)
+- Bespoke patterns that don't fit the emulator analyses
+
+If you find yourself writing `WITH step1 AS ..., step2 AS ...` for a funnel, STOP — use `emulateBreakdown` with `funnelFrequency` instead.
+
+## Emulator analysis types
+
+| Pattern style | Emulator type | Use when |
+|--------------|---------------|----------|
+| count(A) by per-user count(B) | `frequencyByFrequency` | "Insights frequency distribution by per-user count of X" |
+| Funnel completion by per-user count(X) | `funnelFrequency` | "Onboarding magic number" / "engaged users complete more" |
+| avg(prop X) by per-user count(B) | `aggregatePerUser` | "Average order value by sessions per user" |
+| Funnel TTC by user property | `timeToConvert` | "Trial users take 4× longer than enterprise" |
+| First/last touch attribution | `attributedBy` | "Conversions by Source" |
+| Birth retention curves | `retention` | "Sign Up → Login on day N" — requires `cohortEvent`, `returnEvent`, `dayBuckets` |
+| Per-session metrics | `sessionMetrics` | Count / duration / events distributions per session |
+
+Cross-cutting on EVERY type: `timeBucket: 'day' | 'week' | 'month'` partitions events into UTC buckets and emits one row per period.
+
+Quick emulator script:
+
+```js
+import generate from './index.js';
+import { emulateBreakdown } from './lib/verify/index.js';
+
+const r = await generate('./dungeons/<path>.js');
+const events = Array.from(r.eventData);
+console.log(emulateBreakdown(events, {
+  type: 'frequencyByFrequency',
+  metricEvent: 'Purchase',
+  breakdownByFrequencyOf: 'Browse',
+}));
+```
+
+For CI-style assertions, use `verifyDungeon` with a checks array; see `tests/e2e/my-buddy-stories.test.js` for a worked example.
+
+## What the verifier auto-applies
+
+- **`Funnel.conversionWindowDays` auto-applied.** When a check's `breakdown` matches a funnel by sequence, `verifyDungeon` reads `conversionWindowDays` from the funnel config and passes it to the emulator. You do NOT need to thread `conversionWindowMs` by hand for funnels declared in the dungeon.
+- **`Funnel.order` auto-dispatched.** For `sequential` / `interrupt` funnels, the emulator runs the greedy single-pass engine. For other order modes (`first-fixed`, `last-fixed`, `random`, etc.), it dispatches to `evaluateAnyOrderCompletion` (set-membership check). For `random` mode, results are `verificationKind: "informational"` — Mixpanel funnel shape doesn't apply; do not assert PASS/FAIL.
+- **Auto-sort means custom DuckDB queries can trust event order.** Per-user events arrive sorted ascending by time (default; opt out via `autoSortAfterEverything: false`). `LAG`/`LEAD` window functions work without explicit `ORDER BY time` in the partition.
+- **Auto-promote `isStrictEvent` is silent healing — not a regression.** If a stale dungeon's funnel-step events also live in `events[]`, the validator stamps `isStrictEvent: true` and warns. Verification of those dungeons may show CHANGED standalone-event counts vs older runs — that is correct behavior, not a bug to chase.
+- **Touchpoint cap = 10 enforced at generation.** `hasCampaigns: true` users get up to `maxTouchpointsPerUser` (default 10) UTM-stamped events, sampled across lifetime. Attribution checks via `attributedBy` should see realistic first/last-touch shapes, not all-stamps-at-birth.
+
+## Hook awareness for verification
+
+- `injectOnNewDays(events, eventName, targetDays)` — clones events onto previously empty days. Hook authors are expected to use it for COHORT-CONDITIONAL active-day patterns only. Global active-day shape lives in `Dungeon.avgActiveDaysPerUser` (config knob), so a dungeon that uses this atom EVERYWHERE (not scoped to a cohort) is suspect — flag it.
+- Engine-stamped UTMs may already exist on events. Hooks that bias attribution should OVERWRITE existing UTMs, not stamp fresh.
+
+## Common verification gotchas
+
+| Symptom | Root cause | Fix |
+|---------|-----------|-----|
+| Cohort B shows MORE absolute post-d30 events than cohort A even though hook reduces B | Cohort B has structurally higher event volume (e.g., low-balance users check balance constantly) | Compare per-user `post / pre` ratio, not raw counts |
+| Time-window hook (rainy week, etc.) inverts when measured against full-dataset avg | Born-in-dataset ramp inflates late-window baseline | Compare against neighboring days only, not full-dataset average |
+| Weekend-surge hook still <1.0x weekday | Default soup `dayOfWeekWeights` dampens weekends to ~0.55x weekday | Verify against soup baseline (`wknd/wkday > 0.55 × 1.2`), not >1.0 |
+| Funnel-post TTC scaling doesn't move emulator's `timeToConvert` rows | `evaluateFunnel` is greedy single-pass over full event history — picks first match per step regardless of which funnel-instance the hook touched | Document as known limitation (`H9 TTC populations present (limitation)`) |
+| Hook references `profile.X` that's not a defined userProp | Validator doesn't catch undeclared profile reads — `X` resolves to `undefined` | Verify by data SPREAD (max/min, cv) instead of segment correlation |
+| Two `everything` hooks where one injects events the other mutates produce wrong ratios | Hook ordering matters — injection hook ran AFTER cohort-shaping hook | Run cohort-degrading hooks AFTER all injection hooks in same `everything` block |
+| `readFileSync` ENOMEM on shards >500MB | Node string cap at ~512MB | Stream-load with `readline.createInterface` over `data/PREFIX-EVENTS*.json` glob |
+| Hook reads `e.event === 'login'` but cohort empty | `login` is a funnel-step event auto-promoted to `isStrictEvent: true` | Add `isStrictEvent: false` to the event config to keep standalone occurrences |
+
+When writing per-dungeon verify scripts, follow the template in HOOKS.md §9.9. Reference proofs for all 20 vertical dungeons live at `verification/verticals/` — consult them as exemplars before authoring a new one.
+
+**Coverage discipline:** count documented hooks in the dungeon's top-level comment block; count `check()` calls in your verify script; the two MUST match. A "NAILED 7/7" claim against an 11-hook dungeon is misleading — either add the missing checks or document the limitation explicitly in the verify script and status file.
+
+## Common verification mistakes
+
+If a dungeon's frequency / funnel / TTC pattern shows WEAK or NONE in verification, check these BEFORE concluding the hook is broken:
+
+1. **Did you use `COUNT(*)` instead of distinct days?** Frequency-based patterns require `COUNT(DISTINCT date_trunc('day', time::TIMESTAMP))`.
+2. **Did you hand-roll funnel SQL?** Self-joins find the optimal match; Mixpanel uses greedy. Always use `emulateBreakdown` for funnels.
+3. **Are you including step events at the conversion-window boundary?** Mixpanel uses strict `<`. An event exactly at the boundary is excluded.
+4. **Did the hook scale event count without spreading across days?** `scaleEventCount(events, 'X', 3)` clones at sub-second offsets — same day. Frequency reports show ZERO movement. Use `injectOnNewDays`.
+5. **Are you averaging a sometimes-missing property with `AVG()`?** Always wrap in `TRY_CAST(prop AS DOUBLE)`.
+6. **Did you write a funnel-step event as a standalone in `events[]`?** The validator auto-promotes it to `isStrictEvent: true`. Verify the resulting standalone count matches expectations.
+
+## Verifier exports
+
+Direct access to the engine's counting + funnel primitives:
+
+```js
+import {
+  evaluateFunnel,
+  evaluateFunnelHPC,            // Hold Property Constant
+  resolveFunnelSegment,         // first / last / step segment modes
+  evaluateAnyOrderCompletion,
+  buildIdentityMap, resolveUserId,  // identity resolution
+  countDistinctPeriods,
+  nullAwareAvg,
+  binByDistinctPeriods,
+  partitionByTimeBucket,        // day / week / month
+} from '@ak--47/dungeon-master/verify';
+```
+
+## Funnel option threading
+
+When the dungeon's `Funnel` config sets these fields, `verifyDungeon` auto-applies them to matching `funnelFrequency` / `timeToConvert` checks:
+
+| Funnel field | Verifier behavior |
+|--------------|-------------------|
+| `reentry: true` | Counts every completion via `result.completions` |
+| `exclusionEvents: string[]` | Wraps as `exclusionSteps: [{ event }]` and terminates the funnel attempt |
+| `stepFilters: { N: { prop, op, value } }` | Mutates `breakdownArgs.steps[N]` to attach the `where` clause |
+
+## Identity-model dungeons — pass profiles
+
+When `avgDevicePerUser > 0` or `hasAnonIds: true`, ALWAYS pass `profiles` to `emulateBreakdown`. Without it, pre-auth `device_id` events bucket as separate "users" and your funnel/retention/attribution numbers all deflate.
+
+```js
+const events = Array.from(result.eventData);
+const profiles = Array.from(result.userProfilesData);
+
+emulateBreakdown(events, {
+  type: 'funnelFrequency',
+  steps: ['visit_landing', 'sign_up', 'first_action'],
+  breakdownByFrequencyOf: 'visit_landing',
+  profiles,        // ← REQUIRED for identity-model dungeons
+});
+```
+
+Auto-builds the device→user map via `buildIdentityMap(profiles)` (reads `device_ids` first, falls back to `anonymousIds`). For repeated calls, build once and pass `identityMap`.
+
+## Time-series verification (timeBucket)
+
+For temporal trends (engineered campaigns, weekly cycles, growth shapes), add `timeBucket` to any breakdown:
+
+```js
+emulateBreakdown(events, {
+  type: 'frequencyByFrequency',
+  metricEvent: 'Purchase',
+  breakdownByFrequencyOf: 'Browse',
+  timeBucket: 'week',
+});
+// → [{ period: '2024-W01', metric_freq, breakdown_freq, user_count }, ...]
+```
+
+Use `period` to assert weekly / monthly trend shapes (e.g., "engagement rises month over month").

package/.claude/skills/verify-dungeon/references/report-format.md

@@ -0,0 +1,216 @@
+# Report Format
+
+Templates and conventions for writing `./research/hook-results.md` and per-dungeon verification SQL.
+
+## Verdict criteria (5-tier)
+
+- **NAILED** — Within 10% of expected value/ratio. Direction correct, magnitude precise. The story reads exactly as documented.
+- **STRONG** — Within 25% of expected. Direction correct, clearly visible. An analyst would find this pattern immediately.
+- **WEAK** — Within 50% of expected. Directionally correct but magnitude is off, OR sample size is too small to be conclusive.
+- **NONE** — No statistically meaningful difference between cohorts. The hook has no observable effect.
+- **INVERSE** — Effect goes the opposite direction from intended. The story is backwards.
+
+NAILED and STRONG are passing verdicts. WEAK, NONE, and INVERSE are failing verdicts that require investigation.
+
+## Ordering: failures first
+
+Within each dungeon section, order detailed results by verdict severity:
+1. **INVERSE** hooks first
+2. **NONE** hooks second
+3. **WEAK** hooks third
+4. **STRONG** hooks fourth
+5. **NAILED** hooks last
+
+The summary table should also be sorted this way (INVERSE → NONE → WEAK → STRONG → NAILED). This ensures actionable issues are immediately visible at the top.
+
+## Single-dungeon report structure
+
+```markdown
+# Dungeon Verification Report
+
+**Dungeon:** `<filename>`
+**Run Date:** <date>
+**Users:** <count> | **Events:** <count> | **Duration:** <time>
+
+## Schema Validation
+
+| Event Type | Added Columns | Coverage | Verdict |
+|-----------|---------------|----------|---------|
+| purchase | (none) | — | SCHEMA-PASS |
+| page view | (none) | — | SCHEMA-PASS |
+
+<if any SCHEMA-FAIL, list remediation details here>
+
+## Hook Summary
+
+| # | Hook Name | Type | Expected Effect | Observed | Verdict |
+|---|-----------|------|-----------------|----------|---------|
+| 3 | ... | funnel-pre | ... | ... | INVERSE |
+| 2 | ... | everything | ... | ... | WEAK |
+| 1 | ... | event | ... | ... | NAILED |
+
+## Detailed Results
+
+<hooks ordered INVERSE → NONE → WEAK → STRONG → NAILED>
+
+### Hook #3: <Name> (INVERSE)
+...
+
+### Hook #2: <Name> (WEAK)
+...
+
+### Hook #1: <Name> (NAILED)
+...
+
+## Recommendations
+<For any WEAK or FAIL hooks>
+```
+
+## Multi-dungeon report structure
+
+When verifying multiple dungeons, use this consolidated structure. Each dungeon gets its own section with its own summary table and detailed results, all in one file:
+
+```markdown
+# Hook Verification Report
+
+**Run Date:** <date>
+**Dungeons verified:** <count>
+
+## Overall Summary
+
+| Dungeon | Hooks | NAILED | STRONG | WEAK | NONE | INVERSE |
+|---------|-------|--------|--------|------|------|---------|
+| `harness-fintech.js` | 8 | 4 | 2 | 1 | 1 | 0 |
+| `harness-gaming.js` | 10 | 7 | 2 | 1 | 0 | 0 |
+
+---
+
+## harness-fintech.js
+
+**Users:** <count> | **Events:** <count> | **Duration:** <time>
+
+### Summary
+
+| # | Hook Name | Type | Expected Effect | Observed | Verdict |
+|---|-----------|------|-----------------|----------|---------|
+| 4 | Low Balance Churn | everything | ... | ... | NONE |
+| 2 | Payday Patterns | event | ... | ... | WEAK |
+| 1 | Personal vs Business | user | ... | ... | NAILED |
+| ... | ... | ... | ... | ... | ... |
+
+### Detailed Results
+
+<hooks ordered INVERSE → NONE → WEAK → STRONG → NAILED>
+
+### Recommendations
+
+<for this dungeon's WEAK/FAIL hooks>
+
+---
+
+## harness-gaming.js
+
+<same structure, repeated per dungeon>
+
+---
+```
+
+**Key rules for multi-dungeon reports:**
+- The overall summary table at the top shows pass/weak/fail counts per dungeon, sorted with most failures first
+- Each dungeon section is self-contained with its own summary, details, and recommendations
+- Dungeon sections are ordered by failure count descending (most problems first)
+- Use the dungeon filename (without path) as the section header for clarity
+
+## Per-hook detail block
+
+Each hook's detailed section follows this template (same for single and multi-dungeon):
+
+```markdown
+### Hook #N: <Name> (<VERDICT>)
+
+**Intent:** <what the hook is supposed to do>
+**Type:** `<hook type>`
+**Mechanism:** <brief description of how the code works>
+
+**Query:**
+```sql
+<the actual SQL executed>
+```
+
+**Results:**
+<paste the DuckDB output table>
+
+**Analysis:** <interpret the numbers — does the ratio/difference match expectations?>
+
+**Verdict:** NAILED / STRONG / WEAK / NONE / INVERSE
+```
+
+## Query log format
+
+If `./research/` exists locally, write a plain-text log of every DuckDB query execution to `./research/hook-query-log.txt`. If `./research/` does not exist, skip this step entirely — do not create the directory.
+
+Check with: `ls -d ./research/ 2>/dev/null`
+
+Use a consistent delimited format — one block per query, separated by a ruler line. DuckDB table output is preserved verbatim:
+
+```
+================================================================================
+DUNGEON: gaming.js
+HOOK: #1 — Power users have 3x purchase amount
+TYPE: everything
+VERDICT: STRONG
+EXPECTED: ~3x ratio between power and regular users
+OBSERVED: 3.05x ratio
+
+SQL:
+SELECT segment, AVG(amount) as avg_amt, COUNT(*) as n
+FROM read_json_auto('./data/verify-dungeon-EVENTS.json')
+WHERE event = 'purchase'
+GROUP BY segment;
+
+OUTPUT:
+┌────────────┬─────────┬───────┐
+│  segment   │ avg_amt │   n   │
+│  varchar   │ double  │ int64 │
+├────────────┼─────────┼───────┤
+│ power_user │   45.20 │  3841 │
+│ regular    │   14.80 │ 12037 │
+└────────────┴─────────┴───────┘
+
+ANALYSIS: Power users avg $45.20 vs regular $14.80 = 3.05x ratio
+================================================================================
+```
+
+In batch mode (multiple dungeons), all queries across all dungeons go into the same file sequentially. The format is grep-friendly:
+
+```bash
+grep "^VERDICT:" research/hook-query-log.txt           # all verdicts
+grep -B4 "^VERDICT: FAIL" research/hook-query-log.txt  # failing hooks with context
+grep "^DUNGEON:" research/hook-query-log.txt           # list of dungeons queried
+```
+
+## Verification SQL file (mandatory for user dungeons)
+
+When verifying a dungeon in `dungeons/user/`, write a standalone DuckDB SQL file alongside the dungeon at `dungeons/user/<name>-verifications.sql`. This file is the reproducible verification artifact — anyone can re-run it against fresh data.
+
+Follow the format in `verification/verticals/`:
+
+```sql
+-- ============================================================================
+-- <name>.js — Hook Verification SQL (N hooks)
+-- ============================================================================
+-- USAGE:
+--   1. node scripts/verify-runner.mjs dungeons/user/<name>.js verify-<name>
+--   2. duckdb < dungeons/user/<name>-verifications.sql
+--   3. rm -f verify-<name>-*
+-- ============================================================================
+
+-- HOOK N: NAME (TYPE)
+-- PATTERN: <from dungeon JSDoc>
+-- R1 RESULT: <observed> => <verdict>
+<SQL>;
+```
+
+Each query block includes the pattern description, observed result, and verdict as SQL comments. This makes the file self-documenting and grep-friendly.
+
+**This step is mandatory for user dungeons.** Vertical dungeons already have their SQL in `verification/verticals/`. User dungeons keep theirs co-located with the dungeon file.