# Fxa Changelog > Generates a two-audience changelog from merged PRs in the FxA monorepo: a plain-language product summary and an engineer handoff with operational notes. Name a train (e.g. "341") or pass any git range; with no argument it defaults to the in-development train on main (the latest release tag up to HEAD — not a deployed stage/prod train), framed as the range the train owner is accountable for. Use for train-owner handoffs, train summaries, or "what shipped" questions. - Skill: `mozilla/fxa-changelog` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add mozilla/fxa-changelog` - Raw SKILL.md: https://api.skillmd.com/api/skills/mozilla/fxa-changelog/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: mozilla (https://skillmd.com/u/mozilla) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/mozilla/fxa-changelog --- # FxA Changelog Generate a changelog for a range of merged PRs, written for two readers in one document: a product person who wants outcomes in plain language, and an engineer picking up the work who needs PRs, gotchas, and who to ask. **Scope rule:** SubPlat is excluded entirely — no PAY-/ENT- tickets, no payments/entitlements PRs, no `subplat-*` anything. Exclusions are counted honestly in the coverage note, never silently dropped. The boundary lives in the `EXCLUDE_*` constants at the top of `scripts/changelog-scan.py`; tune it there, not in prose. **Train framing:** this is the train owner's handoff. **"Current train" means the one in development on `main`** — the span from the latest `v1.NNN.0` tag up to `HEAD` — not whichever train is deployed to stage or prod (those are older, already-tagged trains). At any moment prod, stage, and `main` are typically three different trains; this skill is about the newest one (`main`), unless the caller names a specific train number (see Phase 1). Train **N** starts the moment train **N-1** is tagged — i.e. at the `v1.(N-1).0` base tag, the cut point on `main`. The owner of train N is accountable for everything merged since then: `v1.(N-1).0..HEAD`. So when the latest train base tag is `v1.340.0` (cut Jul 1), the caller owns **train 341** and the range is `v1.340.0..origin/main`. The boundary is the base `.0` tag, **not** the newest dot-release — pick the highest `v1.NNN.0` (`git tag --list 'v1.*.0' --sort=-v:refname | head -1`), set the train number to `NNN + 1`, and reference the changelog as "Train N" throughout — H1, frontmatter, and the Confluence page. Dot-releases (`v1.340.1`, `v1.340.2`, …) are hotfixes *within* train 340; they do not move the boundary. Because a dot-release fix lands on `main` first and is then cherry-picked onto train 340's release branch, that commit sits inside `v1.340.0..HEAD` and so appears in train 341's range even though it already shipped to users via the cherry-pick. So the honest deploy-state framing is "on `main` since the train started; ships with train N (some fixes also cherry-picked into a v1.340.x dot-release)". Do **not** say entries "merged after the cut" — sha-based tag containment won't see the cherry-pick, so that phrasing can wrongly imply a fix missed a release it's actually in. ## Execution Architecture Same split as the fxa-triage skill, for the same reasons: - **Scan script** (`scripts/changelog-scan.py`) — everything that is pure git arithmetic: first-parent walk, PR/Jira extraction, SubPlat/noise/revert classification, diff stats, flagged-path detection, release-tag containment. Deterministic, instant, can't hallucinate a sha. - **Enrichment collectors** (haiku subagents, ~10 PRs per batch, parallel) — PR bodies, Jira tickets (incl. epic + points), flagged diffs. Compress at the source; return contract JSON only. - **Jira reconciliation** (Phase 3.5) — tickets resolved in the window with no PR in this repo; cross-repo search by ticket key. **Delegate this to one haiku subagent by default** — it's mechanical (one JQL, diff against the scanned keys, `gh search` each orphan, validate hits by summary match) and its ~30-ticket search loop + raw output shouldn't sit in the orchestrator's context. The subagent returns only the bucketed result. - **Orchestrator** (the main model) — epic-first workstream clustering, milestone detection, product-language writing, operational notes, two-axis coverage gate, file output. This is the judgment layer; keep it on the strongest model available. Everything mechanical (scan, enrichment, reconciliation) runs off it — the scan is free Python, enrichment and reconciliation are haiku — so the strong model only spends tokens on judgment. **Single-model fallback:** no Agent tool → do Phase 3 inline, batch by batch, applying the same contract as internal bookkeeping. Everything else is unchanged. **Tool namespaces vary by install.** The `allowed-tools` frontmatter lists `mcp__atlassian__*`, but on some hosts the Atlassian tools are registered as `mcp__plugin_atlassian_atlassian__*` (and GitHub/other MCPs similarly). Never assume a literal name — **resolve every MCP tool via ToolSearch at call time** and use whatever it returns. If the Atlassian MCP isn't connected at all, use the `acli` CLI fallback (Phases 3 and 3.5). ## Phase 1: Resolve Range & Preflight 1. `git fetch origin` (tags and main must be current; ignore l10n hook noise). 2. Resolve the range, in priority order: - **Explicit train number** (the common case) — the caller names the train they own: `/fxa-changelog 341`. Resolve range = that train's base tag `v1.(N-1).0` .. its own tag `v1.N.0` **if it already exists**, else `origin/main` (the train is still open). So `341` → `v1.340.0..v1.341.0` once 341 is tagged, or `v1.340.0..origin/main` while it's in development. Set the train number to the given `N`. Prefer this whenever the owner knows their train — it's unambiguous and doesn't depend on which train is currently on stage/prod. - **Explicit git range** — a git range (`v1.339.5..HEAD`), a tag pair, or natural language ("last 2 weeks" → `--since` converted to the merge-base sha; "since Tuesday" likewise). Normalize to `A..B` form against `origin/main`. - **Train handoff default** (a bare invocation, and the first-run case) — apply the **Train framing** rule above: range = highest `v1.NNN.0` base tag → `origin/main`, train number = `NNN + 1`. Command: `git tag --list 'v1.*.0' --sort=-v:refname | head -1` (ignores dot-releases automatically since it matches only `.0` tags). - **Since last changelog** — *only when the caller explicitly asks to extend incrementally* ("what's new since the last changelog"). Read the newest changelog file in `$CHANGELOG_DIR` (default: the repo root `.`, override with `FXA_CHANGELOG_DIR`) — match `train-*.md` / `*-to-*.md`; its frontmatter `range:` field ends at some sha/tag — start there, end at `origin/main`. **Do not make this the silent default**: it produces a partial mid-train delta, not the train the owner is accountable for. The changelog files (incremental deltas) and the train window (a fixed `.0`-to-HEAD span) are orthogonal; a train handoff always uses the train window regardless of what files already exist. 3. Preflight GitHub access: `gh auth status` if using the `gh` CLI, or confirm a GitHub MCP is connected (resolve via ToolSearch). Either works for Phase 3/3.5; on neither, warn that entries degrade to commit-message language. Atlassian MCP is optional — probe lazily in Phase 3, not here. - **webservices-infra checkout (optional, for Phase 3.5 "landed elsewhere").** Much of the infra work that resolves FxA tickets lands in `mozilla/webservices-infra`. If a local clone exists at the conventional **sibling path `../webservices-infra`** (relative to this repo root; override with `$FXA_WEBSERVICES_REPO`), Phase 3.5 can grep its git log directly — faster, offline-capable, and more reliable than GitHub org-wide search. Check `test -d ../webservices-infra/.git` and record the resolved path (or "not present"). Not a hard requirement: if it's absent, Phase 3.5 falls back to `gh search` — just note it in the coverage line. 4. Echo the **resolved train number, range, and PR count** (`git rev-list --count --first-parent A..B`) and get a one-line confirm before the long run. The `.0`-tag boundary is subtle and easy to mis-resolve (a wrong boundary silently changes which train's work you attribute), so a cheap confirm beats a full re-run. Also stop and confirm if the count is over ~150 — that's probably a mis-resolved range, not a real ask. 5. **Publish flag (opt-in) — preflight the Atlassian MCP if set.** If the invocation includes `--publish` (or "publish to confluence" in the ask), note it now and run Phase 6 after the file is written. **When publish is requested, verify the Atlassian MCP is connected right here, before the long run** — resolve `mcp__atlassian__createConfluencePage`/`updateConfluencePage` via ToolSearch and confirm they load. If the MCP is **not** connected, **stop and fail now** with: `--publish requires the Atlassian MCP; it is not connected. Connect it (/mcp) and re-run, or drop --publish for a local-file-only changelog.` Do not run the scan/enrichment just to fail at the write step — publishing is the whole point of the flag, so fail fast. (A default run without publish never needs the Atlassian MCP for output and proceeds normally.) Default runs stay local-file-only — never publish unless asked. ## Phase 2: Scan ```bash python3 .claude/skills/fxa-changelog/scripts/changelog-scan.py --range "A..B" > /tmp/scan.json ``` (run from the repo root; the path is the script's stable location in-repo.) Output is a JSON **envelope**, not a bare array: `{range, release_tags_checked, total, summary, records}`. Read `.summary` for classification counts (free coverage arithmetic) and iterate `.records` for the per-commit skeletons — parsing the top level as a list will throw. Each record: `{sha, pr_number, branch, jira_key, subject, author, merged_at, scope, files_changed, insertions, deletions, flagged_paths, classification, first_release_tag, cherry_picked_in}`. `first_release_tag` is sha-ancestor containment (a merge that literally sits under a tag). `cherry_picked_in` is a list of tags whose release branch already has this PR's patch via cherry-pick (a *different* sha) — non-null here means the fix shipped early in a dot-release even though `first_release_tag` is null. Use it for accurate deploy state in Phase 4. Classifications: `entry` (goes to Phase 3), `subplat` (excluded, counted), `noise:deps` / `noise:legal-pdfs` / `noise:l10n` (aggregated to one line each), `reverted_pair` (a revert and its target inside the range — collapsed; mention only if the attempt/revert story is itself handoff-relevant). Exit 2 = bad range or not a repo: **abort with the script's message.** There is no fallback here — without git facts there is nothing to enrich. ## Phase 3: Enrich (collectors) **Cache first (re-runs are the norm).** Re-runs are common — the train boundary is easy to get wrong, and a train's range grows across the two weeks it's open — yet most PRs are identical between runs. Before spawning anything, check `$FXA_CHANGELOG_CACHE` (default `/tmp/fxa-changelog-cache/`) for a `.json` per entry; batch only the uncached shas. After each collector returns, write one `.json` per contract. A re-run then enriches only the genuinely new commits (keyed by sha, so a corrected boundary or a grown range reuses everything already fetched). Split the *uncached* `entry` records into batches of ~10 and spawn one haiku collector per batch, all in one message. Each collector's prompt contains: its records (the full skeleton JSON for those PRs), the contract below, and these standing rules: - Fetch per PR: the PR body/labels/author — with the `gh` CLI `gh pr view --repo mozilla/fxa --json body,labels,author`, or with the **GitHub MCP** (resolve via ToolSearch, e.g. `get_pull_request`) if the caller has no `gh`. Then the linked Jira issue: **Atlassian MCP preferred** (resolve tool names via ToolSearch) requesting summary, status, description, `parent` (the epic), and `customfield_10037` (Story Points — stable id on mozilla-hub); **if the MCP is down, fall back to `acli`** — `acli jira workitem search --jql 'key = ' --fields "key,issuetype,status,assignee,labels,summary" --csv` (acli returns summary/status/labels but not epic-parent or points, so set `epic`/`points` null and `jira_read: true` with a `via_acli` note). Then the full diff **only** for PRs with non-empty `flagged_paths` (`git diff ^1 -- `). - Never return raw payloads or diffs — extract and compress. - Final message is ONLY a JSON array of per-PR contracts, no prose. - A PR whose fetches all fail still gets a contract with `status: "partial"` and whatever the skeleton knew. - **Jira access has two failure modes, don't conflate them.** MCP absent/unreadable → `jira_read: false`. But FxA security tickets (the f-series, HackerOne) are ACL-gated behind the "Accounts Security Access" group, so a security ticket often returns *forbidden* even when the MCP works — set `jira_restricted: true` (not a fetch failure), and don't count it against `jira_read` coverage. Its summary can still arrive via the Phase 3.5 reconciliation JQL, which runs with the orchestrator's broader access. Contract per PR: ```json {"pr": 20818, "sha": "aaeaed8ff5", "jira": "FXA-14093", "jira_read": true, "jira_restricted": false, "status": "ok|partial", "epic": {"key": "FXA-9479", "summary": "Deprecate Hawk authentication", "status": "Done"}, "points": 3, "why": "1-2 sentences: the problem this solved, from PR body / Jira", "what_changed": "1-2 sentences, engineer language, concrete", "user_facing": true, "security_sensitive": false, "gotchas": ["new migration patch-142.sql", "new config key oauth.foo (default false)"]} ``` `epic` and `points` are null when the ticket has no parent / no estimate or when `jira_read` is false. `security_sensitive` = true when the PR/ticket has security/HackerOne labels or the description clearly describes a vulnerability fix. `gotchas` come from the flagged-path diffs: new/changed migrations, config keys (with defaults), feature flags added or flipped, API route contract changes, CI workflow changes, new ADRs. Validate each collector reply; one re-ask on malformed output, then mark that batch's PRs `partial`. ## Phase 3.5: Jira Reconciliation (the cross-repo net) The scan only sees commits in this repo; work tracked in Jira but landed elsewhere (docs repos, infra repos, other services) is invisible to it. Close that gap from the Jira side. **Delegate the whole phase to one haiku subagent** (per Execution Architecture) — pass it the scanned jira keys and the window bounds; it returns the three buckets below. Needs Jira access (Atlassian MCP **or** `acli`) and GitHub (`gh` **or** GitHub MCP). If neither Jira path is available, skip this phase with a note in the coverage line. 1. **Tickets resolved in the window:** one JQL query — `project = FXA AND status changed to Done during ("", "") AND (component is EMPTY OR component not in ("Subscription Platform"))` Set `` to **the day *after* the previous train's cut** (the `.0` tag's commit date `+ 1d`), not the cut day itself — the cut day is a batch-close spike of the *previous* train's tickets (dozens flip to Done as that train ships, plus quarter-end epic closes) and are not this train's work. `` is the HEAD commit's date. **Via the Atlassian MCP:** fetch only `["summary","status","parent","resolutiondate"]` with `responseContentFormat: "markdown"` and a `maxResults` cap — the default (all fields, ADF) overflows the tool's token limit; if it still overflows, the result saves to a file, pull fields with `jq -r '.issues.nodes[] | ...'`, never Read the raw file. **Via `acli` fallback:** `acli jira workitem search --jql '' --fields "key,issuetype,status,summary" --csv` — acli rejects the `component not in (...)` clause, so drop it and filter SubPlat (PAY-/ENT- keys, subplat labels) from the CSV yourself; acli's CSV is compact and won't overflow. Separately note any cut-day resolutions excluded as previous-train closeout (count + a couple of examples). 2. **Diff against the PR-claimed set** (the jira keys the scan extracted). Three buckets: - **Matched** — resolved ticket has a PR in range. Already covered; nothing to do. - **Resolved, no PR here** — find where it landed. **First, if the webservices-infra checkout was found in Phase 1**, grep it locally (most infra tickets land there): `git -C ../webservices-infra log --oneline --all --grep '' | head -5` — a hit gives the exact commit/PR without a network call. **Then GitHub org-wide by ticket key** for anything not found locally. With the `gh` CLI: `gh search prs '""' --owner mozilla --merged --json repository,number,title,url --limit 5` (flag is `--merged`, **not** `--state merged`, which errors; keep the inner quotes — GitHub tokenizes `FXA-13709` into `fxa 13709` without them, matching random dependabot bumps). With the **GitHub MCP** instead (resolve via ToolSearch, e.g. `search_pull_requests`/`search_issues`): query `"" org:mozilla is:pr is:merged`. **Validate every hit**: the PR title/repo must plausibly relate to the ticket summary; discard incidental matches (an old low-numbered PR, an unrelated dep bump). Hits in mozilla/fxa itself mean a late/unlinked PR — re-match to an existing entry, or if the PR is *before* the range boundary, bucket it as prior-train. Run the GitHub searches in one batch with a small sleep between calls (rate-limits at ~30/min). - **Resolved, no code anywhere** — list under "Resolved without linked code". Often legitimate (spikes, decisions, ops work); occasionally a process smell. Either way the handoff reader should see it. Never editorialize beyond the facts. 3. **Known limitation, state it honestly:** the search covers GitHub only. Work in mozilla-central (hg) or private repos won't be found; if a ticket's summary clearly implies such a target, say so instead of "no code found". Cost: one JQL + one search per orphan ticket. If the post-cut JQL still returns more than ~40 resolved tickets, the window is probably longer than a train — proceed, but note the volume. ## Phase 4: Analyze **Workstream clustering — epic first.** The parent epic from the collector contracts is the primary cluster key: entries sharing an epic form one workstream named after it ("Passkeys P2 — Sync Sign-in"). Only entries without epics (or whose epic is a catch-all like "Keeping the Lights On") fall back to inference from scope, branch naming, and shared subsystems. Singletons that don't fit a story stay individual entries; do not force fake narratives. Aim for 4–10 clusters on a train-sized range. Sum `points` per cluster and show it ("~21 pts") when at least half the cluster's tickets carry estimates; omit rather than extrapolate. **Epic milestones.** If any entry's epic has status Done and closed during (or near) the range window, that is a **product-summary headline** regardless of how small the in-repo PR was — a one-line metrics tweak can be the visible tip of a multi-quarter migration completing (e.g. the Hawk deprecation epic closing while the range only shows a dashboard-metric PR). Verify the epic's resolution date before claiming it; "epic Done, closed earlier" gets a softer "wrapped up" phrasing. **Deploy state per cluster.** From `first_release_tag`: all members in a tag → "in vX.Y.Z"; none → "on `main`, not yet in a tagged train (ships with train N)" — not "merged after the cut" (see the cherry-pick note in Train framing); mixed → say which parts. **Then layer `cherry_picked_in`**: when it's non-null the fix already shipped early via a dot-release, so say so precisely — "on `main`; also cherry-picked into v1.340.2" — instead of the vague "some fixes may also be in a dot-release" hedge. Trust `cherry_picked_in` over prose guesses; the scan patch-id-matched it. State tags factually — do not guess which env a tag is on unless the engineer tells you. (`git tag --sort=-creatordate` timing plus the team's alternating-Wednesday cadence usually makes it obvious; when it is, phrase it as "in v1.340.1 (stage; prod push Wednesday)".) **Security redaction.** `security_sensitive` entries: engineer section shows `Security fix — see FXA-NNNNN` (link, no vulnerability details, no repro). Product section shows only a count ("includes N security fixes"). This applies even though the file is local — these documents get pasted onward. **Coverage gate (blocks the write) — two axes.** - *PR axis:* every record in the scan is exactly one of: cluster member, individual entry, noise aggregate, subplat exclusion, reverted pair. Print the arithmetic — `43 PRs: 24 in 6 workstreams + 5 individual + 14 subplat excluded + 0 noise + 0 reverted = 43 ✓`. - *Ticket axis (from Phase 3.5):* every ticket resolved in the **post-cut** window is matched, landed-elsewhere, prior-train, or no-code — `14 tickets: 11 matched + 2 elsewhere + 0 prior-train + 1 no code = 14 ✓`. Cut-day resolutions excluded as previous-train closeout are counted separately, not in this sum. A mismatch on either axis means something was dropped; fix before writing. Also compute `jira_read` coverage for the note (excluding `jira_restricted` security tickets, which are expected forbidden — not misses). ## Phase 5: Write One file in `$CHANGELOG_DIR` (default: the **repo root** `.`; override with `FXA_CHANGELOG_DIR`; create the directory if it doesn't exist). Note the root is **not** gitignored, so these files show up in `git status` and are committable — leave it to the engineer whether to commit or delete; the skill itself never stages or commits them. - **Train handoff** → `train-NNN.md` (e.g. `train-341.md`). **No date prefix** — the file is keyed only by train number so a re-run (even days later, as the train grows) overwrites the same file instead of littering the dir with `2026-07-10-train-341.md` / `2026-07-14-train-341.md` near-duplicates. The generation date and exact range live in frontmatter (`generated:`, `range:`). If an older dated `*-train-NNN.md` from a previous version exists, delete it when you write `train-NNN.md`. - **Explicit / ad-hoc range** → `YYYY-MM-DD--to-.md` (dates in UTC; ``/`` are tags or short shas). Ad-hoc ranges keep the date prefix — they're one-offs, not a per-train file that gets refreshed. ```markdown --- train: 341 range: v1.340.0..f18265dd0b generated: YYYY-MM-DD prs_total: 56 prs_entries: 19 coverage: {jira_read: "17/19 (2 security tickets restricted, expected)", subplat_excluded: 11, noise_aggregated: 26, reverted_pairs: 0, tickets_resolved_post_cut: 30, tickets_matched: 13, tickets_landed_elsewhere: 5, tickets_prior_train: 1, tickets_no_code: 11, tickets_cutday_prev_train_excluded: 18} --- # FxA Train 341 Handoff — to (Mon DD – Mon DD) _Everything the train 341 owner is accountable for: merged to main since v1.340.0 (train 340's tag, cut Jul 1) up to HEAD._ ## Product summary One short paragraph: the headline of this range in plain language. Epic milestones (a strategic epic completing) lead this paragraph when present. **** (~N pts) — what users/the product got, in words a PM can paste into a deck. No PR links; Jira links only ([FXA-14093](https://mozilla-hub.atlassian.net/browse/FXA-14093)). Deploy state in-line: *live in v1.340.0* / *merged, ships with the next release*. Points shown only when estimates exist (see Phase 4). (…one block per workstream with anything user-facing; purely internal workstreams get one collective line: "Internal: test infra, CI reliability, logging improvements." Include the security count line here if any.) ## Engineer handoff ### — ask @ *Deploy state (e.g. "on main; also cherry-picked into v1.340.2" when `cherry_picked_in` is set).* Why + what changed, engineer language. - [#20818](https://github.com/mozilla/fxa/pull/20818) ([FXA-14093](…) — ) — one line - … Include the **Jira ticket title** after the key when the collector captured it (`why`/summary), so the bullet reads without clicking through: `[#NNNNN](pr) ([FXA-NNNNN](jira) — ) — one line`. Trim very long titles to the meaningful clause. Omit the title only when there's no ticket, or for **`security_sensitive` entries** — those stay `Security fix — see FXA-NNNNN` with no title (the f-series title itself describes the vulnerability). ### Operational notes The union of all gotchas, grouped: **Migrations** / **Config & flags** / **API changes** / **CI** / **ADRs**. Each with the owning PR linked. If empty, say "None in this range" — the reader needs to know it was checked. ### Landed elsewhere Tickets resolved this window whose code landed outside this repo (from Phase 3.5): - [FXA-NNNNN](…) — summary — [mozilla/ecosystem-platform#785](…) If none: "None found (GitHub-wide search by ticket key; mozilla-central and private repos not searchable)." Then a sub-list for tickets resolved this window whose code landed in this repo but *before* the train boundary (prior train): `- [FXA-NNNNN](…) — summary — mozilla/fxa#NNNNN (merged before the boundary)`. Omit if none. ### Resolved without linked code **One bullet per ticket — never a run-on paragraph** (it must scan like every other section's list): - [FXA-NNNNN](…) — summary (spike/decision/ops — no PR found in any mozilla GitHub repo) - [FXA-NNNNN](…) — summary If there's a natural sub-group (e.g. old `[DONE]`-prefixed bug closeouts), put it under its own one-line sub-label with its own bullets, still one per ticket. If none at all, omit the subsection. ### Aggregates & exclusions - N dependency bumps, N l10n imports, N legal-PDF imports (links to the PR list query) - N SubPlat PRs excluded (out of scope for this changelog) - N tickets resolved on the cut day excluded as previous-train closeout (a couple of examples) - Coverage — PRs: 56/56 accounted for. Tickets (post-cut window): 30 resolved — 13 matched, 5 elsewhere, 1 prior-train, 11 no code. - Jira read for 17/19 entries; 2 security tickets restricted (expected, not a failure); PRs 20831, 20834 partial (fetch failed) ``` Style rules for both sections: - **Impact first, references last.** Every line opens with what happened or why it matters; IDs, counts, and links trail. - **Engineer section keeps the technical payload** — endpoints, config keys, migration names are the content, not noise. - **Never fabricate a why.** If the PR body and Jira gave nothing, say what the diff shows and mark it `(why unclear — ask @author)`. A wrong reason is worse than an honest gap. - **Dates relative to the range**, not to today ("merged mid-train", "last day of the range"). After writing, print to the terminal: the file path, the coverage line, and the product-summary paragraph verbatim (so a quick copy-paste needs no file open). ## Phase 6: Publish to Confluence (opt-in) Runs **only** when Phase 1 flagged the publish arg. Publishes using a **page hierarchy**: a stable parent index page under FxA **Internal Documentation**, with **one child page per train** (`Train NNN`). The Confluence sidebar renders the children as a folder-like tree. Each train is a standalone page, so a re-run overwrites just that train's page (a clean full-body write, no HTML splicing) and a new train is a new child page. ``` Internal Documentation (535363588) └─ FxA Train Owner - Handoff ← parent index (intro + auto child list) ├─ Train 341 ← one page per train (full handoff body) ├─ Train 342 └─ … ``` Targets (override via env; discovered defaults on mozilla-hub): - Site / `cloudId`: `mozilla-hub.atlassian.net` - Space: `PXI` — **numeric `spaceId` `432341014`** (create/update reject the `PXI` key; they need the Long). - Internal Documentation page: `535363588`, override with `FXA_HANDOFF_PARENT_ID`. - Parent index page: title `FxA Train Owner - Handoff`, id `2868510770`, override with `FXA_HANDOFF_PAGE_ID`. Steps: 1. **Preflight — hard fail, not skip.** Publish was requested, so the Atlassian MCP is **required**. Resolve `getConfluencePage`/`createConfluencePage`/`updateConfluencePage`/`searchConfluenceUsingCql` via ToolSearch. If any are unavailable (MCP disconnected), **fail the publish loudly**: `Publish failed — Atlassian MCP not connected; cannot update the handoff doc. The local changelog was written to ; connect the MCP (/mcp) and re-run with --publish.` Never silently mark it skipped. 2. **Ensure the parent index page exists.** Prefer `FXA_HANDOFF_PAGE_ID`; else CQL `title = "FxA Train Owner - Handoff" AND space = PXI AND type = page`. If missing, `createConfluencePage` under `535363588` (space `432341014`) with a short intro `
` (what this is; one child page per train) followed by a Children Display macro so the train list stays automatic: `
`. Leave the parent's body alone on subsequent runs — the child list is automatic. 3. **Convert this train's markdown → a full Confluence HTML page body** (`contentFormat: "html"`). Drop the YAML frontmatter and the top `# FxA Train NNN Handoff …` H1 (the page title carries it). Straight mapping: `##`→`

`, `###`→`

`, bullets→`