create-pmos 0.204.0 → 0.206.0

package/workspace/extension/popup.js

@@ -0,0 +1,195 @@
+/* popup.js — the PMOS button's popup (popup.html): "Add this page to a report design".
+ * PMOS draws the popup: the page is one frame, ${address}/c3.html?capture=1&pop=1&…, which lists the reports and has the Add button. The extension never posts to PMOS
+ * itself, because every PMOS write needs a press on a PMOS page (a nonce and an Origin check). So when the frame asks (postMessage { pmosCapture: 'request' }), this
+ * page takes the open tab and posts it back to the frame ({ pmosCapture: 'data', … }), and the frame uploads it with its own press. Both ways, the message must
+ * come from the other window and from the PMOS origin; the extension posts to the PMOS origin only.
+ *   Google Slides and Google Docs  → the PDF, fetched here with the user's own Google cookies (host permission for https://docs.google.com/*)
+ *   any other page                 → pictures of the whole page, scrolled top to bottom: at most 8, JPEG, 650 ms apart (Chrome's capture rate limit), scroll put back after
+ * When nothing answers at the address, this page says so and offers Try again. Nothing else is fetched. */
+(function () {
+  'use strict';
+  var A = window.PMOS_ADDRESS;
+  var C = window.PMOS_CAPTURE;
+  var CHECK_MS = 4000;     // how long to wait for PMOS to answer
+  var READY_MS = 8000;     // how long to wait for the frame to say it is drawn
+  var SETTLE_MS = 300;     // after a scroll, before the picture
+  var msg = document.getElementById('msg');
+  var frame = null;
+  var frameOrigin = '';
+  var readyTimer = null;
+  var busy = false;
+  var current = null;      // { tab, kind, address }
+
+  function readAddress(done) {
+    var fallback = A.DEFAULT_ADDRESS;
+    try {
+      var o = {}; o[A.KEY] = fallback;
+      chrome.storage.sync.get(o, function (v) { done(A.normalizeAddress(v && v[A.KEY]) || fallback); });
+    } catch (e) { done(fallback); }
+  }
+  function getTab(done) {
+    try { chrome.tabs.query({ active: true, currentWindow: true }, function (t) { done((t && t[0]) || null); }); } catch (e) { done(null); }
+  }
+  /** Resolves when something answers at the address (an opaque no-cors reply is enough), rejects when nothing listens. */
+  function answers(addr) {
+    var ctl = typeof AbortController === 'function' ? new AbortController() : null;
+    var t = ctl ? setTimeout(function () { ctl.abort(); }, CHECK_MS) : null;
+    return fetch(addr + '/c3.html', { mode: 'no-cors', cache: 'no-store', signal: ctl ? ctl.signal : undefined })
+      .then(function (r) { if (t) clearTimeout(t); return r; }, function (e) { if (t) clearTimeout(t); throw e; });
+  }
+  var sleep = function (ms) { return new Promise(function (r) { setTimeout(r, ms); }); };
+
+  /* ── the popup's own states ── */
+  function head(host) {
+    var h = document.createElement('div'); h.className = 'head';
+    var b = document.createElement('b'); b.textContent = 'PMOS'; h.appendChild(b);
+    var s = document.createElement('span'); s.textContent = 'Add this page to a report design'; h.appendChild(s);
+    host.appendChild(h);
+  }
+  function show(text, withRetry, extra) {
+    if (frame) { frame.remove(); frame = null; }
+    clearTimeout(readyTimer);
+    msg.textContent = '';
+    msg.className = 'msg';
+    if (!msg.parentNode) document.body.appendChild(msg);
+    head(msg);
+    var p = document.createElement('p'); p.textContent = text; msg.appendChild(p);
+    if (extra) msg.appendChild(extra);
+    if (withRetry) {
+      var b = document.createElement('button'); b.type = 'button'; b.textContent = 'Try again'; b.setAttribute('data-act', 'retry');
+      b.addEventListener('click', function () { start(); });
+      msg.appendChild(b);
+    }
+  }
+  function showDown(addr) {
+    var a = document.createElement('a'); a.href = '#'; a.textContent = 'Set the address';
+    a.addEventListener('click', function (e) { e.preventDefault(); try { chrome.runtime.openOptionsPage(); } catch (x) { /* no options page */ } });
+    show('PMOS is not answering at ' + addr + '. Start PMOS, then try again.', true, a);
+  }
+
+  /* ── the frame ── */
+  function post(m) {
+    if (!frame || !frame.contentWindow || !C.validOutgoing(m)) return false;
+    frame.contentWindow.postMessage(m, frameOrigin);
+    return true;
+  }
+  function showFrame(tab, kind, addr, screens) {
+    var q = new URLSearchParams({ capture: '1', pop: '1', pkind: kind, ptitle: C.sampleName(tab.title, tab.url), purl: tab.url || '' });
+    if (screens) q.set('pscreens', String(screens));
+    frame = document.createElement('iframe');
+    frame.title = 'PMOS: add this page to a report design';
+    frame.src = addr + '/c3.html?' + q.toString();
+    frameOrigin = new URL(addr).origin;
+    if (msg.parentNode) msg.remove();
+    document.body.appendChild(frame);
+    // an older PMOS answers but has no capture page: it never says ready
+    readyTimer = setTimeout(function () { showDown(addr); }, READY_MS);
+  }
+
+  /* ── what is taken ── */
+  var toBase64 = function (buf) {
+    var bytes = new Uint8Array(buf); var s = '';
+    for (var i = 0; i < bytes.length; i += 0x8000) s += String.fromCharCode.apply(null, bytes.subarray(i, i + 0x8000));
+    return btoa(s);
+  };
+  var run = function (tabId, func, args) {
+    return chrome.scripting.executeScript({ target: { tabId: tabId }, func: func, args: args || [] }).then(function (r) { return r && r[0] ? r[0].result : undefined; });
+  };
+  var measure = function () { var d = document.documentElement; var b = document.body; return { h: Math.max(d ? d.scrollHeight : 0, b ? b.scrollHeight : 0), vh: window.innerHeight, y: window.scrollY }; };
+  var scrollTo = function (y) { window.scrollTo({ top: y, left: 0, behavior: 'instant' }); return window.scrollY; };
+
+  function takePdf(tab, kind) {
+    var url = C.exportUrl(tab.url);
+    post({ pmosCapture: 'progress', text: 'Getting the PDF from Google', step: 1, of: 3 });
+    return fetch(url, { credentials: 'include', cache: 'no-store', redirect: 'follow' }).then(function (r) {
+      if (!r.ok) throw new Error('Google did not give the PDF (' + r.status + '). Open the file in Chrome while signed in to Google, then try again.');
+      return r.arrayBuffer();
+    }, function () { throw new Error('Chrome could not reach Google to get the PDF. Check the connection, then try again.'); }).then(function (buf) {
+      var bytes = new Uint8Array(buf);
+      if (!(bytes[0] === 0x25 && bytes[1] === 0x50 && bytes[2] === 0x44 && bytes[3] === 0x46)) throw new Error('Google did not give a PDF. Sign in to Google in this Chrome, make sure you can open the file, then try again.');
+      if (bytes.length > C.MAX_BYTES) throw new Error('The PDF is over 20 MB. PMOS keeps a sample up to 20 MB. Add a smaller copy.');
+      post({ pmosCapture: 'progress', text: 'Reading the PDF', step: 2, of: 3 });
+      var pages = C.pdfPageCount(bytes);
+      return { pmosCapture: 'data', kind: 'pdf', name: C.sampleName(tab.title, tab.url), url: tab.url, pages: pages || undefined, data: toBase64(buf) };
+    });
+  }
+
+  function takePictures(tab) {
+    var tabId = tab.id; var windowId = tab.windowId;
+    var start = null; var pics = []; var bytes = 0; var last = 0;
+    return run(tabId, measure).then(function (m) {
+      if (!m || !m.vh) throw new Error('Chrome does not let PMOS read this page.');
+      start = m.y || 0;
+      var plan = C.scrollPlan(m.h, m.vh, C.MAX_PICTURES);
+      var n = plan.offsets.length;
+      var chain = Promise.resolve();
+      plan.offsets.forEach(function (y, i) {
+        chain = chain.then(function () {
+          post({ pmosCapture: 'progress', text: 'Picture ' + (i + 1) + ' of ' + n + (i ? ', scrolling down' : ''), step: i + 1, of: n + 1 });
+          return run(tabId, scrollTo, [y]);
+        }).then(function () {
+          var wait = Math.max(SETTLE_MS, C.MIN_GAP_MS - (Date.now() - last));
+          return sleep(wait);
+        }).then(function () {
+          last = Date.now();
+          return chrome.tabs.captureVisibleTab(windowId, { format: 'jpeg', quality: 80 });
+        }).then(function (dataUrl) {
+          var b64 = String(dataUrl || '').replace(/^data:[^,]*,/, '');
+          if (!b64) throw new Error('Chrome did not give a picture of the page.');
+          bytes += C.base64Bytes(b64);
+          if (bytes > C.MAX_BYTES) throw new Error('The pictures are over 20 MB. PMOS keeps a sample up to 20 MB. Open a shorter page, or add it as a PDF.');
+          pics.push(b64);
+        });
+      });
+      return chain;
+    }).then(function () {
+      return { pmosCapture: 'data', kind: 'pictures', name: C.sampleName(tab.title, tab.url), url: tab.url, pictures: pics };
+    }).then(function (out) { return restore(tabId, start).then(function () { return out; }); },
+      function (e) { return restore(tabId, start).then(function () { throw e; }); });
+  }
+  function restore(tabId, y) { return y == null ? Promise.resolve() : run(tabId, scrollTo, [y]).catch(function () { /* the page went away */ }); }
+
+  function capture() {
+    if (busy || !current) return;
+    busy = true;
+    var tab = current.tab;
+    var job = C.exportUrl(tab.url) ? takePdf(tab, current.kind) : takePictures(tab);
+    job.then(function (out) {
+      post({ pmosCapture: 'progress', text: 'Sending it to PMOS', step: out.kind === 'pdf' ? 3 : (out.pictures.length + 1), of: out.kind === 'pdf' ? 3 : (out.pictures.length + 1) });
+      if (!post(out)) throw new Error('The page could not be sent to PMOS.');
+    }).catch(function (e) {
+      post({ pmosCapture: 'error', error: String((e && e.message) || 'The page could not be taken.') });
+    }).then(function () { busy = false; });
+  }
+
+  window.addEventListener('message', function (e) {
+    var m = C.fromFrame(e, frame && frame.contentWindow, frameOrigin);
+    if (!m) return;
+    if (m.pmosCapture === 'ready') { clearTimeout(readyTimer); return; }
+    if (m.pmosCapture === 'resize') { if (frame) frame.style.height = m.height + 'px'; return; }
+    if (m.pmosCapture === 'close') { window.close(); return; }
+    if (m.pmosCapture === 'open') {
+      try { chrome.tabs.create({ url: frameOrigin + '/c3.html?studio=' + encodeURIComponent(m.report) }); } catch (x) { /* no tabs */ }
+      window.close();
+      return;
+    }
+    if (m.pmosCapture === 'request') capture();
+  });
+
+  function start() {
+    busy = false;
+    readAddress(function (addr) {
+      getTab(function (tab) {
+        var kind = tab ? C.classifyUrl(tab.url) : 'blocked';
+        if (!tab || kind === 'blocked') { show('Chrome does not let PMOS read this page. Open a web page, such as a Google Slides deck or any site, then press the PMOS button.', false); return; }
+        current = { tab: tab, kind: kind, address: addr };
+        var go = function (screens) {
+          answers(addr).then(function () { showFrame(tab, C.pageKind(tab.url), addr, screens); }, function () { showDown(addr); });
+        };
+        if (kind !== 'other') { go(0); return; }
+        run(tab.id, measure).then(function (m) { go(m && m.vh ? C.scrollPlan(m.h, m.vh, 1000).total : 0); }, function () { go(0); });
+      });
+    });
+  }
+  start();
+})();

package/workspace/guide/jira.md

@@ -163,6 +163,7 @@ The morning brief, the day check and requirement gathering use it to tie a Jira
 - `pmos jira sync <initiative> --from <file|-> [--query "<jql>"] [--dry-run]`
 - `pmos jira query --sprints`
 - `pmos jira sync --sprints --from <file|-> [--query "<jql>"] [--dry-run]`
+- `pmos jira summary [--from <file|->] [--dry-run]`
 - `pmos jira which <KEY>`
 
 Every command takes `--json` and `--root <dir>`.

package/workspace/guide/report-design.md

@@ -22,7 +22,7 @@ Use one of these two buttons:
 
 1. Select **Deck** or **Document** at the top of the studio.
 2. Write what the report is for and who reads it. For example: "This goes to the progress session every other Thursday. The decisions must stand out."
-3. Press **Add a sample** to give PMOS a report that people liked. You can upload a file, paste a link, or pick a report document that PMOS has. Each sample shows what PMOS took from it. PMOS reads a link from Google Slides, Docs or Sheets, or from Confluence, through your own connectors. It saves the words and the structure (slide titles, order, sections and tables), and it changes nothing in the file. It does not get the look. To match the look, also add the file as a PDF or a screenshot. For Google Slides, choose **File**, **Download**, **PDF document (.pdf)** in Slides, then add that file. If your connectors cannot read the link, the sample says so. Any other link is kept by its address, and PMOS cannot open it. PMOS sees the pages of a PDF or an image, so it can follow their look. From a .pptx or a .docx, PMOS gets only the words.
+3. Press **Add a sample** to give PMOS a report that people liked. You can upload a file, paste a link, add a page from Chrome (see below), or pick a report document that PMOS has. Each sample shows what PMOS took from it. PMOS reads a link from Google Slides, Docs or Sheets, or from Confluence, through your own connectors. It saves the words and the structure (slide titles, order, sections and tables), and it changes nothing in the file. It does not get the look. To match the look, also add the file as a PDF or a screenshot. For Google Slides, choose **File**, **Download**, **PDF document (.pdf)** in Slides, then add that file. If your connectors cannot read the link, the sample says so. Any other link is kept by its address, and PMOS cannot open it. PMOS sees the pages of a PDF or an image, so it can follow their look. From a .pptx or a .docx, PMOS gets only the words.
 4. Press **Make the next version**. PMOS makes a version from your words and this cycle's data. This takes a short time. You can leave the studio. The studio shows when the version is ready.
 5. Read the version in the preview. Write what to change and press **Make the next version** again. Each turn makes a new version: D1, D2, D3 and so on.
 
@@ -30,6 +30,20 @@ To set the width of the studio, use **Half**, **3/4** or **Whole** at the top ri
 
 If a turn fails, the studio shows why. Nothing changes. Try the turn again.
 
+
+### Add a page from Chrome
+
+You can add the page you are looking at in Chrome, on any website, as a sample. This needs the PMOS extension in Chrome. Run `pmos extension` in a terminal for the steps to load it.
+
+1. In Chrome, open the page, for example a Google Slides deck, a Google Doc or a Confluence page.
+2. Press the **PMOS** button in the Chrome toolbar. The popup says "Add this page to a report design".
+3. Choose the report in the **Report** list. It starts on the report whose design studio you opened last.
+4. Press **Add as a sample**. Keep the popup open while it saves. When it says "Added to" and the name of the report, press **Open the studio**.
+
+A Google Slides deck or a Google Doc comes to PMOS as a PDF, so PMOS can follow its look. The sample reads "From Chrome, PDF, 12 slides", or "pages" for a document. Chrome asks Google for the PDF with your own Google sign-in. Any other page comes as pictures of the whole page, scrolled top to bottom, at most 8 pictures. The sample reads "From Chrome, 3 page pictures". PMOS reads every picture, and follows its look as it does for a PDF. A sample is at most 20 MB. If the page is bigger, the popup says so: open a shorter page, or add a smaller copy.
+
+The sample shows in a design studio that is already open, in a few seconds. If the popup says "PMOS is not answering", start PMOS and press **Try again**. Nothing leaves your computer: the popup sends the page only to your own PMOS.
+
 ### Point at a part
 
 Keep **Point and say** on. Click a part of the preview and write what to change there. A numbered marker shows the spot. Your next turn sends the markers with your words.

package/workspace/lib/engine/boards.js

@@ -15,7 +15,7 @@
  *   filterRows(rows, query)                     → { total, offset, limit, rows, facets }
  *   health(rows)                                → 'ok' | 'warn' | 'bad'
  *   counts(rows, workflow)                      → { total, open, byCat, byStage, byStatus, risk, late }
- *   sprintsOf(snapshots, onBoard, whole?)       → { source, readAt, sprints }
+ *   sprintsOf(snapshots, onBoard, whole?, notes?) → { source, readAt, sprints } (notes: each sprint's goal and summary, sprint-goal-summary)
  *   INI_TEMPLATES · isBuildStage · templateBuilds · boardSettings(board)   the per-initiative workflows (console3-initiatives-parity)
  *   workflowOf(board, id, folded)               → the stages an initiative runs: its own (ini-workflow), else the board's
  *   applyIniWorkflow(board, wfNow, stage, template, stages, moveTo) → { ok, template, workflow, moved } | { ok:false, status, error }
@@ -582,7 +582,7 @@ function counts(rows, workflow) {
  * lists EVERY issue Jira holds in it, whoever it is assigned to; an issue no initiative of the board holds has initiative null
  * (jira-sprint-scope). Without it, a sprint lists only the board's own tickets.
  */
-function sprintsOf(snapshots, onBoard = () => true, whole = null) {
+function sprintsOf(snapshots, onBoard = () => true, whole = null, notes = null) {
   const byName = new Map();
   let readAt = null;
   let any = false;
@@ -625,6 +625,49 @@ function sprintsOf(snapshots, onBoard = () => true, whole = null) {
     for (const i of sp.issues) sp.counts[i.category]++;
   }
   if (widened && whole.fetchedAt && (!readAt || whole.fetchedAt < readAt)) readAt = whole.fetchedAt;   // the oldest read is the honest age
+  // The goal and summary the Jira status check wrote (sprint-goal-summary). A closed sprint is summarised once and not read again,
+  // so one the board's initiatives worked in is listed from its note even when none of the board's tickets is in it now.
+  const nl = notes && Array.isArray(notes.notes) ? notes.notes : [];
+  const same = (a, b) => ((a.id && b.id) ? String(a.id) === String(b.id) : String(a.name) === String(b.name));
+  if (any) {
+    const iniOf = new Map();
+    for (const s of snapshots || []) {
+      if (!s || !onBoard(s.initiative)) continue;
+      for (const t of s.tickets instanceof Map ? s.tickets.values() : Array.isArray(s.tickets) ? s.tickets : []) if (t && t.key) iniOf.set(t.key, s.initiative);
+    }
+    for (const n of nl) {
+      if (n.state !== 'closed' || byName.has(n.name)) continue;
+      if (!(n.themes || []).some((t) => t && t.initiative && onBoard(t.initiative))) continue;
+      const issues = wt.filter((t) => t && t.key && t.sprint && same(t.sprint, n)).map((t) => {
+        const category = ['todo', 'doing', 'done'].includes(t.category) ? t.category : 'todo';
+        return { key: t.key, summary: t.summary || '', status: t.status || '', category, initiative: iniOf.get(t.key) || null, flagged: !!t.flagged, reason: t.flagged && t.reason ? String(t.reason) : null };
+      });
+      const counts = { todo: 0, doing: 0, done: 0 };
+      for (const i of issues) counts[i.category]++;
+      byName.set(n.name, { name: n.name, state: 'closed', start: n.start || null, end: n.end || null, issues, counts });
+    }
+  }
+  const jiraGoal = (sp) => {
+    for (const t of wt) if (t && t.sprint && String(t.sprint.name) === sp.name && t.sprint.goal) return String(t.sprint.goal);
+    for (const s of snapshots || []) for (const t of s && s.tickets instanceof Map ? s.tickets.values() : s && Array.isArray(s.tickets) ? s.tickets : []) if (t && t.sprint && String(t.sprint.name) === sp.name && t.sprint.goal) return String(t.sprint.goal);
+    return null;
+  };
+  for (const sp of byName.values()) {
+    const n = nl.find((x) => x.name === sp.name);
+    const jg = jiraGoal(sp);
+    if (n) {
+      sp.goal = { from: n.goal.from, text: n.goal.text, jira: n.goal.from === 'jira' ? n.goal.text : n.goal.jira || null };
+      sp.summary = n.summary;
+      sp.themes = (n.themes || []).map((t) => ({ title: t.title, line: t.line || '', tickets: t.tickets || 0, done: t.done || 0, blocked: t.blocked || 0, people: t.people || '', initiative: t.initiative || null }));
+      sp.writtenAt = n.writtenAt || null;
+      sp.summarisedTickets = Number.isInteger(n.tickets) ? n.tickets : null;
+      sp.closed = sp.state === 'closed' && n.closed ? { ...n.closed } : null;
+      sp.frozen = sp.state === 'closed' && n.state === 'closed';
+    } else {
+      sp.goal = jg ? { from: 'jira', text: jg, jira: jg, unchecked: true } : null;
+      sp.summary = null; sp.themes = []; sp.writtenAt = null; sp.summarisedTickets = null; sp.closed = null; sp.frozen = false;
+    }
+  }
   const order = { active: 0, future: 1, closed: 2 };
   const sprints = [...byName.values()].sort((a, b) => ((order[a.state] ?? 3) - (order[b.state] ?? 3)) || a.name.localeCompare(b.name));
   for (const sp of sprints) sp.issues.sort((a, b) => a.key.localeCompare(b.key, undefined, { numeric: true }));

package/workspace/lib/extension-cli.js

@@ -1,5 +1,5 @@
 'use strict';
-/* extension-cli.js — `pmos extension`: where the Chrome extension for Google Meet is, and how to load it (initiative c3-meet-extension).
+/* extension-cli.js — `pmos extension`: where the PMOS Chrome extension is (the Meet panel and the button that adds a page to a report design), and how to load it (initiatives c3-meet-extension, report-design-studio).
  *
  *   pmos extension    print the absolute path of workspace/extension and the steps to load it in Chrome
  *
@@ -10,20 +10,22 @@ const path = require('path');
 
 const COMMANDS = { extension: [] };
 const FOLDER = path.resolve(__dirname, '..', 'extension');
-const USAGE = ['usage: pmos extension — the Chrome extension that shows the meeting companion over a Google Meet call'];
+const USAGE = ['usage: pmos extension — the Chrome extension: the meeting companion over a Google Meet call, and a button that adds a page to a report design'];
 
 /** The lines `pmos extension` prints for a folder. Pure. */
 function lines(folder, exists = true) {
   const out = [];
   if (!exists) { out.push(`✗ the extension folder is not here: ${folder}`, '  Reinstall the workspace with `pmos upgrade`.'); return out; }
-  out.push('PMOS for Google Meet (Chrome)', '', `  folder  ${folder}`, '',
+  out.push('PMOS for Chrome', '', `  folder  ${folder}`, '',
     'Load it in three steps:',
     '  1. In Chrome, open chrome://extensions',
     '  2. Turn on Developer mode (top right)',
     '  3. Press Load unpacked, then pick the folder above',
     '',
     'PMOS is looked for at http://localhost:7433. If pmos printed another port, open the extension\'s Options and set that address.',
-    'Then open a Google Meet call: the panel shows at the bottom right.');
+    'Then open a Google Meet call: the panel shows at the bottom right.',
+    'To add a page to a report design, open any page and press the PMOS button in the toolbar. Choose the report, then Add as a sample.',
+    'After an update, press the reload arrow on the extension\'s card in chrome://extensions.');
   return out;
 }
 

package/workspace/lib/jira-cli.js

@@ -12,6 +12,7 @@
  *   pmos jira sync <initiative> --from <file|-> [--query "<jql>"] [--dry-run]  a saved search → the status snapshot
  *   pmos jira query --sprints                                   the Jira search for every issue in the sprints the tickets are in
  *   pmos jira sync --sprints --from <file|-> [--query "<jql>"]  a saved whole-sprint search → the Sprints tab (jira-sprint-scope)
+ *   pmos jira summary [--from <file|->] [--dry-run]            the sprints to summarise, or save their goal and summary (sprint-goal-summary)
  *   pmos jira which <KEY>                                       the initiative a Jira key belongs to
  *   every command: [--json] [--root <dir>]
  *
@@ -27,9 +28,9 @@ const jiraTickets = require('./jira-tickets.js');
 const planItems = require('./plan-items.js');
 const guard = require('./pm-guard.js');
 
-const COMMANDS = { jira: ['draft', 'show', 'epic', 'approve', 'pending', 'record', 'query', 'sync', 'which'] };
+const COMMANDS = { jira: ['draft', 'show', 'epic', 'approve', 'pending', 'record', 'query', 'sync', 'summary', 'which'] };
 const USAGE = [
-  'usage: pmos jira draft|show|epic|approve|pending|record|query|sync|which — Jira tickets from the PRD, and their status',
+  'usage: pmos jira draft|show|epic|approve|pending|record|query|sync|summary|which — Jira tickets from the PRD, and their status',
   '  pmos jira draft <initiative> [--dry-run]           draft one ticket per PRD item, in the ticket template',
   '  pmos jira show <initiative>                        every ticket, what needs you, and its status in Jira',
   '  pmos jira epic <initiative> new|<KEY or link>      create a new epic at the first push, or use an existing one',
@@ -40,6 +41,8 @@ const USAGE = [
   '  pmos jira sync <initiative> --from <file|-> [--query "<jql>"] [--dry-run]   save the status read from Jira',
   '  pmos jira query --sprints                          the Jira search for every issue in those tickets\' sprints',
   '  pmos jira sync --sprints --from <file|-> [--query "<jql>"]   save every issue of the sprints, for the Sprints tab',
+  '  pmos jira summary                                  the sprints that need a goal and summary written',
+  '  pmos jira summary --from <file|-> [--dry-run]      save each sprint\'s goal, summary and themes (a closed sprint is kept once written)',
   '  pmos jira which <KEY>                              the initiative a Jira key belongs to',
   '  every command: [--json] [--root <dir>]',
   'This command never calls Jira. Your agent reads and writes Jira with your own connection.',
@@ -99,7 +102,7 @@ async function run(argv, { say = (s) => console.log(s), cwd = process.cwd(), isT
     if (flags.sprints && verb !== 'query' && verb !== 'sync') return fail('--sprints goes with query or sync', 2);
     if (verb === 'query' && flags.sprints) {
       const q = jiraStatus.sprintQuery(root);
-      return out(q, [q.linked ? q.query : 'no Jira reading has a sprint yet — run the initiatives\' searches first']);
+      return out(q, [q.linked ? q.query : q.kept.length ? 'every sprint is closed and summarised once — nothing to read' : 'no Jira reading has a sprint yet — run the initiatives\' searches first']);
     }
     if (verb === 'sync' && flags.sprints) {
       if (!flags.from) return need('--sprints --from <file|->');
@@ -113,6 +116,26 @@ async function run(argv, { say = (s) => console.log(s), cwd = process.cwd(), isT
       if (!r.dryRun) lines.push(`snapshot ${r.snapshot}`);
       return out(r, lines);
     }
+    if (verb === 'summary') {
+      if (!flags.from) {
+        const r = jiraStatus.sprintsToSummarise(root);
+        if (!r.read) return out(r, ['no whole-sprint read yet — run pmos jira query --sprints and sync --sprints first']);
+        const lines = r.sprints.map((s) => `${s.name}\t${s.state}\t${s.tickets} ${s.tickets === 1 ? 'issue' : 'issues'}\t${s.jiraGoal ? `goal in Jira: ${s.jiraGoal}` : 'no goal in Jira'}`);
+        if (!lines.length) lines.push('no sprint needs a summary');
+        for (const k of r.kept) lines.push(`${k}\tclosed\tkept, summarised once`);
+        return out(r, lines);
+      }
+      let raw;
+      try { raw = JSON.parse(readInput(flags.from, cwd, stdin)); }
+      catch (e) { return fail(`could not read ${flags.from} as JSON — ${String((e && e.message) || e).slice(0, 160)}`); }
+      const r = jiraStatus.saveSprintNotes(root, raw, { dryRun: !!flags['dry-run'], now });
+      if (!r.ok) return fail(r.error);
+      const lines = [`sprint summaries · saved ${r.saved.length}${r.kept.length ? ` · kept ${r.kept.length} closed, summarised once` : ''}${r.dryRun ? ' · dry run, nothing written' : ''}`];
+      for (const n of r.saved) lines.push(`  saved ${n}`);
+      for (const n of r.kept) lines.push(`  kept  ${n} (closed; its first summary stays)`);
+      if (!r.dryRun && r.saved.length) lines.push(`file ${r.file}`);
+      return out(r, lines);
+    }
     if (verb === 'query') {
       if (initiative) {
         const q = jiraStatus.queryFor(root, initiative);

package/workspace/lib/jira-status.js

@@ -17,9 +17,12 @@
  *                                         are in, whoever holds them (jira-sprint-scope); linked false when no reading has a sprint
  *   syncSprints(root, raw, opts)        → the whole-sprint snapshot, written to <state>/tracker/jira/_sprints.md
  *   readSprints(root)                   → { fetchedAt, query, tickets: Map<key, reading> } | null
+ *   sprintsToSummarise(root)            → { ok, sprints, kept } the sprints of the whole-sprint read that need a goal and summary
+ *   saveSprintNotes(root, raw, opts)    → each sprint's goal, summary and themes, written to <state>/tracker/jira/_sprint-notes.md
+ *   readSprintNotes(root)               → { writtenAt, notes: [note] } | null (sprint-goal-summary)
  *
  * A READING is { key, summary, status, category: todo|doing|done, sprint: { name, state: active|future|closed, id?, start?, end?,
- * completed? } | null, subtasks: { done, total }, fixVersion: [names], points: number | null, resolved: YYYY-MM-DD | null,
+ * completed?, goal? } | null, subtasks: { done, total }, fixVersion: [names], points: number | null, resolved: YYYY-MM-DD | null,
  * flagged, reason, url }. The sprint's dates, `points` and `resolved` feed the sprint burndown (lib/stage-tools.js); a
  * reading saved before they were carried has none of them, and the burndown says it cannot be drawn. A ticket the search did not return keeps its last reading, marked
  * stale. Titles and statuses only: never a description, a comment or a person.
@@ -100,6 +103,8 @@ function sprintOne(v) {
     const d = dayOf(from.map((f) => v[f]).find((x) => x != null));
     if (d) out[k] = d;
   }
+  const goal = clip(oneLine(v.goal), 300);   // Jira's sprint goal, often empty or broad (sprint-goal-summary)
+  if (goal) out.goal = goal;
   return out;
 }
 /** An ISO date or date-time → YYYY-MM-DD (the date as written, never shifted by a zone), else null. */
@@ -286,7 +291,8 @@ function sync(root, initiative, raw, { query, dryRun = false, now } = {}) {
 const SPRINTS_FILE = '_sprints';
 const jqlName = (n) => `"${String(n).replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
 function sprintQuery(root) {
-  const seen = new Map();
+  const frozen = frozenNotes(root);
+  const seen = new Map(); const kept = new Set();
   for (const q of linkedInitiatives(root).filter((x) => x.linked)) {
     const snap = readSnapshot(root, q.initiative);
     if (!snap) continue;
@@ -294,20 +300,27 @@ function sprintQuery(root) {
       const sp = t && t.sprint;
       if (!sp || !sp.name) continue;
       const k = sp.id || sp.name;
+      if (frozen.some((f) => sameSprint(f, sp))) { kept.add(sp.name); continue; }   // a closed sprint is read once (sprint-goal-summary)
       if (!seen.has(k)) seen.set(k, { name: sp.name, state: sp.state || null, ...(sp.id ? { id: sp.id } : {}) });
     }
   }
   const sprints = [...seen.values()].sort((a, b) => a.name.localeCompare(b.name, undefined, { numeric: true }));
-  if (!sprints.length) return { ok: true, linked: false, sprints, query: null };
-  return { ok: true, linked: true, sprints, query: `sprint in (${sprints.map((s) => s.id || jqlName(s.name)).join(', ')}) ORDER BY key` };
+  if (!sprints.length) return { ok: true, linked: false, sprints, kept: [...kept], query: null };
+  return { ok: true, linked: true, sprints, kept: [...kept], query: `sprint in (${sprints.map((s) => s.id || jqlName(s.name)).join(', ')}) ORDER BY key` };
 }
-/** Save a whole-sprint read. The read replaces the last one whole: an issue moved out of a sprint is gone from it. */
+/** Save a whole-sprint read. The read replaces the last one whole: an issue moved out of a sprint is gone from it. A closed
+ * sprint that has its summary is not searched again, so its issues are kept from the last read. */
 function syncSprints(root, raw, { query, dryRun = false, now } = {}) {
   const n = normalize(raw);
   if (n.error) return { ok: false, error: n.error };
   const kept = n.issues.filter((i) => i.sprint && i.sprint.name);
   const fetchedAt = nowIso(now);
   const prev = readSprints(root);
+  const frozen = frozenNotes(root);
+  if (prev && frozen.length) {
+    const got = new Set(kept.map((i) => i.key));
+    for (const t of prev.tickets.values()) if (!got.has(t.key) && t.sprint && frozen.some((f) => sameSprint(f, t.sprint))) kept.push(t);
+  }
   const bySprint = {};
   for (const i of kept) bySprint[i.sprint.name] = (bySprint[i.sprint.name] || 0) + 1;
   const result = { ok: true, read: kept.length, ignored: n.issues.length - kept.length, skipped: n.skipped, sprints: bySprint,
@@ -322,6 +335,122 @@ function syncSprints(root, raw, { query, dryRun = false, now } = {}) {
 }
 function readSprints(root) { return readSnapshot(root, SPRINTS_FILE); }
 
+// ── the goal and summary of each sprint (sprint-goal-summary) ─────────────────────────────────────────
+// The Jira status check writes them from the tickets it read: Jira's goal when it says what the sprint delivers, else a goal
+// written from the tickets, with why (none: Jira has none; broad: too broad; partial: leaves out part of the sprint). A closed
+// sprint's note is written once and kept; its sprint is not searched again.
+const NOTES_FILE = '_sprint-notes';
+const GOAL_FROM = ['jira', 'none', 'broad', 'partial'];
+const INI_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,80}$/;
+const sameSprint = (a, b) => !!a && !!b && ((a.id && b.id) ? String(a.id) === String(b.id) : String(a.name) === String(b.name));
+function readSprintNotes(root) {
+  let text;
+  try { text = fs.readFileSync(snapshotPath(root, NOTES_FILE), 'utf8'); } catch { return null; }
+  const m = /```json\n([\s\S]*?)\n```/.exec(text);
+  if (!m) return null;
+  let data;
+  try { data = JSON.parse(m[1]); } catch { return null; }
+  const notes = (Array.isArray(data.sprints) ? data.sprints : []).filter((x) => x && isStr(x.name) && x.goal && isStr(x.summary));
+  return { writtenAt: isStr(data.written_at) ? data.written_at : null, notes };
+}
+function frozenNotes(root) { const r = readSprintNotes(root); return r ? r.notes.filter((x) => x.state === 'closed') : []; }
+const count = (v, max) => (Number.isInteger(v) && v >= 0 && v <= (max == null ? 100000 : max) ? v : null);
+const text = (v, n) => clip(oneLine(v), n);
+/** One sprint's note from the agent → { note } | { error }. Nothing is guessed: a missing required field refuses the note. */
+function noteOne(x) {
+  if (!x || typeof x !== 'object') return { error: 'a sprint note is not an object' };
+  const name = text(x.name, 80);
+  if (!name) return { error: 'a sprint note has no name' };
+  const state = String(x.state || '').toLowerCase();
+  if (!SPRINT_STATES.includes(state)) return { error: `${name}: state is active, future or closed` };
+  const g = x.goal && typeof x.goal === 'object' ? x.goal : null;
+  if (!g || !GOAL_FROM.includes(g.from)) return { error: `${name}: goal.from is jira, none, broad or partial` };
+  const gt = text(g.text, 240);
+  if (!gt) return { error: `${name}: the goal has no text` };
+  const goal = { from: g.from, text: gt };
+  if (g.from === 'broad' || g.from === 'partial') {
+    const j = text(g.jira, 300);
+    if (!j) return { error: `${name}: a ${g.from} goal carries Jira's own goal in goal.jira` };
+    goal.jira = j;
+  }
+  const summary = text(x.summary, 900);
+  if (!summary) return { error: `${name}: the summary is empty` };
+  const themes = [];
+  for (const t of Array.isArray(x.themes) ? x.themes.slice(0, 8) : []) {
+    const title = t && text(t.title, 80);
+    if (!title) return { error: `${name}: a theme has no title` };
+    const tickets = count(t.tickets);
+    if (tickets == null) return { error: `${name}: theme "${title}" needs a ticket count` };
+    const ini = t.initiative == null || t.initiative === '' ? null : String(t.initiative).trim();
+    if (ini != null && !INI_RE.test(ini)) return { error: `${name}: theme "${title}" has a bad initiative id` };
+    themes.push({ title, line: text(t.line, 200), tickets, done: Math.min(count(t.done) || 0, tickets), blocked: Math.min(count(t.blocked) || 0, tickets), people: text(t.people, 80), initiative: ini });
+  }
+  const note = { name, state, goal, summary, themes };
+  const id = isStr(x.id) || Number.isInteger(x.id) ? String(x.id) : '';
+  if (/^\d{1,12}$/.test(id)) note.id = id;
+  if (state === 'closed' && x.closed && typeof x.closed === 'object') {
+    const c = x.closed;
+    note.closed = { done: count(c.done) || 0, total: count(c.total) || 0, carried: count(c.carried) || 0, carriedTo: text(c.carriedTo, 80) || null, points: text(c.points, 40) || null };
+  }
+  return { note };
+}
+/** The sprints of the whole-sprint read that need a note: every active and future one, and each closed one not yet noted. */
+function sprintsToSummarise(root) {
+  const whole = readSprints(root);
+  const frozen = frozenNotes(root);
+  const by = new Map();
+  for (const t of whole ? whole.tickets.values() : []) {
+    const sp = t.sprint;
+    if (!sp || !sp.name) continue;
+    if (!by.has(sp.name)) by.set(sp.name, { name: sp.name, ...(sp.id ? { id: sp.id } : {}), state: sp.state, tickets: 0, jiraGoal: null });
+    const o = by.get(sp.name);
+    o.tickets++;
+    if (!o.jiraGoal && sp.goal) o.jiraGoal = sp.goal;
+  }
+  const all = [...by.values()].sort((a, b) => a.name.localeCompare(b.name, undefined, { numeric: true }));
+  const isKept = (s) => frozen.some((f) => sameSprint(f, s));   // the note was written when Jira said closed
+  return { ok: true, read: !!whole, sprints: all.filter((s) => !isKept(s)), kept: all.filter(isKept).map((s) => s.name) };
+}
+/** Save the notes the agent wrote. A closed sprint already noted keeps its first note. A bad note refuses the whole file. */
+function saveSprintNotes(root, raw, { dryRun = false, now } = {}) {
+  const list = Array.isArray(raw) ? raw : raw && Array.isArray(raw.sprints) ? raw.sprints : null;
+  if (!list) return { ok: false, error: 'the file holds no "sprints": [...] list' };
+  const got = [];
+  for (const x of list) { const r = noteOne(x); if (r.error) return { ok: false, error: r.error }; got.push(r.note); }
+  const prev = readSprintNotes(root);
+  const notes = prev ? prev.notes.slice() : [];
+  const whole = readSprints(root);
+  const wt = whole ? [...whole.tickets.values()] : [];
+  const writtenAt = nowIso(now);
+  const saved = []; const kept = [];
+  for (const n of got) {
+    const i = notes.findIndex((o) => sameSprint(o, n));
+    if (i >= 0 && notes[i].state === 'closed') { kept.push(n.name); continue; }
+    const mine = wt.filter((t) => t.sprint && sameSprint(t.sprint, n));
+    const sp = mine.length ? mine[0].sprint : {};
+    const out = { ...n, writtenAt, tickets: mine.length, ...(sp.start ? { start: sp.start } : {}), ...(sp.end ? { end: sp.end } : {}), ...(sp.completed ? { completed: sp.completed } : {}) };
+    if (!out.id && sp.id) out.id = sp.id;
+    if (i >= 0) notes[i] = out; else notes.push(out);
+    saved.push(n.name);
+  }
+  const result = { ok: true, saved, kept, file: snapshotRel(root, NOTES_FILE), dryRun: !!dryRun };
+  if (dryRun || !saved.length) return result;
+  const file = snapshotPath(root, NOTES_FILE);
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const rows = notes.map((o) => `| ${cell(o.name)} | ${cell(o.state)} | ${cell(o.goal.text)} | ${o.goal.from === 'jira' ? 'Jira' : 'written from the tickets'} | ${cell(o.writtenAt)} |`);
+  const body = [
+    '---', 'type: Reference', 'title: "Jira sprints: goal and summary"', `timestamp: ${writtenAt}`, '---', '',
+    '# Jira sprints: goal and summary', '',
+    'Written by the Jira status check from the tickets it read, read-only. The Sprints tab of a board shows it. A closed sprint is written once and kept. Written by `pmos jira summary`; do not edit by hand.', '',
+    '| Sprint | State | Goal | Goal from | Written |', '|---|---|---|---|---|', ...rows, '',
+    '```json', JSON.stringify({ written_at: writtenAt, sprints: notes }, null, 0), '```', '',
+  ].join('\n');
+  const tmp = `${file}.${process.pid}.tmp`;
+  fs.writeFileSync(tmp, body);
+  fs.renameSync(tmp, file);
+  return { ...result, writtenAt };
+}
+
 // ── J13 · which initiative ─────────────────────────────────────────────────────────────────────────
 function which(root, key) {
   const k = String(key || '').trim().toUpperCase();
@@ -335,4 +464,5 @@ function which(root, key) {
   return { ok: true, key: k, initiatives: hits };
 }
 
-module.exports = { queryFor, linkedInitiatives, normalize, sync, readSnapshot, which, sprintLabel, snapshotPath, snapshotRel, sprintQuery, syncSprints, readSprints, SPRINTS_FILE };
+module.exports = { queryFor, linkedInitiatives, normalize, sync, readSnapshot, which, sprintLabel, snapshotPath, snapshotRel, sprintQuery, syncSprints, readSprints, SPRINTS_FILE,
+  sprintsToSummarise, saveSprintNotes, readSprintNotes, sameSprint, NOTES_FILE };