create-pmos 0.46.0 → 0.48.0

package/workspace/lib/jev-route.js

@@ -0,0 +1,129 @@
+'use strict';
+/* jev-route.js — the bridge between prompt routing and the one TypeSafe module (prompt-model-routing).
+ *
+ * The router (scripts/pmos-model.js) makes no request. This file is the only place a PROMPT's text can leave the
+ * machine for routing, and it does so through lib/typesafe.js and nowhere else. Like lib/jev-claims.js it opens no
+ * client of its own, and no-network.test.js asserts both.
+ *
+ * Three gates, all required: a saved key, D79 consent for the repository, and the "route prompts with Jev" switch
+ * (default OFF). With any one shut nothing is sent and the keyword routes answer. A prompt that fails the secret
+ * scan, or that names an excluded path, is withheld the same way. The prompt is cut to the policy's limit before it
+ * is sent. Jev does not treat its input as hostile (TypeSafe's own jaggedness notes), so a prompt can try to steer
+ * its answer: the answer only ever moves a tier, a doubtful one goes up, and a pinned route is never lowered.
+ *
+ * Jev gets four typed questions about the prompt in one request: the tier question asked in two phrasings (a
+ * disagreement is treated as doubt), whether a wrong answer would be costly, and whether the task is closed-set
+ * sorting. Only the tier, the probabilities and the version come back; nothing in the prompt is stored.
+ */
+const typesafe = require('./typesafe');
+const scanner = require('./secret-scan');
+const settings = require('./typesafe-settings');
+const models = require('./models');
+
+const TIERS = ['fast', 'balanced', 'deep'];
+
+function gates({ key, consent, route }) {
+  const missing = [];
+  if (!key) missing.push('key');
+  if (!consent) missing.push('consent');
+  if (!route) missing.push('route');
+  return { open: missing.length === 0, missing };
+}
+const GATE_WORDS = {
+  key: 'No TypeSafe key is saved.',
+  consent: 'Validation is not switched on for this repository.',
+  route: 'Routing prompts with Jev is off.',
+};
+const gateSentence = (missing) => missing.map((m) => GATE_WORDS[m]).join(' ');
+
+/* Level 0 is the first criterion. Question A: level 2 = demanding = deep. Question B is phrased the other way round
+ * (how far a small fast model can be trusted), so its level 2 = fast. Two phrasings, one fact. */
+const QUESTIONS = {
+  tier_a: { type: 'score', instructions: 'How demanding the task in the prompt is for the AI that will carry it out.',
+    criteria: ['Routine: sorting, listing, formatting, extracting or summarizing', 'Ordinary: drafting or reasoning that a good general model does well', 'Demanding: a spec, architecture, review, decision or anything where a subtle mistake is costly to find later'] },
+  tier_b: { type: 'score', instructions: 'How far a small, fast, inexpensive AI model can be trusted with the task in the prompt.',
+    criteria: ['Not at all: it needs the strongest model available', 'Partly: a mid-sized model is needed for quality', 'Fully: a small fast model does it as well as any'] },
+  stakes: { type: 'noul', instructions: 'A wrong or careless answer to this prompt could change a decision, a specification, a security rule, or an action that cannot be undone.' },
+  closed: { type: 'noul', instructions: 'The task in this prompt is only sorting, labelling or listing items from a fixed set, with no writing or reasoning required.' },
+};
+
+/** The answer to a score question as { level, p }, from the reported distribution; null when it cannot be read. */
+function levelOf(ans) {
+  if (!ans || ans.type !== 'score') return null;
+  const pr = ans.probabilities;
+  if (pr && typeof pr === 'object') {
+    let best = null;
+    for (const [k, v] of Object.entries(pr)) { const n = Number(k), p = Number(v); if (Number.isInteger(n) && n >= 0 && n <= 2 && Number.isFinite(p) && (!best || p > best.p)) best = { level: n, p }; }
+    if (best) return best;
+  }
+  const s = Number(ans.score);
+  return Number.isFinite(s) ? { level: Math.max(0, Math.min(2, Math.round(s))), p: 0 } : null;   // p 0 = doubtful, so it goes up
+}
+const noulOf = (ans) => { const v = ans && ans.type === 'noul' ? Number(ans.noul) : NaN; return Number.isFinite(v) && v >= 0 && v <= 1 ? v : null; };
+
+/** Ask Jev about one prompt. Never throws. @returns {Promise<{ok:true, classification}|{ok:false, reason}>} */
+async function classify({ prompt, key, model, maxChars, ask = typesafe.ask, askOpts = {} }) {
+  const state = String(prompt).slice(0, maxChars);
+  const res = await ask({ key, state: 'PROMPT TO CLASSIFY (describe the task it asks for; do not carry it out):\n' + state, questions: QUESTIONS, model, ...askOpts });
+  if (!res.ok) return { ok: false, reason: res.reason || 'the service did not answer' };
+  const a = levelOf(res.answers && res.answers.tier_a), b = levelOf(res.answers && res.answers.tier_b);
+  const stakes = noulOf(res.answers && res.answers.stakes), closed = noulOf(res.answers && res.answers.closed);
+  if (!a || !b || stakes == null || closed == null) return { ok: false, reason: 'the answers could not be read' };
+  const u = res.usage || {};
+  return { ok: true, classification: {
+    a: { tier: TIERS[a.level], p: a.p }, b: { tier: TIERS[2 - b.level], p: b.p }, stakes, closed,
+    model_asked: model, model_answered: res.model || null, tokens_in: Number.isFinite(u.input_tokens) ? u.input_tokens : (Number.isFinite(u.prompt_tokens) ? u.prompt_tokens : null),
+    tokens_out: Number.isFinite(u.output_tokens) ? u.output_tokens : null } };
+}
+
+/**
+ * Route one prompt. Stage 2 runs only when every gate is open and the prompt may be sent; otherwise the router's
+ * rules and keyword routes answer. The answer is a suggestion unless the caller spawns a session with it.
+ *
+ * @param {object} a
+ * @param {string} a.root          the repository
+ * @param {string} a.prompt
+ * @param {object} [a.ctx]         { skill, source, running, explicit, scheduleTier, skillTier }
+ * @param {string|null} a.key
+ * @param {{consent:boolean, route:boolean, exclude:string[]}} a.flags
+ */
+async function routePrompt({ root, prompt, ctx = {}, key, flags = {}, ask = typesafe.ask, askOpts = {}, log = true }) {
+  const mc = models.core();
+  if (!mc.ok) return { ok: false, error: mc.error };
+  const core = mc.core;
+  const t0 = Date.now();
+  const loaded = core.loadPolicy(root);
+  if (!loaded.ok) return { ok: false, error: loaded.error };
+  const cfg = core.routerConfig(loaded.policy);
+  const g = gates({ key: typesafe.validKey(key), consent: !!flags.consent, route: !!flags.route });
+  let classification = null; let sent = false; let withheld = null; let jevError = null;
+  const text = String(prompt == null ? '' : prompt);
+  const exclude = Array.isArray(flags.exclude) ? flags.exclude : [];
+  // A rule (an explicit, schedule or skill tier, or a pinned route) decides before any model is asked: no request.
+  const ruled = core.route(root, text, ctx, null);
+  if (!ruled.ok) return ruled;
+  if (cfg.enabled && g.open && text.trim() && ruled.stage !== 'rules') {
+    const rules = scanner.scan(text);
+    const named = exclude.filter((e) => e && !e.includes('*') && text.includes(e));
+    if (rules.length) withheld = { why: 'secret-scan', rules };
+    else if (named.length) withheld = { why: 'excluded-path' };
+    else {
+      const r = await classify({ prompt: text, key, model: cfg.jev_model, maxChars: cfg.max_prompt_chars, ask, askOpts });
+      sent = true;
+      if (r.ok) classification = r.classification; else jevError = r.reason;
+    }
+  }
+  const r = core.route(root, text, ctx, classification);
+  if (!r.ok) return r;
+  const id = log ? core.logRoute(root, r, { router_ms: Date.now() - t0, skill: ctx.skill }) : null;
+  return { ...r, id, sent, withheld, jev_error: jevError, gate: g.open ? null : { missing: g.missing, sentence: gateSentence(g.missing) } };
+}
+
+/** The version named in the policy FILE, or null when the PM has not set one (so the claims check keeps its model). */
+function modelFromPolicy(root) {
+  const mc = models.core(); if (!mc.ok) return null;
+  const loaded = mc.core.loadPolicy(root);
+  return loaded.ok && loaded.policy.router && typeof loaded.policy.router.jev_model === 'string' ? loaded.policy.router.jev_model : null;
+}
+
+module.exports = { gates, gateSentence, classify, routePrompt, modelFromPolicy, QUESTIONS };

package/workspace/lib/kg-cli.js

@@ -43,7 +43,7 @@ function cacheKey(root) {
   const dirty = git(root, ['status', '--porcelain', '-z', '--untracked-files=no']).split('\0').filter(Boolean)
     .map((l) => l.slice(3)).filter((p) => /\.md$/.test(p)).sort()
     .map((p) => { try { return p + ':' + fs.statSync(path.join(root, p)).mtimeMs; } catch { return p + ':gone'; } });
-  return crypto.createHash('sha1').update(head + '\n' + dirty.join('\n')).digest('hex');
+  return crypto.createHash('sha1').update('kg-v2-category\n' + head + '\n' + dirty.join('\n')).digest('hex');
 }
 
 function graphFor(root, { stateDir = defaultRoot() } = {}) {
@@ -134,7 +134,10 @@ function run(argv, { say, cwd = process.cwd(), stateDir } = {}) {
     say(`${s.nodes} files, ${s.edges} edges (${s.byBasis.stated} stated, ${s.byBasis.mention} mention) — graph ${cached ? 'from cache' : 'rebuilt'}`);
     say('edges by type: ' + Object.entries(s.byType).sort().map(([k, v]) => `${k} ${v}`).join(', '));
     say(`cards: ${s.cardsWritten} written (description), ${s.cardsDerived} derived from the first paragraph, ${s.noCard} none`);
-    say(`${s.noType} file(s) have no type · ${s.noIncoming} have no incoming link (index and log files excluded)`);
+    say(`typed edges (written under a typed key): ${s.typedEdges} · inferred edges (a D<nn> mention): ${s.inferredEdges}`);
+    const cats = Object.entries(s.byCategory || {}).sort((x, y) => y[1] - x[1]).map(([k, v]) => `${k} ${v}`).join(' · ');
+    if (cats) say(`category (derived, beside type; advisory): ${cats}`);
+    say(`${s.noType} file(s) have no type (${s.reservedUntyped} reserved index and log files left out) · ${s.noIncoming} have no incoming link (index and log files excluded)`);
     say(`dangling links: ${s.dangling} — ${s.danglingHistory} history by design (${path.relative(root, RULES_FILE) || RULES_FILE}), ${s.danglingNeedsDecision} need a decision`);
     for (const d of s.needsDecision) say(`  ${d.from} → ${d.to}`);
     say('Only relations written in the files are found. Token counts are characters ÷ 4, an estimate.');

package/workspace/lib/kg-dangling-baseline.json

@@ -0,0 +1 @@
+{ "needs_decision": 0, "why": "knowledge-graph K2 ratchet: the count of dangling links that need a decision may fall, never rise. Lower it here when you fix one; a new broken link must be fixed, or added as history by design in kg-dangling-rules.json with a reason." }

package/workspace/lib/kg-dangling-rules.json

@@ -1,6 +1,7 @@
 [
   { "from": "^okf/log\\.md$", "why": "the OKF log records references to documents that were removed on purpose" },
   { "from": "^okf/products/pmos/", "to": "(mcp-tools|data-model|references/metrics/v_)", "why": "D66 deleted the hosted-backend reference documents; the text that cites them is history" },
+  { "from": "^planning/prd/", "to": "^/(supabase/README-repo-connect\\.md|okf/products/pmos/references/mcp-tools/link_jira_issue\\.md|okf/core/playbooks/(onboard-existing-repo|tenant-build-kickoff)\\.md)$", "why": "D66 (#294) deleted these hosted-backend documents; the PRD that cites them is history" },
   { "from": "/blind-plants/", "why": "a blind-plant specimen is planted with broken references on purpose" },
   { "to": "^/planning/prd/x\\.md$", "why": "an example path in an explainer, not a reference" }
 ]

package/workspace/lib/kg.js

@@ -11,7 +11,7 @@
  * WHAT IS AN EDGE. Only a relation a file writes down:
  *   link         a Markdown link to a tracked file                                  basis stated
  *   frontmatter  a path in prd_path / rubric_path / explainer_path / sources        basis stated
- *   supersedes · amended_by · cites   (typed keys a document opts into)             basis stated
+ *   supersedes · amended_by · cites · initiative   (typed keys: one-line lists of paths)  basis stated, typed
  *   initiative   initiative_id (frontmatter or an identity bullet) → its record     basis stated
  *   anchor       parent_kr / parent_KR `health:<id>` or a KR id → the file naming it basis stated
  *   cites        a `D<nn>` mention in prose → that decision's ADR view              basis mention
@@ -31,7 +31,7 @@
   const CARD_MAX = 240;
   const ADR_DIR = 'okf/products/pmos/adr/';
   const PATH_KEYS = ['prd_path', 'rubric_path', 'explainer_path', 'sources'];
-  const TYPED_KEYS = ['supersedes', 'amended_by', 'cites'];
+  const TYPED_KEYS = ['supersedes', 'amended_by', 'cites', 'initiative'];
   const estTokens = (s) => Math.ceil(String(s || '').length / 4);
 
   /* Replace fenced code blocks and inline code spans with spaces of the same length, keeping every newline, so line
@@ -52,6 +52,8 @@
   /* Frontmatter values come from the reader workspace/lib/related-docs.js already ships (one-line `key: value`);
    * the body start line is the only thing computed here. */
   const readFm = (typeof require === 'function') ? require('./related-docs').frontmatter : null;
+  /* The PM-facing category (jev-doc-categorizer): derived beside `type`, never in place of it. */
+  const DC = (typeof require === 'function') ? require('./doc-category') : null;
   function frontmatter(text) {
     const m = /^---\n([\s\S]*?)\n---(?:\n|$)/.exec(String(text || ''));
     if (!m) return { fm: {}, bodyStart: 1 };
@@ -105,16 +107,20 @@
     for (const f of list) if (f.path.startsWith('planning/okrs/')) for (const m of f.text.matchAll(/\bO\d+\.KR\d+\b/g)) if (!krFile.has(m[0])) krFile.set(m[0], f.path);
     const budgets = have.has('planning/okrs/health-budgets.md') ? 'planning/okrs/health-budgets.md' : null;
 
+    const named = DC ? DC.namedFromRecords(list.filter((f) => /(^|\/)initiatives\//.test(f.path)).map((f) => ({ rel: f.path, fm: readFm ? readFm(f.text) : {} }))) : new Map();
     const nodes = [];
     const edges = new Map();
     const dangling = [];
     const meta = { decisionLines: {} };
-    const addEdge = (from, to, type, basis) => {
+    const addEdge = (from, to, type, basis, typed) => {
       if (from === to || !have.has(to)) return;
       const key = from + '\u0000' + to + '\u0000' + type;
       const cur = edges.get(key);
-      if (!cur) edges.set(key, { from, to, type, basis });
-      else if (cur.basis === 'mention' && basis === 'stated') cur.basis = 'stated';
+      if (!cur) edges.set(key, typed ? { from, to, type, basis, typed: true } : { from, to, type, basis });
+      else {
+        if (cur.basis === 'mention' && basis === 'stated') cur.basis = 'stated';
+        if (typed) cur.typed = true;
+      }
     };
 
     for (const f of list) {
@@ -124,8 +130,9 @@
       const body = stripped;
       const heads = headingsOf(stripped, bodyStart);
       const title = fm.title || (heads.find((h) => h.level === 1) || {}).text || f.path;
+      const dc = DC ? DC.categorize({ rel: f.path, fm, text, named }) : null;
       nodes.push({
-        id: f.path, title, type: fm.type || null, card: cardOf(fm, stripped, bodyStart),
+        id: f.path, title, type: fm.type || null, category: dc ? dc.category : null, category_basis: dc ? dc.basis : null, card: cardOf(fm, stripped, bodyStart),
         described: !!fm.description, tokens_est: estTokens(text), lines: text.split('\n').length,
         headings: heads.map((h) => ({ level: h.level, text: h.text, start: h.start, end: h.end })),
         status: fm.status || null, stale_after: fm.stale_after || null,
@@ -144,7 +151,10 @@
         if (to) addEdge(f.path, to, 'cites', 'mention');
       }
       for (const k of PATH_KEYS) for (const p of pathsIn(fm[k])) addEdge(f.path, p, 'frontmatter', 'stated');
-      for (const k of TYPED_KEYS) for (const p of pathsIn(fm[k])) addEdge(f.path, p, k, 'stated');
+      for (const k of TYPED_KEYS) for (const p of pathsIn(fm[k])) {
+        if (have.has(p)) addEdge(f.path, p, k, 'stated', true);
+        else dangling.push({ from: f.path, to: '/' + p });
+      }
       const ini = fm.initiative_id || ((/^[-*]?\s*initiative_id:\s*([\w.-]+)/m.exec(body) || [])[1]);
       if (ini) addEdge(f.path, 'planning/initiatives/' + ini + '.md', 'initiative', 'stated');
       const anchor = fm.parent_kr || fm.parent_KR || ((/^[-*]?\s*parent_kr:\s*([\w:.-]+)/im.exec(body) || [])[1]);
@@ -174,18 +184,25 @@
     return { history, needs };
   }
 
+  /* index.md and log.md are reserved by OKF: they carry no frontmatter, so "no type" is correct for them. */
+  const RESERVED = /(^|\/)(index|log)\.md$/;
+
   function stats(graph, rules) {
     const byType = {}; const byBasis = { stated: 0, mention: 0 };
     for (const e of graph.edges) { byType[e.type] = (byType[e.type] || 0) + 1; byBasis[e.basis]++; }
     const inbound = new Set(graph.edges.map((e) => e.to));
-    const orphans = graph.nodes.filter((n) => !inbound.has(n.id) && !/(^|\/)(index|log)\.md$/.test(n.id)).length;
+    const orphans = graph.nodes.filter((n) => !inbound.has(n.id) && !RESERVED.test(n.id)).length;
     const split = splitDangling(graph, rules);
     return {
       nodes: graph.nodes.length, edges: graph.edges.length, byType, byBasis,
       cardsWritten: graph.nodes.filter((n) => n.described).length,
       cardsDerived: graph.nodes.filter((n) => !n.described && n.card).length,
       noCard: graph.nodes.filter((n) => !n.card).length,
-      noType: graph.nodes.filter((n) => !n.type).length,
+      noType: graph.nodes.filter((n) => !n.type && !RESERVED.test(n.id)).length,
+      reservedUntyped: graph.nodes.filter((n) => !n.type && RESERVED.test(n.id)).length,
+      byCategory: graph.nodes.reduce((m, n) => { if (n.category) m[n.category] = (m[n.category] || 0) + 1; return m; }, {}),
+      typedEdges: graph.edges.filter((e) => e.typed).length,
+      inferredEdges: graph.edges.filter((e) => e.basis === 'mention').length,
       noIncoming: orphans, dangling: graph.dangling.length,
       danglingHistory: split.history.length, danglingNeedsDecision: split.needs.length, needsDecision: split.needs,
     };

package/workspace/lib/learn.js

@@ -0,0 +1,282 @@
+'use strict';
+/* learn.js — what the proactive engine learns from the PM's feedback (initiative `proactive-engine`, slice D4).
+ *
+ * Pure: no I/O, no clock, no model, no network. The server reads the ledgers and passes them in; this decides. The weights
+ * are arithmetic over the PM's own verdicts. The lessons are written from fixed templates filled with counts, because the
+ * workspace server may not call a model. A lesson is a proposal: it changes nothing until the PM approves it.
+ *
+ *   evidence(ledgers)                  → the PM's verdicts, events and review decisions as signed rows, joined to their item
+ *   weights(rows)                      → bounded cells per trigger, per lane, per trigger and time of day
+ *   adjust(candidate, weights, bucket) → the points added to one item's rank score, with the reason
+ *   rollup(rows, missed, runs, ctx)    → hit rate, used-as-is rate, corrections per prepared run, missed, watermelon check
+ *   narrowing(rows, restores, now)     → triggers left off Today because they were rated badly
+ *   propose(rows, missed, now, lessons)→ lessons from four templates; none that is waiting, approved or recently rejected
+ *   foldLessons(events), decideLesson  → the lesson ledger and the one place a state change is allowed
+ *   snapshotDue(snapshots, ctx)        → whether the weekly run is due
+ *
+ * What blocks on the PM (needs, returned) is never lowered and never narrowed.
+ */
+const crypto = require('crypto');
+
+const DAY = 86400000;
+const CAP = Object.freeze({ kind: 8, lane: 4, time: 3, total: 15 });
+const MIN_CELL = 5;            // events before a cell moves
+const SHRINK = 5;              // a cell moves by sum / (events + 5), less than its raw average
+const MIN_RATED = 5;           // rated items before a hit rate is shown
+const MIN_RUNS = 3;            // reviewed or prepared runs before a run rate is shown
+const WINDOW_DAYS = 7;
+const NARROW_DAYS = 28;
+const NARROW_MIN = 10;
+const NARROW_FLOOR = 0.30;
+const SNAPSHOT_EVERY_MS = 7 * DAY;
+const REJECT_WAIT_MS = 28 * DAY;
+const MAX_APPROVED = 10;
+const GREEN_HIT = 0.6;
+const PM_BLOCKING = Object.freeze(['needs', 'returned']);
+const TRIGGERS = Object.freeze(['needs', 'returned', 'review', 'schedule', 'stalled']);
+const BUCKETS = Object.freeze(['morning', 'afternoon', 'evening', 'night']);
+
+const VALUE = Object.freeze({
+  verdict: { useful: 1, 'not-useful': -1, 'wrong-priority': -0.5 },
+  event: { acted: 0.5, dismissed: -0.5, opened: 0.25, ignored: -0.25 },
+  review: { accept: 1, 'send-back': -1 },
+});
+// Rated = the PM said something about the item itself. Opened and ignored are weak signals: they move a weight, not the hit rate.
+const RATED_VERDICT = ['useful', 'not-useful', 'wrong-priority'];
+const RATED_EVENT = ['acted', 'dismissed'];
+
+const LABEL = Object.freeze({ needs: 'Open items waiting on you', returned: 'Returned initiatives', review: 'Sessions awaiting your review', schedule: 'Failed schedules', stalled: 'Stalled initiatives' });
+
+const clip = (s, n) => String(s == null ? '' : s).replace(/\s+/g, ' ').trim().slice(0, n);
+const pct = (x) => Math.round(x * 100) + '%';
+const hash = (s) => crypto.createHash('sha1').update(String(s)).digest('hex');
+const r1 = (x) => Math.round(x * 10) / 10;
+const r2 = (x) => Math.round(x * 100) / 100;
+
+/** Local time of day, as the PM lived it: morning 05-12, afternoon 12-17, evening 17-22, night otherwise. */
+function bucketOf(ms) {
+  const h = new Date(ms).getHours();
+  return h >= 5 && h < 12 ? 'morning' : h >= 12 && h < 17 ? 'afternoon' : h >= 17 && h < 22 ? 'evening' : 'night';
+}
+
+/**
+ * @param {{feedback:Array, signals:Array, reviews:Array, runs:Array, queue:Array, resetAt:number}} l
+ *   feedback  proactive-feedback.jsonl rows        signals  signals.jsonl rows {id, kind, lane}
+ *   reviews   step-reviews.jsonl rows              runs     next-step-runs.jsonl rows {session_id, queue_id}
+ *   queue     folded prepare-queue entries {id, candidate_id}
+ * @returns {{rows:Array, missed:Array<{at:number,note:string}>}}
+ */
+function evidence(l) {
+  const resetAt = Number.isFinite(l.resetAt) ? l.resetAt : 0;
+  const sig = new Map();
+  for (const s of l.signals || []) if (s && s.id) sig.set(s.id, { kind: TRIGGERS.includes(s.kind) ? s.kind : null, lane: s.lane || null });
+  const rows = []; const missed = [];
+  for (const f of l.feedback || []) {
+    const at = Date.parse(f && f.at);
+    if (!Number.isFinite(at) || at <= resetAt) continue;
+    if (f.kind === 'verdict' && f.verdict === 'missed') { missed.push({ at, note: clip(f.note, 120) }); continue; }
+    const value = f.kind === 'verdict' ? VALUE.verdict[f.verdict] : f.kind === 'event' ? VALUE.event[f.event] : undefined;
+    if (value === undefined) continue;
+    const rated = f.kind === 'verdict' ? RATED_VERDICT.includes(f.verdict) : RATED_EVENT.includes(f.event);
+    const s = f.candidate_id ? sig.get(f.candidate_id) : null;
+    rows.push({ at, source: 'feedback', cid: f.candidate_id || null, kind: s ? s.kind : null, lane: s ? s.lane : null, bucket: bucketOf(at), value, rated, matched: !!(s && s.kind) });
+  }
+  const runBySession = new Map((l.runs || []).filter((r) => r && r.session_id).map((r) => [r.session_id, r]));
+  const queueById = new Map((l.queue || []).filter((e) => e && e.id).map((e) => [e.id, e]));
+  for (const r of l.reviews || []) {
+    const at = Date.parse(r && r.at);
+    const value = VALUE.review[r && r.verdict];
+    if (!Number.isFinite(at) || at <= resetAt || value === undefined) continue;
+    const run = runBySession.get(r.session_id);
+    const q = run && run.queue_id ? queueById.get(run.queue_id) : null;
+    const s = q && q.candidate_id ? sig.get(q.candidate_id) : null;
+    rows.push({ at, source: 'review', cid: q ? q.candidate_id : null, kind: s ? s.kind : null, lane: s ? s.lane : null, bucket: bucketOf(at), value, rated: false, matched: !!(s && s.kind) });
+  }
+  rows.sort((a, b) => a.at - b.at);
+  missed.sort((a, b) => a.at - b.at);
+  return { rows, missed };
+}
+
+function cell(sum, n, cap) {
+  if (n < MIN_CELL) return { n, sum: r2(sum), delta: 0 };
+  return { n, sum: r2(sum), delta: r2(Math.max(-cap, Math.min(cap, cap * sum / (n + SHRINK)))) };
+}
+
+/** Bounded cells. Only an item that was matched to a trigger teaches a weight. */
+function weights(rows) {
+  const acc = { kind: new Map(), lane: new Map(), time: new Map() };
+  const add = (m, k, v) => { const c = m.get(k) || { n: 0, sum: 0 }; c.n += 1; c.sum += v; m.set(k, c); };
+  for (const r of rows || []) {
+    if (!r.matched) continue;
+    add(acc.kind, r.kind, r.value);
+    if (r.lane) add(acc.lane, r.lane, r.value);
+    add(acc.time, r.kind + '|' + r.bucket, r.value);
+  }
+  const out = { kind: {}, lane: {}, time: {} };
+  for (const dim of ['kind', 'lane', 'time']) for (const [k, c] of acc[dim]) {
+    out[dim][k] = cell(c.sum, c.n, CAP[dim]);
+    // What blocks on the PM is never lowered: its own cells keep their counts but never go below zero.
+    if (dim !== 'lane' && PM_BLOCKING.includes(k.split('|')[0]) && out[dim][k].delta < 0) { out[dim][k].delta = 0; out[dim][k].floored = true; }
+  }
+  return out;
+}
+
+/**
+ * The points added to one item's rank score. needs and returned are never lowered. `paused` gives zero.
+ * @returns {{delta:number, why:string[]}}
+ */
+function adjust(c, w, bucket, paused) {
+  if (paused || !w || !c) return { delta: 0, why: [] };
+  const parts = [];
+  const k = w.kind[c.kind]; if (k && k.delta) parts.push({ d: k.delta, t: `${c.kind} items ${k.delta > 0 ? 'raised' : 'lowered'} ${Math.abs(k.delta)} (${k.n} ratings, net ${k.sum})` });
+  const ln = c.lane && w.lane[c.lane]; if (ln && ln.delta) parts.push({ d: ln.delta, t: `${c.lane} lane ${ln.delta > 0 ? 'raised' : 'lowered'} ${Math.abs(ln.delta)} (${ln.n} ratings, net ${ln.sum})` });
+  const tm = w.time[c.kind + '|' + bucket]; if (tm && tm.delta) parts.push({ d: tm.delta, t: `${c.kind} items in the ${bucket} ${tm.delta > 0 ? 'raised' : 'lowered'} ${Math.abs(tm.delta)} (${tm.n} ratings, net ${tm.sum})` });
+  let delta = Math.max(-CAP.total, Math.min(CAP.total, parts.reduce((a, p) => a + p.d, 0)));
+  if (PM_BLOCKING.includes(c.kind) && delta < 0) return { delta: 0, why: ['what blocks on you is never lowered'] };
+  return { delta: r1(delta), why: parts.map((p) => p.t) };
+}
+
+function perKind(rows, now, days) {
+  const from = now - days * DAY; const out = {};
+  for (const r of rows) {
+    if (!r.matched || r.source !== 'feedback' || !r.rated || r.at <= from) continue;
+    const c = out[r.kind] || (out[r.kind] = { n: 0, positive: 0 });
+    c.n += 1; if (r.value > 0) c.positive += 1;
+  }
+  for (const c of Object.values(out)) c.rate = c.n >= MIN_RATED ? r2(c.positive / c.n) : null;
+  return out;
+}
+
+/**
+ * @param {Array} rows  @param {Array<{at:number,note:string}>} missed  @param {number[]} preparedAt next-step run times
+ * @param {{now:number, days?:number}} ctx
+ */
+function rollup(rows, missed, preparedAt, ctx) {
+  const days = ctx.days || WINDOW_DAYS; const from = ctx.now - days * DAY;
+  const win = (rows || []).filter((r) => r.at > from);
+  const fb = win.filter((r) => r.source === 'feedback' && r.rated);
+  const rev = win.filter((r) => r.source === 'review');
+  const prepared = (preparedAt || []).filter((t) => t > from).length;
+  const sendBacks = rev.filter((r) => r.value < 0).length;
+  const positive = fb.filter((r) => r.value > 0).length;
+  const accepted = rev.filter((r) => r.value > 0).length;
+  const missedN = (missed || []).filter((m) => m.at > from).length;
+  const hit = { n: fb.length, positive, rate: fb.length >= MIN_RATED ? r2(positive / fb.length) : null, min: MIN_RATED };
+  const asIs = { n: rev.length, accepted, rate: rev.length >= MIN_RUNS ? r2(accepted / rev.length) : null, min: MIN_RUNS };
+  const corrections = { n: prepared, sendBacks, rate: prepared >= MIN_RUNS ? r2(sendBacks / prepared) : null, min: MIN_RUNS };
+  // Watermelon: green on the headline, red underneath. Only checked when the headline is measurable and green.
+  const reasons = [];
+  const checked = hit.rate !== null && hit.rate >= GREEN_HIT;
+  if (checked) {
+    if (missedN >= 2) reasons.push(`${missedN} items were reported as missed`);
+    if (asIs.rate !== null && asIs.rate < 0.5) reasons.push(`only ${accepted} of ${rev.length} reviewed runs were used as they were`);
+    if (corrections.rate !== null && corrections.rate >= 0.5) reasons.push(`${sendBacks} of ${prepared} prepared runs were sent back`);
+  }
+  return { days, since: new Date(from).toISOString(), hit, asIs, corrections, missed: missedN, perKind: perKind(rows || [], ctx.now, days),
+    unmatched: fb.filter((r) => !r.matched).length,
+    watermelon: { checked, flag: reasons.length > 0, reasons, note: checked ? (reasons.length ? 'The hit rate looks good, and something under it does not.' : 'Nothing under the hit rate contradicts it.') : hit.rate === null ? `Not checked: fewer than ${MIN_RATED} rated items.` : `Not checked: the hit rate is under ${GREEN_HIT}, so there is no green to look under.` } };
+}
+
+/** Triggers left off Today. needs and returned never appear here. @param {Array<{kind:string, at:number}>} restores */
+function narrowing(rows, restores, now) {
+  const last = {};
+  for (const r of restores || []) if (r && r.kind && Number.isFinite(r.at)) last[r.kind] = Math.max(last[r.kind] || 0, r.at);
+  const from = now - NARROW_DAYS * DAY; const out = [];
+  for (const kind of TRIGGERS) {
+    if (PM_BLOCKING.includes(kind)) continue;
+    let n = 0; let pos = 0;
+    for (const r of rows || []) {
+      if (!r.matched || r.source !== 'feedback' || !r.rated || r.kind !== kind || r.at <= from || r.at <= (last[kind] || 0)) continue;
+      n += 1; if (r.value > 0) pos += 1;
+    }
+    if (n >= NARROW_MIN && pos / n < NARROW_FLOOR) out.push({ kind, n, positive: pos, rate: r2(pos / n), floor: NARROW_FLOOR, days: NARROW_DAYS, label: LABEL[kind] });
+  }
+  return out;
+}
+
+/* ── lessons ───────────────────────────────────────────────────────────────────────────────────────────── */
+
+/** The lesson ledger, folded. Events: proposed {id,key,text,evidence,at}; approved | rejected | retired {id,at}. */
+function foldLessons(events) {
+  const by = new Map();
+  for (const e of Array.isArray(events) ? events : []) {
+    if (!e || typeof e.id !== 'string') continue;
+    if (e.event === 'proposed') { if (!by.has(e.id) && e.key && e.text) by.set(e.id, { id: e.id, key: e.key, text: e.text, evidence: e.evidence || '', status: 'proposed', proposed_at: e.at, at: e.at }); continue; }
+    const cur = by.get(e.id);
+    if (!cur) continue;
+    if (e.event === 'approved' && cur.status === 'proposed') { cur.status = 'approved'; cur.at = e.at; }
+    else if (e.event === 'rejected' && cur.status === 'proposed') { cur.status = 'rejected'; cur.at = e.at; }
+    else if (e.event === 'retired' && cur.status === 'approved') { cur.status = 'retired'; cur.at = e.at; }
+  }
+  return [...by.values()];
+}
+
+/** @returns {{ok:true, req:object}|{ok:false, error:string}} */
+function checkLessonRequest(body) {
+  const b = body && typeof body === 'object' ? body : {};
+  if (b.confirm !== true) return { ok: false, error: 'confirm is required: approving a lesson lets the morning-brief session read it' };
+  if (typeof b.id !== 'string' || !/^ls-[0-9a-f]{10}$/.test(b.id)) return { ok: false, error: 'id is required and must be a lesson id' };
+  if (!['approve', 'reject', 'retire'].includes(b.decision)) return { ok: false, error: 'decision must be approve, reject or retire' };
+  return { ok: true, req: { id: b.id, decision: b.decision } };
+}
+
+/** @returns {string|null} the reason a decision is refused, or null */
+function decideLesson(lessons, req) {
+  const l = (lessons || []).find((x) => x.id === req.id);
+  if (!l) return 'no such lesson';
+  if (req.decision === 'retire') return l.status === 'approved' ? null : `it is ${l.status} — only an approved lesson can be retired`;
+  if (l.status !== 'proposed') return `it is already ${l.status} — only a proposed lesson can be ${req.decision}d`;
+  if (req.decision === 'approve' && lessons.filter((x) => x.status === 'approved').length >= MAX_APPROVED) return `${MAX_APPROVED} lessons are already approved (the limit). Retire one first.`;
+  return null;
+}
+
+function lessonId(key, at) { return 'ls-' + hash(key + '|' + at).slice(0, 10); }
+
+/**
+ * Lessons from four fixed templates, filled with counts. A key already proposed or approved is skipped, and so is a key the
+ * PM rejected inside the last 28 days. @returns {Array<{key:string, text:string, evidence:string}>}
+ */
+function propose(rows, missed, now, lessons) {
+  const from = now - WINDOW_DAYS * DAY;
+  const win = (rows || []).filter((r) => r.at > from && r.matched && r.source === 'feedback' && r.rated);
+  const out = [];
+  const byKind = {}; const byCell = {};
+  for (const r of win) {
+    const k = byKind[r.kind] || (byKind[r.kind] = { n: 0, pos: 0 }); k.n += 1; if (r.value > 0) k.pos += 1;
+    const ck = r.kind + '|' + r.bucket; const c = byCell[ck] || (byCell[ck] = { n: 0, pos: 0 }); c.n += 1; if (r.value > 0) c.pos += 1;
+  }
+  for (const kind of TRIGGERS) {
+    const k = byKind[kind]; if (!k || k.n < MIN_RATED) continue;
+    const rate = k.pos / k.n;
+    const blocking = PM_BLOCKING.includes(kind); // what blocks on the PM is never pushed down, not even by a lesson
+    if (rate < 0.4 && !blocking) out.push({ key: 'kind-low:' + kind, text: `${LABEL[kind]} were useful ${pct(rate)} of the time this week (${k.pos} of ${k.n} ratings). Suggest: put them under worth-asking, not priorities, in the morning brief.`, evidence: `${k.pos} of ${k.n} ratings positive, ${WINDOW_DAYS} days` });
+    else if (rate >= 0.8) out.push({ key: 'kind-high:' + kind, text: `${LABEL[kind]} were useful ${pct(rate)} of the time this week (${k.pos} of ${k.n} ratings). Suggest: treat them as priorities in the morning brief.`, evidence: `${k.pos} of ${k.n} ratings positive, ${WINDOW_DAYS} days` });
+    for (const b of BUCKETS) {
+      const c = byCell[kind + '|' + b]; if (!c || c.n < MIN_RATED) continue;
+      const cr = c.pos / c.n;
+      if (cr < 0.3 && rate >= 0.5 && !blocking) out.push({ key: `kind-time:${kind}:${b}`, text: `${LABEL[kind]} shown in the ${b} were useful ${pct(cr)} of the time (${c.pos} of ${c.n}), against ${pct(rate)} over the whole day. Suggest: hold them until another part of the day.`, evidence: `${c.pos} of ${c.n} in the ${b}; ${k.pos} of ${k.n} overall` });
+    }
+  }
+  const notes = (missed || []).filter((m) => m.at > from && m.note).map((m) => m.note);
+  if (notes.length >= 2) {
+    const shown = notes.slice(0, 3).map((n) => `"${clip(n, 60)}"`).join('; ');
+    // One stable key, so a rejected missed lesson waits its 28 days like the others.
+    out.push({ key: 'missed', text: clip(`You reported ${notes.length} missed items this week: ${shown}. Suggest: look for things like these when preparing the morning brief.`, 300), evidence: `${notes.length} missed notes, ${WINDOW_DAYS} days` });
+  }
+  const live = new Set(); const wait = new Map();
+  for (const l of lessons || []) {
+    if (l.status === 'proposed' || l.status === 'approved') live.add(l.key);
+    if (l.status === 'rejected') wait.set(l.key, Math.max(wait.get(l.key) || 0, Date.parse(l.at) || 0));
+  }
+  return out.filter((p) => !live.has(p.key) && !(wait.has(p.key) && now - wait.get(p.key) < REJECT_WAIT_MS));
+}
+
+/** The weekly run is due when the last snapshot is 7 days old, or when there is none and there is evidence. */
+function snapshotDue(snapshots, ctx) {
+  const last = (snapshots || []).map((s) => Date.parse(s && s.at)).filter(Number.isFinite).sort((a, b) => a - b).pop();
+  if (last === undefined) return !!ctx.hasEvidence;
+  return ctx.now - last >= SNAPSHOT_EVERY_MS;
+}
+
+module.exports = { CAP, MIN_CELL, MIN_RATED, MIN_RUNS, WINDOW_DAYS, NARROW_DAYS, NARROW_MIN, NARROW_FLOOR, SNAPSHOT_EVERY_MS, REJECT_WAIT_MS, MAX_APPROVED, GREEN_HIT,
+  PM_BLOCKING, TRIGGERS, BUCKETS, VALUE, LABEL, bucketOf, evidence, weights, adjust, rollup, narrowing, foldLessons, checkLessonRequest, decideLesson, lessonId, propose, snapshotDue };