create-pmos 0.47.0 → 0.49.0

package/workspace/lib/jev-route.js

@@ -0,0 +1,139 @@
+'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;
+}
+
+/* A prompt routed from a terminal waits for its answer before it runs, so Jev gets one short try:
+ * no retries, and a few seconds. A miss falls back to the keyword route, which never moves the model. */
+const INTERACTIVE = Object.freeze({ timeoutMs: 2500, retries: 0 });
+
+/** The loopback address the workspace puts in each terminal's environment (PMOS_ROUTE_URL). */
+function routeUrl(port) {
+  const n = Number(port);
+  return Number.isInteger(n) && n > 0 && n < 65536 ? `http://127.0.0.1:${n}/api/model/route` : null;
+}
+
+module.exports = { gates, gateSentence, classify, routePrompt, modelFromPolicy, routeUrl, INTERACTIVE, 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() } = {}) {
@@ -135,6 +135,8 @@ function run(argv, { say, cwd = process.cwd(), stateDir } = {}) {
     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(`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}`);

package/workspace/lib/kg.js

@@ -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,6 +107,7 @@
     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 = [];
@@ -127,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,
@@ -196,6 +200,7 @@
       noCard: graph.nodes.filter((n) => !n.card).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,

package/workspace/lib/learn.js

@@ -248,18 +248,20 @@ function propose(rows, missed, now, lessons) {
   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` });
+    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) 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` });
+      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('; ');
-    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` });
+    // 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 || []) {