create-pmos 0.37.0 → 0.38.0

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

package/payload/scripts/pmos-skills.js

@@ -0,0 +1,274 @@
+#!/usr/bin/env node
+'use strict';
+/* pmos-skills — the directory of discovered and generated skills (D76).
+ *
+ *   node pmos-skills.js add --id my-skill --file ./downloaded.skill --url https://… --license MIT --author someone --why "…" [--origin discovered|generated]
+ *   node pmos-skills.js list | show <id> [--sha <12>] | reject <id> --sha <12> --reason "…" | retire <id> --sha <12> [--root <repo>] [--json]
+ *
+ * THE POINT OF THIS MODULE IS WHAT IT WILL NOT DO. A skill here is a prompt that runs with the PM's tools and
+ * accounts, and the loader re-reads skill files on every call, so a downloaded file is runnable the moment it lands.
+ * Therefore:
+ *   · `add` puts a text file in QUARANTINE and records provenance. It cannot approve anything. There is no approve
+ *     command in this file at all: approval is a PM press in the workspace, recorded in the workspace's own runtime
+ *     state on that machine (outside the repository, so a commit or a hand-edited registry cannot approve for the PM).
+ *   · the registry in the repository is SUBTRACTIVE-SAFE: anyone may append `add`, `reject` and `retire`, and none of
+ *     them can make a skill run.
+ *   · a file is accepted only as ONE text file of at most 40 KB; archives, binaries, NUL bytes and non-UTF-8 are refused.
+ *   · a critical finding refuses the file outright (nothing is stored); soft findings are stored and shown.
+ *   · the scanner is evadable (the repo's own SECURITY note says so). It is a filter, not a verdict: the PM reading
+ *     the full text, and the loader re-hashing it, are the controls.
+ */
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+const memory = require('./pmos-memory.js');
+
+const MAX_BYTES = 40 * 1024;
+const ID_RE = /^[a-z0-9][a-z0-9-]{0,48}$/;
+const ORIGINS = ['discovered', 'generated'];
+const PERMISSIVE = new Set(['mit', 'apache-2.0', 'bsd-2-clause', 'bsd-3-clause', 'isc', 'cc0-1.0', 'unlicense', '0bsd']);
+const FORCED_KEYS = ['agent', 'run', 'surface'];       // a discovered skill's own values for these are never honoured
+
+// ── 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 skillsDir(root, create) {
+  const s = stateDir(root, create); if (!s) return null;
+  const d = path.join(s, 'skills'); if (create) fs.mkdirSync(d, { recursive: true });
+  return d;
+}
+const sha256 = (text) => crypto.createHash('sha256').update(text, 'utf8').digest('hex');
+
+// ── the scan ─────────────────────────────────────────────────────────────────────────────────
+// Critical = refuse. These are the memory scanner's rules (injection phrasing, credentials, exfiltration, a
+// planted key, invisible and bidirectional characters) — in a skill body they have no legitimate use.
+const SOFT = [
+  ['shell command', /\b(rm\s+-rf|sudo\s|chmod\s+[0-7]{3,4}|mkfs|dd\s+if=|:\(\)\s*\{|\beval\s*\(|bash\s+-c|sh\s+-c)\b/],
+  ['downloads and runs', /\b(curl|wget)\b[^\n]{0,120}\b(sh|bash|zsh|python|node)\b/i],
+  ['network fetch', /\b(curl|wget|fetch|http\.get|requests\.(get|post)|urllib)\b/i],
+  ['hidden comment', /<!--[\s\S]{0,2000}?-->/],
+  ['long encoded blob', /[A-Za-z0-9+\/=]{120,}/],
+  ['mentions credential files', /(~\/\.ssh|\bid_rsa\b|\.aws\/credentials|\.env\b|\.netrc|keychain|ANTHROPIC_API_KEY|OPENAI_API_KEY|GITHUB_TOKEN)/i],
+  ['asks to hide or skip the user', /\b(do not tell the user|don't tell the user|without (asking|telling|confirm)|silently|secretly|no need to inform)\b/i],
+  ['sends data out', /\b(send|email|post|upload|forward)\b[^\n]{0,60}\b(to|at)\b[^\n]{0,40}(@|https?:\/\/)/i],
+];
+function lineOf(text, index) { return text.slice(0, index).split('\n').length; }
+function scanSkill(text) {
+  const critical = []; const soft = [];
+  const lines = text.split('\n');
+  for (const [name, re] of memory.SCAN) {
+    const g = new RegExp(re.source, re.flags.replace('g', '') + 'g'); let m;
+    while ((m = g.exec(text)) && critical.length < 20) { critical.push({ rule: name, line: lineOf(text, m.index) }); if (m.index === g.lastIndex) g.lastIndex++; }
+  }
+  for (const [name, re] of SOFT) {
+    const g = new RegExp(re.source, re.flags.replace('g', '') + 'g'); let m; let n = 0;
+    while ((m = g.exec(text)) && n < 5) { soft.push({ rule: name, line: lineOf(text, m.index) }); n++; if (m.index === g.lastIndex) g.lastIndex++; }
+  }
+  const external = [...new Set((text.match(/https?:\/\/[^\s)>"']+/g) || []))];
+  if (external.length) soft.push({ rule: `external links (${external.length})`, line: lineOf(text, text.indexOf(external[0])) });
+  void lines;
+  return { critical, soft };
+}
+// The frontmatter keys a discovered skill sets that this directory will IGNORE (the harness is forced).
+function ignoredKeys(text) {
+  const m = /^---\r?\n([\s\S]*?)\r?\n---/.exec(text); if (!m) return [];
+  const out = [];
+  for (const k of FORCED_KEYS) { const kv = new RegExp(`^${k}:\\s*(.+)$`, 'm').exec(m[1]); if (kv && !(k === 'agent' && /^["']?claude["']?$/.test(kv[1].trim())) && !(k === 'run' && /^["']?agent["']?$/.test(kv[1].trim()))) out.push(`${k}: ${kv[1].trim().slice(0, 40)}`); }
+  return out;
+}
+
+// ── validation of an incoming file ───────────────────────────────────────────────────────────
+function validateIncoming(buf) {
+  if (!Buffer.isBuffer(buf)) return 'no file content';
+  if (buf.length === 0) return 'the file is empty';
+  if (buf.length > MAX_BYTES) return `the file is ${buf.length} bytes; the limit is ${MAX_BYTES} — a skill is one short text file`;
+  if (buf.includes(0)) return 'the file contains NUL bytes — it is binary, not a text skill';
+  if (buf[0] === 0x50 && buf[1] === 0x4b) return 'the file looks like an archive — only a single text file is accepted';
+  let text; try { text = new TextDecoder('utf-8', { fatal: true }).decode(buf); } catch { return 'the file is not valid UTF-8 text'; }
+  return { text };
+}
+
+// ── the registry (append-only, in the repository) ────────────────────────────────────────────
+function readEvents(dir) {
+  let text = ''; try { text = fs.readFileSync(path.join(dir, 'registry.jsonl'), '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 && e.eid && e.op) events.push(e); else torn++; } catch { torn++; }
+  }
+  return { events, torn };
+}
+function appendEvent(dir, ev) {
+  const file = path.join(dir, 'registry.jsonl');
+  const dst = fs.lstatSync(dir);
+  if (!dst.isDirectory() || dst.isSymbolicLink()) throw new Error('the skills directory is not a plain directory — nothing was written');
+  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) throw new Error('registry.jsonl is not a plain single-link file — nothing was written');
+    const before = st.size; const buf = Buffer.from(JSON.stringify(ev) + '\n');
+    if (fs.writeSync(fd, buf) !== buf.length) { try { fs.ftruncateSync(fd, before); } catch { /* best effort */ } throw new Error('short write — rolled back'); }
+  } finally { fs.closeSync(fd); }
+}
+let _seq = 0;
+const newEid = () => 's-' + Date.now().toString(36).padStart(9, '0') + '-' + String(_seq++ % 1000).padStart(3, '0') + '-' + crypto.randomBytes(3).toString('hex');
+const byTime = (a, b) => String(a.at).localeCompare(String(b.at)) || String(a.eid).localeCompare(String(b.eid));
+
+/* Fold to one row per (id, sha). State here is only quarantined | rejected | retired: whether a candidate is APPROVED
+ * is not in this file — it is the PM's local approval, joined at load time by `resolve`. Adds first, in any order. */
+function fold(events) {
+  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 rows = new Map();
+  for (const e of all) if (e.op === 'add' && ID_RE.test(String(e.id || '')) && /^[0-9a-f]{64}$/.test(String(e.sha || ''))) {
+    const key = `${e.id}@${e.sha}`;
+    if (!rows.has(key)) rows.set(key, { id: e.id, sha: e.sha, sha12: e.sha.slice(0, 12), origin: ORIGINS.includes(e.origin) ? e.origin : 'discovered',
+      source_url: e.source_url || null, author: e.author || null, license: e.license || 'unknown', why: e.why || '', found_by: e.by || 'unknown',
+      found_at: e.at, bytes: e.bytes || null, scan: e.scan || { critical: [], soft: [] }, ignored_keys: e.ignored_keys || [], file: e.file || null, state: 'quarantined' });
+  }
+  for (const e of all) {
+    if (e.op !== 'reject' && e.op !== 'retire') continue;
+    const targets = e.sha ? [rows.get(`${e.id}@${e.sha}`)] : [...rows.values()].filter((r) => r.id === e.id);
+    for (const r of targets) if (r) { r.state = e.op === 'reject' ? 'rejected' : 'retired'; r.decided_by = e.by; r.decided_at = e.at; r.reason = e.reason || ''; }
+  }
+  return [...rows.values()];
+}
+
+const relFile = (root, id, sha) => path.posix.join(path.relative(root, skillsDir(root, false) || '').split(path.sep).join('/'), 'candidates', id, `${sha.slice(0, 12)}.skill`);
+
+/* add — agent CLI and the workspace both use it. Returns { ok, id, sha, scan } or { ok:false, error }. */
+function add(root, req) {
+  const id = String(req.id || '').trim();
+  if (!ID_RE.test(id)) return { ok: false, error: `id must be a plain slug (a-z, 0-9, hyphen; at most 49 characters), got '${id.slice(0, 40)}'` };
+  const origin = req.origin || 'discovered';
+  if (!ORIGINS.includes(origin)) return { ok: false, error: `origin must be one of ${ORIGINS.join(', ')}` };
+  const url = String(req.source_url || '').trim();
+  if (origin === 'discovered' && !/^https?:\/\/\S+$/.test(url)) return { ok: false, error: 'a discovered skill needs the http(s) URL it came from' };
+  if (!String(req.why || '').trim()) return { ok: false, error: 'say why this skill is worth the PM reading (one sentence)' };
+  const v = validateIncoming(req.content);
+  if (typeof v === 'string') return { ok: false, error: v };
+  const text = v.text; const sha = sha256(text);
+  const scan = scanSkill(text);
+  if (scan.critical.length) return { ok: false, error: `refused — ${scan.critical.slice(0, 3).map((c) => `${c.rule} (line ${c.line})`).join('; ')}. Nothing was stored.`, scan };
+  const dir = skillsDir(root, true);
+  const existing = fold(readEvents(dir).events).find((r) => r.id === id && r.sha === sha);
+  if (existing) return { ok: true, id, sha, sha12: sha.slice(0, 12), duplicate: true, state: existing.state, scan };
+  const cdir = path.join(dir, 'candidates', id); fs.mkdirSync(cdir, { recursive: true });
+  const file = path.join(cdir, `${sha.slice(0, 12)}.skill`);
+  try { const fd = fs.openSync(file, fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_EXCL | (fs.constants.O_NOFOLLOW || 0), 0o644); fs.writeSync(fd, text); fs.closeSync(fd); }
+  catch (e) { return { ok: false, error: `could not store the candidate — ${String((e && e.message) || e).slice(0, 100)}` }; }
+  const ev = { eid: newEid(), at: new Date().toISOString(), by: req.by || 'agent:cli', op: 'add', id, sha, origin, source_url: url || null,
+    author: req.author ? String(req.author).slice(0, 80) : null, license: String(req.license || 'unknown').slice(0, 40), why: String(req.why).trim().slice(0, 400),
+    bytes: Buffer.byteLength(text), scan, ignored_keys: ignoredKeys(text), file: relFile(root, id, sha) };
+  try { appendEvent(dir, ev); } catch (e) { return { ok: false, error: String((e && e.message) || e) }; }
+  render(root);
+  return { ok: true, id, sha, sha12: sha.slice(0, 12), state: 'quarantined', scan, file: ev.file };
+}
+
+function decide(root, op, req) {
+  const dir = skillsDir(root, false); if (!dir) return { ok: false, error: 'no skills directory yet' };
+  const rows = fold(readEvents(dir).events);
+  const target = rows.find((r) => r.id === req.id && (!req.sha || r.sha.startsWith(req.sha)));
+  if (!target) return { ok: false, error: `no candidate '${req.id}'${req.sha ? ` at ${req.sha}` : ''}` };
+  try { appendEvent(dir, { eid: newEid(), at: new Date().toISOString(), by: req.by || 'agent:cli', op, id: target.id, sha: target.sha, reason: String(req.reason || '').slice(0, 300) }); }
+  catch (e) { return { ok: false, error: String((e && e.message) || e) }; }
+  render(root);
+  return { ok: true, id: target.id, sha12: target.sha12, state: op === 'reject' ? 'rejected' : 'retired' };
+}
+
+function candidates(root) {
+  const dir = skillsDir(root, false); if (!dir) return { rows: [], torn: 0 };
+  const { events, torn } = readEvents(dir);
+  return { rows: fold(events), torn };
+}
+function textOf(root, row) {
+  const dir = skillsDir(root, false); if (!dir) return { ok: false, error: 'no skills directory' };
+  const file = path.join(dir, 'candidates', row.id, `${row.sha12}.skill`);
+  let st; try { st = fs.lstatSync(file); } catch { return { ok: false, error: 'the candidate file is missing' }; }
+  if (!st.isFile() || st.isSymbolicLink()) return { ok: false, error: 'the candidate file is not a plain file' };
+  const text = fs.readFileSync(file, 'utf8');
+  if (sha256(text) !== row.sha) return { ok: false, error: 'the candidate file no longer matches its recorded hash — it was changed after it was filed', changed: true };
+  return { ok: true, text, file };
+}
+
+/* resolve — what may RUN. `approvals` is the PM's LOCAL list: [{id, sha, ack_license}]. A candidate runs only if it
+ * is approved there, not rejected or retired in the registry, and its file still hashes to the approved value. */
+function resolve(root, approvals) {
+  const { rows } = candidates(root);
+  const approved = new Map(); for (const a of approvals || []) if (a && a.id && a.sha) approved.set(`${a.id}@${a.sha}`, a);
+  const skills = []; const blocked = [];
+  for (const r of rows) {
+    const key = `${r.id}@${r.sha}`; const a = approved.get(key);
+    if (!a) continue;                                                       // quarantined: simply not offered
+    if (r.state !== 'quarantined') { blocked.push({ id: r.id, sha12: r.sha12, why: `${r.state} in the registry` }); continue; }
+    const t = textOf(root, r);
+    if (!t.ok) { blocked.push({ id: r.id, sha12: r.sha12, why: t.error }); continue; }
+    skills.push({ id: r.id, sha: r.sha, sha12: r.sha12, text: t.text, file: t.file, row: r });
+  }
+  // an approved id with two approved hashes: the newest approval wins
+  const best = new Map();
+  for (const s of skills) { const prev = best.get(s.id); const ts = (approved.get(`${s.id}@${s.sha}`) || {}).at || ''; if (!prev || ts > prev.ts) best.set(s.id, { s, ts }); }
+  return { skills: [...best.values()].map((x) => x.s), blocked };
+}
+
+const licenseNeedsAck = (license) => !PERMISSIVE.has(String(license || '').toLowerCase().trim());
+
+// ── the generated directory page (OKF v0.2) ─────────────────────────────────────────────────
+function render(root) {
+  const dir = skillsDir(root, false); if (!dir) return;
+  const { rows } = candidates(root);
+  const lines = ['---', 'type: Reference', 'title: "Discovered and generated skills"',
+    'description: "Every candidate skill found or generated for this repository, with where it came from. Nothing here runs until the PM approves its exact text in the workspace."',
+    `generated: {by: process:pmos-skills, at: "${new Date().toISOString()}"}`, 'status: stable', '---', '',
+    '# Discovered and generated skills', '',
+    'A candidate is quarantined until the PM opens its text and approves it in the workspace. Approval is local to the machine that gave it. The registry is `registry.jsonl`; the text of each candidate is under `candidates/`.', '',
+    '| id | origin | state | licence | source | found | hash | findings |', '|---|---|---|---|---|---|---|---|'];
+  for (const r of rows.sort((a, b) => a.id.localeCompare(b.id) || String(b.found_at).localeCompare(String(a.found_at)))) {
+    const src = r.source_url ? `[${(r.author || 'source')}](${r.source_url})` : (r.origin === 'generated' ? 'generated here' : '—');
+    lines.push(`| ${r.id} | ${r.origin} | ${r.state} | ${r.license} | ${src} | ${String(r.found_at).slice(0, 10)} | \`${r.sha12}\` | ${(r.scan.soft || []).length ? (r.scan.soft || []).map((f) => f.rule).join(', ') : 'none'} |`);
+  }
+  if (!rows.length) lines.push('| _none yet_ | | | | | | | |');
+  lines.push('');
+  try { fs.writeFileSync(path.join(dir, 'index.md'), lines.join('\n')); } catch { /* the index is a convenience, never a reason to fail */ }
+}
+
+// ── 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-skills.js add --id <slug> --file <path> --url <https url> --license <spdx> --author <name> --why "<reason>" [--origin discovered|generated] | list | show <id> | reject <id> --sha <12> --reason "…" | retire <id> --sha <12>   [--root <repo>] [--json]\n(there is no approve command: the PM approves in the workspace)\n'); return cmd ? 0 : 1; }
+  if (cmd === 'add') {
+    let content; try { content = fs.readFileSync(path.resolve(opt.file || '')); } catch { process.stderr.write('--file must name a readable file\n'); return 2; }
+    const r = add(root, { id: opt.id, content, source_url: opt.url, license: opt.license, author: opt.author, why: opt.why, origin: opt.origin, by: opt.by });
+    if (!r.ok) { process.stderr.write(`not filed: ${r.error}\n`); return 2; }
+    out(r, `${r.duplicate ? 'already filed' : 'filed in quarantine'}: ${r.id} @ ${r.sha12} — ${(r.scan.soft || []).length} soft finding(s). It does not run until the PM approves it in the workspace.`);
+    return 0;
+  }
+  if (cmd === 'list') {
+    const { rows } = candidates(root);
+    out(rows, rows.length ? rows.map((r) => `${r.id}@${r.sha12}  ${r.origin}  ${r.state}  ${r.license}  ${(r.scan.soft || []).length} soft finding(s)`).join('\n') : 'no candidates');
+    return 0;
+  }
+  if (cmd === 'show') {
+    const { rows } = candidates(root); const r = rows.find((x) => x.id === rest[0] && (!opt.sha || x.sha.startsWith(opt.sha)));
+    if (!r) { process.stderr.write('no such candidate\n'); return 2; }
+    const t = textOf(root, r); out({ ...r, text: t.ok ? t.text : null, text_error: t.ok ? null : t.error }, `${r.id}@${r.sha12} ${r.state}\nsource: ${r.source_url}\nlicense: ${r.license}\nwhy: ${r.why}\n${t.ok ? '\n' + t.text : '\n(' + t.error + ')'}`);
+    return 0;
+  }
+  if (cmd === 'reject' || cmd === 'retire') {
+    const r = decide(root, cmd, { id: rest[0], sha: opt.sha, reason: opt.reason, by: opt.by });
+    if (!r.ok) { process.stderr.write(r.error + '\n'); return 2; }
+    out(r, `${cmd}ed ${r.id}@${r.sha12}`); return 0;
+  }
+  process.stderr.write(`unknown command '${cmd}'\n`); return 2;
+}
+
+module.exports = { MAX_BYTES, ID_RE, PERMISSIVE, FORCED_KEYS, scanSkill, ignoredKeys, validateIncoming, fold, add, decide, candidates, textOf, resolve, licenseNeedsAck, render, skillsDir, stateDir, readEvents, appendEvent, sha256 };
+if (require.main === module) process.exit(main(process.argv));