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

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.
 

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

@@ -4,13 +4,17 @@ Templates and conventions for writing `hook-results.md` and per-dungeon verifica
 
 ## 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.
+Verdicts are **mechanical** — computed by `scripts/verify-stories.mjs` from each story assertion's declared `target` / `floor` / `minCohort` (see the `StoryVerdict` typedef in `types.d.ts`), not eyeballed percentages:
 
-NAILED and STRONG are passing verdicts. WEAK, NONE, and INVERSE are failing verdicts that require investigation.
+- **NAILED** — observed within ±10% of `target`.
+- **STRONG** — passes `floor` (or `target` when no floor is declared).
+- **WEAK** — fails `floor` but effect direction is correct, **or** the selected cohort is smaller than `minCohort`. The population floor is a hard cap: a 12-user cohort can never score NAILED, no matter how clean its ratio.
+- **NONE** — no measurable effect, or the selection matched no rows.
+- **INVERSE** — effect direction is opposite the assertion.
+
+Story verdict = worst assertion verdict. NAILED and STRONG are passing; WEAK, NONE, and INVERSE fail and require investigation.
+
+Hand-assigned verdicts appear only in the legacy no-stories fallback and MUST follow the same definitions: derive a target from the hook's knob constants, compute the band the observed value lands in, and state the derivation in the detail block — never assign a tier by feel.
 
 ## Ordering: failures first
 
@@ -25,6 +29,8 @@ The summary table should also be sorted this way (INVERSE → NONE → WEAK →
 
 ## Single-dungeon report structure
 
+For story-backed dungeons, `hook-results.md` **renders the runner's JSON**: run `verify-stories.mjs --json` and build the Hook Summary table directly from its per-story records (story id, hook number, archetype, observed vs target per assertion, computed verdict). Do not recompute verdicts the runner already settled. Detailed Results blocks exist only for stories below STRONG, `duckdb`-type assertions, and legacy no-stories hooks.
+
 ```markdown
 # Dungeon Verification Report
 
@@ -191,7 +197,7 @@ grep "^DUNGEON:" research/hook-query-log.txt           # list of dungeons querie
 
 When verifying a dungeon in `dungeons/user/`, write a standalone DuckDB SQL file alongside the dungeon in its folder at `dungeons/user/<name>/<name>-verifications.sql`. This file is the reproducible verification artifact — anyone can re-run it against fresh data.
 
-Follow the format in `verification/verticals/`:
+Follow the format in `dungeons/vertical/<name>/`:
 
 ```sql
 -- ============================================================================
@@ -211,4 +217,4 @@ Follow the format in `verification/verticals/`:
 
 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.
+**This step is mandatory for user dungeons.** Vertical dungeons already have their SQL co-located at `dungeons/vertical/<name>/<name>.sql`. User dungeons keep theirs co-located with the dungeon file.

package/.claude/skills/write-hooks/SKILL.md

@@ -20,7 +20,11 @@ already complete (produced by `create-dungeon`). After writing, hand off to
 In scope:
 - The `hook: function(record, type, meta) { ... }` body
 - Documentation comments above the hook explaining each engineered pattern,
-  including a reference Mixpanel report block per pattern
+  including a reference Mixpanel report block per pattern and the mandatory
+  EXPECTED METRICS SUMMARY table
+- The `stories` named export — one machine-checkable story per engineered
+  pattern (see "Stories export" below). A hook without stories is
+  unverifiable; this skill is not done until the stories exist.
 
 Out of scope:
 - Schema changes (events, properties, funnels, superProps, userProps).
@@ -29,6 +33,18 @@ Out of scope:
 - New top-level config knobs.
 - Removing the `hook: function...` body to start over with a new schema.
 
+**Before writing a hook, ask: is this trend structural?** Between-path
+comparisons (path X converts worse / slower than path Y, detour-takers drop
+off, mix shift drags the blended rate) are better architected as initial
+conditions — duplicate funnels with swapped steps/props/`conversionRate`/
+`timeToConvert`/`weight` (see the "Structural trend engineering" section in
+`create-dungeon`). If a story reduces to structure, recommend the funnel
+change back to the schema instead of writing a hook to fight the engine —
+the knob IS the expected value, which makes the story band knob-derivable
+(NAILED-capable) instead of confounded (STRONG-capped). Hooks are for
+within-cohort behavior: segments doing more/less of something over time,
+property values that differ by cohort, injected bursts, lifecycle waves.
+
 ## Reference reading
 
 - `lib/hook-helpers/index.js` — atoms (cohort, mutate, timing, inject,
@@ -36,8 +52,11 @@ Out of scope:
 - `lib/hook-patterns/index.js` — high-level recipes (one per Mixpanel
   analysis type).
 - `lib/verify/emulate-breakdown.js` — what `verify-dungeon` will check.
-- `dungeons/user/my-buddy/my-buddy.js` — reference dungeon using a mix of atoms
-  and hand-rolled logic.
+- `lib/templates/story-spec.schema.json` + `DungeonStory` in `types.d.ts` —
+  the story-spec grammar the `stories` export must follow.
+- `dungeons/vertical/ecommerce/ecommerce.js` — reference dungeon using a mix
+  of atoms and hand-rolled logic, with the mandatory EXPECTED METRICS SUMMARY
+  table and a full `stories` export.
 - `dungeons/technical/pattern-*.js` — five minimal pattern fixtures, one per
   recipe.
 - `HOOKS.md` — encyclopedia of hook recipes organized by story pattern. Contains
@@ -134,6 +153,10 @@ if (type === 'funnel-post' && meta.experiment) {
 | inject | `injectOnNewDays(events, eventName, targetDistinctDays)` | **Cohort-only.** Spreads injections across previously-empty days. Use for cohort-conditional active-day boosts; for global active-day shape, use `Dungeon.avgActiveDaysPerUser` config knob. |
 | identity | `isPreAuthEvent(event, authTime)` | Standalone variant of meta.isPreAuth |
 | identity | `splitByAuth(events, authTime)` | { preAuth, postAuth, stitch } partition |
+| cohort | `hashCohort(id, pct)` | Deterministic pct% cohort (0–100 scale). **Use this first for hidden cohorts** — replaces ad-hoc `charCodeAt % N`. When one dungeon needs several NON-overlapping cohorts, gate on disjoint `hashFloat(uid)` bands instead (e.g. `[0, 0.45)`, `[0.45, 0.70)`) |
+| shape | `applyLifecycleWave(events, uid, opts)` | Dormancy window + resurrection burst for Lifecycle reports. When-to-use: the story is "users go quiet, then come back". Gap discipline: ONE stray value moment inside the window destroys the Resurrected read — size `dormantDays` to cover ≥2 whole lifecycle periods, keep the window inside the user's lifespan |
+| shape | `applyPathBias(events, uid, opts)` | Inject a Flows path after the user's FIRST anchor occurrence. When-to-use: the story is "X% of users take this route". `share` is a 0–1 FRACTION (not `hashCohort`'s pct scale); needs ~≥0.20–0.25 to survive Sankey top-3-per-level pruning; per-step gaps clamped ≥1s so ordering survives |
+| shape | `applySessionShape(events, uid, opts)` | Retime the whole stream into `sessionsPerWeek` clusters of `sessionMinutes`. When-to-use: session-duration/cadence stories (sessionMetrics reads). Retiming ONLY — no adds/drops; intra-session gaps stay <28min, inter-session >30min, no cluster crosses UTC midnight. Combine with `hashCohort` for per-role shapes; call BEFORE `applyPathBias` so injected paths keep their own tight gaps |
 
 ### Hook anti-patterns
 
@@ -214,17 +237,51 @@ on undeclared entries.
 Higher-level recipes. Each maps to ONE Mixpanel analysis the verify-dungeon
 emulator can re-derive.
 
-| Pattern | Mixpanel analysis | Hook type |
-|---------|-------------------|-----------|
-| `applyFrequencyByFrequency` | Insights — count(A) by per-user count(B) | everything |
-| `applyFunnelFrequencyBreakdown` | Funnels — completion by per-user count(X) | funnel-post |
-| `applyAggregateByBin` | Insights — avg(prop X) by per-user count(B) | everything |
-| `applyTTCBySegment` | Funnel TTC — broken down by user-property segment | funnel-post |
-| `applyAttributedBySource` | Conversions by Source (first/last touch) | everything |
+| Pattern | Mixpanel analysis | Hook type | Caveat (HOOKS.md) |
+|---------|-------------------|-----------|-------------------|
+| `applyFrequencyByFrequency` | Insights — count(A) by per-user count(B) | everything | `binBy` defaults to `'distinctDays'` (v1.6) — bins match Mixpanel's per-user distinct-day counting, not raw event totals |
+| `applyFunnelFrequencyBreakdown` | Funnels — completion by per-user count(X) | funnel-post | When funnels share a step prefix, restrict scaling to the target funnel — scaling every instance lets first-occurrence funnel evaluation assemble chains across unscaled instances and the ratio never reaches the report |
+| `applyAggregateByBin` | Insights — avg(prop X) by per-user count(B) | everything | Same `binBy: 'distinctDays'` default as above |
+| `applyTTCBySegmentV2` | Funnel TTC — broken down by user-property segment | everything | v1 (`applyTTCBySegment`, funnel-post) is **deprecated**: Mixpanel TTC reads each step's FIRST occurrence per user, so per-run gap scaling only reaches the report on `isFirstFunnel` runs. V2 finds the greedy first sequence (`findFirstSequence`) and scales that |
+| `applyAttributedBySource` | Conversions by Source (first/last touch) | everything | OVERWRITES the engine-stamped touch the chosen model reads; never stamps UTMs onto unstamped events (would blow the `maxTouchpointsPerUser` cap and land outside the last-10 lookback) |
 
 Use a pattern when the trend matches its analysis 1:1. Drop down to atoms when
 the trend is bespoke or composite.
 
+### New story archetypes (v1.6) — design rules per report family
+
+Four archetypes joined the story-spec enum in v1.6. Each has a
+non-negotiable design rule learned the hard way:
+
+- **`lifecycle-wave`** (`applyLifecycleWave`) — GAP DISCIPLINE. Mixpanel's
+  "dormant" state is an `EqualTo 0` filter over the whole period: one stray
+  value-moment event inside the dormancy window (including events OTHER hooks
+  injected earlier in the same `everything` pass) flips the user out of
+  Resurrected. Run the wave AFTER every injecting hook, size `dormantDays` to
+  ≥2 lifecycle periods, and keep `dormantFromDay + dormantDays` inside the
+  user's lifespan (the future-time guard eats bursts past dataset end).
+- **`path-share`** (`applyPathBias`) — FIRST-FLOW ANCHORING. Flows' unique
+  counting reads only each user's FIRST flow past the anchor, so the injected
+  path must follow the FIRST anchor occurrence (the atom does this; don't
+  hand-roll a later anchor). Sankey prunes to the top ~3 branches per level:
+  an engineered branch below ~20–25% share silently disappears from the
+  visualization even though the data is there. Label-only path reads can
+  INVERT when a busier cohort glues extra visible events between path steps —
+  assert the share on the cohort you engineered, not globally.
+- **`session-shape`** (`applySessionShape`) — 30-MIN STRADDLING + MIDNIGHT
+  RULE. Mixpanel derives sessions with a 30-min idle timeout and splits at
+  UTC midnight. Engineered cadences must keep intra-session gaps clearly
+  UNDER 30min and inter-session gaps clearly OVER it — a gap that straddles
+  the timeout makes session counts jitter across runs. Never let an
+  engineered session cross UTC midnight (the day split cuts it in two). The
+  atom guarantees all three; hand-rolled retiming must too.
+- **`composition-drift`** — the breakdown's SHARE of a segment moves over
+  time while totals stay flat (e.g. plan-mix shifts toward premium). Engineer
+  by flipping an existing property value on a date-gated cohort, never by
+  changing volumes — volume changes read as `temporal-inflection` instead.
+  Assert with a `timeBucket` breakdown comparing first-window vs last-window
+  share.
+
 ## Anti-flag-stamping rule (HARD WALL)
 
 Hooks MUST NOT add new properties to records. The schema (config) defines what
@@ -318,6 +375,71 @@ checks against and what consumers read to understand the dataset.
  *   Expected ratio: bin>=15 / bin<5 ≈ 3x (within ±15%)
 ```
 
+### EXPECTED METRICS SUMMARY table (MANDATORY)
+
+The doc block MUST end with an EXPECTED METRICS SUMMARY table — one row per
+verifiable read, with the DERIVATION of each expected number from the hook's
+knob constants (never a bare number someone has to trust). Follow the style
+in `dungeons/vertical/ecommerce/ecommerce.js`:
+
+```
+ * EXPECTED METRICS SUMMARY
+ * ============================================================================
+ *
+ * Hook | Metric                          | Derivation          | Expected | Measured (full)
+ * -----|---------------------------------|---------------------|----------|----------------
+ * H2   | avg watchTimeSec post/pre       | 1.52/0.48           | 3.17x    | 3.19x
+ * H6   | sweet/over avg cart item amount | SWEET_CART_BOOST    | 1.25x    | 1.233x
+ * H9   | dark/light checkouts per user   | 20/13 diluted       | ~1.48x   | 1.412x
+ * ============================================================================
+```
+
+Fill the Measured column from the verification run (a reduced-scale iteration
+number is fine if labeled). "Diluted" derivations must say WHAT dilutes
+(organic events, cohort mixing) — the Derivation column is the anchor
+`/verify-dungeon` uses when a read misses.
+
+## Stories export (MANDATORY — the machine contract)
+
+Every engineered pattern ships with one story in a `stories` named export —
+the machine-checkable form of the doc block. `scripts/verify-stories.mjs`
+evaluates them; `/verify-dungeon` runs it as step 1. Grammar:
+`lib/templates/story-spec.schema.json` and `DungeonStory` in `types.d.ts`.
+
+```js
+export const stories = [
+  {
+    id: "H1-power-buyers",
+    hook: "H1",
+    archetype: "frequency-sweet-spot",
+    narrative: "Users with 15+ browse days buy 3x as often as light browsers.",
+    mixpanelReport: { type: "Insights", event: "Purchase", breakdown: "per-user count of Browse" },
+    assertions: [{
+      breakdown: { type: "frequency", event: "Purchase", cohortEvent: "Browse", bins: [5, 15] },
+      select: { hi: { where: { bin: ">=15" } }, lo: { where: { bin: "<5" } } },
+      expect: { metric: "hi.avg / lo.avg", op: ">=", target: POWER_BUYER_MULT, floor: POWER_BUYER_MULT * 0.8 },
+      minCohort: 200,
+    }],
+  },
+];
+```
+
+Rules:
+
+- **Thresholds derive from the knob you just wrote.** Export the hook's knob
+  constants (`const POWER_BUYER_MULT = 3`) and compute `target` from them —
+  never paste the number twice. If the read is diluted (organic mixing),
+  derive the dilution too and say so in a comment.
+- `floor` must itself be derived (e.g. `target * 0.8`) — never hand-tuned to
+  a run. A missed assertion means fixing the hook or the derivation, never
+  relaxing the number to match output.
+- Set `minCohort` from the cohort math (share × numUsers × ~0.5 safety) so
+  reduced-scale runs cap at WEAK instead of passing on noise.
+- One story per pattern; story `hook` matches the doc-block numbering (`H3`).
+- The `assert` function escape hatch is discouraged — each use needs a
+  comment saying why the declarative `expect` grammar can't express it.
+- Stories are JS-dungeon-only (`dungeon-to-json` drops them).
+
 ## Hook Ordering Within `everything`
 
 The order of operations inside the everything hook matters when hooks interact:
@@ -466,22 +588,37 @@ cohort.
 2. Translate the user's story description into 3–5 engineered patterns.
    Consult `HOOKS.md` for recipe ideas that match the user's story. Each recipe
    includes the hook type, code snippet, and Mixpanel report format.
-3. For each pattern:
+3. **Calibrate thresholds against the real distribution.** Before choosing
+   any "N+ events" gate or cohort cutoff, generate a small run and query the
+   actual per-user distribution (see "Threshold Calibration" above for the
+   query). Set gates at ~the 80th percentile of what the data shows — a
+   threshold picked from intuition is the most common cause of empty cohorts.
+   ```bash
+   node scripts/verify-runner.mjs <dungeon> calib --small
+   ```
+4. For each pattern:
    - Pick a pattern from `lib/hook-patterns/` if it fits the analysis 1:1.
    - Otherwise compose atoms from `lib/hook-helpers/`.
    - Document the pattern in a comment block (Mixpanel report instructions).
-4. Write the `hook` function, importing atoms/patterns at the top of the file.
-5. Smoke-test:
+5. Write the `hook` function, importing atoms/patterns at the top of the
+   file. Finish the doc block with the EXPECTED METRICS SUMMARY table.
+6. Write the `stories` export — one story per pattern, `target`/`floor`
+   derived from the exported knob constants (see "Stories export" above).
+7. Smoke-test generation, then evaluate the stories:
    ```bash
    node scripts/verify-runner.mjs <dungeon> verify-dungeon --small
+   node scripts/verify-stories.mjs <dungeon> --data-prefix verify-dungeon
    ```
-   Confirm the run completes without errors.
-6. Hand off:
+   Reduced-scale runs legitimately cap at WEAK on `minCohort` guards; what
+   you're checking here is no NONE/INVERSE and no assertion errors.
+8. Hand off:
    ```
    /verify-dungeon <dungeon>
    ```
-   If verify-dungeon returns WEAK, NONE, or INVERSE on any pattern, return to
-   step 4 and refine. Iterate until all patterns score STRONG or NAILED.
+   If verify-dungeon returns WEAK, NONE, or INVERSE on any pattern at full
+   fidelity, return to step 4 and refine — fix the hook or the derivation,
+   never relax a threshold to match output. Iterate until all patterns score
+   STRONG or NAILED.
 
 ## Stopping condition
 
@@ -492,5 +629,6 @@ still off in the dungeon's overview comment and report the gap to the user.
 ## Output
 
 Modify the dungeon file in place. Add the `hook` function. Add the imports.
-Add the documentation block above the config. Do NOT modify any other file.
+Add the documentation block (with EXPECTED METRICS SUMMARY) above the config.
+Add the `stories` export after the config. Do NOT modify any other file.
 Tell the user to run `/verify-dungeon <dungeon>` next.