create-pmos 0.522.0 → 0.524.0

package/workspace/lib/bg-queue.js

@@ -0,0 +1,226 @@
+'use strict';
+/* bg-queue.js — ONE queue for all of Claude's background work (idle lab design, frame I4 "One queue for all background work",
+ * agreed by the PM 2026-11-04). Every background job asks this queue for its turn, once a minute, from the server's one tick.
+ *
+ *   JOBS · STEPS · CAP                          the job table, the five steps in priority order, the runs-at-once limit
+ *   plan({ jobs, now, idleMs, quiet, running, offOf, spend, workEnd? })
+ *                                               PURE → [{ id, step, go, why, idle }] in the order the jobs take their turn
+ *   holderOf(sessions, initiative, { except? }) PURE → the live background session that holds the initiative, or null
+ *   jobOfOrigin(origin)                         PURE → the queue job a background session's origin belongs to, or null
+ *   create(host) → { register(id, fn), tick(now?), status(), holder(initiative, except?), idle(now?), ended(session, now?), record({ ws?, since? }) }
+ *
+ * THE ORDER (each tick, step by step; inside a step, in the order of JOBS):
+ *   1 asked     what the PM asked for: Scan now, "grill this", Prepare my day. A press starts at once through the route and is never
+ *               held, so step 1 has no tick here. It is in the table so the Lab can list it.
+ *   2 due       what is due at a set time: schedules, the morning brief and the day check, the day plan, the data refresh, report
+ *               schedules, Git sync
+ *   3 driver    the Initiative Driver
+ *   4 deep      the deep drafts: core documents, Your impact, metric drafts and reads, proposals, grill, the report finder, the
+ *               report design and structure checks, milestone reviews, the forecast
+ *   5 idle      the idle lab and the slow reads: the Horizon scan (its daily run waits for the first idle stretch of the day)
+ *
+ * THE CHECKS (made once per tick, for every job):
+ *   off switch   lib/ai-guard.js off(job): PMOS_AI=off, PMOS_AI_<JOB>=off, Settings ai.on / ai.off (`pmos ai off [job]`). A job with
+ *                `ai: false` (Git sync: no model) is not an AI job, so the switch does not stop it.
+ *   idle clock   lib/pm-idle.js idleFor (30 minutes with no press and no key). Step 5 only. In the last hour of the working day a step-5
+ *                job runs even when the PM never stepped away, so a once-a-day job still runs once a day.
+ *   hours        quiet hours hold step 5. Steps 2 to 4 keep the hours rules they have today (each job's own window).
+ *   spend        Settings › Claude's checks spend limit (grill.cap, the month's spend from grill-runs.jsonl). At the limit step 5 holds.
+ *                Steps 2 to 4 are not held: grill holds its own runs at the cap, and the rest run on the PM's plan, not on credits.
+ *   capacity     CAP (3) background runs at once (lib/orchestrator-spawn.js running(): the Driver's runs, the scheduled runs and the
+ *                PM's working chat sessions). At the limit step 5 holds. Steps 2 to 4 start their runs through orchestrator-spawn,
+ *                which holds each start with the capacity governor (lib/capacity-governor.js) as it does today.
+ *   one per initiative   holderOf(): a background run never starts on an initiative another background run holds. orchestrator-spawn
+ *                and the Driver ask holder() before each start; the held start is tried again on the next tick.
+ * A job that is not held runs its own tick, which keeps its own due rules (once a day, its time window, its inputs). Nothing a job
+ * shows changes: the queue decides only WHEN a job may look, never what it files.
+ *
+ * THE RECORD, <stateDir>/bg-queue.jsonl:
+ *   turn  { at, kind: 'turn', job, step, go, why }   a job's turn changed (it was held and now goes, or the reason changed). A steady
+ *                                                     minute writes nothing.
+ *   done  { at, kind: 'done', job, title, ws, ini?, session, meta? }   a background session ended (ended(), from the server's one
+ *                                                     session-end hook). A session the PM started, or a chat, is not written.
+ * status() is the last plan, for the Lab ("what runs next"). record({ ws, since }) is the done lines, newest first, for the Lab's
+ * "What Claude did in the background" (lib/routes-lab.js): [{ job, title, meta?, at, ini?, board? }].
+ * PMOS_QUEUE_IDLE_MS (milliseconds) fixes the idle clock the queue reads, for the suites.
+ */
+const fs = require('fs');
+const path = require('path');
+
+const CAP = 3;
+const STEPS = Object.freeze([
+  { step: 1, id: 'asked', label: 'What you asked for' },
+  { step: 2, id: 'due', label: 'Due at a set time' },
+  { step: 3, id: 'driver', label: 'The Driver' },
+  { step: 4, id: 'deep', label: 'Deep drafts' },
+  { step: 5, id: 'idle', label: 'Idle lab and slow reads' },
+]);
+/* id: the queue's job id (also the `pmos ai off <job>` id). ai: false = no model, so the AI off switch does not stop it. */
+const JOBS = Object.freeze([
+  { id: 'schedules', step: 2, label: 'Scheduled skills' },
+  { id: 'proactive', step: 2, label: 'Morning brief and day check' },
+  { id: 'prepare', step: 2, label: 'Day tasks' },
+  { id: 'day', step: 2, label: 'Day plan' },
+  { id: 'refresh', step: 2, label: 'Data refresh' },
+  { id: 'reports', step: 2, label: 'Report schedules' },
+  { id: 'sync', step: 2, label: 'Git sync', ai: false },
+  { id: 'driver', step: 3, label: 'Initiative Driver' },
+  { id: 'finder', step: 4, label: 'Report finder' },
+  { id: 'coredocs', step: 4, label: 'Core documents' },
+  { id: 'milestones', step: 4, label: 'Milestone reviews' },
+  { id: 'propose', step: 4, label: 'Found elsewhere and task checks' },
+  { id: 'grill', step: 4, label: 'Grill' },
+  { id: 'metric-drafts', step: 4, label: 'Metric drafts' },
+  { id: 'impact', step: 4, label: 'Your impact' },
+  { id: 'metric-reads', step: 4, label: 'Metric reads' },
+  { id: 'forecast', step: 4, label: 'Forecast' },
+  { id: 'report-design', step: 4, label: 'Report design' },
+  { id: 'report-structure', step: 4, label: 'Report structure' },
+  { id: 'scan', step: 5, label: 'Horizon scan' },
+]);
+const BY_ID = new Map(JOBS.map((j) => [j.id, j]));
+const LAST_HOUR_MS = 60 * 60 * 1000;
+
+const hhmmMs = (now, hhmm) => {
+  const m = /^(\d{1,2}):(\d{2})$/.exec(String(hhmm || ''));
+  if (!m) return null;
+  const d = new Date(now); d.setHours(+m[1], +m[2], 0, 0); return d.getTime();
+};
+
+/** PURE. The turn of every job this tick. `offOf(id)` → null | reason; spend: { atCap, why? } | null; workEnd: '18:00' (the day-check
+ * end), for the last-hour rule. Each row's idle is true when the PM has been away idleLimit or more, or in the last hour of the day. */
+function plan({ jobs = JOBS, now = Date.now(), idleMs = 0, idleLimit = 30 * 60 * 1000, quiet = false, running = 0, cap = CAP, offOf = () => null, spend = null, workEnd = null } = {}) {
+  const idle = idleMs >= idleLimit;
+  const end = workEnd ? hhmmMs(now, workEnd) : null;
+  const lastHour = end !== null && now < end && end - now <= LAST_HOUR_MS;
+  const away = idle || lastHour;   // the turn's idle flag: the PM stepped away, or the day's last hour came first
+  const rows = [...jobs].sort((a, b) => a.step - b.step);
+  let live = Math.max(0, Number(running) || 0);
+  return rows.map((j) => {
+    const row = (go, why) => ({ id: j.id, step: j.step, go, why: go ? null : why, idle: away });
+    if (j.ai !== false) { const o = offOf(j.id); if (o) return row(false, o); }
+    if (j.step < 5) return row(true);
+    if (quiet) return row(false, 'quiet hours');
+    if (!away) return row(false, 'waiting for you to step away');
+    if (spend && spend.atCap) return row(false, spend.why || "the spend limit in Settings › Claude's checks is reached");
+    if (live >= cap) return row(false, `${live} background runs are live (limit ${cap})`);
+    live++;   // a step-5 job may start one run: the next one sees it
+    return row(true);
+  });
+}
+
+/** PURE. The live background session that holds `initiative`. sessions: [{ id, initiative?, origin?, state, background? }]. A session
+ * the PM started by hand (no origin) never holds an initiative here. `except`: a session id or an origin prefix ('drive:') to leave out. */
+function holderOf(sessions, initiative, { except = null } = {}) {
+  const ini = String(initiative || '');
+  if (!ini) return null;
+  for (const s of sessions || []) {
+    if (!s || s.state === 'exited' || !s.origin) continue;
+    if (/^chat:/.test(String(s.origin))) continue;
+    if (except && (s.id === except || String(s.origin).startsWith(except))) continue;
+    if (String(s.initiative || '') === ini || initiativeOfOrigin(s.origin) === ini) return s;
+  }
+  return null;
+}
+/** The initiative an origin names: drive:initiative:<id>, grill:<ws>:<id>:<run>, propose:<ws>:<id>:<run>. */
+function initiativeOfOrigin(origin) {
+  const p = String(origin || '').split(':');
+  if (p[0] === 'drive' && p[1] === 'initiative') return p.slice(2).join(':') || null;
+  if ((p[0] === 'grill' || p[0] === 'propose') && p.length >= 4) return p[2] || null;
+  return null;
+}
+
+/* origin prefix → queue job. Origins not listed (a refresh source, a schedule, next-step) keep their prefix as the job name. */
+const ORIGIN_JOB = Object.freeze({ drive: 'driver', grill: 'grill', propose: 'propose', 'metric-read': 'metric-reads', 'metric-draft': 'metric-drafts',
+  impact: 'impact', coredoc: 'coredocs', 'core-docs': 'coredocs', 'scan-web': 'scan', 'scan-repo': 'scan', 'scan-suggest': 'scan',
+  'scan-research-web': 'scan', 'scan-research-repo': 'scan', 'report-find': 'finder', 'ms-review': 'milestones', 'next-step': 'prepare' });
+function jobOfOrigin(origin) {
+  const o = String(origin || '');
+  if (!o || /^chat:/.test(o)) return null;
+  const head = o.split(':')[0];
+  return ORIGIN_JOB[head] || head || null;
+}
+
+/** host: { stateDir, idleFor(now) → ms, idleLimit, quiet(now) → bool, running() → number, offOf(id) → null|reason, spend() → { atCap, why? },
+ *          workEnd() → 'HH:MM' | null, sessions() → [session], warn(what, e), env? } */
+function create(host = {}) {
+  const fns = new Map();
+  const lastWhy = new Map();   // job → the why of its last turn ('' = it went)
+  let last = { at: null, rows: [] };
+  const warn = host.warn || (() => {});
+  const env = host.env || process.env;
+  const call = (f, d) => { try { const v = f(); return v === undefined ? d : v; } catch (e) { warn('bg-queue', e); return d; } };
+
+  function idle(now = Date.now()) {
+    const fixed = Number(env.PMOS_QUEUE_IDLE_MS);
+    if (env.PMOS_QUEUE_IDLE_MS !== undefined && Number.isFinite(fixed)) return fixed;
+    return host.idleFor ? call(() => host.idleFor(now), 0) : 0;
+  }
+  function noteTurn(now, r) {
+    const why = r.go ? '' : r.why;
+    if (lastWhy.get(r.id) === why) return;
+    const first = !lastWhy.has(r.id);
+    lastWhy.set(r.id, why);
+    if (first && r.go) return;   // a job that goes from the start is the steady state: nothing to write
+    if (!host.stateDir) return;
+    append({ at: new Date(now).toISOString(), kind: 'turn', job: r.id, step: r.step, go: r.go, why: r.why });
+  }
+  const file = () => (host.stateDir ? path.join(host.stateDir, 'bg-queue.jsonl') : null);
+  function append(line) {
+    if (!file()) return;
+    try { fs.mkdirSync(host.stateDir, { recursive: true }); fs.appendFileSync(file(), JSON.stringify(line) + '\n'); } catch (e) { warn('bg-queue record', e); }
+  }
+  function ended(s, now = Date.now()) {
+    if (!s || !s.origin) return;
+    const job = jobOfOrigin(s.origin);
+    if (!job) return;
+    const line = { at: new Date(now).toISOString(), kind: 'done', job, title: String(s.name || job).slice(0, 160), ws: s.ws || null, session: s.id || null };
+    const ini = s.initiative || initiativeOfOrigin(s.origin);
+    if (ini) line.ini = String(ini);
+    if (s.outcome && typeof s.outcome === 'string') line.meta = s.outcome.slice(0, 160);
+    append(line);
+  }
+  function record({ ws = null, since = null } = {}) {
+    let text = '';
+    try { text = file() ? fs.readFileSync(file(), 'utf8') : ''; } catch { return []; }
+    const from = since == null ? -Infinity : (typeof since === 'number' ? since : Date.parse(since));
+    const out = [];
+    for (const raw of text.split('\n')) {
+      if (!raw.trim()) continue;
+      let l; try { l = JSON.parse(raw); } catch { continue; }
+      if (!l || l.kind !== 'done') continue;
+      if (ws && l.ws && l.ws !== ws) continue;
+      if (Date.parse(l.at) < from) continue;
+      const row = { job: l.job, title: l.title, at: l.at };
+      if (l.meta) row.meta = l.meta;
+      if (l.ini) row.ini = l.ini;
+      if (l.board) row.board = l.board;
+      out.push(row);
+    }
+    return out.reverse();
+  }
+  function tick(now = Date.now()) {
+    const jobs = JOBS.filter((j) => fns.has(j.id));
+    const rows = plan({
+      jobs, now, idleMs: idle(now), idleLimit: host.idleLimit, quiet: !!(host.quiet && call(() => host.quiet(now), false)),
+      running: host.running ? call(() => host.running(), 0) : 0, offOf: (id) => (host.offOf ? call(() => host.offOf(id), null) : null),
+      spend: host.spend ? call(() => host.spend(now), null) : null, workEnd: host.workEnd ? call(() => host.workEnd(), null) : null,
+    });
+    for (const r of rows) {
+      noteTurn(now, r);
+      if (!r.go) continue;
+      try { fns.get(r.id)({ now, idle: r.idle, step: r.step }); } catch (e) { warn(r.id + ' tick', e); }
+    }
+    last = { at: now, rows };
+    return rows;
+  }
+  return {
+    register(id, fn) { if (!BY_ID.has(id)) throw new Error(`bg-queue: ${id} is not a job in JOBS`); fns.set(id, fn); },
+    tick, idle, ended, record,
+    status: () => ({ at: last.at ? new Date(last.at).toISOString() : null, cap: CAP, steps: STEPS,
+      jobs: last.rows.map((r) => ({ ...r, label: BY_ID.get(r.id).label })) }),
+    holder: (initiative, except) => holderOf(host.sessions ? call(() => host.sessions(), []) : [], initiative, { except }),
+  };
+}
+
+module.exports = { CAP, STEPS, JOBS, plan, holderOf, initiativeOfOrigin, jobOfOrigin, create };

package/workspace/lib/connector-read.js

@@ -0,0 +1,19 @@
+'use strict';
+/* connector-read.js — which connector tools are read-shaped. Shared by project setup (lib/project-onboard.js) and background runs
+ * (lib/headless.js connectorReads). Kept in its own file so a change to project setup does not reach every suite that uses headless runs. */
+const READ_VERBS = new Set(['search', 'get', 'list', 'read', 'fetch', 'find', 'query', 'lookup', 'view', 'describe', 'retrieve', 'browse', 'resolve']);
+const WRITE_VERBS = new Set(['create', 'update', 'delete', 'add', 'post', 'send', 'write', 'edit', 'move', 'transition', 'comment', 'assign', 'upload',
+  'remove', 'set', 'merge', 'close', 'archive', 'share', 'copy', 'trash', 'label', 'mark', 'apply', 'schedule', 'reply', 'forward', 'draft', 'respond',
+  'invite', 'publish', 'run', 'execute', 'trigger', 'link', 'unlink', 'approve', 'submit', 'save', 'log', 'record', 'register', 'insert', 'append',
+  'clear', 'fork', 'enable', 'disable', 'untrash', 'unmark', 'unlabel', 'cancel', 'install', 'import', 'export', 'generate', 'use', 'push', 'request', 'rename']);
+const words = (s) => String(s).replace(/([a-z0-9])([A-Z])/g, '$1 $2').split(/[^A-Za-z0-9]+/).filter(Boolean).map((w) => w.toLowerCase());
+
+/** A tool may be granted only when its own name (after the server prefix) leads with a read verb and holds no write verb. */
+function readTool(toolName, prefix) {
+  const own = prefix && toolName.startsWith(prefix) ? toolName.slice(prefix.length) : toolName.replace(/^mcp__[^_]+(?:_[^_]+)*?__/, '');
+  const w = words(own);
+  if (!w.length || w.some((x) => WRITE_VERBS.has(x))) return false;
+  return w.slice(0, 3).some((x) => READ_VERBS.has(x));
+}
+
+module.exports = { readTool, READ_VERBS, WRITE_VERBS };

package/workspace/lib/driver-run.js

@@ -15,7 +15,8 @@
  *
  * deps: { gather?(w, ctx, opts) → facts answer (tests), workspaces() → [w], isLead(w), stateDirFor(w), ctx (for lib/routes-boards.js), runtimeDir, settings() → proactive settings,
  *         inQuiet(now, quiet) → bool, spawn(spec) → session row, promptFor(kind) → skill body | null, boardOf(w, id) → board id | null,
- *         homeId() → the workspace id that holds the Work tasks, headlessOff() → bool, env, warn(what, err) }
+ *         homeId() → the workspace id that holds the Work tasks, headlessOff() → bool, env, warn(what, err),
+ *         holder?(initiative) → the live background run of another job on it, or null (lib/bg-queue.js: one run per initiative) }
  * `spawn(spec)` gets { name, ws, origin, initialInput, initiative, onDone }; it returns the session row ({ id, state, headless }).
  */
 const fs = require('fs');
@@ -249,6 +250,12 @@ function create(deps) {
             try { g = deps.mayStart({ running: live }) || g; } catch (e) { warn('driver gate', e); }
             if (!g.allowed) { summary.held = g.reason || 'the capacity governor'; break; }
           }
+          // bg-queue: one background run per initiative. Another job's run holds this one; its wakes stay queued for the next tick.
+          if (deps.holder && group.target.kind === 'initiative') {
+            let h = null;
+            try { h = deps.holder(group.target.id); } catch (e) { warn('driver holder', e); }
+            if (h) { summary.held = `another background run is working on ${group.target.id}`; continue; }
+          }
           startRun(w, file, group, state, factsNow, now);
           if (deps.started) { try { deps.started(); } catch { /* a counter */ } }
           live = active.size; summary.started++;

package/workspace/lib/first-reveal.js

@@ -0,0 +1,311 @@
+'use strict';
+/* first-reveal.js — what Home shows right after setup (onboarding build B2; frames ObA2First and ObA5Aha, In development;
+ * brief /mnt/project-files/onboarding-grill/brief-B2-after-setup-reveal.md).
+ *
+ * After "Set up PMOS in <folder>" the PM lands on Home with the product already read. This module turns what setup really did and
+ * really read into four things, and nothing else:
+ *
+ *   ticks     one line per step that finished, with its time from the start of setup ("Folder ready: ~/PMOS/checkout · 0:02")
+ *   portrait  "Here is <product> as I see it": a header and up to three cells (THE GOAL, THE TIME, THE WORK). A cell is drawn only when a
+ *             source returned its facts (zero is silence, proven-only). Every cell names its source.
+ *   draft     the first initiative, drafted from the purpose: title, workflow, Triage, expected outcome, check date, owner, the next step.
+ *             Nothing is written until the PM presses ✓ (keep below).
+ *   left      what Home's list shows from the start: the draft row, the weekly, the PM's own tickets.
+ *
+ *   model({ st, journal, ws, today, workflow }) → { ok, name, ticks, portrait, draft, quiet, left }      PURE
+ *   draftOf(st, { today, workflow })           → the draft alone                                       PURE
+ *   keep(ctx, { ws, outcome?, actor })         → { ok, id, outcome?, horizon?, anchor }                the PM's ✓
+ *   read(runtimeDir, ws) / write(runtimeDir, ws, v)   the decision per product: { kept: { id, at } } | { dropped: at }
+ *
+ * WHERE THE FACTS COME FROM. The onboarding progress record (lib/routes-onboard.js, runtime folder): project, review.fields (each field with
+ * its source), found.findings and found.facts, and the init journal (each step's time). found.facts is what the read-only search returned as
+ * numbers, each citing one finding (lib/project-onboard.js search): jira { key, open, mine, due_week }, weekly { title, weekday, time, next },
+ * goal { metric, now, target }, timeline { start, end }. Facts of a finding that does not exist are dropped there, before they reach here.
+ *
+ * WHAT ✓ WRITES (keep). One initiative, through the Board's own Add an ask + Accept (lib/routes-boards.js writeAs: the record by
+ * lib/initiative-writer.js, its place in Triage on the product's board, the default workflow). Then its expected outcome and check date
+ * (initiative-writer setOutcome) and its description from the purpose (setDescription). The anchor is the product's first key result. A
+ * product with no key result yet gets one goal file with ONE key result, the expected outcome the PM just kept (the card says so before ✓):
+ * an initiative is never written unanchored (D59), and never anchored to an engineering health budget it does not serve.
+ */
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+
+const DAY = 864e5;
+const DEFAULT_DAYS = 90;   // the same default as lib/outcomes.js when no date is cited
+const MON = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'];
+const WEEKDAYS = ['sun', 'mon', 'tue', 'wed', 'thu', 'fri', 'sat'];
+
+const one = (v, n = 300) => String(v == null ? '' : v).replace(/[\u0000-\u001f\u007f]+/g, ' ').replace(/\s+/g, ' ').trim().slice(0, n);
+const clip = (s, n) => { const t = one(s, 2000); if (t.length <= n) return t; const c = t.slice(0, n - 1); return (c.slice(0, c.lastIndexOf(' ')) || c).replace(/[,;:\s]+$/, '') + '…'; };
+const isDay = (s) => /^\d{4}-\d{2}-\d{2}$/.test(String(s || '')) && Number.isFinite(Date.parse(s + 'T00:00:00Z'));
+const dn = (d) => Math.round(Date.parse(d + 'T00:00:00Z') / DAY);
+const isoN = (n) => new Date(n * DAY).toISOString().slice(0, 10);
+const md = (d) => { const t = new Date(Date.parse(d + 'T00:00:00Z')); return t.getUTCDate() + ' ' + MON[t.getUTCMonth()]; };
+const ms = (v) => { const t = Date.parse(v || ''); return Number.isFinite(t) ? t : null; };
+const clock = (n) => { const s = Math.max(0, Math.round(n / 1000)); return Math.floor(s / 60) + ':' + String(s % 60).padStart(2, '0'); };
+const num = (v) => { const m = /-?\d+(?:[.,]\d+)?/.exec(String(v == null ? '' : v)); return m ? Number(m[0].replace(',', '.')) : null; };
+const tilde = (p, home) => (home && p && (p === home || p.startsWith(home + path.sep)) ? '~' + p.slice(home.length) : p);
+const initials = (name) => one(name, 80).split(/\s+/).filter(Boolean).slice(0, 2).map((w) => w[0].toUpperCase()).join('') || 'P';
+const plural = (n, a, b) => n + ' ' + (n === 1 ? a : b);
+const val = (f) => (f && typeof f === 'object' && one(f.value) ? one(f.value, 400) : '');
+
+/* ── the decision store (per user, never in a repository) ── */
+function fileOf(runtimeDir, ws) { return path.join(runtimeDir, 'onboarding', 'reveal-' + crypto.createHash('sha256').update(String(ws)).digest('hex').slice(0, 16) + '.json'); }
+function read(runtimeDir, ws) { try { const v = JSON.parse(fs.readFileSync(fileOf(runtimeDir, ws), 'utf8')); return v && typeof v === 'object' ? v : {}; } catch { return {}; } }
+function write(runtimeDir, ws, v) {
+  const f = fileOf(runtimeDir, ws); fs.mkdirSync(path.dirname(f), { recursive: true, mode: 0o700 });
+  const tmp = f + '.' + crypto.randomBytes(6).toString('hex') + '.tmp';
+  try { fs.writeFileSync(tmp, JSON.stringify({ ...v, ws, updated_at: new Date().toISOString() }) + '\n', { mode: 0o600, flag: 'wx' }); fs.renameSync(tmp, f); }
+  finally { try { fs.unlinkSync(tmp); } catch {} }
+  return v;
+}
+
+/* ── the facts, with their sources ── */
+function findingOf(st, id) { return ((st.found && st.found.findings) || []).find((f) => f.id === id) || null; }
+/** A fact is used only when the finding it cites is there: its source label and title go under the cell. */
+function fact(st, k) {
+  const x = st.found && st.found.facts && st.found.facts[k];
+  if (!x || typeof x !== 'object') return null;
+  const f = findingOf(st, x.finding);
+  return f ? { ...x, src: { label: f.source_label, title: f.title, url: f.url || null } } : null;
+}
+function srcOfField(f) {
+  if (!f) return null;
+  if (f.source === 'finding') return { label: f.source_label, title: f.title || '', url: f.url || null };
+  if (f.source === 'folder') return { label: 'The folder', title: f.title || '' };
+  return { label: 'You', title: '' };
+}
+function fieldsOf(st) { return (st.review && st.review.fields) || {}; }
+function jiraKeyOf(st) {
+  const j = fact(st, 'jira'); if (j && /^[A-Z][A-Z0-9_]{1,19}$/.test(String(j.key || ''))) return j.key;
+  const rv = st.review && st.review.jira; return rv && rv !== 'none' ? rv : '';
+}
+
+/* ── the draft ── */
+/** The title from the purpose: its first clause, as a short line; the product's name when there is no purpose. */
+function titleOf(purpose, name) {
+  const p = one(purpose, 400).replace(/^(we|i)\s+(want|need|aim|plan)\s+to\s+/i, '').replace(/^(to|so that)\s+/i, '');
+  const first = (p.split(/(?<=[.!?])\s|;|\s[—–]\s/)[0] || '').replace(/[.!?]+$/, '').trim();
+  const t = first ? clip(first, 70).replace(/…$/, '') : one(name, 70);
+  return t ? t[0].toUpperCase() + t.slice(1) : 'First initiative';
+}
+function outcomeOf(st) {
+  const g = fact(st, 'goal');
+  if (g && one(g.metric)) {
+    const now = one(g.now, 24), target = one(g.target, 24);
+    return { metric: clip(one(g.metric, 200) + (now && target ? ' from ' + now + ' to ' + target : target ? ' to ' + target : ''), 300), src: g.src };
+  }
+  const goals = fieldsOf(st).goals;
+  if (val(goals) && val(goals).length >= 8) return { metric: clip(val(goals), 300), src: srcOfField(goals) };
+  return null;
+}
+function horizonOf(st, today) {
+  const t = fact(st, 'timeline');
+  if (t && isDay(t.end) && dn(t.end) >= dn(today) + 7) return { day: t.end, why: 'the end of the timeline', src: t.src };
+  return { day: isoN(dn(today) + DEFAULT_DAYS), why: DEFAULT_DAYS + ' days from today', src: null };
+}
+function nextOf(st) {
+  const docs = ((st.found && st.found.findings) || []).filter((f) => /^(page|document)$/.test(f.kind)).slice(0, 2).map((f) => 'the ' + clip(f.title, 40).replace(/^the\s+/i, ''));
+  const j = fact(st, 'jira'), key = jiraKeyOf(st);
+  const parts = docs.slice();
+  if (j && Number.isFinite(num(j.open)) && num(j.open) > 0) parts.push(plural(num(j.open), 'ticket', 'tickets') + (key ? ' in ' + key : ''));
+  const from = parts.length ? ' from ' + (parts.length > 1 ? parts.slice(0, -1).join(', ') + ' and ' + parts[parts.length - 1] : parts[0]) : '';
+  return 'Next: a BRD' + from + '. I’ll draft it once you keep this.';
+}
+function draftOf(st, { today, workflow = 'Product feature' } = {}) {
+  const f = fieldsOf(st), name = val(f.name) || one(st.project && st.project.name, 120);
+  const purpose = val(f.purpose);
+  const out = outcomeOf(st), h = horizonOf(st, today);
+  return {
+    title: titleOf(purpose, name), workflow, stage: 'Triage', purpose, purpose_src: srcOfField(f.purpose),
+    outcome: out ? out.metric : '', outcome_src: out ? out.src : null,
+    horizon: h.day, horizon_label: md(h.day), horizon_why: h.why, horizon_src: h.src,
+    owner: val(f.owner) || 'You', owner_src: val(f.owner) ? srcOfField(f.owner) : null,
+    next: nextOf(st),
+  };
+}
+
+/** What the initiative's chat is asked once the PM keeps the draft: the BRD, from the same sources, with its open questions marked. */
+function brdPrompt(st, draft) {
+  const docs = ((st.found && st.found.findings) || []).filter((f) => /^(page|document)$/.test(f.kind)).slice(0, 3).map((f) => f.title + (f.url ? ' (' + f.url + ')' : ''));
+  const key = jiraKeyOf(st);
+  return ['Draft the BRD for this initiative, "' + draft.title + '", in Triage.', docs.length ? 'Read ' + docs.join('; ') + '.' : '', key ? 'Read the open tickets in Jira ' + key + ', read-only.' : '',
+    'Mark every open question as a question, and do not guess an answer. Then open the BRD in the Viewer at its open questions.'].filter(Boolean).join(' ');
+}
+
+/* ── the portrait ── */
+function goalCell(st) {
+  const g = fact(st, 'goal');
+  if (g && one(g.metric)) {
+    const now = num(g.now), target = num(g.target);
+    const pct = Number.isFinite(now) && Number.isFinite(target) && target > 0 ? Math.max(0, Math.min(100, Math.round((now / target) * 100))) : null;
+    return { key: 'goal', label: 'THE GOAL', metric: one(g.metric, 120), now: one(g.now, 24), target: one(g.target, 24), pct, src: g.src };
+  }
+  const goals = fieldsOf(st).goals;
+  if (val(goals) && goals.source !== 'you') return { key: 'goal', label: 'THE GOAL', metric: clip(val(goals), 120), now: '', target: '', pct: null, src: srcOfField(goals) };
+  return null;
+}
+/** The weekly's dates from the next one on, every 7 days, up to the end (at most 12). */
+function weeklyDates(w, today, end) {
+  let start = isDay(w.next) ? dn(w.next) : null;
+  if (start == null) {
+    const wd = WEEKDAYS.indexOf(String(w.weekday || '').slice(0, 3).toLowerCase());
+    if (wd < 0) return [];
+    const t = dn(today), cur = new Date(t * DAY).getUTCDay();
+    start = t + ((wd - cur + 7) % 7);
+  }
+  const out = [];
+  for (let d = start; d <= end && out.length < 12; d += 7) out.push(isoN(d));
+  return out;
+}
+function timeCell(st, draft, today) {
+  const t = fact(st, 'timeline'), w = fact(st, 'weekly');
+  if (!t && !w) return null;
+  const start = t && isDay(t.start) ? Math.min(dn(t.start), dn(today)) : dn(today);
+  const end = Math.max(t && isDay(t.end) ? dn(t.end) : 0, dn(draft.horizon), start + 28);
+  const at = (d) => Math.round(((dn(d) - start) / (end - start)) * 1000) / 10;
+  const months = [];
+  for (let d = new Date(start * DAY); d.getTime() <= end * DAY; d = new Date(Date.UTC(d.getUTCFullYear(), d.getUTCMonth() + 1, 1))) {
+    const day = d.toISOString().slice(0, 10); months.push({ label: MON[d.getUTCMonth()], at: Math.max(0, at(day)) });
+  }
+  const weekly = w ? weeklyDates(w, today, end).map((d) => ({ day: d, at: at(d) })) : [];
+  const line = t && isDay(t.start) && isDay(t.end) ? md(t.start) + ' to ' + md(t.end) : '';
+  const meet = w ? [one(w.title, 60), [one(w.weekday, 12), one(w.time, 8)].filter(Boolean).join(' ')].filter(Boolean).join(' · ') : '';
+  return { key: 'time', label: 'THE TIME', line, meet, months, today: at(today), weekly, check: { day: draft.horizon, label: md(draft.horizon), at: at(draft.horizon) },
+    src: [t && t.src, w && w.src].filter(Boolean) };
+}
+function workCell(st) {
+  const j = fact(st, 'jira');
+  if (!j || !Number.isFinite(num(j.open))) return null;
+  const mine = num(j.mine), due = num(j.due_week);
+  return { key: 'work', label: 'THE WORK', key_: jiraKeyOf(st), open: num(j.open), mine: Number.isFinite(mine) ? mine : null, due_week: Number.isFinite(due) ? due : null,
+    read_at: (st.found && st.found.at) || null, src: j.src };
+}
+
+/* ── the ticks ── */
+function ticksOf(st, journal, home) {
+  const steps = (journal && journal.steps) || (st.init && st.init.steps) || {};
+  const found = st.found || null;
+  const t0 = [found && found.started_at, found && found.at, st.discovered && st.discovered.at, journal && journal.started_at].map(ms).filter((x) => x != null).reduce((a, b) => Math.min(a, b), Infinity);
+  if (!Number.isFinite(t0)) return [];
+  const out = [];
+  const add = (at, text) => { const t = ms(at); if (t != null) out.push({ t, text, at: clock(t - t0) }); };
+  const root = st.done && st.done.root;
+  if (steps.folder && steps.folder.state === 'done') add(steps.folder.at, 'Folder ready: ' + tilde(root || (journal && journal.root) || '', home));
+  if (found) {
+    const read = (found.sources || []).filter((s) => s.state === 'found' || s.state === 'empty');
+    const docs = (found.findings || []).filter((f) => /^(page|document)$/.test(f.kind)).slice(0, 1).map((f) => 'the ' + clip(f.title, 40).replace(/^the\s+/i, ''));
+    const key = jiraKeyOf(st);
+    const names = docs.concat(key && read.some((s) => /atlassian|jira/i.test(s.label)) ? ['Jira ' + key] : [])
+      .concat(read.filter((s) => !(key && /atlassian|jira/i.test(s.label)) && !(docs.length && (found.findings || []).some((f) => f.source === s.id && /^(page|document)$/.test(f.kind)))).map((s) => s.label));
+    if (names.length) add(found.at, 'Read ' + (names.length > 1 ? names.slice(0, -1).join(', ') + ' and ' + names[names.length - 1] : names[0]) + ', read-only');
+    const w = fact(st, 'weekly');
+    if (w) add(found.at, 'Found your ' + clip(w.title || 'weekly', 40).replace(/^your\s+/i, '') + ' in ' + w.src.label);
+  }
+  if (steps.kit && steps.kit.state === 'done') add(steps.kit.at, steps.kit.detail === 'reused' ? 'PMOS was already there, kept as it is' : 'PMOS added');
+  if (steps.context && steps.context.state === 'done') add(steps.context.at, 'Project context saved');
+  return out.sort((a, b) => a.t - b.t).map(({ text, at }) => ({ text, at }));
+}
+
+/* ── the whole reveal ── */
+function model({ st, journal = null, ws, today, workflow = 'Product feature', decided = {}, home = '', hasKr = true }) {
+  if (!st || !st.done || st.done.ws !== ws) return { ok: true, none: true };
+  const f = fieldsOf(st), name = val(f.name) || st.done.name || one(st.project && st.project.name, 120);
+  const draft = draftOf(st, { today, workflow });
+  const cells = [goalCell(st), timeCell(st, draft, today), workCell(st)].filter(Boolean);
+  const timeline = fact(st, 'timeline');
+  const header = { name, initials: initials(name), line: [val(f.team), workflow, timeline && isDay(timeline.end) ? 'until ' + md(timeline.end) : val(f.timeline) ? clip(val(f.timeline), 40) : ''].filter(Boolean) };
+  const miss = [!val(f.owner) && 'Owner', !val(f.goals) && !fact(st, 'goal') && 'goals'].filter(Boolean);
+  const quiet = miss.length ? (miss.length === 2 ? 'Owner and goals were' : miss[0][0].toUpperCase() + miss[0].slice(1) + (miss[0] === 'goals' ? ' were' : ' was')) + ' not in the notes. Say ' + (miss.length === 2 || miss[0] === 'goals' ? 'them' : 'it') + ' here any time; the portrait updates.' : '';
+  const w = fact(st, 'weekly'), work = workCell(st);
+  const state = decided.kept ? 'kept' : decided.dropped ? 'dropped' : 'open';
+  const left = {
+    draft: state === 'open' ? { title: draft.title, stage: 'Triage', check: draft.horizon_label } : null,
+    weekly: w ? { title: one(w.title, 80), when: [one(w.weekday, 12), one(w.time, 8)].filter(Boolean).join(' '), next: isDay(w.next) ? md(w.next) : '' } : null,
+    mywork: work && work.mine != null && work.key_ ? { key: work.key_, mine: work.mine, due_week: work.due_week } : null,
+  };
+  return { ok: true, ws, name, at: st.done.at, state, kept: decided.kept || null,
+    ticks: ticksOf(st, journal, home), portrait: { header, cells, said: one(st.project && st.project.description, 400) }, draft: { ...draft, goal_new: !hasKr }, quiet, left,
+    brd: brdPrompt(st, draft) };
+}
+
+/* ── ✓ keep ── */
+function laneOf(root) {
+  const rows = require('./initiative-rows.js');
+  let groups = {}; try { groups = rows.workGroupOf(root); } catch { /* the writer says what is wrong */ }
+  const work = Object.keys(groups).filter((l) => groups[l] === 'work');
+  return ['feature', 'new-feature'].find((l) => work.includes(l)) || work[0] || 'feature';
+}
+/** The product's first key result, or null. */
+const DRAFT_GOALS = 'okrs-draft.md';   // the setup's PROPOSED goal (onboarding B1): not a goal the PM kept, so not an anchor here
+function keptOkrFiles(root) {
+  try { return (require('./okr-goals.js').read(root).files || []).filter((f) => path.basename(f) !== DRAFT_GOALS); } catch { return []; }
+}
+function firstKr(root) {
+  const rows = require('./initiative-rows.js');
+  if (!keptOkrFiles(root).length) return null;
+  try { const a = rows.anchorsOf(root).list().find((x) => x.kind === 'kr'); return a ? a.value : null; } catch { return null; }
+}
+function quarterOf(today) { const d = new Date(Date.parse(today + 'T00:00:00Z')); return d.getUTCFullYear() + '-Q' + (Math.floor(d.getUTCMonth() / 3) + 1); }
+/** One goal file with ONE key result: the outcome the PM kept on the card. Never over an existing file. → the anchor */
+function writeGoal(root, { name, purpose, outcome, today }) {
+  const pm = fs.existsSync(path.join(root, 'pmos', 'state')) ? path.join(root, 'pmos', 'planning') : path.join(root, 'planning');
+  const dir = path.join(pm, 'okrs'); fs.mkdirSync(dir, { recursive: true });
+  const q = quarterOf(today);
+  let file = path.join(dir, 'okrs-' + q + '.md');
+  for (let i = 2; fs.existsSync(file) && i < 50; i++) file = path.join(dir, 'okrs-' + q + '-' + i + '.md');
+  const obj = clip(purpose || name, 120).replace(/\n/g, ' ');
+  const draft = fs.existsSync(path.join(dir, DRAFT_GOALS));   // the outcome the PM kept replaces the setup's proposed goal (lib/okr-goals.js reads the line)
+  const text = ['---', 'type: Reference', `title: "Goals ${q}: ${String(name).replace(/"/g, "'")}"`, `timestamp: ${today}`, '---', '',
+    `# Goals ${q}`, '', `period: ${q}`, '', `Written by PMOS when you kept the first initiative. The key result is the expected outcome you kept. Change it here or in Intelligence.`, '',
+    ...(draft ? ['Supersedes `' + DRAFT_GOALS + '`', ''] : []),
+    `## O1 — ${obj}`, '', `- KR1 — ${one(outcome, 300)}`, ''].join('\n');
+  fs.writeFileSync(file, text, { flag: 'wx' });
+  return { anchor: 'O1.KR1', file: path.relative(root, file) };
+}
+
+/**
+ * The PM's ✓. ctx is the route ctx (getWs, runtimeDir, …); g the page press (pm-guard). Writes nothing when the decision was made already.
+ * outcome: what the PM typed on the card when the notes named none (optional).
+ */
+function keep(ctx, g, { ws, outcome, today, st }) {
+  const decided = read(ctx.runtimeDir, ws);
+  if (decided.kept) return { ok: true, id: decided.kept.id, again: true };
+  const w = ctx.getWs(ws);
+  if (!w || !w.root) return { ok: false, status: 404, error: 'That product is not in My Work any more.' };
+  const draft = draftOf(st, { today, workflow: 'Product feature' });
+  const metric = one(outcome, 300) || draft.outcome;
+  let anchor = firstKr(w.root), goal = null;
+  if (!anchor) {
+    if (!metric || metric.length < 8) return { ok: false, status: 400, field: 'outcome', error: 'Say what should change once it ships. It becomes the product’s first goal.' };
+    try { goal = writeGoal(w.root, { name: draft.title, purpose: draft.purpose || (st.done && st.done.name), outcome: metric, today }); anchor = goal.anchor; }
+    catch { return { ok: false, status: 500, error: 'The goal file could not be written. Nothing was saved.' }; }
+  }
+  const RB = require('./routes-boards.js');
+  const a = RB.writeAs(ctx, '/api/boards/asks/add', { ws: w.id, board: w.id, line: draft.title, source: 'Drafted at setup, kept by you' }, g);
+  if (!a.body || !a.body.ok) return { ok: false, status: a.status || 500, error: (a.body && a.body.error) || 'The initiative was not added.' };
+  const r = RB.writeAs(ctx, '/api/boards/asks/accept', { ws: w.id, board: w.id, ask: a.body.ask.id, title: draft.title, lane: laneOf(w.root), anchor }, g);
+  if (!r.body || !r.body.ok) return { ok: false, status: r.status || 500, error: (r.body && r.body.error) || 'The initiative was not started.' };
+  const id = r.body.initiative && r.body.initiative.id;
+  const W = require('./initiative-writer.js');
+  // It starts in the first stage of its workflow (D99: Triage on Product feature). Accept places a new initiative on the default workflow
+  // only when the default is not Product feature (routes-boards startOnDefault); on Product feature it would read the board's own first
+  // column (Discover). So the drafted initiative gets the line a workflow start writes, and stands in Triage like the card said.
+  let stage = r.body.stage || 'Triage';
+  try {
+    const WF = require(require('./repo-script.js').repoScript('workflows.js')), WS = require('./workflows-store.js');
+    const dir = ctx.stateDirFor && ctx.stateDirFor(w);
+    const def = dir ? WF.defaultOf(WS.library(dir)) : WF.defaultOf(null);
+    if (!r.body.wf && def.id === WF.PRODUCT_FEATURE_ID) { const file = RB.ledgerFile(ctx, w); if (file) RB.append(file, g.actor, { kind: 'ini-wf', board: w.id, id, wf: def.id, why: 'drafted at setup: it starts in Triage', start: true, moved: { from: r.body.stage || null, to: (def.stages[0] && def.stages[0].key) || 'triage' } }); }
+    stage = (def.stages[0] && def.stages[0].name) || stage;
+  } catch { /* the board's answer */ }
+  const wrote = { id, anchor, stage, ...(goal ? { goal: goal.file } : {}) };
+  if (metric && metric.length >= 8) { const o = W.setOutcome(w.root, id, { metric, horizon: draft.horizon }, { actor: g.actor, today }); if (o.ok) Object.assign(wrote, { outcome: metric, horizon: draft.horizon }); }
+  if (draft.purpose && draft.purpose.length >= 12) { const d = W.setDescription(w.root, id, clip(draft.purpose, W.DESC_MAX || 600), { actor: g.actor }); if (d.ok) wrote.description = true; }
+  write(ctx.runtimeDir, ws, { kept: { id, at: new Date().toISOString(), ...wrote } });
+  return { ok: true, ...wrote };
+}
+
+module.exports = { model, draftOf, keep, read, write, titleOf, weeklyDates, writeGoal, firstKr, DEFAULT_DAYS };

package/workspace/lib/headless.js

@@ -215,7 +215,7 @@ const TOOLS = Object.freeze({
 // without a prompt. The kinds below read the PM's sources through connectors (Jira, Confluence, Slack, the calendar, mail, Drive), and before
 // dontAsk they relied on the PM's default mode letting a read-only connector tool run. Now the server names those tools: the read-shaped tools
 // of the PM's connected servers (CONNECTOR_READ_SEED, plus what each run's init line reports, server.js), filtered by the same read-verb rule the
-// onboarding search uses (lib/project-onboard.js readTool). A connector WRITE is never named, so it is still denied. The other kinds read no
+// onboarding search uses (lib/connector-read.js readTool). A connector WRITE is never named, so it is still denied. The other kinds read no
 // connector and get none.
 const CONNECTOR_READ_KINDS = Object.freeze(['skill', 'report-setup', 'report-find', 'ms-review', 'propose', 'metric-draft', 'impact', 'metric-read',
   'report-sample-fetch', 'report-structure', 'report-structure-dry', 'report-structure-pull']);
@@ -235,7 +235,7 @@ const CONNECTOR_READ_SEED = Object.freeze([
 const MCP_TOOL_RE = /^mcp__[\w-]+__[\w.-]+$/;   // one exact tool: Claude Code's rule syntax, no server-wide or wildcard rule
 /** The read-shaped connector tools among `names` (a run's init line, or a cached list): exact names only, never a write verb. */
 function connectorReads(names) {
-  const { readTool } = require('./project-onboard.js');
+  const { readTool } = require('./connector-read.js');
   const out = [];
   for (const n of Array.isArray(names) ? names : []) {
     const t = String(n || '');