@tech-leads-club/harness-toolkit 0.2.1

package/src/core/lesson/lesson.garden.ts

@@ -0,0 +1,283 @@
+import { mkdirSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { projectConfigPath } from "../../platform/paths.ts";
+import { isCommandResolutionFailure } from "../gate/gate.command.ts";
+import type { LessonsPolicyConfig } from "../policy/policy.types.ts";
+import { lessonLinkVerdict } from "./lesson.link.ts";
+import { hoursSince } from "./lesson.score.ts";
+import { appliesHere, isInjectable, packLessonsUnderBudget, rankLessonsForSync } from "./lesson.select.ts";
+import { allLessons, gardenGlobalLessons, gardenProjectLessons } from "./lesson.store.ts";
+import type { HarnessLesson } from "./lesson.types.ts";
+import { validityReason } from "./lesson.validity.ts";
+
+export type GardenReport = {
+  promoted: string[];
+  quarantined: string[];
+  pruned: string[];
+  /** Project lessons whose refs no longer resolve. Reported, never auto-deleted — a rename can be reverted. */
+  stale: string[];
+  /** Lessons whose staleness cleared because every ref resolves again. */
+  refreshed: string[];
+  expired: string[];
+  active: number;
+  candidates: number;
+};
+
+/**
+ * A lesson recorded before AD-021, when a gate command that never resolved was classified `verification`
+ * instead of `config`. Such a lesson teaches an agent to go fix tests in response to a malformed command,
+ * and post-AD-021 the same output classifies `config`, so the signature cannot legitimately recur.
+ *
+ * hazard: exitCode 0 is passed deliberately. `isCommandResolutionFailure` returns true for 127, and stored
+ * instruction text can contain any number — only the message patterns may decide this.
+ */
+function isStaleResolutionMisfile(lesson: HarnessLesson): boolean {
+  return (
+    lesson.category === "verification" &&
+    isCommandResolutionFailure({ exitCode: 0, output: lesson.instruction })
+  );
+}
+
+/**
+ * invariant: promotion counts distinct sessions. `hitCount` counts fingerprint recurrences, which one stuck
+ * session can drive to any number, so it promoted lessons that had occurred once in the world.
+ *
+ * why: a record written before `sessionKeys` existed has none, and falling back to `hitCount` is what keeps it
+ * promotable rather than frozen as a candidate forever.
+ */
+export function promotionCount(lesson: HarnessLesson): number {
+  return lesson.sessionKeys.length > 0 ? lesson.sessionKeys.length : lesson.hitCount;
+}
+
+type StaleOutcome = { lesson: HarnessLesson; marked: boolean; cleared: boolean };
+
+/**
+ * invariant: only the tier whose store shares this repository is graded. A global lesson is read from many
+ * repositories, so one persisted flag cannot be true for all of them — that case is decided per repository at
+ * selection time instead.
+ */
+function applyStaleness(root: string, lesson: HarnessLesson, now: Date): StaleOutcome {
+  if (lesson.tier !== "project" || lesson.refs.length === 0) {
+    return { lesson, marked: false, cleared: false };
+  }
+  const verdict = lessonLinkVerdict(root, lesson.refs);
+  const checkedAt = now.toISOString();
+  if (verdict.stale) {
+    return {
+      lesson: { ...lesson, staleReason: verdict.status, staleCheckedAt: checkedAt, updatedAt: checkedAt },
+      marked: lesson.staleReason === undefined,
+      cleared: false,
+    };
+  }
+  if (lesson.staleReason === undefined) {
+    return { lesson: { ...lesson, staleCheckedAt: checkedAt }, marked: false, cleared: false };
+  }
+  const { staleReason: _dropped, ...rest } = lesson;
+  return {
+    lesson: { ...rest, staleCheckedAt: checkedAt, updatedAt: checkedAt },
+    marked: false,
+    cleared: true,
+  };
+}
+
+function gardenOne(
+  root: string,
+  lesson: HarnessLesson,
+  config: LessonsPolicyConfig,
+  now: Date,
+  report: GardenReport,
+): HarnessLesson | null {
+  if (isStaleResolutionMisfile(lesson)) {
+    report.pruned.push(lesson.id);
+    return null;
+  }
+
+  // why: an expired lesson is the one case the author already decided. Prune it, unlike a broken ref, which is
+  // a filesystem observation that a revert could undo.
+  if (validityReason(lesson, now) === "expired") {
+    report.expired.push(lesson.id);
+    return null;
+  }
+
+  const outcome = applyStaleness(root, lesson, now);
+  let candidate = outcome.lesson;
+  if (outcome.marked) {
+    report.stale.push(candidate.id);
+  }
+  if (outcome.cleared) {
+    report.refreshed.push(candidate.id);
+  }
+
+  if (candidate.status === "candidate" && promotionCount(candidate) >= config.promoteHitCount) {
+    candidate = {
+      ...candidate,
+      status: "active",
+      confidence: Math.max(candidate.confidence, 0.7),
+      updatedAt: now.toISOString(),
+    };
+    report.promoted.push(candidate.id);
+  }
+
+  const idleHours = hoursSince(candidate.lastSeenAt, now);
+  if (
+    candidate.status === "active" &&
+    idleHours > 24 * 90 &&
+    promotionCount(candidate) < config.promoteHitCount
+  ) {
+    candidate = { ...candidate, status: "quarantine", updatedAt: now.toISOString() };
+    report.quarantined.push(candidate.id);
+  }
+
+  if (candidate.status === "quarantine" && idleHours > 24 * 180) {
+    report.pruned.push(candidate.id);
+    return null;
+  }
+
+  // invariant: pruning measures the same clock the ranking does — recurrence, not injection. Reading
+  // lastAccessedAt here let an injected lesson postpone its own pruning indefinitely.
+  const decayed =
+    candidate.confidence * Math.exp(-config.decayLambda * hoursSince(candidate.lastSeenAt, now));
+  if (decayed < 0.05 && candidate.status !== "quarantine" && candidate.hitCount < 2) {
+    report.pruned.push(candidate.id);
+    return null;
+  }
+
+  return candidate;
+}
+
+function emptyReport(): GardenReport {
+  return {
+    promoted: [],
+    quarantined: [],
+    pruned: [],
+    stale: [],
+    refreshed: [],
+    expired: [],
+    active: 0,
+    candidates: 0,
+  };
+}
+
+export async function gardenLessons(
+  root: string,
+  config: LessonsPolicyConfig,
+  now = new Date(),
+): Promise<GardenReport> {
+  const report = emptyReport();
+  const sweep = (current: HarnessLesson[]): HarnessLesson[] => {
+    const next: HarnessLesson[] = [];
+    for (const lesson of current) {
+      if (lesson.source === "core") {
+        continue;
+      }
+      const kept = gardenOne(root, lesson, config, now, report);
+      if (kept) {
+        next.push(kept);
+      }
+    }
+    return next;
+  };
+
+  const project = await gardenProjectLessons(root, sweep);
+  // why: the global tier is gardened in the same pass. Decay, promotion and expiry apply to it identically;
+  // only staleness is tier-specific, and `applyStaleness` is what draws that line.
+  const global = await gardenGlobalLessons(sweep);
+  const kept = [...project, ...global];
+
+  report.active = kept.filter((l) => l.status === "active").length;
+  report.candidates = kept.filter((l) => l.status === "candidate").length;
+  return report;
+}
+
+const SYNC_TITLE = "Learned harness lessons (auto-synced; do not hand-edit):";
+
+export function lessonsMarkdownPath(root: string): string {
+  return join(dirname(projectConfigPath(root)), "lessons.md");
+}
+
+/**
+ * Why the synced file has nothing in it, in the operator's terms.
+ *
+ * hazard: one sentence — "No active project lessons yet." — covered a switched-off capability, an enabled one that
+ * had never seen a repeat failure, and a store full of candidates none of which had been promoted. Three different
+ * situations and nothing to tell them apart, so the file read as broken. An operator reported it as never updating,
+ * and it was being rewritten every session with the same empty text ([/decisions/ad-049.md](/decisions/ad-049.md)).
+ */
+export function emptySyncReason(
+  lessons: readonly HarnessLesson[],
+  config: LessonsPolicyConfig,
+  now: Date,
+): string {
+  if (!config.enabled) {
+    return "Lessons are switched off for this project (`intelligence.lessons.enabled` is false), so no gate failure is ever recorded. Ask the agent to run the harness-init skill to turn them on.";
+  }
+  if (lessons.length === 0) {
+    return "No lesson recorded yet. One is written when the *same* gate failure repeats inside a session — a gate that fails once, or fails differently each time, records nothing.";
+  }
+  const candidates = lessons.filter((lesson) => lesson.status === "candidate").length;
+  if (candidates > 0 && lessons.every((lesson) => lesson.status !== "active")) {
+    const noun = candidates === 1 ? "lesson" : "lessons";
+    return `${candidates} candidate ${noun} recorded, none promoted yet. Promotion needs the same failure in ${config.promoteHitCount} distinct sessions — see \`tlc harness lessons list\`.`;
+  }
+  const withheld = lessons.filter(
+    (lesson) => lesson.status === "active" && !isInjectable(lesson, now),
+  ).length;
+  if (withheld > 0) {
+    const noun = withheld === 1 ? "lesson is" : "lessons are";
+    return `${withheld} active ${noun} withheld — a named reference stopped resolving, or a validity window closed. Run \`tlc harness lessons list\` to see which.`;
+  }
+  return "No active project lessons yet.";
+}
+
+export function renderLessonsMarkdown(
+  root: string,
+  lessons: HarnessLesson[],
+  config: LessonsPolicyConfig,
+): string {
+  // invariant: the synced file is what an operator reads as current guidance, so it carries exactly what would
+  // be injected — a withheld lesson appearing here would contradict the store.
+  const now = new Date();
+  // hazard: `appliesHere` as well as `isInjectable`. A global lesson whose refs miss in this repo is withheld from
+  // the injected block, so listing it here would make the file contradict the guidance the model receives.
+  const ranked = rankLessonsForSync(
+    lessons.filter((lesson) => isInjectable(lesson, now) && appliesHere(root, lesson)),
+  ).slice(0, 12);
+  const { body } = packLessonsUnderBudget({
+    lessons: ranked,
+    maxChars: config.maxCharsSession,
+    title: SYNC_TITLE,
+  });
+  const path = lessonsMarkdownPath(root);
+  mkdirSync(dirname(path), { recursive: true });
+  const content = `# Harness lessons
+
+Auto-synced from gate failures; do not hand-edit.
+
+${body || emptySyncReason(lessons, config, now)}
+`;
+  writeFileSync(path, content, "utf8");
+  return path;
+}
+
+/**
+ * `writeDurableView` is the caller's verdict, not a re-read of the config: the mode alone cannot decide it, because
+ * `auto` depends on whether the host delivers context from its session-start hook. Core takes that as data rather
+ * than importing a provider ([/decisions/ad-050.md](/decisions/ad-050.md)).
+ */
+export function gardenAndPersistLessons(
+  root: string,
+  config: LessonsPolicyConfig,
+  options: { writeDurableView: boolean },
+  now = new Date(),
+): Promise<{ report: GardenReport; markdownPath: string | null }> {
+  return gardenLessons(root, config, now).then((report) => {
+    if (!options.writeDurableView) {
+      return { report, markdownPath: null };
+    }
+    // hazard: this read `readProjectLessons`, so the file carried one of the three tiers. On the host where it is
+    // the only route to the model, a core or global lesson therefore reached nothing
+    // ([/decisions/ad-040.md](/decisions/ad-040.md), [/decisions/ad-050.md](/decisions/ad-050.md)).
+    const path = renderLessonsMarkdown(root, allLessons(root), config);
+    return { report, markdownPath: path };
+  });
+}

package/src/core/lesson/lesson.link.ts

@@ -0,0 +1,93 @@
+import { existsSync, readFileSync } from "node:fs";
+import { isAbsolute, resolve } from "node:path";
+import type { HarnessLesson, LessonLink, LessonLinkStatus } from "./lesson.types.ts";
+
+const LINK_SEPARATOR = ":";
+
+export function parseLessonLink(raw: string): LessonLink | null {
+  const trimmed = raw.trim();
+  if (!trimmed) {
+    return null;
+  }
+  const at = trimmed.lastIndexOf(LINK_SEPARATOR);
+  if (at <= 0 || at === trimmed.length - 1) {
+    return { path: trimmed };
+  }
+  const path = trimmed.slice(0, at).trim();
+  const symbol = trimmed.slice(at + 1).trim();
+  if (!path) {
+    return null;
+  }
+  return symbol ? { path, symbol } : { path };
+}
+
+export function formatLessonLink(link: LessonLink): string {
+  return link.symbol ? `${link.path}${LINK_SEPARATOR}${link.symbol}` : link.path;
+}
+
+// hazard: an absolute path resolves against a machine, not a repository, so a global lesson would report
+// `present` in every product on the machine that happens to contain that file.
+function resolveLinkPath(root: string, link: LessonLink): string | null {
+  return isAbsolute(link.path) ? null : resolve(root, link.path);
+}
+
+export function checkLessonLink(root: string, link: LessonLink): LessonLinkStatus {
+  const absolute = resolveLinkPath(root, link);
+  if (absolute === null || !existsSync(absolute)) {
+    return "path-missing";
+  }
+  if (!link.symbol) {
+    return "present";
+  }
+  try {
+    // why: substring, not parsing — a symbol table needs a language per extension and a parse per check, and a
+    // false `present` only costs keeping a lesson a rename would have retired.
+    return readFileSync(absolute, "utf8").includes(link.symbol) ? "present" : "symbol-missing";
+  } catch {
+    // invariant: unreadable is deferred, never stale. A file this process cannot open is not evidence the
+    // lesson stopped being true.
+    return "unreadable";
+  }
+}
+
+const STATUS_SEVERITY: Record<LessonLinkStatus, number> = {
+  present: 0,
+  unreadable: 1,
+  "symbol-missing": 2,
+  "path-missing": 3,
+};
+
+export function worstLinkStatus(statuses: readonly LessonLinkStatus[]): LessonLinkStatus {
+  let worst: LessonLinkStatus = "present";
+  for (const status of statuses) {
+    if (STATUS_SEVERITY[status] > STATUS_SEVERITY[worst]) {
+      worst = status;
+    }
+  }
+  return worst;
+}
+
+export type LessonLinkVerdict = {
+  status: LessonLinkStatus;
+  stale: boolean;
+  brokenRefs: string[];
+};
+
+export function lessonLinkVerdict(root: string, refs: readonly LessonLink[]): LessonLinkVerdict {
+  if (refs.length === 0) {
+    return { status: "present", stale: false, brokenRefs: [] };
+  }
+  const statuses = refs.map((ref) => checkLessonLink(root, ref));
+  const brokenRefs = refs
+    .filter((_, index) => statuses[index] === "path-missing" || statuses[index] === "symbol-missing")
+    .map(formatLessonLink);
+  return { status: worstLinkStatus(statuses), stale: brokenRefs.length > 0, brokenRefs };
+}
+
+export function lessonRefs(lesson: HarnessLesson): LessonLink[] {
+  return Array.isArray(lesson.refs) ? lesson.refs : [];
+}
+
+export function isStaleLesson(lesson: HarnessLesson): boolean {
+  return typeof lesson.staleReason === "string" && lesson.staleReason.length > 0;
+}

package/src/core/lesson/lesson.score.ts

@@ -0,0 +1,61 @@
+import type { HarnessLesson } from "./lesson.types.ts";
+
+const MS_PER_HOUR = 3_600_000;
+
+// hazard: an unparseable or missing timestamp used to yield NaN, which does not throw but poisons every
+// comparator that sorts on the decayed value. Unknown reads as "just seen", which is the conservative side.
+export function hoursSince(iso: string, now: Date): number {
+  const then = new Date(iso).getTime();
+  if (!Number.isFinite(then)) {
+    return 0;
+  }
+  return Math.max(0, (now.getTime() - then) / MS_PER_HOUR);
+}
+
+/**
+ * invariant: decay is measured from `lastSeenAt` — the last time the failure actually recurred — and never
+ * from `lastAccessedAt`.
+ *
+ * hazard: `lastAccessedAt` is written by `touchAccessed` when a lesson is *selected for injection*, so
+ * reading it here made relevance self-fulfilling: showing a lesson reset the clock that decided whether to
+ * keep showing it. Any lesson matching a gate name became immortal and never pruned.
+ */
+export function decayedConfidence(lesson: HarnessLesson, decayLambda: number, now: Date): number {
+  if (lesson.source === "core") {
+    return lesson.confidence;
+  }
+  return lesson.confidence * Math.exp(-decayLambda * hoursSince(lesson.lastSeenAt, now));
+}
+
+export function relevanceScore(lesson: HarnessLesson, args: { gate?: string; text?: string }): number {
+  let score = 0.25;
+  const gate = (args.gate ?? "").toLowerCase();
+  const text = (args.text ?? "").toLowerCase();
+  if (gate && lesson.failedGate.toLowerCase() === gate) {
+    score += 1.2;
+  }
+  if (gate && lesson.triggerTokens.some((token) => gate.includes(token.toLowerCase()))) {
+    score += 0.35;
+  }
+  for (const token of lesson.triggerTokens) {
+    const t = token.toLowerCase();
+    if (t && text.includes(t)) {
+      score += 0.2;
+    }
+  }
+  score += lesson.priority / 200;
+  return score;
+}
+
+export function rankScore(
+  lesson: HarnessLesson,
+  args: { gate?: string; text?: string; decayLambda: number; projectBoost: number; now?: Date },
+): number {
+  const now = args.now ?? new Date();
+  const relevance = relevanceScore(lesson, { gate: args.gate, text: args.text });
+  const confidence = decayedConfidence(lesson, args.decayLambda, now);
+  // why: the boost favours the nearest tier. A lesson written for this repository outranks one carried in from
+  // another product, which is what keeps a cross-product tier from drowning local knowledge.
+  const boost = lesson.tier === "project" ? args.projectBoost : 1;
+  return relevance * confidence * boost;
+}

package/src/core/lesson/lesson.select.ts

@@ -0,0 +1,209 @@
+import type { LessonsPolicyConfig } from "../policy/policy.types.ts";
+import { isStaleLesson, lessonLinkVerdict } from "./lesson.link.ts";
+import { rankScore } from "./lesson.score.ts";
+import { allLessons, touchAccessed } from "./lesson.store.ts";
+import type { HarnessLesson } from "./lesson.types.ts";
+import { isWithinValidity } from "./lesson.validity.ts";
+
+export type SelectMode = "session" | "retry";
+
+const OMIT_NOTE_RESERVE = 96;
+
+// invariant: injectable is decided before ranking, not by scoring a withheld lesson low. A stale or out-of-window
+// lesson must not reach the turn at any score.
+export function isInjectable(lesson: HarnessLesson, now: Date): boolean {
+  return !isStaleLesson(lesson) && isWithinValidity(lesson, now);
+}
+
+/**
+ * why: a global lesson is read from many repositories, so one stored `staleReason` cannot be true for all of
+ * them — a ref that is missing here may be present in the product the lesson came from. Applicability is
+ * therefore computed per repository for the global tier, while a project lesson relies on the flag `garden`
+ * wrote against the same repository it lives in.
+ */
+export function appliesHere(root: string, lesson: HarnessLesson): boolean {
+  if (lesson.tier !== "global" || lesson.refs.length === 0) {
+    return true;
+  }
+  return !lessonLinkVerdict(root, lesson.refs).stale;
+}
+
+function allowedForMode(lesson: HarnessLesson, mode: SelectMode, gate?: string): boolean {
+  if (lesson.status === "quarantine") {
+    return false;
+  }
+  if (mode === "session") {
+    return lesson.status === "active";
+  }
+  if (lesson.status === "active") {
+    return !gate || lesson.failedGate === gate || lesson.failedGate === "stagnation";
+  }
+  if (lesson.status === "candidate") {
+    return Boolean(gate) && lesson.failedGate === gate;
+  }
+  return false;
+}
+
+// why: the tier is rendered because it calibrates trust — a lesson carried in from another product is advice
+// about a different repository, and the turn should be able to tell.
+export function renderLessonBlock(lesson: HarnessLesson): string {
+  const lines = [
+    `- [${lesson.failedGate}/${lesson.status}/${lesson.tier}] ${lesson.instruction}`,
+    `  avoid: ${lesson.avoid}`,
+    `  prefer: ${lesson.prefer}`,
+    `  before retrying: ${lesson.preRetryCheck}`,
+  ];
+  return lines.join("\n");
+}
+
+export function formatLessonsSection(lessons: HarnessLesson[], title: string): string {
+  if (lessons.length === 0) {
+    return "";
+  }
+  return [title, ...lessons.map((lesson) => renderLessonBlock(lesson))].join("\n");
+}
+
+export function omitLessonsNote(omitted: number): string {
+  if (omitted <= 0) {
+    return "";
+  }
+  const noun = omitted === 1 ? "lesson" : "lessons";
+  return `_(${omitted} more active ${noun} omitted under char budget)_`;
+}
+
+export function packLessonsUnderBudget(args: { lessons: HarnessLesson[]; maxChars: number; title: string }): {
+  body: string;
+  included: HarnessLesson[];
+  omitted: number;
+} {
+  const { lessons, title } = args;
+  const maxChars = Math.max(0, args.maxChars);
+  if (lessons.length === 0) {
+    return { body: "", included: [], omitted: 0 };
+  }
+
+  const packBudget = Math.max(0, maxChars - OMIT_NOTE_RESERVE);
+  const included: HarnessLesson[] = [];
+
+  for (const lesson of lessons) {
+    const candidate = formatLessonsSection([...included, lesson], title);
+    if (included.length === 0) {
+      included.push(lesson);
+      if (candidate.length > packBudget) {
+        break;
+      }
+      continue;
+    }
+    if (candidate.length <= packBudget) {
+      included.push(lesson);
+      continue;
+    }
+    break;
+  }
+
+  let omitted = lessons.length - included.length;
+  let body = formatLessonsSection(included, title);
+  const note = omitLessonsNote(omitted);
+  if (!note) {
+    return { body, included, omitted };
+  }
+
+  const withNote = `${body}\n${note}`;
+  if (withNote.length <= maxChars) {
+    return { body: withNote, included, omitted };
+  }
+
+  while (included.length > 1) {
+    included.pop();
+    omitted = lessons.length - included.length;
+    body = formatLessonsSection(included, title);
+    const next = `${body}\n${omitLessonsNote(omitted)}`;
+    if (next.length <= maxChars) {
+      return { body: next, included: [...included], omitted };
+    }
+  }
+
+  return { body, included: [...included], omitted: lessons.length - included.length };
+}
+
+export function rankLessonsForSync(lessons: HarnessLesson[]): HarnessLesson[] {
+  return [...lessons]
+    .filter((lesson) => lesson.status === "active")
+    .sort(
+      (a, b) =>
+        b.priority - a.priority ||
+        b.hitCount - a.hitCount ||
+        b.confidence - a.confidence ||
+        new Date(b.lastSeenAt).getTime() - new Date(a.lastSeenAt).getTime() ||
+        a.id.localeCompare(b.id),
+    );
+}
+
+export async function selectLessons(args: {
+  projectDir: string;
+  config: LessonsPolicyConfig;
+  mode: SelectMode;
+  gate?: string;
+  text?: string;
+  now?: Date;
+}): Promise<{ lessons: HarnessLesson[]; usedIds: string[]; omitted: number }> {
+  if (!args.config.enabled) {
+    return { lessons: [], usedIds: [], omitted: 0 };
+  }
+
+  const maxCount = args.mode === "session" ? args.config.maxInjectSession : args.config.maxInjectRetry;
+  const maxChars = args.mode === "session" ? args.config.maxCharsSession : args.config.maxCharsRetry;
+  const now = args.now ?? new Date();
+
+  const ranked = allLessons(args.projectDir)
+    .filter(
+      (lesson) =>
+        isInjectable(lesson, now) &&
+        appliesHere(args.projectDir, lesson) &&
+        allowedForMode(lesson, args.mode, args.gate),
+    )
+    .map((lesson) => ({
+      lesson,
+      score: rankScore(lesson, {
+        gate: args.gate,
+        text: args.text,
+        decayLambda: args.config.decayLambda,
+        projectBoost: args.config.projectBoost,
+        now,
+      }),
+    }))
+    .sort((a, b) => b.score - a.score || b.lesson.priority - a.lesson.priority);
+
+  // invariant: pinned first, in the operator's own order, before anything scored. Everything else about a pinned
+  // lesson still applies — staleness, validity, mode and the char budget all bind
+  // ([/decisions/ad-043.md](/decisions/ad-043.md)).
+  const ordered = [
+    ...ranked.filter((row) => row.lesson.pinned),
+    ...ranked.filter((row) => !row.lesson.pinned),
+  ];
+
+  const picked: HarnessLesson[] = [];
+  let chars = 0;
+  for (const row of ordered) {
+    if (picked.length >= maxCount) {
+      break;
+    }
+    const block = renderLessonBlock(row.lesson);
+    if (chars + block.length > maxChars && picked.length > 0) {
+      break;
+    }
+    if (block.length > maxChars && picked.length === 0) {
+      picked.push(row.lesson);
+      break;
+    }
+    picked.push(row.lesson);
+    chars += block.length;
+  }
+
+  const usedIds = picked.filter((l) => l.source !== "core").map((l) => l.id);
+  await touchAccessed(args.projectDir, usedIds, now);
+  // hazard: `maxInjectSession` defaults to 5 and `maxCharsSession` to 900, which fits about two rendered blocks —
+  // so the count promises five and delivers two, silently. Whoever reads the injected block has to be able to tell
+  // that eligible lessons were dropped ([/decisions/ad-043.md](/decisions/ad-043.md)).
+  return { lessons: picked, usedIds: picked.map((l) => l.id), omitted: ordered.length - picked.length };
+}