create-pmos 0.37.0 → 0.38.1

package/payload/scripts/pmos-memory.js

@@ -0,0 +1,375 @@
+#!/usr/bin/env node
+'use strict';
+/* pmos-memory — curated repository memory (D72).
+ *
+ *   node pmos-memory.js add     --text "…" [--target memory|user] [--confidence unconfirmed] [--source kind:ref] [--stale-after YYYY-MM-DD]
+ *   node pmos-memory.js replace --old "unique substring" --text "…" [--target …]
+ *   node pmos-memory.js remove  --old "unique substring" [--target …]
+ *   node pmos-memory.js confirm --old "unique substring"
+ *   node pmos-memory.js search "words" [--limit 8]      ranks memory AND the requirement/report notes (lexical, not semantic)
+ *   node pmos-memory.js list | pending | snapshot | approve <eid> | reject <eid>      (all take --root <repo>, --json)
+ *
+ * The LEDGER is the truth: <state>/memory/memory.jsonl, append-only. The current entries are FOLDED
+ * from it by (event time, event id) — never by file position — so two machines appending the same file
+ * (merge=union) fold to the same result, and a duplicated line is harmless. The views MEMORY.md and
+ * USER.md are generated, git-ignored, and rebuilt at session start: a session reads them once (a frozen
+ * snapshot) and sees its own writes only in the next one.
+ *
+ * This is the harness pattern Hermes uses (bounded curated files, add/replace/remove by unique
+ * substring, a capacity error that lists the entries, a frozen snapshot, optional write approval, a
+ * scan for injection and credentials) with three changes: the store lives in the repository so it
+ * travels with Sync, entries carry provenance and staleness, and the scan runs on READ as well as on
+ * write — an agent can append to the file by hand, so the writer cannot be the only guard.
+ */
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+
+const TARGETS = ['memory', 'user'];
+const DEFAULTS = { memory_chars: 2200, user_chars: 1375, write_approval: false };
+const CONFIDENCE = ['confirmed', 'unconfirmed'];
+const HUMAN = /^human:/;
+
+// ── paths ────────────────────────────────────────────────────────────────────────────────────
+function stateDir(root, create) {
+  const kit = path.join(root, 'pmos', 'state');
+  const self = path.join(root, 'planning');
+  if (fs.existsSync(kit)) return kit;
+  if (fs.existsSync(self)) return self;
+  if (create) { fs.mkdirSync(kit, { recursive: true }); return kit; }
+  return null;
+}
+function memDir(root, create) {
+  const s = stateDir(root, create);
+  if (!s) return null;
+  const d = path.join(s, 'memory');
+  if (create) fs.mkdirSync(d, { recursive: true });
+  return d;
+}
+
+// ── the scan ─────────────────────────────────────────────────────────────────────────────────
+const SCAN = [
+  ['prompt injection', /\b(ignore|disregard|forget)\b[^.\n]{0,40}\b(previous|prior|above|earlier|all)\b[^.\n]{0,30}\b(instruction|prompt|rule|direction)s?\b/i],
+  ['prompt injection', /\b(you are now|from now on you|act as if you have no|reveal (your|the) (system )?prompt|new instructions:)/i],
+  ['prompt injection', /<\s*\/?\s*(system|assistant|instructions?)\s*>/i],
+  ['credential', /\b(AKIA[0-9A-Z]{16}|gh[pousr]_[A-Za-z0-9]{30,}|sk-[A-Za-z0-9_-]{20,}|xox[abprs]-[A-Za-z0-9-]{10,}|AIza[0-9A-Za-z_-]{30,})\b/],
+  ['credential', /-----BEGIN [A-Z ]*PRIVATE KEY-----/],
+  ['credential', /\b(password|passwd|secret|api[_-]?key|token)\s*[:=]\s*\S{6,}/i],
+  ['exfiltration', /\b(curl|wget|nc|ncat)\b[^\n]{0,80}(\$\w+|\$\{|`|\|\s*(sh|bash))/i],
+  ['backdoor', /\bauthorized_keys\b|\bssh-(rsa|ed25519)\s+AAAA/i],
+  ['invisible character', /[​-‏‪-‮⁠-⁤]/],
+];
+function scan(text) {
+  const t = String(text == null ? '' : text);
+  for (const [name, re] of SCAN) if (re.test(t)) return name;
+  return null;
+}
+
+// ── the ledger ───────────────────────────────────────────────────────────────────────────────
+function readEvents(dir) {
+  const file = path.join(dir, 'memory.jsonl');
+  let text = '';
+  try { text = fs.readFileSync(file, 'utf8'); } catch { return { events: [], torn: 0 }; }
+  const events = []; let torn = 0;
+  for (const line of text.split('\n')) {
+    if (!line.trim()) continue;
+    try { const e = JSON.parse(line); if (e && typeof e === 'object' && e.eid && e.op) events.push(e); else torn++; }
+    catch { torn++; }
+  }
+  return { events, torn };
+}
+function readConfig(dir) {
+  try { return { ...DEFAULTS, ...JSON.parse(fs.readFileSync(path.join(dir, 'config.json'), 'utf8')) }; }
+  catch { return { ...DEFAULTS }; }
+}
+const byTime = (a, b) => String(a.at).localeCompare(String(b.at)) || String(a.eid).localeCompare(String(b.eid));
+
+/* Fold the events to the current state. Pure and order-independent: events are de-duplicated by eid
+ * and sorted by (at, eid) before they are applied. */
+function fold(events, now) {
+  const seen = new Map();
+  for (const e of events) if (!seen.has(e.eid)) seen.set(e.eid, e);
+  const all = [...seen.values()].sort(byTime);
+  const decided = new Map();                       // staged eid -> 'approve' | 'reject'
+  for (const e of all) if (e.op === 'approve' || e.op === 'reject') decided.set(e.ref, e.op);
+  const entries = new Map(); const pending = []; const blocked = [];
+  const nowMs = now ? Date.parse(now) : Date.now();
+  // Two passes. ADDs first, in any order, so that a replace / remove / confirm finds the entry it names even when
+  // its timestamp sorts before the add's (two machines whose clocks disagree by a second, or two events in the
+  // same millisecond). The other operations then apply in (time, id) order. An operation naming an id that no add
+  // created is ignored.
+  const pass = [e => e.op === 'add', e => e.op !== 'add'];
+  for (const wanted of pass) for (const e of all) {
+    if (!wanted(e)) continue;
+    if (!['add', 'replace', 'remove', 'confirm'].includes(e.op)) continue;
+    if (e.op !== 'confirm' && e.staged) {
+      const d = decided.get(e.eid);
+      if (d === 'reject') continue;
+      if (d !== 'approve') { pending.push(e); continue; }
+    }
+    if (e.op === 'add' || e.op === 'replace') {
+      const hit = scan(e.text);
+      if (hit) { blocked.push({ eid: e.eid, op: e.op, reason: hit, by: e.by, at: e.at }); continue; }
+    }
+    if (e.op === 'add') {
+      if (!TARGETS.includes(e.target)) continue;
+      entries.set(e.eid, { id: e.eid, target: e.target, text: String(e.text), confidence: e.confidence === 'confirmed' ? 'confirmed' : 'unconfirmed',
+        source: e.source || null, by: e.by || 'unknown', at: e.at, updated_at: e.at, stale_after: e.stale_after || null, verified: [] });
+    } else if (e.op === 'replace') {
+      const cur = entries.get(e.id); if (!cur) continue;
+      cur.text = String(e.text); cur.updated_at = e.at; cur.by = e.by || cur.by;
+      if (e.confidence) cur.confidence = e.confidence === 'confirmed' ? 'confirmed' : 'unconfirmed';
+      if (e.source) cur.source = e.source;
+      if (e.stale_after !== undefined) cur.stale_after = e.stale_after || null;
+      cur.verified = [];
+    } else if (e.op === 'remove') {
+      entries.delete(e.id);
+    } else if (e.op === 'confirm') {
+      const cur = entries.get(e.id); if (!cur) continue;
+      cur.confidence = 'confirmed'; cur.verified.push({ by: e.by, at: e.at });
+    }
+  }
+  const list = [...entries.values()].map((x) => ({ ...x, stale: !!(x.stale_after && Date.parse(x.stale_after) <= nowMs) }));
+  return { entries: list, pending, blocked };
+}
+
+const used = (entries, target) => entries.filter((e) => e.target === target).reduce((n, e) => n + e.text.length + 1, 0);
+function usage(state, cfg) {
+  const out = {};
+  for (const t of TARGETS) {
+    const limit = cfg[`${t}_chars`]; const u = used(state.entries, t);
+    out[t] = { used: u, limit, percent: Math.round((u / limit) * 100) };
+  }
+  return out;
+}
+
+// ── the guarded append ───────────────────────────────────────────────────────────────────────
+// Sink fixed from the caller's root; validate before open; O_NOFOLLOW; single link; torn-append rollback.
+function appendEvent(dir, ev) {
+  const file = path.join(dir, 'memory.jsonl');
+  const dst = fs.lstatSync(dir);
+  if (!dst.isDirectory() || dst.isSymbolicLink()) throw new Error('the memory directory is not a plain directory — nothing was written');
+  const flags = fs.constants.O_WRONLY | fs.constants.O_APPEND | fs.constants.O_CREAT | (fs.constants.O_NOFOLLOW || 0);
+  const fd = fs.openSync(file, flags, 0o644);
+  try {
+    const st = fs.fstatSync(fd);
+    if (!st.isFile() || st.nlink !== 1) throw new Error('memory.jsonl is not a plain single-link file — nothing was written');
+    const before = st.size;
+    const line = JSON.stringify(ev) + '\n';
+    const buf = Buffer.from(line, 'utf8');
+    const n = fs.writeSync(fd, buf);
+    if (n !== buf.length) { try { fs.ftruncateSync(fd, before); } catch { /* best effort */ } throw new Error('short write — rolled back'); }
+  } finally { fs.closeSync(fd); }
+}
+const nowIso = () => new Date().toISOString();
+// An event id sorts in the order events were made: a zero-padded millisecond, then a per-process counter (two
+// writes in the same millisecond keep their order), then random bytes to keep ids from different machines apart.
+let _seq = 0;
+const newEid = () => 'm-' + Date.now().toString(36).padStart(9, '0') + '-' + String(_seq++ % 1000).padStart(3, '0') + '-' + crypto.randomBytes(3).toString('hex');
+
+function load(root) {
+  const dir = memDir(root, false);
+  const { events, torn } = dir ? readEvents(dir) : { events: [], torn: 0 };
+  const cfg = dir ? readConfig(dir) : { ...DEFAULTS };
+  const state = fold(events, nowIso());
+  return { dir, cfg, state, torn, usage: usage(state, cfg) };
+}
+
+function listFor(state, target) { return state.entries.filter((e) => e.target === target); }
+function matchOne(state, target, sub) {
+  const s = String(sub || '').trim();
+  if (!s) return { ok: false, error: 'a substring that identifies one entry is required (--old)' };
+  const pool = listFor(state, target);
+  const exact = pool.filter((e) => e.text === s);
+  const hits = exact.length === 1 ? exact : pool.filter((e) => e.text.includes(s));
+  if (hits.length === 1) return { ok: true, entry: hits[0] };
+  return { ok: false, error: hits.length ? `'${s}' matches ${hits.length} entries — use a longer, unique substring` : `'${s}' matches no entry in ${target}`, entries: pool };
+}
+
+/* One write. `actor` is 'human:<id>' (the PM, via the workspace) or an agent label. With
+ * write_approval on, a non-human add/replace/remove is staged, not applied. */
+function write(root, req) {
+  const op = req.op;
+  const target = req.target || 'memory';
+  if (!TARGETS.includes(target)) return { ok: false, error: `target must be one of ${TARGETS.join(', ')}` };
+  const cur = load(root);
+  const dir = memDir(root, true);
+  const cfg = cur.dir ? cur.cfg : readConfig(dir);
+  const actor = req.by || 'agent:cli';
+  const at = nowIso();
+  const staged = !HUMAN.test(actor) && !!cfg.write_approval && ['add', 'replace', 'remove'].includes(op);
+  let ev;
+  if (op === 'add' || op === 'replace') {
+    const text = String(req.text == null ? '' : req.text).trim();
+    if (!text) return { ok: false, error: 'text is required' };
+    if (text.length > 600) return { ok: false, error: 'an entry is a short fact: 600 characters at most' };
+    const hit = scan(text);
+    if (hit) return { ok: false, error: `blocked by the scan (${hit}) — nothing was written` };
+    const conf = req.confidence || (HUMAN.test(actor) ? 'confirmed' : 'unconfirmed');
+    if (!CONFIDENCE.includes(conf)) return { ok: false, error: `confidence must be ${CONFIDENCE.join(' or ')}` };
+    let id = null; let delta = text.length + 1;
+    if (op === 'replace') {
+      const m = matchOne(cur.state, target, req.old);
+      if (!m.ok) return m;
+      id = m.entry.id; delta = text.length - m.entry.text.length;
+    }
+    const limit = cfg[`${target}_chars`]; const u = used(cur.state.entries, target);
+    if (u + delta > limit) {
+      return { ok: false, error: `${target} is full (${u}/${limit} chars) and this write needs ${delta} more — merge or remove entries first`, entries: listFor(cur.state, target), usage: cur.usage };
+    }
+    ev = { eid: newEid(), at, by: actor, op, target, ...(id ? { id } : {}), text, confidence: conf,
+      ...(req.source ? { source: req.source } : {}), ...(req.stale_after ? { stale_after: req.stale_after } : {}), ...(staged ? { staged: true } : {}) };
+  } else if (op === 'remove' || op === 'confirm') {
+    const m = matchOne(cur.state, target, req.old || req.text);
+    if (!m.ok) return m;
+    ev = { eid: newEid(), at, by: actor, op, target, id: m.entry.id, ...(staged ? { staged: true } : {}) };
+    if (op === 'confirm' && !HUMAN.test(actor)) return { ok: false, error: 'only the PM confirms an entry' };
+  } else if (op === 'approve' || op === 'reject') {
+    if (!HUMAN.test(actor)) return { ok: false, error: 'only the PM approves or rejects a pending write' };
+    if (!cur.state.pending.some((p) => p.eid === req.ref)) return { ok: false, error: `no pending write ${req.ref}` };
+    ev = { eid: newEid(), at, by: actor, op, ref: req.ref };
+  } else return { ok: false, error: `unknown operation '${op}'` };
+  try { appendEvent(dir, ev); } catch (e) { return { ok: false, error: String((e && e.message) || e) }; }
+  const after = render(root);
+  return { ok: true, event: ev, staged, usage: after.usage };
+}
+
+// ── the frozen snapshot ──────────────────────────────────────────────────────────────────────
+function viewFor(target, state, usageT, cfg, at) {
+  const title = target === 'memory' ? 'Repository memory' : 'About the PM';
+  const lines = [
+    '---', 'type: Memory', `title: "${title}"`,
+    `description: "Curated ${target === 'memory' ? 'facts about the product and domain' : 'preferences and working style of the PM'} — a snapshot generated from the memory ledger (D72). Edit with pmos-memory, not by hand."`,
+    `generated: {by: process:pmos-memory, at: "${at}"}`, 'status: stable', '---', '',
+    `# ${title} [${usageT.percent}% — ${usageT.used}/${usageT.limit} chars]`, '',
+  ];
+  if (usageT.percent >= 80) lines.push('> Above 80% full: merge or remove entries before adding.', '');
+  const es = listFor(state, target).sort(byTime);
+  if (!es.length) lines.push('_Nothing recorded yet._');
+  for (const e of es) {
+    const tags = [e.confidence === 'unconfirmed' ? 'UNCONFIRMED' : null, e.stale ? 'STALE' : null].filter(Boolean);
+    const src = e.source ? ` · source: ${e.source}` : '';
+    lines.push(`- ${tags.length ? `(${tags.join(', ')}) ` : ''}${e.text}  <!-- ${e.id}${src} · ${e.by} · ${String(e.at).slice(0, 10)} -->`);
+  }
+  lines.push('');
+  return lines.join('\n');
+}
+function render(root) {
+  const cur = load(root);
+  const dir = cur.dir;
+  if (!dir) return { ok: true, rendered: false, usage: cur.usage };
+  const at = nowIso();
+  for (const t of TARGETS) {
+    const file = path.join(dir, t === 'memory' ? 'MEMORY.md' : 'USER.md');
+    try { if (fs.lstatSync(file).isSymbolicLink()) continue; } catch { /* absent */ }
+    fs.writeFileSync(file, viewFor(t, cur.state, cur.usage[t], cur.cfg, at));
+  }
+  const gi = path.join(dir, '.gitignore');
+  const want = 'MEMORY.md\nUSER.md\n';
+  try { if (fs.readFileSync(gi, 'utf8') !== want) fs.writeFileSync(gi, want); } catch { fs.writeFileSync(gi, want); }
+  return { ok: true, rendered: true, usage: cur.usage, blocked: cur.state.blocked, pending: cur.state.pending.length };
+}
+
+
+// ── search (R11) ─────────────────────────────────────────────────────────────────────────────
+// LEXICAL recall over what a repository already knows: its memory entries and the requirement and report notes
+// PMOS's agents filed. BM25 over words — it finds what shares words with the query, and does NOT understand
+// meaning; the output says so. No model, no network, no dependency. Past SESSIONS are searched elsewhere
+// (the workspace's /api/search), per machine.
+const STOP = new Set('the and for with that this from are was were have has had not but you your our their its can will may all any one two per via into out off than then them they she him her who why how what when where which while about over under also more most some such only very just'.split(' '));
+const stem = (w) => (w.length > 4 && /[^s]s$/.test(w) ? w.slice(0, -1) : w);   // crude plural folding, nothing more
+const tokens = (t) => (String(t || '').toLowerCase().match(/[a-z0-9][a-z0-9'-]{1,}/g)?.filter((w) => w.length > 2 && !STOP.has(w)) || []).map(stem);
+function noteChunks(root) {
+  const st = stateDir(root, false); if (!st) return [];
+  const out = [];
+  const walk = (dir, depth) => {
+    let ents = []; try { ents = fs.readdirSync(dir, { withFileTypes: true }); } catch { return; }
+    for (const e of ents) {
+      const p = path.join(dir, e.name);
+      if (e.isSymbolicLink()) continue;
+      if (e.isDirectory() && depth < 4) walk(p, depth + 1);
+      else if (e.isFile() && e.name.endsWith('.md') && !['index.md', 'log.md'].includes(e.name)) {
+        let text = ''; try { text = fs.readFileSync(p, 'utf8'); } catch { continue; }
+        const body = text.replace(/^---\r?\n[\s\S]*?\r?\n---\r?\n?/, '');
+        const rel = path.relative(root, p).split(path.sep).join('/');
+        let buf = '';
+        const flush = () => { const t = buf.trim(); if (t.length > 20) out.push({ source: `note:${rel}`, text: t.slice(0, 420) }); buf = ''; };
+        for (const line of body.split('\n')) { if (!line.trim() || /^#{1,6}\s/.test(line)) flush(); if (line.trim()) buf += (buf ? ' ' : '') + line.replace(/^#{1,6}\s*/, '').trim(); if (buf.length > 320) flush(); }
+        flush();
+      }
+    }
+  };
+  for (const sub of ['requirements', 'reports']) walk(path.join(st, sub), 0);
+  walk(path.join(root, 'reports'), 0);
+  return out;
+}
+function search(root, query, limit) {
+  const q = tokens(query);
+  if (!q.length) return { ok: false, error: 'a query with at least one real word is required' };
+  const cur = load(root);
+  const docs = [
+    ...cur.state.entries.map((e) => ({ source: `memory:${e.target}`, id: e.id, text: e.text, confidence: e.confidence, stale: e.stale })),
+    ...noteChunks(root),
+  ];
+  if (!docs.length) return { ok: true, method: 'lexical', hits: [], searched: 0, note: 'nothing to search yet' };
+  const toks = docs.map((d) => tokens(d.text));
+  const avg = toks.reduce((n, t) => n + t.length, 0) / docs.length || 1;
+  const df = new Map(); for (const t of toks) for (const w of new Set(t)) df.set(w, (df.get(w) || 0) + 1);
+  const N = docs.length; const k1 = 1.4; const b = 0.75;
+  const hits = [];
+  docs.forEach((d, i) => {
+    const tf = new Map(); for (const w of toks[i]) tf.set(w, (tf.get(w) || 0) + 1);
+    let score = 0;
+    for (const w of q) { const f = tf.get(w); if (!f) continue; const idf = Math.log(1 + (N - df.get(w) + 0.5) / (df.get(w) + 0.5)); score += idf * ((f * (k1 + 1)) / (f + k1 * (1 - b + b * (toks[i].length / avg)))); }
+    if (score > 0) hits.push({ ...d, score: Math.round(score * 1000) / 1000 });
+  });
+  hits.sort((a, c) => c.score - a.score || String(a.source).localeCompare(String(c.source)));
+  return { ok: true, method: 'lexical', note: 'ranked by shared words, not by meaning', searched: docs.length, hits: hits.slice(0, Math.max(1, Math.min(25, +limit || 8))) };
+}
+
+// ── CLI ──────────────────────────────────────────────────────────────────────────────────────
+function main(argv) {
+  const a = argv.slice(2);
+  const cmd = a[0];
+  const opt = {}; const rest = [];
+  for (let i = 1; i < a.length; i++) {
+    if (a[i].startsWith('--')) { const k = a[i].slice(2); if (k === 'json') opt.json = true; else opt[k] = a[++i]; } else rest.push(a[i]);
+  }
+  const root = path.resolve(opt.root || process.cwd());
+  const say = (o) => process.stdout.write(opt.json ? JSON.stringify(o, null, 2) + '\n' : '');
+  if (!cmd || cmd === 'help' || cmd === '--help') {
+    process.stdout.write('usage: pmos-memory.js add|replace|remove|confirm|search|list|pending|snapshot|approve|reject [--text … --old … --target memory|user --confidence … --source … --stale-after … --root <repo> --json]\n');
+    return cmd ? 0 : 1;
+  }
+  if (cmd === 'search') {
+    const r = search(root, rest.join(' ') || opt.q, opt.limit);
+    if (opt.json) { say(r); return r.ok ? 0 : 2; }
+    if (!r.ok) { process.stderr.write(`${r.error}\n`); return 2; }
+    process.stdout.write(`${r.hits.length} hit(s) of ${r.searched} searched — ${r.note}\n`);
+    for (const h of r.hits) process.stdout.write(`  [${h.source}${h.confidence === 'unconfirmed' ? ', unconfirmed' : ''}${h.stale ? ', stale' : ''}] ${h.text.slice(0, 160)}\n`);
+    return 0;
+  }
+  if (cmd === 'list' || cmd === 'pending' || cmd === 'snapshot') {
+    if (cmd === 'snapshot') { const r = render(root); say(r); if (!opt.json) process.stdout.write(r.rendered ? `snapshot rebuilt — memory ${r.usage.memory.percent}%, user ${r.usage.user.percent}%\n` : 'no memory directory yet\n'); return 0; }
+    const cur = load(root);
+    if (opt.json) { say({ entries: cur.state.entries, pending: cur.state.pending, blocked: cur.state.blocked, usage: cur.usage, torn: cur.torn }); return 0; }
+    if (cmd === 'pending') { for (const p of cur.state.pending) process.stdout.write(`${p.eid}  ${p.op} ${p.target}  ${p.text || p.id}  (${p.by})\n`); return 0; }
+    for (const t of TARGETS) {
+      process.stdout.write(`${t} [${cur.usage[t].percent}% — ${cur.usage[t].used}/${cur.usage[t].limit}]\n`);
+      for (const e of listFor(cur.state, t)) process.stdout.write(`  ${e.confidence === 'unconfirmed' ? '(unconfirmed) ' : ''}${e.stale ? '(stale) ' : ''}${e.text}\n`);
+    }
+    for (const b of cur.state.blocked) process.stdout.write(`BLOCKED ${b.eid}: ${b.reason}\n`);
+    return 0;
+  }
+  const req = { op: cmd, target: opt.target, text: opt.text, old: opt.old, confidence: opt.confidence, source: opt.source,
+    stale_after: opt['stale-after'], by: opt.by, ref: rest[0] };
+  const r = write(root, req);
+  if (opt.json) { say(r); return r.ok ? 0 : 2; }
+  if (r.ok) { process.stdout.write(`${r.staged ? 'held for the PM to approve' : 'saved'} — ${req.target || 'memory'} ${r.usage[req.target || 'memory'].percent}% full. It appears in the next session's snapshot.\n`); return 0; }
+  process.stderr.write(`not saved: ${r.error}\n`);
+  if (r.entries) for (const e of r.entries) process.stderr.write(`  - ${e.text}\n`);
+  return 2;
+}
+
+module.exports = { fold, scan, load, write, render, search, memDir, stateDir, readEvents, readConfig, usage, appendEvent, TARGETS, DEFAULTS, SCAN };
+if (require.main === module) process.exit(main(process.argv));

package/payload/scripts/pmos-model.js

@@ -0,0 +1,239 @@
+#!/usr/bin/env node
+'use strict';
+/* pmos-model — model routing by tier (D75).
+ *
+ *   node pmos-model.js show                         the policy in force (defaults, or the PM's file)
+ *   node pmos-model.js init                         write the defaults to <state>/models/policy.json for the PM to edit
+ *   node pmos-model.js recommend "the work" [--skill x] [--agent claude]
+ *   node pmos-model.js resolve [--skill x] [--tier fast|balanced|deep] [--agent claude]
+ *   node pmos-model.js buckets                      evaluator models seen in evals.jsonl (calibration is per model, D40)
+ *
+ * PMOS routes on TIERS, never on a model name: the PM maps a tier to a model and an effort in
+ * <state>/models/policy.json, and the defaults use the harness's own aliases (haiku, sonnet, opus) so they
+ * follow the latest model of each size instead of pinning an id that will age. Nothing here fetches a price,
+ * a catalogue or a benchmark: a cost is only ever the PM's own relative `cost_rank`.
+ *
+ * A launch form is known only for a binary someone has CHECKED (today: claude, against its own --help). For any
+ * other binary, and for a shell, no flag is guessed: the answer is "no model control", and callers must say so.
+ */
+const fs = require('fs');
+const path = require('path');
+
+const TIERS = ['fast', 'balanced', 'deep'];
+const EFFORTS = ['low', 'medium', 'high', 'xhigh', 'max'];       // from `claude --help`: --effort <level>
+const MODEL_RE = /^[A-Za-z0-9][A-Za-z0-9._:\/-]{0,80}$/;            // a plain token: nothing a shell would interpret
+
+const DEFAULT_POLICY = {
+  version: 1,
+  tiers: {
+    fast: { model: 'haiku', effort: 'low', cost_rank: 1 },
+    balanced: { model: 'sonnet', effort: 'medium', cost_rank: 2 },
+    deep: { model: 'opus', effort: 'high', cost_rank: 3 },
+  },
+  routes: [
+    { match: { skill: 'evaluator' }, tier: 'deep', pinned: true, why: 'review work stays on one model so its calibration means something (D40)' },
+    { match: { skill: 'memory-groom' }, tier: 'fast', why: 'routine review of a small store' },
+    { match: { skill: 'report-daily' }, tier: 'fast', why: 'a short end-of-day summary' },
+    { match: { skill: 'backlog-triage' }, tier: 'fast', why: 'sorting, not deciding' },
+    { match: { skill: 'skill-discover' }, tier: 'balanced', why: 'judging relevance and safety of text found on the web' },
+    { match: { skill: 'skill-generate' }, tier: 'balanced', why: 'drafting a skill from evidence in the repository' },
+    { match: { skill: 'gather-requirements' }, tier: 'balanced', why: 'reading many sources and judging what is a requirement' },
+    { match: { skill: 'report-weekly' }, tier: 'balanced', why: 'a weekly synthesis' },
+    { match: { skill: 'report-biweekly' }, tier: 'balanced', why: 'a two-week synthesis' },
+    { match: { skill: 'report-monthly' }, tier: 'balanced', why: 'a monthly review' },
+    { match: { skill: 'report-special' }, tier: 'balanced', why: 'a one-off report' },
+    { match: { words: ['spec', 'prd', 'architecture', 'architect', 'review', 'evaluate', 'decide', 'decision', 'strategy', 'adr', 'security', 'threat', 'contract', 'rubric', 'migration'] }, tier: 'deep', why: 'the work where a mistake is costly to find later' },
+    { match: { words: ['summarize', 'summarise', 'format', 'list', 'triage', 'groom', 'dedupe', 'rename', 'extract', 'tag', 'classify', 'sort', 'copy', 'reformat'] }, tier: 'fast', why: 'routine, mechanical work' },
+  ],
+};
+
+// ── paths ────────────────────────────────────────────────────────────────────────────────────
+function stateDir(root, create) {
+  const kit = path.join(root, 'pmos', 'state'); const self = path.join(root, 'planning');
+  if (fs.existsSync(kit)) return kit;
+  if (fs.existsSync(self)) return self;
+  if (create) { fs.mkdirSync(kit, { recursive: true }); return kit; }
+  return null;
+}
+function modelsDir(root, create) {
+  const s = stateDir(root, create); if (!s) return null;
+  const d = path.join(s, 'models'); if (create) fs.mkdirSync(d, { recursive: true });
+  return d;
+}
+
+// ── the policy ───────────────────────────────────────────────────────────────────────────────
+function validate(p) {
+  const errs = [];
+  if (!p || typeof p !== 'object' || Array.isArray(p)) return ['the policy must be a JSON object'];
+  if (!p.tiers || typeof p.tiers !== 'object') errs.push('`tiers` is required');
+  for (const t of TIERS) {
+    const x = p.tiers && p.tiers[t];
+    if (!x) { errs.push(`tier '${t}' is missing`); continue; }
+    if (typeof x.model !== 'string' || !MODEL_RE.test(x.model)) errs.push(`tier '${t}': model must be a plain token like "sonnet" or "claude-sonnet-5-5"`);
+    if (!EFFORTS.includes(x.effort)) errs.push(`tier '${t}': effort must be one of ${EFFORTS.join(', ')}`);
+    if (x.cost_rank !== undefined && !(Number.isFinite(x.cost_rank))) errs.push(`tier '${t}': cost_rank must be a number`);
+  }
+  if (p.routes !== undefined && !Array.isArray(p.routes)) errs.push('`routes` must be a list');
+  (p.routes || []).forEach((r, i) => {
+    if (!r || typeof r !== 'object') { errs.push(`route ${i}: must be an object`); return; }
+    if (!TIERS.includes(r.tier)) errs.push(`route ${i}: tier must be one of ${TIERS.join(', ')}`);
+    if (!r.match || (typeof r.match.skill !== 'string' && !Array.isArray(r.match.words))) errs.push(`route ${i}: match needs a skill or a list of words`);
+    if (r.pinned !== undefined && typeof r.pinned !== 'boolean') errs.push(`route ${i}: pinned must be true or false`);
+  });
+  return errs;
+}
+function loadPolicy(root) {
+  const dir = root ? modelsDir(root, false) : null;
+  const file = dir ? path.join(dir, 'policy.json') : null;
+  if (!file || !fs.existsSync(file)) return { ok: true, source: 'defaults', policy: DEFAULT_POLICY };
+  let parsed;
+  try { parsed = JSON.parse(fs.readFileSync(file, 'utf8')); }
+  catch (e) { return { ok: false, source: file, error: `policy.json is not valid JSON — ${String((e && e.message) || e).slice(0, 100)}` }; }
+  const errs = validate(parsed);
+  if (errs.length) return { ok: false, source: file, error: `policy.json is not usable — ${errs.join('; ')}` };
+  return { ok: true, source: file, policy: parsed };
+}
+
+const rank = (policy, tier) => (policy.tiers[tier] && policy.tiers[tier].cost_rank) ?? TIERS.indexOf(tier);
+const words = (t) => new Set(String(t || '').toLowerCase().match(/[a-z][a-z-]+/g) || []);
+
+function routeFor(policy, { skill, text }) {
+  const w = words(text);
+  for (const r of policy.routes || []) {
+    if (r.match.skill && skill && r.match.skill === skill) return r;
+    if (Array.isArray(r.match.words) && r.match.words.some((x) => w.has(String(x).toLowerCase()))) return r;
+  }
+  return null;
+}
+
+// ── launch forms: ONLY for a binary someone has checked ──────────────────────────────────────
+const LAUNCH = {
+  claude: (model, effort) => (effort ? ['--model', model, '--effort', effort] : ['--model', model]),
+};
+function launchFor(agent, resolution) {
+  if (!resolution || !resolution.tier) return { state: 'not-asked', args: [] };
+  const f = LAUNCH[agent];
+  if (!f) return { state: 'no-model-control', args: [] };
+  const { model, effort } = resolution;
+  if (!MODEL_RE.test(model) || (effort && !EFFORTS.includes(effort))) return { state: 'refused', args: [], error: `'${model}' / '${effort}' is not a plain model token and a known effort — nothing was started` };
+  return { state: 'applied', args: f(model, effort) };
+}
+
+/* ctx: { skill, text, explicit: {tier?|model?, effort?}, scheduleTier, skillTier, agent }.
+ * Order: explicit → schedule tier → skill tier → policy route → nothing. A pinned route may be raised, never lowered. */
+function resolve(root, ctx = {}) {
+  const loaded = loadPolicy(root);
+  if (!loaded.ok) return { ok: false, error: loaded.error };
+  const policy = loaded.policy;
+  const route = routeFor(policy, ctx);
+  const ex = ctx.explicit || {};
+  let tier = null; let model = null; let effort = null; let decidedBy = null; let why = '';
+  if (ex.model) {
+    if (!MODEL_RE.test(String(ex.model))) return { ok: false, error: `'${String(ex.model).slice(0, 40)}' is not a plain model token — nothing was started` };
+    if (ex.effort && !EFFORTS.includes(ex.effort)) return { ok: false, error: `effort must be one of ${EFFORTS.join(', ')}` };
+    model = String(ex.model); effort = ex.effort || null; tier = 'custom'; decidedBy = 'explicit model'; why = 'the model was named directly for this session';
+  } else if (ex.tier || ctx.scheduleTier || ctx.skillTier || route) {
+    if (ex.tier) { tier = ex.tier; decidedBy = 'explicit tier'; why = 'chosen for this session'; }
+    else if (ctx.scheduleTier) { tier = ctx.scheduleTier; decidedBy = 'schedule'; why = "the schedule's tier"; }
+    else if (ctx.skillTier) { tier = ctx.skillTier; decidedBy = 'skill'; why = "the skill's tier"; }
+    else { tier = route.tier; decidedBy = 'policy route'; why = route.why || 'a route in the policy matched'; }
+    if (!TIERS.includes(tier)) return { ok: false, error: `'${tier}' is not a tier — one of ${TIERS.join(', ')}` };
+    model = policy.tiers[tier].model; effort = ex.effort || policy.tiers[tier].effort;
+    if (ex.effort && !EFFORTS.includes(ex.effort)) return { ok: false, error: `effort must be one of ${EFFORTS.join(', ')}` };
+  }
+  if (route && route.pinned && tier) {
+    const lowered = tier === 'custom' ? model !== policy.tiers[route.tier].model : rank(policy, tier) < rank(policy, route.tier);
+    if (lowered) return { ok: false, error: `'${ctx.skill || 'this work'}' is pinned to the ${route.tier} tier (D40: review work stays on one model so its calibration means something) — ${tier === 'custom' ? model : tier} would lower it` };
+  }
+  const base = { ok: true, source: loaded.source, tier, model, effort, decidedBy, why, pinned: !!(route && route.pinned), route: route ? { tier: route.tier, why: route.why || '' } : null };
+  const launch = launchFor(ctx.agent || 'claude', tier ? base : null);
+  return { ...base, state: launch.state, args: launch.args, ...(launch.error ? { ok: false, error: launch.error } : {}) };
+}
+
+// A recommendation for work an agent is about to do. With no rule matching, the safe middle — and it says so.
+function recommend(root, text, ctx = {}) {
+  const t = String(text || '').trim();
+  if (!t && !ctx.skill) return { ok: false, error: 'say what the work is (a sentence), or name a skill' };
+  const loaded = loadPolicy(root);
+  if (!loaded.ok) return { ok: false, error: loaded.error };
+  const route = routeFor(loaded.policy, { skill: ctx.skill, text: t });
+  const tier = route ? route.tier : 'balanced';
+  const x = loaded.policy.tiers[tier];
+  return { ok: true, tier, model: x.model, effort: x.effort, pinned: !!(route && route.pinned),
+    why: route ? (route.why || 'a route in the policy matched') : 'no rule matched — balanced is the safe middle; say what is at stake if it should be deep',
+    matched: !!route, source: loaded.source };
+}
+
+// ── the decisions ledger (append-only, guarded like the memory ledger) ───────────────────────
+// Written only where the PM has opted in by creating <state>/models/ (`pmos-model init`, or the policy file): a
+// repository that never asked for model routing gets no ledger, and a test run against a checkout leaves nothing behind.
+function logDecision(root, entry) {
+  try {
+    const dir = modelsDir(root, false); if (!dir || !fs.existsSync(dir)) return false;
+    const file = path.join(dir, 'decisions.jsonl');
+    const ds = fs.lstatSync(dir); if (!ds.isDirectory() || ds.isSymbolicLink()) return false;
+    const fd = fs.openSync(file, fs.constants.O_WRONLY | fs.constants.O_APPEND | fs.constants.O_CREAT | (fs.constants.O_NOFOLLOW || 0), 0o644);
+    try {
+      const st = fs.fstatSync(fd); if (!st.isFile() || st.nlink !== 1) return false;
+      const before = st.size; const buf = Buffer.from(JSON.stringify({ at: new Date().toISOString(), ...entry }) + '\n');
+      if (fs.writeSync(fd, buf) !== buf.length) { try { fs.ftruncateSync(fd, before); } catch { /* best effort */ } return false; }
+    } finally { fs.closeSync(fd); }
+    return true;
+  } catch { return false; }
+}
+
+// ── evaluator models seen (D40: calibration is per model) ────────────────────────────────────
+const normModel = (m) => String(m || '').toLowerCase().trim().replace(/^anthropic\//, '');
+function evaluatorBuckets(root) {
+  const counts = {};
+  for (const f of [path.join(root, 'planning', 'runs', 'evals.jsonl'), path.join(root, 'pmos', 'state', 'evals.jsonl')]) {
+    let text = ''; try { text = fs.readFileSync(f, 'utf8'); } catch { continue; }
+    for (const line of text.split('\n')) { if (!line.trim()) continue; try { const m = normModel(JSON.parse(line).evaluator_model); if (m) counts[m] = (counts[m] || 0) + 1; } catch { /* torn */ } }
+  }
+  return counts;
+}
+function evaluatorNote(root, model) {
+  const b = evaluatorBuckets(root); const m = normModel(model);
+  if (!m) return null;
+  return b[m] ? null : `'${m}' has no recorded evaluator verdicts here: its calibration starts at zero and the Review Gate stays advisory for it (D40).`;
+}
+
+// ── CLI ──────────────────────────────────────────────────────────────────────────────────────
+function main(argv) {
+  const a = argv.slice(2); const cmd = a[0]; const opt = {}; const rest = [];
+  for (let i = 1; i < a.length; i++) { if (a[i].startsWith('--')) { const k = a[i].slice(2); if (k === 'json') opt.json = true; else opt[k] = a[++i]; } else rest.push(a[i]); }
+  const root = path.resolve(opt.root || process.cwd());
+  const out = (o, human) => { process.stdout.write(opt.json ? JSON.stringify(o, null, 2) + '\n' : human + '\n'); };
+  if (!cmd || cmd === 'help' || cmd === '--help') { process.stdout.write('usage: pmos-model.js show | init | recommend "the work" [--skill x] | resolve [--skill x] [--tier t] | buckets   [--root <repo>] [--json]\n'); return cmd ? 0 : 1; }
+  if (cmd === 'show') {
+    const l = loadPolicy(root); if (!l.ok) { process.stderr.write(l.error + '\n'); return 2; }
+    out(l, `policy: ${l.source}\n${TIERS.map((t) => `  ${t.padEnd(9)} ${l.policy.tiers[t].model} · effort ${l.policy.tiers[t].effort}`).join('\n')}\n  ${l.policy.routes.length} route(s); first match wins`);
+    return 0;
+  }
+  if (cmd === 'init') {
+    const dir = modelsDir(root, true); const file = path.join(dir, 'policy.json');
+    if (fs.existsSync(file)) { process.stderr.write(`${file} already exists — edit it; nothing was overwritten\n`); return 2; }
+    fs.writeFileSync(file, JSON.stringify(DEFAULT_POLICY, null, 2) + '\n');
+    out({ ok: true, file }, `wrote ${file} — edit the tiers and routes to suit; the defaults use the harness's own aliases`);
+    return 0;
+  }
+  if (cmd === 'recommend') {
+    const r = recommend(root, rest.join(' ') || opt.text, { skill: opt.skill });
+    if (!r.ok) { process.stderr.write(r.error + '\n'); return 2; }
+    const launch = launchFor(opt.agent || 'claude', r);
+    if (!logDecision(root, { kind: 'recommend', work: String(rest.join(' ') || opt.text || '').slice(0, 200), skill: opt.skill || null, tier: r.tier, model: r.model, effort: r.effort, matched: r.matched, by: opt.by || 'agent:cli' })) process.stderr.write('(no decisions ledger kept: run `pmos-model init` to opt in)\n');
+    out({ ...r, launch }, `${r.tier} → ${r.model} (effort ${r.effort})${r.pinned ? ' · pinned' : ''}\n  why: ${r.why}${launch.state === 'no-model-control' ? `\n  note: '${opt.agent}' has no verified model control in PMOS` : ''}`);
+    return 0;
+  }
+  if (cmd === 'resolve') {
+    const r = resolve(root, { skill: opt.skill, text: opt.text, agent: opt.agent || 'claude', explicit: opt.tier ? { tier: opt.tier } : (opt.model ? { model: opt.model } : {}) });
+    if (!r.ok) { process.stderr.write(r.error + '\n'); return 2; }
+    out(r, r.tier ? `${r.tier} → ${r.model} (effort ${r.effort}) · decided by ${r.decidedBy} · ${r.state}` : 'not asked — no rule matched, so no flags (the harness default)');
+    return 0;
+  }
+  if (cmd === 'buckets') { const b = evaluatorBuckets(root); out(b, Object.keys(b).length ? Object.entries(b).sort((x, y) => y[1] - x[1]).map(([m, n]) => `  ${m}  ${n} verdict(s)`).join('\n') : 'no evaluator verdicts recorded'); return 0; }
+  process.stderr.write(`unknown command '${cmd}'\n`); return 2;
+}
+
+module.exports = { DEFAULT_POLICY, TIERS, EFFORTS, MODEL_RE, validate, loadPolicy, routeFor, resolve, recommend, launchFor, logDecision, evaluatorBuckets, evaluatorNote, modelsDir, stateDir, LAUNCH };
+if (require.main === module) process.exit(main(process.argv));