eklavya 1.13.1 → 1.15.0

package/dist/ask.js

@@ -1,48 +1,30 @@
-/** What each tier is actually asking for, so `tier 4` is not a bare number. */
-const TIER_LABEL = {
-    1: 'recall',
-    2: 'mechanism',
-    3: 'judgement',
-    4: 'failure modes',
-    5: 'design',
-};
 /**
- * `null` when nothing should be shown.
+ * The settings line: gone from the question, still stripped from the record.
  *
- * `quiet` is the only suppressor: someone who turned the narration off has
- * already answered this question.
+ * Eklavya used to print a bracketed line above every question naming the dials
+ * that chose it -- `[mode: ambient · focus: concept · level: easy · tier: 2
+ * mechanism]`. It was composed here and pasted into the `question` field of
+ * `AskUserQuestion`, and it existed for a real reason: on `concept` focus a
+ * deliberately transferable question reads as a vague one, and on `easy` a
+ * tier-2 question reads as Eklavya being shallow rather than as a runway the
+ * developer is 37 answers into. Dials nobody can see make a well-pitched
+ * question look like a badly written one.
  *
- * `cadence` is deliberately absent. The question's *arrival* -- mid-task or at
- * the end -- already tells them when Eklavya asks, and a line that repeats what
- * the moment just demonstrated is noise. Everything else is here: the mode, the
- * focus, the level, what the tier is asking for, and how many questions are
- * coming. A learner who cannot see those is answering a question with no idea
- * why it was pitched where it was, or whether four more follow.
+ * The dials now live in the status bar (`statusline.ts`), which meets that
+ * requirement without spending four lines above every stem: ambient state
+ * belongs somewhere ambient, and a bar is on screen when the question arrives
+ * *and* the rest of the time. `askHeader` is deleted rather than deprecated --
+ * a composer nothing calls is a composer that drifts.
+ *
+ * `stripAskHeader` stays, and has to stay for good. Every attempt recorded while
+ * the line existed still has it baked into the stem, and `questionFingerprint`
+ * (`store.ts`) hashes that text to make *never the same question twice* true. A
+ * strip that stopped knowing the old shape would let every one of those rows
+ * change fingerprint at once, and the whole back catalogue would come back round
+ * as brand-new questions.
  */
-export function askHeader({ config, level, pinned, tier, position }) {
-    if (config.quiet)
-        return null;
-    // `learn (topic)` rather than `learn: topic`: the value now sits behind its own
-    // `focus:` label, and two colons in one field read as a nested key.
-    const focus = config.focus === 'learn' && config.focus_topic
-        ? `learn (${config.focus_topic})`
-        : config.focus;
-    const label = TIER_LABEL[tier];
-    const parts = [
-        // `enforced` is the one value with a consequence attached, so it says so.
-        ['mode', config.mode === 'enforced' ? 'enforced (gated)' : config.mode],
-        ['focus', focus],
-        // A pinned level explains itself here or nowhere: without it, questions
-        // simply stop getting harder one day and nothing on screen says why.
-        ['level', pinned ? `${level} (pinned)` : level],
-        ['tier', label ? `${tier} ${label}` : String(tier)],
-    ];
-    if (position && position.total > 1)
-        parts.push(['question', `${position.index} of ${position.total}`]);
-    return `[${parts.map(([key, value]) => `${key}: ${value}`).join(' · ')}]`;
-}
 /**
- * The settings line, matched exactly as `askHeader` composes it.
+ * The settings line, matched exactly as Eklavya used to compose it.
  *
  * Anchored to the start or the end of the stem, one line only, and strict enough
  * about the shape -- mode, focus, level, tier, in that order -- that it can never
@@ -54,11 +36,11 @@ export function askHeader({ config, level, pinned, tier, position }) {
  * questions, and a strip that only knew the labelled shape would leave the old
  * line baked into every one of their fingerprints.
  *
- * It exists because the tutor will eventually record the whole block it
- * displayed, and `question` is what `questionFingerprint` hashes -- a settings
+ * It exists because `question` is what `questionFingerprint` hashes -- a settings
  * line inside the stem would make the same question look brand new every time the
  * level or the focus changed, which is precisely the failure migration 006 kept
- * the options out of the stem to avoid. The brackets are optional in the pattern
+ * the options out of the stem to avoid. Nothing composes the line any more, so
+ * what it now guards is history plus a model that decides to invent one. The brackets are optional in the pattern
  * for the same reason the leading dials group is: older rows do not have them.
  */
 const SETTINGS_LINE_BODY = String.raw `\[?[ \t]*(?:(?:mode:[ \t]*)?(?:off|ambient|enforced(?:[ \t]*\(gated\))?)[ \t]*·[ \t]*)?(?:focus:[ \t]*)?(?:project|concept|learn(?:[ \t]*[:(][^\n·\]]*)?)[ \t]*·[ \t]*(?:level:[ \t]*)?(?:easy|medium|hard)(?:[ \t]*\(pinned\))?[ \t]*·[ \t]*tier:?[ \t]*[1-5][^\n]*`;

package/dist/ask.js.map

@@ -1 +1 @@
-{"version":3,"file":"ask.js","sourceRoot":"","sources":["../src/ask.ts"],"names":[],"mappings":"AAsDA,+EAA+E;AAC/E,MAAM,UAAU,GAA2B;IACzC,CAAC,EAAE,QAAQ;IACX,CAAC,EAAE,WAAW;IACd,CAAC,EAAE,WAAW;IACd,CAAC,EAAE,eAAe;IAClB,CAAC,EAAE,QAAQ;CACZ,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,SAAS,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,EAAkB;IACjF,IAAI,MAAM,CAAC,KAAK;QAAE,OAAO,IAAI,CAAC;IAE9B,gFAAgF;IAChF,oEAAoE;IACpE,MAAM,KAAK,GACT,MAAM,CAAC,KAAK,KAAK,OAAO,IAAI,MAAM,CAAC,WAAW;QAC5C,CAAC,CAAC,UAAU,MAAM,CAAC,WAAW,GAAG;QACjC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC;IAEnB,MAAM,KAAK,GAAG,UAAU,CAAC,IAAI,CAAC,CAAC;IAC/B,MAAM,KAAK,GAAuB;QAChC,0EAA0E;QAC1E,CAAC,MAAM,EAAE,MAAM,CAAC,IAAI,KAAK,UAAU,CAAC,CAAC,CAAC,kBAAkB,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC;QACvE,CAAC,OAAO,EAAE,KAAK,CAAC;QAChB,wEAAwE;QACxE,qEAAqE;QACrE,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC,CAAC,GAAG,KAAK,WAAW,CAAC,CAAC,CAAC,KAAK,CAAC;QAC/C,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC,CAAC,GAAG,IAAI,IAAI,KAAK,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;KACpD,CAAC;IACF,IAAI,QAAQ,IAAI,QAAQ,CAAC,KAAK,GAAG,CAAC;QAAE,KAAK,CAAC,IAAI,CAAC,CAAC,UAAU,EAAE,GAAG,QAAQ,CAAC,KAAK,OAAO,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;IAEvG,OAAO,IAAI,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC,GAAG,GAAG,KAAK,KAAK,EAAE,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC;AAC5E,CAAC;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,kBAAkB,GACtB,MAAM,CAAC,GAAG,CAAA,sQAAsQ,CAAC;AAEnR,MAAM,YAAY,GAAG,IAAI,MAAM,CAAC,MAAM,CAAC,GAAG,CAAA,UAAU,kBAAkB,KAAK,EAAE,GAAG,CAAC,CAAC;AAClF,MAAM,aAAa,GAAG,IAAI,MAAM,CAAC,MAAM,CAAC,GAAG,CAAA,WAAW,kBAAkB,GAAG,EAAE,GAAG,CAAC,CAAC;AAElF,MAAM,UAAU,cAAc,CAAC,QAAgB;IAC7C,OAAO,QAAQ,CAAC,OAAO,CAAC,YAAY,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,aAAa,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;AAC9E,CAAC"}
+{"version":3,"file":"ask.js","sourceRoot":"","sources":["../src/ask.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,kBAAkB,GACtB,MAAM,CAAC,GAAG,CAAA,sQAAsQ,CAAC;AAEnR,MAAM,YAAY,GAAG,IAAI,MAAM,CAAC,MAAM,CAAC,GAAG,CAAA,UAAU,kBAAkB,KAAK,EAAE,GAAG,CAAC,CAAC;AAClF,MAAM,aAAa,GAAG,IAAI,MAAM,CAAC,MAAM,CAAC,GAAG,CAAA,WAAW,kBAAkB,GAAG,EAAE,GAAG,CAAC,CAAC;AAElF,MAAM,UAAU,cAAc,CAAC,QAAgB;IAC7C,OAAO,QAAQ,CAAC,OAAO,CAAC,YAAY,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,aAAa,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;AAC9E,CAAC"}

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.