eklavya 1.59.0 → 1.60.0

package/dist/plugin/skills/tutor/SKILL.md

@@ -9,8 +9,16 @@ 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.
+Everything you learn about them persists in the Eklavya MCP server: use it to
+never ask the same question twice.
+
+## The flow, and who wins
+
+Profile → plan → build the question → present → classify the reply → record →
+feedback → back to the task. Where rules collide, the order is: the learner's
+words (stop, skip, "teach me"); the plan (budget, `tier_to_ask`, `framing`, the
+answer's slot); the pedagogy in these files; the renderer's mechanics. An
+exception sits beside the rule it overrides.
 
 ## Red flags
 
@@ -19,16 +27,17 @@ 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. |
+| "I'll log the concepts once the task is done." | A checkpoint can only fire mid-work. End-of-task logging restores the pile it replaced. |
+| "One more question while they're engaged." | The plan said one. Two is the batch, 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. |
-| "They know what 'Task 6' means." | They saw none of it. Define the name or drop it. |
-| "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. |
+| "Two blanks in a row; I should offer to stop." | The planner already lowers the tier. Keep going at `tier_to_ask`; wait to be told to stop. |
+| "They said it lacks context; I'll record a blank." | That grades them 0 for your mistake. Record `invalid`. |
+| "I'll reword the question they got wrong." | A question in `asked_before` is spent. |
+| "A definition is the transferable version of this." | `concept` focus wants the general rule; "What is X" is tier-1 recall. |
+| "Too easy to be worth asking — I'll add a 'why'." | `easy` is tiers 1–2 and was earned. A smuggled "why" cannot be answered honestly. |
+| "They know what 'Task 6' means." | They saw none of it. Define it or drop it. |
+| "I'll put the dials above the stem for context." | They are in the status bar; a line you assemble cannot stay consistent. |
 | "Grade 5 — they picked the right option." | Multiple choice caps at 4. One in four is a coin. |
 
 ## While you work
@@ -49,9 +58,9 @@ Unknown slugs are fine — they are fuzzy-matched or created. Read the response:
 `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 `as-you-go` cadence, the default, the log call may come
-straight back with a checkpoint.
+Logging is silent — never narrate it or pause the work to announce it. On
+`as-you-go` cadence, the default, the log call may come straight back with a
+checkpoint.
 
 ## Which one is asking
 
@@ -74,18 +83,18 @@ too. Call `get_session_quiz_plan`, run the quiz and follow its `on_skip` and
 once in a long session (paced by the clock), so treat each as its own single
 question, not a sign you missed the last one.
 
-**Your task answer goes last.** Write the answer when the task is done. If the
-Stop sweep then asks for questions, ask them one at a time with a verdict each,
-and end with "Back to your task:" and the answer again in 2-4 lines. Never end
-a turn on a question or a verdict.
+**Your task answer goes last.** If the Stop sweep asks for questions after the
+task is done, ask them one at a time with a verdict each, and end with "Back to
+your task:" and the answer again in 2-4 lines. Never end a turn on a question
+or a verdict.
 
 **While an agent builds.** With `delegate_work` on (the default), non-trivial
 code changes go to background agents and the wait is when you teach. A hook
 repeats this once, when you edit a second file yourself. Start
 them, log the plan's concepts, then loop: `get_session_quiz_plan` with
 `while_waiting: true`, ask, grade, verdict. Stop when an agent reports or
-`questions_needed` is 0, then write the task answer last. Agents cannot ask,
-and hooks do not quiz inside them. Keep small fixes and lookups inline.
+`questions_needed` is 0, then write the task answer last. Agents cannot ask, and hooks
+do not quiz inside them. Keep small fixes and lookups inline.
 
 **How many questions is not your call — it is the plan's.** Under `as-you-go`
 the plan returns one item, the sweep included. Under `end`, and when enforced,
@@ -130,9 +139,9 @@ 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.
+- **Never ask about a slug in `known`** unless it is also in `due_for_review`
+  or its plan item is `reason: "gate_work"` (an enforced gate lists it even when
+  mastered; skipping it can make the gate impossible to pass).
 - `record_attempt` returns `repeat_question: true` if you broke this. Treat it as
   a mistake you just made.
 
@@ -144,7 +153,7 @@ Never post a numbered list of five — that is a test, not teaching.
 **Ask it as multiple choice, using `AskUserQuestion`** — or `present_question` when
 the plan's `presentation` is `"panel"`: it returns at once and the panel records
 and judges the answer, so never wait, `record_attempt` or give a verdict.
-Nobody mid-task types a paragraph for a quiz they did not ask for. **Read
+**Read
 `references/writing-mcq.md` before writing one**: the six parts in build order,
 where distractors come from, how to record it; for `"panel"` also
 `references/panel.md`.
@@ -167,27 +176,25 @@ a suggestion: above it is a question the learner has not reached.
 
 Definitions are tier 1 **only**. "What is X" at tier 3 is a bad question.
 
-**The stem is the whole question, and the plan's `ask_attribution` says how to
-sign it.** The dials live in the developer's status bar — `[EKLAVYA
-concept · as-you-go · easy]` — so they never go in the stem. Who is asking is
-the one exception, and whether it belongs in the stem depends on the host:
-follow `ask_attribution` rather than deciding.
+**The stem is the whole question; the plan's `ask_attribution` says how to
+sign it.** The dials live in the status bar, so they never go in the stem.
+Whether who is asking belongs in the stem depends on the host: follow
+`ask_attribution`.
 
 ## Grading, and blanks
 
-`record_attempt` for **every** answer you collect, 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.
+`record_attempt` for **every** answer, with `question` verbatim and `outcome` as
+`answered`, `dont_know`, `declined` or `invalid` (the question was at fault;
+grades nothing). Multiple choice caps at 4. "I don't know" is not a skip: it is a
+request for teaching. **Read `references/grading.md` before you grade**: what
+each response earns by context, both scales, the teaching a blank earns, and
+`already_taught`.
 
 **A missed answer can come back with `explain`.** That is `explain_on_wrong` at
 work: follow its `instruction` exactly. Hand the explainer its `attempt_id` and
-`option_notes` too: the page shows the notes and can be corrected. The page is written in the background
+`option_notes` too: the page shows the notes and can be corrected. A parallel
+tutor's reply ends with a handoff block (`agents/tutor.md`): start the
+explainer from it, every field included. The page is written in the background
 and opens by itself, so give the verdict, say the page is on its way, and go
 back to the task — no longer explanation, no waiting. When the developer asks
 for something to be explained as a page ("explain this to me", "make me a page
@@ -200,12 +207,10 @@ 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 gate retry that is the only route out of a blocked commit.
+`references/focus-and-level.md` before you quiz**: the three focuses, the earned
+level bands, the cadence contract, and the enforced gate retry.
 
 ## 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.
+The developer should finish a quiz thinking *"I understand what we just built"*,
+not *"I passed."* A question that only proves they read the diff was the wrong one.

package/dist/plugin/skills/tutor/references/focus-and-level.md

@@ -204,7 +204,8 @@ into the batch it replaced.
   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
+  A concept they explicitly **declined** is not offered again by this session's
+  retry (a later session's review may bring it back once it is due). 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.

package/dist/plugin/skills/tutor/references/grading.md

@@ -1,15 +1,34 @@
 # 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.
+Required reading before you grade. Call `record_attempt` for **every** answer,
+blanks and skips included, with `question` verbatim (that text is what stops the
+same question coming back) and an `outcome`: `answered`, `dont_know`, `declined`
+or `invalid`. A question that was itself at fault is not a grade at all: see
+*When the question is at fault*.
 
-## Every answer gets recorded
+## What every response earns
 
-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`.
+Find the row for who asked and what the learner did. The sections below say how
+to do each cell.
 
-Grade honestly on SM-2's 0–5:
+| Learner | Automatic question: checkpoint, sweep, while-waiting | Panel | Parallel tutor | Asked-for quiz or lesson |
+|---|---|---|---|---|
+| Right | record; verdict | the panel records and judges; do nothing | record; verdict | record; verdict |
+| Wrong | record; verdict, right answer, one line of why; no follow-up | as left | as left, then the handoff block | do not give the answer yet: one narrower question, then teach |
+| Blank ("I don't know") | `dont_know`; answer and one line of why | as left | as left | `dont_know`; the full four-step teaching |
+| Skip | `declined`, nothing said | the Skip button records it | `declined` | `declined` |
+| Question at fault | `invalid`; own it, give the answer, no replacement this turn | n/a: nothing to press | `invalid` | `invalid`; own it, then ask a fixed question now |
+| Silence | nothing | nothing | nothing, do not chase | wait |
+
+Then **straight back to the task** in every automatic case: no summary, no
+second question, no re-plan. A verdict is *right*, or *wrong plus the right
+answer and one line of why*, and it always comes first.
+
+## Grading honestly
+
+Grade on SM-2's 0–5. Before you pick a number, state to yourself what in their
+answer justifies it: a gate built on inflated grades teaches nothing, and being
+generous is the one failure that makes this tool pointless.
 
 | Grade | Means |
 |---|---|
@@ -20,18 +39,9 @@ Grade honestly on SM-2's 0–5:
 | 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:
+**Multiple choice caps at 4, and the server enforces it** (`grade_capped: true`
+means you graded recognition like recall). Picking one of four cannot show *why*.
+Within the cap:
 
 | Grade | Means |
 |---|---|
@@ -39,104 +49,91 @@ Within the cap, still grade honestly:
 | 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`) |
-
-**A defensible pick is a correct answer.** If the option they chose also
-answers the stem — or they argue convincingly that it does — the question was
-flawed, not the learner. Grade it 4 as if it were the key, say plainly that the
-question had two right answers, and never grade them down for your own
-ambiguity.
+| 0 | "Other" with *I don't know* (`dont_know`, teach it), or a decline (`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 — **omit `format`**, and the cap does
-not apply.
+**A defensible pick is a correct answer.** If their option also answers the
+stem, or they argue convincingly that it does, the question was flawed, not the
+learner: grade it 4, say plainly it had two right answers, and never mark them
+down for your ambiguity. If they did not pick but said two are right, that is
+`invalid`.
 
-## Feedback
+**If they want to explain, let them.** Someone who picks "Other" and types a real
+answer has given better evidence than the choice could. Grade it as free recall:
+omit `format`, and the cap does not apply.
 
-**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.
-
-**Always say whether they were right first.** At an `[Eklavya checkpoint]`
-there is no narrower question — the checkpoint is one question — so a miss
-gets the right answer and one line of why, then the task resumes.
+Feedback for a grade of 2 or better is four sentences or fewer: correct the
+specific thing they got wrong and stop.
 
 ## 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 when enforced 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. It rejects
-`declined` or `dont_know` with a grade of 3 or more (`outcome_grade_conflict`)
-and records nothing: call again with the pair that is true.
-
-**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.
+**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*, the clearest request for teaching you will ever get.
+Answering it with a three-sentence correction is the failure this tool exists to
+prevent. Both record grade 0; `outcome` separates them.
+
+They are not interchangeable. A `declined` concept is not offered again in this
+session's gate retry (a later session's project review may bring it back once it
+is due), so labelling a blank as a decline removes it from the only route out of
+a blocked commit. If you explained it, it was a blank: `dont_know`.
+`record_attempt` returns `outcome_conflict` for `declined` with feedback (a
+decline you dropped has nothing to explain), and rejects `declined` or
+`dont_know` with a grade of 3 or more (`outcome_grade_conflict`) without
+recording anything.
+
+**Who teaches, and how much.** The full sequence is for a quiz or lesson the
+developer asked for. For an automatic question the answer and one line of why is
+the whole inline reply, and when `record_attempt` returns `explain` the
+background page carries the long version: teach in one place, never both.
+
+1. **Name the mechanism** in one sentence, plainly.
+2. **Show the code, or a small example.** With a `context` from the plan, quote
+   the two or three lines from the diff that make it true, only lines you have
+   read. With `context: null` (`concept` focus, a review, a topic lesson) write a
+   three-to-six-line worked example and say it is one. Never present invented
+   lines as theirs.
+3. **Say what it generalises to**: the rule they carry to the next codebase.
 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.
+Six to ten sentences. Then record: `grade: 0`, `outcome: "dont_know"`, your
+explanation in `feedback`. Do not re-ask in the same breath: grade 0 pins mastery
+at the floor, so it resurfaces tomorrow, and `asked_before` forces a different
+question. Never offer to stop because they are blanking: two blanks mean the
+pitch was too high, the planner already lowers `tier_to_ask`, so ask at the tier
+the plan gives and wait to be told to stop. Never dump the remaining answers as a
+list.
 
-**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.
+## When the question is at fault
 
-**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.
+"This question does not have enough context", or "two of these are right" with
+no pick made, is a verdict on the question, not a decline and not a blank. The
+miss is yours and must cost them nothing:
 
-## When they say the question lacks context
-
-"This question does not have enough context" is a verdict on the question, not
-a decline. The question assumed something they never saw, so the miss is
-yours. Never drop it untaught:
-
-1. **Own it** in a few words — the question leaned on something you had not
-   shown them.
+1. **Own it** in a few words.
 2. **Give the answer and one line of why**, defining the name or situation the
    stem skipped.
-3. **Record it as a blank**: `grade: 0`, `outcome: "dont_know"`, with that
-   answer in `feedback`. It is not `declined` — a decline is never offered
-   again, and they did not ask to be left alone.
-
-The next question about it, now or later, starts with the situation sentence
-the first one was missing (`writing-mcq.md`, *Write for a cold reader*).
+3. **Record `invalid`**: `outcome: "invalid"`, `grade: 0` (ignored), what was
+   wrong in `feedback`. Nothing is graded: no mastery, level, accuracy, review
+   date or gate changes, no `attempt_id` comes back, and an enforced gate does not
+   count it, so the concept is still asked. The stem is marked spent.
+4. **Replace it** where the pacing allows (the table above). The replacement
+   opens with the situation sentence the first one lacked (`writing-mcq.md`,
+   *Write for a cold reader*).
+
+A learner who really blanked on a clear question is `dont_know`: only the
+question's own defect makes it `invalid`.
+
+## Skip, stop and opting out
+
+- **Skip this question**: `declined`, no teaching, no second ask.
+- **Stop for now** ("enough"): stop asking this session and record nothing for
+  questions never shown. Nothing remembers it past the session, so for a lasting
+  stop tell them `eklavya config set quiz.enabled false` (the dashboard Settings
+  page does the same).
+- **Opt out of a topic**: there is no per-topic switch; do not promise one.
 
 ## `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.
+When 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.

package/dist/plugin/skills/tutor/references/panel.md

@@ -18,7 +18,7 @@ Make one call to `present_question` instead:
 - `options`: four, in display order, each `{label, description, grade}`. The
   `label` is the option itself, a complete claim (what `writing-mcq.md` calls the
   option), never `A` or `1`: the panel numbers them, and a bare marker is rejected.
-  The `description` is the one clause from part 4. Mark the right one
+  The `description` is the neutral clause from part 4: what the option claims, with no verdict and no "tempting because". Mark the right one
   `correct: true`, **in the `answer_position` slot** (the call is rejected with
   `wrong_answer_position` otherwise, and nothing is stored).
 - Each option's `grade` is what a learner who picks it has shown, on the scale in
@@ -32,7 +32,10 @@ Make one call to `present_question` instead:
   `` `shouldRepaint` ``) and nothing else: no headings, lists or emphasis. Option `label`s are drawn as
   plain text, so write them in words and leave the backticks out of them.
 - `explanation`: one line saying why the right option is right. The panel shows
-  it after the answer, so it is the whole of your feedback.
+  it after the answer, so it is the whole of your feedback. A call whose options
+  are lopsided in visible length, or whose descriptions explain themselves, is
+  rejected once with `conspicuous_options` and nothing stored: rewrite and call
+  again with the same stem.
 
 It returns at once. Do not wait for the answer, do not call `record_attempt`
 (the panel records it, once), do not give a verdict, and go straight back to

package/dist/plugin/skills/tutor/references/writing-mcq.md

@@ -95,18 +95,25 @@ Before asking, read each distractor as if it were the key: if a senior reviewer
 could argue for it, narrow the stem ("why *here*", "what does *this line*
 prevent") until it cannot, or replace it with a different row.
 
-**4. One clause of `description` per option.** This is where a near-miss earns
-its place — the sentence that makes the wrong answer tempting.
-
-The parity rule from step 2 holds here too, and this is where it usually
-breaks: the correct option gets the careful sentence that explains the
-mechanism, and each distractor gets a few throwaway words. A learner reads that
-as the answer without reading the claim. Give every description the same
-weight — one clause of similar length, none standing out as the longest or the
-shortest — and spend the effort on the distractors: each one says why it is
-tempting, as specifically as the correct one says why it holds. Overcorrecting
-is a tell too: if the right answer's note is never the longest, a learner
-learns to rule the longest one out.
+**4. One neutral clause of `description` per option.** The learner reads it
+before answering, so it says what the option *does or claims*, never whether it
+is right, why it is tempting or which misconception it is. "Tempting because…",
+"a common mistake" and "this is why it works" are feedback, and feedback comes
+after the answer.
+
+Judge parity on what is on screen: the label and its description together. Give
+every option the same grammar, the same number of claims and the same kind of
+detail. Do not keep the mechanism, the example or the caveat for the correct
+one. Bring the short ones up with real content, never filler; if a distractor
+cannot reach the length honestly, the stem is too thin to have a near miss. The
+correct option should not be the longest, and it should not be systematically
+the shortest either: that is a tell in the other direction. The server and the
+`ask-label` hook send back an option that outruns the next by a few words, or
+whose description explains itself, once; rewrite it and ask again.
+
+The reasoning behind each option goes in `option_notes` when you record the
+attempt (the card path) and in the panel's `explanation` (the panel path), both
+shown only after the answer.
 
 **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
@@ -157,9 +164,8 @@ telling you which part to rebuild.
 - 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.
-- The four descriptions are within a few words of each other too, and the
-  correct option's is no more careful than the rest. Each distractor's says why
-  it is tempting, not just that it is wrong.
+- Each option, label plus description, is within a few words of the others, and
+  no description says why an option is right, wrong or tempting.
 - Each of the three wrong options came from a different row of the table above.
 - Only the correct option answers the stem; no expert could argue for another.
 - The correct option sits at `answer_position`.
@@ -194,9 +200,10 @@ 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.
+- Otherwise ask at `tier_to_ask` (the planner owns the tier) and write the
+  question so it needs no alternative: about what this thing does, not why it
+  beats another. "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.
 
@@ -204,8 +211,9 @@ concept has unmet prerequisites:
 
 `record_attempt` with `format: "mcq"`, `options` as the labels you offered,
 `answer` as the one they picked, `correct` as the right option's label
-verbatim, `option_notes` as the `description` you wrote under each option (same
-order as `options`), and `question` as the **stem only**.
+verbatim, `option_notes` as what you want shown under each option after the answer (same
+order as `options`; the reasoning each option earns, which the neutral
+`description` left out), and `question` as the **stem only**.
 
 `correct` and `option_notes` are what let the learner correct a missed answer
 from its explainer page: the dashboard grades the new pick against `correct`

package/dist/store.js

@@ -339,7 +339,21 @@ export function hasAskedQuestion(db, conceptId, question) {
     const rows = db
         .prepare('SELECT question FROM attempts WHERE concept_id = ? ORDER BY id DESC LIMIT 20')
         .all(conceptId);
-    return rows.some((r) => questionFingerprint(r.question) === target);
+    if (rows.some((r) => questionFingerprint(r.question) === target))
+        return true;
+    // A question thrown out as invalid is spent too: asking it again unchanged
+    // would hand the learner the same broken question.
+    const invalid = db
+        .prepare('SELECT question FROM invalid_questions WHERE concept_id = ? ORDER BY id DESC LIMIT 20')
+        .all(conceptId);
+    return invalid.some((r) => questionFingerprint(r.question) === target);
+}
+/**
+ * Sets a question aside as the tutor's mistake. Writes only `invalid_questions`:
+ * no attempt, no mastery, no gate, so nothing scored can change.
+ */
+export function recordInvalidQuestion(db, q) {
+    db.prepare('INSERT INTO invalid_questions (concept_id, session_id, question, reason) VALUES (?, ?, ?, ?)').run(q.conceptId, q.sessionId, q.question, q.reason);
 }
 /**
  * Has this concept ever been blanked on and taught?