create-pmos 0.239.0 → 0.241.0

package/workspace/lib/report-structure.js

@@ -0,0 +1,515 @@
+'use strict';
+/* report-structure.js — the report structure step's file store, fold, validators and brief (initiative report-structure, contract sections 1 to 5).
+ *
+ *   paths(root, id)                           → { abs, rel, folder, dir, events, versions, pending, dry, checks, checksPending, brief, briefRel }   <state>/reports/<id>/structure/…
+ *   append(root, id, line, { actor, now })    → the line written. THE SINGLE WRITER of structure.jsonl. `at` and `actor` are set here.
+ *   readEvents(root, id) · fold(events)       → the current state (see FOLD) · stateOf(root, id)
+ *   validatePlan(plan, { charts })            → { ok, plan } | { ok: false, status, error }   the plan of section 3, cleaned (group derived, fixed sections set)
+ *   validateSource(source)                    → { ok, source } | refusal                    one source the PM adds (no `state`; the server sets it)
+ *   validateDry(dry, plan)                    → { ok, dry } | refusal                       a dry-run result (section 4)
+ *   validateCheck(check, kind)                → { ok, steps } | refusal                     the steps a check session wrote (section 5)
+ *   landVersion(root, id, plan, meta)         → { ok, n, plan }                             writes versions/S<n>.json and the version line (plus any `before` lines)
+ *   readVersion(root, id, n)                  → the plan of S<n> | null
+ *   rewriteVersion(root, id, n, plan)         → the plan written back to S<n>.json (accept links chart ids)
+ *   writeDry · readDry · writeCheck · readCheck · pendingCheck
+ *   writeBrief(root, id, setup, { now })      → { ok, path } | refusal                      brief.md (type Reference): the saved plan in words
+ *   structureAnswer(root, id, opts)           → the `structure` object GET /api/report-structure answers
+ *   savedOf(root, id)                         → { saved, at, charts, sections } | null      the setups GET carries this per setup
+ *   addSourceTo(plan, source, opts) · removeFrom(plan, kind, ref)   → the next plan (not yet validated) | refusal
+ *
+ * THE LINES of structure.jsonl. Every line is { ev, …, at, actor }. `actor` is the guard's actor for a press, or { by: 'pmos', via: 'job' } for a job:
+ *   describe {text} · turn {text, base, job} · version {n, turn, answer, questions?, options?, from?} · accept {n, charts: [ids]} · revert {n}
+ *   source {n, source} (the new source, with the version it made) · remove {n, kind, ref} · dry {run, n, ok} · check {source, ok, steps} · error {text, mode}
+ *
+ * FOLD. { description, log: [{ who: pm|pmos, text, at, n?, questions, options }], versions: Map n → meta, current, saved: { n, at } | null, dry: {run, n, at, ok} | null,
+ * errors: [], turns }. A torn line is skipped.
+ *
+ * THE VALIDATORS are the trust boundary for a job's output (PRD done-criterion 9): a plan or a dry result that holds an unknown kind, no fixed
+ * section, more than a limit, a script, an on* handler, javascript: or a URL in a text is refused and nothing lands. A URL is allowed in
+ * sources[].ref of a `link` or a `chrome` source and nowhere else.
+ *
+ * NOTHING HERE STARTS A JOB OR SENDS ANYTHING. lib/routes-report-structure.js starts the jobs and the check sessions and calls these writers.
+ */
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+const RD = require('./report-draft.js');
+const CS = require('./charts-store.js');
+
+const EVENTS = Object.freeze(['describe', 'turn', 'version', 'accept', 'revert', 'source', 'remove', 'dry', 'check', 'error']);
+const PMOS_KINDS = Object.freeze(['pmos-level', 'dashboard', 'chart', 'document', 'past-report']);
+const OUTSIDE_KINDS = Object.freeze(['connector', 'link', 'upload', 'person', 'chrome', 'computer']);
+const KINDS = Object.freeze([...PMOS_KINDS, ...OUTSIDE_KINDS]);
+const STATES = Object.freeze(['reached', 'not-connected', 'later', 'needs-you', 'off']);
+const FIXED = Object.freeze(['headline', 'needs', 'sources']);
+const LIMITS = Object.freeze({ sources: 12, charts: 16, sections: 10, options: 3, questions: 4, chips: 4, text: 600, turn: 4000 });
+const CHECK_STATES = Object.freeze(['works', 'needs-you', 'waiting']);
+const CHECK_STEPS = Object.freeze({
+  chrome: Object.freeze([['mac', 'PMOS runs on this Mac'], ['session', 'A session can start with Claude in Chrome'], ['extension', 'The Chrome extension answers'],
+    ['signed-in', 'You are signed in'], ['read', 'PMOS can read the numbers']]),
+  computer: Object.freeze([['mac', 'PMOS runs on this Mac'], ['session', 'A session can start with computer use'], ['permission', 'macOS allows screen and input'],
+    ['signed-in', 'You are signed in'], ['read', 'PMOS can read the numbers']]),
+});
+const CADENCE_RE = /^[a-z][a-z0-9-]{0,39}$/;
+const SLUG_RE = /^[a-z][a-z0-9-]{0,39}$/;
+const RUN_RE = /^[0-9a-f]{10}$/;
+const PMOS_ACTOR = Object.freeze({ by: 'pmos', via: 'job' });
+
+const isObj = (v) => !!v && typeof v === 'object' && !Array.isArray(v);
+const str = (v) => (typeof v === 'string' ? v : '');
+const refuse = (status, error) => ({ ok: false, status, error });
+const iso = (now) => new Date(now == null ? Date.now() : now).toISOString();
+const newRun = () => crypto.randomBytes(5).toString('hex');
+const clip = (s, n) => { const t = String(s == null ? '' : s).replace(/\r\n?/g, '\n').trim(); return t.length > n ? t.slice(0, n - 1) + '…' : t; };
+
+function writeAtomic(file, data) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const tmp = `${file}.tmp-${crypto.randomBytes(4).toString('hex')}`;
+  fs.writeFileSync(tmp, data);
+  fs.renameSync(tmp, file);
+}
+function readJson(file) { try { const o = JSON.parse(fs.readFileSync(file, 'utf8')); return isObj(o) ? o : null; } catch { return null; } }
+
+// ── paths ─────────────────────────────────────────────────────────────────────────────────────────────────
+function stateRel(root) { try { return RD.stateRel(root); } catch { return 'planning'; } }
+function paths(root, id) {
+  if (!CADENCE_RE.test(String(id || ''))) throw new Error('report-structure: not a report id: ' + JSON.stringify(id));
+  const abs = path.resolve(String(root));
+  const rel = `${stateRel(abs)}/reports/${id}`;
+  const folder = path.join(abs, rel);
+  const dir = path.join(folder, 'structure');
+  return { abs, rel, folder, dir, relDir: `${rel}/structure`, events: path.join(dir, 'structure.jsonl'), versions: path.join(dir, 'versions'), pending: path.join(dir, 'pending'),
+    dry: path.join(dir, 'dry'), checks: path.join(dir, 'checks'), checksPending: path.join(dir, 'checks', 'pending'), brief: path.join(dir, 'brief.md'), briefRel: `${rel}/structure/brief.md` };
+}
+
+// ── the one writer and the fold ───────────────────────────────────────────────────────────────────────────
+function append(root, id, line, { actor, now } = {}) {
+  if (!isObj(line) || !EVENTS.includes(line.ev)) throw new Error(`report-structure: unknown event ${JSON.stringify(line && line.ev)}`);
+  const p = paths(root, id);
+  const out = { ...line, at: iso(now), actor: isObj(actor) ? { by: str(actor.by), via: str(actor.via) } : { ...PMOS_ACTOR } };
+  fs.mkdirSync(p.dir, { recursive: true });
+  fs.appendFileSync(p.events, JSON.stringify(out) + '\n');
+  return out;
+}
+function readEvents(root, id) {
+  let text = '';
+  try { text = fs.readFileSync(paths(root, id).events, 'utf8'); } catch { return []; }
+  const out = [];
+  for (const raw of text.split('\n')) {
+    if (!raw.trim()) continue;
+    try { const l = JSON.parse(raw); if (isObj(l) && EVENTS.includes(l.ev)) out.push(l); } catch { /* a torn line is skipped */ }
+  }
+  return out;
+}
+const listOf = (v) => (Array.isArray(v) ? v : []);
+
+function fold(events) {
+  const st = { description: null, log: [], versions: new Map(), current: null, saved: null, dry: null, errors: [], turns: 0 };
+  for (const l of events) {
+    if (l.ev === 'describe') {
+      st.description = str(l.text) || st.description;
+      st.log.push({ who: 'pm', text: str(l.text), at: l.at });
+    } else if (l.ev === 'turn') {
+      st.turns++;
+      st.log.push({ who: 'pm', text: str(l.text), at: l.at });
+    } else if (l.ev === 'version') {
+      st.versions.set(l.n, { n: l.n, at: l.at, turn: str(l.turn), from: l.from || 'turn' });
+      st.current = l.n;
+      st.log.push({ who: 'pmos', text: str(l.answer) || `Made S${l.n}.`, at: l.at, n: l.n, questions: listOf(l.questions), options: listOf(l.options) });
+    } else if (l.ev === 'accept') {
+      st.saved = { n: l.n, at: l.at };
+      st.log.push({ who: 'pm', text: `Saved S${l.n} as the structure.`, at: l.at, n: l.n });
+    } else if (l.ev === 'revert') {
+      if (st.versions.has(l.n)) st.current = l.n;
+      st.log.push({ who: 'pm', text: `Back to S${l.n}. The next turn builds on it.`, at: l.at, n: l.n });
+    } else if (l.ev === 'source') {
+      st.log.push({ who: 'pm', text: `Added the source ${str(l.source && l.source.name) || str(l.source && l.source.id)}.`, at: l.at });
+    } else if (l.ev === 'remove') {
+      st.log.push({ who: 'pm', text: `Removed the ${str(l.kind)} ${str(l.ref)}.`, at: l.at });
+    } else if (l.ev === 'dry') {
+      st.dry = { run: str(l.run), n: l.n, at: l.at, ok: l.ok === true };
+    } else if (l.ev === 'error') {
+      st.errors.push({ text: str(l.text), at: l.at, mode: l.mode || null });
+      st.log.push({ who: 'pmos', text: str(l.text), at: l.at });
+    }
+  }
+  return st;
+}
+const stateOf = (root, id) => fold(readEvents(root, id));
+const nextN = (st) => (st.versions.size ? Math.max(...st.versions.keys()) : 0) + 1;
+
+// ── text safety ───────────────────────────────────────────────────────────────────────────────────────────
+const URL_RE = /\b(?:[a-z][a-z0-9+.-]*:\/\/|www\.)/i;
+/** Why a text is refused, or null: not text, too long, or it holds a script, an on* handler, javascript:/vbscript:, or (unless allowUrl) an address. */
+function badText(v, where, { allowUrl = false, max = LIMITS.text } = {}) {
+  if (typeof v !== 'string') return `${where} must be text`;
+  if (v.length > max) return `${where} is at most ${max} characters`;
+  if (/<\s*\/?\s*script/i.test(v)) return `${where} must not hold a script`;
+  if (/\b(?:javascript|vbscript)\s*:/i.test(v) || /data:\s*text\/html/i.test(v)) return `${where} must not hold a javascript: address`;
+  if (/<[^>]*\bon[a-z]+\s*=/i.test(v) || /\bon[a-z]+\s*=\s*["'`]/i.test(v)) return `${where} must not hold an on* handler`;
+  if (!allowUrl && URL_RE.test(v)) return `${where} must not hold an address (an address belongs only in the ref of a link or a Chrome source)`;
+  return null;
+}
+/** Read an optional text field. → { v } | { error } */
+function textField(o, key, where, opts) {
+  const raw = o[key];
+  if (raw === undefined || raw === null) return { v: '' };
+  const why = badText(raw, `${where}.${key}`, opts);
+  return why ? { error: why } : { v: raw.trim() };
+}
+
+// ── the plan ──────────────────────────────────────────────────────────────────────────────────────────────
+const groupOf = (kind) => (PMOS_KINDS.includes(kind) ? 'pmos' : 'outside');
+const defaultState = (kind) => (kind === 'past-report' ? 'later' : PMOS_KINDS.includes(kind) ? 'reached' : kind === 'chrome' || kind === 'computer' ? 'needs-you' : kind === 'person' || kind === 'upload' ? 'later' : 'not-connected');
+
+function cleanSource(s, where) {
+  if (!isObj(s)) return refuse(422, `${where} must be an object`);
+  if (!KINDS.includes(s.kind)) return refuse(422, `${where}.kind ${JSON.stringify(str(s.kind)).slice(0, 40)} is not a source kind (${KINDS.join(', ')})`);
+  if (!SLUG_RE.test(str(s.id))) return refuse(422, `${where}.id must be a short lowercase slug`);
+  const out = { id: s.id, kind: s.kind };
+  for (const k of ['name', 'via', 'use']) { const r = textField(s, k, where); if (r.error) return refuse(422, r.error); out[k] = r.v; }
+  if (!out.name) return refuse(422, `${where}.name is required`);
+  const urlKind = s.kind === 'link' || s.kind === 'chrome';
+  const ref = textField(s, 'ref', where, { allowUrl: urlKind });
+  if (ref.error) return refuse(422, ref.error);
+  if (urlKind && ref.v) {
+    let u = null; try { u = new URL(ref.v); } catch { u = null; }
+    if (!u || (u.protocol !== 'https:' && u.protocol !== 'http:')) return refuse(422, `${where}.ref must be a full https:// or http:// address`);
+  }
+  out.ref = ref.v;
+  if (s.state === undefined || s.state === null) out.state = defaultState(s.kind);
+  else if (!STATES.includes(s.state)) return refuse(422, `${where}.state ${JSON.stringify(str(s.state)).slice(0, 40)} is not one of ${STATES.join(', ')}`);
+  else out.state = s.state;
+  out.group = groupOf(s.kind);
+  return { ok: true, source: out };
+}
+
+function cleanChart(c, where, sourceIds, known) {
+  if (!isObj(c)) return refuse(422, `${where} must be an object`);
+  if (!SLUG_RE.test(str(c.id))) return refuse(422, `${where}.id must be a short lowercase slug`);
+  const out = { id: c.id, chart: null };
+  if (c.chart !== undefined && c.chart !== null) {
+    if (!CS.ID_RE.test(str(c.chart))) return refuse(422, `${where}.chart must be a chart id or null`);
+    if (known && !known.has(c.chart)) return refuse(422, `${where}.chart ${c.chart} is not in the chart store`);
+    out.chart = c.chart;
+  }
+  for (const k of ['name', 'question', 'from', 'how', 'compare', 'flag', 'query', 'why']) { const r = textField(c, k, where); if (r.error) return refuse(422, r.error); out[k] = r.v; }
+  const src = str(c.source);
+  if (!src || !sourceIds.has(src)) return refuse(422, `${where}.source ${JSON.stringify(src).slice(0, 40)} is not a source of the plan`);
+  out.source = src;
+  if (!out.chart) for (const k of ['name', 'question', 'from', 'how']) if (!out[k]) return refuse(422, `${where}.${k} is required for a new chart`);
+  if (out.chart && !out.name) return refuse(422, `${where}.name is required`);
+  return { ok: true, chart: out };
+}
+
+/** The plan of section 3, cleaned. `charts` (a Set of chart store ids) lets a From Charts chart be checked; without it any well-formed id passes. */
+function validatePlan(plan, { charts } = {}) {
+  if (!isObj(plan)) return refuse(422, 'the plan must be a JSON object');
+  const out = {};
+  // purpose
+  const pu = plan.purpose;
+  if (!isObj(pu)) return refuse(422, 'purpose is required');
+  out.purpose = {};
+  for (const k of ['readers', 'decision', 'scope', 'cadence']) { const r = textField(pu, k, 'purpose'); if (r.error) return refuse(422, r.error); out.purpose[k] = r.v; }
+  const qs = pu.questions === undefined ? [] : pu.questions;
+  if (!Array.isArray(qs)) return refuse(422, 'purpose.questions must be a list');
+  if (qs.length > LIMITS.questions) return refuse(422, `purpose.questions holds at most ${LIMITS.questions}`);
+  out.purpose.questions = [];
+  for (const [i, q] of qs.entries()) { const why = badText(q, `purpose.questions[${i}]`); if (why) return refuse(422, why); out.purpose.questions.push(q.trim()); }
+  // sources
+  if (!Array.isArray(plan.sources)) return refuse(422, 'sources must be a list');
+  if (plan.sources.length > LIMITS.sources) return refuse(422, `a plan holds at most ${LIMITS.sources} sources (this one has ${plan.sources.length})`);
+  out.sources = [];
+  const sourceIds = new Set();
+  for (const [i, s] of plan.sources.entries()) {
+    const r = cleanSource(s, `sources[${i}]`); if (!r.ok) return r;
+    if (sourceIds.has(r.source.id)) return refuse(422, `sources[${i}].id ${r.source.id} is used twice`);
+    sourceIds.add(r.source.id); out.sources.push(r.source);
+  }
+  // charts
+  if (!Array.isArray(plan.charts)) return refuse(422, 'charts must be a list');
+  if (plan.charts.length > LIMITS.charts) return refuse(422, `a plan holds at most ${LIMITS.charts} charts (this one has ${plan.charts.length})`);
+  out.charts = [];
+  const chartIds = new Set();
+  for (const [i, c] of plan.charts.entries()) {
+    const r = cleanChart(c, `charts[${i}]`, sourceIds, charts); if (!r.ok) return r;
+    if (chartIds.has(r.chart.id)) return refuse(422, `charts[${i}].id ${r.chart.id} is used twice`);
+    chartIds.add(r.chart.id); out.charts.push(r.chart);
+  }
+  // outline
+  if (!Array.isArray(plan.outline)) return refuse(422, 'outline must be a list');
+  if (plan.outline.length > LIMITS.sections) return refuse(422, `an outline holds at most ${LIMITS.sections} sections (this one has ${plan.outline.length})`);
+  const ids = plan.outline.map((o) => (isObj(o) ? o.id : null));
+  const n = ids.length;
+  if (n < 3 || ids[0] !== 'headline' || ids[n - 2] !== 'needs' || ids[n - 1] !== 'sources') {
+    return refuse(422, 'the outline must start with the fixed section headline and end with the fixed sections needs and sources');
+  }
+  out.outline = [];
+  const secIds = new Set();
+  for (const [i, o] of plan.outline.entries()) {
+    const where = `outline[${i}]`;
+    if (!isObj(o)) return refuse(422, `${where} must be an object`);
+    if (!SLUG_RE.test(str(o.id))) return refuse(422, `${where}.id must be a short lowercase slug`);
+    if (secIds.has(o.id)) return refuse(422, `${where}.id ${o.id} is used twice`);
+    secIds.add(o.id);
+    const fixed = FIXED.includes(o.id);
+    if (o.fixed === true && !fixed) return refuse(422, `${where}: only headline, needs and sources are fixed sections`);
+    const sec = { id: o.id, fixed };
+    for (const k of ['title', 'notes', 'show']) { const r = textField(o, k, where); if (r.error) return refuse(422, r.error); sec[k] = r.v; }
+    if (!sec.title) return refuse(422, `${where}.title is required`);
+    const cs = o.charts === undefined ? [] : o.charts;
+    if (!Array.isArray(cs)) return refuse(422, `${where}.charts must be a list of chart ids`);
+    for (const c of cs) if (typeof c !== 'string' || !chartIds.has(c)) return refuse(422, `${where}.charts names ${JSON.stringify(str(c)).slice(0, 40)}, which is not a chart of the plan`);
+    sec.charts = [...new Set(cs)];
+    out.outline.push({ id: sec.id, title: sec.title, fixed: sec.fixed, charts: sec.charts, notes: sec.notes, show: sec.show });
+  }
+  // options
+  const opts = plan.options === undefined || plan.options === null ? [] : plan.options;
+  const o2 = cleanOptions(opts, 'options'); if (!o2.ok) return o2;
+  out.options = o2.options;
+  return { ok: true, plan: out };
+}
+
+function cleanOptions(list, where) {
+  if (!Array.isArray(list)) return refuse(422, `${where} must be a list`);
+  if (list.length > LIMITS.options) return refuse(422, `${where} holds at most ${LIMITS.options} structures (this has ${list.length})`);
+  const out = [];
+  for (const [i, o] of list.entries()) {
+    const w = `${where}[${i}]`;
+    if (!isObj(o)) return refuse(422, `${w} must be an object`);
+    const c = {};
+    for (const k of ['name', 'good', 'misses']) { const r = textField(o, k, w); if (r.error) return refuse(422, r.error); c[k] = r.v; }
+    if (!c.name) return refuse(422, `${w}.name is required`);
+    const secs = o.sections === undefined ? [] : o.sections;
+    if (!Array.isArray(secs) || secs.length > LIMITS.sections) return refuse(422, `${w}.sections must be a list of at most ${LIMITS.sections}`);
+    c.sections = [];
+    for (const [j, s] of secs.entries()) { const why = badText(s, `${w}.sections[${j}]`); if (why) return refuse(422, why); c.sections.push(s.trim()); }
+    c.recommended = o.recommended === true;
+    out.push({ name: c.name, sections: c.sections, good: c.good, misses: c.misses, recommended: c.recommended });
+  }
+  return { ok: true, options: out };
+}
+/** The questions a job prints with its answer: [{ q, chips }]. A bad list is dropped, not an error. */
+function cleanQuestions(list) {
+  if (!Array.isArray(list)) return [];
+  const out = [];
+  for (const q of list.slice(0, LIMITS.questions)) {
+    if (!isObj(q) || badText(q.q, 'q')) continue;
+    const chips = listOf(q.chips).filter((c) => typeof c === 'string' && c.trim() && !badText(c, 'chip', { max: 80 })).slice(0, LIMITS.chips).map((c) => c.trim());
+    out.push({ q: q.q.trim(), chips });
+  }
+  return out;
+}
+
+/** One source the PM adds: the section 3 source with no `state`. The id is made from the name when none is given. */
+function validateSource(source, { taken = [] } = {}) {
+  if (!isObj(source)) return refuse(400, 'source must be an object');
+  if (source.state !== undefined && source.state !== null) return refuse(400, 'a source you add has no state: PMOS sets it');
+  const s = { ...source };
+  if (!s.id) {
+    const base = CS.slugOf(str(s.name) || str(s.kind));
+    let id = base; let k = 2;
+    while (taken.includes(id)) id = `${base.slice(0, 36)}-${k++}`;
+    s.id = id;
+  }
+  const r = cleanSource(s, 'source');
+  return r.ok ? r : refuse(400, r.error);
+}
+
+/** The next plan with the source added (not validated: the caller validates). */
+function addSourceTo(plan, source) {
+  if (listOf(plan.sources).some((s) => s.id === source.id)) return refuse(400, `the plan already has a source ${source.id}`);
+  if (listOf(plan.sources).length >= LIMITS.sources) return refuse(400, `a plan holds at most ${LIMITS.sources} sources`);
+  return { ok: true, plan: { ...plan, sources: [...plan.sources, source] } };
+}
+/** The next plan without a chart, a source or a section. A fixed section is refused; a source that charts read from is refused. */
+function removeFrom(plan, kind, ref) {
+  if (kind === 'chart') {
+    if (!plan.charts.some((c) => c.id === ref)) return refuse(404, `no chart ${ref} in this version`);
+    return { ok: true, plan: { ...plan, charts: plan.charts.filter((c) => c.id !== ref), outline: plan.outline.map((o) => ({ ...o, charts: o.charts.filter((c) => c !== ref) })) } };
+  }
+  if (kind === 'source') {
+    if (!plan.sources.some((s) => s.id === ref)) return refuse(404, `no source ${ref} in this version`);
+    const users = plan.charts.filter((c) => c.source === ref).map((c) => c.name || c.id);
+    if (users.length) return refuse(400, `${users.length === 1 ? 'a chart reads' : users.length + ' charts read'} from this source (${users.slice(0, 3).join(', ')}). Remove ${users.length === 1 ? 'it' : 'them'} first`);
+    return { ok: true, plan: { ...plan, sources: plan.sources.filter((s) => s.id !== ref) } };
+  }
+  if (kind === 'section') {
+    const sec = plan.outline.find((o) => o.id === ref);
+    if (!sec) return refuse(404, `no section ${ref} in this version`);
+    if (sec.fixed || FIXED.includes(ref)) return refuse(400, `${sec.title} is in every report and cannot be removed`);
+    return { ok: true, plan: { ...plan, outline: plan.outline.filter((o) => o.id !== ref) } };
+  }
+  return refuse(400, 'kind must be chart, source or section');
+}
+
+// ── dry run and checks ────────────────────────────────────────────────────────────────────────────────────
+function validateDry(dry, plan) {
+  if (!isObj(dry)) return refuse(422, 'the dry-run result must be a JSON object');
+  const chartIds = new Set(listOf(plan && plan.charts).map((c) => c.id));
+  const sourceIds = new Set(listOf(plan && plan.sources).map((s) => s.id));
+  const out = {};
+  if (!Number.isInteger(dry.n) || dry.n < 1) return refuse(422, 'n must be the version number');
+  out.n = dry.n;
+  const per = badText(dry.period, 'period', { max: 40 });
+  if (per || !dry.period.trim()) return refuse(422, per || 'period is required');
+  out.period = dry.period.trim();
+  const hl = badText(dry.headline, 'headline');
+  if (hl) return refuse(422, hl);
+  out.headline = dry.headline.trim();
+  const values = dry.values === undefined ? [] : dry.values;
+  if (!Array.isArray(values) || values.length > LIMITS.charts) return refuse(422, `values is a list of at most ${LIMITS.charts}`);
+  out.values = [];
+  for (const [i, v] of values.entries()) {
+    const w = `values[${i}]`;
+    if (!isObj(v)) return refuse(422, `${w} must be an object`);
+    if (!chartIds.has(str(v.chart))) return refuse(422, `${w}.chart ${JSON.stringify(str(v.chart)).slice(0, 40)} is not a chart of the plan`);
+    const c = { chart: v.chart };
+    for (const k of ['value', 'was', 'delta', 'note']) { const r = textField(v, k, w); if (r.error) return refuse(422, r.error); c[k] = r.v; }
+    if (v.flag !== undefined && typeof v.flag !== 'boolean') return refuse(422, `${w}.flag must be true or false`);
+    c.flag = v.flag === true;
+    out.values.push({ chart: c.chart, value: c.value, was: c.was, delta: c.delta, flag: c.flag, note: c.note });
+  }
+  const missing = dry.missing === undefined ? [] : dry.missing;
+  if (!Array.isArray(missing) || missing.length > LIMITS.sources) return refuse(422, `missing is a list of at most ${LIMITS.sources}`);
+  out.missing = [];
+  for (const [i, m] of missing.entries()) {
+    const w = `missing[${i}]`;
+    if (!isObj(m)) return refuse(422, `${w} must be an object`);
+    if (!sourceIds.has(str(m.source))) return refuse(422, `${w}.source ${JSON.stringify(str(m.source)).slice(0, 40)} is not a source of the plan`);
+    const r = textField(m, 'reason', w); if (r.error) return refuse(422, r.error);
+    out.missing.push({ source: m.source, reason: r.v });
+  }
+  const options = dry.options === undefined ? [] : dry.options;
+  if (!Array.isArray(options) || options.length > LIMITS.options) return refuse(422, `options is a list of at most ${LIMITS.options}`);
+  out.options = [];
+  for (const [i, o] of options.entries()) { const why = badText(o, `options[${i}]`); if (why) return refuse(422, why); out.options.push(o.trim()); }
+  return { ok: true, dry: out };
+}
+
+/** The steps a check session wrote. Steps it left out are 'waiting'; an unknown step or state is refused. → { ok, steps, pass } */
+function validateCheck(check, kind) {
+  const table = CHECK_STEPS[kind];
+  if (!table) return refuse(400, 'only a Chrome or a computer source has a check');
+  if (!isObj(check)) return refuse(422, 'the check result must be a JSON object');
+  const given = new Map();
+  for (const [i, s] of listOf(check.steps).entries()) {
+    if (!isObj(s) || !table.some(([id]) => id === s.id)) return refuse(422, `steps[${i}].id ${JSON.stringify(str(s && s.id)).slice(0, 40)} is not a step of a ${kind} check`);
+    if (!CHECK_STATES.includes(s.state)) return refuse(422, `steps[${i}].state must be works, needs-you or waiting`);
+    const r = textField(s, 'reason', `steps[${i}]`, { max: 300 }); if (r.error) return refuse(422, r.error);
+    given.set(s.id, { state: s.state, reason: r.v });
+  }
+  const steps = table.map(([id, label]) => { const g = given.get(id) || { state: 'waiting', reason: '' }; return { id, label, state: g.state, reason: g.reason }; });
+  return { ok: true, steps, pass: steps.every((s) => s.state === 'works') };
+}
+
+function writeDry(root, id, run, dry) { writeAtomic(path.join(paths(root, id).dry, `${run}.json`), JSON.stringify(dry, null, 2) + '\n'); }
+function readDry(root, id, run) { return RUN_RE.test(String(run)) ? readJson(path.join(paths(root, id).dry, `${run}.json`)) : null; }
+function writeCheck(root, id, check) {
+  if (!SLUG_RE.test(String(check.source))) throw new Error('report-structure: bad source id');
+  writeAtomic(path.join(paths(root, id).checks, `${check.source}.json`), JSON.stringify(check, null, 2) + '\n');
+}
+function readCheck(root, id, source) { return SLUG_RE.test(String(source)) ? readJson(path.join(paths(root, id).checks, `${source}.json`)) : null; }
+function readChecks(root, id) {
+  const out = {};
+  let names = [];
+  try { names = fs.readdirSync(paths(root, id).checks); } catch { return out; }
+  for (const f of names) { const m = /^([a-z][a-z0-9-]{0,39})\.json$/.exec(f); if (m) { const c = readJson(path.join(paths(root, id).checks, f)); if (c) out[m[1]] = c; } }
+  return out;
+}
+
+// ── versions ──────────────────────────────────────────────────────────────────────────────────────────────
+function readVersion(root, id, n) { return Number.isInteger(n) && n > 0 ? readJson(path.join(paths(root, id).versions, `S${n}.json`)) : null; }
+function rewriteVersion(root, id, n, plan) { writeAtomic(path.join(paths(root, id).versions, `S${n}.json`), JSON.stringify(plan, null, 2) + '\n'); return plan; }
+
+/** Validate, write S<n>.json, then the `before` lines and the version line. → { ok, n, plan } | refusal */
+function landVersion(root, id, plan, { turn, answer, questions, options, from, before, actor, now, charts } = {}) {
+  const v = validatePlan(plan, { charts });
+  if (!v.ok) return v;
+  const st = stateOf(root, id);
+  const n = nextN(st);
+  writeAtomic(path.join(paths(root, id).versions, `S${n}.json`), JSON.stringify(v.plan, null, 2) + '\n');
+  for (const b of listOf(before)) append(root, id, { ...b, n }, { actor, now });
+  const line = { ev: 'version', n, turn: clip(turn, LIMITS.turn), answer: clip(answer, LIMITS.turn), from: from || 'turn' };
+  const qs = cleanQuestions(questions); if (qs.length) line.questions = qs;
+  let opts = null;
+  if (Array.isArray(options)) { const o = cleanOptions(options, 'options'); if (o.ok) opts = o.options; }
+  if (!opts || !opts.length) opts = v.plan.options;
+  if (opts.length) line.options = opts;
+  append(root, id, line, { actor, now });
+  return { ok: true, n, plan: v.plan };
+}
+
+// ── the GET answer ────────────────────────────────────────────────────────────────────────────────────────
+/** Chrome and computer sources show what their last check found: a passing check is Reached, a failing one Needs you. */
+function overlay(plan, checks) {
+  if (!plan) return null;
+  return { ...plan, sources: plan.sources.map((s) => {
+    const c = checks[s.id];
+    if (!c || (s.kind !== 'chrome' && s.kind !== 'computer') || c.running) return s;
+    return { ...s, state: c.ok ? 'reached' : 'needs-you' };
+  }) };
+}
+function structureAnswer(root, id, { running } = {}) {
+  const st = stateOf(root, id);
+  const checks = readChecks(root, id);
+  const versions = [...st.versions.values()].sort((a, b) => a.n - b.n).map((v) => ({ n: v.n, at: v.at, turn: v.turn }));
+  return {
+    running: !!running, job: running ? { since: running.since, turn: running.turn, kind: running.kind } : null,
+    current: st.current, saved: st.saved ? st.saved.n : null, versions, log: st.log,
+    plan: st.current != null ? overlay(readVersion(root, id, st.current), checks) : null,
+    dry: st.dry, checks, errors: st.errors.map((e) => ({ text: e.text, at: e.at })),
+  };
+}
+/** What the setups GET carries for one report: { saved, at, charts, sections } of the accepted version, else null. */
+function savedOf(root, id) {
+  let st; try { st = stateOf(root, id); } catch { return null; }
+  if (!st.saved) return null;
+  const plan = readVersion(root, id, st.saved.n);
+  if (!plan) return null;
+  return { saved: st.saved.n, at: st.saved.at, charts: plan.charts.length, sections: plan.outline.length };
+}
+
+// ── brief.md ──────────────────────────────────────────────────────────────────────────────────────────────
+const yq = (s) => JSON.stringify(String(s == null ? '' : s));
+function writeBrief(root, id, setup, { now } = {}) {
+  const st = stateOf(root, id);
+  if (!st.saved) return refuse(409, 'no structure is saved yet');
+  const plan = readVersion(root, id, st.saved.n);
+  if (!plan) return refuse(409, `S${st.saved.n} is not on disk`);
+  const name = (setup && setup.name) || id;
+  const day = iso(now).slice(0, 10);
+  const L = ['---', 'type: Reference', `title: ${yq('Report structure: ' + name)}`, `timestamp: ${day}`, '---', '', `# Report structure: ${name}`, '',
+    `The saved structure of the ${name} report. Each cycle is drafted from it: the outline's sections in order, each chart worked out from its source by the logic below. It is a brief, not a template.`, '',
+    `- Saved version: S${st.saved.n} (structure/versions/S${st.saved.n}.json), saved ${st.saved.at.slice(0, 10)}`, '', '## What it answers', ''];
+  const pu = plan.purpose;
+  L.push(`- Readers: ${pu.readers || 'not said'}`, `- Decision: ${pu.decision || 'not said'}`, `- Scope: ${pu.scope || 'not said'}`, `- Cadence: ${pu.cadence || 'not said'}`);
+  if (pu.questions.length) { L.push('', 'Questions it answers:', ''); for (const q of pu.questions) L.push(`- ${q}`); }
+  const srcName = (sid) => (plan.sources.find((s) => s.id === sid) || { name: sid }).name;
+  for (const [h, g] of [['Sources from PMOS', 'pmos'], ['Sources outside PMOS', 'outside']]) {
+    L.push('', `## ${h}`, '');
+    const list = plan.sources.filter((s) => s.group === g);
+    if (!list.length) L.push('None.');
+    for (const s of list) L.push(`- ${s.name} (${s.kind}${s.via ? ', through ' + s.via : ''}${s.ref ? ', ' + s.ref : ''}): ${s.use || 'no use stated'}`);
+  }
+  L.push('', '## Charts', '');
+  if (!plan.charts.length) L.push('None.');
+  for (const c of plan.charts) {
+    L.push(`### ${c.name || c.id}${c.chart ? ` (chart ${c.chart})` : ''}`, '', `- Question: ${c.question || 'not said'}`, `- Source: ${srcName(c.source)}`, `- Read: ${c.from || 'not said'}`,
+      `- Worked out: ${c.how || 'not said'}`, `- Compared with: ${c.compare || 'not said'}`, `- Flagged when: ${c.flag || 'not said'}`, '');
+  }
+  L.push('## Outline', '');
+  plan.outline.forEach((o, i) => {
+    L.push(`${i + 1}. ${o.title}${o.fixed ? ' (in every report)' : ''}`);
+    if (o.charts.length) L.push(`   - Charts: ${o.charts.map((c) => (plan.charts.find((x) => x.id === c) || { name: c }).name || c).join(', ')}`);
+    if (o.notes) L.push(`   - PMOS notes: ${o.notes}`);
+    if (o.show) L.push(`   - Shown as: ${o.show}`);
+  });
+  L.push('');
+  writeAtomic(paths(root, id).brief, L.join('\n'));
+  return { ok: true, path: paths(root, id).briefRel };
+}
+
+module.exports = { EVENTS, KINDS, PMOS_KINDS, OUTSIDE_KINDS, STATES, FIXED, LIMITS, CHECK_STEPS, CHECK_STATES, CADENCE_RE, SLUG_RE, RUN_RE,
+  paths, append, readEvents, fold, stateOf, nextN, badText, validatePlan, validateSource, validateDry, validateCheck, cleanQuestions, cleanOptions, addSourceTo, removeFrom,
+  landVersion, readVersion, rewriteVersion, writeDry, readDry, writeCheck, readCheck, readChecks, writeBrief, structureAnswer, savedOf, overlay, defaultState, newRun };

package/workspace/lib/route-modules.js

@@ -49,7 +49,8 @@ const MODULES = Object.freeze([
   'routes-forecast',      // console3 B5: forecast, critical path, time machine and capacity (read-only)
   'routes-calendar-views', // console3 C2: Day/Week/Month/Quarter/Year cells, Gantt and the strategy lens (read-only)
   'routes-briefing',      // console3 C1: the day-part Briefing cards from the signal engine (read-only)
-  'routes-brief-page',    // console3 Briefing as the brief: Today agenda and Needs you (read-only; writes go through routes-pm-items)
+  'routes-brief-page',    // console3 Briefing as the brief: Today agenda, Needs you and Mentions (read-only; writes go through routes-pm-items)
+  'routes-mentions',      // console3 Briefing Mentions: the PM's read marks (page press only)
   'routes-phone-day',     // phone companion: the agent's finished drafts, the evening recap and tomorrow at a glance (read-only)
   'routes-report-facts',  // console3 D: GET /api/report-families/facts (read-only, real data only)
   'routes-records',       // console3 E1a: ideas, hypotheses, decisions, KR metrics, bets (GET list; page-press add/edit/reading)
@@ -74,6 +75,7 @@ const MODULES = Object.freeze([
   'routes-report-setups', // report-workspace: recurring reports, the Ask box, the finder, the report documents and their export (report-setups.jsonl)
   'routes-core-docs',     // core-documents: the core documents of each level, Draft it (a core-doc run), Issue it and Drop (core-docs.jsonl)
   'routes-report-design', // report-design-studio: the design studio (describe, samples, turns, versions, This is it), cycle renders and decisions, speaker notes and pins
+  'routes-report-structure', // report-structure: the structure step (turns, versions, Use this structure, sources and their checks, dry run) and the chart store (GET /api/charts)
   'routes-refresh',       // data-refresh-settings: Settings › Data refresh: what refreshes, when, the refresh log, Refresh now
 ]);
 const PM_DIR = path.join(__dirname, '..', 'public', 'pm');

package/workspace/lib/routes-brief-page.js

@@ -17,8 +17,15 @@
  *           evidence is { text, event_id } when the calendar holds a meeting with the person, else null: the page asks the PM to
  *           confirm it and never marks the item done itself.
  *           A decision row: { key, kind: 'decision', headline, tag, card }.
+ *   mentions  the items of today's morning brief (<runtime>/briefs/<date>.json) that say `mention: true`: someone named the PM in Slack, Jira,
+ *           Confluence or mail (initiative c3-brief-summary-mentions). Newest first: { id, source, who, where, text, at, reply, link, initiative,
+ *           in_needs, need_key, read }. text is the item's quote, else its ask, else its title. at is the time of the author's last message in the item's thread.
+ *           reply is the item's reply_needed. in_needs: a worth-asking item, which Needs you shows as its row need_key ("ask:<id>"). A mention whose ledger copy
+ *           (brief:<id>) is done or dropped is left out. read: the PM marked it read (<runtime>/mentions/read.jsonl). A field the item lacks is absent.
+ *           mentions is null when there is no brief for today.
  * Item fields read defensively (a missing field is absent): kind, defer, person, evidence, workPlacement(item, today) when lib/pm-items.js
- * has it. A deferred item ('Not yet') is left out until its defer date or time. Writes go through the existing pm-items routes. */
+ * has it. A deferred item ('Not yet') is left out until its defer date or time. Writes go through the existing pm-items routes; a mention's
+ * read mark goes through POST /api/mentions/read (routes-mentions.js). */
 const path = require('path');
 const pmItems = require('./pm-items.js');
 const { repoScript } = require('./repo-script.js');
@@ -129,13 +136,53 @@ function needsOf(items, events, cards, now, deps = {}) {
   return [...late, ...dueToday, ...offline, ...decisions];
 }
 
+const MENTION_ID = /^[0-9a-f]{12}$/;
+const httpsUrl = (v) => { const t = String(v || ''); try { return new URL(t).protocol === 'https:' && t.length <= 500 ? t : null; } catch { return null; } };
+
+/** The read marks: the last line for each id wins. */
+function readMarks(lines) {
+  const m = new Map();
+  for (const l of lines || []) if (l && MENTION_ID.test(String(l.id || '')) && typeof l.read === 'boolean') m.set(l.id, l.read);
+  return m;
+}
+
+/** The mentions of today's brief. itemLines: the PM's ledger (pm-items items.jsonl lines); reads: readMarks(). Pure. */
+function mentionsOf(brief, itemLines, reads, todayIso) {
+  if (!brief || brief.date !== todayIso) return null;
+  const folded = pmItems.fold(itemLines || []);
+  const done = new Set(folded.filter((i) => i.done).map((i) => i.id));
+  const live = new Set(folded.map((i) => i.id));
+  const dropped = new Set((itemLines || []).filter((l) => l && l.id && !live.has(l.id)).map((l) => l.id));
+  const seen = new Set(); const out = [];
+  for (const [list, ask] of [[brief.priorities, false], [brief.worth_asking, true]]) {
+    for (const x of Array.isArray(list) ? list : []) {
+      if (!x || !x.mention || !MENTION_ID.test(String(x.id || '')) || seen.has(x.id)) continue;
+      seen.add(x.id);
+      const key = 'brief:' + x.id;
+      if (done.has(key) || dropped.has(key)) continue;
+      const thread = Array.isArray(x.thread) ? x.thread : [];
+      const mine = thread.filter((m) => m && m.at && !Number.isNaN(Date.parse(m.at)) && (!x.who || m.who === x.who));
+      const row = { id: x.id, source: x.source, text: clip(x.quote || x.ask || x.title, 280), reply: x.reply_needed === true, in_needs: ask || !!x.worth_asking, read: reads && reads.get(x.id) === true };
+      if (x.who) row.who = clip(x.who, 120);
+      if (x.where) row.where = clip(x.where, 120);
+      row.at = mine.length ? new Date(mine[mine.length - 1].at).toISOString() : null;
+      const link = httpsUrl(x.link); if (link) row.link = link;
+      if (x.initiative_id) row.initiative = x.initiative_id;
+      if (row.in_needs) row.need_key = 'ask:' + x.id;   // the Needs you row it is (briefing-real.js askNeed)
+      out.push(row);
+    }
+  }
+  return out.sort((a, b) => (b.at ? Date.parse(b.at) : 0) - (a.at ? Date.parse(a.at) : 0));
+}
+
 /** The pure builder. deps: { events, items (folded), cards, notes } so a test needs no repository. */
 function build(query, deps = {}) {
   const q = query || {};
   let now = q.now ? new Date(q.now) : (deps.now ? new Date(deps.now) : new Date());
   if (Number.isNaN(now.getTime())) now = new Date();
   const events = deps.events || []; const items = deps.items || [];
-  const body = { ok: true, date: localDate(now), today: todayAgenda(events, items, now, deps.notes || {}), needs: needsOf(items, events, deps.cards || [], now, deps) };
+  const body = { ok: true, date: localDate(now), today: todayAgenda(events, items, now, deps.notes || {}), needs: needsOf(items, events, deps.cards || [], now, deps),
+    mentions: mentionsOf(deps.brief || null, deps.itemLines || [], readMarks(deps.readLines), localDate(now)) };
   if (deps.decisionsError) body.decisions_error = deps.decisionsError;
   return { status: 200, body };
 }
@@ -164,7 +211,8 @@ function firstName(cwd) {
 
 module.exports = {
   prefixes: ['/api/brief-page'],
-  build, todayAgenda, needsOf, evidenceFor, deferred, firstName, notesAdapter,
+  MENTION_ID,
+  build, todayAgenda, needsOf, evidenceFor, deferred, firstName, notesAdapter, mentionsOf, readMarks,
   handle: async (req, res, url, ctx) => {
     if (url.pathname !== '/api/brief-page') return false;
     if (req.method !== 'GET') { ctx.json(res, { ok: false, error: 'GET only' }, 405); return true; }
@@ -174,7 +222,10 @@ module.exports = {
     try {
       const dir = ctx.runtimeDir;
       const events = dir ? require('./calendar-events.js').readAll(dir, { now: now.getTime() }) : [];
-      const items = dir ? pmItems.fold(pmItems.readLines(path.join(dir, 'pm-items', 'items.jsonl'))) : [];
+      const itemLines = dir ? pmItems.readLines(path.join(dir, 'pm-items', 'items.jsonl')) : [];
+      const items = pmItems.fold(itemLines);
+      let brief = null; try { brief = dir ? JSON.parse(require('fs').readFileSync(path.join(dir, 'briefs', localDate(now) + '.json'), 'utf8')) : null; } catch { brief = null; }
+      const readLines = dir ? pmItems.readLines(path.join(dir, 'mentions', 'read.jsonl')) : [];
       // The decisions come from the signal engine, whose repository read is slow. The page already holds them (GET /api/briefing feeds its deck), so the
       // read is made only when the caller asks (?decisions=1); the items and the agenda never wait for it.
       let cards = []; let decisionsError = null;
@@ -185,7 +236,7 @@ module.exports = {
         const facts = await require('./facts-async.js').readFactsAsync(root, { today: iso });
         cards = require(repoScript('signals/index.js')).present(facts, { lens: 'Unblock', zoom: 'week', today: iso }).cards || [];
       } catch (e) { decisionsError = 'the decisions could not be read: ' + (e && e.message ? e.message : String(e)); }
-      const out = build({ now: now.toISOString() }, { events, items, cards, decisionsError, notes: dir ? notesAdapter(dir) : {} });
+      const out = build({ now: now.toISOString() }, { events, items, itemLines, brief, readLines, cards, decisionsError, notes: dir ? notesAdapter(dir) : {} });
       if (out.body && out.body.ok) out.body.me = firstName(path.resolve(__dirname, '..', '..'));
       ctx.json(res, out.body, out.status);
     } catch (e) {