create-pmos 0.57.1 → 0.58.0

package/workspace/lib/jira-tickets.js

@@ -0,0 +1,668 @@
+'use strict';
+/* jira-tickets.js — Jira tickets drafted from the PRD in the PM's template, selected by the PM, then pushed (initiative
+ * jira-wbs, PRD J1 to J10 and J12, proposed D88).
+ *
+ *   items(root, initiative)                     → { items, sources, prd }     J1: the ticket items of the PRD and story files
+ *   fromItem(item, prd)                         → a ticket                    J2: one item in the PM's template
+ *   draft(root, initiative, opts)               → the merged draft, written   J3: new items added, unedited ones redrafted
+ *   view(root, initiative)                      → what the tab draws          J4, J5, J10, J12
+ *   edit(root, initiative, id, patch)           → the ticket, written         J5
+ *   resolvePrd(root, initiative, id, use)       → 'prd' | 'keep'              J10
+ *   setEpic(root, initiative, { mode, key })    → the epic choice             J8
+ *   approve(root, initiative, ids)              → the selected hashes         J6 (the caller has checked it is the PM)
+ *   pushPlan(root, initiative)                  → what to create or update    J7: approved content only
+ *   record(root, initiative, keys)              → keys and pushed hashes      J9
+ *
+ * THE DRAFT FILE is `<state>/tracker/jira/<initiative>-tickets.md`. PMOS owns the text of these tickets and Jira owns
+ * their status (D88). A ticket is:
+ *
+ *   ## TD-01 · Carry the real runtime version on every GA4 event
+ *   - type: Task                       Task | Story | Bug
+ *   - priority: High                   Highest | High | Medium | Low
+ *   - estimate: S                      XS | S | M | L | XL, or absent
+ *   - depends: TD-00                   other ticket ids, comma-separated, or absent
+ *   - source: <hash of the PRD item it matches>
+ *   - drafted: <hash of the content as drafted>      (equal to the content: the PM has not edited it)
+ *   - approved: <hash of the content the PM selected for a push>
+ *   - jira: ATL-491                    (written by `record`)
+ *   - pushed: <hash of the content last pushed>
+ *
+ *   ### User Story · ### Additional Context · ### User Flow · ### Functional Requirements · ### Terminal States
+ *   ### Acceptance Criteria · ### Refs
+ *
+ * The CONTENT of a ticket is its summary, the four fields and the seven sections. Approval, push and edit detection
+ * all compare a hash of it, so a key or a hash written by `record` never counts as an edit.
+ *
+ * BOUNDARY (J15). No network module and no child process: an agent creates the tickets with the PM's own Atlassian
+ * connection (D53) and tells this module the keys. Who may approve is decided by the caller (pm-guard), never here.
+ */
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+const planItems = require('./plan-items.js');
+const planTree = require('./plan-tree.js');
+const consoleState = require('./console-state');
+
+const KEY_RE = /^[A-Za-z][A-Za-z0-9_]*-\d+$/;
+const KEY_IN = /\b([A-Z][A-Z0-9_]+-\d+)\b/;
+const ID_RE = /^[A-Za-z0-9][\w.-]{0,40}$/;
+const TICKET_RE = /^## ([A-Za-z0-9][\w.-]{0,40}) · (.*)$/;
+const FIELD_RE = /^- (type|priority|estimate|depends|source|drafted|approved|jira|pushed): (.*)$/;
+const TYPES = Object.freeze(['Task', 'Story', 'Bug']);
+const PRIORITIES = Object.freeze(['Highest', 'High', 'Medium', 'Low']);
+const ESTIMATES = Object.freeze(['XS', 'S', 'M', 'L', 'XL']);
+/** The template's sections, in order, as [key, heading]. */
+const SECTIONS = Object.freeze([
+  ['story', 'User Story'], ['context', 'Additional Context'], ['flow', 'User Flow'],
+  ['functional', 'Functional Requirements'], ['terminal', 'Terminal States'], ['acceptance', 'Acceptance Criteria'], ['refs', 'Refs'],
+]);
+const REQUIRED = Object.freeze(['story', 'functional', 'acceptance']);
+const ALIASES = Object.freeze({
+  'user story': 'story', story: 'story', 'additional context': 'context', context: 'context', background: 'context',
+  'user flow': 'flow', flow: 'flow', 'functional requirements': 'functional', requirements: 'functional',
+  'terminal states': 'terminal', 'end states': 'terminal', 'acceptance criteria': 'acceptance', acceptance: 'acceptance',
+  refs: 'refs', references: 'refs', links: 'refs',
+});
+const ITEM_SECTIONS = /^(user stories|stories|tickets|jira tickets|work items)\b/i;
+const MAX_SUMMARY = 250;
+const MAX_SECTION = 20000;
+
+const isStr = (v) => typeof v === 'string';
+const oneLine = (s) => String(s == null ? '' : s).replace(/[\r\n\t]+/g, ' ').replace(/\s{2,}/g, ' ').trim();
+const clip = (s, n) => (s.length > n ? s.slice(0, n - 1).trimEnd() + '…' : s);
+const sha = (s) => crypto.createHash('sha256').update(s).digest('hex').slice(0, 16);
+const tokens = (s) => String(s || '').toLowerCase().split(/[^a-z0-9]+/).filter(Boolean);
+const pick = (list, v) => list.find((x) => x.toLowerCase() === String(v || '').trim().toLowerCase()) || null;
+
+function engine() {
+  const loaded = consoleState.loadEngine();
+  if (!loaded.ok) throw new Error(loaded.error);
+  return loaded.engine;
+}
+const mainRoot = (root) => planItems.ledgerRoot(root);
+const stateDir = (root) => path.dirname(engine().layout(mainRoot(root)).initiatives);
+function recordFm(root, initiative) {
+  const file = planTree.recordPath(root, initiative);
+  if (!file) return null;
+  try { return engine().parseLeadingFrontmatter(fs.readFileSync(file, 'utf8')) || {}; } catch { return {}; }
+}
+/** The PRD of an initiative: `prd_path` in a code repository, `doc_path` (the lane's draft) in a document repository. */
+function prdOf(rfm) {
+  for (const k of ['prd_path', 'doc_path']) if (rfm && isStr(rfm[k]) && rfm[k].trim()) return rfm[k].trim();
+  return null;
+}
+function jiraDir(root) { return path.join(stateDir(root), 'tracker', 'jira'); }
+function draftPath(root, initiative) { return path.join(jiraDir(root), `${initiative}-tickets.md`); }
+const relOf = (root, file) => path.relative(mainRoot(root), file).split(path.sep).join('/');
+function draftRel(root, initiative) { return relOf(root, draftPath(root, initiative)); }
+
+// ── J1 · the ticket items of the PRD ───────────────────────────────────────────────────────────────
+const stripFm = (text) => String(text).replace(/^---\n[\s\S]*?\n---\n?/, '');
+const slug = (s) => tokens(s).slice(0, 6).join('-') || 'item';
+/** "TD-01 · Carry the version" / "S3: Pay" / "Pay" → { id, title } */
+function splitHeading(h) {
+  const t = oneLine(h.replace(/\*\*/g, ''));
+  const m = /^([A-Za-z]{1,5}-?\d+)\s*[·:.\-—–]\s*(.+)$/.exec(t);
+  if (m) return { id: m[1].toUpperCase(), title: m[2].replace(/\.$/, '').trim() };
+  return { id: null, title: t.replace(/\.$/, '') };
+}
+/** "As a PM, I want to pay with a saved card, so that …" → "Pay with a saved card" */
+function titleFromStory(text) {
+  const m = /\bI want(?: to)? (.+?)(?:,? so that\b|[.;]|$)/i.exec(oneLine(text));
+  if (!m) return clip(oneLine(text), 80);
+  const t = m[1].trim();
+  return clip(t[0].toUpperCase() + t.slice(1), 80);
+}
+/** The items under one heading: its subheadings, else its top-level bullets. */
+function itemsIn(lines, level) {
+  const out = [];
+  const sub = '#'.repeat(level + 1) + ' ';
+  if (lines.some((l) => l.startsWith(sub))) {
+    let cur = null;
+    for (const l of lines) {
+      if (l.startsWith(sub)) { cur = { heading: l.slice(sub.length), body: [] }; out.push(cur); continue; }
+      if (cur) cur.body.push(l);
+    }
+    return out.map((s) => { const h = splitHeading(s.heading); return { id: h.id, title: h.title, body: s.body.join('\n').trim() }; });
+  }
+  let cur = null;
+  for (const l of lines) {
+    const b = /^[-*] (.+)$/.exec(l);
+    if (b) { cur = { first: b[1], rest: [] }; out.push(cur); continue; }
+    if (cur && /^\s+\S/.test(l)) cur.rest.push(l.trim());
+    else if (cur && l.trim()) cur = null;
+  }
+  return out.map((s) => {
+    const lead = /^\*\*(.+?)\*\*\s*(.*)$/.exec(s.first);
+    const body = [lead ? lead[2] : s.first, ...s.rest].join('\n').trim();
+    if (lead) { const h = splitHeading(lead[1]); return { id: h.id, title: h.title || titleFromStory(body), body }; }
+    return { id: null, title: titleFromStory(body), body };
+  }).filter((s) => /\bas an? \b/i.test(s.body) || s.id);
+}
+/** The items in a PRD: the sections headed "User stories", "Stories", "Tickets", "Jira tickets" or "Work items". */
+function itemsInPrd(text) {
+  const lines = stripFm(text).split('\n');
+  const out = [];
+  for (let i = 0; i < lines.length; i++) {
+    const m = /^(#{2,4}) (.+)$/.exec(lines[i]);
+    if (!m || !ITEM_SECTIONS.test(m[2].trim())) continue;
+    const level = m[1].length;
+    const body = [];
+    for (let j = i + 1; j < lines.length; j++) {
+      const h = /^(#{1,6}) /.exec(lines[j]);
+      if (h && h[1].length <= level) break;
+      body.push(lines[j]);
+    }
+    out.push(...itemsIn(body, level));
+  }
+  return out;
+}
+/** A story file: each `## ` section is an item. */
+function itemsInFile(text) {
+  return itemsIn(stripFm(text).split('\n').filter((l) => !/^# /.test(l)), 1);
+}
+function readPrd(root, prd) {
+  try { return fs.readFileSync(path.join(root, prd), 'utf8'); } catch { /* the main tree */ }
+  try { return fs.readFileSync(path.join(mainRoot(root), prd), 'utf8'); } catch { return null; }
+}
+function items(root, initiative) {
+  const fm = recordFm(root, initiative);
+  if (!fm) return { ok: false, error: `no initiative ${initiative} in this repository` };
+  const base = mainRoot(root);
+  const found = []; const sources = [];
+  const prd = prdOf(fm) || '';
+  if (prd) {
+    const text = readPrd(root, prd);
+    if (text != null) { const s = itemsInPrd(text); for (const x of s) x.source = prd; if (s.length) { found.push(...s); sources.push(prd); } }
+  }
+  const dir = path.join(stateDir(root), 'stories');
+  let names = [];
+  try { names = fs.readdirSync(dir).filter((n) => n.endsWith('.md')).sort(); } catch { names = []; }
+  for (const n of names) {
+    let text = '';
+    try { text = fs.readFileSync(path.join(dir, n), 'utf8'); } catch { continue; }
+    const ffm = engine().parseLeadingFrontmatter(text) || {};
+    const mine = ffm.initiative_id === initiative || n === `${initiative}.md` || n.startsWith(`${initiative}-`);
+    if (!mine) continue;
+    const rel = path.relative(base, path.join(dir, n)).split(path.sep).join('/');
+    const s = itemsInFile(text);
+    for (const x of s) x.source = rel;
+    if (s.length) { found.push(...s); sources.push(rel); }
+  }
+  // Ids: the item's own (TD-01, S3) or a slug of its title; a repeat gets -2, -3.
+  const seen = new Map();
+  for (const s of found) {
+    let id = s.id || slug(s.title);
+    const n = (seen.get(id) || 0) + 1; seen.set(id, n);
+    if (n > 1) id = `${id}-${n}`;
+    s.id = id;
+    s.title = clip(oneLine(s.title), MAX_SUMMARY);
+    s.hash = sha(s.title + '\n' + s.body);
+  }
+  return { ok: true, initiative, items: found, sources, prd: prd || null };
+}
+
+// ── J2 · one item in the PM's template ─────────────────────────────────────────────────────────────
+const sectionKey = (line) => {
+  const t = String(line).replace(/^#{1,6}\s+/, '').replace(/\*\*/g, '').replace(/:\s*$/, '').trim().toLowerCase();
+  return ALIASES[t] || null;
+};
+/** "Type: Task · Priority: High · Estimate: S · Depends on: TD-00" → the four fields it names. */
+function metaLine(line) {
+  const t = String(line).replace(/\*\*/g, '').replace(/^\s*[-*]\s+/, '');
+  if (!/\b(type|priority|estimate|depends on)\s*:/i.test(t)) return null;
+  const out = {};
+  for (const part of t.split(/\s*[·|]\s*/)) {
+    const m = /^\s*(type|priority|estimate|depends on)\s*:\s*(.*)$/i.exec(part);
+    if (!m) continue;
+    const k = m[1].toLowerCase(); const v = m[2].trim();
+    if (k === 'type') out.type = pick(TYPES, v);
+    else if (k === 'priority') out.priority = pick(PRIORITIES, v);
+    else if (k === 'estimate') out.estimate = pick(ESTIMATES, v);
+    else out.depends = /^[-—–]?$|^none$/i.test(v) ? [] : v.split(/[\s,]+/).map((x) => x.trim()).filter((x) => ID_RE.test(x));
+  }
+  return Object.keys(out).length ? out : null;
+}
+const LINK_RE = /\[[^\]]+\]\([^)\s]+\)/g;
+/**
+ * A ticket from a PRD item. The item's own subsections fill the template by name; a `Type: … · Priority: …` line sets
+ * the fields; text before the first subsection is the User Story when it reads "As a …", else Additional Context.
+ */
+function fromItem(item, prd) {
+  const t = { id: item.id, summary: item.title, type: 'Task', priority: 'Medium', estimate: null, depends: [], sections: {} };
+  const buckets = { lead: [] };
+  let cur = 'lead';
+  for (const raw of String(item.body || '').split('\n')) {
+    const m = cur === 'lead' ? metaLine(raw) : null;
+    if (m) { for (const [k, v] of Object.entries(m)) if (v !== null) t[k] = v; continue; }
+    const sum = cur === 'lead' ? /^\s*(?:[-*]\s+)?(?:\*\*)?summary(?:\*\*)?\s*:(?:\*\*)?\s*(.+)$/i.exec(raw) : null;
+    if (sum) { t.summary = clip(oneLine(sum[1].replace(/\*\*/g, '')), MAX_SUMMARY); continue; }
+    const looksHeading = /^#{1,6}\s+\S/.test(raw) || /^\s*\*\*[^*]+\*\*:?\s*$/.test(raw) || /^[A-Z][A-Za-z ]{2,30}:\s*$/.test(raw);
+    const k = looksHeading ? sectionKey(raw.trim()) : null;
+    if (k) { cur = k; buckets[k] = buckets[k] || []; continue; }
+    (buckets[cur] = buckets[cur] || []).push(raw);
+  }
+  // A "## " line would start a new ticket in the draft file, and a "### " line a new section: keep them as text.
+  const text = (lines) => (lines || []).join('\n').replace(/^\n+|\n+$/g, '').replace(/^(#{1,3}) /gm, '#### ');
+  const lead = text(buckets.lead);
+  for (const [k] of SECTIONS) if (k !== 'refs') t.sections[k] = text(buckets[k]);
+  if (lead) {
+    const k = /^\s*(?:[-*]\s+)?as an? \b/i.test(lead) ? 'story' : 'context';
+    t.sections[k] = [lead, t.sections[k]].filter(Boolean).join('\n\n');
+  }
+  // Refs: the PRD and the item, the item's own refs, and every other link the item carries.
+  const own = text(buckets.refs);
+  const links = [];
+  for (const [k, lines] of Object.entries(buckets)) {
+    if (k === 'refs') continue;
+    for (const l of lines) for (const m of l.matchAll(LINK_RE)) if (!own.includes(m[0]) && !links.includes(m[0])) links.push(m[0]);
+  }
+  const refs = [prd ? `- PRD: \`${prd}\` · ${item.id}` : `- Item: ${item.id}`];
+  if (own) refs.push(own);
+  for (const l of links) refs.push(`- ${l}`);
+  t.sections.refs = refs.join('\n');
+  t.depends = t.depends.filter((d) => d !== t.id);
+  return t;
+}
+
+// ── the draft file ─────────────────────────────────────────────────────────────────────────────────
+function parseDraft(text) {
+  const fm = engine().parseLeadingFrontmatter(text) || {};
+  const tickets = [];
+  let cur = null; let inFields = false; let sec = 'context';
+  for (const l of stripFm(text).split('\n')) {
+    const h = TICKET_RE.exec(l);
+    if (h) { cur = { id: h[1], summary: h[2].trim(), fields: {}, buckets: {} }; tickets.push(cur); inFields = true; sec = 'context'; continue; }
+    if (!cur) continue;
+    if (/^## /.test(l)) { cur = null; continue; }
+    const f = FIELD_RE.exec(l);
+    if (inFields && f) { cur.fields[f[1]] = f[2].trim(); continue; }
+    inFields = false;
+    const s = /^### (.+)$/.exec(l);
+    const k = s ? sectionKey(s[1]) : null;
+    if (k) { sec = k; cur.buckets[k] = cur.buckets[k] || []; continue; }
+    (cur.buckets[sec] = cur.buckets[sec] || []).push(l);
+  }
+  const hashOk = (v) => (/^[0-9a-f]{16}$/.test(v || '') ? v : null);
+  return {
+    fm, tickets: tickets.map((t) => {
+      const sections = {};
+      for (const [k] of SECTIONS) {
+        const body = (t.buckets[k] || []).join('\n').replace(/^\n+|\n+$/g, '');
+        sections[k] = filled(body) ? body : '';
+      }
+      return {
+        id: t.id, summary: t.summary,
+        type: pick(TYPES, t.fields.type) || 'Task', priority: pick(PRIORITIES, t.fields.priority) || 'Medium',
+        estimate: pick(ESTIMATES, t.fields.estimate), depends: String(t.fields.depends || '').split(/[\s,]+/).filter((x) => ID_RE.test(x)),
+        sections, source: hashOk(t.fields.source), drafted: hashOk(t.fields.drafted), approved: hashOk(t.fields.approved),
+        jira: KEY_RE.test(t.fields.jira || '') ? t.fields.jira.toUpperCase() : null, pushed: hashOk(t.fields.pushed),
+      };
+    }),
+  };
+}
+function readDraft(root, initiative) {
+  let text;
+  try { text = fs.readFileSync(draftPath(root, initiative), 'utf8'); } catch { return null; }
+  return parseDraft(text);
+}
+/** A section that only says "—" is empty. */
+function filled(s) { return !!String(s || '').replace(/^[\s—–-]+$/, '').trim(); }
+/** The content of a ticket: what a push carries, and so what approval and edit detection cover. */
+const norm = (s) => (filled(s) ? String(s).trim() : '');
+const contentOf = (t) => JSON.stringify([t.id, oneLine(t.summary), t.type, t.priority, t.estimate || '', (t.depends || []).join(','),
+  ...SECTIONS.map(([k]) => norm(t.sections[k]))]);
+const contentHash = (t) => sha(contentOf(t));
+const nowIso = (now) => new Date(now == null ? Date.now() : now).toISOString().replace(/\.\d{3}Z$/, 'Z');
+function renderDraft({ initiative, fm, tickets, prd, timestamp }) {
+  const lines = ['---', 'type: Reference', `title: "Jira tickets: ${initiative}"`, `timestamp: ${timestamp}`];
+  if (fm.epic_mode === 'new' || fm.epic_mode === 'existing') lines.push(`epic_mode: ${fm.epic_mode}`);
+  if (KEY_RE.test(fm.epic || '')) lines.push(`epic: ${String(fm.epic).toUpperCase()}`);
+  lines.push('---', '');
+  lines.push(`# Jira tickets: ${initiative}`, '',
+    `Drafted by PMOS from ${prd ? `[${prd}](/${prd})` : 'the PRD'}, one ticket per item. Read and edit them on the initiative's Jira tickets tab, or here. Check the ones that are ready and press Push: only checked tickets are sent. A ticket edited after it was checked must be checked again.`, '',
+    'PMOS owns the text of these tickets and Jira owns their status. When the PRD changes, the tab flags each ticket whose item changed.', '');
+  for (const t of tickets) {
+    lines.push(`## ${t.id} · ${oneLine(t.summary)}`);
+    lines.push(`- type: ${t.type}`, `- priority: ${t.priority}`);
+    if (t.estimate) lines.push(`- estimate: ${t.estimate}`);
+    if (t.depends && t.depends.length) lines.push(`- depends: ${t.depends.join(', ')}`);
+    for (const k of ['source', 'drafted', 'approved', 'jira', 'pushed']) if (t[k]) lines.push(`- ${k}: ${t[k]}`);
+    lines.push('');
+    for (const [k, head] of SECTIONS) {
+      const body = norm(t.sections[k]);
+      lines.push(`### ${head}`, '', body || '—', '');
+    }
+  }
+  return lines.join('\n');
+}
+function writeDraft(root, initiative, d, { now, prd } = {}) {
+  const file = draftPath(root, initiative);
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const tmp = `${file}.${process.pid}.tmp`;
+  fs.writeFileSync(tmp, renderDraft({ initiative, fm: d.fm, tickets: d.tickets, prd, timestamp: nowIso(now) }));
+  fs.renameSync(tmp, file);
+}
+
+// ── J4 · complete ──────────────────────────────────────────────────────────────────────────────────
+const NAME = Object.fromEntries(SECTIONS);
+function missingOf(t) {
+  const out = [];
+  if (!oneLine(t.summary)) out.push('Summary');
+  for (const k of REQUIRED) if (!filled(t.sections[k])) out.push(NAME[k]);
+  return out;
+}
+
+// ── J3 · draft ─────────────────────────────────────────────────────────────────────────────────────
+function anchorOf(rfm) {
+  return isStr(rfm.jira_issue_key) && KEY_RE.test(rfm.jira_issue_key.trim()) ? rfm.jira_issue_key.trim().toUpperCase() : null;
+}
+function draft(root, initiative, { dryRun = false, now } = {}) {
+  const st = items(root, initiative);
+  if (!st.ok) return st;
+  if (!st.items.length) return { ok: false, error: `no ticket items found for ${initiative} — add a "User stories" or "Tickets" section to its PRD${st.prd ? ` (${st.prd})` : ''}, one subheading per ticket, such as "### TD-01 · Title"` };
+  const old = readDraft(root, initiative);
+  const prev = old ? old.tickets : [];
+  const byId = new Map(prev.map((t) => [t.id, t]));
+  const changes = [];
+  const out = [];
+  for (const it of st.items) {
+    const was = byId.get(it.id);
+    if (!was) {
+      const t = { ...fromItem(it, it.source), source: it.hash, approved: null, jira: null, pushed: null };
+      t.drafted = contentHash(t);
+      out.push(t); changes.push({ ticket: t.id, what: 'added', summary: t.summary });
+      continue;
+    }
+    byId.delete(it.id);
+    const t = { ...was };
+    if (t.source !== it.hash && !t.jira && (!t.drafted || t.drafted === contentHash(t))) {
+      Object.assign(t, fromItem(it, it.source), { source: it.hash });
+      t.drafted = contentHash(t);
+      changes.push({ ticket: t.id, what: 'redrafted', summary: t.summary, why: 'its item changed in the PRD and the ticket was not edited or pushed' });
+    }
+    out.push(t);
+  }
+  // Tickets whose item is gone stay, at the end: the tab says so and Jira is not touched (J10).
+  for (const t of byId.values()) out.push(t);
+  const fm = old ? { ...old.fm } : {};
+  if (!fm.epic_mode) {
+    const anchor = anchorOf(recordFm(root, initiative) || {});
+    fm.epic_mode = anchor ? 'existing' : 'new';
+    if (anchor && !fm.epic) fm.epic = anchor;
+  }
+  const result = { ok: true, initiative, draft: draftRel(root, initiative), sources: st.sources, tickets: out.length, changes, changed: !old || changes.length > 0 };
+  if (dryRun || (old && !changes.length)) return result;
+  writeDraft(root, initiative, { fm, tickets: out }, { now, prd: st.prd });
+  return result;
+}
+
+// ── J4, J5, J10, J12 · what the tab draws ──────────────────────────────────────────────────────────
+function epicOf(d, rfm) {
+  const fm = (d && d.fm) || {};
+  const anchor = anchorOf(rfm);
+  const mode = fm.epic_mode === 'existing' || fm.epic_mode === 'new' ? fm.epic_mode : (anchor ? 'existing' : 'new');
+  const key = KEY_RE.test(fm.epic || '') ? String(fm.epic).toUpperCase() : (mode === 'existing' ? anchor : null);
+  const pushedAny = !!(d && d.tickets.some((t) => t.jira));
+  return { mode, key, locked: pushedAny || (mode === 'new' && !!key), summary: isStr(rfm.title) ? rfm.title : null };
+}
+/** Is the handoff done, so the tab opens (J12)? */
+function gateOf(root, initiative, d, rfm) {
+  if (d && d.tickets.some((t) => t.jira)) return { open: true, why: 'a ticket is in Jira' };
+  let stages = [];
+  try { stages = planTree.stagesFor(root, initiative); } catch { stages = []; }
+  if (!stages.some((s) => s.id === 'handoff')) return { open: true, why: 'this lane has no handoff stage' };
+  if (isStr(rfm.handed_off) && rfm.handed_off.trim()) return { open: true, why: 'handed off' };
+  let fold = null;
+  try { fold = planItems.readFold(root); } catch { fold = null; }
+  const mine = fold ? (fold.order || []).map((id) => fold.items[id])
+    .filter((it) => it && it.initiative === initiative && it.stage === 'handoff' && !it.proposed && it.state !== 'withdrawn') : [];
+  if (mine.length && mine.every((it) => it.state === 'done')) return { open: true, why: 'every Handoff item is done' };
+  return { open: false, why: mine.length ? 'the Handoff item is not done yet' : 'the handoff is not done yet' };
+}
+function view(root, initiative, { snapshot } = {}) {
+  const rfm = recordFm(root, initiative);
+  if (!rfm) return { ok: false, status: 404, error: `no initiative ${initiative} in this repository` };
+  const st = items(root, initiative);
+  const d = readDraft(root, initiative);
+  const byItem = new Map((st.ok ? st.items : []).map((x) => [x.id, x]));
+  const reading = (snapshot && snapshot.tickets) || new Map();
+  const tickets = (d ? d.tickets : []).map((t) => {
+    const h = contentHash(t);
+    const it = byItem.get(t.id);
+    const missing = missingOf(t);
+    const prdChanged = !!(it && t.source && it.hash !== t.source);
+    const removed = !!(st.ok && !it);
+    const edited = !!(t.jira && t.pushed && t.pushed !== h);
+    const waiting = !!(t.approved === h && (!t.jira || t.pushed !== h));
+    const r = t.jira ? reading.get(t.jira) || null : null;
+    // One flag per row, the most urgent first (the mockup: a row carries one).
+    const flag = prdChanged ? 'prd-changed' : removed ? 'removed' : (r && r.flagged) ? 'blocked' : missing.length ? 'incomplete'
+      : waiting ? 'pushing' : edited ? 'edited' : null;
+    return {
+      id: t.id, summary: t.summary, type: t.type, priority: t.priority, estimate: t.estimate, depends: t.depends,
+      sections: t.sections, key: t.jira, inJira: !!t.jira, edited, prdChanged, removed, missing, waiting,
+      selectable: !missing.length && !removed && (!t.jira || t.pushed !== h), flag,
+      jira: r ? { status: r.status, category: r.category, sprint: r.sprint, subtasks: r.subtasks, flagged: !!r.flagged, reason: r.reason || null, url: r.url || null, stale: !!r.stale } : null,
+      prd: prdChanged ? (() => { const p = fromItem(it, it.source); return { summary: p.summary, type: p.type, priority: p.priority, estimate: p.estimate, depends: p.depends, sections: p.sections }; })() : null,
+    };
+  });
+  const have = new Set(tickets.map((t) => t.id));
+  const fresh = (st.ok ? st.items : []).filter((x) => !have.has(x.id)).map((x) => ({ id: x.id, summary: x.title }));
+  return {
+    ok: true, initiative, title: isStr(rfm.title) ? rfm.title : initiative, prd: st.ok ? st.prd : null,
+    gate: gateOf(root, initiative, d, rfm), epic: epicOf(d, rfm), drafted: !!d, draft: draftRel(root, initiative),
+    items: st.ok ? st.items.length : 0, newInPrd: fresh, tickets,
+    inJira: tickets.filter((t) => t.inJira).length, checkedAt: snapshot ? snapshot.fetchedAt : null,
+    types: TYPES, priorities: PRIORITIES, estimates: ESTIMATES, sectionNames: SECTIONS.map(([k, n]) => ({ key: k, name: n })),
+  };
+}
+
+// ── J5 · edit ──────────────────────────────────────────────────────────────────────────────────────
+function mustDraft(root, initiative) {
+  const d = readDraft(root, initiative);
+  if (!d) return { error: `no ticket draft for ${initiative} — press Draft tickets, or run pmos jira draft ${initiative}` };
+  return { d };
+}
+function edit(root, initiative, id, patch, { now } = {}) {
+  const { d, error } = mustDraft(root, initiative);
+  if (error) return { ok: false, status: 404, error };
+  const t = d.tickets.find((x) => x.id === id);
+  if (!t) return { ok: false, status: 404, error: `no ticket ${id} in the draft` };
+  const p = patch && typeof patch === 'object' ? patch : {};
+  if ('summary' in p) {
+    const s = clip(oneLine(p.summary), MAX_SUMMARY);
+    if (!s) return { ok: false, status: 400, error: 'a ticket needs a summary' };
+    t.summary = s;
+  }
+  if ('type' in p) { const v = pick(TYPES, p.type); if (!v) return { ok: false, status: 400, error: `type is one of ${TYPES.join(', ')}` }; t.type = v; }
+  if ('priority' in p) { const v = pick(PRIORITIES, p.priority); if (!v) return { ok: false, status: 400, error: `priority is one of ${PRIORITIES.join(', ')}` }; t.priority = v; }
+  if ('estimate' in p) {
+    if (p.estimate === null || p.estimate === '') t.estimate = null;
+    else { const v = pick(ESTIMATES, p.estimate); if (!v) return { ok: false, status: 400, error: `estimate is one of ${ESTIMATES.join(', ')}, or none` }; t.estimate = v; }
+  }
+  if ('depends' in p) {
+    const list = Array.isArray(p.depends) ? p.depends : String(p.depends || '').split(/[\s,]+/);
+    const ids = new Set(d.tickets.map((x) => x.id));
+    const dep = [...new Set(list.map((x) => String(x).trim()).filter(Boolean))];
+    const bad = dep.filter((x) => !ids.has(x) || x === id);
+    if (bad.length) return { ok: false, status: 400, error: `${bad.join(', ')} ${bad.length === 1 ? 'is not another ticket' : 'are not other tickets'} of this draft` };
+    t.depends = dep;
+  }
+  if ('sections' in p) {
+    if (!p.sections || typeof p.sections !== 'object' || Array.isArray(p.sections)) return { ok: false, status: 400, error: 'sections is an object of section texts' };
+    for (const [k, v] of Object.entries(p.sections)) {
+      if (!NAME[k]) return { ok: false, status: 400, error: `no section ${k}` };
+      if (!isStr(v) || v.length > MAX_SECTION) return { ok: false, status: 400, error: `${NAME[k]} must be text of at most ${MAX_SECTION} characters` };
+      // A "## " line would start a new ticket in the file, and a "### " line a new section: keep them as text.
+      t.sections[k] = v.replace(/\r\n?/g, '\n').replace(/^(#{1,3}) /gm, '#### ').trim();
+    }
+  }
+  writeDraft(root, initiative, d, { now, prd: prdOf(recordFm(root, initiative)) });
+  return { ok: true, initiative, ticket: id, missing: missingOf(t), edited: !!(t.jira && t.pushed !== contentHash(t)) };
+}
+
+// ── J10 · the PRD's version, or keep the ticket ────────────────────────────────────────────────────
+function resolvePrd(root, initiative, id, use, { now } = {}) {
+  if (use !== 'prd' && use !== 'keep') return { ok: false, status: 400, error: 'say which to use: prd or keep' };
+  const { d, error } = mustDraft(root, initiative);
+  if (error) return { ok: false, status: 404, error };
+  const t = d.tickets.find((x) => x.id === id);
+  if (!t) return { ok: false, status: 404, error: `no ticket ${id} in the draft` };
+  const st = items(root, initiative);
+  const it = st.ok ? st.items.find((x) => x.id === id) : null;
+  if (!it) return { ok: false, status: 409, error: `${id} is no longer in the PRD — nothing to take from it` };
+  if (t.source === it.hash) return { ok: true, initiative, ticket: id, already: true };
+  if (use === 'prd') {
+    Object.assign(t, fromItem(it, it.source));
+    t.drafted = contentHash(t);
+  }
+  t.source = it.hash;
+  writeDraft(root, initiative, d, { now, prd: st.prd });
+  return { ok: true, initiative, ticket: id, use, inJira: !!t.jira, pushable: !!t.jira && t.pushed !== contentHash(t) };
+}
+
+// ── J8 · the epic ──────────────────────────────────────────────────────────────────────────────────
+function setEpic(root, initiative, { mode, key } = {}, { now } = {}) {
+  const { d, error } = mustDraft(root, initiative);
+  if (error) return { ok: false, status: 404, error };
+  const rfm = recordFm(root, initiative) || {};
+  const cur = epicOf(d, rfm);
+  if (cur.locked) return { ok: false, status: 409, error: `the epic is set (${cur.key || 'created at the first push'}) — tickets are already under it` };
+  if (mode === 'new') { d.fm.epic_mode = 'new'; delete d.fm.epic; }
+  else if (mode === 'existing') {
+    const m = KEY_IN.exec(String(key || '').toUpperCase());
+    if (!m) return { ok: false, status: 400, error: 'paste the epic\'s Jira link or key, such as ATL-482' };
+    d.fm.epic_mode = 'existing'; d.fm.epic = m[1];
+  } else return { ok: false, status: 400, error: 'say new or existing' };
+  writeDraft(root, initiative, d, { now, prd: prdOf(rfm) });
+  return { ok: true, initiative, epic: epicOf(d, rfm) };
+}
+
+// ── J6 · approve the selected tickets (the caller checked it is the PM) ────────────────────────────
+function approve(root, initiative, ids, { now } = {}) {
+  const { d, error } = mustDraft(root, initiative);
+  if (error) return { ok: false, status: 404, error };
+  const want = [...new Set((ids || []).map(String))];
+  if (!want.length) return { ok: false, status: 400, error: 'select at least one ticket' };
+  const st = items(root, initiative);
+  const inPrd = new Set(st.ok ? st.items.map((x) => x.id) : []);
+  const refused = [];
+  for (const id of want) {
+    const t = d.tickets.find((x) => x.id === id);
+    if (!t) { refused.push(`${id}: no such ticket`); continue; }
+    const miss = missingOf(t);
+    if (miss.length) { refused.push(`${id}: missing ${miss.join(', ')}`); continue; }
+    if (st.ok && !inPrd.has(id)) { refused.push(`${id}: no longer in the PRD`); continue; }
+    if (t.jira && t.pushed === contentHash(t)) refused.push(`${id}: already in Jira as ${t.jira}, unchanged`);
+  }
+  if (refused.length) return { ok: false, status: 409, error: `nothing was approved — ${refused.join('; ')}` };
+  const rfm = recordFm(root, initiative) || {};
+  const ep = epicOf(d, rfm);
+  if (ep.mode === 'existing' && !ep.key) return { ok: false, status: 409, error: 'choose the epic first: paste the existing epic\'s link, or choose Create new epic' };
+  if (!d.fm.epic_mode) d.fm.epic_mode = ep.mode;
+  if (ep.key && !d.fm.epic) d.fm.epic = ep.key;
+  for (const id of want) { const t = d.tickets.find((x) => x.id === id); t.approved = contentHash(t); }
+  writeDraft(root, initiative, d, { now, prd: prdOf(rfm) });
+  return { ok: true, initiative, approved: want, epic: epicOf(d, rfm) };
+}
+
+// ── J7 · the push plan ─────────────────────────────────────────────────────────────────────────────
+function describe(t) {
+  const head = [`Type: ${t.type}`, `Priority: ${t.priority}`, `Estimate: ${t.estimate || '—'}`, `Depends on: ${t.depends.length ? t.depends.join(', ') : '—'}`].join(' · ');
+  const out = [head, ''];
+  for (const [k, name] of SECTIONS) out.push(`## ${name}`, '', norm(t.sections[k]) || '—', '');
+  out.push('Drafted in PMOS, which owns this text. Edit it there: the next push replaces it here.');
+  return out.join('\n').trim();
+}
+function pushPlan(root, initiative) {
+  const rfm = recordFm(root, initiative);
+  if (!rfm) return { ok: false, error: `no initiative ${initiative} in this repository` };
+  const { d, error } = mustDraft(root, initiative);
+  if (error) return { ok: false, status: 409, error };
+  const ep = epicOf(d, rfm);
+  const title = isStr(rfm.title) ? rfm.title : initiative;
+  const labels = ['pmos', `pmos-${initiative}`.slice(0, 60)];
+  const keyOf = new Map(d.tickets.filter((t) => t.jira).map((t) => [t.id, t.jira]));
+  const create = []; const update = []; let notApproved = 0; let unchanged = 0;
+  for (const t of d.tickets) {
+    const h = contentHash(t);
+    if (t.jira && t.pushed === h) { unchanged++; continue; }
+    if (t.approved !== h) { notApproved++; continue; }
+    const fields = {
+      summary: clip(oneLine(t.summary), MAX_SUMMARY), description: describe(t), issuetype: t.type, priority: t.priority, labels,
+      blocked_by: t.depends.map((dep) => ({ ticket: dep, key: keyOf.get(dep) || null })),
+    };
+    if (!t.jira) create.push({ ticket: t.id, hash: h, ...fields });
+    else update.push({ ticket: t.id, key: t.jira, hash: h, ...fields });
+  }
+  return {
+    ok: true, initiative, draft: draftRel(root, initiative),
+    epic: ep.key ? { key: ep.key, mode: ep.mode } : { key: null, mode: 'new', create: { summary: clip(oneLine(title), MAX_SUMMARY), issuetype: 'Epic', labels,
+      description: `PMOS initiative ${initiative}.${prdOf(rfm) ? ` Spec: ${prdOf(rfm)}.` : ''} The tickets under this epic are drafted in PMOS, which owns their text.` } },
+    create, update, notApproved, unchanged,
+  };
+}
+
+// ── J9 · record what was pushed ──────────────────────────────────────────────────────────────────────
+/**
+ * @param {{epic?: string, tickets?: Object<string,string>, pushed?: string[]}} keys
+ *   tickets: ticket id → the Jira key the agent created; pushed: ticket ids the agent updated in Jira.
+ */
+function record(root, initiative, keys, { now } = {}) {
+  const { d, error } = mustDraft(root, initiative);
+  if (error) return { ok: false, status: 404, error };
+  const byId = new Map(d.tickets.map((t) => [t.id, t]));
+  const rfm = recordFm(root, initiative) || {};
+  if (keys.epic) {
+    if (!KEY_RE.test(keys.epic)) return { ok: false, error: `epic ${JSON.stringify(keys.epic)} is not a Jira key like ATL-482` };
+    const ep = epicOf(d, rfm);
+    if (ep.key && ep.key !== keys.epic.toUpperCase()) return { ok: false, error: `the epic is already ${ep.key}` };
+    d.fm.epic = keys.epic.toUpperCase();
+    if (!d.fm.epic_mode) d.fm.epic_mode = ep.mode;
+  }
+  const done = [];
+  const taken = new Map(d.tickets.filter((t) => t.jira).map((t) => [t.jira, t.id]));
+  const approvedNow = (t) => t.approved === contentHash(t);
+  for (const [id, key] of Object.entries(keys.tickets || {})) {
+    const t = byId.get(id);
+    if (!t) return { ok: false, error: `no ticket ${id} in the draft` };
+    if (!approvedNow(t)) return { ok: false, status: 409, error: `${id} is not approved as it stands — nothing is recorded for content the PM has not selected` };
+    if (!KEY_RE.test(key)) return { ok: false, error: `${id}: ${JSON.stringify(key)} is not a Jira key like ATL-491` };
+    const k = key.toUpperCase();
+    if (t.jira && t.jira !== k) return { ok: false, error: `${id} is already ${t.jira} — a ticket is created once` };
+    if (taken.has(k) && taken.get(k) !== id) return { ok: false, error: `${k} is already ${taken.get(k)}` };
+    t.jira = k; t.pushed = contentHash(t); taken.set(k, id); done.push({ ticket: id, key: k, what: 'created' });
+  }
+  for (const id of keys.pushed || []) {
+    const t = byId.get(id);
+    if (!t) return { ok: false, error: `no ticket ${id} in the draft` };
+    if (!t.jira) return { ok: false, error: `${id} has no Jira key yet — record the key it was created as` };
+    if (!approvedNow(t)) return { ok: false, status: 409, error: `${id} is not approved as it stands — nothing is recorded for content the PM has not selected` };
+    t.pushed = contentHash(t); done.push({ ticket: id, key: t.jira, what: 'updated' });
+  }
+  writeDraft(root, initiative, d, { now, prd: prdOf(rfm) });
+  return { ok: true, initiative, epic: d.fm.epic || null, recorded: done };
+}
+
+/** The tickets of one initiative that are in Jira: key → { id, summary }. And the epic. */
+function pushedTickets(root, initiative) {
+  const d = readDraft(root, initiative);
+  if (!d) return { epic: null, tickets: new Map() };
+  const tickets = new Map();
+  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 };
+}
+/** Every initiative with a ticket draft in this repository. */
+function draftedInitiatives(root) {
+  let names = [];
+  try { names = fs.readdirSync(jiraDir(root)).filter((n) => n.endsWith('-tickets.md')); } catch { return []; }
+  return names.map((n) => n.slice(0, -'-tickets.md'.length)).filter((id) => planItems.INIT_RE.test(id)).sort();
+}
+
+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,
+  draftPath, draftRel, jiraDir, relOf, recordFm, prdOf,
+};