create-pmos 0.36.0 → 0.38.0

package/payload/scripts/gate-initiative.sh

@@ -86,6 +86,38 @@ anchor="$(frontval parent_kr)"
 # file IS the row, so the gate is where the same rule lands. A KR or health:<id> — never blank.
 [ -n "$anchor" ] || fail "initiative '$id' has no parent_kr in $init_file — anchor it to a KR, or to a declared health budget (parent_kr: health:<id> from $KIT_ROOT/planning/okrs/health-budgets.md, D59). Unanchored work is rejected (D21)."
 
+# ---- D68: the pm-artifacts profile ------------------------------------------
+# A repository whose root holds `.pmos-profile` reading `pm-artifacts` is a PM's documents repo: its
+# lanes are strategy | prd | project-plan | discovery | decision-record | report | chore, and its
+# ladder is brief -> draft -> review -> approved -> handed off. A `light` track (the default for
+# decision-record, report, chore) needs only the anchored record above; a `governed` track (the
+# default for the rest) needs its brief to exist, and a draft it names to exist. Order is the
+# engine's to check (workflow-state.js --gate); this gate checks presence. No rubric, contract or
+# build is asked for in this profile — that is the point of it.
+profile=""
+if [ -f .pmos-profile ]; then profile="$(sed -e 's/#.*$//' -e 's/[[:space:]]//g' .pmos-profile | grep -m1 . || true)"; fi
+if [ "$profile" = "pm-artifacts" ]; then
+  pmlane="$(frontval lane)"; [ -n "$pmlane" ] || pmlane="$lane"
+  case "$pmlane" in
+    strategy|prd|project-plan|discovery|decision-record|report|chore) : ;;
+    *) note "unknown pm-artifacts lane '$pmlane' on '$id' — enforcing a governed prd (the profile's strictest, D68)."; pmlane="prd" ;;
+  esac
+  track="$(frontval track)"
+  case "$track" in
+    light|governed) : ;;
+    *) case "$pmlane" in decision-record|report|chore) track="light" ;; *) track="governed" ;; esac ;;
+  esac
+  if [ "$track" = "governed" ]; then
+    brief="$(frontval brief_path)"; [ -n "$brief" ] || brief="$prd"
+    docp="$(frontval doc_path)"
+    [ -n "$brief" ] || fail "initiative '$id' ($pmlane, governed track) has no brief — set brief_path in $init_file to a short brief (the question, the reader, the decision it informs). A light track needs none: set track: light (D68)."
+    [ -f "$brief" ] || fail "brief_path '$brief' (from $init_file) does not exist in the repo."
+    [ -z "$docp" ] || [ -f "$docp" ] || fail "doc_path '$docp' (from $init_file) does not exist in the repo."
+  fi
+  echo "✅ initiative gate PASSED — '$id' ($pmlane lane, $track track, pm-artifacts profile): $init_file exists and is anchored."
+  exit 0
+fi
+
 # ---- lane-parameterized artifact checks (D56) --------------------------------
 # The kernel invariants already held above (anchored record; the human merge stays the Acceptance
 # Gate); what varies per lane is the spec/eval artifact. In EVERY lane a rubric_path that is set

package/payload/scripts/okf-upgrade.js

@@ -0,0 +1,232 @@
+#!/usr/bin/env node
+'use strict';
+/* okf-upgrade — bring the documents PMOS writes into a TENANT repository to OKF v0.2 (D73).
+ *
+ *   node scripts/okf-upgrade.js <repo>            report what would change (nothing is written)
+ *   node scripts/okf-upgrade.js <repo> --write    apply it
+ *   node scripts/okf-upgrade.js <repo> --check    exit 1 if a document in scope is not conformant
+ *
+ * SCOPE is the documents PMOS or its agents write: requirement notes, report drafts and definitions,
+ * the memory views, the kit's seed documents, and <repo>/reports/. It never touches an initiative,
+ * a ticket, a *.jsonl ledger, needs.json, or any file outside that list, and it refuses PMOS's own
+ * repository (which follows OKF v0.2 itself since D74, with its own gate). Idempotent: a second --write changes nothing.
+ *
+ * HONESTY. `generated.by` is recorded nowhere in an old file, so the tool does not invent it: an
+ * existing `timestamp` is KEPT (OKF tolerates unknown keys) and reported as "author unknown".
+ *
+ * SINGLE-LINE FORM. Five of PMOS's frontmatter readers stop at the first indented line, so a block-style
+ * `generated:` / `sources:` / `verified:` is rewritten to one line (`generated: {by: x, at: "…"}`).
+ */
+const fs = require('fs');
+const path = require('path');
+
+const OKF_VERSION = '0.2';
+const FLOW_KEYS = ['generated', 'sources', 'verified'];
+
+// ── scope ────────────────────────────────────────────────────────────────────────────────────
+function isPmosSelf(root) { return fs.existsSync(path.join(root, 'okf', 'core', 'concepts')); }
+function stateDir(root) {
+  const kit = path.join(root, 'pmos', 'state');
+  if (fs.existsSync(kit)) return kit;
+  const self = path.join(root, 'planning');
+  return fs.existsSync(self) ? self : null;
+}
+function walkMd(dir, out) {
+  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()) walkMd(p, out);
+    else if (e.isFile() && e.name.endsWith('.md')) out.push(p);
+  }
+}
+function scopeFiles(root) {
+  const s = stateDir(root);
+  const files = [];
+  if (s) {
+    for (const sub of ['requirements', 'reports', 'memory']) walkMd(path.join(s, sub), files);
+    try { for (const n of fs.readdirSync(s)) if (n.endsWith('.md') && !['index.md', 'log.md'].includes(n)) files.push(path.join(s, n)); } catch { /* none */ }
+  }
+  walkMd(path.join(root, 'reports'), files);
+  for (const p of [path.join(root, 'pmos', 'planning', 'evals', 'eval-calibration.md'), path.join(root, 'pmos', 'planning', 'okrs', 'health-budgets.md')]) {
+    if (fs.existsSync(p)) files.push(p);
+  }
+  return [...new Set(files)].filter((f) => !['index.md', 'log.md'].includes(path.basename(f)));
+}
+
+// ── a deliberately small frontmatter reader/writer ───────────────────────────────────────────
+function split(text) {
+  const m = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/.exec(text);
+  if (!m) return { fm: null, body: text };
+  return { fm: m[1], body: m[2] };
+}
+// Top-level entries as { key, lines[] }: an entry owns its indented continuation lines.
+function entries(fm) {
+  const out = [];
+  for (const line of fm.split(/\r?\n/)) {
+    if (/^\s+\S/.test(line) && out.length) { out[out.length - 1].lines.push(line); continue; }
+    const m = /^([A-Za-z_][\w-]*)\s*:/.exec(line);
+    out.push({ key: m ? m[1] : null, lines: [line] });
+  }
+  return out;
+}
+const q = (s) => (/^[A-Za-z0-9_.\/@+-]+$/.test(s) && !/^(true|false|null|yes|no|\d+)$/i.test(s) ? s : JSON.stringify(s));
+function scalar(v) { return String(v).trim().replace(/^["']|["']$/g, ''); }
+function parseBlock(entry) {
+  const head = entry.lines[0].replace(/^[^:]*:/, '').trim();
+  const rest = entry.lines.slice(1);
+  if (head && !rest.length) return { flow: true };                       // already one line
+  if (head) return null;                                                 // something unexpected
+  const items = []; let cur = null;
+  for (const l of rest) {
+    const li = /^\s+-\s*(.*)$/.exec(l);
+    const kv = /^\s+([A-Za-z_][\w-]*)\s*:\s*(.*)$/.exec(l);
+    if (li) {
+      const inner = li[1]; const ikv = /^([A-Za-z_][\w-]*)\s*:\s*(.*)$/.exec(inner);
+      cur = ikv ? { [ikv[1]]: scalar(ikv[2]) } : { resource: scalar(inner) };
+      items.push(cur);
+    } else if (kv) {
+      if (cur && items.length) cur[kv[1]] = scalar(kv[2]);
+      else { cur = {}; items.push(cur); cur[kv[1]] = scalar(kv[2]); items.single = true; }
+    }
+  }
+  return { items, single: !!items.single };
+}
+function flowOf(key, parsed) {
+  const obj = (o) => `{${Object.entries(o).map(([k, v]) => `${k}: ${q(String(v))}`).join(', ')}}`;
+  if (key === 'generated') return `generated: ${obj(parsed.items[0] || {})}`;
+  return `${key}: [${parsed.items.map(obj).join(', ')}]`;
+}
+// Parse the items of a one-line flow list `[{k: v, k: "v"}, {…}]` back into objects. Values are bare or JSON-quoted.
+function flowItems(line) {
+  const body = line.replace(/^[^:]*:\s*/, '');
+  const out = [];
+  const objRe = /\{((?:[^{}"]|"(?:[^"\\]|\\.)*")*)\}/g; let m;
+  while ((m = objRe.exec(body))) {
+    const o = {}; const kvRe = /([A-Za-z_][\w-]*)\s*:\s*("(?:[^"\\]|\\.)*"|[^,]*)/g; let kv;
+    while ((kv = kvRe.exec(m[1]))) { let v = kv[2].trim(); if (v.startsWith('"')) { try { v = JSON.parse(v); } catch { /* keep raw */ } } o[kv[1]] = v; }
+    out.push(o);
+  }
+  return out;
+}
+function firstH1(body) { const m = /^#\s+(.+?)\s*$/m.exec(body); return m ? m[1].trim() : null; }
+function titleFromName(file) { return path.basename(file, '.md').replace(/[-_]+/g, ' ').replace(/\b\w/g, (c) => c.toUpperCase()); }
+
+// `# Citations` (or ##) list at the end of the body → sources items. Returns null when nothing converts.
+function takeCitations(body) {
+  const m = /(^|\n)#{1,3}\s+Citations\s*\n([\s\S]*?)(?=\n#{1,3}\s|\s*$)/.exec(body);
+  if (!m) return null;
+  const items = []; let unconverted = 0;
+  for (const raw of m[2].split('\n')) {
+    const l = raw.trim(); if (!l) continue;
+    const mm = /^[-*]\s+(?:\[([^\]]*)\]\(([^)]+)\)|(https?:\/\/\S+))(?:\s*[—-]\s*(.*))?$/.exec(l);
+    if (!mm) { unconverted++; continue; }
+    const resource = mm[2] || mm[3]; const title = mm[1] || mm[4] || null;
+    items.push(title ? { resource, title } : { resource });
+  }
+  return { whole: m[0], lead: m[1], items, unconverted };
+}
+
+function upgradeDoc(file, text) {
+  const notes = []; const issues = [];
+  let { fm, body } = split(text);
+  let ents;
+  if (fm === null) {
+    issues.push('no frontmatter');
+    ents = [{ key: 'type', lines: ['type: Reference'] }, { key: 'title', lines: [`title: ${q(firstH1(body) || titleFromName(file))}`] }];
+    notes.push('added type and title (type is a guess: Reference)');
+    body = text;
+  } else {
+    ents = entries(fm);
+    const has = (k) => ents.some((e) => e.key === k);
+    if (!has('type')) { issues.push('no type'); ents.unshift({ key: 'type', lines: ['type: Reference'] }); notes.push('added type: Reference (a guess)'); }
+    if (!has('title')) { issues.push('no title'); ents.splice(1, 0, { key: 'title', lines: [`title: ${q(firstH1(body) || titleFromName(file))}`] }); notes.push('added title from the first heading'); }
+    for (const e of ents) {
+      if (!FLOW_KEYS.includes(e.key) || e.lines.length < 2 && /:\s*\S/.test(e.lines[0])) continue;
+      const parsed = parseBlock(e);
+      if (parsed && parsed.items && parsed.items.length) {
+        issues.push(`block-style ${e.key} (readers stop at the first indented line)`);
+        e.lines = [flowOf(e.key, parsed)]; notes.push(`${e.key} rewritten to one line`);
+      }
+    }
+  }
+  const cit = takeCitations(body);
+  if (cit && cit.items.length) {
+    issues.push('citations in the body (v0.2 keeps them in `sources`)');
+    const src = ents.find((e) => e.key === 'sources');
+    const have = src ? flowItems(src.lines[0]) : [];
+    const merged = [...have];
+    for (const it of cit.items) if (!merged.some((h) => h.resource === it.resource)) merged.push(it);
+    const line = `sources: [${merged.map((o) => `{${Object.entries(o).map(([k, v]) => `${k}: ${q(String(v))}`).join(', ')}}`).join(', ')}]`;
+    if (src) src.lines = [line]; else ents.push({ key: 'sources', lines: [line] });
+    if (!cit.unconverted) body = body.replace(cit.whole, cit.lead ? '\n' : '');
+    else notes.push(`${cit.unconverted} citation line(s) are not links and stay in the body`);
+    notes.push(`${cit.items.length} citation(s) moved to sources`);
+  }
+  const hasTs = ents.some((e) => e.key === 'timestamp'); const hasGen = ents.some((e) => e.key === 'generated');
+  if (hasTs && !hasGen) notes.push('legacy timestamp kept — who generated it is not recorded, so generated.by is not invented');
+  const out = `---\n${ents.map((e) => e.lines.join('\n')).join('\n')}\n---\n${body}`;
+  const final = out.endsWith('\n') ? out : out + '\n';
+  return { text: final, changed: final !== text, issues, notes };
+}
+
+// ── the bundle root ──────────────────────────────────────────────────────────────────────────
+function rootIndex(dir) {
+  const names = []; try { for (const e of fs.readdirSync(dir, { withFileTypes: true })) if (!e.name.startsWith('.') && (e.isDirectory() || e.name.endsWith('.md'))) names.push(e); } catch { /* none */ }
+  const lines = ['---', `okf_version: "${OKF_VERSION}"`, '---', '', '# Knowledge bundle', '', 'Documents PMOS and its agents write in this repository (OKF v0.2, D73).', ''];
+  for (const e of names.sort((a, b) => a.name.localeCompare(b.name))) {
+    if (['index.md', 'log.md'].includes(e.name)) continue;
+    lines.push(e.isDirectory() ? `- [${e.name}/](/${e.name}/)` : `- [${e.name}](/${e.name})`);
+  }
+  return lines.join('\n') + '\n';
+}
+function rootFiles(root) {
+  const dir = stateDir(root); const todo = []; const issues = [];
+  if (!dir) return { todo, issues, dir };
+  const idx = path.join(dir, 'index.md'); const log = path.join(dir, 'log.md');
+  let idxText = null; try { idxText = fs.readFileSync(idx, 'utf8'); } catch { /* absent */ }
+  if (idxText === null) { issues.push('no bundle-root index.md'); todo.push({ file: idx, text: rootIndex(dir), note: 'created index.md with okf_version "0.2"' }); }
+  else if (!new RegExp(`^okf_version:\\s*["']?${OKF_VERSION.replace('.', '\\.')}["']?\\s*$`, 'm').test(split(idxText).fm || '')) {
+    issues.push(`bundle-root index.md does not declare okf_version "${OKF_VERSION}"`);
+    const { fm, body } = split(idxText);
+    todo.push({ file: idx, text: fm === null ? `---\nokf_version: "${OKF_VERSION}"\n---\n${idxText}` : `---\n${fm.replace(/^okf_version:.*$/m, '').replace(/\n+$/, '')}\nokf_version: "${OKF_VERSION}"\n---\n${body}`.replace(/^---\n\n/, '---\n'), note: 'set okf_version "0.2" on index.md' });
+  }
+  if (!fs.existsSync(log)) {
+    issues.push('no log.md');
+    const day = new Date().toISOString().slice(0, 10);
+    todo.push({ file: log, text: `# Log\n\nNewest first, ISO dates.\n\n## ${day}\n\n- Adopted OKF v0.2 (D73).\n`, note: 'created log.md' });
+  }
+  return { todo, issues, dir };
+}
+
+function run(root, { write = false } = {}) {
+  if (isPmosSelf(root)) return { ok: false, error: 'this is PMOS\'s own repository, which has its own Frontmatter Gate (D74) — okf-upgrade is for tenant repositories' };
+  if (!stateDir(root)) return { ok: false, error: 'no pmos/state/ or planning/ directory here — nothing to upgrade' };
+  const files = scopeFiles(root); const results = [];
+  for (const f of files) {
+    const text = fs.readFileSync(f, 'utf8');
+    const r = upgradeDoc(f, text);
+    results.push({ file: path.relative(root, f), ...r });
+    if (write && r.changed) fs.writeFileSync(f, r.text);
+  }
+  const rf = rootFiles(root);
+  for (const t of rf.todo) { results.push({ file: path.relative(root, t.file), changed: true, issues: [], notes: [t.note], rootFile: true }); if (write) fs.writeFileSync(t.file, t.text); }
+  const issues = results.flatMap((r) => r.issues.map((i) => ({ file: r.file, issue: i }))).concat(rf.issues.map((i) => ({ file: path.relative(root, path.join(rf.dir, 'index.md')), issue: i })));
+  return { ok: true, write, scanned: files.length, results, issues, changed: results.filter((r) => r.changed).length };
+}
+
+function main(argv) {
+  const a = argv.slice(2); const flags = a.filter((x) => x.startsWith('--')); const pos = a.filter((x) => !x.startsWith('--'));
+  const root = path.resolve(pos[0] || process.cwd());
+  const write = flags.includes('--write'); const check = flags.includes('--check');
+  const r = run(root, { write: write && !check });
+  if (!r.ok) { process.stderr.write(`okf-upgrade: ${r.error}\n`); return 2; }
+  if (flags.includes('--json')) { process.stdout.write(JSON.stringify(r, null, 2) + '\n'); return check && r.issues.length ? 1 : 0; }
+  for (const x of r.results) if (x.changed || x.issues.length) process.stdout.write(`${x.changed ? (write && !check ? 'upgraded' : 'would change') : 'ok'}  ${x.file}\n${x.notes.map((n) => `    · ${n}`).join('\n')}${x.notes.length ? '\n' : ''}`);
+  process.stdout.write(`\n${r.scanned} document(s) in scope · ${r.issues.length} not conformant · ${check ? 'check only' : write ? `${r.changed} written` : `${r.changed} would change — nothing written; add --write to apply`}\n`);
+  return check && r.issues.length ? 1 : 0;
+}
+
+module.exports = { run, upgradeDoc, scopeFiles, isPmosSelf, OKF_VERSION };
+if (require.main === module) process.exit(main(process.argv));

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