@ak--47/dungeon-master 1.5.4 → 1.6.0

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

@@ -1,7 +1,7 @@
 ---
 name: analyze-soup
 description: Use when investigating TimeSoup parameters, diagnosing event-distribution shape, or comparing soup configs — runs a dungeon locally and analyzes time distribution at week/day/hour/minute granularities, producing a soup-analysis.md diagnostic report.
-argument-hint: [dungeon path, e.g. dungeons/soup-test.js]
+argument-hint: [dungeon path, e.g. dungeons/technical/simplest.js]
 model: claude-opus-4-6
 effort: max
 ---
@@ -10,7 +10,7 @@ effort: max
 
 Run a dungeon and analyze the time distribution of generated events to evaluate TimeSoup parameters.
 
-**Dungeon file:** `$ARGUMENTS` (default: `dungeons/soup-test.js`)
+**Dungeon file:** `$ARGUMENTS` (default: `dungeons/technical/simplest.js`)
 
 ## Step 1: Run the Dungeon
 
@@ -32,10 +32,19 @@ Wait for generation to complete. Note the event count and EPS.
 
 Run these DuckDB queries against the generated JSONL file. Use `duckdb` CLI.
 
+**All bucketing is UTC — do not convert timezones.** TimeSoup applies its
+day-of-week / hour-of-day weights in UTC, the engine's calendar-day logic
+(`avgActiveDaysPerUser`, lifecycle periods, session midnight splits) is UTC,
+and `/create-project` pins Mixpanel projects to UTC. Casting `time::timestamp`
+on the ISO strings keeps the UTC wall time. Converting to a local zone (e.g.
+`America/Los_Angeles`, −8h) shifts late-evening UTC events onto the previous
+calendar day — the DOW histogram you'd analyze would not be the one the soup
+generated or the one Mixpanel reports.
+
 ### 2a. Week over Week
 ```bash
 duckdb -c "
-SELECT date_trunc('week', (time::timestamp AT TIME ZONE 'UTC' AT TIME ZONE 'America/Los_Angeles')) as week,
+SELECT date_trunc('week', time::timestamp) as week,
        count(*) as events
 FROM read_json_auto('./data/soup-analysis-EVENTS.json')
 GROUP BY 1 ORDER BY 1;
@@ -45,7 +54,7 @@ GROUP BY 1 ORDER BY 1;
 ### 2b. Day over Day
 ```bash
 duckdb -c "
-SELECT date_trunc('day', (time::timestamp AT TIME ZONE 'UTC' AT TIME ZONE 'America/Los_Angeles')) as day,
+SELECT date_trunc('day', time::timestamp) as day,
        count(*) as events
 FROM read_json_auto('./data/soup-analysis-EVENTS.json')
 GROUP BY 1 ORDER BY 1;
@@ -55,10 +64,10 @@ GROUP BY 1 ORDER BY 1;
 ### 2c. Hour over Hour (last 7 days only)
 ```bash
 duckdb -c "
-SELECT date_trunc('hour', (time::timestamp AT TIME ZONE 'UTC' AT TIME ZONE 'America/Los_Angeles')) as hour,
+SELECT date_trunc('hour', time::timestamp) as hour,
        count(*) as events
 FROM read_json_auto('./data/soup-analysis-EVENTS.json')
-WHERE (time::timestamp AT TIME ZONE 'UTC' AT TIME ZONE 'America/Los_Angeles') > (SELECT max((time::timestamp AT TIME ZONE 'UTC' AT TIME ZONE 'America/Los_Angeles')) - interval '7 days' FROM read_json_auto('./data/soup-analysis-EVENTS.json'))
+WHERE time::timestamp > (SELECT max(time::timestamp) - interval '7 days' FROM read_json_auto('./data/soup-analysis-EVENTS.json'))
 GROUP BY 1 ORDER BY 1;
 "
 ```
@@ -66,10 +75,10 @@ GROUP BY 1 ORDER BY 1;
 ### 2d. Minute over Minute (last 24 hours only)
 ```bash
 duckdb -c "
-SELECT date_trunc('minute', (time::timestamp AT TIME ZONE 'UTC' AT TIME ZONE 'America/Los_Angeles')) as minute,
+SELECT date_trunc('minute', time::timestamp) as minute,
        count(*) as events
 FROM read_json_auto('./data/soup-analysis-EVENTS.json')
-WHERE (time::timestamp AT TIME ZONE 'UTC' AT TIME ZONE 'America/Los_Angeles') > (SELECT max((time::timestamp AT TIME ZONE 'UTC' AT TIME ZONE 'America/Los_Angeles')) - interval '1 day' FROM read_json_auto('./data/soup-analysis-EVENTS.json'))
+WHERE time::timestamp > (SELECT max(time::timestamp) - interval '1 day' FROM read_json_auto('./data/soup-analysis-EVENTS.json'))
 GROUP BY 1 ORDER BY 1;
 "
 ```
@@ -78,14 +87,14 @@ GROUP BY 1 ORDER BY 1;
 ```bash
 duckdb -c "
 WITH daily AS (
-  SELECT date_trunc('day', (time::timestamp AT TIME ZONE 'UTC' AT TIME ZONE 'America/Los_Angeles')) as day, count(*) as events
+  SELECT date_trunc('day', time::timestamp) as day, count(*) as events
   FROM read_json_auto('./data/soup-analysis-EVENTS.json')
   GROUP BY 1
 ),
 hourly AS (
-  SELECT date_trunc('hour', (time::timestamp AT TIME ZONE 'UTC' AT TIME ZONE 'America/Los_Angeles')) as hour, count(*) as events
+  SELECT date_trunc('hour', time::timestamp) as hour, count(*) as events
   FROM read_json_auto('./data/soup-analysis-EVENTS.json')
-  WHERE (time::timestamp AT TIME ZONE 'UTC' AT TIME ZONE 'America/Los_Angeles') > (SELECT max((time::timestamp AT TIME ZONE 'UTC' AT TIME ZONE 'America/Los_Angeles')) - interval '7 days' FROM read_json_auto('./data/soup-analysis-EVENTS.json'))
+  WHERE time::timestamp > (SELECT max(time::timestamp) - interval '7 days' FROM read_json_auto('./data/soup-analysis-EVENTS.json'))
   GROUP BY 1
 )
 SELECT 'daily' as granularity,
@@ -112,7 +121,7 @@ FROM hourly;
 ```bash
 duckdb -c "
 WITH daily AS (
-  SELECT date_trunc('day', (time::timestamp AT TIME ZONE 'UTC' AT TIME ZONE 'America/Los_Angeles')) as day, count(*) as events
+  SELECT date_trunc('day', time::timestamp) as day, count(*) as events
   FROM read_json_auto('./data/soup-analysis-EVENTS.json')
   GROUP BY 1
 )

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

@@ -51,7 +51,14 @@ Out of scope (hand off to `write-hooks`):
 For an encyclopedia of hook patterns, recipes, and real-world examples:
 see `HOOKS.md` at the project root.
 
-These config keys are silently ignored — DO NOT use them: `subscription`, `attribution`, `geo`, `features`, `anomalies`. Recreate with hooks via `write-hooks`.
+> ⚠️ **Silently-ignored config keys — do not use.** The validator STRIPS these
+> five keys before generation: `subscription`, `attribution`, `geo`,
+> `features`, `anomalies`. They produce **zero data** — only a verbose-mode
+> warning. A dungeon that "configures" churn via `subscription:` or campaign
+> lift via `attribution:` is configuring nothing, and the omission is
+> invisible at smoke-test scale. Recreate those behaviors with hooks via
+> `/write-hooks` (churn cohorts, UTM biasing, geo weighting, feature-flag
+> cohorts, anomaly windows all have recipes in `HOOKS.md`).
 
 ## Reference reading
 
@@ -62,8 +69,10 @@ Before writing any code, scan:
   with full JSDoc. **Treat this as the source of truth.**
 - `lib/utils/utils.js` — `pickAWinner`, `weighNumRange`, `initChance`, `exhaust`,
   `takeSome` for property value distributions
-- `dungeons/vertical/sass.js` — B2B reference dungeon with full identity model
-- `dungeons/user/my-buddy/my-buddy.js` — consumer-app reference (gitignored)
+- `dungeons/vertical/sass/sass.js` — B2B reference dungeon with full identity model
+- `dungeons/vertical/ecommerce/ecommerce.js` — canonical consumer exemplar:
+  schema, funnels, stories export, and full hook layout (what your schema
+  becomes after `/write-hooks`)
 - `dungeons/technical/identity-model-verify.js` — minimal identity-model fixture
 
 ## File structure
@@ -88,6 +97,7 @@ import * as v from "ak-tools";
  * APP:        <2-4 line description: what users do, core flow, monetization>
  * SCALE:      <numUsers> users, ~<numEvents> events, <numDays> days (<start> → <end>)
  * CORE LOOP:  <event1> → <event2> → <event3> → ...
+ * VALUE MOMENT: <the one event representing realized value — lifecycle hooks anchor here>
  *
  * EVENTS (N):
  *   <event name (weight)> > ...   (sorted by weight desc)
@@ -160,7 +170,7 @@ KNOBS (extracted tunable constants — timing, thresholds, multipliers),
 HOOK STATE (module-level Maps/Sets used across users), and HELPER FUNCTIONS
 (per-type handlers like `handleEventHooks`, `handleEverythingHooks`).
 `config.hook` becomes a thin dispatcher delegating to the helpers. See
-`dungeons/vertical/ecommerce.js` as the canonical exemplar.
+`dungeons/vertical/ecommerce/ecommerce.js` as the canonical exemplar.
 
 ## Required components
 
@@ -196,6 +206,30 @@ When using experiments, include `$experiment_started` in the events array with
 }}
 ```
 
+**Design the vocabulary for the analyses hooks will target (v1.6):**
+
+- **Session-friendly next-events.** Flows (Sankey) reads collapse when an
+  anchor event can plausibly be followed by 15 different event types — every
+  branch gets a sliver and no engineered path clears the top level. For each
+  high-traffic anchor (post-login, post-search, post-add-to-cart), keep the
+  realistic next-event vocabulary to **≤5–6 event types**; if the app
+  genuinely has more surfaces, give the rare ones weight 1 so the top paths
+  stay legible. A path-share hook needs ~20–25% share to survive a Sankey's
+  top-3 — impossible against a 15-way fan-out.
+- **Designate a value moment.** Pick ONE event that represents realized value
+  (first workout logged, order delivered, report generated) and record it in
+  the OVERVIEW block as `VALUE MOMENT: <event>`. Lifecycle stories
+  (dormancy → resurrection waves) anchor on the value moment — hooks gate or
+  inject THAT event, not generic page views. A schema with no obvious value
+  moment forces `write-hooks` to invent one badly.
+- **Hidden-event hygiene.** Heartbeat/telemetry events (`ping`,
+  `app foregrounded`, `position updated`) at weight ≥5 drown every Sankey
+  level — every top path becomes anchor → heartbeat → heartbeat. Mixpanel
+  Flows (and the emulator's `topPaths` via `hiddenEvents`) can hide them at
+  query time, but the default view is what demos show. If realism demands
+  heartbeats, keep them at weight 1–2 and list them in the OVERVIEW so
+  `write-hooks` knows to pass `hiddenEvents` in flows stories.
+
 ### 2. Funnels (3–6)
 
 - First funnel: includes `isFirstEvent` AND has `isAuthEvent: true` on the
@@ -237,6 +271,32 @@ event.
 
 **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.
 
+**Structural trend engineering — duplicate funnels instead of reaching for
+hooks.** Not every trend needs a hook: initial conditions can raise or lower
+a metric by themselves. The funnel array is a set of knobs — duplicate a
+funnel and swap steps, props, `conversionRate`, `timeToConvert`, or `weight`
+to architect a comparison directly into the schema:
+
+- **Exclusion-step story**: Mixpanel funnels can exclude users who did
+  `foo` between A and B. There's no `excludeSteps` config — model it with
+  two funnels, `[A, B, C]` and `[A, B, foo, C]`, giving the second a lower
+  `conversionRate`. The report shows the conversion dip for the
+  detour-takers with zero hook code.
+- **Segment-split story**: two copies of the same sequence with different
+  `props` (`{ checkout_version: "v1" }` vs `"v2"`) and different
+  `conversionRate` — an A/B story without the experiment machinery (use
+  `experiment` when you want `$experiment_started` + variant reports).
+- **Speed story**: same sequence, different `timeToConvert`, split by a
+  funnel-level prop — time-to-convert deltas appear structurally.
+- **Mix-shift story**: `weight` controls how often each variant funnel is
+  chosen; a heavy-weighted low-converting path drags the blended rate.
+
+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.
+
 ### 3. SuperProps (2–3)
 
 Properties present on EVERY event. Common picks: `Plan`, `Region`, `Platform`,
@@ -554,7 +614,7 @@ When designing event properties, always consider which Mixpanel type best repres
 app/customer, then **create `dungeons/user/<name>/` if it doesn't already exist**
 (`mkdir -p dungeons/user/<name>`) and write the dungeon to
 `dungeons/user/<name>/<name>.js` (e.g. `dungeons/user/acme/acme.js`). Folder and
-file share the name, matching `kodiak/kodiak.js`, `my-buddy/my-buddy.js`.
+file share the name, matching the vertical layout (`ecommerce/ecommerce.js`).
 
 This keeps `dungeons/user/` organized — EVERYTHING about this dungeon lives in
 the same folder: `hook-results.md` + `hook-query-log.txt` +

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

@@ -25,7 +25,7 @@ in order:
 1. **createProject** — name derived from the dungeon's `OVERVIEW` (`NAME:` line), region `US`, timezone `UTC` (set as a follow-up by the endpoint).
 2. **mintServiceAccount** — `admin`, expires `+30 days`, scoped to the new project. This is what the dungeon uses to **send** data.
 3. **addGroupKey** — one per `groupKeys` entry in the dungeon (`property_name` + a titleized `display_name`). Skipped if the dungeon has no group keys.
-4. **setBusinessContext** — markdown built from the dungeon's `OVERVIEW` + `HOOK STORIES` comment blocks (via the package's `extractComments`) plus an events/funnels/props/group-keys summary, capped at 50k chars.
+4. **setBusinessContext** — markdown built from the dungeon's `OVERVIEW` comment block plus the `stories` named export (per story: `narrative` + `mixpanelReport` + intentional deviations); dungeons without stories fall back to the `HOOK STORIES` comment scrape (via the package's `extractComments`). Plus an events/funnels/props/group-keys summary, capped at 50k chars. The dry-run plan prints which source was used.
 5. **write-back** — replaces the dungeon's `credentials: { … }` block with `{ token, projectId, serviceAccount, serviceSecret, region }`.
 
 **Always creates a fresh project.** Re-running mints a new project and overwrites

package/.claude/skills/create-project/provision.mjs

@@ -10,7 +10,9 @@
  *   1. createProject       (sets timezone UTC as a follow-up)
  *   2. mintServiceAccount  (admin, +30d) — scoped to the new project
  *   3. addGroupKey         (only if the dungeon declares groupKeys)
- *   4. setBusinessContext  (OVERVIEW + HOOK STORIES + schema summary)
+ *   4. setBusinessContext  (OVERVIEW + the dungeon's `stories` export
+ *      (narrative + mixpanelReport per story) — falls back to the HOOK
+ *      STORIES comment scrape when the dungeon has no stories — + schema summary)
  *   5. write `credentials: { token, projectId, serviceAccount, serviceSecret, region }`
  *      back into the dungeon (gitignored user dungeons — plaintext is fine)
  *
@@ -27,7 +29,7 @@
 
 import { readFileSync, writeFileSync, existsSync } from 'fs';
 import path, { dirname, resolve } from 'path';
-import { fileURLToPath } from 'url';
+import { fileURLToPath, pathToFileURL } from 'url';
 import dotenv from 'dotenv';
 import { loadFromFile, extractComments } from '../../../index.js';
 
@@ -57,12 +59,26 @@ if (!existsSync(dungeonPath)) fail(`dungeon file not found: ${dungeonPath}`);
 const config = await loadFromFile(dungeonPath);
 const comments = extractComments(dungeonPath);
 
+// stories is a NAMED export of JS dungeons (v1.6 story-spec) — the verified
+// behavior contract. Preferred over the comment scrape for business context.
+let stories = null;
+if (/\.(js|mjs)$/i.test(dungeonPath)) {
+	try {
+		const mod = await import(pathToFileURL(dungeonPath).href);
+		if (Array.isArray(mod.stories) && mod.stories.length) stories = mod.stories;
+	} catch {
+		// loadFromFile above already imported the module; an error here would
+		// have surfaced there. Fall back to the comment scrape regardless.
+	}
+}
+
 const name = deriveName(comments, dungeonPath);
 const groupKeys = Array.isArray(config.groupKeys)
 	? config.groupKeys.filter(Boolean).map(([prop]) => ({ property_name: prop, display_name: titleize(prop) }))
 	: [];
 const saName = `${slug(name)}-dungeon-sa`.slice(0, 64);
-const content = buildContext(name, config, comments, groupKeys);
+const ctxSource = stories ? `stories export (${stories.length} stories)` : 'comment scrape';
+const content = buildContext(name, config, comments, groupKeys, stories);
 
 if (dryRun) {
 	printPlan();
@@ -182,13 +198,41 @@ function slug(s) {
 
 function isoInDays(days) {
 	const ms = Date.now() + days * 24 * 60 * 60 * 1000;
-	return new Date(ms).toISOString();
+	// Mixpanel's createServiceAccount requires %Y-%m-%dT%H:%M:%SZ — seconds
+	// precision, NO milliseconds. toISOString() emits ".sssZ", which the API
+	// rejects ("Expiration date … does not match %Y-%m-%dT%H:%M:%SZ").
+	return new Date(ms).toISOString().replace(/\.\d{3}Z$/, 'Z');
 }
 
-function buildContext(name, config, comments, groupKeys) {
+function buildContext(name, config, comments, groupKeys, stories) {
 	const parts = [`# ${name}`, ''];
 	if (comments.overview) parts.push(comments.overview, '');
-	if (comments.hookStories) parts.push('## Engineered Behaviors', '', comments.hookStories, '');
+
+	// Preferred source: the stories export — each story's narrative is the
+	// human-readable behavior and mixpanelReport (free-form object) points at
+	// the report where it shows. Comment scrape is the fallback for dungeons
+	// without stories (schema-only or pre-1.6).
+	if (stories?.length) {
+		parts.push('## Engineered Behaviors', '');
+		parts.push(`${stories.length} machine-verified story patterns (from the dungeon's \`stories\` export):`, '');
+		for (const s of stories) {
+			const arch = s.archetype ? ` — ${s.archetype}` : '';
+			parts.push(`### ${s.id}${arch}`, '');
+			if (s.narrative) parts.push(String(s.narrative).trim(), '');
+			if (s.mixpanelReport && typeof s.mixpanelReport === 'object') {
+				parts.push('How to see it in Mixpanel:');
+				for (const [k, v] of Object.entries(s.mixpanelReport)) {
+					parts.push(`- **${k}**: ${typeof v === 'string' ? v : JSON.stringify(v)}`);
+				}
+				parts.push('');
+			}
+			if (Array.isArray(s.intentionalDeviations) && s.intentionalDeviations.length) {
+				parts.push('Notes:', ...s.intentionalDeviations.map((d) => `- ${d}`), '');
+			}
+		}
+	} else if (comments.hookStories) {
+		parts.push('## Engineered Behaviors', '', comments.hookStories, '');
+	}
 
 	parts.push('## Schema', '');
 	const events = config.events || [];
@@ -252,7 +296,7 @@ function printPlan() {
 	console.log(`region:         ${REGION}    timezone: UTC`);
 	console.log(`service acct:   ${saName}  (role admin, expires +${SA_TTL_DAYS}d)`);
 	console.log(`group keys:     ${groupKeys.length ? groupKeys.map((g) => `${g.property_name} → "${g.display_name}"`).join(', ') : '(none)'}`);
-	console.log(`business ctx:   ${content.length} chars`);
+	console.log(`business ctx:   ${content.length} chars (source: ${ctxSource})`);
 	console.log('');
 	console.log('would POST: createProject → mintServiceAccount' + (groupKeys.length ? ' → addGroupKey' : '') + ' → setBusinessContext');
 	console.log('then write credentials back into the dungeon.');
@@ -268,11 +312,14 @@ function printSummary() {
 	console.log(`region:         ${REGION}    timezone: UTC`);
 	console.log(`service acct:   ${sa ? `${sa.username} (role ${sa.role}, expires ${sa.expires})` : '(FAILED — see warnings)'}`);
 	if (groupKeys.length) {
-		const added = groupKeyResult?.added?.map((g) => g.property_name).join(', ') || '(none)';
-		const skipped = groupKeyResult?.skipped?.join(', ') || '(none)';
+		// Defensive: the API's `added`/`skipped` entries may be objects, strings, or
+		// null. Never let summary formatting throw — it would swallow real warnings.
+		const fmt = (g) => (g == null ? null : typeof g === 'string' ? g : (g.property_name || g.name || null));
+		const added = (groupKeyResult?.added || []).map(fmt).filter(Boolean).join(', ') || '(none)';
+		const skipped = (groupKeyResult?.skipped || []).map(fmt).filter(Boolean).join(', ') || '(none)';
 		console.log(`group keys:     added [${added}]  skipped [${skipped}]`);
 	}
-	console.log(`business ctx:   ${content.length} chars uploaded`);
+	console.log(`business ctx:   ${content.length} chars uploaded (source: ${ctxSource})`);
 	console.log(`credentials:    ${wroteBack ? 'written back into dungeon ✓' : 'NOT written (see warnings)'}`);
 	if (warnings.length) {
 		console.log('');

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

@@ -1,16 +1,16 @@
 ---
 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]
+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]
 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`.
+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`.
 
-**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.
+**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.
 
 ## Reference files
 
@@ -28,9 +28,10 @@ Also: `HOOKS.md` (recipe encyclopedia) and `types.d.ts` (source of truth for hoo
 
 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)
+1. **The `stories` named export** — the machine-checkable contract (see `lib/templates/story-spec.schema.json` and the `DungeonStory` typedef in `types.d.ts`). If present, the story runner in Step 3 does the heavy lifting. If absent (legacy dungeon), the full per-hook flow in Step 5 applies to every hook.
+2. **The `hook:` function** — read the full body
+3. **The documentation comment block** describing engineered patterns
+4. **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")
@@ -52,7 +53,7 @@ node scripts/verify-runner.mjs <dungeon-path> <run-name>
 
 Example:
 ```bash
-node scripts/verify-runner.mjs dungeons/vertical/gaming.js verify-gaming
+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`.
@@ -65,7 +66,27 @@ Full-fidelity runs can take minutes (50K+ user dungeons). Plan accordingly — k
 
 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)
+### Step 3: Run the story runner (primary mechanical check)
+
+For any dungeon with a `stories` export, the runner — not the LLM — computes the verdicts:
+
+```bash
+node scripts/verify-stories.mjs <dungeon-path> --data-prefix <run-name>
+node scripts/verify-stories.mjs <dungeon-path> --data-prefix <run-name> --json   # machine-readable, for hook-results.md
+```
+
+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.
+
+**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.
+
+Do NOT re-derive verdicts the runner already computed as passing. `hook-results.md` (Step 7) renders the runner's JSON.
+
+### 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.
 
@@ -75,7 +96,9 @@ Catches hooks that introduce undeclared columns (flag stamping). For each unique
 
 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
+### 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.
 
 **Decision: emulator vs DuckDB**
 
@@ -84,14 +107,22 @@ If any event type has SCHEMA-FAIL, flag it prominently in the report header with
 | 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'})` |
+| Funnel TTC by segment (steps-based or funnel-based) | `emulateBreakdown({type: 'timeToConvert'})` |
 | First/last touch attribution | `emulateBreakdown({type: 'attributedBy'})` |
-| Retention curves | `emulateBreakdown({type: 'retention'})` |
+| Retention curves — birth or compounded | `emulateBreakdown({type: 'retention'})` (`compounded: true` for "DAU coming back") |
 | Per-session metrics | `emulateBreakdown({type: 'sessionMetrics'})` |
+| Lifecycle (new / retained / resurrected / dormant) | `emulateBreakdown({type: 'lifecycle'})` |
+| Flows / top paths (Sankey) | `emulateBreakdown({type: 'topPaths'})` |
+| Event totals segmented by property | `emulateBreakdown({type: 'eventBreakdown'})` (`countType: 'general' \| 'sessions'`) |
+| Uniques per segment | `emulateBreakdown({type: 'uniques'})` |
+| COUNT DISTINCT of a property + top values | `emulateBreakdown({type: 'distinctCount'})` |
+| Ratio / composite metrics (conversion %, ARPU, blends) | `evaluateFormula` (`lib/verify/formula.js`) over emulator rows |
 | Schema integrity / column coverage | DuckDB |
 | Identity-model invariants | DuckDB |
 | Experiment invariants | DuckDB |
-| Bespoke time-window patterns | DuckDB |
+| True bespokes (no emulator analysis fits) | DuckDB |
+
+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.
 
@@ -107,18 +138,18 @@ For emulator details, identity-model dungeons (must pass `profiles`), and time-s
 **Everything about a dungeon lives in its folder.** When the dungeon being
 verified is a user dungeon at `dungeons/user/<name>/<name>.js`, write ALL
 generated artifacts into `dungeons/user/<name>/`:
-- `hook-results.md` (Step 6)
-- `hook-query-log.txt` (Step 5)
-- `<name>-verifications.sql` (Step 6b)
+- `hook-results.md` (Step 7)
+- `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 7.
+deleted in Step 8.
 
 For non-user dungeons (technical/vertical) or batch runs across many dungeons,
 fall back to `./research/` for `hook-results.md` / `hook-query-log.txt`.
 
-### Step 5: Stash query log
+### Step 6: Stash query log
 
 Write every DuckDB query execution to `hook-query-log.txt`:
 - **User dungeon:** always write to `dungeons/user/<name>/hook-query-log.txt`.
@@ -126,21 +157,21 @@ Write every DuckDB query execution to `hook-query-log.txt`:
 
 Format and conventions: see [report-format.md "Query log format"](references/report-format.md#query-log-format).
 
-### Step 6: Write `hook-results.md`
+### Step 7: Write `hook-results.md`
 
-Write to `dungeons/user/<name>/hook-results.md` for a user dungeon, else `./research/hook-results.md`. 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`. 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):
 - Single-dungeon report structure
 - Multi-dungeon report structure (when batch mode)
 - Per-hook detail block
-- Verdict criteria (5-tier)
+- Verdict criteria (5-tier, mechanical)
 
 **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)
+### Step 7b: Write verification SQL (mandatory for user dungeons)
 
-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 in `verification/verticals/`. Format: see [report-format.md "Verification SQL file"](references/report-format.md#verification-sql-file-mandatory-for-user-dungeons).
+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 7: Cleanup
+### Step 8: Cleanup
 
 ```bash
 rm -f ./data/verify-* ./verify-*
@@ -171,7 +202,7 @@ Tell the user:
 1. Report path: `dungeons/user/<name>/hook-results.md` (user dungeon) or `./research/hook-results.md`
 2. Verification SQL path (for user dungeons): `dungeons/user/<name>/<name>-verifications.sql`
 3. Query log path (if written): alongside the report (`dungeons/user/<name>/hook-query-log.txt`, else `./research/hook-query-log.txt`)
-4. Pass/weak/fail counts (per dungeon if batch mode)
+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
 
 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

@@ -14,13 +14,10 @@ Mixpanel does NOT count the way naive SQL does. The verifier (and any DuckDB que
 | Sessions | 3-trigger split: timeout `>`, max duration `>`, day-idx change (`session_query.cpp:906-911`) | Trust pre-stamped `session_id`; group by `(user, session_id)` |
 | Retention | Birth-anchored, ms-strict gate (default `birth_can_retain=false` → `<`), bucketed by `floor((ret−birth)/unit)` (`retention_query.cpp:1097-1109,1228-1231`) | Use `emulateBreakdown` with `retention` |
 
-**Known divergences from Mixpanel C++** (1.5.1):
+**Known divergences from Mixpanel C++** (1.6.0):
 - `countDistinctPeriods` default = `algorithm: 'calendar'` (UTC bucket).
   Mixpanel C++ (`addiction_query.cpp:359`) uses ROLLING window. Pass
   `algorithm: 'rolling'` for exact Frequency-Distribution parity.
-- COMPOUNDED retention is NOT implemented — verifier silently ignores
-  `compounded: true`. Use DuckDB or query Mixpanel directly for "DAU
-  coming back" reports.
 - Touchpoint sampling: generator stamps uniform-random across user
   lifetime; verifier reads last-N before conversion (matches C++).
   For users with ≤10 attribution events lifetime, no divergence.
@@ -31,7 +28,7 @@ Full rules: see [HOOKS.md Section 2](../../../../HOOKS.md#2-how-mixpanel-counts-
 
 ## 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.
+The emulator (`emulateBreakdown` from `@ak--47/dungeon-master/verify`) implements Mixpanel's rules natively. **ALWAYS use the emulator for funnel, frequency, aggregate, TTC, attribution, retention, lifecycle, flows, sessions, and event-breakdown 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)
@@ -51,10 +48,33 @@ If you find yourself writing `WITH step1 AS ..., step2 AS ...` for a funnel, STO
 | 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` |
+| Compounded retention ("DAU coming back") | `retention` + `compounded: true` | Sets `returnEvent := cohortEvent` internally; throws on a conflicting `returnEvent` |
 | Per-session metrics | `sessionMetrics` | Count / duration / events distributions per session |
+| Lifecycle states (new / retained / resurrected / dormant) | `lifecycle` | "Resurrection wave in week N" — per-period user-state classification |
+| Flows / top paths | `topPaths` | "What do users do after X" — Sankey top-path shares |
+| Event totals segmented by property | `eventBreakdown` | "Purchases by plan tier" — `countType: 'general' \| 'sessions'`; list props fan out per item |
+| Uniques per segment | `uniques` | "Unique users by plan tier" |
+| Distinct property values | `distinctCount` | "How many distinct SKUs" — see below |
+| Ratio / composite metrics | `evaluateFormula` (`lib/verify/formula.js`) | Conversion %, ARPU, any PEMDAS formula over emulator series |
 
 Cross-cutting on EVERY type: `timeBucket: 'day' | 'week' | 'month'` partitions events into UTC buckets and emits one row per period.
 
+### `distinctCount`
+
+Counts distinct values of a flat event property, Mixpanel COUNT_DISTINCT-style, with a top-values breakdown:
+
+```js
+emulateBreakdown(events, {
+  type: 'distinctCount',
+  property: 'sku',        // required — flat property name (dot-paths not supported)
+  event: 'Purchase',      // optional — restrict to one event type; omit = all events
+  topN: 25,               // optional — top values by count (default 25)
+});
+// → [{ distinct_count: 143, top_values: [{ value: 'SKU-001', count: 812 }, ...] }]
+```
+
+Single-row result. Use it for catalog-breadth stories ("power sellers list 5× more distinct SKUs") where `uniques` / `eventBreakdown` answer a different question (users or totals per bucket, not distinct values of the property itself).
+
 Quick emulator script:
 
 ```js
@@ -98,7 +118,7 @@ For CI-style assertions, use `verifyDungeon` with a checks array; see `tests/e2e
 | `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.
+When writing per-dungeon verify scripts, follow the template in HOOKS.md §9.9. Reference proofs for all 22 vertical dungeons live at `dungeons/vertical/<name>/` — 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.