create-pmos 0.142.0 → 0.144.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-pmos",
-  "version": "0.142.0",
+  "version": "0.144.0",
   "description": "Scaffold the PMOS portable kit — run the PMOS product-management workflow (initiative → lane-fit spec → contract → build → three gates, with work-type lanes for features, research, maintenance, incidents, and content) entirely inside your own repo, with all state as git-versioned files. Includes `workflow-sweep`, which audits the state every board derives from and separates real defects from work you simply have not done. `create-pmos workspace` also installs + launches the local Terminal Workspace GUI. No database, no network, no telemetry.",
   "license": "MIT",
   "bin": {

package/payload/KIT-VERSION

@@ -1,3 +1,3 @@
-kernel-source: pmos@69e497b
+kernel-source: pmos@9f8623c
 assembled: 2026-10-12
 mode: vendor

package/payload/planning/evals/eval-calibration.md

@@ -2,7 +2,7 @@
 type: Reference
 title: "Eval calibration log"
 description: "Append-only record of every PM override of an evaluator verdict."
-generated: {by: process:create-pmos, at: "2026-10-12T01:34:35Z"}
+generated: {by: process:create-pmos, at: "2026-10-12T01:54:19Z"}
 status: stable
 ---
 

package/payload/planning/okrs/health-budgets.md

@@ -2,7 +2,7 @@
 type: Reference
 title: "Health budgets"
 description: "Closed registry of health-budget anchors (D59), edited only by the PM."
-generated: {by: process:create-pmos, at: "2026-10-12T01:34:35Z"}
+generated: {by: process:create-pmos, at: "2026-10-12T01:54:19Z"}
 status: stable
 ---
 

package/payload/state/discoveries.md

@@ -2,7 +2,7 @@
 type: Reference
 title: "Discoveries and friction log"
 description: "Append-only record of what runs discovered and where the process rubbed."
-generated: {by: process:create-pmos, at: "2026-10-12T01:34:35Z"}
+generated: {by: process:create-pmos, at: "2026-10-12T01:54:19Z"}
 status: stable
 ---
 

package/workspace/c3-initiatives-test.js

@@ -61,12 +61,12 @@ const { harness } = require('./c3-ini-harness');
   ok('S1 the settings sheet offers no Build template while Build and deliver is off', await st(() => document.querySelector('[data-ini-offer="fix"]').disabled && document.querySelector('[data-ini-offer="product"]').disabled));
   await page.click('[data-ini="build"]');
   await until(() => st(() => !!document.querySelector('[data-ini="jira-key"]')));
-  await page.fill('[data-ini="jira-key"]', 'off');
+  await page.fill('[data-ini="jira-key"]', 'off, mov');
   ok('S2 turning it on offers the Build templates and asks for the Jira key', await st(() => !document.querySelector('[data-ini-offer="fix"]').disabled && document.querySelector('[data-ini-offer="fix"]').checked));
   await page.click('[data-ini="settings-save"]');
   await until(() => store(() => window.__c3boards.boards.find((b) => b.id === 'office').build === true));
-  const off = await store(() => { const b = window.__c3boards.boards.find((x) => x.id === 'office'); return { build: b.build, jira: b.jira, offer: b.offer }; });
-  ok('S3 Save posts buildDeliver: Office move mirrors Jira OFF and offers the Build templates', off.build === true && off.jira === 'OFF' && off.offer.includes('fix'), JSON.stringify(off));
+  const off = await store(() => { const b = window.__c3boards.boards.find((x) => x.id === 'office'); return { build: b.build, jira: b.jira, projects: (b.jiraProjects || []).join(), offer: b.offer }; });
+  ok('S3 Save posts buildDeliver: Office move mirrors Jira OFF and MOV (two Jira projects) and offers the Build templates', off.build === true && off.jira === 'OFF' && off.projects === 'OFF,MOV' && off.offer.includes('fix'), JSON.stringify(off));
   const s4 = await until(async () => { const t = await toast(); return /Build and deliver on, mirroring Jira OFF/.test(t) && t; });
   ok('S4 a toast says what changed', !!s4, await toast());
   await until(() => st(() => !!document.querySelector('[data-ini-tab="sprints"]')));
@@ -144,6 +144,19 @@ const { harness } = require('./c3-ini-harness');
   ok('W4 the initiative now runs Research only and moved to Plan; other initiatives keep theirs', r07.stage === 'Plan' && r07.wf === 'Discover,Plan,Evaluate'
     && await store(() => !window.__c3boards.rows.find((r) => r.id === 'IDPF-12').template), JSON.stringify(r07));
 
+  /* ── Jira epics of an initiative (jira-epic-items) ── */
+  await page.click('[data-ini="jira-epics"]');
+  await until(() => st(() => !!document.querySelector('[data-ini="epics-input"]')));
+  await page.fill('[data-ini="epics-input"]', 'IDPF-900, XX-1');
+  await page.click('[data-ini="epics-save"]');
+  const epErr = await until(() => st(() => { const e = document.querySelector('[data-ini="epics-form"] [data-ini="error"]'); return e && e.textContent; }));
+  ok('E1 an epic outside the board\'s Jira projects is refused, and the sheet says why', /XX-1 is not in a Jira project of IDPF/.test(epErr || ''), epErr);
+  await page.fill('[data-ini="epics-input"]', 'idpf-900, idpf-901');
+  await page.click('[data-ini="epics-save"]');
+  await until(() => store(() => (window.__c3boards.rows.find((r) => r.id === 'IDPF-07').epics || []).length === 2));
+  const epChip = await until(() => st(() => { const c = document.querySelector('[data-ini="jira-epics"]'); return c && /Jira epics IDPF-900, IDPF-901/.test(c.textContent) && c.textContent; }));
+  ok('E2 the epics are saved upper-cased, and the initiative header names them', !!epChip, epChip);
+
   /* ── phone width ── */
   await page.setViewportSize({ width: 400, height: 860 });
   for (const loc of ['', 'board:idpf:summary', 'ini:idpf:IDPF-12:overview']) {

package/workspace/guide/console-calendar.md

@@ -1,14 +1,30 @@
 ---
 type: Guide
 title: "Guide: the Calendar tab of the console page"
-description: "The Calendar tab of the console page (/c3.html): the five zooms, the layer chips, the markers, the context of a meeting, free time, the tidy-up suggestions and the empty states."
-timestamp: 2026-10-11
+description: "The Calendar tab of the console page (/c3.html): Calendar and Notes, the five zooms, the layer chips, the markers, the context of a meeting, free time, the tidy-up suggestions and the empty states."
+timestamp: 2026-10-12
 ---
 
 # Guide: the Calendar tab of the console page
 
 The Calendar tab of the console page (`/c3.html`) shows time. It shows what happens and what falls due, by date. At the top it shows a short deck of headline cards about your calendar, for example a conflict or a meeting with no time to prepare. The deck shows nothing when PMOS has no card about your calendar. The tab shows no task list and no strategy panel. Your due items live in Work. The strategy and progress panels live in Reports and Initiatives.
 
+## Calendar and Notes
+
+The switch at the start of the bar has two parts. **Calendar** shows the grid. **Notes** shows your notes.
+
+In **Notes**, the list is at the left. The notes are in groups, one for each initiative. **No initiative** is the last group. The number shows how many notes the list shows. Type in **Search notes** to keep only the notes whose title, initiative or summary has the words. A row shows when the note was made and its length. A row also shows **recording** or **paused** while the note is held, **no meeting** when the note has no meeting, and a warning mark when a statement differs from a file.
+
+Press a row to open the note at the right. The note has three stages. Press **Before**, **During** or **After** to change the stage.
+
+- **Before** shows what the note kept about its meeting: the agenda, what the meeting is for, what to do to be ready, what to read first and the people. A tick shows an agenda item that was heard in the transcript. A note with no meeting says so, and has **Link to a meeting** and **Link to an initiative**.
+- **During** shows the live notes while the note is recorded or paused. At other times it shows the transcript.
+- **After** shows the overview, the decisions with why, the next steps with owner and due date, the open questions, the statements that differ from a file and the highlights. The transcript is folded at the bottom. When the final notes are written, click a text to correct it. Leave the text to save it. Press `Esc` to cancel. **Make task** adds a next step to the note's initiative.
+
+A note that is recorded now opens on **During**. Other notes open on **After**. **Show in the calendar** goes back to the grid, on the day of the meeting, with the meeting selected. The copy button puts the note on the clipboard as Markdown.
+
+In **Notes**, the zoom, the arrows and the calendar keys do nothing.
+
 ## Zoom and move
 
 Use **Day**, **Week**, **Month**, **Quarter** or **Year** to change the zoom. Use the arrows to go to the previous or the next period. Press **Today** to come back to today.
@@ -53,6 +69,8 @@ Press a meeting to show its context in the side column. Under the title, a row s
 - For a past meeting, **What came out of it** lists the decisions and actions of its note. **What moved after it** lists the items that changed within 48 hours and refer to the meeting or its initiative.
 - For a coming meeting, **Prepared** lists what is ready, and **To prepare** lists what is still open.
 
+When the meeting has a note, the detail has **Open the note**. It opens the note in **Notes**.
+
 When PMOS holds nothing for a meeting, the detail says so. It does not guess.
 
 ## Free time

package/workspace/guide/initiative-boards.md

@@ -14,7 +14,7 @@ The Initiatives tab of the console page (`/c3.html`) has these levels: **Portfol
 The Portfolio shows one row per board. A board is a product folder, for example IDPF. Each row shows:
 
 - the board name and its health: On track, Needs attention or Off track
-- the owner, and **Build and deliver** with the Jira project key, or "PMOS tasks only"
+- the owner, and **Build and deliver** with the Jira project keys, or "PMOS tasks only"
 - the initiatives per category: Discover, Plan, Do and Learn
 - the next release
 
@@ -39,7 +39,7 @@ The tabs are **Summary**, **Initiatives**, **Triage**, **Backlog**, **Board**, *
 
 Press the gear in the board header to open the board settings.
 
-- **Build and deliver**: turn it on to mirror a Jira project. Type the Jira project key. With it off, every item is a PMOS task and the Build workflows are not available.
+- **Build and deliver**: turn it on to mirror Jira. Type one or more Jira project keys, separated by commas, for example `IDPF, LB`. A board can map several Jira projects. With it off, every item is a PMOS task and the Build workflows are not available.
 - **Workflows this board offers**: the templates that a new initiative on this board can use.
 - **Default for new initiatives and accepted asks**: the template that a new initiative or an accepted ask starts on.
 

package/workspace/guide/jira.md

@@ -2,7 +2,7 @@
 type: Guide
 title: "Jira: tickets drafted from the PRD, and their status"
 description: "How to draft Jira tickets from a PRD in your ticket template, push the ones that are ready, and see their status, sprint and progress on the initiative's Jira tickets tab."
-timestamp: 2026-10-11
+timestamp: 2026-10-12
 ---
 
 # Jira: tickets drafted from the PRD, and their status
@@ -110,6 +110,20 @@ pmos jira query [<initiative>]
 pmos jira sync <initiative> --from <file|-> [--query "<jql>"] [--dry-run]
 ```
 
+## Link an initiative to its Jira epics
+
+Your team may already plan in Jira, with an epic for each piece of work. Then link the initiative to its epics. You do not have to draft or push tickets.
+
+1. Open the initiative. On a board with **Build and deliver** on, press **Link Jira epics** in the initiative header.
+2. Type the epic keys, separated by commas, for example `IDPF-2685, LB-120`. Each epic must be in one of the board's Jira projects.
+3. Press **Save epics**.
+
+The **Jira status check** then reads each epic and the issues under it. The initiative's **Jira items**, **Breakdown** and **Timeline** show them, and the board's **Backlog**, **Board** and **Timeline** too. They are read-only: change them in Jira.
+
+An initiative record that names an epic in its frontmatter (`jira: IDPF-2685`) is linked to it until you save epics on the page. Save an empty list to unlink.
+
+An initiative whose tickets PMOS pushed keeps the tickets it pushed. The epic link is for initiatives with no pushed ticket.
+
 ## When the PRD changes
 
 Each time the tab opens, PMOS compares every ticket with its item in the PRD:

package/workspace/guide/notes.md

@@ -2,7 +2,7 @@
 type: Guide
 title: "Guide: notes"
 description: "How to take notes in a meeting: one note top to bottom, typed notes as timed lines, key points written each minute and labelled by Jev, delete a note; final notes written after Stop from the whole recording, with speakers and a quote for each item, decisions with their why and who, next steps with an open question, a discussion paragraph, and Wispr Flow's notes merged in and fetched by hand when the fetch fails; listen to your microphone and the meeting on this machine, see decisions, actions and questions caught as they are said, check them against the repository for conflicts, capture highlights during the meeting, create tasks from next steps, correct and tag lines, see what changed in your notes, replay the meeting, see screenshots of the shared screen beside the transcript, link a note to its meeting and its initiative, and get a summary."
-timestamp: 2026-10-11
+timestamp: 2026-10-12
 ---
 
 # Guide: notes
@@ -22,7 +22,7 @@ Starting a note, from the Record control or from **Take notes** on a calendar ev
 
 ### The Record control in the console
 
-The console (the page at `/c3.html`) has the same Record control in its top bar, beside the Sessions button. It is always there, also when nothing is recording. **Record** (the microphone) starts an untitled note and listens at once. The arrow lists the meetings of today that have not started. Press one to start a note linked to that calendar event. While a meeting records, the red group shows its name and clock, **Highlight**, **Pause** and **Stop**. While it is paused, the group shows **Resume** and **Stop**. **Stop** asks first and offers **Pause instead**. A red dot shows on the Calendar tab while a meeting is held. The console has no Notes page, so the name in the red group opens the note in the main app.
+The console (the page at `/c3.html`) has the same Record control in its top bar, beside the Sessions button. It is always there, also when nothing is recording. **Record** (the microphone) starts an untitled note and listens at once. The arrow lists the meetings of today that have not started. Press one to start a note linked to that calendar event. While a meeting records, the red group shows its name and clock, **Highlight**, **Pause** and **Stop**. While it is paused, the group shows **Resume** and **Stop**. **Stop** asks first and offers **Pause instead**. A red dot shows on the Calendar tab while a meeting is held. Press the name in the red group to open the note on the console's Calendar tab, in **Notes**, on the **During** stage. See [the Calendar tab of the console page](console-calendar.md).
 
 When Whisper or Qwen3-ASR transcribes the meeting, the red group also names the engine and the language, for example **Whisper · English**. Check it when lines come out in the wrong language: the language is set in the Notes settings.
 

package/workspace/lib/engine/boards.js

@@ -83,6 +83,13 @@ const templateBuilds = (k) => !!INI_TEMPLATES[k] && INI_TEMPLATES[k].stages.some
 /** A board's Build and deliver settings, with the defaults of a board that never set them: buildDeliver is true when the
  * ledger line does not carry it (the stage-records thread reads the same field the same way), every template the board may run is offered, and new initiatives start with
  * the board's own template. */
+const JIRA_KEY_RE = /^[A-Za-z][A-Za-z0-9_]*-\d+$/;
+const JIRA_PROJECT_RE = /^[A-Za-z][A-Za-z0-9_]{0,19}$/;
+/** The Jira projects a board mirrors: the ledger's `jira` (one key, or a list of keys), else the keys in its tracker label. */
+function jiraProjectsOf(b) {
+  const raw = Array.isArray(b.jira) ? b.jira : typeof b.jira === 'string' && b.jira ? [b.jira] : String((/^Jira · (.+)$/.exec(b.tracker || '') || [])[1] || '').split(/[,\s]+/);
+  return [...new Set(raw.filter((k) => typeof k === 'string' && JIRA_PROJECT_RE.test(k.trim())).map((k) => k.trim().toUpperCase()))];
+}
 function boardSettings(board) {
   const b = board || {};
   const build = typeof b.buildDeliver === 'boolean' ? b.buildDeliver : true;
@@ -92,8 +99,8 @@ function boardSettings(board) {
   const tpl = INI_TEMPLATES[b.template] ? b.template : 'product';
   let defTpl = typeof b.defTpl === 'string' && offer.includes(b.defTpl) ? b.defTpl : (offer.includes(tpl) ? tpl : offer[0]);
   if (!defTpl) defTpl = 'simple';
-  const jira = build ? (typeof b.jira === 'string' && b.jira ? b.jira : (/^Jira · (.+)$/.exec(b.tracker || '') || [])[1] || null) : null;
-  return { build, jira, offer, defTpl };
+  const projects = build ? jiraProjectsOf(b) : [];
+  return { build, jira: projects[0] || null, jiraProjects: projects, offer, defTpl };
 }
 
 /* The PMOS-self board: the nine stage names of scripts/nine-stages.js, read-only, each in its category. */
@@ -139,7 +146,7 @@ const TOOLS = Object.freeze({
 
 const STATUSES = Object.freeze(['on track', 'at risk', 'late', 'done']);
 const VIEWS = Object.freeze(['now', 'mine', 'risk', 'noowner', 'all']);
-const KINDS = new Set(['board', 'workflow', 'move', 'assign', 'ask', 'ask-accept', 'ask-decline', 'ask-more', 'ini-workflow', 'task', 'task-update']);
+const KINDS = new Set(['board', 'workflow', 'move', 'assign', 'ask', 'ask-accept', 'ask-decline', 'ask-more', 'ini-workflow', 'task', 'task-update', 'ini-epics']);
 const TASK_STATES = Object.freeze(['To do', 'In progress', 'In review', 'Done']);
 
 const copyStages = (stages) => stages.map((s) => ({ name: s.name, cat: s.cat, hint: s.hint || '' }));
@@ -166,6 +173,7 @@ function fold(events) {
   const stages = new Map();        // key(board, id) → stage name (the last move)
   const iniWorkflows = new Map();  // key(board, id) → { template, stages } (the initiative's own workflow)
   const tasks = new Map();         // task id → { id, board, initiative, title, epic, owner, state, start, due, at, by, history }
+  const epics = new Map();         // initiative id → the Jira epic keys the PM linked to it (the last ini-epics line wins)
   const list = [];
   for (let e of Array.isArray(events) ? events : []) {
     if (typeof e === 'string') { try { e = JSON.parse(e); } catch { continue; } }
@@ -232,13 +240,15 @@ function fold(events) {
       if (typeof e.start === 'string') t.start = e.start;
       if (typeof e.due === 'string') t.due = e.due;
       t.history.push({ at: e.at || null, by: e.by || null, state: e.state || null, start: e.start || null, due: e.due || null, why: e.why || '' });
+    } else if (e.kind === 'ini-epics' && typeof e.id === 'string' && Array.isArray(e.epics)) {
+      epics.set(e.id, e.epics.filter((k) => typeof k === 'string' && JIRA_KEY_RE.test(k)).map((k) => k.toUpperCase()));
     } else if (e.kind === 'ask-decline' && typeof e.ask === 'string' && asks.has(e.ask)) {
       const a = asks.get(e.ask);
       if (a.state !== 'open') continue;
       Object.assign(a, { state: 'declined', why: e.why || '', closedAt: e.at || null });
     }
   }
-  return { boards, moves, assigns, asks, stages, iniWorkflows, tasks, events: list };
+  return { boards, moves, assigns, asks, stages, iniWorkflows, tasks, epics, events: list };
 }
 
 /** The stages an initiative runs on a board: its own workflow when one is recorded, else the board's. */
@@ -537,6 +547,6 @@ module.exports = {
   CATEGORIES, WORKFLOW_TEMPLATES, TOOLS, SELF_LADDER, READING_CAT, STATUSES, VIEWS, SORTS,
   templateWorkflow, isTemplateEdited, fold, readingOf, deriveStage, stageOf, catOf, moveWarnings, cardWarnings,
   applyWorkflowEdit, filterRows, health, counts, sprintsOf, key,
-  INI_TEMPLATES, TASK_STATES, isBuildStage, templateBuilds, boardSettings, workflowOf, templateOf, applyIniWorkflow, taskOf, shiftDay,
+  INI_TEMPLATES, TASK_STATES, isBuildStage, templateBuilds, boardSettings, jiraProjectsOf, JIRA_KEY_RE, JIRA_PROJECT_RE, workflowOf, templateOf, applyIniWorkflow, taskOf, shiftDay,
   ITEM_PROGRESS, itemStatus, taskItem, rollupItems,
 };

package/workspace/lib/jira-status.js

@@ -6,7 +6,8 @@
  * This module reads that file and writes a snapshot the initiative's Jira tickets tab shows. It writes nothing else:
  * no plan item, no record, no ledger line (D88: the Breakdown is the handoff checklist, not a copy of Jira).
  *
- *   queryFor(root, initiative)          → { linked, query }     the JQL for the tickets this initiative pushed
+ *   queryFor(root, initiative)          → { linked, mode, query } the JQL for the tickets this initiative pushed, or, when it
+ *                                         pushed none, for its Jira epics and their children (mode 'epic', jira-epic-items)
  *   linkedInitiatives(root)             → [{ initiative, query }]
  *   normalize(raw)                      → { issues, skipped } | { error }
  *   sync(root, initiative, raw, opts)   → the snapshot, written to <state>/tracker/jira/<initiative>.md
@@ -35,11 +36,15 @@ const nowIso = (now) => new Date(now == null ? Date.now() : now).toISOString().r
 function queryFor(root, initiative) {
   if (!jiraTickets.recordFm(root, initiative)) return { ok: false, error: `no initiative ${initiative} in this repository` };
   const keys = [...jiraTickets.pushedTickets(root, initiative).tickets.keys()];
-  if (!keys.length) return { ok: true, initiative, linked: false, keys: [], query: null };
-  return { ok: true, initiative, linked: true, keys, query: `key in (${keys.join(', ')}) ORDER BY key` };
+  if (keys.length) return { ok: true, initiative, linked: true, mode: 'pushed', keys, query: `key in (${keys.join(', ')}) ORDER BY key` };
+  // EPIC MODE (jira-epic-items): no ticket pushed, but the initiative has Jira epics. Read each epic and its children.
+  const epics = jiraTickets.epicKeysOf(root, initiative);
+  if (epics.length) return { ok: true, initiative, linked: true, mode: 'epic', keys: epics, epics, query: `key in (${epics.join(', ')}) OR parent in (${epics.join(', ')}) ORDER BY key` };
+  return { ok: true, initiative, linked: false, keys: [], query: null };
 }
 function linkedInitiatives(root) {
-  return jiraTickets.draftedInitiatives(root).map((id) => queryFor(root, id)).filter((q) => q.ok);
+  const ids = [...new Set([...jiraTickets.draftedInitiatives(root), ...jiraTickets.epicInitiatives(root)])].sort();
+  return ids.map((id) => queryFor(root, id)).filter((q) => q.ok);
 }
 
 // ── reading a saved search result ──────────────────────────────────────────────────────────────────
@@ -147,6 +152,15 @@ function urlOf(x, key) {
   return `${u.origin}/browse/${key}`;
 }
 /** One issue of either shape → a reading, or null when it has no key or no summary. */
+/** The issue type's name and the parent's key, when the search returned them: { type?, parent? }. */
+function typeParent(t, p) {
+  const out = {};
+  const type = clip(nameOf(t), 40);
+  if (type) out.type = type;
+  const pk = oneLine(p && typeof p === 'object' ? p.key : p).toUpperCase();
+  if (KEY_RE.test(pk)) out.parent = pk;
+  return out;
+}
 function normalizeIssue(x) {
   if (!x || typeof x !== 'object') return null;
   const key = oneLine(x.key).toUpperCase();
@@ -160,7 +174,8 @@ function normalizeIssue(x) {
     const flagged = flaggedIn(f) || /block|impediment|on hold/i.test(status);
     return { key, summary, status, category: categoryOf(status, st.statusCategory), sprint: sprintIn(f), subtasks: subtasksOf(f.subtasks), fixVersion: fixVersionsOf(f.fixVersions),
       points: pointsIn(f), resolved: dayOf(f.resolutiondate || f.resolved),
-      flagged, reason: flagged ? (flaggedIn(f) ? 'Flagged in Jira' : `Status: ${status}`) : null, url: urlOf(x, key) };
+      flagged, reason: flagged ? (flaggedIn(f) ? 'Flagged in Jira' : `Status: ${status}`) : null, url: urlOf(x, key),
+      ...typeParent(f.issuetype, f.parent) };
   }
   // The flat shape: what the skill tells the agent to write when it is unsure of the connector's shape.
   const summary = clip(oneLine(x.summary || x.title), 250);
@@ -170,7 +185,7 @@ function normalizeIssue(x) {
   return { key, summary, status, category: categoryOf(status, x.category), sprint: sprintOf(x.sprint), subtasks: subtasksOf(x.subtasks), fixVersion: fixVersionsOf(x.fixVersions != null ? x.fixVersions : x.fixVersion),
     points: pointsIn(x), resolved: dayOf(x.resolved || x.resolutiondate),
     flagged, reason: flagged ? clip(oneLine(x.reason || x.flag_reason || (x.flagged === true ? 'Flagged in Jira' : `Status: ${status}`)), 160) : null,
-    url: urlOf(x, key) };
+    url: urlOf(x, key), ...typeParent(x.type != null ? x.type : x.issuetype, x.parent) };
 }
 function normalize(raw) {
   const list = issuesList(raw);
@@ -223,13 +238,18 @@ function sync(root, initiative, raw, { query, dryRun = false, now } = {}) {
   const n = normalize(raw);
   if (n.error) return { ok: false, error: n.error };
   const pushed = jiraTickets.pushedTickets(root, initiative).tickets;
-  if (!pushed.size) return { ok: false, error: `${initiative} has no ticket in Jira yet — push its tickets first` };
+  const epics = pushed.size ? [] : jiraTickets.epicKeysOf(root, initiative);
+  if (!pushed.size && !epics.length) return { ok: false, error: `${initiative} has no ticket in Jira yet — push its tickets first, or link its Jira epic` };
   const prev = readSnapshot(root, initiative);
-  const got = new Map(n.issues.filter((i) => pushed.has(i.key)).map((i) => [i.key, i]));
+  // Pushed mode keeps the pushed keys. Epic mode keeps the epics and the issues under them; an issue the search returned
+  // with no parent field is kept, since the search was scoped to the epics; one under another parent is ignored.
+  const keep = pushed.size ? (i) => pushed.has(i.key) : (i) => epics.includes(i.key) || !i.parent || epics.includes(i.parent);
+  const got = new Map(n.issues.filter(keep).map((i) => [i.key, i]));
   const ignored = n.issues.length - got.size;
   const ids = new Map([...pushed].map(([k, v]) => [k, v.id]));
   const readings = []; const changes = []; const missing = [];
-  for (const key of pushed.keys()) {
+  const expected = pushed.size ? [...pushed.keys()] : [...new Set([...epics, ...got.keys(), ...(prev ? [...prev.tickets.keys()].filter((k) => { const r = prev.tickets.get(k); return epics.includes(k) || !r.parent || epics.includes(r.parent); }) : [])])];
+  for (const key of expected) {
     const r = got.get(key);
     const was = prev ? prev.tickets.get(key) : null;
     if (!r) {

package/workspace/lib/jira-tickets.js

@@ -42,6 +42,7 @@ const crypto = require('crypto');
 const planItems = require('./plan-items.js');
 const planTree = require('./plan-tree.js');
 const consoleState = require('./console-state');
+const { repoScript } = require('./repo-script.js');
 
 const KEY_RE = /^[A-Za-z][A-Za-z0-9_]*-\d+$/;
 const KEY_IN = /\b([A-Z][A-Z0-9_]+-\d+)\b/;
@@ -354,8 +355,10 @@ function missingOf(t) {
 }
 
 // ── J3 · draft ─────────────────────────────────────────────────────────────────────────────────────
+/** The Jira epic a record names: `jira_issue_key`, else `jira_epic`, else `jira`, when the value is a Jira key. */
 function anchorOf(rfm) {
-  return isStr(rfm.jira_issue_key) && KEY_RE.test(rfm.jira_issue_key.trim()) ? rfm.jira_issue_key.trim().toUpperCase() : null;
+  for (const k of ['jira_issue_key', 'jira_epic', 'jira']) if (rfm && isStr(rfm[k]) && KEY_RE.test(rfm[k].trim())) return rfm[k].trim().toUpperCase();
+  return null;
 }
 function draft(root, initiative, { dryRun = false, now } = {}) {
   const st = items(root, initiative);
@@ -653,6 +656,31 @@ function pushedTickets(root, initiative) {
   for (const t of d.tickets) if (t.jira) tickets.set(t.jira, { id: t.id, summary: t.summary });
   return { epic: KEY_RE.test(d.fm.epic || '') ? String(d.fm.epic).toUpperCase() : null, tickets };
 }
+/** The Jira epics the PM linked on the initiative page: the boards ledger's `ini-epics` lines (lib/routes-boards.js),
+ * folded by scripts/boards.js. Map initiative id → keys; an initiative the PM never linked is absent. */
+function linkedEpics(root) {
+  const base = mainRoot(root);
+  for (const rel of [['pmos', 'state'], ['state'], ['.pmos']]) {
+    let text;
+    try { text = fs.readFileSync(path.join(base, ...rel, 'boards.jsonl'), 'utf8'); } catch { continue; }
+    try { return require(repoScript('boards.js')).fold(text.split('\n').filter(Boolean)).epics || new Map(); } catch { return new Map(); }
+  }
+  return new Map();
+}
+/** The Jira epics of an initiative: the ones the PM linked on the page, else the one its record names (anchorOf). */
+function epicKeysOf(root, initiative, linked = linkedEpics(root)) {
+  if (linked.has(initiative)) return linked.get(initiative);
+  const a = anchorOf(recordFm(root, initiative) || {});
+  return a ? [a] : [];
+}
+/** Every initiative with a Jira epic, linked on the page or named by its record, whether or not it has a ticket draft. */
+function epicInitiatives(root) {
+  const linked = linkedEpics(root);
+  let names = [];
+  try { names = fs.readdirSync(engine().layout(mainRoot(root)).initiatives).filter((n) => n.endsWith('.md')).map((n) => n.slice(0, -3)); } catch { names = []; }
+  const ids = new Set([...names, ...linked.keys()].filter((id) => planItems.INIT_RE.test(id)));
+  return [...ids].filter((id) => epicKeysOf(root, id, linked).length && recordFm(root, id)).sort();
+}
 /** Every initiative with a ticket draft in this repository. */
 function draftedInitiatives(root) {
   let names = [];
@@ -663,6 +691,6 @@ function draftedInitiatives(root) {
 module.exports = {
   TYPES, PRIORITIES, ESTIMATES, SECTIONS, REQUIRED,
   items, itemsInPrd, itemsInFile, fromItem, draft, view, edit, resolvePrd, setEpic, approve, pushPlan, record,
-  readDraft, parseDraft, pushedTickets, draftedInitiatives, missingOf, contentHash, describe,
+  readDraft, parseDraft, pushedTickets, draftedInitiatives, epicInitiatives, epicKeysOf, linkedEpics, anchorOf, missingOf, contentHash, describe,
   draftPath, draftRel, jiraDir, relOf, recordFm, prdOf,
 };

package/workspace/lib/routes-boards.js

@@ -19,8 +19,9 @@
  *   POST /api/boards/asks/accept   { ws, board, ask, title, lane, anchor, intent?, id? } → { ok, initiative, stage }
  *   POST /api/boards/asks/decline  { ws, board, ask, why }                               → { ok }
  *   POST /api/boards/asks/more     { ws, board, ask, note? }                             → { ok }
- *   POST /api/boards/settings      { ws, board, buildDeliver?, jira?, offer?, defTpl? }       → { ok, board }
+ *   POST /api/boards/settings      { ws, board, buildDeliver?, jira?, offer?, defTpl? }       → { ok, board }   jira: one key or a list
  *   POST /api/boards/ini-workflow  { ws, board, id, template?, stages, moveTo? }         → { ok, row, moved }
+ *   POST /api/boards/ini-epics     { ws, board, id, epics: [Jira key] }                  → { ok, row }   the Jira epics of an initiative ([] unlinks)
  *   POST /api/boards/tasks/add     { ws, board, initiative, title, type?, epic?, start?, due?, owner? } → { ok, item }
  *   POST /api/boards/tasks/state   { ws, board, task, state }                            → { ok, item }
  *   POST /api/boards/tasks/reschedule { ws, board, task, days }                          → { ok, item }
@@ -116,8 +117,8 @@ function boardsOf(ctx, w, folded) {
     return {
       ws: w.id, id: b0.id, name: typeof led.name === 'string' && led.name ? led.name : b0.name, domain: 'domain' in led ? led.domain : b0.domain,
       kind: b0.kind, template, templateEdited: selfBoard ? false : B.isTemplateEdited(template, workflow), workflow, self: selfBoard,
-      tracker: led.tracker || (set.jira ? `Jira · ${set.jira}` : null), sprints: !!led.sprints || (set.build && !!set.jira),
-      build: set.build, buildDeliver: set.build, jira: set.jira, offer: set.offer, defTpl: set.defTpl,
+      tracker: set.jiraProjects.length ? `Jira · ${set.jiraProjects.join(', ')}` : led.tracker || null, sprints: !!led.sprints || (set.build && !!set.jira),
+      build: set.build, buildDeliver: set.build, jira: set.jira, jiraProjects: set.jiraProjects, offer: set.offer, defTpl: set.defTpl,
     };
   });
 }
@@ -201,12 +202,19 @@ function baseRows(w) {
       reading: B.readingOf(r.nine_stages, { accepted: !!rec.accepted }),
       lifecycle: rec.stopped ? rec.stopped.state : null,
       hasSpec, record: relRec || null, domainFolder: dm ? dm[1] : null,
+      recordEpic: jiraTickets.anchorOf(fm),
     });
   }
   rowCache.set(w.root, { key: cacheKey, rows });
   return { ok: true, rows };
 }
 
+/** The Jira epics of an initiative: the ones the PM linked on the page (the ledger), else the epic its record names. */
+function epicsOf(base, folded) {
+  if (folded && folded.epics && folded.epics.has(base.id)) return { epics: folded.epics.get(base.id), epicsFrom: 'pmos' };
+  return base.recordEpic ? { epics: [base.recordEpic], epicsFrom: 'record' } : { epics: [], epicsFrom: null };
+}
+
 /** The PRD row of one base row on one board. */
 function boardRow(board, base, folded) {
   const s = B.stageOf(board, base.id, base.reading, folded);
@@ -217,6 +225,7 @@ function boardRow(board, base, folded) {
     horizon: base.horizon, status: base.status, start: base.start, end: base.end, progress: base.progress, warnings: [],
     rank: base.rank, health: base.health, updated: base.updated, reading: base.reading, stageSource: s.source, lifecycle: base.lifecycle,
     template: B.templateOf(board, base.id, folded), workflow: wf.map((x) => ({ name: x.name, cat: x.cat })),
+    ...epicsOf(base, folded),
   };
   const w = [];
   if (s.source === 'move') {
@@ -272,9 +281,9 @@ function itemsOf(w, fr, board, rows) {
       let d = null;
       let snap = null;
       try { d = jiraTickets.readDraft(w.root, row.id); } catch { d = null; }
-      if (!d) continue;
       try { snap = jiraStatus.readSnapshot(w.root, row.id); } catch { snap = null; }
       const reading = (k) => (snap && snap.tickets && snap.tickets.get ? snap.tickets.get(k) : null) || null;
+      if (!d) { epicItems(row, board, snap, jiraKeys, out); continue; }
       const epicKey = /^[A-Za-z][A-Za-z0-9_]*-\d+$/.test(String((d.fm && d.fm.epic) || '')) ? String(d.fm.epic).toUpperCase() : null;
       if (epicKey) {
         const rd = reading(epicKey);
@@ -294,6 +303,22 @@ function itemsOf(w, fr, board, rows) {
   return B.rollupItems(out);
 }
 
+/** The Jira items of an initiative PMOS pushed nothing for: its linked epics and the issues under them, from the last
+ * read of the Jira status check (lib/jira-status.js, epic mode). An issue under no linked epic hangs under the first. */
+function epicItems(row, board, snap, seen, out) {
+  if (!snap || !snap.tickets || !snap.tickets.size || !(row.epics || []).length) return;
+  const epics = row.epics.filter((k) => snap.tickets.has(k));
+  const first = epics[0] || null;
+  const item = (r, kind, epic) => ({ uid: r.key, key: r.key, kind, src: 'jira', title: r.summary || r.key, status: B.itemStatus(r.status, r.category), blocked: !!r.flagged, owner: null, ini: row.id, epic, start: null, end: null, ref: null, board: board.id });
+  for (const k of epics) { if (!seen.has(k)) { out.push(item(snap.tickets.get(k), 'Epic', null)); seen.add(k); } }
+  for (const r of snap.tickets.values()) {
+    if (seen.has(r.key) || (r.parent && !row.epics.includes(r.parent)) || (!r.parent && r.type === 'Epic')) continue;   // a reading of an epic no longer linked
+    const kind = ['Story', 'Task', 'Bug'].find((t) => t.toLowerCase() === String(r.type || '').toLowerCase()) || 'Task';
+    out.push(item(r, kind, r.parent && epics.includes(r.parent) ? r.parent : first));
+    seen.add(r.key);
+  }
+}
+
 // ── HTTP ──────────────────────────────────────────────────────────────────────────────────────────
 function wsOf(ctx, wsParam) {
   const w = ctx.getWs(wsParam || null);
@@ -415,8 +440,8 @@ const READS = {
   '/api/boards/items': (ctx, res, url) => {
     const r = boardRead(ctx, res, url);
     if (!r) return;
-    ctx.json(res, { ok: true, ws: r.w.id, board: r.board.id, build: r.board.build, jira: r.board.jira, items: itemsOf(r.w, r.fr, r.board, r.rows),
-      initiatives: r.rows.map((x) => ({ id: x.id, title: x.title, stage: x.stage, cat: x.cat, status: x.status, owner: x.owner, horizon: x.horizon, start: x.start, end: x.end, progress: x.progress, template: x.template })) });
+    ctx.json(res, { ok: true, ws: r.w.id, board: r.board.id, build: r.board.build, jira: r.board.jira, jiraProjects: r.board.jiraProjects, items: itemsOf(r.w, r.fr, r.board, r.rows),
+      initiatives: r.rows.map((x) => ({ id: x.id, title: x.title, stage: x.stage, cat: x.cat, status: x.status, owner: x.owner, horizon: x.horizon, start: x.start, end: x.end, progress: x.progress, template: x.template, epics: x.epics })) });
   },
   '/api/boards/sprints': (ctx, res, url) => {
     const r = boardRead(ctx, res, url);
@@ -461,10 +486,12 @@ function settingsOf(body, board) {
   const v = {};
   const bd = body.buildDeliver != null ? body.buildDeliver : body.build;
   if (bd != null) { if (typeof bd !== 'boolean') return { error: 'buildDeliver is true or false' }; v.buildDeliver = bd; }
-  if (body.jira != null && body.jira !== '') {
-    if (typeof body.jira !== 'string' || !/^[A-Za-z][A-Za-z0-9_]{0,19}$/.test(body.jira.trim())) return { error: 'jira is a Jira project key: a letter, then letters, digits or _ (at most 20)' };
-    v.jira = body.jira.trim().toUpperCase();
-  } else if (body.jira === '') v.jira = null;
+  if (body.jira != null && body.jira !== '' && !(Array.isArray(body.jira) && !body.jira.length)) {
+    const list = Array.isArray(body.jira) ? body.jira : typeof body.jira === 'string' ? body.jira.split(/[,\s]+/).filter(Boolean) : null;
+    if (!list || list.length > 10 || list.some((k) => typeof k !== 'string' || !B.JIRA_PROJECT_RE.test(k.trim()))) return { error: 'jira is one or more Jira project keys (at most 10), each a letter, then letters, digits or _ (at most 20)' };
+    const keys = [...new Set(list.map((k) => k.trim().toUpperCase()))];
+    v.jira = keys.length === 1 ? keys[0] : keys;
+  } else if (body.jira === '' || Array.isArray(body.jira)) v.jira = null;
   const build = 'buildDeliver' in v ? v.buildDeliver : board ? board.build : true;
   if (body.offer != null) {
     if (!Array.isArray(body.offer) || !body.offer.length || body.offer.some((k) => !B.INI_TEMPLATES[k])) return { error: `offer is a list of templates: ${Object.keys(B.INI_TEMPLATES).join(', ')}` };
@@ -501,7 +528,7 @@ const WRITES = {
     if (set.error) return fail(ctx, res, 400, set.error);
     const ev = { kind: 'board', op: 'create', board: id, name, domain: body.domain ? String(body.domain).trim() : null, template: body.template, workflow, sprints: false, tracker: null };
     for (const k of ['buildDeliver', 'jira', 'offer', 'defTpl']) if (k in set.value) ev[k] = set.value[k];
-    if (ev.buildDeliver !== false && ev.jira) { ev.tracker = `Jira · ${ev.jira}`; ev.sprints = true; }
+    if (ev.buildDeliver !== false && ev.jira) { ev.tracker = `Jira · ${[].concat(ev.jira).join(', ')}`; ev.sprints = true; }
     append(p.file, g.actor, ev);
     const board = boardsOf(ctx, p.w, B.fold(readLedger(ctx, p.w))).find((b) => b.id === id);
     ctx.json(res, { ok: true, board });
@@ -613,9 +640,9 @@ const WRITES = {
     if (!p.file) return fail(ctx, res, 409, NO_STATE);
     const ev = { kind: 'board', op: 'settings', board: p.board.id, ...set.value };
     const build = 'buildDeliver' in set.value ? set.value.buildDeliver : p.board.build;
-    const jira = 'jira' in set.value ? set.value.jira : p.board.jira;
-    ev.tracker = build && jira ? `Jira · ${jira}` : null;
-    ev.sprints = !!(build && jira);
+    const jira = 'jira' in set.value ? (set.value.jira ? [].concat(set.value.jira) : []) : p.board.jiraProjects;
+    ev.tracker = build && jira.length ? `Jira · ${jira.join(', ')}` : null;
+    ev.sprints = !!(build && jira.length);
     append(p.file, g.actor, ev);
     const board = boardsOf(ctx, p.w, B.fold(readLedger(ctx, p.w))).find((b) => b.id === p.board.id);
     ctx.json(res, { ok: true, board });
@@ -639,6 +666,26 @@ const WRITES = {
     const row = boardRow(p.board, b0, B.fold(readLedger(ctx, p.w)));
     ctx.json(res, { ok: true, row, moved: ed.moved });
   },
+  '/api/boards/ini-epics': (ctx, res, body, g) => {
+    const p = postFrame(ctx, res, body);
+    if (!p) return;
+    if (typeof body.id !== 'string' || !body.id) return fail(ctx, res, 400, 'id is required');
+    if (!p.board.build) return fail(ctx, res, 409, `${p.board.name} has Build and deliver off, so it mirrors no Jira`);
+    const list = Array.isArray(body.epics) ? body.epics : typeof body.epics === 'string' ? body.epics.split(/[,\s]+/).filter(Boolean) : null;
+    if (!list || list.length > 20 || list.some((k) => typeof k !== 'string' || !B.JIRA_KEY_RE.test(k.trim()))) return fail(ctx, res, 400, 'epics is a list of Jira keys (at most 20), each like IDPF-2685');
+    const epics = [...new Set(list.map((k) => k.trim().toUpperCase()))];
+    const projects = p.board.jiraProjects || [];
+    const off = projects.length ? epics.filter((k) => !projects.includes(k.split('-')[0])) : [];
+    if (off.length) return fail(ctx, res, 400, `${off.join(', ')} ${off.length === 1 ? 'is' : 'are'} not in a Jira project of ${p.board.name} (${projects.join(', ')})`);
+    if (!p.file) return fail(ctx, res, 409, NO_STATE);
+    const base = needRows(ctx, res, p.w);
+    if (!base) return;
+    const b0 = base.find((r) => r.id === body.id);
+    if (!b0 || boardIdOf(b0, p.fr.boards, p.fr.folded, p.w) !== p.board.id) return fail(ctx, res, 404, `no initiative ${body.id} on this board`);
+    append(p.file, g.actor, { kind: 'ini-epics', board: p.board.id, id: body.id, epics });
+    const row = boardRow(p.board, b0, B.fold(readLedger(ctx, p.w)));
+    ctx.json(res, { ok: true, row });
+  },
   '/api/boards/tasks/add': (ctx, res, body, g) => {
     const p = postFrame(ctx, res, body);
     if (!p) return;

package/workspace/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "pmos-workspace",
-  "version": "0.142.0",
+  "version": "0.144.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "pmos-workspace",
-      "version": "0.142.0",
+      "version": "0.144.0",
       "license": "MIT",
       "dependencies": {
         "@xterm/addon-fit": "^0.11.0",

package/workspace/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pmos-workspace",
-  "version": "0.142.0",
+  "version": "0.144.0",
   "private": true,
   "description": "PMOS Terminal Workspace — local companion hosting real PTYs beside the library and gates (D62)",
   "license": "MIT",