create-pmos 0.57.0 → 0.58.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-pmos",
-  "version": "0.57.0",
+  "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@d3d97f5
+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:08:49Z"}
+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:08:49Z"}
+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:08:49Z"}
+generated: {by: process:create-pmos, at: "2026-10-06T11:54:59Z"}
 status: stable
 ---
 

package/workspace/first-paint-audit.js

@@ -18,9 +18,12 @@
  */
 
 // The budgets start at specimen A's counts. reports: 14 → 15 in Run 6 for Present, the one control the PM asked to keep
-// with the slides (2026-10-06). The calibration stays specimen A's own count: the specimen did not change.
+// with the slides (2026-10-06). Every place +1 for Docs in the top bar (the PM, 2026-10-06, docs-three-way-sync): the
+// budget is for the whole screen and the bar is on every screen. The calibration stays specimen A's own count: the
+// specimen did not change.
 const SPECIMEN_A = Object.freeze({ today: 17, initiatives: 24, board: 33, reports: 14 });
-const EXPECT = Object.freeze({ ...SPECIMEN_A, reports: 15 });
+const BAR_DOCS = 1;
+const EXPECT = Object.freeze({ today: 17 + BAR_DOCS, initiatives: 24 + BAR_DOCS, board: 33 + BAR_DOCS, reports: 15 + BAR_DOCS });
 
 /* ── shoot.js audit(), copied verbatim (scratchpad/specimens2/shoot.js, 2026-10-05) ─────────────────────────────── */
 // runs in the page

package/workspace/guide/docs.md

@@ -6,7 +6,7 @@ timestamp: 2026-10-06
 
 # Docs
 
-Open Docs from ⌘K (**Docs**) or press `g d`.
+Open Docs from the top bar, from ⌘K (**Docs**), or press `g d`.
 
 Docs lists every document in the repository that has a copy in Google Docs or Confluence. For each copy, it shows whether the repository version (PMOS) or the copy is newer. You can then use one version over the other, one copy at a time.
 

package/workspace/guide/index.md

@@ -12,7 +12,7 @@ This guide describes the PMOS workspace as it works today. It ships with the app
 
 On a desktop the workspace is one frame. [Layout](layout.md) explains each part.
 
-1. **The top bar.** Repository ▾, the four places, search (⌘K), Sync when the repository is not in sync, and Settings.
+1. **The top bar.** Repository ▾, the five places (Docs included), search (⌘K), Sync when the repository is not in sync, and Settings.
 2. **The place.** One of Today, Initiatives, Board or Reports, or Docs (⌘K or `g d`). It fills the screen under the bar.
 3. **The detail.** The item you opened: an initiative with its status, next steps and artifacts, or the profiles. It opens beside the place and closes with ×.
 4. **The agent dock.** Terminals, documents, conversations and web pages. It is open on Today and a thin rail elsewhere.
@@ -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/guide/layout.md

@@ -15,7 +15,7 @@ The top bar has these parts, from left to right:
 
 - **Repository ▾** names the current repository. Press it to choose another repository, or **All repositories** to see the work of every repository at once. All repositories replaces the old Portfolio mode.
 - **Branches and sessions** is in ⌘K. It opens a sheet with every branch of the repository (main first) and how many sessions run in each. Press a branch to see its sessions, open one, end one, or start a session there. **＋ branch** makes a branch, and **＋ session** starts one with a branch, an agent and a profile. With All repositories, the sheet lists every repository.
-- **Today, Initiatives, Board and Reports** are the four places. Press one to show it. The Today count shows how many items need you.
+- **Today, Initiatives, Board, Reports and Docs** are the five places. Press one to show it. The Today count shows how many items need you. Docs shows whether each document is the same as its Google Docs and Confluence copy.
 - **Search or capture ⌘K** opens the command palette. Type to find an initiative, a repository, an open tab or a command.
 - **Sync** shows only when the current repository is not in sync with its remote. Press it to fetch, bring in the work of the other machine, record your changes and push. If the repository has not fetched in the last 10 minutes, Sync also shows, because a push from another machine is not visible until a fetch. When the repository fetched recently and is in sync, Sync is not shown. If Sync stops, the message names the step that stopped.
 - **Sync on its own.** If you forget to press Sync, the workspace syncs for you. It syncs each repository once when the workspace starts. It also syncs a repository that has records not yet pushed when no record changed for 5 minutes. In a document repository it syncs every changed file on any branch. In a code repository it syncs only on the default branch (for example `main`), and only when every commit not yet pushed changes records and no code. If you close the tab while records are not yet pushed, the browser asks you first. To turn automatic sync off, start the workspace with `PMOS_AUTO_SYNC=0`.
@@ -70,7 +70,7 @@ The workspace is neutral. A primary button is the text colour on the page colour
 
 | Key | What it does |
 |---|---|
-| g t, g i, g b, g r | Show Today, Initiatives, Board or Reports. |
+| g t, g i, g b, g r, g d | Show Today, Initiatives, Board, Reports or Docs. |
 | ⌘K (Ctrl-K) | Open or close the command palette. |
 | ⌘J (Ctrl-J) | Open or fold the dock. |
 | ⌘⇧J (Ctrl-Shift-J) | Focus: give the dock the whole window, or show the place again. |

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 };