create-pmos 0.132.0 → 0.133.0

package/workspace/lib/vendor/scripts/nine-stages.js

@@ -0,0 +1,81 @@
+'use strict';
+/*
+ * The nine stage names as a label layer over the workflow engine's derived stage (run 3).
+ *
+ * The engine derives one of six rungs (intake, spec, contract, build, eval, accepted) from the steps
+ * it found. This file names the nine stages the PM sees and says which of them each lane uses. It
+ * never decides a stage itself: a stage is `done` only when a derived signal shows it, and a stage
+ * no record can yet show is `no-signal`, not guessed.
+ *
+ * The lane sets below are a proposal for the PM to correct (see the run 3 contract in the PRD).
+ */
+
+const STAGES = ['discover', 'ideate', 'strategize', 'prioritize', 'plan', 'build', 'deliver', 'monitor', 'evaluate'];
+
+const LABELS = {
+  discover: 'Discover', ideate: 'Ideate', strategize: 'Strategize', prioritize: 'Prioritize', plan: 'Plan',
+  build: 'Build', deliver: 'Deliver', monitor: 'Monitor', evaluate: 'Evaluate',
+};
+
+// Which stages each product-code lane uses. Stages not listed read `skipped`.
+const LANE_STAGES = {
+  feature: STAGES,
+  discovery: ['discover', 'ideate', 'strategize', 'prioritize', 'evaluate'],
+  chore: ['plan', 'build', 'evaluate'],
+  incident: ['build', 'deliver', 'monitor', 'evaluate'],
+  content: ['ideate', 'plan', 'build', 'deliver'],
+  prototype: ['discover', 'ideate', 'evaluate'],
+};
+
+// Stages that have a derived signal today. Every other stage reads `no-signal` until its record exists.
+const SIGNALLED = new Set(['discover', 'plan', 'build', 'evaluate']);
+
+const RANK = { intake: 0, spec: 1, contract: 2, build: 3, eval: 4, accepted: 5 };
+
+// Stages that gain a signal only when the caller passes the records (scripts/records readAll plus optional `releases`).
+// With no records the output is exactly the older output, so the lifecycle-lens mirror stays equal.
+const RECORD_SIGNALLED = new Set(['ideate', 'strategize', 'prioritize', 'monitor', 'deliver']);
+
+// records: { initiative?, anchor?, ideas, hypotheses, decisions, bets, 'kr-metrics', releases } (every list optional).
+// The initiative id and anchor come from `derived` (id, anchor) or from records.initiative / records.anchor.
+function recordSignals(derived, records, buildDone) {
+  const id = (derived && derived.id) || records.initiative || null;
+  const anchor = (derived && derived.anchor) || records.anchor || null;
+  const mine = (list) => (list || []).filter((r) => id && r.initiative === id);
+  const kr = (records['kr-metrics'] || []).filter((m) => anchor && (m.rid === anchor || m.parent_kr === anchor || 'kr:' + m.rid === anchor));
+  return {
+    ideate: mine(records.ideas).length + mine(records.hypotheses).length > 0,
+    strategize: mine(records.decisions).length + mine(records.bets).length > 0,
+    prioritize: mine(records.bets).some((b) => ['now', 'next', 'later'].includes(b.horizon) && Number.isInteger(b.rank)),
+    monitor: !!buildDone && kr.some((m) => (m.readings || []).length > 0),
+    deliver: mine(records.releases).length > 0,
+  };
+}
+
+function nineStages(lane, derived, records) {
+  const laneSet = new Set(LANE_STAGES[lane] || STAGES);
+  const rank = RANK[derived && derived.stage] ?? 0;
+  const step = (key) => (derived && derived.steps || []).find((s) => s.key === key);
+  const done = {
+    discover: rank >= 1,
+    plan: rank >= 2,
+    build: rank >= 3 || (step('build') && step('build').status === 'done'),
+    evaluate: rank >= 4,
+  };
+  const accepted = rank >= 5;
+  const fromRecords = records && typeof records === 'object' ? recordSignals(derived, records, done.build) : null;
+  const out = [];
+  let currentSet = false;
+  for (const key of STAGES) {
+    let status;
+    if (!laneSet.has(key)) status = 'skipped';
+    else if (!SIGNALLED.has(key) && !(fromRecords && RECORD_SIGNALLED.has(key) && (key !== 'deliver' || fromRecords.deliver))) status = 'no-signal';
+    else if (done[key] || (fromRecords && fromRecords[key])) status = 'done';
+    else status = 'pending';
+    if (status === 'pending' && !currentSet) { status = 'current'; currentSet = true; }
+    out.push({ key, label: LABELS[key], status, accepted: key === 'evaluate' ? accepted : undefined });
+  }
+  return out;
+}
+
+module.exports = { STAGES, LABELS, LANE_STAGES, nineStages };

package/workspace/lib/vendor/scripts/onboarding/apply.js

@@ -0,0 +1,110 @@
+'use strict';
+/* apply.js: take the proposed structure into the per-user overlay, with a reverse manifest (slice 2). Nothing is written into the scanned folder.
+ *   apply(dir, structure, { include, revisions, answers, actor, now, root }) -> { import_id, boards, initiatives, skipped, manifest }
+ *   undo(dir, import_id, { actor, now }) -> { retracted, import_id }       one `retract` event; nothing is deleted
+ *   importedFor(dir) -> { boards, initiatives, imports }                   the fold of <dir>/imports.jsonl
+ * <dir>/imports.jsonl holds, through scripts/trust/ledger.js (ULIDs in order, actor from the call path):
+ *   import { import_id, scan_id, include, fiscal? }   the press
+ *   board { import_id, board:{key,name,domain,template} }
+ *   initiative { import_id, board, proposal_id, initiative_id (the row id; `id` is the event's own ULID), title, lane, anchor, anchor_source, stage, open, docs, docs_total }
+ *   assign { import_id, initiative, board }
+ *   retract { import_id, events:[ids] }
+ * apply also records an approve (or a revise, for a renamed or moved row) for each included proposal in <dir>/proposals.jsonl.
+ * A human actor is required; a dir inside the scanned root is refused. */
+const fs = require('fs');
+const path = require('path');
+const ledger = require('../trust/ledger.js');
+const P = require('./proposals.js');
+
+const LANES = ['feature', 'discovery', 'chore', 'incident', 'content', 'prototype'];
+const TEMPLATES = ['product', 'project', 'simple'];
+const inside = (child, parent) => { const r = path.relative(path.resolve(parent), path.resolve(child)); return r === '' || (!r.startsWith('..') && !path.isAbsolute(r)); };
+const slug = (s) => String(s || '').toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 60) || 'initiative';
+const file = (dir) => path.join(dir, 'imports.jsonl');
+
+function apply(dir, structure, opts = {}) {
+  const actor = P.humanActor(opts.actor);
+  if (opts.root && inside(dir, opts.root)) throw new Error('refusing to write the import inside the scanned folder: ' + dir);
+  const at = opts.now || new Date().toISOString();
+  const revisions = opts.revisions || {}; const answers = opts.answers || {};
+  const allRows = structure.boards.flatMap((b) => b.initiatives.map((r) => ({ r, b })));
+  const include = new Set(Array.isArray(opts.include) ? opts.include : allRows.filter((x) => x.r.checked).map((x) => x.r.proposal_id));
+  const boardMeta = new Map(structure.boards.map((b) => [b.key, { key: b.key, name: b.name, domain: b.domain, template: b.template }]));
+  for (const [k, t] of Object.entries(answers.template || {})) { if (!TEMPLATES.includes(t)) throw new Error('template must be one of ' + TEMPLATES.join(', ')); if (boardMeta.has(k)) boardMeta.get(k).template = t; }
+  const picked = [];
+  for (const { r, b } of allRows) {
+    if (!include.has(r.proposal_id)) continue;
+    const rev = revisions[r.proposal_id] || {};
+    const row = Object.assign({}, r, { board: b.key, anchor_source: r.anchor_source });
+    if (rev.title) row.title = String(rev.title);
+    if (rev.board) { if (!boardMeta.has(rev.board)) throw new Error('unknown board ' + rev.board); row.board = rev.board; }
+    if (rev.lane) { if (!LANES.includes(rev.lane)) throw new Error('lane must be one of ' + LANES.join(', ')); row.lane = rev.lane; }
+    if (rev.anchor) { row.anchor = String(rev.anchor); row.anchor_source = 'confirmed'; }
+    else if (answers.anchor && row.anchor_source === 'proposed') {
+      // 'per-board' (or the one proposed anchor itself) is the PM accepting each board's domain anchor; anything else replaces it
+      if (answers.anchor !== 'per-board') row.anchor = String(answers.anchor);
+      row.anchor_source = 'confirmed';
+    }
+    row._rev = Object.keys(rev).length ? rev : null;
+    picked.push(row);
+  }
+  if (!picked.length) throw new Error('nothing to import: no row is included');
+  fs.mkdirSync(dir, { recursive: true });
+  const importId = 'imp_' + ledger.newId();
+  const used = new Set(); const ids = [];
+  const uniqueId = (row) => { const base = row.id ? String(row.id) : slug(row.title); let id = base; let n = 2; while (used.has(id)) id = base + '-' + n++; used.add(id); return id; };
+  const f = file(dir);
+  const put = (ev) => { const l = ledger.append(f, Object.assign({ id: ledger.newId(), at }, ev), actor); ids.push(l.id); return l; };
+  const used2 = picked.map((row) => Object.assign(row, { _id: uniqueId(row) }));
+  const boardKeys = [...new Set(used2.map((r) => r.board))].sort();
+  put({ kind: 'import', import_id: importId, scan_id: structure.scan_id, include: used2.length, fiscal: answers.fiscal || undefined, why: 'first-run import: ' + used2.length + ' initiatives into ' + boardKeys.length + ' boards' });
+  for (const k of boardKeys) put({ kind: 'board', import_id: importId, board: boardMeta.get(k), why: 'board for import ' + importId });
+  for (const r of used2.sort((a, b) => (a.board < b.board ? -1 : a.board > b.board ? 1 : a._id < b._id ? -1 : 1))) {
+    put({ kind: 'initiative', import_id: importId, board: r.board, proposal_id: r.proposal_id, initiative_id: r._id, title: r.title, lane: r.lane, anchor: r.anchor, anchor_source: r.anchor_source, stage: r.stage, open: r.open, docs: (r.docs || []).map((d) => d.file), docs_total: r.docs_total || 0, why: 'imported at first run' });
+    put({ kind: 'assign', import_id: importId, initiative: r._id, board: r.board, why: 'imported at first run' });
+  }
+  const known = new Set(P.load(path.join(dir, 'proposals.jsonl')).map((p) => p.proposal_id));
+  const pf = path.join(dir, 'proposals.jsonl'); const decisions = []; let skipped = 0;
+  for (const r of used2) {
+    if (!known.has(r.proposal_id)) { skipped++; continue; }
+    const rev = r._rev;
+    const d = rev ? P.decide(pf, { proposal_id: r.proposal_id, decision: 'revise', revision: rev, why: 'revised at first-run import' }, actor, { now: at })
+      : P.decide(pf, { proposal_id: r.proposal_id, decision: 'approve' }, actor, { now: at });
+    decisions.push(d.id);
+  }
+  const manifest = { import_id: importId, scan_id: structure.scan_id, at, by: actor.by, events: ids.slice(), decisions, skipped_decisions: skipped };
+  fs.mkdirSync(path.join(dir, 'imports'), { recursive: true });
+  fs.writeFileSync(path.join(dir, 'imports', importId + '.manifest.json'), JSON.stringify(manifest, null, 1) + '\n');
+  return { import_id: importId, boards: boardKeys.length, initiatives: used2.length, skipped, manifest };
+}
+
+function undo(dir, importId, opts = {}) {
+  const actor = P.humanActor(opts.actor);
+  const lines = ledger.read(file(dir));
+  const imp = lines.find((l) => l.kind === 'import' && l.import_id === importId);
+  if (!imp) throw new Error('unknown import ' + importId);
+  if (lines.some((l) => l.kind === 'retract' && l.import_id === importId)) throw new Error('import ' + importId + ' is already retracted');
+  const events = lines.filter((l) => l.import_id === importId && l.kind !== 'retract').map((l) => l.id);
+  const l = ledger.append(file(dir), { id: ledger.newId(), kind: 'retract', import_id: importId, events, at: opts.now || new Date().toISOString(), why: 'undo of import ' + importId }, actor);
+  return { retracted: events.length, import_id: importId, event: l.id };
+}
+
+function importedFor(dir) {
+  const lines = ledger.read(file(dir));
+  const retracted = new Set(lines.filter((l) => l.kind === 'retract').map((l) => l.import_id));
+  const imports = []; const boards = new Map(); const inits = new Map();
+  for (const l of lines) {
+    if (l.kind === 'import') imports.push({ import_id: l.import_id, at: l.at, boards: 0, initiatives: 0, retracted: retracted.has(l.import_id) });
+    const im = imports.find((x) => x.import_id === l.import_id);
+    if (!im) continue;
+    if (l.kind === 'board') { im.boards++; if (!im.retracted) boards.set(l.board.key, Object.assign({}, l.board, { import_id: l.import_id, source: 'import' })); }
+    else if (l.kind === 'initiative') {
+      im.initiatives++;
+      if (!im.retracted) inits.set(l.initiative_id, { proposal_id: l.proposal_id, id: l.initiative_id, title: l.title, board: l.board, lane: l.lane, anchor: l.anchor, anchor_source: l.anchor_source, stage: l.stage, open: l.open, docs: l.docs, docs_total: l.docs_total, import_id: l.import_id, source: 'import' });
+    } else if (l.kind === 'assign' && !im.retracted && inits.has(l.initiative)) inits.get(l.initiative).board = l.board;
+  }
+  const cmp = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
+  return { boards: [...boards.values()].sort((a, b) => cmp(a.key, b.key)), initiatives: [...inits.values()].sort((a, b) => cmp(a.board, b.board) || cmp(a.id, b.id)), imports };
+}
+
+module.exports = { apply, undo, importedFor };

package/workspace/lib/vendor/scripts/onboarding/brief.js

@@ -0,0 +1,154 @@
+'use strict';
+/* brief.js - the ONBOARDING BRIEF: what the user tells PMOS before the scan runs.
+ * Pure module. No file access, no model. A caller stores the text at <repo>/onboarding/brief.md.
+ * The file is OKF Markdown: frontmatter (keys on one line), sentences for a person, and one JSON block that holds the exact fields. */
+
+const KINDS = ['folder', 'repo', 'jira', 'confluence', 'drive', 'calendar', 'slack', 'mail', 'notion', 'figma', 'other'];
+const LOCAL_KINDS = ['folder', 'repo'];
+const SENSITIVITY = ['public', 'internal', 'confidential', 'personal'];
+const ACCESS = { LOCAL: 'local path', IMPORT: 'imported through a session with my own connection' };
+const BRIEF_TYPE = 'Reference'; // a registered frontmatter type (scripts/frontmatter_registry.txt)
+const MARK = 'pmos-onboarding-brief';
+
+const clone = (x) => JSON.parse(JSON.stringify(x));
+const now = () => new Date().toISOString();
+
+function newSource(o = {}) {
+  return { kind: 'folder', ref: '', scope: '', include: [], exclude: [], sensitivity: null, access: ACCESS.LOCAL, ...o };
+}
+
+function newBrief(o = {}) {
+  const b = {
+    type: BRIEF_TYPE,
+    title: 'Onboarding brief',
+    timestamp: now(),
+    sources: [],
+    product: '',
+    knownInitiatives: [],
+    vocabulary: { initiative: [], goal: [], fiscalYearStartMonth: null, quarterNames: [] },
+    horizonDays: null,
+    people: [],
+    goals: [],
+    doNotRead: [],
+    decisionsPending: [],
+    constraints: '',
+    history: [],
+    answered: [],
+    override: null,
+  };
+  const v = { ...b.vocabulary, ...(o.vocabulary || {}) };
+  const out = { ...b, ...clone(o), vocabulary: clone(v) };
+  out.sources = (o.sources || []).map((s) => newSource(clone(s)));
+  return out;
+}
+
+function validate(b) {
+  const e = [];
+  if (!b || typeof b !== 'object') return { valid: false, errors: ['the brief is not an object'] };
+  const arr = (k) => { if (!Array.isArray(b[k])) e.push(`${k} must be a list`); };
+  ['sources', 'knownInitiatives', 'people', 'goals', 'doNotRead', 'decisionsPending', 'history', 'answered'].forEach(arr);
+  if (b.type !== BRIEF_TYPE) e.push(`type must be ${BRIEF_TYPE}`);
+  if (typeof b.title !== 'string' || !b.title) e.push('title is required');
+  if (!b.timestamp || Number.isNaN(Date.parse(b.timestamp))) e.push('timestamp must be an ISO date');
+  (b.sources || []).forEach((s, i) => {
+    const p = `sources[${i}]`;
+    if (!KINDS.includes(s.kind)) e.push(`${p}.kind must be one of ${KINDS.join(', ')}`);
+    if (typeof s.ref !== 'string') e.push(`${p}.ref must be text`);
+    if (s.sensitivity !== null && !SENSITIVITY.includes(s.sensitivity)) e.push(`${p}.sensitivity must be one of ${SENSITIVITY.join(', ')}`);
+    if (![ACCESS.LOCAL, ACCESS.IMPORT].includes(s.access)) e.push(`${p}.access must be "${ACCESS.LOCAL}" or "${ACCESS.IMPORT}"`);
+    if (!Array.isArray(s.include) || !Array.isArray(s.exclude)) e.push(`${p}.include and ${p}.exclude must be lists`);
+  });
+  (b.knownInitiatives || []).forEach((k, i) => {
+    if (!k || typeof k.name !== 'string' || !Array.isArray(k.aliases)) e.push(`knownInitiatives[${i}] needs name and aliases[]`);
+  });
+  const v = b.vocabulary;
+  if (!v || !Array.isArray(v.initiative) || !Array.isArray(v.goal) || !Array.isArray(v.quarterNames)) e.push('vocabulary needs initiative[], goal[], quarterNames[]');
+  else if (v.fiscalYearStartMonth !== null && !(Number.isInteger(v.fiscalYearStartMonth) && v.fiscalYearStartMonth >= 1 && v.fiscalYearStartMonth <= 12)) e.push('vocabulary.fiscalYearStartMonth must be 1 to 12 or null');
+  if (b.horizonDays !== null && !(Number.isFinite(b.horizonDays) && b.horizonDays > 0)) e.push('horizonDays must be a positive number or null');
+  (b.people || []).forEach((p, i) => { if (!p || typeof p.name !== 'string') e.push(`people[${i}] needs a name`); });
+  if (typeof b.constraints !== 'string') e.push('constraints must be text');
+  if (b.override !== null && !(b.override && b.override.reason && b.override.by)) e.push('override needs reason and by');
+  return { valid: e.length === 0, errors: e };
+}
+
+/* ---- glob matching (shared by the assess and probe code) ---- */
+function globToRegExp(g) {
+  let s = '';
+  for (let i = 0; i < g.length; i++) {
+    const c = g[i];
+    if (c === '*') {
+      if (g[i + 1] === '*') { i++; if (g[i + 1] === '/') { i++; s += '(?:.*/)?'; } else s += '.*'; } else s += '[^/]*';
+    } else if (c === '?') s += '[^/]';
+    else s += c.replace(/[.+^${}()|[\]\\]/g, '\\$&');
+  }
+  return new RegExp(`^${s}$`, 'i');
+}
+/* A pattern with no slash matches any file or folder name at any depth. A trailing slash means "everything inside". */
+function matchGlob(pattern, relPath) {
+  let p = String(pattern || '').trim();
+  if (!p) return false;
+  const rel = relPath.replace(/\\/g, '/').replace(/^\.?\//, '');
+  if (p.endsWith('/')) p += '**';
+  p = p.replace(/^\//, '');
+  if (!p.includes('/')) return rel.split('/').some((seg) => globToRegExp(p).test(seg));
+  return globToRegExp(p).test(rel) || globToRegExp(p.replace(/\/\*\*$/, '')).test(rel);
+}
+const matchesAny = (patterns, rel) => (patterns || []).some((p) => matchGlob(p, rel));
+
+/* ---- text rendering and parsing ---- */
+const oneLine = (s) => String(s).replace(/\s+/g, ' ').replace(/"/g, "'").trim();
+const list = (a) => (a && a.length ? a.join(', ') : 'none');
+
+function renderBody(b) {
+  const L = [];
+  L.push(`# ${b.title}`, '', 'This brief tells the scan what to read and how to read it.', '');
+  L.push('## Sources', '');
+  if (!b.sources.length) L.push('No source is named yet.');
+  b.sources.forEach((s, i) => {
+    L.push(`${i + 1}. ${s.kind}: ${s.ref || '(no reference)'}.`);
+    L.push(`   - What counts: ${s.scope || 'not said'}.`);
+    L.push(`   - Include: ${list(s.include)}. Exclude: ${list(s.exclude)}.`);
+    L.push(`   - Sensitivity: ${s.sensitivity || 'not said'}. Access: ${s.access}.`);
+  });
+  L.push('', '## Product and initiatives', '');
+  L.push(`The product is ${b.product || 'not named'}.`);
+  if (b.knownInitiatives.length) b.knownInitiatives.forEach((k) => L.push(`- ${k.name}${k.aliases.length ? ` (also: ${k.aliases.join(', ')})` : ''}`));
+  else L.push('No initiative is named yet.');
+  L.push('', '## Words you use', '');
+  L.push(`One piece of work is called: ${list(b.vocabulary.initiative)}.`);
+  L.push(`A goal is called: ${list(b.vocabulary.goal)}.`);
+  L.push(`The fiscal year starts in month: ${b.vocabulary.fiscalYearStartMonth || 'not said'}.`);
+  L.push(`Quarter names: ${list(b.vocabulary.quarterNames)}.`);
+  L.push('', '## Horizon, people and goals', '');
+  L.push(`Look ahead: ${b.horizonDays ? `${b.horizonDays} days` : 'not said'}.`);
+  b.people.forEach((p) => L.push(`- ${p.name}${p.role ? `, ${p.role}` : ''}${p.audience ? `. Audience: ${p.audience}` : ''}`));
+  if (!b.people.length) L.push('No person is named yet.');
+  L.push('', 'What you want from the first look:');
+  if (b.goals.length) b.goals.forEach((g) => L.push(`- ${oneLine(g)}`)); else L.push('- not said');
+  L.push('', '## Boundaries', '');
+  L.push(`Do not read: ${list(b.doNotRead)}.`);
+  L.push(`Decisions still open: ${list(b.decisionsPending)}.`);
+  L.push(`Constraints: ${b.constraints ? oneLine(b.constraints) : 'none'}.`);
+  if (b.override) L.push('', `The scan was started with open blockers. Reason: ${oneLine(b.override.reason)} (by ${b.override.by}).`);
+  L.push('', '## Questions and answers', '');
+  if (!b.history.length) L.push('No question has been answered yet.');
+  b.history.forEach((h) => L.push(`- ${h.at || ''} ${h.by}: ${oneLine(h.question || h.kind)} Answer: ${oneLine(JSON.stringify(h.answer === undefined ? h.reason || '' : h.answer))}`));
+  return L.join('\n');
+}
+
+function serialize(b) {
+  const fm = ['---', `type: ${b.type}`, `title: "${oneLine(b.title)}"`, `timestamp: ${b.timestamp}`, '---'].join('\n');
+  const data = JSON.stringify(b, null, 2);
+  return `${fm}\n\n${renderBody(b)}\n\n## Exact fields\n\nThe scan reads this block. Edit the brief with the interview, not by hand.\n\n\`\`\`json ${MARK}\n${data}\n\`\`\`\n`;
+}
+
+function parse(text) {
+  const m = String(text).match(new RegExp('```json ' + MARK + '\\n([\\s\\S]*?)\\n```'));
+  if (!m) throw new Error('no exact-fields block found: this is not an onboarding brief');
+  const b = JSON.parse(m[1]);
+  const v = validate(b);
+  if (!v.valid) throw new Error('invalid brief: ' + v.errors.join('; '));
+  return b;
+}
+
+module.exports = { KINDS, LOCAL_KINDS, SENSITIVITY, ACCESS, BRIEF_TYPE, newBrief, newSource, validate, serialize, parse, globToRegExp, matchGlob, matchesAny, clone };

package/workspace/lib/vendor/scripts/onboarding/first-briefing.js

@@ -0,0 +1,41 @@
+'use strict';
+/* first-briefing.js: the first Briefing after an import (slice 2). firstBriefing(scan, imported, { today }) -> { items }
+ * At most five items, from the first-look findings, each mapped onto an imported initiative when the finding's evidence file is one of that
+ * initiative's documents, the proposal id matches, or the finding's candidate names the initiative id. Items with an initiative come first;
+ * room left over goes to open imported initiatives whose anchor is still only proposed. No model, no write. */
+const { findings } = require('./first-look.js');
+
+const MAX = 5;
+
+function firstBriefing(scan, imported, opts = {}) {
+  void opts;
+  const inits = (imported && imported.initiatives) || [];
+  const byDoc = new Map(); const byId = new Map(); const byProposal = new Map();
+  for (const i of inits) { byId.set(i.id, i); if (i.proposal_id) byProposal.set(i.proposal_id, i); for (const f of i.docs || []) if (!byDoc.has(f)) byDoc.set(f, i); }
+  const cand = new Map((scan.candidates || []).map((c) => [c.id, c]));
+  const ref = (i) => (i ? { id: i.id, title: i.title, board: i.board } : null);
+  const mapped = []; const rest = []; const asked = new Set();
+  for (const f of findings(scan)) {
+    const c = cand.get(f.proposal_id); const d = (c && c.detail) || {};
+    let hit = byProposal.get(f.proposal_id) || null;
+    for (const e of f.evidence) if (!hit && byDoc.has(e.file)) hit = byDoc.get(e.file);
+    for (const k of [d.id, d.initiative, ...(d.cited_by || [])]) if (!hit && k && byId.has(k)) hit = byId.get(k);
+    const evidence = f.evidence.slice(0, 2).map((e) => ({ file: e.file, line: e.line, quote: e.quote }));
+    if (f.kind === 'MISSING_ANCHOR' && hit) {
+      // the import gave it an anchor: a confirmed one settles the finding; a proposed one is still the PM's to confirm
+      if (hit.anchor_source !== 'proposed') continue;
+      asked.add(hit.id);
+      mapped.push({ title: `${hit.title} needs an anchor you confirm`, why: `It had no anchor. PMOS proposed ${hit.anchor}; PMOS rejects unanchored work and never invents a KR.`, initiative: ref(hit), evidence });
+      continue;
+    }
+    (hit ? mapped : rest).push({ title: f.title, why: f.why, initiative: ref(hit), evidence });
+  }
+  const items = [...mapped, ...rest].slice(0, MAX);
+  for (const i of inits) {
+    if (items.length >= MAX) break;
+    if (i.open && i.anchor_source === 'proposed' && !asked.has(i.id)) items.push({ title: `${i.title} needs an anchor you confirm`, why: `PMOS proposed ${i.anchor} for it; it rejects unanchored work and never invents a KR.`, initiative: ref(i), evidence: [] });
+  }
+  return { items };
+}
+
+module.exports = { firstBriefing };

package/workspace/lib/vendor/scripts/onboarding/first-look.js

@@ -0,0 +1,84 @@
+'use strict';
+/* first-look.js: the AHA report. firstLook(scan, today) -> { numbers, sentence, findings, markdown }.
+ * Every number comes from scan.totals (uncapped counts); every finding is a scan candidate with its file:line evidence and the
+ * proposal id it leads to. Findings are ranked by consequence, not by count. Text taken from the folder is untrusted data: it is
+ * shown datamarked (a leading mark) inside a code span, never as markdown a reader or an agent could take for an instruction. */
+const MARK = '▒';
+
+const code = (s) => '`' + MARK + ' ' + String(s).replace(/`/g, "'").replace(/\n/g, ' ') + '`';
+const ref = (e) => (e.line ? `${e.file}:${e.line}` : e.file);
+
+function goalBoost(goals) {
+  const g = (goals || []).join(' ').toLowerCase();
+  return { late: /late|overdue|slip|deadline|behind/.test(g) ? 15 : 0, owner: /owner|accountab|who/.test(g) ? 15 : 0, stale: /stale|old|outdated|fresh/.test(g) ? 15 : 0, anchor: /goal|okr|anchor|kr\b/.test(g) ? 15 : 0 };
+}
+
+function findings(scan) {
+  const out = []; const cs = scan.candidates; const boost = goalBoost(scan.brief && scan.brief.goals);
+  const win = (scan.windows) || { near: 30, far: 90 };
+  const push = (c, score, title, why) => out.push({ score, title, why, evidence: c.evidence, proposal_id: c.id, kind: c.kind, confidence: c.confidence, label: c.label });
+  const recById = new Map(cs.filter((c) => c.kind === 'INITIATIVE' && c.detail.id).map((c) => [c.detail.id, c]));
+  for (const c of cs) {
+    const d = c.detail;
+    if (c.kind === 'DEADLINE' && d.bucket === 'in_30' && c.confidence !== 'low') {
+      if (!d.owner) push(c, 100 - d.days + boost.owner, `Deadline ${d.iso} in ${d.days} days with no owner`, `A date within ${win.near} days is written in ${c.evidence[0].file}, and the document names no owner or author.`);
+      else push(c, 70 - d.days + boost.late, `Deadline ${d.iso} in ${d.days} days`, `Owner on the document: ${d.owner}.`);
+    } else if (c.kind === 'DEADLINE' && d.bucket === 'past' && d.days >= -60 && c.confidence === 'high' && !d.owner) push(c, 62 + boost.late, `Date ${d.iso} passed ${-d.days} days ago, no owner`, 'A strong deadline word sits next to a date that has passed, and the document names no owner.');
+    else if (c.kind === 'DEADLINE' && d.bucket === 'in_90' && c.confidence !== 'low') push(c, 45 - Math.floor(d.days / 10) + boost.late, `Deadline ${d.iso} in ${d.days} days`, `Inside the ${win.far}-day window.`);
+    else if (c.kind === 'MISSING_ANCHOR') push(c, (d.open ? 80 : 30) + boost.anchor, `${d.id} has no anchor`, 'PMOS rejects unanchored work: the PM names a KR or a health budget.');
+    else if (c.kind === 'STALE' && d.cited_by && d.cited_by.length) push(c, 72 + boost.stale, `Stale document cited by an open initiative`, `${c.evidence[0].file} was last committed ${d.age_days} days ago and ${d.cited_by.join(', ')} cites it.`);
+    else if (c.kind === 'STALE') push(c, 20 + boost.stale, `Untouched for ${d.age_days} days`, c.title);
+    else if (c.kind === 'DECISION' && c.detail.level === 'doc' && (c.detail.followups || 0) === 0) push(c, 50, `Decision with no follow-up: ${c.title}`, 'No other document links to it and it names no initiative.');
+    else if (c.kind === 'RISK' && d.blocked && !/^Blocked by:\s*\[[^\]]+\]\([^)]+\)\s*$/i.test(c.title)) push(c, 36, `Blocked: ${c.title}`, 'A blocker is written under a Blocked heading or prefix.');
+    else if (c.kind === 'KR' && c.confidence === 'low' && d.in_okr_doc) push(c, 28 + boost.anchor, `${d.id} has no complete metric`, 'The KR is written with neither a baseline nor a target; the metric is the first thing a plan needs.');
+    else if (c.kind === 'DUPLICATE' && c.confidence === 'high') push(c, 22, `Duplicate: ${c.evidence.length} places`, c.proposed.summary);
+  }
+  void recById;
+  // one finding per proposal and per file:line, and at most 3 of one kind (4 deadlines), so ten findings are ten different things
+  const seen = new Set(); const per = {};
+  const ranked = out.sort((a, b) => b.score - a.score || (a.proposal_id < b.proposal_id ? -1 : 1)).filter((f) => {
+    const k = f.evidence[0].file + ':' + f.evidence[0].line + (f.kind === 'KR' ? '' : '');
+    if (seen.has(f.proposal_id) || seen.has(k)) return false;
+    const cap = f.kind === 'DEADLINE' ? 4 : 3; per[f.kind] = (per[f.kind] || 0) + 1; if (per[f.kind] > cap) return false;
+    seen.add(f.proposal_id); seen.add(k); return true;
+  });
+  return ranked.slice(0, 10).map((f, i) => Object.assign({ rank: i + 1 }, f));
+}
+
+function firstLook(scan, today) {
+  const t = scan.totals; const day = today || scan.today; const win = scan.windows || { near: 30, far: 90 };
+  const dl = t.deadlines || { in_30: 0, in_90: 0, in_next_90: 0 };
+  const numbers = {
+    initiatives: t.initiatives, initiatives_anchored: t.initiatives_anchored, possible_initiatives: t.initiative_clusters || 0,
+    documents: t.documents, documents_with_frontmatter: t.documents_with_frontmatter,
+    deadlines_near: dl.in_30, deadlines_far: dl.in_next_90, near_days: win.near, far_days: win.far, deadlines_past: dl.past,
+    stale: t.stale, duplicates: t.duplicates, people: t.people, risks_or_questions: (t.risks || 0) + (t.open_questions || 0), git_history: !!t.git_history,
+  };
+  const n = numbers;
+  const sentence = `We found ${n.initiatives} initiatives (${n.initiatives_anchored} anchored), ${n.documents} documents (${n.documents_with_frontmatter} with frontmatter), ${n.deadlines_near} deadlines in the next ${n.near_days} days and ${n.deadlines_far} in the next ${n.far_days}, ${n.stale} documents untouched for 90 days, ${n.duplicates} duplicates, ${n.people} people, ${n.risks_or_questions} risks or open questions.`;
+  const top = findings(scan);
+  const L = [];
+  L.push('---', 'type: Reference', `title: "First look: ${String(scan.tenant_name).replace(/"/g, "'")} (${day})"`, `timestamp: ${day}`, '---', '');
+  L.push(`# First look: ${scan.tenant_name}`, '');
+  L.push(`Scan ${scan.scan_id} of ${scan.tenant_name}, read-only, today is ${day}. Every number below is counted from the scan; every finding cites a file and line. Nothing has been changed, and every finding is a proposal for you to approve, reject or revise.`, '');
+  L.push(`**${sentence}**`, '');
+  if (n.possible_initiatives) L.push(`Beside those records, ${n.possible_initiatives} possible initiatives were grouped from folders, briefs, Jira epic keys and documents that declare an initiative id. They are low or medium confidence: an agent grouping pass is the next slice, and you decide.`, '');
+  if (!n.git_history) L.push('This folder has no git history, so "untouched for 90 days" could not be counted. It is not zero; it is unknown.', '');
+  if (scan.brief) L.push(`The scan followed your onboarding brief: ${scan.brief.skipped_files} files were not opened (${Object.entries(scan.brief.skipped_by_reason).map(([k, v]) => `${v} by ${k}`).join('; ') || 'none'}).`, '');
+  L.push('## The ten findings that matter most', '');
+  if (!top.length) L.push('No finding reached the ranking rules in this scan.', '');
+  for (const f of top) {
+    L.push(`${f.rank}. **${f.title}** (${f.confidence} confidence, ${f.label})`);
+    L.push(`   ${f.why}`);
+    for (const e of f.evidence.slice(0, 2)) L.push(`   - ${ref(e)}: ${code(e.quote)}`);
+    L.push(`   - leads to proposal \`${f.proposal_id}\` (${f.kind})`);
+  }
+  L.push('', '## What the numbers are', '');
+  L.push(`- Initiatives and anchors: counted from initiative records (${t.initiatives_archived || 0} archived records are not counted). Anchored means the record names a parent_kr.`);
+  L.push(`- Deadlines: a date next to a trigger word (due, deadline, launch, release, go-live, by, ETA ...) in a document or a deadline-type frontmatter key. ${dl.past} more are in the past. A quarter with no year assumes the current year; a quarter under a fiscal start month is labelled an assumption.`);
+  L.push(`- Windows: next ${win.near} days and next ${win.far} days (the second includes the first).`);
+  L.push('- People: only from frontmatter owner, author, attendees and the like, and from Roles tables. No name is guessed from prose.', '');
+  return { numbers, sentence, findings: top, markdown: L.join('\n') + '\n' };
+}
+
+module.exports = { firstLook, findings };

package/workspace/lib/vendor/scripts/onboarding/infer-brief.js

@@ -0,0 +1,70 @@
+'use strict';
+/* infer-brief.js: a valid onboarding brief made from the folder alone (slice 2, scan first and ask later).
+ *   inferBrief(root, { today }) -> brief   (brief.js shape, `inferred: true`)
+ * Reads only file and folder NAMES and the first lines of a few markdown files, to learn which word the folder uses for a piece of work
+ * (initiative, epic, project, bet). No model, no network, no write. The same folder and the same today give the same brief. */
+const fs = require('fs');
+const path = require('path');
+const B = require('./brief.js');
+
+const DO_NOT_READ = ['.git/**', 'node_modules/**', '**/.env*', '**/*secret*', '**/*.pem', '**/*.key'];
+const WORDS = ['initiative', 'epic', 'project', 'bet'];
+const SKIP_DIR = /^(\.git|node_modules|\.next|dist|build|coverage|\.venv)$/;
+const MAX_FILES = 600; const MAX_DEPTH = 5; const MAX_HEAD = 300;
+
+/** Count the words the folder uses: folder names that are the word, and markdown lines that start `Word:` or `# Word:` in the first 40 lines. */
+function vocabulary(root) {
+  const count = Object.fromEntries(WORDS.map((w) => [w, 0]));
+  let seen = 0; let heads = 0;
+  const lineRe = new RegExp('^\\s*(?:#+\\s*)?(' + WORDS.join('|') + ')\\s*[:\\u2014\\u2013-]', 'i');
+  const dirRe = new RegExp('^(' + WORDS.join('|') + ')s?$', 'i');
+  (function walk(dir, depth) {
+    let ents; try { ents = fs.readdirSync(dir, { withFileTypes: true }); } catch { return; }
+    ents.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+    for (const e of ents) {
+      if (seen >= MAX_FILES) return;
+      const f = path.join(dir, e.name);
+      if (e.isDirectory()) {
+        if (SKIP_DIR.test(e.name) || depth >= MAX_DEPTH) continue;
+        const m = dirRe.exec(e.name); if (m) count[m[1].toLowerCase()]++;
+        walk(f, depth + 1);
+      } else if (e.isFile() && /\.(md|markdown)$/i.test(e.name) && !/secret|\.env/i.test(e.name)) {
+        seen++; if (heads >= MAX_HEAD) continue; heads++;
+        let text; try { const fd = fs.openSync(f, 'r'); const buf = Buffer.alloc(4096); const n = fs.readSync(fd, buf, 0, 4096, 0); fs.closeSync(fd); text = buf.slice(0, n).toString('utf8'); } catch { continue; }
+        for (const l of text.split('\n').slice(0, 40)) { const m = lineRe.exec(l); if (m) count[m[1].toLowerCase()]++; }
+      }
+    }
+  })(root, 0);
+  const used = WORDS.filter((w) => count[w] > 0).sort((a, b) => count[b] - count[a] || WORDS.indexOf(a) - WORDS.indexOf(b));
+  return used.length ? used : ['initiative'];
+}
+
+function inferBrief(root, opts = {}) {
+  const abs = path.resolve(root);
+  const today = opts.today || new Date().toISOString().slice(0, 10);
+  const b = B.newBrief({
+    title: 'Onboarding brief (inferred)',
+    timestamp: today + 'T00:00:00.000Z',
+    sources: [{ kind: 'folder', ref: abs, scope: 'everything in the folder', sensitivity: null, access: B.ACCESS.LOCAL }],
+    product: path.basename(abs),
+    vocabulary: { initiative: vocabulary(abs), goal: [], fiscalYearStartMonth: null, quarterNames: [] },
+    horizonDays: 30,
+    doNotRead: DO_NOT_READ.slice(),
+    constraints: 'Inferred from the folder alone. Nothing here was asked of the user.',
+  });
+  b.inferred = true;
+  const v = B.validate(b); if (!v.valid) throw new Error('inferred brief is invalid: ' + v.errors.join('; '));
+  return b;
+}
+
+/** The first-run scan: the inferred brief, then the read-only scan with every initiative kept. The default cap (80) suits a proposal list
+ * the PM reads; a portfolio must hold every initiative, or the boards silently miss some. */
+const FIRST_RUN_CAPS = { INITIATIVE: 5000 };
+function firstRunScan(root, opts = {}) {
+  const today = opts.today || new Date().toISOString().slice(0, 10);
+  const brief = opts.brief || inferBrief(root, { today });
+  const scan = require('./scan.js').scan(root, { domain: opts.domain, today, brief, caps: FIRST_RUN_CAPS });
+  return { brief, scan };
+}
+
+module.exports = { inferBrief, firstRunScan, DO_NOT_READ, FIRST_RUN_CAPS };