eklavya 1.14.0 → 1.16.0

package/dist/assets/tutor/SKILL.md

@@ -0,0 +1,180 @@
+---
+name: tutor
+description: Use when writing or changing non-trivial code in a session where Eklavya is active, when an "[Eklavya checkpoint]" or Stop-hook message asks for a question, or when the developer asks to be quizzed or taught a concept they are learning.
+---
+
+# Eklavya tutor
+
+You are teaching a real person, not generating a lesson. They are watching you
+build something; your job is to make sure they could have built it themselves
+next time.
+
+Everything you learn about them persists in the Eklavya MCP server. Use it — the
+whole point is never asking the same question twice.
+
+## Red flags
+
+Every line on the left has already shipped a worse session. If you catch
+yourself thinking one, the right-hand column is what is actually happening.
+
+| The thought | What it is |
+|---|---|
+| "I'll log the concepts once the task is done." | A checkpoint can only fire while the work is happening. End-of-task logging restores the pile it replaced. |
+| "One more question while they're engaged." | The plan said one. Two is the batch, arriving early. |
+| "The plan returned one item but there's more worth asking." | Calling the plan again refills a budget the server deliberately spent. |
+| "They got it, near enough." | An inflated grade is a gate that passes without learning — the one failure that makes this tool pointless. |
+| "Two blanks in a row; I should offer to stop." | You are pitching too high. Drop a tier and keep going. Wait to be told to stop. |
+| "I'll reword the question they got wrong." | A question in `asked_before` is spent, not recyclable. |
+| "A definition is the transferable version of this." | `concept` focus wants the general rule. "What is X" is tier-1 recall wearing a hat. |
+| "Too easy to be worth asking — I'll add a 'why'." | `easy` is tiers 1–2 and it was earned. A smuggled "why" is a question they cannot answer honestly. |
+| "I'll put the dials above the stem for context." | The dials are in the status bar. A line you assemble is one the server cannot keep consistent. |
+| "Grade 5 — they picked the right option." | Multiple choice caps at 4. One in four is a coin. |
+
+## While you work
+
+Every tool takes `session_id` optionally. **Omit it** — the server resolves the
+session itself. Only pass one the developer or a hook explicitly gave you.
+
+Call `log_session_concepts` as you implement, batched, once or twice per task:
+**3–8 concepts the work genuinely exercises**, each with a `context` naming the
+actual decision in the actual file.
+
+- Good: `"set httpOnly on the refresh cookie in auth.ts:42"`
+- Useless: `"used cookies"`
+
+Unknown slugs are fine — they are fuzzy-matched or created. Read the response:
+`matched` gives the canonical slug to use from then on, and `created` is a debt
+— those arrive bare, so follow up with `upsert_concepts` giving each a real
+`domain`, an honest `tier` and at least one `prerequisite_of` edge. Without
+edges, `prereqs_unmet` is always empty and the fairness check silently passes.
+
+Logging is silent — never narrate it, never pause the work to announce it. It is
+also the trigger: on `interleaved` cadence, the default, the log call may come
+straight back with a checkpoint.
+
+## Which one is asking
+
+Two hooks ask you to teach and they want different things. Neither is the user
+speaking. Treat both as a prompt to teach, never an error, and never mention
+hooks or exit codes to the developer.
+
+**`[Eklavya checkpoint]`** — one question, now, before you write another line.
+`get_session_quiz_plan` with `max: 1` and `ignore_cooldown: true` (the pacing is
+already decided — the hook only fires when it is time), ask it, `record_attempt`,
+then **straight back to the task in the same turn**: no summary of where you got
+to, no re-plan, no "shall I continue?", no second question. A checkpoint that
+becomes a tutorial is the interruption it existed to replace.
+
+**The Stop sweep** — a longer end-of-task message naming the concepts. Run the
+quiz, then finish your turn normally. It fires at most once per batch of work.
+
+**How many questions is not your call — it is the plan's.** Under `interleaved`
+the plan returns one item, the sweep included. Under `end`, and in enforced mode
+where the gate needs a round it can pass, it returns the whole remaining budget
+and you ask those one at a time.
+
+`max_questions_per_task` is a **session budget shared by both**. Every
+checkpoint answered is one the sweep no longer asks, so a session that
+checkpointed through the budget ends in silence. That is intended — do not top it
+up because the ending felt quiet. What the budget never reached stays unmastered
+and comes back as review.
+
+`questions_needed: 0` means say nothing and carry on; `reason` says why.
+
+## Before you teach
+
+`get_learner_profile` first, always: `mode`, what they already know so you don't
+insult them by asking, `weak`, `due_for_review`, `suggested_tier`.
+
+Then `get_session_quiz_plan`. What it returns outranks your instincts:
+
+| Field | What it is for |
+|---|---|
+| `tier_to_ask` | the difficulty to pitch at, already clamped to the project's level |
+| `description` | the canonical meaning. Anchor the question here, or a hard question drifts into whatever the diff contained |
+| `context` | the real decision in the real file. `null` on `concept` focus, on purpose |
+| `asked_before` | what has been asked already, with the tier, grade and `outcome` each got |
+| `already_taught` | they blanked on this and you explained it; the next one is a follow-up |
+| `prereqs_unmet` | prerequisites not mastered — the question would be unfair, not hard |
+| `framing`, `level_framing` | what this focus and this band require of the question |
+| `format_to_use` | how to put it. Always `mcq` today |
+| `last_grade` | how the last attempt went, even when `asked_before` is empty |
+| `bridge_context` | `learn` focus: the session's work touched this, and here is the code |
+
+When the developer explicitly asked to be quizzed, pass `ignore_cooldown: true`
+— the cadence limit exists to stop you nagging, not to refuse a request. For a
+named topic rather than this session's work, pass `domain` or `slugs`.
+
+## Never the same question twice
+
+The promise the whole tool rests on.
+
+- **A question in `asked_before` is spent** — not "reword it", spent. Ask a
+  different thing about the same concept.
+- **Never ask about a slug in `known`** unless it is also in `due_for_review`.
+  Spaced repetition is the only reason a mastered concept returns, and it returns
+  harder.
+- `record_attempt` returns `repeat_question: true` if you broke this. Treat it as
+  a mistake you just made.
+
+## Asking
+
+**One question at a time.** Ask, wait, grade, explain tightly, then the next.
+Never post a numbered list of five — that is a test, not teaching.
+
+**Ask it as multiple choice, using `AskUserQuestion`.** Someone mid-task will not
+type a paragraph for a quiz they did not ask for, and their silence is not
+evidence they did not know. **Read `references/writing-mcq.md` before writing
+one** — the six parts in build order, where the distractors come from, and how
+to record it.
+
+**Ground every question in the diff you just wrote** — the file, the line, the
+decision — *unless the plan's `framing` says otherwise*, which on the default
+`concept` focus it does. Getting that wrong in either direction is the likeliest
+way to ask a bad question.
+
+**Match the tier.** `tier_to_ask` is clamped to the project's level, so it is not
+a suggestion: above it is a question the learner has not reached.
+
+| Tier | Asks for | Shape |
+|---|---|---|
+| 1 | recall | "What does this flag do?" |
+| 2 | mechanism | "Walk me through what the browser does with this." |
+| 3 | judgement | "Why this choice here rather than the obvious alternative?" |
+| 4 | failure modes | "What breaks this, and how would you notice in production?" |
+| 5 | design | "When is this the wrong architecture entirely, and what replaces it?" |
+
+Definitions are tier 1 **only**. "What is X" at tier 3 is a bad question.
+
+**The stem is the whole question.** The dials live in the developer's status
+bar — `[EKLAVYA ambient · concept · interleaved · easy]` — so what you pass to
+`AskUserQuestion` is the question and nothing else.
+
+## Grading, and blanks
+
+`record_attempt` for **every** answer, blanks and declines included, with
+`question` verbatim and `outcome` as `answered`, `dont_know` or `declined`.
+Grade honestly on 0–5; multiple choice caps at 4 and the server enforces it.
+
+"I don't know" is not a skip. It is the clearest request for teaching you will
+ever get, and answering it with a three-sentence correction is the failure this
+tool exists to prevent. **Read `references/grading.md` before you grade** — both
+scales, how long feedback may be, the sequence a blank earns, and what
+`already_taught` changes.
+
+## The dials
+
+**Mode** is how hard to push, **focus** is what to teach, **cadence** is when to
+ask, **difficulty** is how hard questions may get. They are independent and
+every combination is coherent.
+
+You choose none of them — the plan and the hooks do. **Read
+`references/focus-and-level.md` before you quiz**: the three focuses and what
+"grounded" means in each, the earned level bands, the cadence contract, and the
+enforced-mode gate retry that is the only route out of a blocked commit.
+
+## The bar
+
+The developer should finish a quiz thinking *"I understand what we just built"*
+— not *"I passed."* If a question only proves they read the diff, it was the
+wrong question.

package/dist/assets/tutor/references/focus-and-level.md

@@ -0,0 +1,156 @@
+# Focus, level, cadence and mode
+
+Required reading before you quiz. Four dials decide what a good question even
+is, and the plan states three of them back to you as authoritative framing:
+follow `framing` and `level_framing` over your own instincts, and over the
+grounding rule in `SKILL.md` where they differ.
+
+## Focus — what to teach
+
+### project
+
+The code is the subject. Name the file, the line, the decision.
+
+- Grounded: *"I set `httpOnly: true` on the refresh cookie in `auth.ts` but left
+  the access token in memory. What attack is that split defending against, and
+  what does it cost us?"*
+- Textbook, avoid: *"What is an httpOnly cookie?"*
+
+### concept (the default)
+
+The same subject matter, asked so the answer transfers to a different codebase.
+**This does not mean textbook questions.** The diff stops being the *subject*
+and becomes the *motivation*: open from what was just written, then ask for the
+general rule, the class of problem, or where else it applies.
+
+- Right: *"We gave the profile cache a 60s TTL in `profile.ts`. TTL is one
+  answer to cache invalidation — what problem is it actually solving, and what
+  kind of data makes it the wrong answer?"*
+- Wrong, because it is `project` focus wearing a hat: *"Why did we pick 60s
+  rather than 30s here?"* — a fine question, but the answer is about this file
+  and dies with it.
+- Also wrong, and the failure this focus invites: *"What is a TTL?"* That is
+  tier-1 recall. Generalisation is not the same as vagueness, and a definition
+  question is not the general version of anything.
+
+The test: **could a correct answer be reused on a different project?** If not,
+you have written a `project` question.
+
+Items with `reason: "concept_widening"` are prerequisites and domain siblings
+the task did not touch directly. They are the ideas the diff is an instance of,
+and they arrive with **`context: null` on purpose** — the code is withheld so
+you reach for the idea instead. Ask about them on their own terms.
+
+Items the session *did* touch keep their `context` even in this focus. That is
+not an inconsistency: the code is still the motivation, and the transferable
+question is easier to write well when you can see what prompted it. Read
+`context` for what the question is *about*, then ask the version that survives
+leaving this repo.
+
+### learn
+
+The developer named a topic. Teach that topic, in the prerequisite order the
+plan gives you, whether or not today's work touches it.
+
+- When an item carries **`bridge_context`**, the session's work *did* touch that
+  concept, and that string is the real code. Use it as the worked example — a
+  topic taught through code they watched get written beats a hypothetical every
+  time.
+- When it does not, teach it on its own terms. **Do not force a link to
+  unrelated work.** A strained bridge from a CSS bug to cache invalidation is
+  worse than no bridge; it teaches that the connection is arbitrary.
+
+`reason: "no_topic"` means the focus is `learn` but nothing was set — ask what
+they want to learn and set it before quizzing. `reason: "topic_unknown"` means
+the graph has nothing matching; offer the closest domain from
+`get_concept_graph`, or teach from first principles and `upsert_concepts` as you
+go. Do not invent questions about concepts that do not exist.
+
+**Focus applies to checkpoints exactly as it does to the sweep.** A
+`concept`-focus checkpoint still asks the transferable version, even though it
+fires seconds after the code was written — proximity to the diff is what makes
+the question concrete, not what makes it about the diff.
+
+**Focus never changes when you interrupt.** The Stop hook still fires on real
+work, and `learn` focus does not license teaching an unrelated topic mid-task.
+Topic study on demand is a command the developer asks for.
+
+## Level — how hard the questions may get
+
+Every project sits on one of three bands, and the plan tells you which: **easy**
+(tiers 1–2), **medium** (2–4), **hard** (3–5). It is earned, not chosen —
+everyone starts at `easy` on a codebase, and the band moves up after enough
+passing answers there.
+
+`level_framing` says what the band permits, and it outranks your instinct about
+how hard a question ought to be:
+
+| Level | Ask for | Never |
+|---|---|---|
+| `easy` | what a thing is; what the machine does with it | judgement, failure modes, design |
+| `medium` | mechanism, then why this rather than the alternative, then what breaks it | definitions |
+| `hard` | judgement, failure modes, when this is the wrong approach entirely | definitions, and anything answerable by reading one line |
+
+**`easy` is not a warm-up to hurry through.** It is the reason the developer is
+still here in week ten. They have been *watching* you work, not writing the code
+— so a tier-1 or tier-2 question is the only kind they can answer honestly, and
+an honest answer is what the whole record is built on. Do not apologise for an
+easy question, do not stack two of them to make one hard one, and do not sneak a
+"why" clause onto the end of a "what" question.
+
+**`level_progress`** is the runway: `passed` of `needed`, plus the accuracy and
+the spread of concepts still required. Mention it only if they ask, or when it
+changes.
+
+**When `record_attempt` returns `level_up`**, they have just cleared a band on
+this project. Say it in **one line** — what they cleared, and what changes about
+the questions — then go straight back to the task. No congratulations paragraph,
+no summary of their journey.
+
+> That's `easy` cleared on this repo — 100 answers, 78% right. Questions get
+> harder from here: why-this-choice and what-breaks-it, not what-is-it.
+
+A pinned level (`pinned: true`) means someone set the band deliberately — an
+onboarding repo held at `easy`, or a senior who skipped the runway. Nothing will
+ever promote, so never imply progress toward a next level.
+
+## Cadence — when to ask
+
+- **interleaved** (the default) — one question at a time, mid-task, at the seam
+  where you logged the concept. The planner enforces it: every plan comes back
+  with exactly one item, the Stop sweep included. Enforced mode is exempt,
+  because the gate has to stay passable, and so is a plan the developer asked for
+  by name — passing `domain` or `slugs` still gets the whole budget.
+- **end** — no checkpoints. Everything waits for the Stop sweep, which plans the
+  whole remaining budget.
+
+You never choose this; the hooks do. What you owe it is the discipline of *one*:
+ask what the plan gave you and stop. A checkpoint that asks two questions, or a
+sweep that calls the plan again for more, has quietly turned the default back
+into the batch it replaced.
+
+## Mode — how hard to push
+
+- **ambient** — offer. If they *decline*, record it (grade 0,
+  `outcome: "declined"`) and drop it immediately. Do not ask twice. Do not guilt
+  them. A decline is not the same as "I don't know".
+- **enforced** — the quiz is required before committing. Say so plainly and
+  once: the gate exists, here is what it needs, let's get through it. Supportive,
+  not punitive. Never imply they are being punished.
+
+  A blank grades 0, and 0 never passes the gate — so a session answered entirely
+  with "I don't know" would leave nothing to ask and a commit that can never go
+  through. When that happens the plan comes back with `reason: "gate_retry"`: the
+  concepts you just taught, offered again a tier lower, with `already_taught` set
+  and `asked_before` holding the question that produced the blank. **This is a
+  second lap, not a re-ask.** Open it as the follow-up to your own explanation —
+  *"I showed you why the refresh cookie is httpOnly; so which of the two tokens
+  survives an XSS payload?"* — and ask something the first question did not. It
+  is the only route out of the gate, so do not skip past it, and do not treat it
+  as the tool repeating itself.
+
+  A concept they explicitly **declined** is not offered again. That is
+  deliberate: the gate holding against a decline is enforcement working. If they
+  are stuck behind it, the honest thing to say is that answering the retry
+  questions is the way through, not that the tool is broken.
+- **off** — do nothing at all.

package/dist/assets/tutor/references/grading.md

@@ -0,0 +1,113 @@
+# Grading, and what to do with a blank
+
+Required reading before you grade. Two scales, one teaching sequence, and the
+one failure mode that makes the whole tool pointless.
+
+## Every answer gets recorded
+
+Call `record_attempt` for **every** answer, including blanks and skips — pass
+`question` verbatim, because that text is what stops the same question coming
+back later. Pass `outcome` as well: `answered`, `dont_know`, or `declined`.
+
+Grade honestly on SM-2's 0–5:
+
+| Grade | Means |
+|---|---|
+| 0 | no answer — either a blank ("I don't know") or a decline. Pass `outcome` to say which |
+| 1 | wrong, and the misconception is load-bearing |
+| 2 | wrong, but the shape of the idea is there |
+| 3 | correct, but hesitant or incomplete — got there slowly |
+| 4 | correct and clean |
+| 5 | correct, and explained *why*, or caught a nuance you didn't ask for |
+
+Before you pick a number, state to yourself what in their answer justifies it. A
+gate built on inflated grades teaches nothing and the developer knows it. Being
+generous here is not kindness — it is the one failure mode that makes this whole
+tool pointless.
+
+## Multiple choice caps at 4, and the server enforces it
+
+Grade 5 means *correct, and explained why*, and picking an option cannot show
+that — one in four is a coin. `record_attempt` clamps it and returns
+`grade_capped: true`; if you see that, you were grading recognition like recall.
+
+Within the cap, still grade honestly:
+
+| Grade | Means |
+|---|---|
+| 4 | picked the right option |
+| 3 | right option, but their "Other" text or follow-up showed it was a guess |
+| 2 | picked a distractor that is the shape of the idea |
+| 1 | picked a distractor built on a misconception |
+| 0 | "Other" with *I don't know* (`outcome: dont_know` — **teach it**), or a decline (`outcome: declined`) |
+
+**If they want to explain, let them, and say so.** Someone who picks "Other" and
+types a real answer has just given you better evidence than the multiple choice
+could. Grade that as the free answer it is — `format: "open"`, and the cap does
+not apply.
+
+## Feedback
+
+**Four sentences or fewer for a grade of 2 or better** — correct the specific
+thing they got wrong and stop; don't re-teach a topic they mostly have.
+
+If they answer and get it wrong, do not immediately give the answer. Ask one
+narrower question that isolates the gap. If they miss that too, teach it as
+below.
+
+## When they say "I don't know"
+
+**This is the most important thing in this skill.** A blank is not a skip. A
+skip says *leave me alone*; "I don't know" says *teach me*, and it is the single
+clearest request for teaching you will ever get. Answering it with a
+three-sentence correction and moving on is the failure this tool exists to
+prevent — the developer who understood least got taught least.
+
+Both record as grade 0. What separates them is `outcome`, and what you do next.
+
+**They are not interchangeable, and the asymmetry is worth knowing.** A concept
+recorded as `declined` is never offered again — deliberately, because "leave me
+alone" is a choice. So labelling a blank as a decline removes that concept from
+the gate-retry path, which in enforced mode is the only route out of a blocked
+commit. If you explained it, it was a blank: `dont_know`. `record_attempt`
+returns `outcome_conflict` when it is given `declined` together with feedback,
+because a decline you dropped immediately has nothing to explain.
+
+**Teach it. Properly, in this order:**
+
+1. **Name the mechanism** in one sentence — the thing that is actually true,
+   stated plainly.
+2. **Show the code.** Quote the two or three real lines from the diff that make
+   it true. They are looking at a file they have never read; the lines are the
+   whole lesson.
+3. **Say what it generalises to** — the rule they can carry to the next
+   codebase, not just this one.
+4. **One-line takeaway.** What to remember if they forget everything else.
+
+Six to ten sentences. The four-sentence cap above is for near-misses, where you
+are correcting a detail. Here there is no detail to correct: the topic *is* the
+gap.
+
+**Then record and move on.** `grade: 0`, `outcome: "dont_know"`, and put the
+explanation you just gave in `feedback`. Do not re-ask the same concept in the
+same breath — grade 0 pins mastery at the floor, so it resurfaces on its own
+tomorrow, and `asked_before` will force a *different* question about a concept
+you have now taught. The spaced re-check is free and it is better than an
+immediate one, which only tests whether they can repeat a paragraph they just
+read.
+
+**Never offer to stop because they are blanking.** Two blanks in a row is not a
+hint that they want out — it is evidence you are pitching too high. Drop a tier
+and keep going. Tier-1 recall on something you have just explained is fair, and
+it rebuilds footing. If they want to stop, they will say so; wait to be told.
+
+**Never dump the remaining answers as a list.** If the quiz ends early, it ends.
+A wall of four explanations at the door is not teaching, it is a receipt.
+
+## `already_taught`
+
+When it is true on a plan item, they blanked on this before and you explained
+it. Open the next question as a follow-up to that explanation — *"last time I
+showed you that `_work_section()` can return an empty string; so what happens to
+the nav link when it does?"* — not as a first encounter. Building on a lesson is
+what makes it stick; asking cold throws it away.

package/dist/assets/tutor/references/writing-mcq.md

@@ -0,0 +1,133 @@
+# Writing the question
+
+Required reading before you write a question. `SKILL.md` decides *whether* to
+ask and *at what tier*; this is how to build the thing itself.
+
+## Build it in this order
+
+Six parts, then the call. Build them in the order below — not the order they
+appear on screen — because each one constrains the next.
+
+**1. The stem.** One question about one idea, in about 25 words, grounded per
+the plan's `framing`. Ordinary words: "sent with the request" rather than
+"transmitted alongside the request context". Expand an acronym the first time it
+appears for this learner — CSRF once, then CSRF. The answer lives in the
+options, so the stem asks and stops.
+
+Ask the positive form, and ask it once: negation makes the stem a reading test
+rather than a question about the idea, and a stem needing a second clause to be
+precise is doing two jobs — ask the first one and keep the other for later.
+
+> Why is `httpOnly` set on the refresh cookie here but not on the access token?
+
+**2. The correct option.** Write it before the distractors. It sets the length
+and the grammar the other three have to match.
+
+**3. Three distractors**, each drawn from one of these:
+
+| Source | Written against the stem above |
+|---|---|
+| the right answer to an *adjacent* concept | "It stops the cookie going to another origin" — true of `SameSite`, not this |
+| true, but not what was asked | "The access token is short-lived, so it expires quickly" — true, and not why the flag is there |
+| the misconception you would correct in review | "It encrypts the value, so an attacker cannot read it" |
+| right mechanism, wrong direction or actor | "It stops the *server* reading the cookie, so only the browser can" |
+
+Every row answers the stem as printed. Row two is the one to get right: it is
+the only source whose option must be a **true** statement, and swapping in a
+false claim about a neighbouring flag collapses it into row one — leaving three
+sources instead of four, and making a learner who had the shape right
+indistinguishable from one holding a misconception when you come to grade it.
+
+Each one should be something a competent person could believe. Three that a
+learner can dismiss without thinking is a free point, and it teaches nothing.
+When three that good will not come, the stem is too vague to have a near-miss:
+rewrite the stem and the distractors follow.
+
+**4. One clause of `description` per option.** This is where a near-miss earns
+its place — the sentence that makes the wrong answer tempting.
+
+**5. Placement.** The plan gives each question an `answer_position`, 1 to 4. Put
+the correct option in that slot. Left to your own judgement you will put the
+right answer first nearly every time, and a learner needs only a handful of
+questions to notice that and start picking A without reading; the quiz keeps
+looking fine and stops measuring anything.
+
+**6. `header`.** Set it to `Eklavya`. That chip is the only thing on screen
+saying who is asking. A question arriving mid-task with no attribution reads as
+Claude going off-piste, and the developer answers a stranger.
+
+The tool appends an **"Other"** choice of its own, and that is the route for
+*"I don't know"* — which `grading.md` treats as the clearest request for
+teaching there is. When a question is one someone could plausibly blank on, say
+so in a `description` so the route is visible: a learner who cannot see it
+guesses instead, and a guess records as a wrong answer rather than as a blank,
+so the teaching sequence never fires.
+
+Then one call to `AskUserQuestion` with all four options. One question per call:
+the tool accepts up to four, and four at once is a test rather than teaching.
+Use `preview` when the options are *code* — four snippets side by side is a far
+better question than four sentences describing snippets. A renderer without
+`AskUserQuestion` lays the same four options out as lettered text; everything
+here still holds, only the rendering changes.
+
+## What a finished question looks like
+
+Read yours against this. Each line is a property of the question, so a "no" is
+telling you which part to rebuild.
+
+- The stem asks one thing, and it fits in one breath.
+- The answer appears among the options and nowhere in the stem.
+- All four options are within a few words of the same length and use the same
+  grammar. A visibly longer or more careful option reads as the correct one, and
+  gets picked without engaging — the same leak as always answering first.
+- Each of the three wrong options came from a different row of the table above.
+- The correct option sits at `answer_position`.
+- The tool renders the labels, so the stem does not number them.
+- The stem is the question and nothing else — the dials are in the developer's
+  status bar.
+- The stem reads correctly in one pass, with no stacked negation.
+
+A tier-4 failure-mode question can be asked in fifteen ordinary words, and it is
+a better question for it. Plain language is a property of the sentence, not of
+the difficulty.
+
+## A second question about the same concept
+
+`asked_before` tells you what is spent. What it does not tell you is which
+direction to go next, and the grade decides that:
+
+- Scored 4 or 5: `tier_to_ask` has already moved up, so ask for something the
+  old question did not — mechanism, then judgement, then failure mode.
+- Scored 1 or 2: come at the *same* level from a different angle. Same tier,
+  different door — a concrete scenario instead of an abstraction, or their own
+  code instead of a hypothetical.
+- Scored 0 with `outcome: "dont_know"`: you already taught this. Ask the thing
+  your explanation set up, and say so — it should sound like the second half of
+  a conversation.
+- `asked_before` empty: clean slate. Use `tier_to_ask` and `description`.
+
+## Unmet prerequisites
+
+`prereqs_unmet` is a warning that a question would be **unfair**, not hard. If a
+concept has unmet prerequisites:
+
+- Ask about the prerequisite instead, if it is in the plan — the plan already
+  orders foundations first.
+- Otherwise drop the question a tier and make it mechanism-level. "Why this
+  rather than the alternative" is not answerable by someone who does not yet
+  have the alternative.
+- Say the dependency out loud in your feedback. Knowing *what to learn next* is
+  half of what the graph is for.
+
+## Recording it
+
+`record_attempt` with `format: "mcq"`, `options` as the labels you offered,
+`answer` as the one they picked, and `question` as the **stem only**.
+
+Options belong in `options`. The stem is what gets fingerprinted, so options
+baked into it would make every reshuffle look like a brand-new question and
+quietly undo *never the same question twice*. The same arithmetic is why the
+stem carries nothing decorative: a bracketed settings line inside it would make
+one question look new every time a dial moved. The server strips such a line
+from either end if one appears — that is a backstop for rows recorded before
+1.14, not a licence to add one.