@xhulz/nina 0.37.0 → 0.38.0

package/src/commands/learn.mjs

@@ -29,7 +29,7 @@ import { HARNESS, legacyHint, slugFor, snapshotsDir } from '../paths.mjs';
 import { localDay, projectRecords } from '../store.mjs';
 import { isLoopBack, runOf } from '../transcripts.mjs';
 import { REQUIRES, byVersion, layerRootFor } from './compose.mjs';
-import { GRADUATION_AT, frontmatter, graduationTarget, list, pillFiles, roleGates, tidyRetired } from './pills.mjs';
+import { GRADUATION_AT, RETIRED, frontmatter, graduationTarget, list, pillFiles, roleGates, tidyRetired } from './pills.mjs';
 import { decodeProjectDir } from './stats.mjs';
 import { snapshot } from './snapshot.mjs';
 import { loadProject, projectGateDir, readLedger, replay } from '../gate.mjs';
@@ -106,6 +106,38 @@ export async function lessons(target) {
   return out;
 }
 
+/** How long after a loop-back's report a dispatch can still be its fix. */
+const SENT_BACK_HOURS = 24;
+
+/**
+ * The stage each loop-back sent work back to: the next one dispatched in its session, after it reported, among
+ * the stages the project's graph routes that verdict of that stage to — or the only one it routes it to.
+ *
+ * @param {object[]} records - Recorded dispatches.
+ * @param {Map<string, Map<string, Map<string, number>>>|null} loops - The graph's capped loop-back edges.
+ * @returns {Map<object, string>} Loop-back record → the stage it sent work back to, where one can be told.
+ */
+export function sentBackTo(records, loops) {
+  const out = new Map();
+  if (!loops) return out;
+  const bySession = new Map();
+  for (const r of records) if (r.session) bySession.set(r.session, [...(bySession.get(r.session) ?? []), r]);
+  for (const rs of bySession.values()) rs.sort((a, b) => String(a.ts).localeCompare(String(b.ts)));
+  for (const r of records) {
+    if (!readable(r.verdict) || !isLoopBack(r.verdict)) continue;
+    const targets = loops.get(r.role)?.get(r.verdict);
+    if (!targets || targets.size === 0) continue;
+    const back = String(r.result_ts ?? r.ts);
+    // Within a day of the report: one project ran six weeks in one session, and the next architect there could be
+    // five days on, with no telling it was this loop-back's fix.
+    const within = (x) => Date.parse(x.ts) - Date.parse(back) <= SENT_BACK_HOURS * 3_600_000;
+    const next = (bySession.get(r.session) ?? []).find((x) => String(x.ts) > back && within(x) && targets.has(x.role));
+    const to = next?.role ?? (targets.size === 1 ? [...targets.keys()][0] : null);
+    if (to) out.set(r, to);
+  }
+  return out;
+}
+
 /**
  * Roles that looped back often enough, since their newest lesson, that one is overdue.
  *
@@ -118,9 +150,13 @@ export async function lessons(target) {
  *   lesson: a count alone sends them digging through weeks of transcripts, which is how a warning
  *   becomes one more thing to ignore.
  */
-export function overdue(records, known, now = new Date(), days = CAPTURE_DAYS) {
+export function overdue(records, known, now = new Date(), days = CAPTURE_DAYS, owners = new Map()) {
   const cutoff = day(new Date(now.getTime() - days * 86_400_000).toISOString());
-  const roles = [...new Set(records.map((r) => r.role).filter(Boolean))];
+  // A loop-back is the lesson of the stage it sent work back to, where that is known (`sentBackTo`): charged
+  // to the stage that gave the verdict, the reviewer owed the implementer's lessons, and only a pill naming
+  // every checker in its applies_to ever settled the count.
+  const ownerOf = (r) => owners.get(r) ?? r.role;
+  const roles = [...new Set(records.map(ownerOf).filter(Boolean))];
   const out = [];
   for (const role of roles) {
     // A retired lesson was still written down: it retired because its rule moved into the harness,
@@ -138,7 +174,7 @@ export function overdue(records, known, now = new Date(), days = CAPTURE_DAYS) {
     // thing capture exists to catch.
     const at = floor === newest ? taught?.at ?? null : null;
     const after = (r) => day(r.ts) > floor || (at !== null && day(r.ts) === floor && String(r.ts) > at);
-    const loops = records.filter((r) => r.role === role && readable(r.verdict) && isLoopBack(r.verdict) && after(r));
+    const loops = records.filter((r) => ownerOf(r) === role && readable(r.verdict) && isLoopBack(r.verdict) && after(r));
     if (loops.length >= CAPTURE_AT) {
       const recent = loops
         .sort((a, b) => String(b.ts).localeCompare(String(a.ts)))
@@ -177,50 +213,129 @@ export function applied(records, known) {
   };
 }
 
+/** How many days either side of a lesson's date its role is measured over: the same on both sides. */
+const VERIFY_DAYS = 14;
+
+/** A day as `YYYY-MM-DD`, moved by some days. */
+const shift = (date, days) => new Date(Date.parse(`${date}T12:00:00Z`) + days * 86_400_000).toISOString().slice(0, 10);
+
 /**
- * The loop-back rate of a lesson's roles before it was written and after.
+ * The 95% Wilson interval of a share.
  *
- * Not proof — the work changes too, and a small sample swings — but without it the pipeline
- * cannot tell a lesson that helped from one that did not, even in principle.
+ * @param {number} k - How many.
+ * @param {number} n - Out of how many.
+ * @returns {[number, number]}
+ */
+export function wilson(k, n) {
+  if (n === 0) return [0, 1];
+  const z = 1.96;
+  const p = k / n;
+  const d = 1 + (z * z) / n;
+  const c = p + (z * z) / (2 * n);
+  const m = z * Math.sqrt((p * (1 - p)) / n + (z * z) / (4 * n * n));
+  return [(c - m) / d, (c + m) / d];
+}
+
+/**
+ * How often a lesson's stage had its work sent back before the lesson was written and after, stage by stage.
+ *
+ * It measured the rate of the stage's own verdicts. For a lesson about the implementer that was its BLOCKED
+ * rate, mostly unreadable, while the reviewer's rejections of its work — what the lesson was about — went to
+ * the reviewer's account; a lesson for several stages pooled them and read one model; and "before" and
+ * "after" were all of history either side, so a lesson written in a project's first days had nothing to
+ * compare. Now a stage is read on its own, over the same fourteen days either side, as the share of its
+ * rounds that a later stage sent back to it (`sentBackTo`), beside the same share for every other stage the
+ * graph sends work back to. A change is called only where the two intervals do not overlap. Not proof — the
+ * work changes too — but a number where one can be had, and the reason where it cannot.
  *
  * @param {object[]} records - Recorded dispatches.
  * @param {Awaited<ReturnType<typeof lessons>>} known - The project's pills.
- * Each comes with a control: every OTHER role, split at the same date. A lesson is written because
- * its role just started failing, so "after" is partly the same bad patch; and the whole pipeline's
- * rate moves with the work. The control does not remove either, but it shows whether the lesson's
- * roles moved differently from everything else, which the lesson's own numbers cannot.
- *
- * @returns {{rel: string, date: string, on: string|null, comparable: boolean, was?: string, before?: {n: number, loops: number}, after?: {n: number, loops: number}, control?: {before: {n: number, loops: number}, after: {n: number, loops: number}}}[]}
+ * @param {{owners?: Map<object, string>, targets?: Set<string>|null}} [graph] - Who each loop-back sent work
+ *   back to, and the stages the graph sends work back to at all.
+ * @returns {{rel: string, date: string, role: string, comparable: boolean, why?: string, on?: string|null,
+ *   was?: string, before?: {n: number, loops: number}, after?: {n: number, loops: number},
+ *   change?: 'lower'|'higher'|'unclear', control?: {before: {n: number, loops: number}, after: {n: number, loops: number}}}[]}
  */
-export function verified(records, known) {
+export function verified(records, known, { owners = new Map(), targets = null } = {}) {
   const out = [];
+  const ownerOf = (r) => owners.get(r) ?? r.role;
+  const sentBack = records.filter((r) => readable(r.verdict) && isLoopBack(r.verdict));
+  const ranOn = (r) => (r.usage_model ? `${r.usage_model}${r.effort ? ` · ${r.effort}` : ''}` : null);
   for (const lesson of known.filter((l) => l.date)) {
-    const rate = (rs, pick) => {
-      const s = rs.filter(pick);
-      return { n: s.length, loops: s.filter((r) => isLoopBack(r.verdict)).length };
-    };
-    const all = records.filter((r) => lesson.roles.includes(r.role) && readable(r.verdict));
-    const others = records.filter((r) => r.role && !lesson.roles.includes(r.role) && readable(r.verdict));
-    const pre = (r) => day(r.ts) < lesson.date;
-    const post = (r) => day(r.ts) > lesson.date;
-    if (rate(all, pre).n < VERIFY_MIN || rate(all, post).n < VERIFY_MIN) continue;
-    // Read on one model and effort level: the one the roles ran on most after the lesson. A lesson written
-    // the week a role moved to a stricter model read as making it worse — one project's reviewer went from
-    // 2% to 29% "after" a lesson, and from Sonnet to Opus in the same days. Where the roles ran on it too
-    // little before the lesson, the two sides are not comparable, and that is said rather than a number.
-    const ranOn = (r) => (r.usage_model ? `${r.usage_model}${r.effort ? ` · ${r.effort}` : ''}` : null);
-    const tally = new Map();
-    for (const r of all.filter(post)) if (ranOn(r)) tally.set(ranOn(r), (tally.get(ranOn(r)) ?? 0) + 1);
-    const on = [...tally].sort((x, y) => y[1] - x[1])[0]?.[0] ?? null;
-    const mine = on ? all.filter((r) => ranOn(r) === on) : all;
-    const before = rate(mine, pre);
-    const after = rate(mine, post);
-    if (before.n < VERIFY_MIN || after.n < VERIFY_MIN) {
-      const was = [...new Set(all.filter(pre).map(ranOn).filter(Boolean))].join(', ') || 'no recorded model';
-      out.push({ rel: lesson.rel, date: lesson.date, on, was, comparable: false });
-      continue;
+    const from = shift(lesson.date, -VERIFY_DAYS);
+    const until = shift(lesson.date, VERIFY_DAYS);
+    const pre = (r) => day(r.ts) >= from && day(r.ts) < lesson.date;
+    const post = (r) => day(r.ts) > lesson.date && day(r.ts) <= until;
+    for (const role of lesson.roles) {
+      const base = { rel: lesson.rel, date: lesson.date, role };
+      if (targets && !targets.has(role)) {
+        out.push({ ...base, comparable: false, why: `nothing in the graph sends work back to ${role}` });
+        continue;
+      }
+      const rounds = records.filter((r) => r.role === role && readable(r.verdict));
+      const backs = sentBack.filter((r) => ownerOf(r) === role);
+      const side = (pick, mine) => {
+        const n = mine.filter(pick).length;
+        return { n, loops: Math.min(n, backs.filter(pick).length) };
+      };
+      if (side(pre, rounds).n < VERIFY_MIN || side(post, rounds).n < VERIFY_MIN) {
+        const [b, a] = [side(pre, rounds).n, side(post, rounds).n];
+        out.push({ ...base, comparable: false, why: `too few rounds of ${role} either side (${b} before, ${a} after, in ${VERIFY_DAYS} days each)` });
+        continue;
+      }
+      // Read on the model and effort the stage ran on most after the lesson: one written the week its stage moved
+      // to a stricter model read as making it worse — one reviewer went from 2% to 29%, and from Sonnet to Opus.
+      const tally = new Map();
+      for (const r of rounds.filter(post)) if (ranOn(r)) tally.set(ranOn(r), (tally.get(ranOn(r)) ?? 0) + 1);
+      const on = [...tally].sort((x, y) => y[1] - x[1])[0]?.[0] ?? null;
+      const mine = on ? rounds.filter((r) => ranOn(r) === on) : rounds;
+      const before = side(pre, mine);
+      const after = side(post, mine);
+      if (before.n < VERIFY_MIN || after.n < VERIFY_MIN) {
+        const was = [...new Set(rounds.filter(pre).map(ranOn).filter(Boolean))].join(', ') || 'no recorded model';
+        out.push({ ...base, on, was, comparable: false, why: `${role} ran on ${on} after it, and before it on ${was}` });
+        continue;
+      }
+      const [bLo, bHi] = wilson(before.loops, before.n);
+      const [aLo, aHi] = wilson(after.loops, after.n);
+      const change = aHi < bLo ? 'lower' : aLo > bHi ? 'higher' : 'unclear';
+      const others = [...(targets ?? new Set(sentBack.map(ownerOf)))].filter((x) => x !== role);
+      const theirs = records.filter((r) => others.includes(r.role) && readable(r.verdict));
+      const otherBacks = sentBack.filter((r) => others.includes(ownerOf(r)));
+      const control = (pick) => ({ n: theirs.filter(pick).length, loops: Math.min(theirs.filter(pick).length, otherBacks.filter(pick).length) });
+      out.push({ ...base, comparable: true, on, before, after, change, control: { before: control(pre), after: control(post) } });
     }
-    out.push({ rel: lesson.rel, date: lesson.date, on, comparable: true, before, after, control: { before: rate(others, pre), after: rate(others, post) } });
+  }
+  return out;
+}
+
+/**
+ * Lessons that came back after the rule they graduated into reached this project: their newest request is
+ * closed, and the pill has been counted more times since it was filed. The pill is retired by then, and
+ * nothing read a retired pill's count — one project's lesson graduated twice and was learned a third time,
+ * while two retired pills went from 3 to 8 and from 5 to 11 without a word to anyone.
+ *
+ * @param {Awaited<ReturnType<typeof lessons>>} known - The project's pills, retired ones included.
+ * @param {Awaited<ReturnType<typeof filedRequests>>} filed - Its requests.
+ * @returns {{lesson: object, request: object, recurred: number}[]}
+ */
+export function relapsed(known, filed) {
+  // A pill with a request still open is waiting on the harness, whatever the dates say. Of the closed ones, the
+  // newest by date — and on one date the one that counted most, since a reopening is filed after what it reopens;
+  // by the order a directory lists them, a reopening filed the same day read as older, and was filed again.
+  const open = new Set(filed.filter((r) => r.status === 'open').map((r) => r.pill));
+  const newest = new Map();
+  for (const r of filed) {
+    if (!r.pill || r.status !== 'closed' || open.has(r.pill)) continue;
+    const had = newest.get(r.pill);
+    if (!had || r.date > had.date || (r.date === had.date && Number(r.occurrences) > Number(had.occurrences))) newest.set(r.pill, r);
+  }
+  const out = [];
+  for (const [pill, request] of newest) {
+    const shelved = pill.replace(/^\.claude\/pills\//, `.claude/pills/${RETIRED}/`);
+    const lesson = known.find((l) => l.rel === pill || l.rel === shelved);
+    const then = Number(request.occurrences);
+    if (lesson && Number.isFinite(then) && lesson.occurrences > then) out.push({ lesson, request, recurred: lesson.occurrences - then });
   }
   return out;
 }
@@ -250,7 +365,17 @@ export async function filedRequests(target) {
   const out = [];
   for (const f of (await readdir(dir).catch(() => [])).filter((f) => f.endsWith('.md'))) {
     const fields = frontmatter(await readFile(join(dir, f), 'utf8')) ?? {};
-    out.push({ file: f, id: f.replace(/\.md$/, ''), status: fields.status ?? '', pill: fields.pill ?? '', target: fields.target ?? '', date: fields.date ?? '' });
+    out.push({
+      file: f,
+      id: f.replace(/\.md$/, ''),
+      status: fields.status ?? '',
+      pill: fields.pill ?? '',
+      target: fields.target ?? '',
+      date: fields.date ?? '',
+      occurrences: fields.occurrences ?? '',
+      rule_in: fields.rule_in ?? '',
+      answered_in: fields.answered_in ?? '',
+    });
   }
   return out;
 }
@@ -474,15 +599,23 @@ async function deepReport(target, records, known, argv) {
  * @param {Awaited<ReturnType<typeof lessons>>[number]} lesson - A lesson that names its roles.
  * @returns {Promise<{file: string, layer: string, why: string}>}
  */
-async function fileRequest(target, profile, layerRoot, lesson) {
+async function fileRequest(target, profile, layerRoot, lesson, { reopens = null, recurred = 0 } = {}) {
   const target_ = graduationTarget(lesson.roles, await roleGates(layerRoot));
   const date = localDay(new Date().toISOString());
+  // Asked about the pill where it was learned, a retired one included: its request names that path.
+  const pill = reopens?.pill ?? lesson.rel;
   // The directory separator becomes `__`, so `reviewer/a.b.md` and `reviewer-a/b.md` stay two
   // names — flattening both `/` and `.` to `-` gave them the same one.
-  const name = lesson.rel.replace(/^\.claude\/pills\//, '').replace(/\.md$/, '').replace(/\//g, '__');
+  const name = pill.replace(/^\.claude\/pills\//, '').replace(/\.md$/, '').replace(/\//g, '__');
   const dir = join(target, HARNESS, 'requests');
-  const file = `${date}-${name}.md`;
+  // Never over a request already written: the same lesson can be sent more than once on one day.
+  let file = `${date}-${name}.md`;
+  for (let n = 1; existsSync(join(dir, file)); n += 1) file = `${date}-${name}-again${n > 1 ? `-${n}` : ''}.md`;
   await mkdir(dir, { recursive: true });
+  const heading = reopens
+    ? `**A lesson that graduated into \`${reopens.rule_in || reopens.target}\` in ${reopens.answered_in || 'a release'} came back ${recurred} time(s) since** — ` +
+      `the rule did not hold here. It reopens ${HARNESS}/requests/${reopens.file}.`
+    : `**A lesson this project has learned ${lesson.occurrences} time(s), proposed as a rule in \`${target_.layer}\`** — ${target_.why}.`;
   await writeFile(
     join(dir, file),
     [
@@ -491,12 +624,13 @@ async function fileRequest(target, profile, layerRoot, lesson) {
       'status: open',
       `date: ${date}`,
       `core: ${profile.core}`,
-      `target: ${target_.layer}`,
-      `pill: ${lesson.rel}`,
+      `target: ${reopens?.target || target_.layer}`,
+      `pill: ${pill}`,
       `occurrences: ${lesson.occurrences}`,
+      ...(reopens ? [`reopens: ${reopens.file}`, `rule_in: ${oneLine(reopens.rule_in)}`] : []),
       '---',
       '',
-      `**A lesson this project has learned ${lesson.occurrences} time(s), proposed as a rule in \`${target_.layer}\`** — ${target_.why}.`,
+      heading,
       '',
       `Learned against core ${profile.core}. The rule lands in a release of the harness, and the`,
       '`nina upgrade` that installs that release closes this request and retires the pill — not before.',
@@ -504,6 +638,7 @@ async function fileRequest(target, profile, layerRoot, lesson) {
       lesson.body,
       '',
     ].join('\n'),
+    { flag: 'wx' },
   );
   return { file, layer: target_.layer, why: target_.why };
 }
@@ -589,7 +724,11 @@ export async function learn(argv, ctx) {
   }
   if (argv.includes('--close')) return close(target, argv[argv.indexOf('--close') + 1] ?? '');
 
-  const late = overdue(records, known, new Date(), days);
+  // Who each loop-back sent work back to, read off the project's own graph.
+  const loops = loadProject(target)?.loops ?? null;
+  const owners = sentBackTo(records, loops);
+  const targets = loops ? new Set([...loops.values()].flatMap((byToken) => [...byToken.values()].flatMap((to) => [...to.keys()]))) : null;
+  const late = overdue(records, known, new Date(), days, owners);
   const filed = await filedRequests(target);
   const owed = unfiled(known, filed);
 
@@ -614,20 +753,22 @@ export async function learn(argv, ctx) {
     // once. The per-line actions matter too: one hint for the whole detector told a project to
     // "write the lesson" when the lesson was written three times over and only needed sending.
     const sent = [];
-    const stuck = owed
-      .filter((l) => l.roles.length === 0)
-      .map((lesson) => ({ lesson, why: 'names no role in applies_to, so no layer can take it', fix: 'fix its frontmatter — `nina pills` says what is wrong' }));
+    // A lesson that came back after its rule shipped goes back to the harness the way it went the first time.
+    const outgoing = [...owed.map((lesson) => ({ lesson })), ...relapsed(known, filed).map(({ lesson, request, recurred }) => ({ lesson, reopens: request, recurred }))];
+    const stuck = outgoing
+      .filter((o) => o.lesson.roles.length === 0)
+      .map((o) => ({ ...o, why: 'names no role in applies_to, so no layer can take it', fix: 'fix its frontmatter — `nina pills` says what is wrong' }));
     // Sent from the Stop hook, a request was news only the person heard: its one line said the model would
     // be told, and by the next message the lesson was no longer owed, so nothing told it. It is sent by the
     // run that hands its findings to the model, or by hand; the Stop hook says it is about to go.
-    const due = beforeModel() ? owed.filter((l) => l.roles.length > 0) : [];
-    for (const lesson of beforeModel() ? [] : owed.filter((l) => l.roles.length > 0)) {
+    const due = beforeModel() ? outgoing.filter((o) => o.lesson.roles.length > 0) : [];
+    for (const o of beforeModel() ? [] : outgoing.filter((o) => o.lesson.roles.length > 0)) {
       // A detector that throws is reported as one that could not run, every turn, and takes the
       // rest of its findings with it — so a request that cannot be written is a finding instead.
       try {
-        sent.push({ lesson, ...(await fileRequest(target, profile, resolved.dir, lesson)) });
+        sent.push({ ...o, ...(await fileRequest(target, profile, resolved.dir, o.lesson, o)) });
       } catch (error) {
-        stuck.push({ lesson, why: `could not be written to ${HARNESS}/requests/ — ${error.message}`, fix: `make it writable, or send it by hand: \`nina learn --graduate ${lesson.rel}\`` });
+        stuck.push({ ...o, why: `could not be written to ${HARNESS}/requests/ — ${error.message}`, fix: `make it writable, or send it by hand: \`nina learn --graduate ${o.lesson.rel}\`` });
       }
     }
     if (late.length === 0 && sent.length === 0 && due.length === 0 && stuck.length === 0 && !exported) {
@@ -643,15 +784,19 @@ export async function learn(argv, ctx) {
       for (const r of o.recent) console.log(`      ${r.ts}  ${r.desc || '(no description)'}  session ${r.session}`);
       console.log('    → ask of each whether it would happen again; if so, write the pill, or bump `occurrences` and `last_seen` on the one that already says it');
     }
+    const what = (o) =>
+      o.reopens
+        ? `${o.lesson.rel} came back ${o.recurred} time(s) after its rule shipped in ${o.reopens.answered_in || 'a release'} (${o.reopens.rule_in || o.reopens.target})`
+        : `${o.lesson.rel} has recurred ${o.lesson.occurrences} times`;
     for (const s of sent) {
-      console.log(`  ${s.lesson.rel} has recurred ${s.lesson.occurrences} times — sent to the harness as ${HARNESS}/requests/${s.file}, proposing a rule in ${s.layer}`);
+      console.log(`  ${what(s)} — sent to the harness as ${HARNESS}/requests/${s.file}${s.reopens ? ', reopening the rule' : `, proposing a rule in ${s.layer}`}`);
       console.log('    → commit it with the pill; nothing else is owed here. `nina upgrade` to the release that answers it closes it and retires the pill');
     }
-    for (const lesson of due) {
-      console.log(`  ${lesson.rel} has recurred ${lesson.occurrences} times — it goes to the harness as a request before your next message`);
+    for (const o of due) {
+      console.log(`  ${what(o)} — it goes to the harness as a request before your next message`);
     }
     for (const s of stuck) {
-      console.log(`  ${s.lesson.rel} has recurred ${s.lesson.occurrences} times and ${s.why}`);
+      console.log(`  ${what(s)} and ${s.why}`);
       console.log(`    → ${s.fix}`);
     }
     if (exported) console.log(`  ${exported}`);
@@ -673,7 +818,7 @@ export async function learn(argv, ctx) {
   const ready = active.filter((l) => l.occurrences >= GRADUATION_AT);
   const open = filed.filter((r) => r.status === 'open');
   const use = applied(records, known);
-  const checks = verified(records, known);
+  const checks = verified(records, known, { owners, targets });
   const span = records.length ? `${day(records[0].ts)} → ${day(records.at(-1).ts)}` : '';
 
   console.log(`\n  learning — core ${profile.core}\n`);
@@ -703,19 +848,28 @@ export async function learn(argv, ctx) {
   );
   for (const l of ready.filter((l) => owed.includes(l))) console.log(`            not sent yet: ${l.rel} — the next \`harness:check\` sends it`);
   for (const r of open) console.log(`            open since ${r.date}: ${r.pill} → ${r.target}. \`nina upgrade\` to the release that answers it closes it`);
-  if (checks.length === 0) console.log(`  verify    no lesson has ${VERIFY_MIN}+ readable verdicts on both sides of its date yet`);
-  checks.forEach((c, i) => {
-    const head = `  ${i === 0 ? 'verify  ' : '        '}  ${c.rel.replace(/^\.claude\/pills\//, '')} (${c.date})`;
-    if (!c.comparable) {
-      console.log(`${head}: not comparable — the role ran on ${c.on} after it, and before it on ${c.was}`);
-      return;
-    }
+  for (const r of relapsed(known, filed)) {
+    console.log(`            ✗ ${r.lesson.rel} came back ${r.recurred} time(s) after its rule shipped in ${r.request.answered_in || 'a release'} — the rule did not hold; \`harness:check\` reopens it`);
+  }
+  const measured = checks.filter((c) => c.comparable);
+  const unmeasured = checks.filter((c) => !c.comparable);
+  if (measured.length === 0) console.log(`  verify    no lesson could be measured yet — ${VERIFY_MIN}+ rounds of its stage on the same model are needed in the ${VERIFY_DAYS} days either side of its date`);
+  measured.forEach((c, i) => {
+    const said = { lower: 'sent back less since', higher: 'sent back more since', unclear: 'no clear change' }[c.change];
     console.log(
-      `${head}${c.on ? `, on ${c.on}` : ''}: ` +
-        `${pct(c.before.loops, c.before.n)} → ${pct(c.after.loops, c.after.n)} loop-back (n ${c.before.n} → ${c.after.n}); ` +
-        `every other role ${pct(c.control.before.loops, c.control.before.n)} → ${pct(c.control.after.loops, c.control.after.n)}`,
+      `  ${i === 0 ? 'verify  ' : '        '}  ${c.rel.replace(/^\.claude\/pills\//, '')} (${c.date}) · ${c.role}${c.on ? `, on ${c.on}` : ''}: ` +
+        `${pct(c.before.loops, c.before.n)} → ${pct(c.after.loops, c.after.n)} of its rounds sent back (n ${c.before.n} → ${c.after.n}) — ${said}; ` +
+        `the other stages ${pct(c.control.before.loops, c.control.before.n)} → ${pct(c.control.after.loops, c.control.after.n)}`,
     );
   });
+  if (unmeasured.length > 0) {
+    const reasons = new Map();
+    for (const c of unmeasured) {
+      const reason = c.why.startsWith('too few') ? 'too few rounds either side' : c.why.startsWith('nothing') ? 'a stage nothing sends work back to' : 'a stage that changed model across its date';
+      reasons.set(reason, (reasons.get(reason) ?? 0) + 1);
+    }
+    console.log(`            ${unmeasured.length} more could not be measured: ${[...reasons].map(([why, n]) => `${n} ${why}`).join(', ')}`);
+  }
   // The loops the lessons are about, as the gate counted them — beside the lessons, because a loop the
   // gate held is a lesson waiting to be asked for.
   const since = new Date(Date.now() - days * 86_400_000).toISOString();
@@ -858,7 +1012,8 @@ export async function requests(argv = [], ctx = { root: '.' }) {
     }
     // The maintainer's side of graduation used to be "run nina requests and remember to" — the one
     // step with nothing to prompt it. This repo's own harness:check runs this every turn.
-    for (const r of unanswered) console.log(`  ${r.fields.date}  ${r.fields.pill} → ${r.fields.target} (core ${r.fields.core})  ${where(r)}`);
+    const reopened = (r) => (r.fields.reopens ? ` — reopens a rule that did not hold (${r.fields.rule_in || r.fields.target})` : '');
+    for (const r of unanswered) console.log(`  ${r.fields.date}  ${r.fields.pill} → ${r.fields.target} (core ${r.fields.core})${reopened(r)}  ${where(r)}`);
     for (const r of unreleased) console.log(`  answered, not released: ${r.id}`);
     console.log(
       `requests: ${[
@@ -881,7 +1036,7 @@ export async function requests(argv = [], ctx = { root: '.' }) {
       : working[r.id]
         ? 'answered in the working core — cut a release to carry it'
         : `waiting — nina requests --answer ${r.id} --in <layer file>, or --decline … --why …`;
-    console.log(`  ${r.fields.date}  ${r.fields.target.padEnd(20)} core ${r.fields.core}  ${r.fields.pill}`);
+    console.log(`  ${r.fields.date}  ${r.fields.target.padEnd(20)} core ${r.fields.core}  ${r.fields.pill}${r.fields.reopens ? `  — reopens a rule that did not hold (${r.fields.rule_in || r.fields.target})` : ''}`);
     console.log(`              ${where(r)}`);
     console.log(`              ${state}`);
   }

package/src/commands/pills.mjs

@@ -81,14 +81,17 @@ const CITATION = /^[^\s:]+(:\d+)?$/;
  * @param {string} text - The whole file.
  * @returns {Record<string, string> | null} The fields, or `null` when there is no frontmatter.
  */
-export function frontmatter(text) {
+export function frontmatter(raw) {
+  // Saved on Windows, a pill read as having no frontmatter at all; and `occurrences: 4  # seen in 5.1` read as
+  // 1 — a comment after a value is YAML's, and ends at the value.
+  const text = String(raw ?? '').replace(/^\uFEFF/, '').replace(/\r\n?/g, '\n');
   if (!text.startsWith('---\n')) return null;
   const end = text.indexOf('\n---', 3);
   if (end === -1) return null;
   const fields = {};
   for (const line of text.slice(4, end + 1).split('\n')) {
     const field = /^([a-z_]+):\s*(.*)$/.exec(line);
-    if (field) fields[field[1]] = field[2].trim();
+    if (field) fields[field[1]] = field[2].replace(/\s+#.*$/, '').trim();
   }
   return fields;
 }
@@ -308,6 +311,9 @@ export function validate(pill, text, roles, today) {
     problems.push(`${label} has last_seen "${fields.last_seen}" — expected YYYY-MM-DD`);
   } else if (fields.last_seen && fields.date && fields.last_seen < fields.date) {
     problems.push(`${label} was last seen ${fields.last_seen}, before it was first learned (${fields.date})`);
+  } else if (fields.last_seen && fields.last_seen > today) {
+    // The capture detector counts loop-backs after a stage's newest lesson: one seen in the future silenced it.
+    problems.push(`${label} was last seen ${fields.last_seen}, which is in the future — no loop-back of its stage would be counted until then`);
   }
   if (fields.occurrences !== undefined && !/^[1-9]\d*$/.test(fields.occurrences)) {
     problems.push(`${label} has occurrences "${fields.occurrences}" — expected a positive whole number`);
@@ -384,6 +390,15 @@ export async function pills(argv, ctx) {
     /* without a profile the candidate is still worth naming; only its target is unknown */
   }
 
+  // What this project has already asked the harness for, by pill: a request is how a lesson leaves a project.
+  const requested = new Map();
+  for (const f of (await readdir(join(target, HARNESS, 'requests')).catch(() => [])).filter((f) => f.endsWith('.md'))) {
+    const fields = frontmatter(await readFile(join(target, HARNESS, 'requests', f), 'utf8').catch(() => ''));
+    if (fields?.pill) requested.set(fields.pill, fields);
+  }
+  /** Every stage a pill was ever written for, by its directory or its applies_to, retired ones included. */
+  const taught = new Set();
+
   const changedCache = new Map();
   const candidates = [];
   let resolved = 0;
@@ -393,7 +408,9 @@ export async function pills(argv, ctx) {
     const result = validate(pill, await readFile(pill.path, 'utf8'), roles, today);
     problems.push(...result.problems);
     notes.push(...result.notes);
-    if (result.uncited) uncited += 1;
+    if (pill.dir && pill.dir !== 'shared' && pill.dir !== RETIRED) taught.add(pill.dir);
+    for (const role of list(result.fields?.applies_to)) taught.add(role);
+    if (result.uncited && result.fields?.status !== 'retired') uncited += 1;
     if (result.fields?.status === 'retired') retired += 1;
     else active.push({ ...pill, date: result.fields?.date });
 
@@ -429,23 +446,29 @@ export async function pills(argv, ctx) {
   if (cited > 0) notes.push(`${resolved} of ${cited} citation(s) still resolve`);
 
   // A lesson learned three times is not a correction any more; it is a rule nobody wrote down.
+  // A project cannot write the harness, and a pill retired before the release that carries its rule arrives
+  // leaves the lesson nowhere: it goes as a request, and waits.
   for (const c of candidates) {
-    const target = gates && c.applies.length > 0 ? graduationTarget(c.applies, gates) : null;
+    const home = gates && c.applies.length > 0 ? graduationTarget(c.applies, gates) : null;
+    const asked = requested.get(`.claude/pills/${c.label}`);
     notes.push(
       `${c.label} has recurred ${c.seen} times — that is a rule, not a pill.` +
-        (target ? ` Its home is ${target.layer}, since ${target.why}.` : '') +
-        ' Write it there, then set this pill retired.',
+        (home ? ` Its home is ${home.layer}, since ${home.why}.` : '') +
+        (asked
+          ? ` It went to the harness as a request on ${asked.date} (${asked.status}); the \`nina upgrade\` to the release that answers it retires this pill.`
+          : ' `harness:check` sends it to the harness as a request, or `nina learn --graduate` does now; keep it active until the release that answers it retires it.'),
     );
   }
 
   // One line, not one per pill: what matters is how much of the corpus a staleness check
   // could ever reach, and naming eleven files says that worse than counting them.
   if (uncited > 0) {
-    notes.push(`${uncited} of ${files.length} pill(s) cite no code, so staleness cannot be checked mechanically`);
+    notes.push(`${uncited} of ${active.length} active pill(s) cite no code, so staleness cannot be checked mechanically`);
   }
 
-  const covered = new Set(files.flatMap((p) => (p.dir && p.dir !== 'shared' ? [p.dir] : [])));
-  const uncovered = roles.filter((r) => !covered.has(r));
+  // Read off each pill's applies_to as well as its directory: counted by directory, a project whose lessons were
+  // all shared was told none had ever been written for the stages they named.
+  const uncovered = roles.filter((r) => !taught.has(r));
   if (uncovered.length > 0 && files.length > 0) {
     notes.push(`no pill has ever been written for ${uncovered.join(', ')}`);
   }

package/src/commands/stats.mjs

@@ -5,10 +5,10 @@
  * can be judged by whether it ever stops anything rather than by whether it is in the
  * table.
  *
- * It also reports the one rule that governs the harness's own improvement. The router
- * writes a pill on every loop-back, and nothing ever checked whether that happened — so
- * the rule ran at a fraction of its declared rate for months, invisibly, while the
- * loop-backs it was supposed to harvest were being counted right here.
+ * It also reports the one rule that governs the harness's own improvement: every loop-back is looked
+ * at for a lesson. Nothing ever checked whether that happened — the rule ran at a fraction of its
+ * declared rate for months, invisibly, while the loop-backs it was supposed to harvest were being
+ * counted right here.
  */
 
 import { amber, bar, bold, dim, heading, note, pink, stacked } from '../look.mjs';

package/src/deep.mjs

@@ -152,6 +152,28 @@ export function reducePrompt(causes, known) {
   ].join('\n');
 }
 
+/**
+ * The causes a batch's answer adds: one per report the batch held, the first the answer gave for it. Checked
+ * against the causes already taken, a ref an answer repeated was taken twice, and the count of reports given
+ * no cause came out short by as many.
+ *
+ * @param {{ref: string}[]} taken - Causes from earlier batches.
+ * @param {{ref: string}[]} batch - The reports this answer is about.
+ * @param {unknown[]} answered - What the answer gave.
+ * @returns {{ref: string, cause: string}[]}
+ */
+export function newCauses(taken, batch, answered) {
+  const refs = new Set(batch.map((r) => r.ref));
+  const seen = new Set(taken.map((c) => c.ref));
+  const out = [];
+  for (const c of Array.isArray(answered) ? answered : []) {
+    if (!c || !refs.has(c.ref) || seen.has(c.ref) || typeof c.cause !== 'string') continue;
+    seen.add(c.ref);
+    out.push(c);
+  }
+  return out;
+}
+
 /**
  * Reads the loop-backs and says what they were about.
  *
@@ -178,9 +200,7 @@ export async function deepLearn({ records, known, projectDir, since, model, api,
     made += 1;
     if (failed || !Array.isArray(answer?.causes)) return stop(failed ?? 'the map answer was not the shape asked for');
     cost += spent;
-    const refs = new Set(batch.map((r) => r.ref));
-    const seen = new Set(causes.map((c) => c.ref));
-    causes.push(...answer.causes.filter((c) => refs.has(c.ref) && !seen.has(c.ref) && typeof c.cause === 'string'));
+    causes.push(...newCauses(causes, batch, answer.causes));
   }
   progress('reduce');
   const { answer, cost: spent, failed } = ask(reducePrompt(causes, known), REDUCE_SCHEMA, options);
@@ -189,7 +209,9 @@ export async function deepLearn({ records, known, projectDir, since, model, api,
   cost += spent;
   // Believed only as far as it can be checked: refs that were read, and pills that exist.
   const read = new Set(causes.map((c) => c.ref));
-  const pills = new Set(known.map((p) => p.rel));
+  // Only an active pill covers a cause here: the grouping is shown no retired one, and one named is a lesson that
+  // left this project for the harness, not one this project still holds.
+  const pills = new Set(known.filter((p) => !p.retired).map((p) => p.rel));
   const clusters = answer.clusters
     .map((c) => ({
       ...c,

package/src/gate.mjs

@@ -60,6 +60,7 @@ import { fileURLToPath } from 'node:url';
 import { TERMINALS, declaredTokens, parseGraph } from './graph.mjs';
 import { gateDir, slugFor } from './paths.mjs';
 import { declaredIssues, isLoopBack, saidToAgent } from './transcripts.mjs';
+import { lessonIndex } from './lessons.mjs';
 
 /** The package this runs from: its releases say whether a pinned version ships the gate at all. */
 const PACKAGE = dirname(dirname(fileURLToPath(import.meta.url)));
@@ -718,6 +719,15 @@ export function handle(input, { root, now = new Date(), pkg = PACKAGE }) {
         return null;
       case 'SubagentStop':
         return onStop(input, project, path, at);
+      case 'SubagentStart': {
+        // Not the loop's business, but the one hook every stage passes through as it begins: its lessons. Claude
+        // Code reads `additionalContext` from this event's `hookSpecificOutput` into the subagent's context as it
+        // starts — its hook schema and handler say so in 2.1.283, and the handler in 2.1.158 — though the help text
+        // it prints for a malformed hook output does not list the event.
+        const role = input.agent_type;
+        const text = role && project.graph.stages.has(role) ? lessonIndex(root, role) : null;
+        return text ? { hookSpecificOutput: { hookEventName: 'SubagentStart', additionalContext: text } } : null;
+      }
       case 'PostToolUse':
         return onPost(input, project, path, at);
       case 'PreToolUse':