The adaptive engine resolves settings in four layers. Each layer inherits from the one above and may override specific values. Teachers always see loaded defaults and can change them; nothing is locked behind a hidden “advanced only” wall. 1. Subject domain (Tier A / B prefill) Subject presets supply Cognitive Rigidity (R), recommended gate mode, mastery and calibration thresholds, frustration limit, and a default path profile (for example Mastery Gate for mathematics). Platform Admin engine_defaults sit at the absolute global tier; a teacher’s preferred subject only prefills new ladders — it does not override another author’s published ladder at play time. 2. Ladder The ladder’s subject_domain and whole-ladder pedagogy settings (confidence, predictive pre-step, interleaving, show_solution_after, no_repeat_across_sessions, allow_retry) apply to every step unless a node or path overrides them. 3. Node (step) Each step is a question type on the canvas. Node settings can override the predictive prompt for that step and carry role / difficulty / concept tags used by interleaving and analytics. 4. Path (edge) Paths are the arrows between steps. Gate mode, thresholds, frustration limit, and “if not ready” branching (ALB / Replay / Drop) live on the path. Changing the path profile reloads suggested numbers; editing a field writes a sparse override for that path only. Runtime merges these layers when a student plays. Type-level exit routing (post-question active-learning blocks by outcome × confidence) remains separate from path gates — exit routing shapes pedagogy after a question; path gates decide whether the student advances to the next step.

Cognitive Rigidity (R) is a number from 0 to 1 that describes how strictly a subject’s concepts must be mastered in order. High R means gaps early in the chain make later work meaningless; low R means themes can be explored in a more flexible order. R drives default thresholds, prerequisite strength, preferred gate mode, and which remediation style is suggested when a student struggles. Domain types (summary): • Type I — Strictly cumulative (R ≈ 0.85–0.95): mathematics, classical mechanics. Hard gates; Mastery Gate profile. • Type II — Scientifically cumulative (R ≈ 0.65–0.80): physics, chemistry. Soft gates; composite readiness. • Type III — Conceptually associative (R ≈ 0.45–0.60): biology, literacy/language. Advisory order. • Type IV — Interpretive / thematic (R ≈ 0.20–0.40): psychology, history. Minimal ordering; Replay often preferred over Drop. • Custom — teacher-set R and gates. Subject defaults (sensible starting points — always editable on each path): Mathematics — Type I · R 0.92 · Mastery 0.90 · CI 0.75 · Frustration 3 · Drop → ALB · Template: Mastery Gate Classical mechanics — Type I · R 0.88 · Mastery 0.85 · CI 0.72 · Frustration 3 · Drop → ALB · Mastery Gate Physics — Type II · R 0.78 · Mastery 0.80 · CI 0.65 · Frustration 4 · ALB · Scientific Method Chemistry — Type II · R 0.72 · Mastery 0.75 · CI 0.60 · Frustration 4 · ALB · Molecular Web Biology — Type III · R 0.55 · Mastery 0.70 · CI 0.50 · Frustration 5 · ALB · Conceptual Network Psychology — Type IV · R 0.35 · Mastery 0.65 · CI 0.45 · Frustration 6 · Replay · Reflective Lens History — Type IV · R 0.30 · Mastery 0.65 · CI 0.40 · Frustration 6 · Replay · Reflective Lens Literacy / language — Type III · R 0.50 · Mastery 0.68 · CI 0.50 · Frustration 5 · Replay · Resilience Builder Pedagogically, high-R subjects reward procedural correctness before advance; low-R subjects give more weight to honest self-assessment so a student who knows what they do not know is treated differently from one who is blindly guessing.

Each arrow is a learning dependency with weight 1–5 (from subject mode by default). The engine topologically sorts steps, respects AND-joins (all incoming paths), supports multiple entry priorities, and completes only when all exit nodes are reached. Hard prerequisite cycles block publish; soft loops condense into a study-together block. On frustration, demote sends the student to the highest-weight unsatisfied prerequisite.

From the learning-path builder, Insert ladder offers exactly two choices. Copy content in Copies all question types, paths, and settings into this ladder. Steps are fully editable afterwards and there is no live link to the source at runtime. Draft sources are allowed. Quiet provenance metadata is stored for migration tools. Insert as a black box Adds the source ladder as a sealed block you cannot edit on this canvas. The block shows the source title and exposes multiple inlets (entry ports) and outlets (exit ports) derived from the source graph. Wire outlet → inlet between blocks and ordinary question-type steps using the same path settings as any other arrow (profile, gate, frustration, dependency weight, branching). Students always run the latest published version of the source inside the block. The source must be published when you insert and when students play. Port wiring Each inlet/outlet is a React Flow handle labelled with the underlying entry/exit step. Single-entry/single-exit sources stay simple — one inlet and one outlet. Multi-port sources require explicit handle-to-handle connections. When the source’s entries or exits change elsewhere, the block shows Update available; click Update from source (or Update all blocks) to refresh cached ports and highlight stale paths in red for rewiring. Delete protection Deleting a ladder that other ladders embed as a block warns you first. Delete anyway detaches those blocks and their wired paths from referencing ladders, then removes the source.

After each question (before feedback is fully revealed in the confidence flow), the student rates confidence on a 1–5 scale. Pairing that rating with correctness places them in one of four metacognitive states. The engine uses these states to choose remediation, not merely to show a score. I — Mastery (correct + high confidence 4–5) Calibrated and competent. The student may fast-track: remaining variants on this node can be skipped and the path gate is more likely to open. II — Fragile knowledge (correct + low confidence 1–2) Under-confident or lucky. Correctness alone is not enough — serve an isomorphic parallel variant with affirming feedback and confirm mastery before advancing. III — Illusion (incorrect + high confidence 4–5) A misconception held with certainty. Do not drill the same stem again. Intercept with conflict-style active learning (counter-example, cognitive dissonance) so the false belief is challenged. IV — Blindspot (incorrect + low confidence 1–2) Aware of the gap; often frustrated but honest. Prefer scaffold-style active learning: step-by-step breakdown and worked example. Separate from this 1–5 question confidence, ladder topic confidence (1–10) can be collected between steps when enabled in ladder settings. That rating can trigger same-step remediation when it sits at or below a teacher-chosen threshold. Both signals support teacher-controlled adaptivity — AI does not auto-publish content; the configured blocks and paths decide what students see.

These formulas are the mathematical heart of path gates. Values are computed per attempt on a node; thresholds on the path decide whether the student may advance. Mastery (recency-weighted EMA) M_t = α · A_t + (1 − α) · M_(t−1) A_t is 1 if the attempt is correct, else 0. α (default about 0.35) is the recency weight: higher α makes recent attempts matter more. M_t stays between 0 and 1. An EMA avoids “early struggle locks you out forever” streak counters — a student who recovers recently can still pass a mastery bar. Calibration index First deviation D_t: • If correct (A_t = 1): D_t = 5 − C_t (penalises under-confidence) • If incorrect (A_t = 0): D_t = C_t − 1 (penalises over-confidence) Then: CI_t = 1 − D_t / 4 C_t is confidence 1–5. CI_t = 1 means perfect calibration (e.g. correct with 5, or incorrect with 1). CI_t = 0 means complete misalignment (incorrect with 5 — Illusion). Composite gate score G_t = R · M_t + (1 − R) · CI_t R is Cognitive Rigidity for the subject. Mathematics (R ≈ 0.92) makes G_t almost entirely mastery-driven; psychology (R ≈ 0.35) weights calibration more heavily so accurate self-assessment counts toward readiness. Frustration / fatigue F_t = F_(t−1) + 1 if A_t = 0 F_t = 0 if A_t = 1 When F_t reaches the path’s frustration limit without meeting the gate, the “if not ready” branch runs (ALB, Replay, or Drop). After an ALB that returns to the same node, F_t resets to 0. After Replay into a parallel variant, F_t is typically halved so the struggle still informs routing. A correct answer clears the counter.

Every path has a gate mode that decides how M_t, CI_t, and G_t are interpreted against thresholds. Dual mode The student must meet both the mastery threshold and the calibration threshold (and keep F_t below the frustration limit). This is the natural fit for Type I subjects: procedures must be correct and confidence must not be wildly misaligned. Thresholds are shown as percentages in the builder (for example mastery 90%, calibration 75%). Composite mode A single readiness score G_t = R · M_t + (1 − R) · CI_t must meet the composite threshold, with F_t still below the limit. Teachers who prefer one dial use this mode. Subject R is already baked into G_t, so the same composite threshold feels stricter in high-R subjects than in low-R ones for the same raw accuracy. What the thresholds mean in plain language • Mastery — minimum recent accuracy bar on this path. • Calibration — how well stated confidence must match outcomes. • Composite — combined readiness bar when using Composite mode. • Frustration limit — how many failed attempts before remediation branching fires. Changing gate mode on a path does not delete your numbers; unused thresholds are simply ignored until you switch back. Profiles (Mastery Gate, Scientific Method, Reflective Lens, …) preload a sensible mode + numbers for the ladder subject — you can still edit freely.

A path is the directed transition from one step to the next. Students advance along a path only when the gate says they are ready (and frustration has not forced a branch). If not ready — three strategies • ALB (active learning, then retry) — show a remediation block (scaffold, conflict, concept map, …), then let the student attempt the step again. Preferred when the misconception or gap needs structured teaching. • Replay — send the student through the step again (often an isomorphic variant) without a separate pedagogy block. Preferred for interpretive subjects where another attempt with reflection is enough. • Drop — move onto an easier alternative path when the graph provides one. Useful in cumulative subjects when a parallel scaffold track exists. allow_retry (ladder setting) When allow_retry is on, failing a gate and completing remediation can return the student to attempt the same step again. When off, the engine avoids endless retry loops and follows the configured fallback / drop behavior more strictly. Pair allow_retry with ALB branching for “teach then try again”; turn it down when you want Drop or a fixed exit after limited attempts. Profiles encode a recommended branching default (mathematics Mastery Gate → Drop → ALB; psychology Reflective Lens → Replay). Editing “If not ready” on a path writes an override for that edge only.

These settings apply to the ladder session as a whole. They sit beside path gates and type-level exit routing. show_solution_after When on, worked solutions / solution steps may be returned after submit. When off, the grade API omits solution payloads so students cannot peek at the worked answer — useful for timed practice or exam-style embeds. The frontend must honour the flag on next/grade responses. no_repeat_across_sessions When on, question selection excludes items this student (by student_token) has already seen on this ladder across prior embed sessions. Small pools may still exhaust and fall back to repeats; treat this as “prefer fresh items”, not a hard uniqueness guarantee. Predictive pre-step When enabled, before a new step begins the student answers a short prediction prompt (metacognitive reflection). The ladder can set a default prompt; each node may override with its own predictive_prompt. Runtime prefers the node prompt when present, otherwise the ladder-wide prompt. Interleaving At frequency N (every 2–6 steps; 0 = off), the engine may insert a disguised review question before continuing. Source options: • within_node — another published item from the current step’s question type • ladder_wide — earlier mastered / prior steps on this ladder (default) • cross_ladder — published questions from other ladders by the same teacher (falls back to ladder_wide when none exist) Confidence (ladder topic, 1–10) Optional between-step confidence with optional remediation: at or below the threshold, serve another question from the same step until confidence improves. This is separate from the 1–5 post-question confidence used in the four quadrants. Pass score and questions per step remain available for linear / legacy progression rules where a simple percent pass is enough; path gates are the richer adaptive control.

The subject dropdown chooses which preset seeds new paths and which profile chip is suggested. It does not silently rewrite a finished graph without confirmation. When you change subject on create or edit, TeachForge offers two choices: • Keep existing path settings — only the ladder’s subject label updates; every path keeps its current profile, thresholds, and overrides. • Apply subject defaults to all paths — reloads each path from the new subject’s recommended profile (for example switching to mathematics loads Mastery Gate–style defaults). Custom overrides on those paths are cleared as part of applying the new profile. Use “apply to all” when you are still designing and want a coherent subject flavour. Use “keep” when you have already tuned individual paths and only need the correct subject metadata for cataloguing, interleaving tags, or reporting. Teachers can also save a preferred subject for the next new ladder (Tier B authoring preference). That preference never overrides another author’s ladder at play time — runtime always respects the ladder’s own settings and path overrides.