create-pmos 0.43.0 → 0.45.0

package/payload/mods/pmos-cockpit/hooks/lib/guard.mjs

@@ -0,0 +1,561 @@
+// The guards' matcher (D81, M3, M6, M8, M9, M10): what a tool call is, as far as a pure function can
+// tell. It returns findings; the module that wires it decides what to do with each.
+//
+//   ledger        a write to a *.jsonl ledger in the state root        -> deny, name the writer
+//   accept-grants a model write to acceptances or grants, or running
+//                 record-acceptance.js, pmos-log.sh accept|grant       -> deny, a person's act
+//   governing     the installed mod, .claude/pmos-cockpit.json, the
+//                 plugin entries in .claude/settings.json              -> deny, a person edits these
+//   merge         gh pr merge, the GitHub merge tools, a push to the
+//                 default branch, a forced push, npm publish           -> needs a live grant
+//   cloud         a cloud-mutating command from AGENTS.md              -> deny, the PM runs it
+//   outward       a write tool for Confluence, Jira, Slack, Gmail …    -> ask for each item
+//
+// WHAT THIS IS NOT. A shell can do what no matcher names: a path built from pieces, a script written
+// first and run second, a tool this file has never seen. The mod is defence in depth. The writers
+// validate, branch protection and CI stay the real gate where a remote exists. The comments below say
+// which routes are covered and which are not.
+//
+// Never in the way (M17): reading, editing and testing pass. A segment that only reads a ledger is
+// fine; `git add` and `git commit` of a ledger are fine; a script on the read allow-list is fine.
+//
+// Pure: no I/O. The caller gives it the layout, the branch facts and, for settings.json, the text.
+
+// ── paths ───────────────────────────────────────────────────────────────────────────────────────
+export const LEDGER_NAMES = new Set([
+  'runs.jsonl', 'evals.jsonl', 'acceptances.jsonl', 'outcome_checks.jsonl', 'grants.jsonl',
+  'agent-runs.jsonl', 'lifecycle.jsonl', 'verify-queue.jsonl',
+]);
+const ACCEPT_GRANTS = new Set(['acceptances.jsonl', 'grants.jsonl']);
+
+export function resolvePath(p, cwd) {
+  let s = String(p);
+  if (!s.startsWith('/')) s = `${String(cwd).replace(/\/+$/, '')}/${s}`;
+  const out = [];
+  for (const part of s.split('/')) {
+    if (part === '' || part === '.') continue;
+    if (part === '..') out.pop();
+    else out.push(part);
+  }
+  return `/${out.join('/')}`;
+}
+const under = (p, dir) => p === dir || p.startsWith(dir.replace(/\/+$/, '') + '/');
+const base = (p) => p.slice(p.lastIndexOf('/') + 1);
+
+/** What a file path is, for a write. ctx: { root, layout: {kind,stateRoot}|null } */
+export function classifyPath(path, ctx) {
+  const root = ctx.root.replace(/\/+$/, '');
+  const abs = resolvePath(path, root);
+  const name = base(abs);
+  const state = ctx.layout?.stateRoot ?? null;
+  const inState = state !== null && under(abs, state);
+  if (name.endsWith('.jsonl') && (inState || LEDGER_NAMES.has(name))) {
+    return { kind: ACCEPT_GRANTS.has(name) ? 'accept-grants' : 'ledger', path: abs };
+  }
+  if (abs === `${root}/.claude/pmos-cockpit.json`) return { kind: 'governing', path: abs, what: '.claude/pmos-cockpit.json' };
+  if (ctx.layout?.kind === 'kit' && under(abs, `${root}/pmos/mods`)) return { kind: 'governing', path: abs, what: 'the installed mod (pmos/mods)' };
+  if (abs === `${root}/.claude/settings.json`) return { kind: 'settings', path: abs, what: '.claude/settings.json' };
+  return null;
+}
+
+const PLUGIN_KEYS = /extraKnownMarketplaces|enabledPlugins|pmos-cockpit|pmos-mods/;
+/** Does an edit to settings.json touch the plugin entries? `current` is the file's text now, or null. */
+export function touchesPluginEntries(e, current) {
+  const parts = [];
+  for (const k of ['old_string', 'new_string', 'content', 'new_source']) if (typeof e[k] === 'string') parts.push(e[k]);
+  if (Array.isArray(e.edits)) for (const x of e.edits) { if (typeof x?.old_string === 'string') parts.push(x.old_string); if (typeof x?.new_string === 'string') parts.push(x.new_string); }
+  if (parts.some((t) => PLUGIN_KEYS.test(t))) return true;
+  // A whole-file write can drop the entries without naming them.
+  if (typeof e.content === 'string' && current !== null && PLUGIN_KEYS.test(current)) return !PLUGIN_KEYS.test(e.content);
+  return false;
+}
+
+export const PATH_KEYS = ['file_path', 'notebook_path', 'path', 'filepath', 'filename', 'destination', 'dest', 'target_file'];
+const WRITE_BUILTIN = new Set(['Edit', 'Write', 'MultiEdit', 'NotebookEdit']);
+// A tool from a server that writes files: its name says so (mcp__filesystem__write_file, …).
+const WRITE_MCP = /(^|_)(write|edit|append|move|rename|replace|delete|remove|copy|create_or_update|push_files|apply_patch)(_|$)/i;
+
+export function isFileWriteTool(tool) {
+  if (WRITE_BUILTIN.has(tool)) return true;
+  if (tool.startsWith('mcp__')) return WRITE_MCP.test(tool.split('__').slice(2).join('_'));
+  return false;
+}
+const pathsOf = (e) => PATH_KEYS.map((k) => e[k]).filter((v) => typeof v === 'string' && v !== '');
+
+// ── the shell ───────────────────────────────────────────────────────────────────────────────────
+// A small quote-aware reader. It is not a shell: it knows quotes, escapes, the separators, the
+// redirect operators and here-documents, which is what the guards need.
+
+function readSubstitutions(cmd) {
+  // $( … ) and `…` outside single quotes, returned as their own commands.
+  const subs = [];
+  let i = 0;
+  let q = null;
+  while (i < cmd.length) {
+    const c = cmd[i];
+    if (q === "'") { if (c === "'") q = null; i += 1; continue; }
+    if (c === '\\') { i += 2; continue; }
+    if (c === "'" && q === null) { q = "'"; i += 1; continue; }
+    if (c === '"') { q = q === '"' ? null : '"'; i += 1; continue; }
+    if (c === '$' && cmd[i + 1] === '(') {
+      let depth = 1; let j = i + 2;
+      while (j < cmd.length && depth > 0) { if (cmd[j] === '(') depth += 1; else if (cmd[j] === ')') depth -= 1; j += 1; }
+      subs.push(cmd.slice(i + 2, j - 1)); i = j; continue;
+    }
+    if (c === '`') {
+      const j = cmd.indexOf('`', i + 1);
+      if (j === -1) { subs.push(cmd.slice(i + 1)); break; }
+      subs.push(cmd.slice(i + 1, j)); i = j + 1; continue;
+    }
+    i += 1;
+  }
+  return subs;
+}
+
+/**
+ * Split a command into segments of words. A word is { t: text, dyn: has an unresolved $ or glob,
+ * op: a redirect operator }. A segment also carries the bodies of its here-documents.
+ */
+export function parseShell(cmd) {
+  const segs = [];
+  let seg = { words: [], heredocs: [] };
+  let cur = null;
+  let pending = null; // { delim, strip, seg }
+  let i = 0;
+  const flushWord = () => { if (cur !== null) { seg.words.push(cur); cur = null; } };
+  const flushSeg = () => { flushWord(); if (seg.words.length || seg.heredocs.length || pending?.seg === seg) segs.push(seg); seg = { words: [], heredocs: [] }; };
+  const add = (ch, dyn) => { if (cur === null) cur = { t: '', dyn: false }; cur.t += ch; if (dyn) cur.dyn = true; };
+  const standalone = (k) => cur === null && (k + 1 >= cmd.length || /[\s]/.test(cmd[k + 1]));
+  while (i < cmd.length) {
+    const c = cmd[i];
+    if (c === '\n') {
+      flushSeg(); i += 1;
+      if (pending) {
+        const lines = []; let j = i;
+        while (j < cmd.length) {
+          let k = cmd.indexOf('\n', j); if (k === -1) k = cmd.length;
+          const line = cmd.slice(j, k); j = k + 1;
+          if ((pending.strip ? line.trim() : line) === pending.delim) break;
+          lines.push(line);
+        }
+        pending.seg.heredocs.push(lines.join('\n')); pending = null; i = j;
+      }
+      continue;
+    }
+    if (c === ' ' || c === '\t') { flushWord(); i += 1; continue; }
+    if (c === '\\') { if (cmd[i + 1] === '\n') { i += 2; continue; } add(cmd[i + 1] ?? '', false); i += 2; continue; }
+    if (c === "'") {
+      const j = cmd.indexOf("'", i + 1); const end = j === -1 ? cmd.length : j;
+      if (cur === null) cur = { t: '', dyn: false }; cur.t += cmd.slice(i + 1, end); i = end + 1; continue;
+    }
+    if (c === '"') {
+      let j = i + 1; if (cur === null) cur = { t: '', dyn: false };
+      while (j < cmd.length && cmd[j] !== '"') {
+        if (cmd[j] === '\\' && j + 1 < cmd.length) { cur.t += cmd[j + 1]; j += 2; continue; }
+        if (cmd[j] === '$' || cmd[j] === '`') cur.dyn = true;
+        cur.t += cmd[j]; j += 1;
+      }
+      i = j + 1; continue;
+    }
+    if (c === '&' && cmd[i + 1] === '>') {
+      flushWord(); i += 2; if (cmd[i] === '>') i += 1;
+      seg.words.push({ t: '&>', dyn: false, op: true }); continue;
+    }
+    if (c === ';' || c === '|' || c === '&' || c === '(' || c === ')' || ((c === '{' || c === '}') && standalone(i))) {
+      flushSeg(); i += 1; if ((c === '&' || c === '|') && cmd[i] === c) i += 1; continue;
+    }
+    if (c === '>' || c === '<') {
+      if (cur !== null && /^\d+$/.test(cur.t)) cur = null; else flushWord();
+      let op = c; i += 1;
+      if (cmd[i] === c) { op += c; i += 1; if (op === '<<' && cmd[i] === '-') { op += '-'; i += 1; } else if (op === '<<' && cmd[i] === '<') { op += '<'; i += 1; } }
+      else if (c === '>' && (cmd[i] === '|' || cmd[i] === '&')) { op += cmd[i]; i += 1; }
+      seg.words.push({ t: op, dyn: false, op: true });
+      if (op === '<<' || op === '<<-') {
+        while (cmd[i] === ' ' || cmd[i] === '\t') i += 1;
+        let d = ''; let j = i;
+        while (j < cmd.length && !/[\s;|&()<>]/.test(cmd[j])) { if (cmd[j] !== "'" && cmd[j] !== '"' && cmd[j] !== '\\') d += cmd[j]; j += 1; }
+        pending = { delim: d, strip: op === '<<-', seg }; i = j;
+      }
+      continue;
+    }
+    add(c, c === '*' || c === '?' || c === '[' || c === '$' || c === '`' || c === '{' || c === '}'); i += 1;
+  }
+  flushSeg();
+  return segs;
+}
+
+// ── findings ────────────────────────────────────────────────────────────────────────────────────
+const KEYWORDS = new Set(['do', 'then', 'else', 'elif', 'if', 'while', 'until', '!', 'time', 'coproc']);
+const WRAPPERS = new Set(['env', 'sudo', 'command', 'builtin', 'exec', 'nohup', 'time', 'nice', 'ionice', 'xargs', 'stdbuf', 'setsid']);
+const SHELLS = new Set(['bash', 'sh', 'zsh', 'dash', 'ksh']);
+const INTERPRETERS = new Set(['python', 'python3', 'node', 'nodejs', 'perl', 'ruby', 'php', 'deno', 'bun', 'osascript']);
+// Verbs that only read what they are given. `sed` and `find` have a read form, checked separately.
+const READ_VERBS = new Set([
+  'cat', 'head', 'tail', 'less', 'more', 'grep', 'egrep', 'fgrep', 'rg', 'wc', 'ls', 'stat', 'file', 'jq', 'sort', 'uniq', 'cut',
+  'column', 'diff', 'cmp', 'md5sum', 'sha1sum', 'sha256sum', 'shasum', 'nl', 'tac', 'od', 'xxd', 'hexdump', 'echo', 'printf', 'test', '[',
+  'readlink', 'realpath', 'basename', 'dirname', 'cd', 'pwd', 'true', 'false', 'wait', 'type', 'which', 'tr', 'fold', 'strings', 'comm', 'join', 'paste', 'du',
+]);
+const GIT_READ = new Set(['add', 'commit', 'diff', 'log', 'show', 'status', 'blame', 'ls-files', 'grep', 'rev-parse', 'check-ignore', 'cat-file', 'rev-list', 'branch', 'remote', 'fetch', 'config', 'describe', 'shortlog', 'ls-tree', 'whatchanged']);
+// Scripts that read the ledgers and write nothing, by file name. A script written first and then given
+// one of these names is the "shell can always" route; it is not defended here.
+const READ_SCRIPTS = new Set(['metrics.py', 'workflow-state.js', 'workflow-sweep.js', 'check_rubrics.py', 'check_okf_drift.py', 'frontmatter_lint.py', 'check-verify-queue.js', 'pmos-model.js', 'pmos-skills.js', 'md-newlines.js']);
+// Code that writes a file, as inline interpreter text gives it away. A read of settings.json by an
+// interpreter passes; one that writes does not.
+const INLINE_WRITE = /\b(write|writeFile|writeFileSync|appendFile|appendFileSync|createWriteStream|rename|renameSync|unlink|unlinkSync|rmSync|copyFile|copyFileSync|truncate|dump|dumps)\b|open\([^)]*,\s*['"][wax]/;
+const WRITERS = new Set(['record-acceptance.js', 'record-eval.js', 'record-outcome.js', 'log-run.js', 'pmos-log.sh']);
+const base0 = (w) => base(w.t);
+
+// A verb that reads can still be told where to write: sort -o FILE, uniq IN OUT, xxd -r IN OUT, less -o.
+function writesByFlag(verb, args) {
+  const flags = args.filter((a) => a.startsWith('-'));
+  const files = args.filter((a) => !a.startsWith('-'));
+  if (verb === 'sort') return flags.some((a) => /^-[A-Za-z]*o|^--output/.test(a));
+  if (verb === 'uniq') return files.length >= 2;
+  if (verb === 'xxd') return flags.some((a) => /^-[A-Za-z]*r/.test(a)) && files.length >= 2;
+  if (verb === 'less' || verb === 'more') return flags.some((a) => /^-[oO]/.test(a));
+  return false;
+}
+
+function stripWrappers(words) {
+  let i = 0;
+  while (i < words.length) {
+    const w = words[i];
+    if (w.op) { i += 2; continue; }
+    if (/^[A-Za-z_][A-Za-z0-9_]*=/.test(w.t)) { i += 1; continue; }
+    const b = base0(w);
+    if (b === 'timeout') { i += 1; while (i < words.length && (words[i].t.startsWith('-') || /^[\d.]+[smhd]?$/.test(words[i].t))) i += 1; continue; }
+    if (KEYWORDS.has(w.t)) { i += 1; continue; }
+    if (WRAPPERS.has(b)) { i += 1; while (i < words.length && (words[i].t.startsWith('-') || /^[A-Za-z_][A-Za-z0-9_]*=/.test(words[i].t)) && b !== 'xargs') i += 1; if (b === 'xargs') while (i < words.length && words[i].t.startsWith('-')) i += 1; continue; }
+    break;
+  }
+  return words.slice(i);
+}
+
+// `git -C dir -c k=v --no-pager <sub> …`: the subcommand and what follows it.
+function gitSub(args) {
+  let i = 0;
+  while (i < args.length) {
+    const a = args[i];
+    if (['-C', '-c', '--git-dir', '--work-tree', '--namespace', '--exec-path'].includes(a)) { i += 2; continue; }
+    if (a.startsWith('-')) { i += 1; continue; }
+    return { sub: a, rest: args.slice(i + 1) };
+  }
+  return { sub: '', rest: [] };
+}
+
+const nonFlags = (words) => words.filter((w) => !w.op && !w.t.startsWith('-')).map((w) => w.t);
+
+function pushTargets(args) {
+  // the refspec targets of a `git push`, as branch names
+  const out = [];
+  for (const a of args) {
+    if (a === '') continue;
+    const dst = a.includes(':') ? a.slice(a.lastIndexOf(':') + 1) : a;
+    out.push(dst.replace(/^\+/, '').replace(/^refs\/heads\//, ''));
+  }
+  return out;
+}
+
+function gitPush(args, ctx, findings, raw) {
+  const flags = args.filter((a) => a.startsWith('-')).join(' ');
+  const rest = args.filter((a) => !a.startsWith('-'));
+  const refspecs = rest.slice(1); // the first is the remote
+  const forced = /(^|\s)(-f|--force|--force-with-lease(=\S*)?|--force-if-includes)(\s|$)/.test(flags) || refspecs.some((r) => r.startsWith('+'));
+  const deleting = /(^|\s)(-d|--delete|--mirror|--prune)(\s|$)/.test(flags) || refspecs.some((r) => r.startsWith(':'));
+  const defaults = new Set(['main', 'master', ...(ctx.defaultBranch ? [ctx.defaultBranch] : [])]);
+  let targets = pushTargets(refspecs).map((t) => (t === 'HEAD' ? (ctx.branch ?? 'HEAD') : t));
+  if (targets.length === 0) targets = [ctx.branch ?? ''];
+  if (/(^|\s)(--all|--mirror)(\s|$)/.test(flags)) targets.push('main'); // every ref, the default branch included
+  for (const t of targets) {
+    if (forced) findings.push({ kind: 'merge', action: 'forced push', target: t || ctx.branch || 'unknown', raw });
+    else if (deleting && defaults.has(t)) findings.push({ kind: 'merge', action: 'deleting the default branch', target: t, raw });
+    else if (t === '' || defaults.has(t)) findings.push({ kind: 'merge', action: 'push to the default branch', target: t || 'unknown', raw });
+  }
+}
+
+function ghFindings(args, findings, raw) {
+  // `gh -R owner/repo pr merge 3`: global flags take a value, so look for the words, not the position
+  const sub = nonFlags(args.map((t) => ({ t })));
+  const at = sub.findIndex((x, i) => (x === 'pr' && sub[i + 1] === 'merge') || x === 'api');
+  const pr = at !== -1 && sub[at] === 'pr';
+  if (pr) {
+    const rest = sub.slice(at + 2);
+    const n = rest.find((x) => /^\d+$/.test(x)) ?? rest.map((x) => /\/pull\/(\d+)/.exec(x)?.[1]).find(Boolean) ?? null;
+    findings.push({ kind: 'merge', action: 'gh pr merge', target: n, raw });
+  } else if (at !== -1) {
+    const text = args.join(' ');
+    const m = /\/pulls\/(\d+)\/merge\b|\/pulls\/(\d+)\b.*auto_merge/.exec(text);
+    const writes = /(^|\s)(-X|--method)[= ]?(PUT|POST|PATCH|DELETE)\b/i.test(text) || /(^|\s)(-f|-F|--field|--raw-field|--input)\b/.test(text);
+    if (m && writes) findings.push({ kind: 'merge', action: 'gh api merge', target: m[1] ?? m[2], raw });
+    else if (/\bmergePullRequest\b|\benablePullRequestAutoMerge\b/.test(text)) findings.push({ kind: 'merge', action: 'GraphQL merge', target: null, raw });
+    else if (/\/git\/refs\/heads\/(main|master)\b/.test(text) && writes) findings.push({ kind: 'merge', action: 'gh api update default branch', target: 'main', raw });
+  }
+}
+
+const CLOUD = /^(db\s+(push|reset)|functions\s+deploy|projects\s+create|secrets\s+set|branches\s+create|link)\b/;
+
+function segmentFindings(seg, ctx, findings, depth) {
+  const raw = seg.words.map((w) => w.t).join(' ');
+  const words = stripWrappers(seg.words);
+  if (seg.words.length === 0 && seg.heredocs.length === 0) return;
+  const verb = words.length ? base0(words[0]) : '';
+  const args = words.slice(1).map((w) => w.t);
+  const stateDir = ctx.layout?.stateRoot ?? null;
+
+  // nested commands: bash -c "…", eval "…", and here-documents fed to a shell
+  if (depth < 4) {
+    if (SHELLS.has(verb)) {
+      const ci = args.findIndex((a) => /^-[A-Za-z]*c[A-Za-z]*$/.test(a));
+      if (ci !== -1 && args[ci + 1] !== undefined) analyzeInto(args[ci + 1], ctx, findings, depth + 1);
+      for (const h of seg.heredocs) analyzeInto(h, ctx, findings, depth + 1);
+    }
+    if (verb === 'eval') analyzeInto(args.join(' '), ctx, findings, depth + 1);
+    if (verb === 'source' || verb === '.') { /* a file: not read here */ }
+  }
+
+  // ── merge-class ────────────────────────────────────────────────────────────────────────
+  if (verb === 'gh') ghFindings(args, findings, raw);
+  if (verb === 'git') {
+    const g = gitSub(args);
+    if (g.sub === 'push') gitPush(g.rest, ctx, findings, raw);
+  }
+  if (['npm', 'pnpm', 'yarn', 'npx', 'bun'].includes(verb)) {
+    const a = nonFlags(words.slice(1).map((w) => w));
+    const i = a.findIndex((x) => ['publish', 'unpublish', 'deprecate'].includes(x));
+    if (i !== -1) {
+      const rest = a.slice(i + 1);
+      findings.push({ kind: 'merge', action: `${verb} ${a[i]}`, publish: true, target: rest[0] ?? null, raw });
+    }
+  }
+  if (verb === 'supabase' && CLOUD.test(nonFlags(words.slice(1)).join(' '))) findings.push({ kind: 'cloud', action: `supabase ${nonFlags(words.slice(1)).slice(0, 2).join(' ')}`, raw });
+
+  // ── the ledgers ────────────────────────────────────────────────────────────────────────
+  const scriptName = [words[0], ...words.slice(1, 3)].map((w) => (w ? base(w.t) : '')).find((n) => WRITERS.has(n) || READ_SCRIPTS.has(n)) ?? '';
+  if (scriptName === 'record-acceptance.js') findings.push({ kind: 'accept-grants', why: 'record-acceptance.js writes the acceptance ledger', raw });
+  if (scriptName === 'pmos-log.sh') {
+    const sub = args.slice(args.findIndex((a) => base(a) === 'pmos-log.sh') + 1).find((a) => !a.startsWith('-'));
+    if (sub === 'accept' || sub === 'grant' || sub === 'grant-use') findings.push({ kind: 'accept-grants', why: `pmos-log.sh ${sub} is a person's command`, raw });
+  }
+
+  // does this segment write a protected path? Redirect targets, then the verb.
+  const redirectTargets = [];
+  for (let k = 0; k < seg.words.length; k += 1) {
+    const w = seg.words[k];
+    if (w.op && (w.t.startsWith('>') || w.t === '&>')) { const t = seg.words[k + 1]; if (t && !t.op) redirectTargets.push(t); }
+  }
+  const mentions = [];
+  const consider = (text, dyn) => {
+    // every path-ish piece that names a ledger, or that could (dynamic .jsonl)
+    const re = /[^\s'"`<>|;&()=,\[\]{}]*\.jsonl\b/g;
+    let m;
+    while ((m = re.exec(text)) !== null) {
+      const p = m[0]; const name = base(p);
+      const bare = name === '.jsonl' || /[*?$]/.test(name);
+      let hit = null;
+      if (LEDGER_NAMES.has(name)) hit = name; else if (stateDir !== null && !/[$`~]/.test(p) && under(resolvePath(p, ctx.root), stateDir)) hit = name; else if (bare || /[$`]/.test(p)) hit = name;
+      if (hit) mentions.push({ name: hit, path: p });
+    }
+    if (dyn && stateDir !== null && /\.jsonl/.test(text)) mentions.push({ name: 'dynamic.jsonl', path: text });
+  };
+  for (const w of seg.words) if (!w.op) consider(w.t, w.dyn);
+  if (ctx.tainted?.size) {
+    for (const w of seg.words) {
+      if (w.op || !w.dyn) continue;
+      for (const n of ctx.tainted) if (new RegExp(`\\$\\{?${n}\\b`).test(w.t)) mentions.push({ name: 'variable', path: w.t });
+    }
+  }
+  if (INTERPRETERS.has(verb) || SHELLS.has(verb)) for (const h of seg.heredocs) consider(h, false);
+  // a redirect to a glob or a variable, in a command that also names the state directory or a ledger
+  for (const t of redirectTargets) {
+    if (t.dyn && stateDir !== null && words.some((w) => LEDGER_NAMES.has(base(w.t)) || w.t.includes(base(stateDir)))) mentions.push({ name: 'glob', path: t.t });
+  }
+  if (mentions.length > 0) {
+    const redirectsToLedger = redirectTargets.some((t) => mentions.some((m) => m.path === t.t || base(t.t) === m.name || (t.dyn && m.name !== undefined)));
+    let readOnly = false;
+    if (READ_VERBS.has(verb) || (verb === '' && !redirectTargets.length)) readOnly = !writesByFlag(verb, args);
+    else if (verb === 'git') readOnly = GIT_READ.has(gitSub(args).sub);
+    else if (verb === 'sed') readOnly = !args.some((a) => /^-[A-Za-z]*i|^--in-place/.test(a)) && !args.some((a) => /(^|[;{}\s])w\s|\/w\s/.test(a));
+    else if (verb === 'find') readOnly = !args.some((a) => ['-delete', '-exec', '-execdir', '-fprint', '-fprintf', '-ok'].includes(a));
+    else if (verb === 'awk' || verb === 'gawk') readOnly = !args.some((a) => /system\s*\(|print[^;]*>|getline\s*<.*\||\|&/.test(a)) && !/-i\s*inplace|--include.*inplace/.test(args.join(' '));
+    else if (INTERPRETERS.has(verb) || verb === 'bash' || verb === 'sh') readOnly = scriptName !== '' && READ_SCRIPTS.has(scriptName) && !args.some((a) => a === '-c' || a === '-e' || a === '--eval');
+    else if (WRITERS.has(scriptName) || READ_SCRIPTS.has(scriptName)) readOnly = READ_SCRIPTS.has(scriptName);
+    if (!readOnly || redirectsToLedger) {
+      const acc = mentions.some((m) => ACCEPT_GRANTS.has(m.name));
+      findings.push({ kind: acc ? 'accept-grants' : 'ledger', why: `${verb || 'a redirect'} writes ${mentions[0].path}`, raw });
+    }
+  }
+
+  // ── the governing files ────────────────────────────────────────────────────────────────
+  const touched = [];
+  const gov = /[^\s'"`<>|;&()=,]*(?:pmos-cockpit\.json|settings\.json|pmos\/mods(?:\/[^\s'"`<>|;&()=,]*)?)/g;
+  const texts = seg.words.filter((w) => !w.op).map((w) => w.t);
+  if (INTERPRETERS.has(verb) || SHELLS.has(verb)) texts.push(...seg.heredocs);
+  for (const text of texts) {
+    let m;
+    while ((m = gov.exec(text)) !== null) {
+      const c = classifyPath(m[0].replace(/^\.\//, './'), ctx);
+      if (c && (c.kind === 'governing' || c.kind === 'settings')) touched.push(c);
+    }
+  }
+  if (touched.length) {
+    const wholeFile = redirectTargets.some((t) => /settings\.json$|pmos-cockpit\.json$/.test(t.t)) || ['tee', 'cp', 'mv', 'install', 'dd', 'ln', 'rm'].includes(verb);
+    const writes = !READ_VERBS.has(verb) && !(verb === 'git' && GIT_READ.has(gitSub(args).sub)) && !(verb === 'sed' && !args.some((a) => /^-[A-Za-z]*i|^--in-place/.test(a)));
+    const redirect = redirectTargets.length > 0;
+    const interp = INTERPRETERS.has(verb) || SHELLS.has(verb);
+    for (const c of touched) {
+      if (!(writes || redirect)) continue;
+      if (c.kind === 'governing') findings.push({ kind: 'governing', what: c.what, raw });
+      else if (PLUGIN_KEYS.test(raw) || wholeFile || redirect || (interp && INLINE_WRITE.test(texts.join('\n')))) findings.push({ kind: 'governing', what: c.what, raw });
+    }
+  }
+}
+
+// A variable set to a ledger or to the state directory taints the later words that use it, so
+// `F=pmos/state/runs.jsonl; echo x >> $F` is found. The set lives for one command string.
+function taintedNames(segs, ctx) {
+  const names = new Set();
+  const state = ctx.layout?.stateRoot ?? null;
+  for (const seg of segs) {
+    for (const w of seg.words) {
+      const m = /^([A-Za-z_][A-Za-z0-9_]*)=([\s\S]*)$/.exec(w.t);
+      if (!m) continue;
+      const v = m[2];
+      const hitsLedger = /\.jsonl\b/.test(v) || [...LEDGER_NAMES].some((n) => v.includes(n));
+      const hitsState = state !== null && (under(resolvePath(v, ctx.root), state) || v.includes('pmos/state') || v.includes('planning/runs'));
+      if (hitsLedger || hitsState) names.add(m[1]);
+    }
+  }
+  return names;
+}
+
+function analyzeInto(cmd, ctx, findings, depth) {
+  for (const sub of readSubstitutions(cmd)) if (depth < 4) analyzeInto(sub, ctx, findings, depth + 1);
+  const segs = parseShell(cmd);
+  const tainted = taintedNames(segs, ctx);
+  for (const seg of segs) segmentFindings(seg, { ...ctx, tainted }, findings, depth);
+}
+
+/**
+ * Findings for one Bash command.
+ * @param {string} command
+ * @param {{ root: string, layout: {kind: string, stateRoot: string|null}|null, branch?: string|null, defaultBranch?: string|null }} ctx
+ */
+export function classifyBash(command, ctx) {
+  const findings = [];
+  analyzeInto(String(command), ctx, findings, 0);
+  return findings;
+}
+
+// ── MCP tools ───────────────────────────────────────────────────────────────────────────────────
+const tail = (tool) => tool.split('__').slice(2).join('__');
+const server = (tool) => (tool.split('__')[1] ?? '').toLowerCase();
+
+const OUTWARD = [
+  { server: /atlassian|confluence|jira/, verb: /^(create|edit|add|update|transition|delete|link)/i },
+  { server: /slack/, verb: /^slack_(send_message|schedule_message|create_canvas|update_canvas|add_reaction)$/ },
+  { server: /gmail/, verb: /^(send_message|reply|forward)$/ },
+  { server: /google_?drive/, verb: /^(share_file|create_file|update_file|copy_file|trash_file)$/ },
+  { server: /google_?calendar/, verb: /^(create_event|update_event|delete_event|respond_to_event)$/ },
+];
+
+/** The kind of a tool call that is not Bash and not a file write, or null. */
+export function classifyTool(e, ctx) {
+  const tool = String(e.tool);
+  if (!tool.startsWith('mcp__')) return null;
+  const t = tail(tool);
+  if (/(^|__)merge_pull_request$/.test(t) || /(^|_)enable_pr_auto_merge$/.test(t)) {
+    const n = e.pullNumber ?? e.pull_number ?? e.number ?? null;
+    return { kind: 'merge', action: t, target: n === null ? null : String(n) };
+  }
+  if (/^github$/.test(server(tool)) && /^(push_files|create_or_update_file|delete_file)$/.test(t)) {
+    const defaults = new Set(['main', 'master', ...(ctx.defaultBranch ? [ctx.defaultBranch] : [])]);
+    const br = typeof e.branch === 'string' && e.branch !== '' ? e.branch : null;
+    if (br === null || defaults.has(br)) return { kind: 'merge', action: `${t} to the default branch`, target: br ?? ctx.defaultBranch ?? 'main' };
+    return null;
+  }
+  for (const o of OUTWARD) if (o.server.test(server(tool)) && o.verb.test(t)) return { kind: 'outward', action: tool };
+  return null;
+}
+
+/**
+ * Everything the guards need to decide about one tool call, in one place.
+ * @returns {Array<{kind: string, [k: string]: any}>}
+ */
+export function findingsFor(e, ctx, settingsText = null) {
+  const tool = String(e.tool);
+  if (tool === 'Bash') return typeof e.command === 'string' ? classifyBash(e.command, ctx) : [];
+  const out = [];
+  if (isFileWriteTool(tool)) {
+    for (const p of pathsOf(e)) {
+      const c = classifyPath(p, ctx);
+      if (c === null) continue;
+      if (c.kind === 'settings') { if (touchesPluginEntries(e, settingsText)) out.push({ kind: 'governing', what: c.what, path: c.path }); continue; }
+      out.push({ ...c });
+    }
+  }
+  const other = classifyTool(e, ctx);
+  if (other) out.push(other);
+  return out;
+}
+
+/** The writer to name in a block message. */
+export function writerHint(ctx) {
+  return ctx.layout?.kind === 'self'
+    ? 'scripts/log-run.js, scripts/record-eval.js or scripts/record-outcome.js'
+    : 'pmos/scripts/pmos-log.sh (run, eval, outcome or friction)';
+}
+
+// ── what the model reads when a call is denied ─────────────────────────────────────────────────
+const SCOPE_HINT = (f) => (f.publish ? 'publish:<artifact>' : f.target ? `merge:${f.target}` : 'merge:<PR number>');
+
+/** One sentence the model reads on a deny. It always names what to do next. */
+export function denyMessage(f, ctx) {
+  const head = 'Blocked by pmos-cockpit:';
+  switch (f.kind) {
+    case 'ledger':
+      return `${head} a hand-written change to a ledger (${f.why ?? f.path ?? 'a *.jsonl file in the state root'}). Write ledger rows with ${writerHint(ctx)}, which validates the row. Reading a ledger is not blocked.`;
+    case 'accept-grants':
+      return `${head} acceptances and grants are the PM's (D12: Acceptance is non-delegable). ${f.why ? `${f.why}. ` : ''}The PM records one by typing /pmos-accept <run_id> pass|fail <note> or /pmos-grant <scope>, or by pressing the button. Ask the PM to do it.`;
+    case 'governing':
+      return `${head} ${f.what} is governing configuration. A person edits it${ctx.layout?.kind === 'kit' ? '; npx create-pmos --update refreshes the installed mod' : ''}. Ask the PM.`;
+    case 'cloud':
+      return `${head} ${f.action} changes a cloud service. AGENTS.md makes it confirm-first, and no grant covers it in this release. Ask the PM to run it.`;
+    default:
+      return `${head} ${f.action ?? 'this action'} is not allowed here.`;
+  }
+}
+
+/** A merge-class denial: why no grant allows it, and the command that mints one. */
+export function denyMerge(f, reason) {
+  const what = `${f.action}${f.target ? ` ${f.target}` : ''}`;
+  return `Blocked by pmos-cockpit: ${what} needs the PM's grant, and ${reason} Ask the PM to type /pmos-grant ${SCOPE_HINT(f)} (single use, 120 minutes). A grant for one target never covers another.`;
+}
+
+/**
+ * The guard's own failure path. When the matcher or its inputs throw, the mod cannot classify the
+ * call, so it uses names alone: an ordinary action is allowed, and a merge, a publish or a ledger,
+ * acceptance, grants or governing-file write is denied (M17). Returns a reason, or null.
+ */
+export function looseDeny(e) {
+  const tool = String(e.tool);
+  const say = (what) => `Blocked by pmos-cockpit: the guard failed while checking this call, and ${what} is denied when it cannot be checked. An ordinary action would have been allowed. Ask the PM, or retry.`;
+  if (tool === 'Bash' && typeof e.command === 'string') {
+    const c = e.command;
+    if (/\bgh\b[^\n;|&]*\b(pr\s+merge|api)\b|\bnpm\b[^\n;|&]*\bpublish\b|\b(pnpm|yarn)\b[^\n;|&]*\bpublish\b|\bgit\b[^\n;|&]*\bpush\b|\bsupabase\b[^\n;|&]*\b(db push|functions deploy|projects create|secrets set)\b/.test(c)) return say('a merge, push or publish');
+    if (/\.jsonl\b|record-acceptance|pmos-log\.sh\s+(accept|grant)|pmos\/mods|pmos-cockpit\.json|settings\.json/.test(c)) return say('a write that names a ledger or governing file');
+    return null;
+  }
+  if (isFileWriteTool(tool)) {
+    const hit = PATH_KEYS.map((k) => e[k]).some((v) => typeof v === 'string' && /\.jsonl$|pmos\/mods\/|pmos-cockpit\.json$|\.claude\/settings\.json$/.test(v));
+    return hit ? say('a write to a ledger or governing file') : null;
+  }
+  if (tool.startsWith('mcp__') && /merge_pull_request|enable_pr_auto_merge/.test(tool)) return say('a merge');
+  return null;
+}
+
+/** Does a user message read as an approval? Used only to OFFER a press; nothing is written from it. */
+export function readsAsApproval(text) {
+  const t = String(text ?? '').trim();
+  if (t === '' || t.startsWith('/') || t.length > 600) return false;
+  return /\b(accepted?|i accept|approved?|lgtm|ship it|looks good|go ahead and merge|merge (it|this|that|pr\s*#?\d+))\b/i.test(t) && !/\?\s*$/.test(t);
+}

package/payload/mods/pmos-cockpit/hooks/lib/initiative.mjs

@@ -0,0 +1,54 @@
+// Which initiative is this session in? One rule, and it is the workspace's: the branch is
+// `initiative/<id>` with an id after it (workspace/lib/working-set.js, initiativeOfBranch). A test
+// pins this function to that one on the same cases, so the mod and the workspace cannot disagree.
+//
+// It never guesses. A branch with another name, a detached head, an id that is not a safe file name
+// and an id with no record all answer "no initiative" and say why.
+
+const PREFIX = 'initiative/';
+// The id becomes part of a path, so it must be a plain slug. The workspace accepts any text after
+// the prefix because it only compares strings; the mod reads files, so it is stricter, and says so.
+const SAFE_ID = /^[a-z0-9][a-z0-9._-]{0,99}$/;
+
+/** The id a branch names, or null. Same cases as the workspace's `initiativeOfBranch`. */
+export function initiativeOfBranch(branch) {
+  const b = typeof branch === 'string' ? branch : '';
+  if (!b.startsWith(PREFIX)) return null;
+  const id = b.slice(PREFIX.length);
+  return id ? id : null;
+}
+
+/**
+ * @param {{ branch: string|null, recordExists: boolean|null, commitsAhead?: number|null }} facts
+ * @returns {{ id: string|null, state: 'ok'|'no-initiative'|'no-record'|'unsafe-id'|'detached', warn: boolean, text: string }}
+ */
+export function resolveInitiative(facts) {
+  const branch = facts.branch ?? null;
+  if (branch === null || branch === '' || branch === 'HEAD') {
+    return { id: null, state: 'detached', warn: false, text: 'no initiative (no branch: a detached head)' };
+  }
+  const id = initiativeOfBranch(branch);
+  if (id === null) {
+    const warn = (facts.commitsAhead ?? 0) > 0;
+    return {
+      id: null,
+      state: 'no-initiative',
+      warn,
+      text: `no initiative (branch ${branch} is not initiative/<id>)${warn ? '. It has commits, so the work has no initiative record.' : ''}`,
+    };
+  }
+  if (!SAFE_ID.test(id)) {
+    return { id: null, state: 'unsafe-id', warn: true, text: `no initiative (the id "${id}" is not a plain lowercase slug, so it is not used as a path)` };
+  }
+  if (facts.recordExists === false) {
+    return { id, state: 'no-record', warn: true, text: `no initiative record for ${id} (the branch names it and the file does not exist)` };
+  }
+  return { id, state: 'ok', warn: false, text: id };
+}
+
+/** The record paths the layout keeps initiatives at, for the caller's existence check. */
+export function recordPath(layout, id) {
+  if (layout.kind === 'kit') return `${layout.root.replace(/\/+$/, '')}/pmos/state/initiatives/${id}.md`;
+  if (layout.kind === 'self') return `${layout.root.replace(/\/+$/, '')}/planning/initiatives/${id}.md`;
+  return null;
+}

package/payload/mods/pmos-cockpit/hooks/lib/layout.mjs

@@ -0,0 +1,31 @@
+// layout.mjs — which PMOS layout is this repository, and where do its ledgers live?
+//
+// PMOS keeps its state in two shapes. PMOS's own repository keeps records in `planning/` and the
+// ledgers in `planning/runs/`. A vendored kit keeps them under `pmos/state/`. The rule below is the
+// one scripts/workflow-state.js uses (its `layout()`, `isKit = !selfDir && kitDir`), and a test pins
+// the two together, so the mod and the ladder cannot disagree about which repository this is.
+//
+// Pure: it asks a `probe` whether a path exists and does nothing else.
+
+export const KIT = 'kit';
+export const SELF = 'self';
+export const NONE = 'none';
+
+/**
+ * @param {{ exists: (path: string) => Promise<boolean> | boolean }} probe
+ * @param {string} root the repository root (the session's working root)
+ * @returns {Promise<{kind: 'kit'|'self'|'none', root: string, stateRoot: string|null, runsFile: string|null, skillsNative: string|null, claudeSkills: string}>}
+ */
+export async function detectLayout(probe, root) {
+  const at = (...parts) => [root.replace(/\/+$/, ''), ...parts].join('/');
+  const hasSelf = await probe.exists(at('planning', 'initiatives'));
+  const hasKit = await probe.exists(at('pmos', 'state', 'initiatives'));
+  const claudeSkills = at('.claude', 'skills');
+  if (!hasSelf && hasKit) {
+    return { kind: KIT, root, stateRoot: at('pmos', 'state'), runsFile: 'runs.jsonl', skillsNative: at('pmos', 'skills-native'), claudeSkills };
+  }
+  if (hasSelf) {
+    return { kind: SELF, root, stateRoot: at('planning', 'runs'), runsFile: 'agent-runs.jsonl', skillsNative: null, claudeSkills };
+  }
+  return { kind: NONE, root, stateRoot: null, runsFile: null, skillsNative: null, claudeSkills };
+}