create-pmos 0.45.0 → 0.47.0

package/workspace/guide/validate-with-typesafe.md

@@ -1,6 +1,7 @@
 ---
 type: Guide
 title: "Guide: validate a repository"
+description: "How the validate item checks that a repository agrees with itself, and the optional second check with TypeSafe."
 timestamp: 2026-10-03
 ---
 

package/workspace/lib/kg-cli.js

@@ -134,7 +134,8 @@ 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}`);
+    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
@@ -109,12 +109,15 @@
     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) {
@@ -144,7 +147,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 +180,24 @@
     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,
+      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,280 @@
+'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;
+    if (rate < 0.4) 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) 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('; ');
+    out.push({ key: 'missed:' + hash(notes.slice().sort().join('|')).slice(0, 10), 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 };

package/workspace/lib/proactive-cli.js

@@ -16,13 +16,14 @@
  *   pmos proactive prepare plan --initiative ID [--repo PATH]
  *   pmos proactive prepare queue --initiative ID --item ITEM --sha HASH [--repo PATH]
  *   pmos proactive prepare status | cancel ID | run
+ *   pmos proactive learn [status] | run | lessons | approve ID | reject ID | retire ID | restore TRIGGER | reset
  */
 const fs = require('fs');
 const path = require('path');
 const { execFileSync } = require('child_process');
 const { parseArgs } = require('./schedule-cli');
 
-const COMMANDS = { proactive: ['today', 'scan', 'settings', 'feedback', 'brief', 'prepare'] };
+const COMMANDS = { proactive: ['today', 'scan', 'settings', 'feedback', 'brief', 'prepare', 'learn'] };
 const BRIEF_SOURCES = ['calendar', 'wispr', 'mail', 'jira', 'confluence'];
 const onOff = (v, what) => (v === 'on' || v === 'true' ? true : v === 'off' || v === 'false' ? false : { err: `${what} takes on or off` });
 
@@ -141,6 +142,53 @@ async function run(argv, { call, say, cwd = process.cwd() }) {
     for (const e of r.entries) say(`${e.id}  ${e.status}  ${e.label}${e.reason ? ' — ' + e.reason : ''}`);
     return 0;
   }
+  if (verb === 'learn') {
+    const sub = pos[0] || 'status';
+    const rate = (x, what) => (x.rate === null ? `${what}: not enough evidence (${x.n} of ${x.min} needed)` : `${what}: ${Math.round(x.rate * 100)}% (${x.n} counted)`);
+    const decide = async (decision, past) => {
+      if (!pos[1]) return fail(`usage: pmos proactive learn ${decision} ID`);
+      const r = await call('POST', '/api/proactive/learn/lesson', { id: pos[1], decision, confirm: true });
+      if (!r || r.ok === false) return fail(`refused — ${(r && r.error) || 'the server did not answer'}. Nothing changed.`);
+      say(`${past} ${r.id}`); return 0;
+    };
+    if (sub === 'approve') return decide('approve', 'approved');
+    if (sub === 'reject') return decide('reject', 'rejected');
+    if (sub === 'retire') return decide('retire', 'retired');
+    if (sub === 'restore') {
+      if (!pos[1]) return fail('usage: pmos proactive learn restore TRIGGER');
+      const r = await call('POST', '/api/proactive/learn/restore', { kind: pos[1], confirm: true });
+      if (!r || r.ok === false) return fail(`refused — ${(r && r.error) || 'the server did not answer'}. Nothing changed.`);
+      say(`restored ${r.kind} — it comes back on Today and stays until 10 new ratings of it have arrived`); return 0;
+    }
+    if (sub === 'reset') {
+      const r = await call('POST', '/api/proactive/learn/reset', { confirm: true });
+      if (!r || r.ok === false) return fail(`refused — ${(r && r.error) || 'the server did not answer'}. Nothing changed.`);
+      say('reset — earlier feedback is ignored from now on. It is not deleted.'); return 0;
+    }
+    if (sub === 'run') {
+      const r = await call('POST', '/api/proactive/learn/run', {});
+      if (!r || r.ok === false) return fail(`refused — ${(r && r.error) || 'the server did not answer'}`);
+      say(`weekly review taken — ${r.proposed.length} lesson(s) proposed${r.snapshot.narrowed.length ? ', narrowed: ' + r.snapshot.narrowed.join(', ') : ''}`);
+      return 0;
+    }
+    const r = await call('GET', '/api/proactive/learn');
+    if (!r || r.ok === false) return fail((r && r.error) || 'the server did not answer');
+    if (sub === 'lessons') {
+      if (r.paused) { say('Learning is paused: no lesson applies.'); return 0; }
+      if (!r.approved.length) say('No approved lessons.');
+      for (const l of r.approved) say(`- ${l.text}`);
+      return 0;
+    }
+    if (sub !== 'status') return fail('usage: pmos proactive learn [status|run|lessons|approve ID|reject ID|retire ID|restore TRIGGER|reset]');
+    say(`learning ${r.paused ? 'paused' : 'on'} · ${r.evidenceCount} piece(s) of evidence${r.resetAt ? ' since ' + r.resetAt : ''}`);
+    const ro = r.rollup;
+    say(`last ${ro.days} days — ${rate(ro.hit, 'hit rate')} · ${rate(ro.asIs, 'used as is')} · ${rate(ro.corrections, 'corrections per prepared run')} · ${ro.missed} reported missed`);
+    say('watermelon check: ' + ro.watermelon.note + (ro.watermelon.reasons.length ? ' ' + ro.watermelon.reasons.join('; ') + '.' : ''));
+    for (const c of r.cells.filter((x) => x.delta)) say(`weight ${c.dim} ${c.key}: ${c.delta > 0 ? '+' : ''}${c.delta} (${c.n} events, net ${c.sum})`);
+    for (const n of r.narrowed) say(`narrowed: ${n.kind} — useful ${Math.round(n.rate * 100)}% over ${n.n} ratings in ${n.days} days (floor ${Math.round(n.floor * 100)}%). Restore with: pmos proactive learn restore ${n.kind}`);
+    for (const l of r.lessons.filter((x) => x.status === 'proposed' || x.status === 'approved')) say(`${l.id}  ${l.status}  ${l.text}`);
+    return 0;
+  }
   if (verb === 'brief') {
     const sub = pos[0] || 'show';
     if (sub === 'submit') {

package/workspace/lib/proactive.js

@@ -39,14 +39,14 @@ const clip = (s, n) => String(s == null ? '' : s).replace(/\s+/g, ' ').trim().sl
 const days = (ms) => Math.floor(ms / DAY);
 
 function cand(kind, key, p) {
-  return { id: idOf(key), key, kind, owner: OWNER[kind], initiative_id: p.initiative_id || null, ws: p.ws || null, repo: p.repo || null,
+  return { id: idOf(key), key, kind, owner: OWNER[kind], initiative_id: p.initiative_id || null, ws: p.ws || null, repo: p.repo || null, lane: p.lane || null,
     title: clip(p.title, 120), why: clip(p.why, 200), evidence: clip(p.evidence, 240), confidence: p.confidence, since: p.since == null ? null : p.since,
     open: p.open || null };
 }
 
 /**
  * @param {{now:number, settings:object, repos:Array, nextStepRuns:Array}} ctx
- *   repos[]: {name, ws, error?, initiatives:[{id,title,active,lastRun,hasRuns}], needs:[{initiative_id,question,run_id}],
+ *   repos[]: {name, ws, error?, initiatives:[{id,title,active,lane,lastRun,hasRuns}], needs:[{initiative_id,question,run_id}],
  *            returned:[{initiative_id,note,at}], schedules:[{id,name,lastStatus,lastRun}]}
  *   nextStepRuns[]: {session_id, initiative_id, ws, key, ended, reviewed, at}
  * @returns {{candidates:Array, unreadable:Array<{repo:string,error:string}>}}
@@ -61,7 +61,7 @@ function detect(ctx) {
       for (const n of r.needs || []) {
         const ini = byId.get(n.initiative_id);
         out.push(cand('needs', `needs:${r.ws}:${n.run_id || n.initiative_id + ':' + clip(n.question, 60)}`, {
-          initiative_id: n.initiative_id, ws: r.ws, repo: r.name, title: ini ? ini.title || ini.id : (n.initiative_id || 'an open item'),
+          initiative_id: n.initiative_id, ws: r.ws, repo: r.name, lane: ini ? ini.lane : null, title: ini ? ini.title || ini.id : (n.initiative_id || 'an open item'),
           why: 'An open item is waiting on you.', evidence: n.question, confidence: 0.95, since: null,
           open: n.initiative_id ? { type: 'initiative', initiative_id: n.initiative_id, ws: r.ws } : null }));
       }
@@ -71,7 +71,7 @@ function detect(ctx) {
         const ini = byId.get(x.initiative_id);
         if (ini && !ini.active) continue;
         out.push(cand('returned', `returned:${r.ws}:${x.initiative_id}:${x.at || ''}`, {
-          initiative_id: x.initiative_id, ws: r.ws, repo: r.name, title: ini ? ini.title || ini.id : x.initiative_id,
+          initiative_id: x.initiative_id, ws: r.ws, repo: r.name, lane: ini ? ini.lane : null, title: ini ? ini.title || ini.id : x.initiative_id,
           why: 'You returned this at the Acceptance Gate and it has not been accepted since.', evidence: x.note || 'returned', confidence: 0.95, since: x.at ? Date.parse(x.at) || null : null,
           open: { type: 'initiative', initiative_id: x.initiative_id, ws: r.ws } }));
       }
@@ -93,7 +93,7 @@ function detect(ctx) {
         if (idle < limit) continue;
         const d = days(idle);
         out.push(cand('stalled', `stalled:${r.ws}:${i.id}`, {
-          initiative_id: i.id, ws: r.ws, repo: r.name, title: i.title || i.id,
+          initiative_id: i.id, ws: r.ws, repo: r.name, lane: i.lane, title: i.title || i.id,
           why: `In progress, with no agent run for ${d} days.`, evidence: `last run ${new Date(i.lastRun).toISOString().slice(0, 10)}; the threshold is ${st.stalledDays || DEFAULTS.stalledDays} days`,
           confidence: Math.min(0.85, +(0.5 + 0.05 * (d - (st.stalledDays || DEFAULTS.stalledDays))).toFixed(2)), since: i.lastRun,
           open: { type: 'initiative', initiative_id: i.id, ws: r.ws } }));
@@ -112,9 +112,10 @@ function detect(ctx) {
   return { candidates: out, unreadable };
 }
 
-function rank(cands, now) {
+/** `adj` is optional (slice D4): c → {delta, why[]}. Without it the order is the fixed one, unchanged. */
+function rank(cands, now, adj) {
   const score = (c) => BASE[c.kind] + (c.since != null && now != null ? Math.min(30, Math.max(0, days(now - c.since))) : 0);
-  return cands.map((c) => ({ ...c, rank: score(c) })).sort((a, b) => b.rank - a.rank || (a.id < b.id ? -1 : 1))
+  return cands.map((c) => { const a = typeof adj === 'function' ? adj(c) : null; const d = a && a.delta ? a.delta : 0; return { ...c, rank: score(c) + d, adjust: d, adjust_why: a && a.why ? a.why.join('; ') : '' }; }).sort((a, b) => b.rank - a.rank || (a.id < b.id ? -1 : 1))
     .map((c, i) => ({ ...c, n: i + 1 }));
 }
 

package/workspace/lib/session-flag.js

@@ -0,0 +1,35 @@
+'use strict';
+// session-flag — the one variable the workspace puts in the environment of each agent terminal it
+// starts, so a Claude Code mod running inside can tell it is hosted (pmos-cockpit-mod, Run 4, M12).
+//
+//   PMOS_WORKSPACE=1
+//
+// It is set in exactly two places, one per way a terminal starts, and nowhere else:
+//   · the direct PTY path   — `withFlag(env)`    over the merged session environment
+//   · the tmux path          — `tmuxOverlay(o)`   over the `-e K=V` overlay that travels to the pane
+//
+// It is NEVER put in `sessionEnv()` itself. That base environment also seeds tmux control commands
+// (a cold start seeds the daemon, and so every pane on the socket) and a git sync process, which are
+// not agent terminals. And it is applied LAST, after a profile's overlay, so a profile cannot unset
+// or change it: the workspace owns this variable.
+//
+// The flag changes what the mod DRAWS (it hides the slice, which the workspace already shows). It
+// never changes what the mod GUARDS. A terminal started outside the workspace has no such flag.
+//
+// Pure: no I/O, no process state.
+
+const FLAG = 'PMOS_WORKSPACE';
+const VALUE = '1';
+
+/** The direct PTY path: set the flag on a session environment, last. Returns the same object. */
+function withFlag(env) {
+  env[FLAG] = VALUE;
+  return env;
+}
+
+/** The tmux path: the overlay that becomes `new-session -e K=V`, with the flag last. A new object. */
+function tmuxOverlay(overlay) {
+  return { ...(overlay || {}), [FLAG]: VALUE };
+}
+
+module.exports = { FLAG, VALUE, withFlag, tmuxOverlay };

package/workspace/package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "pmos-workspace",
-  "version": "0.45.0",
+  "version": "0.47.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {

package/workspace/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pmos-workspace",
-  "version": "0.45.0",
+  "version": "0.47.0",
   "private": true,
   "description": "PMOS Terminal Workspace — local companion hosting real PTYs beside the library and gates (D62)",
   "license": "MIT",
@@ -10,12 +10,12 @@
   "scripts": {
     "start": "node server.js",
     "test": "node test.js && npm run test:modules",
-    "test:modules": "node proactive.test.js && node focus.test.js && node handoff.test.js && node repo-scan.test.js && node profiles.test.js && node external-linking.test.js && node story-artifacts.test.js && node no-network.test.js && node typesafe-validation.test.js && node claims.test.js && node jev-claims.test.js && node repo-watch.test.js && node fixture-parity.test.mjs && node markdown.test.mjs && node start-policy.test.js && node state-isolation.test.js && node sync.test.js && node schedule-cli.test.js && node initiative-surface.test.js && node guide.test.js && node next-step-actions.test.js && node kg.test.js && node proactive-prepare.test.js",
+    "test:modules": "node proactive.test.js && node focus.test.js && node handoff.test.js && node repo-scan.test.js && node profiles.test.js && node external-linking.test.js && node story-artifacts.test.js && node no-network.test.js && node typesafe-validation.test.js && node claims.test.js && node jev-claims.test.js && node repo-watch.test.js && node fixture-parity.test.mjs && node markdown.test.mjs && node start-policy.test.js && node state-isolation.test.js && node sync.test.js && node schedule-cli.test.js && node initiative-surface.test.js && node guide.test.js && node next-step-actions.test.js && node kg.test.js && node proactive-prepare.test.js && node learn.test.js && node session-flag.test.js",
     "test:ui": "node ui-test.js",
     "test:parity": "node design-parity.js --states",
     "test:all": "npm test && npm run test:panels && npm run test:ui && npm run test:parity && npm run test:offline",
     "doctor": "node doctor.js",
-    "test:panels": "node pm-shell-test.js && node pm-repos-test.js && node pm-initiatives-test.js && node pm-detail-test.js && node pm-tabs-test.js && node pm-term-test.js && node pm-modes-test.js && node pm-r1-test.js && node pm-r2-test.js && node pm-r3-test.js && node pm-r4-test.js && node pm-r5-test.js && node pm-r6-test.js && node pm-r7-test.js && node pm-r8-test.js && node pm-r9-test.js && node pm-r10-test.js && node pm-r11-test.js && node pm-r12-test.js && node pm-r13-test.js && node pm-r14-test.js && node pm-r15-test.js && node pm-r16-test.js && node pm-r17-test.js && node pm-r16-test.js && node pm-r18-test.js && node pm-r19-test.js && node pm-r20-test.js && node pm-r21-test.js && node pm-r22-test.js && node pm-r23-test.js && node pm-r24-test.js && node pm-r25-test.js",
+    "test:panels": "node pm-shell-test.js && node pm-repos-test.js && node pm-initiatives-test.js && node pm-detail-test.js && node pm-tabs-test.js && node pm-term-test.js && node pm-modes-test.js && node pm-r1-test.js && node pm-r2-test.js && node pm-r3-test.js && node pm-r4-test.js && node pm-r5-test.js && node pm-r6-test.js && node pm-r7-test.js && node pm-r8-test.js && node pm-r9-test.js && node pm-r10-test.js && node pm-r11-test.js && node pm-r12-test.js && node pm-r13-test.js && node pm-r14-test.js && node pm-r15-test.js && node pm-r16-test.js && node pm-r17-test.js && node pm-r16-test.js && node pm-r18-test.js && node pm-r19-test.js && node pm-r20-test.js && node pm-r21-test.js && node pm-r22-test.js && node pm-r23-test.js && node pm-r24-test.js && node pm-r25-test.js && node pm-r26-test.js",
     "test:offline": "node offline-tarball.test.js"
   },
   "engines": {