create-pmos 0.46.0 → 0.47.0

package/payload/skills/SKILL-FORMAT.md

@@ -1,6 +1,7 @@
 ---
 type: Reference
 title: "SKILL-FORMAT.md — Required Format for PMOS Skills"
+description: "The required structure of every .skill file in PMOS, and why it keeps skills cheap to keep available and expensive to load only when used."
 timestamp: 2026-07-23
 ---
 

package/payload/state/discoveries.md

@@ -2,7 +2,7 @@
 type: Reference
 title: "Discoveries and friction log"
 description: "Append-only record of what runs discovered and where the process rubbed."
-generated: {by: process:create-pmos, at: "2026-10-04T09:45:16Z"}
+generated: {by: process:create-pmos, at: "2026-10-04T10:38:12Z"}
 status: stable
 ---
 

package/workspace/README.md

@@ -76,7 +76,7 @@ After the session ends, `GET /api/next-step/summary` returns the files the branc
 
 ## Today: what is waiting for you (`proactive-engine`, slice D1)
 
-`lib/proactive.js` is a pure core: it reads the records the workspace already derives and finds five conditions: a need waiting on the PM, an initiative returned at acceptance, an ended next-step session with no review, a scheduled task whose last run failed, and an active initiative with no agent run for the stalled threshold (5 days by default). The ranking is fixed and stated in the guide. `GET /api/proactive/today` computes the list on each request. A scan (`POST /api/proactive/scan`, and a 10-minute automatic tick inside the existing 60-second interval) appends new items once a day to `signals.jsonl`. Feedback (`useful`, `not-useful`, `wrong-priority`, `missed` with a note, and the events `opened`, `dismissed`) is appended to `proactive-feedback.jsonl`; a dismissed item is hidden for 7 days. Settings are in `proactive-settings.json` (engine on or off, one trigger off, the stalled threshold, quiet hours, pause learning; the last has no effect yet because nothing learns from the verdicts in this slice). The same actions are in `pmos proactive today|scan|settings|feedback` (`lib/proactive-cli.js`), a thin client of those routes. The list is drawn in the navigation column by the `today` drawer item. It runs only while the server runs, reads no mail or calendar, and starts no session, sends nothing and changes no record of an initiative (`proactive.test.js` E25-E26 read the source for that). Tests: `proactive.test.js` (pure core, routes, CLI) and `pm-r22-test.js` (the page). The guide page is `guide/proactive-engine.md`.
+`lib/proactive.js` is a pure core: it reads the records the workspace already derives and finds five conditions: a need waiting on the PM, an initiative returned at acceptance, an ended next-step session with no review, a scheduled task whose last run failed, and an active initiative with no agent run for the stalled threshold (5 days by default). The ranking is fixed and stated in the guide. `GET /api/proactive/today` computes the list on each request. A scan (`POST /api/proactive/scan`, and a 10-minute automatic tick inside the existing 60-second interval) appends new items once a day to `signals.jsonl`. Feedback (`useful`, `not-useful`, `wrong-priority`, `missed` with a note, and the events `opened`, `dismissed`) is appended to `proactive-feedback.jsonl`; a dismissed item is hidden for 7 days. Settings are in `proactive-settings.json` (engine on or off, one trigger off, the stalled threshold, quiet hours, pause learning). The same actions are in `pmos proactive today|scan|settings|feedback` (`lib/proactive-cli.js`), a thin client of those routes. The list is drawn in the navigation column by the `today` drawer item. It runs only while the server runs, reads no mail or calendar, and starts no session, sends nothing and changes no record of an initiative (`proactive.test.js` E25-E26 read the source for that). Tests: `proactive.test.js` (pure core, routes, CLI) and `pm-r22-test.js` (the page). The guide page is `guide/proactive-engine.md`. **Learning (D4).** `lib/learn.js` is a second pure core. It joins the PM's verdicts, events and step reviews to items through the candidate id in `signals.jsonl` (which now records the initiative's lane), moves three bounded weights (per trigger, per lane, per trigger and time of day; caps 8, 4, 3 and 15 in all, no cell before 5 events) that `rank` adds to the fixed score, reports a 7-day rollup with every count and a watermelon check, leaves a trigger off Today when it was rated useful under 30% of the time over 10 or more ratings in 28 days, and proposes lessons from four templates. A lesson is approved, rejected or retired only by the PM's press; an approved lesson is read by the morning-brief session through `pmos proactive learn lessons` and goes into no other prompt, so the C1 prompt and plan hash are unchanged. The weekly review runs from the existing 10-minute proactive tick and does not catch up. needs and returned are never lowered or narrowed. Pause learning gives zero weights and no review. Ledgers: `learn-events.jsonl`, `lessons.jsonl`, `proactive-rollups.jsonl`. Routes `GET /api/proactive/learn` and `POST /api/proactive/learn/{run,lesson,restore,reset}`; commands `pmos proactive learn …`. Tests: `learn.test.js` and `pm-r26-test.js`.
 
 ## The morning brief (`proactive-engine`, slice D2)
 

package/workspace/guide/initiatives-and-next-steps.md

@@ -1,6 +1,7 @@
 ---
 type: Guide
 title: "Guide: initiatives and next steps"
+description: "What the initiative detail shows, top to bottom: status, lifecycle control, and the next step the workspace proposes."
 timestamp: 2026-10-03
 ---
 

package/workspace/guide/knowledge-graph.md

@@ -1,6 +1,7 @@
 ---
 type: Guide
 title: "Guide: find knowledge without reading whole files"
+description: "How to use pmos kg to find one card, section or decision without reading whole files, and the limits of the map."
 timestamp: 2026-10-03
 ---
 
@@ -18,7 +19,7 @@ The map has an **edge** only where a file states a relation:
 |---|---|
 | link | A Markdown link to a tracked file. |
 | frontmatter | A path in `prd_path`, `rubric_path`, `explainer_path` or `sources`. |
-| supersedes, amended_by, cites | A document that chooses to carry one of these keys. |
+| supersedes, amended_by, cites, initiative | A document that chooses to carry one of these keys. |
 | initiative | An `initiative_id` that names an initiative record. |
 | anchor | A `parent_kr` of `health:<id>` or a KR id. |
 | cites (mention) | A `D<nn>` in the text, such as `D65`, with two or more digits. |
@@ -27,6 +28,10 @@ A link that points at a missing file is **dangling**. It is listed and never bec
 
 It does not guess. A file that talks about a topic without a link, a path or a `D<nn>` is not connected to it. It does not use embeddings or a model, and it does not use the network.
 
+## Typed keys
+
+A document may carry `supersedes`, `amended_by`, `cites` and `initiative` in its frontmatter. Each key is one line and holds one or more paths to `.md` files, separated by commas. The map reads each path as a stated edge of that type. A path to a file that does not exist is listed as dangling and never becomes an edge. Nobody fills these keys in for existing documents; add them to new or edited ones. `pmos kg stats` shows how many edges are typed and how many are inferred from a `D<nn>` in the text.
+
 ## Commands
 
 | Command | What it does |

package/workspace/guide/layout.md

@@ -1,6 +1,7 @@
 ---
 type: Guide
 title: "Guide: layout"
+description: "The three workspace columns: navigation, detail and tabs, and what each one holds."
 timestamp: 2026-10-03
 ---
 

package/workspace/guide/proactive-engine.md

@@ -1,6 +1,7 @@
 ---
 type: Guide
 title: "Guide: Today and the proactive engine"
+description: "What the Today item shows, how the morning brief is made, and how the workspace works out what is waiting for you."
 timestamp: 2026-10-03
 ---
 
@@ -39,6 +40,22 @@ From a Today item that names an initiative, you can ask for the plan and approve
 
 The states of an entry are queued, started, skipped, expired and cancelled.
 
+## What it learns
+
+Today learns from you, and only from you. The evidence is your own records on this computer: the verdict you give an item, what you do with it (opened, acted, dismissed, ignored), and your accept or send-back on a prepared session. The workspace makes no model call to do this. The weights are arithmetic, and the lessons are written from fixed templates filled with counts.
+
+- **Weights.** Three adjustments are added to an item's place in the order: one for its trigger (at most 8 points), one for its lane (at most 4) and one for its trigger at this time of day (at most 3). Time of day is morning 05-12, afternoon 12-17, evening 17-22 and night, in your local time. A cell moves only after 5 events, and moves less than the raw average. The total is at most 15, so learning reorders items that are close and cannot turn the stated order upside down. An item shows its adjustment and the counts behind it.
+- **What it never does.** It never lowers or hides what blocks on you: the needs and returned triggers get no negative adjustment and are never narrowed. Items of the morning brief teach no weight, because their order is fixed. Pause learning makes every weight zero and stops the weekly review, the proposals and the narrowing; feedback is still recorded.
+- **The weekly review.** About every 7 days, only while the workspace server runs, the workspace takes one snapshot. It does not catch up after a gap: it takes one snapshot of the last 7 days. **run the weekly review now** does the same on demand and is refused while learning is paused. Quiet hours hold scans, not this review.
+- **The rollup.** For the last 7 days: the hit rate (useful and acted, over useful, acted, not useful, wrong priority and dismissed), the used-as-is rate (accepted over accepted and sent back), corrections per prepared run (sends-back over every session started from a step, reviewed or not), and the items you reported as missed. Every rate shows its count. With fewer than 5 rated items, or 3 runs, it says there is not enough evidence and shows no rate.
+- **The watermelon check.** It looks only when the hit rate is 0.6 or more. It then names any of these: 2 or more items reported as missed, a used-as-is rate under 0.5 over 3 or more reviewed runs, or 0.5 or more corrections per prepared run over 3 or more runs. A good hit rate with one of these under it is not a good week.
+- **Lessons.** The review proposes lessons from four templates: a trigger that was useful under 40% or at least 80% of the time (5 or more ratings), items you reported as missed (2 or more), and a trigger that did badly in one part of the day only. A lesson is a proposal. It is approved, rejected or retired only when you press the button. A rejected lesson is not proposed again for 28 days. At most 10 lessons are approved at once.
+- **Where an approved lesson goes.** Into the state folder, and from there to the morning-brief session, which reads it with `pmos proactive learn lessons`. It goes into no other prompt, so the prompt and the plan hash of a prepared step do not change, and no file of any repository is written. To keep a lesson in repository memory, copy it there yourself.
+- **Narrowing.** A trigger other than needs and returned that you rated useful under 30% of the time over 10 or more ratings in 28 days is left off Today. Today says so, with the numbers and a **restore** button. The trigger is still scanned. A restore holds until 10 new ratings of that trigger have arrived.
+- **forget what it learned** makes the workspace ignore all earlier feedback from then on. Nothing is deleted.
+
+The records are `learn-events.jsonl` (restore and reset), `lessons.jsonl` and `proactive-rollups.jsonl`, in the workspace state folder. They are not committed.
+
 ## What it shows
 
 Today scans for five conditions. Each one becomes one item with the reason and the evidence.
@@ -60,7 +77,7 @@ The order is fixed and you can read it: what blocks on you first, then an unrevi
 - dismiss 7 days hides the item for 7 days.
 - something was missed records a note about what Today should have shown. It needs a note.
 
-A verdict never changes a status, a lifecycle record or an acceptance. In this release a verdict is only recorded. Nothing uses it to change the order yet.
+A verdict never changes a status, a lifecycle record or an acceptance. It is recorded, and it is evidence for what Today learns, as described above.
 
 ## Settings
 
@@ -74,7 +91,7 @@ A verdict never changes a status, a lifecycle record or an acceptance. In this r
 | name | Used in the greeting. |
 | stalled after N days | The stalled threshold, from 1 to 90 days. |
 | quiet hours | A start and an end time. No automatic scan runs between them. |
-| pause learning | Saved for later. Nothing learns from your verdicts in this release, so it changes nothing today. |
+| pause learning | Stops all learning: weights are zero, and there is no weekly review, no proposal and no narrowing. Feedback is still recorded. |
 
 ## The commands
 
@@ -83,12 +100,13 @@ A verdict never changes a status, a lifecycle record or an acceptance. In this r
 - `pmos proactive settings` shows the settings. Add `--enabled`, `--trigger NAME=on|off`, `--stalled-days`, `--quiet HH:MM-HH:MM|none`, `--pause-learning`, `--background-prepare on|off`, `--brief-source NAME=on|off`, `--brief-scoring on|off` or `--name` to change one.
 - `pmos proactive brief` shows today's brief. `pmos proactive brief submit --file PATH` submits one. `pmos proactive brief schedule` makes the 06:45 schedule for the current repository.
 - `pmos proactive prepare` shows the queue. `pmos proactive prepare plan --initiative ID` shows a plan and its hash. `pmos proactive prepare queue --initiative ID --item ITEM --sha HASH` approves it. `pmos proactive prepare cancel ID` cancels an entry. `pmos proactive prepare run` looks at the queue now.
+- `pmos proactive learn` shows the rollup, the weights, the narrowed triggers and the lessons. `pmos proactive learn run` takes the weekly review now. `pmos proactive learn lessons` lists the approved lessons. `pmos proactive learn approve ID`, `reject ID` and `retire ID` decide a lesson. `pmos proactive learn restore TRIGGER` brings back a narrowed trigger. `pmos proactive learn reset` makes it ignore earlier feedback.
 - `pmos proactive feedback <id> useful|not-useful|wrong-priority|opened|dismissed` records feedback. Use `--missed "text"` for a missed item.
 
 ## Limits
 
 - It runs only while the workspace server runs. It does not catch up for time the server was off. A sleeping computer gets no scan.
 - The items from the records come from this computer. The workspace itself does not read your mail or your calendar. Only the morning-brief session does, and only the sources you switched on.
-- It does not start a session, push, send, post, accept or merge. It only shows items and records your feedback. The one exception is background preparation, which starts a session only for a plan you approved, as described above.
+- It does not start a session, push, send, post, accept or merge. It only shows items and records your feedback, and learns from it as described above. The one exception is background preparation, which starts a session only for a plan you approved, as described above.
 - An unreadable repository is listed as not read. An empty list is not proof that nothing waits there.
 - The records stay in the workspace state folder on this computer. They are not committed.

package/workspace/guide/scheduled-tasks-and-cli.md

@@ -1,6 +1,7 @@
 ---
 type: Guide
 title: "Guide: scheduled tasks and the command line"
+description: "How scheduled tasks run a skill in a terminal session, their limits, and the command line that manages them."
 timestamp: 2026-10-03
 ---
 

package/workspace/guide/statuses.md

@@ -1,6 +1,7 @@
 ---
 type: Guide
 title: "Guide: statuses"
+description: "The nine initiative statuses, who acts on each, and why a status is worked out again each time and never typed."
 timestamp: 2026-10-03
 ---
 

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 };