feat: refresh the coaching notebook only every 10 lessons

Calling update_notebook after every lesson churned the notebook. The
lesson-ready hook now reads the total lesson count from the DB (the source of
truth) and makes step 6 of the directive conditional: at an every-10th-lesson
checkpoint it asks the model to call update_notebook (recording '(updated after
N lessons)'); otherwise it explicitly tells the model NOT to touch the notebook
and names the next checkpoint. The model never counts — the hook does.

Author: UltimaPhoenix

assets/SKILL.md

@@ -446,13 +446,16 @@ Did that land?
 
 ---
 
-### Step 1c — Update the coaching notebook
-
-After feedback is known, fold it into the notebook: call `update_notebook` with the full
-revised `learning-state.md` markdown — note what the user absorbed (`know`) or should
-revisit (`dont_know`), any new recurring pattern, and updated open hypotheses, keeping the
-prior notes. This is what makes the notebook (read from `devcoach://notebook`) drive future
-lesson selection.
+### Step 1c — Update the coaching notebook (only at every-10-lesson checkpoints)
+
+The notebook's observations are refreshed only at **checkpoints — every 10 delivered
+lessons**. The `lesson-ready` hook owns the count and tells you whether the current lesson
+is a checkpoint; do not count yourself. **At a checkpoint**, after feedback is known, call
+`update_notebook` with the full revised `learning-state.md` markdown — note what the user
+absorbed (`know`) or should revisit (`dont_know`), any new recurring pattern, and updated
+open hypotheses, keep the prior notes, and record `(updated after N lessons)`. **Between
+checkpoints, do not touch the notebook.** This keeps `devcoach://notebook` driving future
+lesson selection without churning it on every lesson.
 
 ---
 

plugin/skills/devcoach/SKILL.md

@@ -446,13 +446,16 @@ Did that land?
 
 ---
 
-### Step 1c — Update the coaching notebook
-
-After feedback is known, fold it into the notebook: call `update_notebook` with the full
-revised `learning-state.md` markdown — note what the user absorbed (`know`) or should
-revisit (`dont_know`), any new recurring pattern, and updated open hypotheses, keeping the
-prior notes. This is what makes the notebook (read from `devcoach://notebook`) drive future
-lesson selection.
+### Step 1c — Update the coaching notebook (only at every-10-lesson checkpoints)
+
+The notebook's observations are refreshed only at **checkpoints — every 10 delivered
+lessons**. The `lesson-ready` hook owns the count and tells you whether the current lesson
+is a checkpoint; do not count yourself. **At a checkpoint**, after feedback is known, call
+`update_notebook` with the full revised `learning-state.md` markdown — note what the user
+absorbed (`know`) or should revisit (`dont_know`), any new recurring pattern, and updated
+open hypotheses, keep the prior notes, and record `(updated after N lessons)`. **Between
+checkpoints, do not touch the notebook.** This keeps `devcoach://notebook` driving future
+lesson selection without churning it on every lesson.
 
 ---
 

src/cli/commands.ts

@@ -787,20 +787,43 @@ function cmdOnboardHook(): void {
   );
 }
 
+// The notebook's observations are refreshed only every Nth delivered lesson, not after
+// each one. The hook owns the count (the DB is the source of truth) so the model never
+// has to count.
+const NOTEBOOK_UPDATE_EVERY = 10;
+
 function cmdLessonReady(): void {
   if (stopHookContinuation()) process.exit(0);
   // No DB → no profile yet. Stay silent without creating coaching.db.
   if (!existsSync(db.DB_PATH)) process.exit(0);
-  let allowed: boolean;
+  let result: { allowed: boolean; nextLessonNumber: number };
   try {
-    allowed = db.withConnection((conn) => {
-      if (!db.isOnboardingComplete(conn).knowledge_ready) return false;
-      return coach.checkRateLimit(conn).allowed;
+    result = db.withConnection((conn) => {
+      if (!db.isOnboardingComplete(conn).knowledge_ready) {
+        return { allowed: false, nextLessonNumber: 0 };
+      }
+      return {
+        allowed: coach.checkRateLimit(conn).allowed,
+        nextLessonNumber: Number(coach.getStats(conn).total_lessons ?? 0) + 1,
+      };
     });
   } catch {
     process.exit(0);
   }
-  if (!allowed) process.exit(0);
+  if (!result.allowed) process.exit(0);
+
+  const { nextLessonNumber } = result;
+  const updateDue = nextLessonNumber % NOTEBOOK_UPDATE_EVERY === 0;
+  const nextCheckpoint =
+    Math.ceil(nextLessonNumber / NOTEBOOK_UPDATE_EVERY) * NOTEBOOK_UPDATE_EVERY;
+  const notebookStep = updateDue
+    ? `6. This is lesson #${nextLessonNumber} — a notebook checkpoint (every ${NOTEBOOK_UPDATE_EVERY} ` +
+      "lessons). After log_lesson returns the feedback, call update_notebook with the revised " +
+      "notebook markdown: fold in what the user absorbed or struggled with and any new pattern, " +
+      `keep the prior notes, and record "(updated after ${nextLessonNumber} lessons)".`
+    : `6. Do NOT call update_notebook this time — the notebook is refreshed only every ` +
+      `${NOTEBOOK_UPDATE_EVERY} lessons (next checkpoint at lesson #${nextCheckpoint}). Just ` +
+      "deliver the card and call log_lesson.";
 
   emitBlock(
     "devcoach: a lesson is due for the technical work just completed. Do it now — do not " +
@@ -825,9 +848,7 @@ function cmdLessonReady(): void {
       "summary in their own fields; body = ONLY the prose + the 💡 tip as CLEAN markdown (no " +
       "bands, no '>' quote, no title or 'Category · Level' line). log_lesson then asks the user " +
       "'Did that land?', so the card MUST be printed first.\n" +
-      "6. After log_lesson returns the feedback, call update_notebook with the revised notebook " +
-      "markdown: fold in what the user absorbed or struggled with and any new pattern, keeping " +
-      "the existing notes.\n\n" +
+      `${notebookStep}\n\n` +
       "The rate-limit check is already done by this hook — skip it. Output only the lesson " +
       "card (or nothing). No preamble, no meta-commentary.",
   );

tests/cli.test.ts

@@ -88,6 +88,34 @@ describe("cli", () => {
     expect(lr.out).toContain("update_notebook");
   });
 
+  it("lesson-ready gates the notebook update to every 10 lessons", async () => {
+    const seed = (n: number) =>
+      db.withConnection((c) => {
+        c.exec("DELETE FROM lessons");
+        for (let i = 0; i < n; i++) {
+          db.insertLesson(
+            c,
+            parseLesson({
+              id: `seed-${i}`,
+              timestamp: "2026-01-01T00:00:00Z",
+              topic_id: "python",
+              categories: [],
+              title: "T",
+              level: "mid",
+              summary: "s",
+            }),
+          );
+        }
+        db.upsertKnowledge(c, "python", 4);
+      });
+    seed(5); // next lesson is #6 → not a checkpoint → skip the notebook update
+    expect((await run(["lesson-ready"])).out).toContain("Do NOT call update_notebook");
+    seed(9); // next lesson is #10 → checkpoint → update the notebook
+    const due = await run(["lesson-ready"]);
+    expect(due.out).toContain("notebook checkpoint");
+    expect(due.out).toContain("call update_notebook");
+  });
+
   it("parseStopHookActive: only a payload with stop_hook_active=true short-circuits", () => {
     expect(parseStopHookActive(JSON.stringify({ stop_hook_active: true }))).toBe(true);
     expect(parseStopHookActive(JSON.stringify({ stop_hook_active: false }))).toBe(false);