@vue-skuilder/db 0.2.5 → 0.2.8

package/docs/navigators-architecture.md

@@ -117,8 +117,12 @@ class Pipeline {
       cards = await filter.transform(cards, context);
     }
 
-    return cards.filter(c => c.score > 0)
-                .sort((a, b) => b.score - a.score)
+    cards = cards.filter(c => c.score > 0);
+
+    // Stage 3: diversity re-rank (post-filter, pre-sort)
+    cards = diversityRerank(cards);
+
+    return cards.sort((a, b) => b.score - a.score)
                 .slice(0, limit);
   }
 }
@@ -128,8 +132,43 @@ class Pipeline {
 - **Context building** — Fetches shared data (user ELO, orchestration context) once for all strategies
 - **Data hydration** — Pre-fetches commonly needed data (tags) in batch queries
 - **Filter orchestration** — Applies filters in sequence, accumulating provenance
+- **Diversity re-rank** — Demotes repeated answers/concepts so no one tag monopolises the head of the queue (see below)
 - **Result selection** — Removes zero-scores, sorts, and returns top N
 
+### Diversity Re-rank (Stage 3)
+
+A first-class stage that runs **after** the filter chain on the final scores. The
+three-stage model is: generators *produce* → filters *weigh* → re-rank
+*diversifies*. It exists to break "ruts" where many top-scoring candidates share
+the same answer (e.g. a run of missing-letter cards that all resolve to `i`), so
+the learner can't go on autopilot pressing one key.
+
+**Why a separate stage, not a filter:** filters are documented as
+order-independent multipliers (see [Score Semantics](#score-semantics)). The
+re-rank is *rank-dependent* — a card's penalty depends on what outscored it — so
+it deliberately sits outside the commutative filter chain, running last.
+
+**Tag-agnostic by construction.** Tags are the only structured similarity signal
+the framework has, so the re-rank operates on tags — but privileges none. It
+weights each shared tag by its rarity in the candidate pool (inverse document
+frequency): ubiquitous scaffolding tags (`ui:*`, incidental `gpc:expose:*`)
+contribute ~0, while the distinctive tag a cluster shares dominates. No namespace
+is hardcoded, so any course benefits for free *provided its sameness axis is
+tagged* ("tag-agnostic" = no tag is special, not "needs no tags").
+
+**Algorithm** (greedy maximal-marginal-relevance): walk candidates in score
+order; a candidate's repetition load is `Σ idf[tag]·(#already-emitted cards with
+tag)`; emit `argmax(score / (1 + strength·load))` each step, flooring the penalty
+so a strong-but-repeated card is never driven under downstream "well-indicated"
+thresholds. Penalties are expressed as **scores** (not a positional shuffle) so
+the ordering survives both the Pipeline's final sort and the `SourceMixer`'s
+score-descending re-sort downstream.
+
+Per-source: the stage lives inside each Pipeline run, so in multi-source sessions
+it diversifies each source's contribution before the mixer interleaves sources.
+Two global knobs (`strength`, `floor`) have course-general defaults; promote to
+strategy `serializedData` if you want them learnable under orchestration.
+
 ## Pipeline Assembly
 
 `PipelineAssembler` builds pipelines from strategy documents:
@@ -590,6 +629,7 @@ return { ...card, score: card.score * multiplier };
 | `core/navigators/generators/types.ts` | `CardGenerator`, `GeneratorContext` |
 | `core/navigators/filters/types.ts` | `CardFilter`, `FilterContext` |
 | `core/navigators/Pipeline.ts` | Pipeline orchestration |
+| `core/navigators/diversityRerank.ts` | Diversity re-rank stage (IDF-weighted MMR, pipeline stage 3) |
 | `core/navigators/PipelineAssembler.ts` | Builds Pipeline from strategy docs |
 | `core/navigators/CompositeGenerator.ts` | Merges multiple generators |
 | `core/navigators/generators/elo.ts` | ELO generator |

package/package.json

@@ -4,7 +4,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.2.5",
+  "version": "0.2.8",
   "description": "Database layer for vue-skuilder",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -48,7 +48,7 @@
   },
   "dependencies": {
     "@nilock2/pouchdb-authentication": "^1.0.2",
-    "@vue-skuilder/common": "0.2.5",
+    "@vue-skuilder/common": "0.2.8",
     "cross-fetch": "^4.1.0",
     "moment": "^2.29.4",
     "pouchdb": "^9.0.0",
@@ -62,5 +62,5 @@
     "vite": "^8.0.0",
     "vitest": "^4.1.0"
   },
-  "stableVersion": "0.2.5"
+  "stableVersion": "0.2.8"
 }

package/src/core/navigators/Pipeline.ts

@@ -9,6 +9,7 @@ import type { GeneratorResult } from './generators/types';
 import { logger } from '../../util/logger';
 import { createOrchestrationContext, OrchestrationContext } from '../orchestration';
 import { captureRun, buildRunReport, registerPipelineForDebug, type GeneratorSummary, type FilterImpact } from './PipelineDebugger';
+import { diversityRerank } from './diversityRerank';
 
 // ============================================================================
 // REPLAN HINTS
@@ -180,7 +181,7 @@ function logResultCards(cards: WeightedCard[]): void {
     const c = cards[i];
     const tags = c.tags?.slice(0, 3).join(', ') || '';
     const filters = c.provenance
-      .filter((p) => p.strategy === 'hierarchyDefinition' || p.strategy === 'priorityDefinition' || p.strategy === 'interferenceFilter' || p.strategy === 'letterGating' || p.strategy === 'ephemeralHint')
+      .filter((p) => p.strategy === 'hierarchyDefinition' || p.strategy === 'priorityDefinition' || p.strategy === 'interferenceFilter' || p.strategy === 'letterGating' || p.strategy === 'ephemeralHint' || p.strategy === 'diversityRerank')
       .map((p) => {
         const arrow = p.action === 'boosted' ? '↑' : p.action === 'penalized' ? '↓' : '=';
         return `${p.strategyName}${arrow}${p.score.toFixed(2)}`;
@@ -254,7 +255,22 @@ function logCardProvenance(cards: WeightedCard[], maxCards: number = 3): void {
  * const cards = await pipeline.getWeightedCards(20);
  * ```
  */
-export class Pipeline extends ContentNavigator {
+
+/**
+ * Narrow capability surface for out-of-band, commit-free reads against a live
+ * pipeline (see {@link getActivePipeline}). Kept minimal on purpose — consumers
+ * get the forecast capability, not the whole `Pipeline` class.
+ */
+export interface PipelineForecaster {
+  forecast(opts?: {
+    hints?: ReplanHints;
+    unseenOnly?: boolean;
+    threshold?: number;
+    limit?: number;
+  }): Promise<WeightedCard[]>;
+}
+
+export class Pipeline extends ContentNavigator implements PipelineForecaster {
   private generator: CardGenerator;
   private filters: CardFilter[];
 
@@ -495,6 +511,14 @@ export class Pipeline extends ContentNavigator {
       cards = this.applyHints(cards, hints, allCardsBeforeFiltering);
     }
 
+    // Stage 3: diversity re-rank (post-filter, post-hints, pre-sort). Demotes
+    // cards whose distinctive tags already appeared among higher-ranked
+    // candidates so a single answer/concept can't monopolise the head of the
+    // queue. Tag-agnostic (rarity-weighted overlap — no namespace privileged)
+    // and expressed as score penalties so the ordering survives the final sort
+    // here AND the SourceMixer's score-descending re-sort downstream.
+    cards = diversityRerank(cards);
+
     // Sort by score descending
     cards.sort((a, b) => b.score - a.score);
 
@@ -881,6 +905,83 @@ export class Pipeline extends ContentNavigator {
   // Card-space diagnostic
   // ---------------------------------------------------------------------------
 
+  /**
+   * Commit-free forecast: score the user's full card space through the filter
+   * chain and return the cards that are currently *reachable* (score >=
+   * threshold), optionally nudged by caller-supplied hints and/or restricted
+   * to cards the user hasn't seen yet.
+   *
+   * This is a GENERIC primitive — it returns scored, tag-hydrated cards and
+   * stops there. It has no knowledge of any particular tag convention; callers
+   * decide what the surviving cards mean (e.g. filter to their own "intro"
+   * tag family). Nothing is written and no session is started.
+   *
+   * The optional `hints` are the "out-of-band kick": they run through the same
+   * {@link applyHints} path a live replan uses, so the two semantics carry over —
+   *   - `boostTags`/`boostCards` reweight *within* gating (a gated score-0 card
+   *     stays out), and
+   *   - `requireTags`/`requireCards` inject from the full pre-filter pool,
+   *     *bypassing* gating (use when you want a card regardless of reachability).
+   * Note `unseenOnly` is applied LAST, so it can drop a `require`d card that the
+   * user has already seen — pass `unseenOnly: false` if that matters.
+   *
+   * Cost note: like {@link diagnoseCardSpace}, this scans every card through the
+   * filters, so it's heavier than a normal replan. Intended for one-shot
+   * out-of-band use (e.g. a session-end "what's next" snapshot), not the hot path.
+   *
+   * @param opts.hints       Optional ephemeral hints to apply after the filter chain.
+   * @param opts.unseenOnly  Only return cards the user hasn't encountered (default true).
+   * @param opts.threshold   Min score to count as reachable (default 0.10).
+   * @param opts.limit       Optional cap on results (already sorted desc).
+   */
+  async forecast(opts?: {
+    hints?: ReplanHints;
+    unseenOnly?: boolean;
+    threshold?: number;
+    limit?: number;
+  }): Promise<WeightedCard[]> {
+    const threshold = opts?.threshold ?? 0.10;
+    const unseenOnly = opts?.unseenOnly ?? true;
+
+    const courseId = this.course!.getCourseID();
+    const allCardIds = await this.course!.getAllCardIds();
+
+    let cards: WeightedCard[] = allCardIds.map((cardId) => ({
+      cardId,
+      courseId,
+      score: 1.0,
+      provenance: [],
+    }));
+
+    cards = await this.hydrateTags(cards);
+    // Snapshot the full pool before filtering, for require-injection in applyHints.
+    const fullPool = cards.slice();
+
+    const context = await this.buildContext();
+    for (const filter of this.filters) {
+      cards = await filter.transform(cards, context);
+    }
+
+    if (opts?.hints) {
+      cards = this.applyHints(cards, opts.hints, fullPool);
+    }
+
+    cards = cards.filter((c) => c.score >= threshold);
+
+    if (unseenOnly) {
+      let encountered: Set<string>;
+      try {
+        encountered = new Set(await this.user!.getSeenCards(courseId));
+      } catch {
+        encountered = new Set();
+      }
+      cards = cards.filter((c) => !encountered.has(c.cardId));
+    }
+
+    cards.sort((a, b) => b.score - a.score);
+    return opts?.limit ? cards.slice(0, opts.limit) : cards;
+  }
+
   /**
    * Scan every card in the course through the filter chain and report
    * how many are "well indicated" (score >= threshold) for the current user.

package/src/core/navigators/PipelineDebugger.ts

@@ -8,7 +8,7 @@ import {
   isFilter,
 } from './index';
 import { logger } from '../../util/logger';
-import type { Pipeline, CardSpaceDiagnosis } from './Pipeline';
+import type { Pipeline, CardSpaceDiagnosis, PipelineForecaster } from './Pipeline';
 import type { ReplanHints } from './generators/types';
 
 /**
@@ -25,6 +25,16 @@ export function registerPipelineForDebug(pipeline: Pipeline): void {
   _activePipeline = pipeline;
 }
 
+/**
+ * The most recently constructed pipeline for the current session, or null if
+ * none has been built yet. This is the supported, non-debug accessor for
+ * out-of-band reads against the live pipeline (e.g. a commit-free
+ * `forecast()`), replacing reach-ins through `window.skuilder.pipeline`.
+ */
+export function getActivePipeline(): PipelineForecaster | null {
+  return _activePipeline;
+}
+
 // ============================================================================
 // PIPELINE DEBUGGER
 // ============================================================================

package/src/core/navigators/diversityRerank.ts

@@ -0,0 +1,185 @@
+import type { WeightedCard } from './index';
+
+// ============================================================================
+// DIVERSITY RE-RANK  (pipeline stage 3)
+// ============================================================================
+//
+// Generators produce candidates → filters weigh them → THIS stage diversifies
+// the ranking. It demotes cards whose distinctive tags already appeared among
+// higher-ranked candidates, so a single answer/concept can't monopolise the
+// head of the queue (the "press `i` repeatedly" rut).
+//
+// ## Tag-agnostic by construction
+//
+// The framework has no first-class notion of an "answer" — tags are the only
+// structured similarity signal it carries. This stage privileges NO tag: it
+// hardcodes no namespace and works on whatever tags a course happens to apply.
+// "Tag-agnostic" means "no tag is special," not "ignores tags": a course that
+// never tags its sameness axis is invisible to the re-rank (acceptable — tags
+// are the framework's content contract).
+//
+// ## Why rarity weighting (IDF)
+//
+// Naive "penalize by count of shared tags" is noisy: cards share lots of
+// scaffolding tags (`ui:*`, incidental `gpc:expose:*`) that say nothing about
+// sameness. We weight each shared tag by its rarity in the candidate pool
+// (inverse document frequency). Ubiquitous tags contribute ~0; the distinctive
+// tag a cluster shares — exactly what makes a rut a rut — dominates. This is
+// self-tuning and needs no per-course configuration: a math course clustering
+// on "answer = 7" or a music course on "interval = M3" gets the same benefit
+// for free, provided that axis is tagged.
+//
+// ## Algorithm — greedy maximal-marginal-relevance
+//
+//   1. df[tag] = #cards carrying tag;  idf[tag] = ln(N / df[tag])
+//      (tag in every card → idf 0; rarer → larger).
+//   2. Walk candidates in score order, emitting one at a time. Track how many
+//      already-emitted cards carry each tag (`emittedCount`).
+//   3. A candidate's repetition load = Σ_{t ∈ card.tags} idf[t]·emittedCount[t].
+//      penalty = max(floor, 1 / (1 + strength·load)).
+//   4. Each step emit argmax(score·penalty); freeze that penalised score.
+//
+// Because each step picks the current maximum and selecting a card only lowers
+// (never raises) the remaining cards' values, the frozen scores are
+// monotonically non-increasing in pick order — so a subsequent sort-by-score
+// (the Pipeline's, and the SourceMixer's) reproduces this exact order. This is
+// why the stage expresses itself as SCORE penalties rather than a bare array
+// reorder: a positional shuffle would be silently undone by the mixer's
+// score-descending re-sort.
+//
+// ============================================================================
+
+export interface DiversityRerankOptions {
+  /**
+   * How hard repetition is penalised. Larger → steeper demotion of repeated
+   * distinctive tags. Penalty = 1 / (1 + strength·load).
+   */
+  strength?: number;
+  /**
+   * Minimum penalty multiplier. A card is never demoted below `floor × score`,
+   * however much it repeats. Keeps a strong-but-repeated card from being driven
+   * under downstream "well-indicated" thresholds (which would mislabel it as
+   * filler and could trigger spurious quality-replans). Tunes "perturb ordering"
+   * vs "annihilate candidates."
+   */
+  floor?: number;
+}
+
+/** Default repetition strength. See DiversityRerankOptions.strength. */
+export const DIVERSITY_STRENGTH = 0.6;
+
+/** Default penalty floor. See DiversityRerankOptions.floor. */
+export const DIVERSITY_FLOOR = 0.3;
+
+const STRATEGY = 'diversityRerank';
+const STRATEGY_ID = 'DIVERSITY_RERANK';
+const STRATEGY_NAME = 'Diversity Re-rank';
+
+/**
+ * Re-rank a scored candidate pool for answer/concept variety.
+ *
+ * Pure: returns a new array (diversified order, adjusted scores, appended
+ * provenance) and does not mutate the input cards. Cards entering are assumed
+ * to have score > 0 (the Pipeline strips zero-score cards before this stage).
+ * Non-finite scores (mandatory `requireCards`, score = +Infinity) are emitted
+ * untouched and still count toward repetition for later cards.
+ *
+ * @param cards - Post-filter, post-hint candidates.
+ * @param opts  - Optional strength/floor overrides (defaults are sane and
+ *                course-general; promote to strategy config if you ever want
+ *                this learnable under the orchestration layer).
+ * @returns Cards in diversified order with penalised scores.
+ */
+export function diversityRerank(
+  cards: WeightedCard[],
+  opts: DiversityRerankOptions = {}
+): WeightedCard[] {
+  const strength = opts.strength ?? DIVERSITY_STRENGTH;
+  const floor = opts.floor ?? DIVERSITY_FLOOR;
+
+  const n = cards.length;
+  if (n <= 1) return cards;
+
+  // 1. Document frequency → IDF. A tag in every card carries no discriminative
+  //    signal (idf 0); a rare tag dominates the repetition load.
+  const df = new Map<string, number>();
+  for (const card of cards) {
+    for (const tag of card.tags ?? []) {
+      df.set(tag, (df.get(tag) ?? 0) + 1);
+    }
+  }
+  const idf = new Map<string, number>();
+  for (const [tag, freq] of df) {
+    idf.set(tag, Math.log(n / freq));
+  }
+
+  // 2-4. Greedy MMR. `remaining` holds candidates not yet emitted; `emitted`
+  //      counts selected cards per tag.
+  const remaining = [...cards];
+  const emittedCount = new Map<string, number>();
+  const out: WeightedCard[] = [];
+
+  const repetitionLoad = (card: WeightedCard): number => {
+    let load = 0;
+    for (const tag of card.tags ?? []) {
+      const seen = emittedCount.get(tag);
+      if (seen) load += (idf.get(tag) ?? 0) * seen;
+    }
+    return load;
+  };
+
+  while (remaining.length > 0) {
+    let bestIdx = 0;
+    let bestValue = -Infinity;
+    let bestPenalty = 1;
+    let bestLoad = 0;
+
+    for (let i = 0; i < remaining.length; i++) {
+      const card = remaining[i];
+      const load = repetitionLoad(card);
+      const penalty = load > 0 ? Math.max(floor, 1 / (1 + strength * load)) : 1;
+      // Non-finite (mandatory) scores stay non-finite: Infinity × penalty =
+      // Infinity, so they argmax first and ride through unchanged.
+      const value = card.score * penalty;
+      // Strict ">" keeps the scan stable: ties resolve to the earlier (already
+      // higher-ranked-by-incoming-score) card.
+      if (value > bestValue) {
+        bestValue = value;
+        bestIdx = i;
+        bestPenalty = penalty;
+        bestLoad = load;
+      }
+    }
+
+    const [picked] = remaining.splice(bestIdx, 1);
+
+    if (Number.isFinite(picked.score) && bestPenalty < 1) {
+      const newScore = picked.score * bestPenalty;
+      out.push({
+        ...picked,
+        score: newScore,
+        provenance: [
+          ...picked.provenance,
+          {
+            strategy: STRATEGY,
+            strategyId: STRATEGY_ID,
+            strategyName: STRATEGY_NAME,
+            action: 'penalized',
+            score: newScore,
+            reason: `repeated tags (load ${bestLoad.toFixed(2)}) → ×${bestPenalty.toFixed(2)}`,
+          },
+        ],
+      });
+    } else {
+      // No penalty (fresh card, or mandatory/non-finite): emit untouched but
+      // still let it count toward later cards' repetition load below.
+      out.push(picked);
+    }
+
+    for (const tag of picked.tags ?? []) {
+      emittedCount.set(tag, (emittedCount.get(tag) ?? 0) + 1);
+    }
+  }
+
+  return out;
+}

package/src/core/navigators/generators/prescribed.ts

@@ -45,6 +45,21 @@ interface PrescribedGroupConfig {
   maxSupportCardsPerRun?: number;
   hierarchyWalk?: HierarchyWalkConfig;
   retireOnEncounter?: boolean;
+  /**
+   * Tag patterns identifying *practice* skills to drill once unlocked. For each
+   * course tag matching one of these patterns that is (a) unlocked — all its
+   * hierarchy prerequisites met, i.e. the learner has been introduced to it —
+   * but (b) still under-practiced (per-tag attempt count below
+   * `practiceMinCount`), the generator emits cards carrying that tag into the
+   * candidate pool. This closes the post-intro drilling gap independent of
+   * global-ELO retrieval (easy drill cards that the ELO window never reaches).
+   * Ordering/emphasis is left to the pipeline's scoring + decaying boost.
+   */
+  practiceTagPatterns?: string[];
+  /** Attempt-count threshold below which a practice skill is "under-practiced". */
+  practiceMinCount?: number;
+  /** Cap on practice cards emitted per run (across all under-practiced skills). */
+  maxPracticeCardsPerRun?: number;
 }
 
 interface PrescribedConfig {
@@ -106,9 +121,15 @@ const DEFAULT_MAX_DIRECT_PER_RUN = 3;
 const DEFAULT_MAX_SUPPORT_PER_RUN = 3;
 const DEFAULT_HIERARCHY_DEPTH = 2;
 const DEFAULT_MIN_COUNT = 3;
+const DEFAULT_PRACTICE_MIN_COUNT = 3;
+const DEFAULT_MAX_PRACTICE_PER_RUN = 4;
 const BASE_TARGET_SCORE = 1.0;
 const BASE_SUPPORT_SCORE = 0.8;
 const DISCOVERED_SUPPORT_SCORE = 12.0;
+// Practice drill cards enter the pool at parity with a well-matched target so
+// they survive into the candidate set; per-skill *emphasis* (recency, decay) is
+// the durable boost's job, not this base score's.
+const BASE_PRACTICE_SCORE = 1.0;
 const MAX_TARGET_MULTIPLIER = 8.0;
 const MAX_SUPPORT_MULTIPLIER = 4.0;
 
@@ -315,8 +336,19 @@ export default class PrescribedCardsGenerator extends ContentNavigator implement
         courseId,
         emittedIds
       );
+      const practiceCards = this.buildPracticeCards({
+        group,
+        courseId,
+        emittedIds,
+        cardsByTag,
+        hierarchyConfigs,
+        userTagElo,
+        userGlobalElo,
+        activeIds,
+        seenIds,
+      });
 
-      emitted.push(...directCards, ...supportCards, ...discoveredSupportCards);
+      emitted.push(...directCards, ...supportCards, ...discoveredSupportCards, ...practiceCards);
     }
 
     const hintSummary = this.buildSupportHintSummary(groupRuntimes);
@@ -357,6 +389,10 @@ export default class PrescribedCardsGenerator extends ContentNavigator implement
     const surfacedByGroup = new Map<string, { targetIds: string[]; supportIds: string[] }>();
     for (const card of finalCards) {
       const prov = card.provenance[0];
+      // Practice cards are not target/support surfacing — they must not reset a
+      // group's freshness/pressure state (which tracks whether *intro targets*
+      // are getting through). Skip them here.
+      if (prov?.reason.includes('mode=practice')) continue;
       const groupId = prov?.reason.match(/group=([^;]+)/)?.[1];
       const mode = prov?.reason.includes('mode=support') ? 'supportIds' : 'targetIds';
       if (!groupId) continue;
@@ -449,6 +485,17 @@ export default class PrescribedCardsGenerator extends ContentNavigator implement
                 : DEFAULT_HIERARCHY_DEPTH,
           },
           retireOnEncounter: raw.retireOnEncounter !== false,
+          practiceTagPatterns: dedupe(
+            Array.isArray(raw.practiceTagPatterns)
+              ? raw.practiceTagPatterns.filter((v: unknown): v is string => typeof v === 'string')
+              : []
+          ),
+          practiceMinCount:
+            typeof raw.practiceMinCount === 'number' ? raw.practiceMinCount : DEFAULT_PRACTICE_MIN_COUNT,
+          maxPracticeCardsPerRun:
+            typeof raw.maxPracticeCardsPerRun === 'number'
+              ? raw.maxPracticeCardsPerRun
+              : DEFAULT_MAX_PRACTICE_PER_RUN,
         }))
         .filter((g) => g.targetCardIds.length > 0);
 
@@ -765,6 +812,131 @@ export default class PrescribedCardsGenerator extends ContentNavigator implement
     return cards;
   }
 
+  /**
+   * Emit drill cards for *unlocked-but-under-practiced* skills.
+   *
+   * For each course tag matching the group's `practiceTagPatterns` that is both
+   * unlocked (all hierarchy prerequisites met — i.e. the learner has been
+   * introduced to it) and under-practiced (per-tag attempt count below
+   * `practiceMinCount`), this resolves cards carrying that tag and emits them
+   * into the candidate pool. It exists because global-ELO retrieval
+   * systematically fails to fetch the (low-ELO) drill cards for a
+   * freshly-introduced skill — putting them in the pool here lets the pipeline's
+   * scoring + the durable per-skill boost order them. Ordering/emphasis is NOT
+   * this method's job; it only guarantees presence.
+   *
+   * Fully data-driven: the unlock relation comes from the hierarchy config and
+   * practice-status from per-tag ELO. No card-id or tag-namespace hard-coding.
+   */
+  private buildPracticeCards(args: {
+    group: PrescribedGroupConfig;
+    courseId: string;
+    emittedIds: Set<string>;
+    cardsByTag: Map<string, string[]>;
+    hierarchyConfigs: HierarchyConfig[];
+    userTagElo: Record<string, { score: number; count: number }>;
+    userGlobalElo: number;
+    activeIds: Set<string>;
+    seenIds: Set<string>;
+  }): WeightedCard[] {
+    const {
+      group,
+      courseId,
+      emittedIds,
+      cardsByTag,
+      hierarchyConfigs,
+      userTagElo,
+      userGlobalElo,
+      activeIds,
+      seenIds,
+    } = args;
+
+    const patterns = group.practiceTagPatterns ?? [];
+    if (patterns.length === 0) return [];
+
+    const practiceMinCount = group.practiceMinCount ?? DEFAULT_PRACTICE_MIN_COUNT;
+    const maxPractice = group.maxPracticeCardsPerRun ?? DEFAULT_MAX_PRACTICE_PER_RUN;
+
+    const practiceTags = [...cardsByTag.keys()].filter(
+      (tag) =>
+        patterns.some((p) => matchesTagPattern(tag, p)) &&
+        this.isUnlockedGatedSkill(tag, hierarchyConfigs, userTagElo, userGlobalElo) &&
+        (userTagElo[tag]?.count ?? 0) < practiceMinCount
+    );
+
+    if (practiceTags.length === 0) return [];
+
+    // Reuse the diversity-aware tag→cards collector (stem-dedup + shuffle).
+    const practiceCardIds = this.findDiscoveredSupportCards({
+      supportTags: practiceTags,
+      cardsByTag,
+      activeIds,
+      seenIds,
+      excludedIds: emittedIds,
+      limit: maxPractice,
+    });
+
+    if (practiceCardIds.length === 0) return [];
+
+    logger.info(
+      `[Prescribed] Group '${group.id}' practice: ${practiceTags.length} unlocked under-practiced ` +
+        `skill(s), emitting ${practiceCardIds.length} drill card(s)`
+    );
+
+    const cards: WeightedCard[] = [];
+    for (const cardId of practiceCardIds) {
+      emittedIds.add(cardId);
+      cards.push({
+        cardId,
+        courseId,
+        score: BASE_PRACTICE_SCORE,
+        provenance: [
+          {
+            strategy: 'prescribed',
+            strategyName: this.strategyName || this.name,
+            strategyId: this.strategyId || 'NAVIGATION_STRATEGY-prescribed',
+            action: 'generated' as const,
+            score: BASE_PRACTICE_SCORE,
+            reason:
+              `mode=practice;group=${group.id};` +
+              `underPracticedSkills=${practiceTags.length};` +
+              `practiceTags=${practiceTags.slice(0, 8).join('|')}${practiceTags.length > 8 ? '|…' : ''};` +
+              `testversion=${PRESCRIBED_DEBUG_VERSION}`,
+          },
+        ],
+      });
+    }
+
+    return cards;
+  }
+
+  /**
+   * True for a skill that was *gated and is now reached*: it has at least one
+   * declared hierarchy prerequisite set, and every set is fully satisfied by the
+   * learner's per-tag ELO. This deliberately EXCLUDES tags with no prerequisites
+   * — an ungated tag was never "introduced" in the curricular sense, so it isn't
+   * a post-intro drill target (e.g. whole-word spelling tags that share the
+   * `gpc:exercise:*` prefix but have no intro gate). Those are left to normal
+   * ELO retrieval. This is the precise population the retrieval gap strands:
+   * just-unlocked, low-ELO skills.
+   */
+  private isUnlockedGatedSkill(
+    tag: string,
+    hierarchyConfigs: HierarchyConfig[],
+    userTagElo: Record<string, { score: number; count: number }>,
+    userGlobalElo: number
+  ): boolean {
+    const prereqSets = hierarchyConfigs
+      .map((hierarchy) => hierarchy.prerequisites[tag])
+      .filter((prereqs): prereqs is TagPrerequisite[] => Array.isArray(prereqs) && prereqs.length > 0);
+
+    if (prereqSets.length === 0) return false;
+
+    return prereqSets.every((prereqs) =>
+      prereqs.every((pr) => this.isPrerequisiteMet(pr, userTagElo[pr.tag], userGlobalElo))
+    );
+  }
+
   private findSupportCardsByTags(
     group: PrescribedGroupConfig,
     tagsByCard: Map<string, string[]>,