create-pmos 0.57.1 → 0.58.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-pmos",
-  "version": "0.57.1",
+  "version": "0.58.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@fd17645
+kernel-source: pmos@e8fcb2a
 assembled: 2026-10-06
 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-06T11:33:15Z"}
+generated: {by: process:create-pmos, at: "2026-10-06T11:54:59Z"}
 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-06T11:33:15Z"}
+generated: {by: process:create-pmos, at: "2026-10-06T11:54:59Z"}
 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-06T11:33:15Z"}
+generated: {by: process:create-pmos, at: "2026-10-06T11:54:59Z"}
 status: stable
 ---
 

package/workspace/guide/index.md

@@ -36,6 +36,7 @@ On a desktop the workspace is one frame. [Layout](layout.md) explains each part.
 ## Where to read next
 
 - [Start the workspace without a terminal](launcher.md): the PMOS app, the login item and `pmos launcher`.
+- [Jira tickets](jira.md): Jira tickets drafted from the PRD, pushed when you select them, and their status.
 - [Docs](docs.md): whether each linked document is the same as, ahead of or behind its Google Docs and Confluence copy.
 - [Layout](layout.md): the frame, the keys and the rule for where a list or a detail opens.
 - [Statuses](statuses.md): what each status means, where it comes from, and what you can change.

package/workspace/guide/jira.md

@@ -0,0 +1,141 @@
+---
+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-06
+---
+
+# Jira: tickets drafted from the PRD, and their status
+
+Your team works in Jira. You plan in PMOS. This page shows how the two stay in step without a second Jira:
+
+1. PMOS drafts one Jira ticket for each ticket item of the PRD, in your ticket template.
+2. You read the tickets, edit them if needed, and select the ones that are ready.
+3. An agent creates the selected tickets in Jira, with your own Atlassian connection.
+4. Each day, an agent reads their status back. The initiative's **Jira tickets** tab shows it.
+
+PMOS owns the text of a ticket. Jira owns its status. PMOS holds no Jira password or token: your agent session reads and writes Jira with the connection you set up in it.
+
+## Where it is
+
+Open an initiative. Its sheet has four tabs: Breakdown, Files, History and **Jira tickets**.
+
+In a document repository whose lane has a Handoff stage, the Jira tickets tab opens when the handoff is done. Mark the Handoff item done in the Breakdown, or record `handed_off:` in the initiative. In other repositories the tab is open as soon as the PRD has ticket items.
+
+## Write the ticket items in the PRD
+
+PMOS reads a section headed **User stories**, **Stories**, **Tickets**, **Jira tickets** or **Work items**. Each ticket is a subheading with an ID:
+
+```markdown
+## Tickets
+
+### TD-01 · Carry the real runtime version on every GA4 event
+Type: Task · Priority: High · Estimate: S · Depends on: —
+
+As a PM, I want every GA4 event to carry the runtime version, so that I can compare releases.
+
+#### Additional Context
+#### User Flow
+#### Functional Requirements
+1. …
+#### Terminal States
+#### Acceptance Criteria
+- Given …, when …, then …
+#### Refs
+- [Tagging plan](https://example.com/plan)
+```
+
+- Keep the ID (`TD-01`) stable. PMOS matches a ticket to its item by ID.
+- The `Type · Priority · Estimate · Depends on` line is optional. The defaults are Task, Medium, no estimate and no dependency.
+- Text before the first subsection is the User Story when it starts "As a …".
+- A bullet such as `- **S1 · Pay with a saved card.** As a …` also works.
+
+## Draft, read and edit
+
+Press **Draft tickets**, or run:
+
+```
+pmos jira draft <initiative>
+```
+
+The draft is a file, `<state>/tracker/jira/<initiative>-tickets.md`. Every row of the tab opens a ticket: its fields, its full text and its status in Jira. **Edit text** changes the summary and the sections. Type, Priority, Estimate and Depends on are lists.
+
+A ticket needs a User Story, Functional Requirements and Acceptance Criteria before it can be pushed. A ticket without them shows **Missing text**.
+
+To see every ticket in the terminal:
+
+```
+pmos jira show <initiative>
+```
+
+## Choose the epic
+
+Above the list, choose **Create new** (an epic named after the initiative, made at the first push) or **Use an existing epic** and paste its link or key. After the first push the epic is fixed. In the terminal:
+
+```
+pmos jira epic <initiative> new
+pmos jira epic <initiative> ATL-482
+```
+
+## Push the tickets that are ready
+
+Check the tickets that are ready and press **Push N to Jira**. Only checked tickets are sent. An agent session starts and creates them under the epic. A ticket you edit after you checked it must be checked again.
+
+In your own terminal, the same selection is:
+
+```
+pmos jira approve <initiative> TD-01 TD-02
+```
+
+It asks you to type the initiative's id. An agent session cannot select tickets.
+
+The agent runs the **Push to Jira** skill. It reads what to send with `pmos jira pending <initiative>`, and records each key with `pmos jira record <initiative> TD-01=ATL-491`. It never moves, assigns, comments on, closes or deletes a Jira issue.
+
+## Status, sprint and progress
+
+Each row shows the ticket's status in Jira, and whether it is in the **Active sprint**, the **Next sprint** or the **Backlog**, with its subtasks done. A blocked ticket shows **Blocked** and the reason.
+
+The **Jira status check** reads this for every initiative. **Check now** on the tab reads it for one. To run it every day before the morning brief (06:45), schedule it at 06:30:
+
+```
+pmos schedule add --skill jira-sync --cadence daily --time 06:30
+```
+
+The check reads Jira only. It writes `<state>/tracker/jira/<initiative>.md` with:
+
+```
+pmos jira query [<initiative>]
+pmos jira sync <initiative> --from <file|-> [--query "<jql>"] [--dry-run]
+```
+
+## When the PRD changes
+
+Each time the tab opens, PMOS compares every ticket with its item in the PRD:
+
+- **PRD changed**: the item changed since the ticket was drafted. Open the ticket to see both versions, then press **Use the PRD version** or **Keep the ticket as it is**. A ticket that is in Jira then shows **Edited, not in Jira yet** until you push it again.
+- **New in PRD**: an item has no ticket yet. Press **Add to tickets**.
+- **Removed from PRD**: the item is gone. The Jira ticket is not changed.
+
+A ticket you did not edit and did not push is redrafted at the next **Draft tickets**.
+
+## Which initiative is this Jira key?
+
+```
+pmos jira which ATL-491
+```
+
+The morning brief, the day check and requirement gathering use it to tie a Jira issue to its initiative.
+
+## Every command
+
+- `pmos jira draft <initiative> [--dry-run]`
+- `pmos jira show <initiative>`
+- `pmos jira epic <initiative> new|<KEY or link>`
+- `pmos jira approve <initiative> <ID> …`
+- `pmos jira pending <initiative>`
+- `pmos jira record <initiative> [ID=KEY …] [--epic KEY] [--updated ID,ID]`
+- `pmos jira query [<initiative>]`
+- `pmos jira sync <initiative> --from <file|-> [--query "<jql>"] [--dry-run]`
+- `pmos jira which <KEY>`
+
+Every command takes `--json` and `--root <dir>`.

package/workspace/lib/jira-cli.js

@@ -0,0 +1,194 @@
+'use strict';
+/* jira-cli.js — `pmos jira …`: Jira tickets drafted from the PRD, pushed by the PM's selection, and their status
+ * (initiative jira-wbs).
+ *
+ *   pmos jira draft <initiative> [--dry-run]                    the PRD's items → the ticket draft (lib/jira-tickets.js)
+ *   pmos jira show <initiative>                                 every ticket, its flags and its status in Jira
+ *   pmos jira epic <initiative> new|<KEY or link>               create a new epic, or use an existing one
+ *   pmos jira approve <initiative> <ID> …                       the PM selects tickets to push, in their own terminal
+ *   pmos jira pending <initiative>                              what the agent creates or updates in Jira (approved only)
+ *   pmos jira record <initiative> [ID=KEY …] [--epic KEY] [--updated ID,ID]   the keys the agent created
+ *   pmos jira query [<initiative>]                              the Jira search for the tickets an initiative pushed
+ *   pmos jira sync <initiative> --from <file|-> [--query "<jql>"] [--dry-run]  a saved search → the status snapshot
+ *   pmos jira which <KEY>                                       the initiative a Jira key belongs to
+ *   every command: [--json] [--root <dir>]
+ *
+ * This command never talks to Jira. An agent session does, with the PM's own Atlassian connection (D53, D88), and
+ * hands the result to `sync` or `record`. `approve` is PM-only (pm-guard act `push`): an agent session is refused.
+ */
+const fs = require('fs');
+const path = require('path');
+const { execFileSync } = require('child_process');
+const { parseArgs } = require('./schedule-cli');
+const jiraStatus = require('./jira-status.js');
+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 USAGE = [
+  'usage: pmos jira draft|show|epic|approve|pending|record|query|sync|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',
+  '  pmos jira approve <initiative> <ID> …              select tickets to push (you, in your own terminal)',
+  '  pmos jira pending <initiative>                     what the push creates or updates in Jira',
+  '  pmos jira record <initiative> [ID=KEY …] [--epic KEY] [--updated ID,ID]   the keys created in Jira',
+  '  pmos jira query [<initiative>]                     the Jira search for the pushed tickets',
+  '  pmos jira sync <initiative> --from <file|-> [--query "<jql>"] [--dry-run]   save the status read from Jira',
+  '  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.',
+];
+const BOOL = new Set(['json', 'dry-run', 'help']);
+const VALUE = new Set(['from', 'query', 'root', 'epic', 'updated']);
+const FLAG_TEXT = { 'prd-changed': 'PRD changed', removed: 'Removed from PRD', blocked: 'Blocked', incomplete: 'Missing text', pushing: 'Selected, waiting for the push', edited: 'Edited, not in Jira yet' };
+
+function parse(argv) {
+  const rest = []; const bools = {};
+  for (const a of argv) {
+    if (a.startsWith('--') && BOOL.has(a.slice(2))) bools[a.slice(2)] = true;
+    else if (a === '-h') bools.help = true;
+    else rest.push(a);
+  }
+  const { pos, flags } = parseArgs(rest);
+  return { pos, flags: { ...flags, ...bools } };
+}
+function repoRoot(cwd) {
+  try { return execFileSync('git', ['rev-parse', '--show-toplevel'], { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim() || cwd; }
+  catch { return cwd; }
+}
+function readInput(from, cwd, stdin) {
+  if (from === '-') return stdin != null ? stdin : fs.readFileSync(0, 'utf8');
+  return fs.readFileSync(path.resolve(cwd, from), 'utf8');
+}
+function statusLine(t) {
+  if (!t.inJira) return 'not in Jira';
+  if (!t.jira) return `${t.key} · not checked yet`;
+  const j = t.jira;
+  const where = j.category === 'done' ? 'Done' : jiraStatus.sprintLabel(j.sprint);
+  return `${t.key} · ${j.status} · ${where}${j.subtasks && j.subtasks.total ? ` · subtasks ${j.subtasks.done} of ${j.subtasks.total}` : ''}${j.stale ? ' · not in the last read' : ''}`;
+}
+
+async function run(argv, { say = (s) => console.log(s), cwd = process.cwd(), isTTY, env, now, stdin, ask } = {}) {
+  const args = argv[0] === 'jira' ? argv.slice(1) : argv.slice();
+  const verb = args[0];
+  const { pos, flags } = parse(args.slice(1));
+  const json = !!flags.json;
+  if (!verb || verb === 'help' || verb === '--help' || verb === '-h' || flags.help) {
+    for (const l of USAGE) say(l);
+    return verb ? 0 : 1;
+  }
+  if (!COMMANDS.jira.includes(verb)) { say(`unknown jira command "${verb}" — one of ${COMMANDS.jira.join(', ')}`); return 2; }
+  for (const k of Object.keys(flags)) {
+    if (!BOOL.has(k) && !VALUE.has(k)) { say(`unknown option --${k}`); return 2; }
+    if (VALUE.has(k) && flags[k] === '') { say(`--${k} needs a value`); return 2; }
+  }
+  const root = flags.root ? path.resolve(cwd, flags.root) : repoRoot(cwd);
+  const fail = (error, code = 1) => { if (json) say(JSON.stringify({ ok: false, error })); else say(`✗ ${error}`); return code; };
+  const out = (r, lines) => { if (json) say(JSON.stringify(r)); else for (const l of lines) say(l); return 0; };
+  const need = (what) => { say(`usage: pmos jira ${verb} ${what}`); return 2; };
+  const initiative = pos[0];
+  const known = () => planItems.INIT_RE.test(initiative || '') && !!jiraTickets.recordFm(root, initiative);
+
+  try {
+    if (verb === 'query') {
+      if (initiative) {
+        const q = jiraStatus.queryFor(root, initiative);
+        if (!q.ok) return fail(q.error);
+        if (!q.linked) return fail(`${initiative} has no ticket in Jira yet — push its tickets first`);
+        return out(q, [q.query]);
+      }
+      const all = jiraStatus.linkedInitiatives(root).filter((x) => x.linked);
+      return out({ ok: true, initiatives: all }, all.length ? all.map((x) => `${x.initiative}\t${x.query}`) : ['no initiative has a ticket in Jira yet']);
+    }
+    if (verb === 'which') {
+      if (!initiative) return need('<KEY>');
+      const r = jiraStatus.which(root, initiative);
+      if (!r.ok) return fail(r.error);
+      return out(r, r.initiatives.length ? r.initiatives.map((h) => `${r.key} → ${h.initiative} · ${h.role}${h.ticket ? ` ${h.ticket} · ${h.summary}` : ''}`) : [`${r.key} belongs to no initiative in this repository`]);
+    }
+    if (!initiative) return need('<initiative> …');
+    if (!known()) return fail(`no initiative ${initiative} in this repository`);
+
+    if (verb === 'draft') {
+      const r = jiraTickets.draft(root, initiative, { dryRun: !!flags['dry-run'], now });
+      if (!r.ok) return fail(r.error);
+      const lines = [`${initiative} · ${r.tickets} ${r.tickets === 1 ? 'ticket' : 'tickets'} in ${r.draft}${r.changed ? '' : ' · no change'}${flags['dry-run'] ? ' · dry run, nothing written' : ''}`];
+      for (const c of r.changes) lines.push(`  ${c.what.padEnd(9)} ${c.ticket} · ${c.summary}${c.why ? ` (${c.why})` : ''}`);
+      lines.push('Read them on the Jira tickets tab, or with pmos jira show. Select the ready ones there, or with pmos jira approve.');
+      return out(r, lines);
+    }
+    if (verb === 'show') {
+      const r = jiraTickets.view(root, initiative, { snapshot: jiraStatus.readSnapshot(root, initiative) });
+      if (!r.ok) return fail(r.error);
+      const lines = [`${initiative} · ${r.inJira} of ${r.tickets.length} in Jira · ${r.checkedAt ? `checked ${r.checkedAt}` : 'not checked yet'} · epic ${r.epic.key || (r.epic.mode === 'new' ? 'new, created at the first push' : 'not chosen')}`];
+      if (!r.gate.open) lines.push(`  The Jira tickets tab opens when the handoff is done (${r.gate.why}).`);
+      for (const t of r.tickets) {
+        lines.push(`  ${t.id} · ${t.summary} · ${[t.type, t.priority, t.estimate].filter(Boolean).join(' · ')}`);
+        lines.push(`      ${statusLine(t)}${t.flag ? ` · ${FLAG_TEXT[t.flag]}${t.flag === 'incomplete' ? `: ${t.missing.join(', ')}` : t.flag === 'blocked' && t.jira.reason ? `: ${t.jira.reason}` : ''}` : ''}`);
+      }
+      for (const n of r.newInPrd) lines.push(`  ${n.id} · ${n.summary} · New in PRD: run pmos jira draft ${initiative}`);
+      if (!r.drafted) lines.push(`  No draft yet: pmos jira draft ${initiative}`);
+      return out(r, lines);
+    }
+    if (verb === 'epic') {
+      const v = pos[1];
+      if (!v) return need('<initiative> new|<KEY or link>');
+      const r = jiraTickets.setEpic(root, initiative, v === 'new' ? { mode: 'new' } : { mode: 'existing', key: v }, { now });
+      if (!r.ok) return fail(r.error);
+      return out(r, [r.epic.mode === 'new' ? `${initiative} · a new epic is created at the first push` : `${initiative} · tickets go under ${r.epic.key}`]);
+    }
+    if (verb === 'approve') {
+      const ids = pos.slice(1);
+      if (!ids.length) return need('<initiative> <ID> …');
+      const g = await guard.requirePmCli({ act: 'push', expect: initiative,
+        ...(isTTY === undefined ? {} : { isTTY }), ...(env === undefined ? {} : { env }), ask: ask || guard.askAtTerminal });
+      if (!g.ok) return fail(g.error);
+      const r = jiraTickets.approve(root, initiative, ids, { now });
+      if (!r.ok) return fail(r.error);
+      return out(r, [`selected ${r.approved.join(', ')} for ${initiative}. Your agent can push them now: run the Push to Jira skill, or press Push on the tab.`]);
+    }
+    if (verb === 'pending') {
+      const r = jiraTickets.pushPlan(root, initiative);
+      if (!r.ok) return fail(r.error);
+      const lines = [`${initiative} · ${r.create.length} to create · ${r.update.length} to update · ${r.unchanged} unchanged · ${r.notApproved} not selected`];
+      lines.push(r.epic.key ? `  epic     ${r.epic.key}` : `  epic     create "${r.epic.create.summary}"`);
+      for (const t of r.create) lines.push(`  create   ${t.ticket} · ${t.summary} · ${t.issuetype} · ${t.priority}`);
+      for (const t of r.update) lines.push(`  update   ${t.ticket} ${t.key} · ${t.summary}`);
+      return out(r, lines);
+    }
+    if (verb === 'record') {
+      const tickets = {};
+      for (const p of pos.slice(1)) {
+        const m = /^([A-Za-z0-9][\w.-]{0,40})=(.+)$/.exec(p);
+        if (!m) return fail(`"${p}" is not <ID>=<KEY>`, 2);
+        tickets[m[1]] = m[2];
+      }
+      const updated = flags.updated ? String(flags.updated).split(',').map((s) => s.trim()).filter(Boolean) : [];
+      if (!Object.keys(tickets).length && !updated.length && !flags.epic) return need('<initiative> [ID=KEY …] [--epic KEY] [--updated ID,ID]');
+      const r = jiraTickets.record(root, initiative, { epic: flags.epic || null, tickets, pushed: updated }, { now });
+      if (!r.ok) return fail(r.error);
+      return out(r, [`${initiative}${r.epic ? ` · epic ${r.epic}` : ''} · recorded ${r.recorded.length}`, ...r.recorded.map((x) => `  ${x.what} ${x.ticket} ${x.key}`)]);
+    }
+    if (verb === 'sync') {
+      if (!flags.from) return need('<initiative> --from <file|->');
+      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.sync(root, initiative, raw, { query: flags.query || undefined, dryRun: !!flags['dry-run'], now });
+      if (!r.ok) return fail(r.error);
+      const lines = [`${initiative} · read ${r.read} ${r.read === 1 ? 'ticket' : 'tickets'}${r.ignored ? ` · ${r.ignored} other issues ignored` : ''}${r.skipped ? ` · ${r.skipped} skipped (no key or summary)` : ''}${r.dryRun ? ' · dry run, nothing written' : ''}`];
+      for (const c of r.changes) lines.push(`  ${c.key} · ${c.what}${c.from !== undefined ? `: ${c.from} → ${c.to}` : c.status ? `: ${c.status}` : ''}${c.reason ? ` (${c.reason})` : ''}`);
+      if (!r.changes.length) lines.push('  no change');
+      for (const k of r.missing) lines.push(`  ${k} · not in this read; its last status is kept`);
+      if (!r.dryRun) lines.push(`snapshot ${r.snapshot}`);
+      return out(r, lines);
+    }
+  } catch (e) {
+    return fail(String((e && e.message) || e).slice(0, 200));
+  }
+  return 2;
+}
+
+module.exports = { run, COMMANDS, USAGE };

package/workspace/lib/jira-status.js

@@ -0,0 +1,239 @@
+'use strict';
+/* jira-status.js — the status of the Jira tickets PMOS pushed, read back read-only (initiative jira-wbs, PRD J11, J13).
+ *
+ * THE READ PATH. An agent session reads Jira read-only with the PM's own Atlassian connection (D53: PMOS holds no
+ * tracker credential; D71: an agent skill reads a source, the server does not) and saves the search result to a file.
+ * 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
+ *   linkedInitiatives(root)             → [{ initiative, query }]
+ *   normalize(raw)                      → { issues, skipped } | { error }
+ *   sync(root, initiative, raw, opts)   → the snapshot, written to <state>/tracker/jira/<initiative>.md
+ *   readSnapshot(root, initiative)      → { fetchedAt, query, tickets: Map<key, reading> } | null
+ *   which(root, key)                    → the initiative and ticket a key belongs to
+ *
+ * A READING is { key, summary, status, category: todo|doing|done, sprint: { name, state: active|future|closed } | null,
+ * subtasks: { done, total }, flagged, reason, url }. 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.
+ *
+ * BOUNDARY (J15). No network module, no child process. The only write is the snapshot file.
+ */
+const fs = require('fs');
+const path = require('path');
+const jiraTickets = require('./jira-tickets.js');
+
+const KEY_RE = /^[A-Za-z][A-Za-z0-9_]*-\d+$/;
+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 nowIso = (now) => new Date(now == null ? Date.now() : now).toISOString().replace(/\.\d{3}Z$/, 'Z');
+
+// ── the query ──────────────────────────────────────────────────────────────────────────────────────
+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` };
+}
+function linkedInitiatives(root) {
+  return jiraTickets.draftedInitiatives(root).map((id) => queryFor(root, id)).filter((q) => q.ok);
+}
+
+// ── reading a saved search result ──────────────────────────────────────────────────────────────────
+function issuesList(raw) {
+  if (Array.isArray(raw)) return raw;
+  if (!raw || typeof raw !== 'object') return null;
+  if (Array.isArray(raw.issues)) return raw.issues;
+  if (raw.issues && Array.isArray(raw.issues.nodes)) return raw.issues.nodes;
+  if (Array.isArray(raw.values)) return raw.values;
+  if (raw.data && typeof raw.data === 'object') return issuesList(raw.data);
+  return null;
+}
+const nameOf = (v) => (v && typeof v === 'object' ? oneLine(v.name || v.value || '') : oneLine(v));
+function categoryOf(status, cat) {
+  const key = String((cat && typeof cat === 'object' ? (cat.key || cat.name) : cat) || '').toLowerCase();
+  if (key === 'done' || key === 'complete') return 'done';
+  if (key === 'indeterminate' || key === 'in progress' || key === 'doing') return 'doing';
+  if (key === 'new' || key === 'to do' || key === 'todo') return 'todo';
+  const s = String(status || '').toLowerCase();
+  if (/done|closed|resolved|released|complete|shipped|deployed/.test(s)) return 'done';
+  if (/progress|doing|started|review|\bqa\b|test|verif|\buat\b|block/.test(s)) return 'doing';
+  return 'todo';
+}
+/** Jira's Flagged field is a custom field whose id differs per site: any field holding the value "Impediment". */
+function flaggedIn(fields) {
+  if (fields.flagged === true) return true;
+  for (const v of Object.values(fields)) {
+    if (Array.isArray(v) && v.some((x) => x && typeof x === 'object' && /impediment/i.test(String(x.value || '')))) return true;
+  }
+  return false;
+}
+const SPRINT_STATES = ['active', 'future', 'closed'];
+/** One sprint, from an object { name, state } or a bare name. */
+function sprintOne(v) {
+  if (!v) return null;
+  if (isStr(v)) { const name = clip(oneLine(v), 80); return name ? { name, state: 'active' } : null; }
+  if (typeof v !== 'object') return null;
+  const name = clip(oneLine(v.name), 80);
+  const state = String(v.state || '').toLowerCase();
+  if (!name) return null;
+  return { name, state: SPRINT_STATES.includes(state) ? state : 'active' };
+}
+/** The sprint that matters: the active one, else the next, else the last closed. null is the backlog. */
+function sprintOf(v) {
+  const all = (Array.isArray(v) ? v : [v]).map(sprintOne).filter(Boolean);
+  return all.find((s) => s.state === 'active') || all.find((s) => s.state === 'future') || all[all.length - 1] || null;
+}
+/** Jira Cloud keeps the sprint in a custom field: any array of objects that carry a sprint's name and state. */
+function sprintIn(fields) {
+  if ('sprint' in fields) return sprintOf(fields.sprint);
+  for (const v of Object.values(fields)) {
+    if (Array.isArray(v) && v.length && v.every((x) => x && typeof x === 'object' && 'name' in x && 'state' in x && ('boardId' in x || 'id' in x))) return sprintOf(v);
+  }
+  return null;
+}
+function subtasksOf(v) {
+  if (Array.isArray(v)) {
+    const done = v.filter((s) => {
+      const st = s && (s.fields ? s.fields.status : s.status);
+      return categoryOf(nameOf(st), st && typeof st === 'object' ? st.statusCategory : (s && s.category)) === 'done';
+    }).length;
+    return { done, total: v.length };
+  }
+  if (v && typeof v === 'object' && Number.isInteger(v.total) && v.total >= 0) {
+    const done = Number.isInteger(v.done) ? Math.max(0, Math.min(v.done, v.total)) : 0;
+    return { done, total: v.total };
+  }
+  return { done: 0, total: 0 };
+}
+/** https://site.atlassian.net/rest/api/3/issue/10001 → https://site.atlassian.net/browse/KEY */
+function urlOf(x, key) {
+  const raw = isStr(x.url) ? x.url : isStr(x.self) ? x.self : '';
+  let u;
+  try { u = new URL(raw); } catch { return null; }
+  if (u.protocol !== 'https:') return null;
+  if (/\/browse\//.test(u.pathname)) return u.origin + u.pathname;
+  return `${u.origin}/browse/${key}`;
+}
+/** One issue of either shape → a reading, or null when it has no key or no summary. */
+function normalizeIssue(x) {
+  if (!x || typeof x !== 'object') return null;
+  const key = oneLine(x.key).toUpperCase();
+  if (!KEY_RE.test(key)) return null;
+  if (x.fields && typeof x.fields === 'object') {
+    const f = x.fields;
+    const summary = clip(oneLine(f.summary), 250);
+    if (!summary) return null;
+    const st = f.status || {};
+    const status = nameOf(st) || 'Unknown';
+    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),
+      flagged, reason: flagged ? (flaggedIn(f) ? 'Flagged in Jira' : `Status: ${status}`) : null, url: urlOf(x, key) };
+  }
+  // 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);
+  if (!summary) return null;
+  const status = oneLine(x.status) || 'Unknown';
+  const flagged = x.flagged === true || /block|impediment|on hold/i.test(status);
+  return { key, summary, status, category: categoryOf(status, x.category), sprint: sprintOf(x.sprint), subtasks: subtasksOf(x.subtasks),
+    flagged, reason: flagged ? clip(oneLine(x.reason || x.flag_reason || (x.flagged === true ? 'Flagged in Jira' : `Status: ${status}`)), 160) : null,
+    url: urlOf(x, key) };
+}
+function normalize(raw) {
+  const list = issuesList(raw);
+  if (!list) return { error: 'the file holds no list of Jira issues (expected "issues": [...], "issues": {"nodes": [...]} or a list)' };
+  const issues = []; const seen = new Set(); let skipped = 0;
+  for (const x of list) {
+    const n = normalizeIssue(x);
+    if (!n || seen.has(n.key)) { skipped++; continue; }
+    seen.add(n.key);
+    issues.push(n);
+  }
+  return { issues, skipped };
+}
+
+// ── the snapshot ───────────────────────────────────────────────────────────────────────────────────
+function snapshotPath(root, initiative) { return path.join(jiraTickets.jiraDir(root), `${initiative}.md`); }
+function snapshotRel(root, initiative) { return jiraTickets.relOf(root, snapshotPath(root, initiative)); }
+const cell = (s) => oneLine(s).replace(/\\/g, '\\\\').replace(/\|/g, '\\|') || '—';
+const SPRINT_WORD = { active: 'Active sprint', future: 'Next sprint', closed: 'Closed sprint' };
+function sprintLabel(s) { return s ? `${SPRINT_WORD[s.state] || 'Sprint'}: ${s.name}` : 'Backlog'; }
+function renderSnapshot({ initiative, fetchedAt, query, readings, ids }) {
+  const rows = readings.map((r) => `| ${cell(ids.get(r.key) || '')} | ${cell(r.key)} | ${cell(r.summary)} | ${cell(r.status)} | ${cell(r.category === 'done' ? 'Done' : sprintLabel(r.sprint))} | ${r.subtasks.total ? `${r.subtasks.done} of ${r.subtasks.total}` : '—'} | ${cell(r.flagged ? r.reason : '')} |${r.stale ? ' not in the last read |' : ''}`);
+  return [
+    '---', 'type: Reference', `title: "Jira status: ${initiative}"`, `timestamp: ${fetchedAt}`, `initiative: ${initiative}`, '---', '',
+    `# Jira status: ${initiative}`, '',
+    `Read from Jira at ${fetchedAt} by the Jira status check, read-only. The Jira tickets tab of the initiative shows it. Written by \`pmos jira sync\`; do not edit by hand.`, '',
+    query ? `Search: \`${query.replace(/`/g, "'")}\`` : 'Search: not recorded', '',
+    '| Ticket | Key | Summary | Status | Sprint | Subtasks | Blocked |', '|---|---|---|---|---|---|---|', ...rows, '',
+    '```json', JSON.stringify({ fetched_at: fetchedAt, query: query || null, tickets: readings }, null, 0), '```', '',
+  ].join('\n');
+}
+function readSnapshot(root, initiative) {
+  let text;
+  try { text = fs.readFileSync(snapshotPath(root, initiative), '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 tickets = new Map();
+  for (const r of Array.isArray(data.tickets) ? data.tickets : []) if (r && KEY_RE.test(String(r.key || ''))) tickets.set(r.key, r);
+  return { fetchedAt: isStr(data.fetched_at) ? data.fetched_at : null, query: isStr(data.query) ? data.query : null, tickets };
+}
+
+/**
+ * Write the snapshot from a saved search result. Only the tickets this initiative pushed are kept; any other issue in
+ * the result is counted and ignored. A pushed ticket missing from the result keeps its last reading, marked stale.
+ */
+function sync(root, initiative, raw, { query, dryRun = false, now } = {}) {
+  if (!jiraTickets.recordFm(root, initiative)) return { ok: false, error: `no initiative ${initiative} in this repository` };
+  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 prev = readSnapshot(root, initiative);
+  const got = new Map(n.issues.filter((i) => pushed.has(i.key)).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 r = got.get(key);
+    const was = prev ? prev.tickets.get(key) : null;
+    if (!r) {
+      missing.push(key);
+      if (was) readings.push({ ...was, stale: true });
+      continue;
+    }
+    readings.push(r);
+    if (!was) { changes.push({ key, what: 'first read', status: r.status }); continue; }
+    if (was.status !== r.status) changes.push({ key, what: 'status', from: was.status, to: r.status });
+    const sw = sprintLabel(was.sprint); const sn = sprintLabel(r.sprint);
+    if (sw !== sn) changes.push({ key, what: 'sprint', from: sw, to: sn });
+    if (!!was.flagged !== !!r.flagged) changes.push({ key, what: r.flagged ? 'blocked' : 'unblocked', reason: r.reason || null });
+  }
+  const fetchedAt = nowIso(now);
+  const result = { ok: true, initiative, read: got.size, ignored, skipped: n.skipped, missing, changes, snapshot: snapshotRel(root, initiative), dryRun: !!dryRun };
+  if (dryRun) return result;
+  const file = snapshotPath(root, initiative);
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const tmp = `${file}.${process.pid}.tmp`;
+  fs.writeFileSync(tmp, renderSnapshot({ initiative, fetchedAt, query: query || (prev && prev.query) || null, readings, ids }));
+  fs.renameSync(tmp, file);
+  return { ...result, fetchedAt };
+}
+
+// ── J13 · which initiative ─────────────────────────────────────────────────────────────────────────
+function which(root, key) {
+  const k = String(key || '').trim().toUpperCase();
+  if (!KEY_RE.test(k)) return { ok: false, error: `${JSON.stringify(key)} is not a Jira key like ATL-482` };
+  const hits = [];
+  for (const id of jiraTickets.draftedInitiatives(root)) {
+    const p = jiraTickets.pushedTickets(root, id);
+    if (p.epic === k) hits.push({ initiative: id, role: 'epic' });
+    else if (p.tickets.has(k)) hits.push({ initiative: id, role: 'ticket', ticket: p.tickets.get(k).id, summary: p.tickets.get(k).summary });
+  }
+  return { ok: true, key: k, initiatives: hits };
+}
+
+module.exports = { queryFor, linkedInitiatives, normalize, sync, readSnapshot, which, sprintLabel, snapshotPath, snapshotRel };