@mmerterden/multi-agent-pipeline 16.3.0 → 16.5.0

package/CHANGELOG.md

@@ -16,6 +16,130 @@ Internal file-layout changes that don't affect the slash-command surface are sti
 
 ## [Unreleased]
 
+## [16.5.0] - 2026-08-25
+
+Staying current stops being something a user has to be told to do.
+
+### Changed
+
+- **`updateCheck.autoUpdate` now defaults to `true`.** A newer version is installed before the run starts, in interactive modes and autopilot alike, instead of asking once per `ttlHours`. The old default made "be current" opt-in, which in practice meant a maintainer telling people to run a command - and since v15.14 the Supported Version Gate already halts any install below the `required` floor, so the real choice was never "update or not", it was "update, or be stopped and told to update". `autoUpdate: false` restores the question; `updateCheck.enabled: false` silences the advisory check (neither disables the required floor, whose only override remains `MULTI_AGENT_ALLOW_OUTDATED=1`). Docs already loaded finish the current run on the old version; the update takes full effect on the next run.
+- **The MCP server is registered as `@latest`.** The registration was the bare package name, so `npx` reused any cached copy: a machine that had cached toolkit 3.0.0 kept starting 3.0.0 after 3.1.0 was published and tagged `latest`. The new tool existed on the registry and in the docs, and in no running server. Measured, not assumed - the npx cache held exactly `3.0.0` while `latest` was `3.1.0`. The cost is a registry round-trip when the server starts, and an offline start now depends on what npx can resolve rather than on any cached version being present: a stale server is a silent wrong answer, a failed start is a loud one.
+- **Registration is rewritten on every install and update, not skipped when present.** The installer treated "already registered" as done and left the stored args alone, so an existing install would have kept the bare spec forever and the `@latest` change would have reached new installs only. The current entry is now removed before the add, exactly as the pre-rename entry already was. A host that refuses the remove is reported as possibly-stale with the manual command, rather than counted as a clean registration.
+
+### Fixed
+
+- Two comments in `install/_mcp-register.mjs` and one in `smoke-npm-scope-pinning.sh` still said 83 tools / `MCP_SERVER_PACKAGE`; the toolkit serves 84 and the registration builds from `MCP_SERVER_SPEC`.
+
+## [16.4.0] - 2026-08-24
+
+Two default changes are worth reading before upgrading. `/multi-agent:analysis`
+no longer overwrites a Jira issue's description - it posts a comment unless you
+explicitly choose the description, which is then backed up first. And Phase 6
+gained a blocking gate: a plan step that never reached a terminal status stops
+the commit instead of surfacing in the Phase 7 report afterwards. Both are
+corrections to behaviour that lost work quietly; neither changes a command name
+or an option.
+
+Four ideas taken from github/spec-kit, obra/superpowers, karpathy/llm-council and yamadashy/repomix after auditing all five candidate repos against this pipeline at source level. Most of what those projects do the pipeline already had (spec-kit's constitution is `analysis/locked.md`, its `/analyze` is `validate-analysis-doc.mjs`, repomix's packed digest is `repo-map.mjs`, its offload pattern is Phase 4 Step 1.9, its secretlint pass is Gate 4 before any reviewer runs, serena's memories are the learnings ledger). These are the four gaps that were real.
+
+### Fixed
+
+- **The triage model could recognise its own findings.** On Claude Code the reviewers are Fable + Sonnet and triage is Fable; on Copilot CLI the reviewers include Opus and triage is Opus. Step 3.2 handed that model a list labelled "Reviewer 1 + Reviewer 2", and the Step 2.5 rebuttal round showed each reviewer "the OTHER reviewers'" findings by attribution - so the judge was marking its own homework, and the word "anonym" appeared nowhere in the pipeline. `scripts/anonymize-findings.mjs` now strips every identity key, relabels findings `Source A/B/C`, and orders them with a PRNG seeded from `taskId:iteration` after a stable content sort, so reviewer completion order cannot leak through position and `/multi-agent:resume` reproduces the same input. The label map is written to a separate file and never enters a prompt. Pattern source: llm-council `backend/council.py` stage 2; the delta is deliberate, since llm-council anonymizes only its peer-ranking step and lets its chairman see names - our triage is chairman AND panel member.
+- **An unfinished plan could reach commit.** Phase 4 answers whether the diff is correct, Step 1.45 covers the planned tests, and the criteria manifest's denominator is rule IDs. Nothing covered the plan's own steps: the `[done]` / `[pending]` rollup is rendered in Phase 7, after the commit. `scripts/plan-coverage-gate.mjs` runs as Phase 6 Step 0a and fails when a step never reached a terminal status, when a skip or failure carries no reason, or when an analysis Section 14 row tagged `Add new` names a file that is not in the tree. Pattern source: spec-kit `converge` - current state rather than a diff, and a clean run stays quiet. Not copied: spec-kit appends remediation tasks to `tasks.md`; rewriting an approved plan is a Phase 2 decision, not a gate's.
+
+### Added
+
+- **Test baseline (`prefs.global.testBaseline`, default off).** Phase 4 Gate 3 had no way to tell an inherited red suite from one this run broke, so it blocked on someone else's bug or the dev agent "fixed" tests it never touched (`shadow-git.sh init` snapshots files, not test results). Phase 0 Step 7.6 now runs the same command Gate 3 uses, time-capped, and records `state.baseline.tests` with one of three statuses: `green`, `red` with the failing set, `red` with an empty set plus the log path when the output cannot be parsed into names, or `unknown`. Gate 3 subtracts a known failing set, refuses to either pass or silently block on an unparseable red, and leaves today's behaviour untouched when there is no baseline. Pattern source: superpowers `using-git-worktrees` Step 3, extended from ask-the-user to a stored set.
+- **`smoke-triage-anonymity.sh` (17 assertions), `smoke-plan-coverage.sh` (15), `smoke-test-baseline.sh` (13).** Each proves the behaviour, not the prose: identity keys really are stripped, no model name survives in the payload, the same seed reproduces the order and a different seed does not, reviewer order does not change finding order, per-reviewer metrics degrade to `unavailable` instead of inventing a zero, every unaccounted todo shape is caught, Reuse/Modify rows and template placeholders are not counted against the tree, and no doc collapses baseline `unknown` into `green`.
+
+### Changed
+
+- **`reviewIterations[].reviewers` is typed.** It was `{"type": "array"}` with no item schema, so nothing said a reviewer entry names its model. Now `model`, `findings[]` and `roundCount` are declared, with nothing required: a run written before this shape still validates and surfaces as `unknown` rather than being folded into a named model.
+- **`run-metrics.mjs` reports signal-to-noise per reviewer.** `acceptedRatio` pooled every reviewer together, so "which model is worth dispatching" had no answer. With the anonymization map present, accepted findings are attributed back per model; without it the raw counts still land and `perReviewerAttribution` says `unavailable`. Pattern source: llm-council `calculate_aggregate_rankings`.
+- **`smoke-gate-wiring.sh` matches the property, not the section title.** It grepped for the literal heading "3.0 Merge the deterministic findings in" and reported a wiring break when that section was retitled, while the wiring was intact. It now checks that 3.0 merges, that 3.1 reads the merged count, and that anonymization precedes the merge - relabelling gate findings as reviewer findings would cost triage the difference between a fact and a raw signal.
+- **`total_max_tokens` 56600 -> 57600.** Three new phase-doc contracts cost about 1000 tokens after trimming the drafts by 500. Every individual phase stays inside its own max and `phase-0-init` is back under its warn line; only the aggregate needed the same incremental bump the last three feature commits made.
+
+### Fixed (same release, found by reviewing the four items above)
+
+- **`run-metrics` understated a reviewer on a mixed-map run.** `attributed` was a
+  single global flag, so an iteration with no label map still added its findings
+  to the per-reviewer denominator while being unable to contribute a numerator. A
+  resumed run that upgraded mid-flight read as noise the reviewer was never
+  credited for. The denominator is now the attributable raw count,
+  `rawAttributable` is reported next to `rawFindings`,
+  `mappedIterations` says how many iterations carried a map, and
+  `acceptedUnattributed` counts every accepted finding that resolves to no
+  reviewer - a deterministic-gate finding, which carries no `foundBy` by design,
+  or anything from an iteration that had no map - so
+  `acceptedAll === sum(perReviewer.accepted) + acceptedUnattributed` holds.
+- **`anonymizationMap` was referenced but never declared.** Phase 4 Step 3.0
+  writes it and `run-metrics.mjs` reads it, yet it appeared nowhere in
+  `agent-state.schema.json` - it validated only because the iteration object
+  allows extra keys. That is the same declared-but-undeclared shape the typed
+  `reviewers` entry was added to close. Now declared with `seed` and
+  `labelToModel`.
+- **`anonymize-findings.mjs` documented an exit code it could not reach.** The
+  header promised `64 usage`, but the TTY guard was lost when the file was
+  rewritten, so a bare invocation blocked on stdin forever and 64 was
+  unreachable. Restored, and verified through a pty rather than a pipe.
+- **`plan-coverage-gate.mjs` could skip a real Section 14 row.** A header-row
+  filter matched `^(dosya|file)\b` against the PATH column, so a promised file
+  under a `File/` directory left the denominator silently. The filter was
+  redundant anyway - the header's tag cell already fails the `Add new` test - so
+  it is gone, with a fixture row proving it.
+- **Two gate assertions claimed more than their code.**
+  `smoke-triage-anonymity.sh` said "no model name appears anywhere in the
+  payload" when the guarantee is structural (no identity FIELD survives; free
+  text is deliberately not scrubbed, because that would mangle a finding about
+  `ClaudeService.swift`), and the limit is now stated in both the gate and the
+  script header. `smoke-gate-wiring.sh` matched a section title instead of the
+  property and reported a wiring break on a retitled but intact section.
+
+### Fixed (review round 2)
+
+- **The Section 14 file check was wired to a variable nothing sets.** Phase 6
+  passed `${ANALYSIS_DOC:+--analysis "$ANALYSIS_DOC"}`, and `ANALYSIS_DOC` is
+  defined nowhere in the pipeline - so in practice that half of the gate never
+  ran. The real location is `state.analysis.docPath[]`, an array with one entry
+  per platform (Phase 1 Step 4), and `--analysis` is now repeatable so every
+  platform's promised files enter one denominator instead of the first one
+  standing in for the run.
+- **A plan with zero steps passed.** `todos: []` reported `0/0 steps accounted
+  for` and exited 0, so a Phase 2 that produced nothing - or a state whose todos
+  were cleared - read as a fully delivered plan. An empty plan is now exit 2,
+  the same as a missing one.
+- **A malformed reviewer dispatch vanished.** A reviewer whose `findings` came
+  back as an object contributed nothing and said nothing, so triage adjudicated
+  a smaller panel than actually ran. The anonymizer now warns on stderr and
+  records the loss in the map under `malformed`, named by label.
+- **A residual that anonymization does not remove is written down.** With two
+  reviewers the label set is `{Source A, Source B}` and the triage model is one
+  of them, so it keeps a 50% prior on which findings are its own. The value is
+  that nothing tells it; llm-council's four-model council has a stronger version
+  of the same property.
+
+### Not adopted, with reasons
+
+- **tree-sitter symbol extraction (repomix `--compress`).** `repo-map.mjs` extracts declarations by regex and tree-sitter would be more accurate, but `package.json` has `"dependencies": {}` and that zero-runtime-dependency property is deliberate. If accuracy is wanted, LSP is the compatible route.
+- **serena-style symbol-level reuse detection.** Locked 11's `Reuse existing X (file:line)` rows rest on regex and would benefit, but it means rewriting the Phase 1b collector, and serena was only read at README level. Separate work.
+- **Per-task `verification` field (superpowers).** Not a failure class, overlaps the coverage gate above, and touches schema plus plan approval plus the Phase 3 evidence chain - the widest blast radius of the five candidates.
+- **spec-kit `extensions.yml` hooks.** A HookExecutor layer above the existing `prefs` flags, for one maintainer.
+
+### Fixed - Jira channel
+
+- **`/multi-agent:analysis` overwrote the Jira issue description.** The Jira output target was a bare `PUT /rest/api/2/issue/{key}` on the `description` field: one write, no read first, no backup, no preview. An issue whose description held the reporter's own requirement text lost it silently - the picker asked which issue, never what would happen to it. Publishing now goes through `lib/jira-publish.sh`, and the destination question has three answers with **Comment pre-selected** (a comment cannot destroy anything, and it is what an unattended run gets). The description path reads the current value first, writes it to `~/.claude/logs/multi-agent/jira-backups/<KEY>-description-<stamp>.txt` and reports the path, appends below a `----` rule by default, and exits 3 rather than replacing a non-empty field unless the user's explicit "Description - replace" answer supplies `--confirm-overwrite`. The body is escaped by `jira-wiki-escape.mjs` on both paths, and the bearer token is passed through a curl `-K` config so it never reaches argv.
+
+- **A Jira comment showed a smiley nobody typed.** The body referenced the Swift selector `login(source:input:)`, whose trailing `:)` Jira's wiki renderer turns into an emoticon image at render time. `channels/jira.md` had carried an "Emoticon escaping (required)" table with all 21 sequences for releases, and its own text said the table "is applied by the model, by hand" - so on a long body it was skipped, silently. The escape is now `pipeline/scripts/jira-wiki-escape.mjs`: it backslash-escapes each documented sequence, skips `{code}` / `{noformat}` blocks, reaches inside `{{monospace}}` (Jira parses emoticons there too), and is idempotent. `--check` is the inverse, for a pre-POST assertion. Wired into all nine Jira comment/description write sites (channels adapter, analysis description PUT, generate-issue create, wiki-to-Jira triad, readiness review, create-jira).
+
+### Added - Jira channel
+
+- **`smoke-jira-publish.sh`** - 20 assertions over the safe-write contract, driven by a curl stub so nothing touches the network: comment is the default target, the description path GETs before it writes, the backup exists even on the refused path, a blind replace is refused, a confirmed one writes only the new body, an empty description needs no ceremony, `--dry-run` sends nothing, and the token never appears in argv. It also holds `analysis/render.md` to the contract, so the bare description PUT cannot come back in prose.
+
+### Changed - Jira channel
+
+- **`smoke-channel-glyphs.sh` section 3 tests behavior instead of prose.** It used to grep `channels/jira.md` for the escaping table and pass - the table was present, and nothing applied it. It now runs the program: the exact selector that caused the bug, the monospace case, the code-block skip, idempotency, both `--check` exit codes, and a table-to-program tie that reads the 21 sequences out of the doc rather than retyping them, so the doc and the program cannot drift apart in either direction. It also asserts every known Jira write site routes through the escape, which is how a new write site that skips it gets caught.
+- **`pipeline/scripts/README.md` counts recounted from the filesystem** - the header said 148 shell + 45 `.mjs` and the smoke heading said 118 files; the tree holds 186 shell, 58 `.mjs`, 151 smokes.
+
 ## [16.3.0] - 2026-08-24
 
 Three defects the 16.2.0 review named but did not close, plus one it caused.

package/docs/features.md

@@ -173,7 +173,7 @@ Existing tests are immutable during a task: deleting, renaming, or weakening an
 
 Phase 0 Step 0.6. Once per `ttlHours` window (cached, 3s-bounded curl to the npm registry), the installed version is compared against two dist-tags.
 
-**`latest` - advisory**, opt-out via `prefs.global.updateCheck.enabled`. Newer version: interactive modes ask "Update now?" (yes runs the `/multi-agent:update` flow, then the run continues); autopilot logs one line and never asks. `autoUpdate: true` updates silently before the worktree exists. Offline and failed checks are silent - never blocks.
+**`latest` - automatic**, since v16.5.0. `prefs.global.updateCheck.autoUpdate` defaults to `true`: a newer version is installed before the run starts, in interactive modes and autopilot alike, and the run continues. Set `autoUpdate: false` to be asked once per `ttlHours` instead, or `updateCheck.enabled: false` to silence the check (neither disables the required-version floor).
 
 **`required` - blocking** (v15.14.0+). Most releases do not publish this tag and nothing changes for them. A release that changed a contract a run depends on is promoted with `npm dist-tag add <pkg>@<version> required`, and an install below that floor is not behind, it is wrong: `require-supported-version.sh` exits 3, the run halts, `/multi-agent:update` runs, and the user re-issues the command on the new version rather than continuing on docs already loaded from the old one. Interactive and autopilot behave identically. The gate fails open on every undeterminable answer (offline, blocked registry, no tag), `updateCheck.enabled: false` does not disable it, and the single override is the env var `MULTI_AGENT_ALLOW_OUTDATED=1`, which is logged in the run record. Exemptions: `update`, `setup`, `uninstall`, `help`, `status`, `log`, `search`, `routines`, `forget`, `language`.
 

package/install/_mcp-register.mjs

@@ -31,6 +31,22 @@ import { isDryRun } from "./_common.mjs";
 export const MCP_SERVER_NAME = "multi-agent-toolkit";
 export const MCP_SERVER_PACKAGE = "@mmerterden/multi-agent-toolkit-mcp";
 
+/**
+ * The spec the host is registered with. `@latest` is deliberate and it is the
+ * difference between "the toolkit was published" and "the toolkit is running".
+ *
+ * Measured before this was added: the registration was the bare package name,
+ * npx found ANY cached version and reused it, and a machine that had cached
+ * 3.0.0 kept starting 3.0.0 after 3.1.0 was published and tagged `latest`. The
+ * new tool existed on the registry and in the docs, and in no running server.
+ *
+ * The cost is a registry round-trip when the MCP server starts, and an offline
+ * start now depends on what npx can resolve from its cache rather than on a
+ * cached version being present at all. That trade was made explicitly: a stale
+ * server is a silent wrong answer, a failed start is a loud one.
+ */
+export const MCP_SERVER_SPEC = `${MCP_SERVER_PACKAGE}@latest`;
+
 /**
  * The registry the package is published to, pinned BY SCOPE.
  *
@@ -44,7 +60,7 @@ export const MCP_SERVER_PACKAGE = "@mmerterden/multi-agent-toolkit-mcp";
  *
  * So `npx` fetched from the wrong registry, the package was not there, the
  * process never started, and the host reported `CONNECTION_CLOSED` - a server
- * that works perfectly when run directly (83 tools) looked broken.
+ * that works perfectly when run directly (84 tools) looked broken.
  *
  * `--registry` does NOT fix this: a scope mapping outranks it. The scope itself
  * has to be pinned, which is why the flag below is built from the package name
@@ -64,7 +80,7 @@ export function scopeRegistryFlag(pkg = MCP_SERVER_PACKAGE, registry = MCP_REGIS
  * A host keys its registration by name, so renaming does NOT upgrade an entry in
  * place: without this, an existing install ends up with both `dev-toolkit`
  * (pointing at the old package, still resolvable, now frozen at 2.26.0) and
- * `multi-agent-toolkit`. Two servers advertising the same 83 tools is worse than
+ * `multi-agent-toolkit`. Two servers advertising the same 84 tools is worse than
  * either alone - the host has to pick, and which one it picks is not something
  * the pipeline controls. Registration removes the legacy entry first.
  */
@@ -152,7 +168,7 @@ function saysAlreadyExists(text) {
 export function registerMcpServer(host, label) {
   const cli = resolveCli(host);
   const scopeArgs = HOSTS[host]?.scopeArgs || [];
-  const npxArgs = ["-y", ...scopeRegistryFlag(), MCP_SERVER_PACKAGE];
+  const npxArgs = ["-y", ...scopeRegistryFlag(), MCP_SERVER_SPEC];
   const manual = `${host} mcp add ${scopeArgs.join(" ")}${scopeArgs.length ? " " : ""}${MCP_SERVER_NAME} -- npx ${npxArgs.join(" ")}`;
 
   if (isDryRun()) {
@@ -182,6 +198,24 @@ export function registerMcpServer(host, label) {
     /* not present, or the host declines - either way the add below is what matters */
   }
 
+  // Drop the CURRENT entry too, so the add below rewrites its spec. Without this
+  // the host answers "already exists", the installer reported success, and the
+  // stored args stayed whatever an older version wrote - which is how a machine
+  // kept starting the toolkit from a bare package name (and therefore from
+  // whatever npx had cached) long after the spec gained `@latest`. The entry is
+  // installer-owned, so replacing it is not clobbering a user's work; a host
+  // that refuses the remove is reported below rather than counted as current.
+  let replacedExisting = false;
+  try {
+    execFileSync(cli, ["mcp", "remove", ...scopeArgs, MCP_SERVER_NAME], {
+      stdio: "pipe",
+      timeout: 20_000,
+    });
+    replacedExisting = true;
+  } catch {
+    /* not registered yet - the common case on a fresh install */
+  }
+
   try {
     // Bounded: an installer must never hang on a child process. This is a local config
     // write and returns in milliseconds.
@@ -193,10 +227,18 @@ export function registerMcpServer(host, label) {
     // Claude Code refuses a duplicate on the SUCCESS path (exit 0), so the check
     // cannot live in the catch alone.
     if (saysAlreadyExists(stdout?.toString() ?? "")) {
-      console.log(`    -> ${label}: ${MCP_SERVER_NAME} MCP server already registered, left as-is`);
-      return { registered: true, alreadyPresent: true };
+      // Reached only when the remove above did not take. The entry survives, but
+      // its spec is whatever was there before, so this is not a current
+      // registration - say that instead of reporting a clean pass.
+      console.log(
+        `    -> ${label}: ${MCP_SERVER_NAME} already registered and the host declined to replace it; ` +
+          `its spec may predate ${MCP_SERVER_SPEC}. Re-register manually with: ${manual}`,
+      );
+      return { registered: true, alreadyPresent: true, staleSpec: true };
     }
-    console.log(`    -> ${label}: registered the ${MCP_SERVER_NAME} MCP server`);
+    console.log(
+      `    -> ${label}: ${replacedExisting ? "re-registered" : "registered"} the ${MCP_SERVER_NAME} MCP server (${MCP_SERVER_SPEC})`,
+    );
     return { registered: true };
   } catch (e) {
     // The CLI writes its diagnosis to stderr, which execFileSync parks on the error

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mmerterden/multi-agent-pipeline",
-  "version": "16.3.0",
+  "version": "16.5.0",
   "description": "8-phase AI development pipeline with full orchestration on Claude Code, Copilot CLI and Codex CLI. Analysis, planning, TDD, CLI-aware parallel review with consensus surfacing + Fable triage, default-FAIL evidence gates, secret + intent guards, per-phase cost ledger, persistent learnings memory, wiki generation, commit automation. Token-preserving uninstall.",
   "type": "module",
   "main": "index.js",

package/pipeline/commands/multi-agent/analysis/SKILL.md

@@ -50,7 +50,7 @@ Full contract: `$HOME/.claude/multi-agent-refs/analysis/synthesis.md`. Pass A bu
 
 ### Phases 3, 3.5, 4, 5 - Render, publish, report
 
-Full contract: `$HOME/.claude/multi-agent-refs/analysis/render.md`. Renders one markdown file per platform, runs the **required** `ai-common-toolkit:humanizer` pass, gates on `validate-analysis-doc.mjs`, asks for the output destination, dispatches to Local / Confluence / Jira, then reports and stops. The humanizer pass and the validator are required in every mode; a document that skipped either is not shippable.
+Full contract: `$HOME/.claude/multi-agent-refs/analysis/render.md`. Renders one markdown file per platform, runs the **required** `ai-common-toolkit:humanizer` pass, gates on `validate-analysis-doc.mjs`, asks for the output destination, dispatches to Local / Confluence / Jira (a Jira issue receives a comment unless the user explicitly asks for the description, which is never overwritten without a backup and a confirmation), then reports and stops. The humanizer pass and the validator are required in every mode; a document that skipped either is not shippable.
 
 ### Resume contract
 
@@ -106,6 +106,7 @@ When `phase == "cancelled_at_pass_b_preview"`:
 | `$HOME/.claude/rules/tdd.md` | Section 15 test naming |
 | `$HOME/.claude/multi-agent-refs/analysis-template.md` | Template master copy + language matrix (v3 - 23 sections) |
 | `$HOME/.claude/multi-agent-refs/conventions-defaults.md` | Pass B fallback defaults (4 platforms x 7 pattern groups) - applied when convention confidence is none AND standards binding is silent |
+| `$HOME/.claude/lib/jira-publish.sh` | Phase 4 Jira write: comment by default, description only on explicit choice - reads the current description first, backs it up, appends below a rule, refuses a non-empty replace without `--confirm-overwrite` |
 | `$HOME/.claude/scripts/validate-analysis-doc.mjs` | Phase 4 pre-dispatch gate: deterministic check of the emitted per-platform doc (front-matter, never-omitted sections, humanizer punctuation, Full-mode BR traceability) |
 | a project-supplied Confluence-embedded API-table parser (optional) | Parse endpoints from a Confluence page's Request Path / Service Name / Response Body table columns |
 | `~/<project>-Standards.md` | Canonical home-dir standards reference (auto-detected at Q5 option 2; exact filename from `prefs.projects[<project>].standardsFile`) |

package/pipeline/commands/multi-agent/channels/SKILL.md

@@ -369,7 +369,7 @@ Aggregated Markdown from Step 5 → PR description. GitHub uses `gh pr edit --bo
 Full contract: [`$HOME/.claude/multi-agent-refs/channels/pr.md`]($HOME/.claude/multi-agent-refs/channels/pr.md)  -  Bitbucket payload assembly snippet, version-mismatch retry, `--ready` promotion, multi-repo cross-link block.
 
 #### Adapter: Jira comment
-Body converted to Jira wiki markup (`### ...` → `*...*`, `- [ ] ...` → `# ...`, `` `x` `` → `{{x}}`, tables to `||h||h|| |c|c|`); first line is the PR URL. POST `/rest/api/2/issue/{id}/comment` via heredoc + `jq --rawfile` + `curl --data-binary @file`. Token resolved from `keychainMapping.jira`.
+Body converted to Jira wiki markup (`### ...` → `*...*`, `- [ ] ...` → `# ...`, `` `x` `` → `{{x}}`, tables to `||h||h|| |c|c|`); first line is the PR URL. The converted body then goes through `node "$HOME/.claude/scripts/jira-wiki-escape.mjs"` (required, not optional  -  Jira renders `:)` `(x)` `(!)` `(/)` as emoticon images, and a Swift selector like `login(source:input:)` ends in `:)`). POST `/rest/api/2/issue/{id}/comment` via heredoc + `jq --rawfile` + `curl --data-binary @file`, from the escaped file. Token resolved from `keychainMapping.jira`.
 
 Full contract: [`$HOME/.claude/multi-agent-refs/channels/jira.md`]($HOME/.claude/multi-agent-refs/channels/jira.md)  -  full conversion table, multi-repo PR-list prepend, Wiki→Jira triad interaction.
 

package/pipeline/commands/multi-agent/prune-logs/SKILL.md

@@ -20,6 +20,13 @@ Unlike `/multi-agent:purge` (which wipes worktrees, branches, logs, and state
 together), this only removes log dirs and leaves your worktrees and branches
 untouched.
 
+Not in scope: `~/.claude/logs/multi-agent-toolkit/`, the sibling directory where
+`multi-agent-toolkit-mcp` saves tool outputs too large to return inline. That
+directory prunes itself at write time (newest 50 files, 7 days), because an
+MCP-only user has no pipeline installed and "some other tool cleans it" would
+mean nobody does. Mentioned here so the files are not a mystery when you come
+looking for what is using space under `logs/`.
+
 ## Steps
 
 1. **Preview (dry-run)**  -  run the pruner with no `--yes`, forwarding any

package/pipeline/lib/jira-publish.sh

@@ -0,0 +1,173 @@
+#!/usr/bin/env bash
+#
+# jira-publish.sh
+#
+# Publishes an analysis / report body to a Jira issue without destroying what
+# is already there. Spec: refs/analysis/render.md (Phase 4 Jira target) and
+# refs/channels/jira.md (transport + emoticon escaping).
+#
+# Why this exists: the analysis Jira target used to PUT the description field
+# directly, so an issue whose description held the analyst's original
+# requirement text lost it with no preview, no backup and no undo. A comment
+# cannot destroy anything, so `comment` is the default target; writing the
+# description is opt-in, always backed up first, appends by default, and
+# refuses to replace a non-empty description without an explicit confirmation.
+#
+# Usage:
+#   jira-publish.sh --issue KEY --body-file FILE
+#                   [--target comment|description]   (default: comment)
+#                   [--mode append|replace]          (description only, default: append)
+#                   [--confirm-overwrite]            (required for mode=replace on a non-empty field)
+#                   [--backup-dir DIR]
+#                   [--dry-run]
+#
+# Resolution:
+#   host    JIRA_HOST, else prefs .global.hosts.jira
+#   token   JIRA_TOKEN, else credential-store.sh get <prefs .global.keychainMapping.jira>
+#   The token never reaches argv or a log: it is passed to curl through a -K
+#   config on process substitution, the same idiom as post-pr-review.sh.
+#
+# Every body is run through scripts/jira-wiki-escape.mjs before it is sent, so
+# Jira cannot manufacture an emoticon out of a Swift selector or a table cell.
+#
+# Exit codes:
+#   0  published (or, with --dry-run, previewed)
+#   3  refused: replace would destroy a non-empty description and no
+#      --confirm-overwrite was given. The backup is already on disk.
+#   4  host or token could not be resolved
+#   5  a Jira API call failed
+#  64  usage error
+
+set -euo pipefail
+
+SELF_DIR="$(cd "$(dirname "$0")" && pwd)"
+PREFS="${MULTI_AGENT_PREFS:-$HOME/.claude/multi-agent-preferences.json}"
+CURL="${JIRA_PUBLISH_CURL:-curl}"
+
+ISSUE=""
+BODY_FILE=""
+TARGET="comment"
+MODE="append"
+CONFIRM=0
+DRY_RUN=0
+BACKUP_DIR="${JIRA_BACKUP_DIR:-$HOME/.claude/logs/multi-agent/jira-backups}"
+
+die() { echo "$1" >&2; exit "${2:-64}"; }
+
+while [ "$#" -gt 0 ]; do
+  case "$1" in
+    --issue) ISSUE="${2:-}"; shift 2 ;;
+    --body-file) BODY_FILE="${2:-}"; shift 2 ;;
+    --target) TARGET="${2:-}"; shift 2 ;;
+    --mode) MODE="${2:-}"; shift 2 ;;
+    --backup-dir) BACKUP_DIR="${2:-}"; shift 2 ;;
+    --confirm-overwrite) CONFIRM=1; shift ;;
+    --dry-run) DRY_RUN=1; shift ;;
+    -h|--help) sed -n '2,40p' "$0"; exit 0 ;;
+    *) die "unknown argument: $1" ;;
+  esac
+done
+
+[ -n "$ISSUE" ] || die "usage: jira-publish.sh --issue KEY --body-file FILE [--target comment|description]"
+[ -n "$BODY_FILE" ] || die "usage: jira-publish.sh --issue KEY --body-file FILE [--target comment|description]"
+[ -f "$BODY_FILE" ] || die "body file not found: $BODY_FILE"
+case "$TARGET" in comment|description) ;; *) die "--target must be comment or description, got: $TARGET" ;; esac
+case "$MODE" in append|replace) ;; *) die "--mode must be append or replace, got: $MODE" ;; esac
+
+ESCAPER=""
+for cand in "$SELF_DIR/../scripts/jira-wiki-escape.mjs" "$HOME/.claude/scripts/jira-wiki-escape.mjs"; do
+  [ -f "$cand" ] && { ESCAPER="$cand"; break; }
+done
+[ -n "$ESCAPER" ] || die "jira-wiki-escape.mjs not found next to lib/ or in ~/.claude/scripts" 4
+
+HOST="${JIRA_HOST:-}"
+if [ -z "$HOST" ] && [ -f "$PREFS" ]; then
+  HOST=$(jq -r '.global.hosts.jira // empty' "$PREFS" 2>/dev/null || echo "")
+fi
+[ -n "$HOST" ] || die "no Jira host: set JIRA_HOST or prefs .global.hosts.jira" 4
+HOST="${HOST#https://}"; HOST="${HOST#http://}"; HOST="${HOST%/}"
+
+TOKEN="${JIRA_TOKEN:-}"
+if [ -z "$TOKEN" ]; then
+  key="${JIRA_TOKEN_KEY:-}"
+  if [ -z "$key" ] && [ -f "$PREFS" ]; then
+    key=$(jq -r '.global.keychainMapping.jira // empty' "$PREFS" 2>/dev/null || echo "")
+  fi
+  [ -n "$key" ] || die "no Jira token: set JIRA_TOKEN or map prefs .global.keychainMapping.jira" 4
+  TOKEN=$("$SELF_DIR/credential-store.sh" get "$key" 2>/dev/null || echo "")
+  [ -n "$TOKEN" ] || die "Jira token not in the credential store under: $key" 4
+fi
+
+auth_cfg() { printf 'header = "Authorization: Bearer %s"\n' "$1"; }
+api() { "$CURL" -sS -m 30 -K <(auth_cfg "$TOKEN") -H "Content-Type: application/json" "$@"; }
+
+WORK="$(mktemp -d)"
+trap 'rm -rf "$WORK"' EXIT
+
+node "$ESCAPER" "$BODY_FILE" > "$WORK/new.txt"
+
+if [ "$TARGET" = "comment" ]; then
+  if [ "$DRY_RUN" = "1" ]; then
+    echo "dry-run: would POST a comment to $ISSUE ($(wc -l < "$WORK/new.txt" | tr -d ' ') lines)"
+    cat "$WORK/new.txt"
+    exit 0
+  fi
+  jq -n --rawfile body "$WORK/new.txt" '{body: $body}' > "$WORK/payload.json"
+  http=$(api -o "$WORK/resp.json" -w '%{http_code}' -X POST \
+    --data-binary @"$WORK/payload.json" \
+    "https://$HOST/rest/api/2/issue/$ISSUE/comment") || http="000"
+  case "$http" in
+    20*) echo "comment posted to $ISSUE (nothing was overwritten)" ;;
+    *) echo "Jira comment POST failed with HTTP $http" >&2; sed -n '1,5p' "$WORK/resp.json" >&2; exit 5 ;;
+  esac
+  exit 0
+fi
+
+# --- description: read before write ------------------------------------------
+http=$(api -o "$WORK/issue.json" -w '%{http_code}' \
+  "https://$HOST/rest/api/2/issue/$ISSUE?fields=description") || http="000"
+case "$http" in
+  200) ;;
+  *) echo "could not read the current description of $ISSUE (HTTP $http)" >&2; exit 5 ;;
+esac
+jq -r '.fields.description // ""' "$WORK/issue.json" > "$WORK/existing.txt"
+
+existing_bytes=$(wc -c < "$WORK/existing.txt" | tr -d ' ')
+existing_lines=$(grep -c . "$WORK/existing.txt" || true)
+
+mkdir -p "$BACKUP_DIR"
+STAMP=$(date +%Y%m%dT%H%M%S)
+BACKUP="$BACKUP_DIR/$ISSUE-description-$STAMP.txt"
+cp "$WORK/existing.txt" "$BACKUP"
+echo "existing description backed up: $BACKUP ($existing_lines non-empty line(s))"
+
+if [ "$existing_bytes" -le 1 ]; then
+  cp "$WORK/new.txt" "$WORK/final.txt"
+  RESULT="written into an empty description"
+elif [ "$MODE" = "append" ]; then
+  { cat "$WORK/existing.txt"; printf '\n\n----\n\n'; cat "$WORK/new.txt"; } > "$WORK/final.txt"
+  RESULT="appended below the existing description"
+else
+  if [ "$CONFIRM" != "1" ]; then
+    echo "REFUSED: --mode replace would discard $existing_lines non-empty line(s) already in the description of $ISSUE." >&2
+    echo "The current text is saved at $BACKUP. Re-run with --mode append to keep it, or add --confirm-overwrite to replace it deliberately." >&2
+    exit 3
+  fi
+  cp "$WORK/new.txt" "$WORK/final.txt"
+  RESULT="replaced the existing description (backup above)"
+fi
+
+if [ "$DRY_RUN" = "1" ]; then
+  echo "dry-run: would PUT the description of $ISSUE - $RESULT"
+  cat "$WORK/final.txt"
+  exit 0
+fi
+
+jq -n --rawfile body "$WORK/final.txt" '{fields: {description: $body}}' > "$WORK/payload.json"
+http=$(api -o "$WORK/resp.json" -w '%{http_code}' -X PUT \
+  --data-binary @"$WORK/payload.json" \
+  "https://$HOST/rest/api/2/issue/$ISSUE") || http="000"
+case "$http" in
+  20*) echo "description of $ISSUE updated - $RESULT" ;;
+  *) echo "Jira description PUT failed with HTTP $http" >&2; sed -n '1,5p' "$WORK/resp.json" >&2; exit 5 ;;
+esac

package/pipeline/multi-agent-refs/analysis/render.md

@@ -41,12 +41,29 @@ options:
   - label: "Local file"
     description: "analysis/<feature>-<platform>.md in each selected repo's working tree"
   - label: "Confluence page"
-  - label: "Jira description"
+  - label: "Jira issue"
+    description: <localized: "As a comment by default; writing the description is a separate, explicit choice">
 ```
 
 Conditional follow-ups:
 - If `Confluence` selected: ask `header="Parent page"`, free-text via Other for the parent page key or URL. One Confluence page per platform is created under this parent, each titled `<Feature> - <Platform>`.
-- If `Jira` selected: if Step 5 Q4 produced Jira IDs, AskUserQuestion (single-select) to pick which one; otherwise ask via Other. Per Locked decision 9 + design choice "single description with platform separators", the chosen issue receives one combined description body holding all per-platform sections under `h2. Platform: <X>` separators (wiki markup  -  the description field does not render Markdown; conversion happens at dispatch, see Phase 4).
+- If `Jira` selected: if Step 5 Q4 produced Jira IDs, AskUserQuestion (single-select) to pick which one; otherwise ask via Other. Per Locked decision 9 + design choice "single description with platform separators", the chosen issue receives one combined body holding all per-platform sections under `h2. Platform: <X>` separators (wiki markup  -  neither the comment nor the description field renders Markdown; conversion happens at dispatch, see Phase 4).
+
+  Then ask **where in the issue it goes**, because two of the three answers can destroy text somebody else wrote:
+
+  ```
+  header: "Jira write"
+  question: <localized: "Where should the analysis go on {ISSUE-KEY}?">
+  options:
+    - label: "Comment"
+      description: <localized: "Added as a new comment. Nothing existing is touched.">   # pre-selected
+    - label: "Description - append"
+      description: <localized: "Kept below the current description, separated by a rule.">
+    - label: "Description - replace"
+      description: <localized: "Replaces the current description. Its text is backed up first and the run tells you what was there.">
+  ```
+
+  `Comment` is pre-selected and is the default on any non-answer, including autopilot. The description of an issue is often the analyst's original requirement text, and an analysis run is not a reason to lose it. Result: `state.analysisSpec.outputs.jira = { key, target: "comment"|"description", mode: "append"|"replace" }`.
 
 Result: `state.analysisSpec.outputs.requested[]`.
 
@@ -68,7 +85,7 @@ Iterate `state.analysisSpec.outputs.requested`. For each target:
 |--------|--------|
 | Local | For each per-platform draft, `cp /tmp/analysis-<feature-slug>-<ts>/<feature>-<platform>.md` into `analysis/<feature>-<platform>.md` in the matching repo's working tree. When multiple repos exist for the same platform, the file is duplicated into each and the dispatch report lists every destination. **No commit.** |
 | Confluence | Re-humanize each per-platform draft with `formal-stakeholder` tone. One Confluence page per platform under the chosen parent, titled `<Feature> - <Platform>`. Cross-link siblings inside each page via `<ac:link><ri:page ri:content-title="<Feature> - <OtherPlatform>"/></ac:link>`. Markdown -> storage XML via `$HOME/.claude/multi-agent-refs/channels/confluence.md`. Re-emit on existing pages uses PUT with version bump. |
-| Jira | Re-humanize the combined body with `informal-technical` tone. Concatenate per-platform drafts under `h2. Platform: iOS`, `h2. Platform: Android`, `h2. Platform: Backend`, `h2. Platform: Frontend` separators (in the order platforms were selected), then run the whole body through the markdown → Jira wiki conversion table in `$HOME/.claude/multi-agent-refs/channels/jira.md`  -  the `description` field renders wiki markup, so raw `##`/`**`/backticks arrive as literal text. Write with `PUT /rest/api/2/issue/{key}` body `{"fields": {"description": <converted body>}}` (`channels/jira.md` documents only the comment POST; the description update is this PUT). Same rawfile + `--data-binary` transport rules. |
+| Jira | Re-humanize the combined body with `informal-technical` tone. Concatenate per-platform drafts under `h2. Platform: iOS`, `h2. Platform: Android`, `h2. Platform: Backend`, `h2. Platform: Frontend` separators (in the order platforms were selected), then run the whole body through the markdown → Jira wiki conversion table in `$HOME/.claude/multi-agent-refs/channels/jira.md`  -  both the comment body and the `description` field render wiki markup, so raw `##`/`**`/backticks arrive as literal text. Write the converted body to a file and publish it with `$HOME/.claude/lib/jira-publish.sh`, never with a hand-rolled `curl`: <br><br>`bash "$HOME/.claude/lib/jira-publish.sh" --issue "$KEY" --body-file "$F" --target comment` <br>`bash "$HOME/.claude/lib/jira-publish.sh" --issue "$KEY" --body-file "$F" --target description --mode append` <br><br>The script owns the parts that are easy to get wrong: it runs `jira-wiki-escape.mjs` on the body, resolves host + token without putting either in argv, and on the description path it GETs the current value, writes it to a backup under `~/.claude/logs/multi-agent/jira-backups/` and reports the path, appends below a `----` rule by default, and **refuses with exit 3** when `--mode replace` would discard a non-empty description unless `--confirm-overwrite` is passed. Exit 3 is reported to the user with the backup path, never retried with the flag added automatically  -  only the user's explicit "Description - replace" answer from Phase 3.5 supplies it. `--dry-run` previews the exact final body without writing. |
 
 **Output capture**: fill `state.analysisSpec.outputs.localPaths[]` (one entry per per-platform-per-repo write), `outputs.confluencePageUrls[]` (one entry per platform), `outputs.jiraIssueKey` (single string).
 

package/pipeline/multi-agent-refs/channels/jira.md

@@ -55,7 +55,8 @@ The links are pulled from `agent-state.json.contextLinks[]` (see Phase 0 link ex
 3. Run the assembled body through the `humanizer` skill (see Hard rules below).
 4. Apply Cross-link injection (PR URL on line 1).
 5. Run Wiki markup conversion.
-6. POST.
+6. Run the emoticon escape program on the converted body (see *Emoticon escaping*).
+7. POST.
 ```
 
 ## Wiki markup conversion
@@ -79,7 +80,16 @@ The `\|` sequences in the two link/table rows are this table's own escape for a
 
 ### Emoticon escaping (required)
 
-Jira's wiki renderer turns ASCII sequences into emoticon images. This is not something the pipeline writes; Jira manufactures it at render time, which is why a comment can show a smiley nobody typed. Escape every sequence below with a leading backslash before POST:
+Jira's wiki renderer turns ASCII sequences into emoticon images. This is not something the pipeline writes; Jira manufactures it at render time, which is why a comment can show a smiley nobody typed. The escape is a program, not a habit  -  run the converted body through it and POST the output:
+
+```bash
+node "$HOME/.claude/scripts/jira-wiki-escape.mjs" /tmp/channels-$TASK_ID-jira.txt \
+  > /tmp/channels-$TASK_ID-jira-escaped.txt
+```
+
+It prefixes a backslash to each sequence below, skips `{code}` / `{noformat}` blocks, and is idempotent, so running it twice is harmless. `--check` is the inverse: it exits 1 and prints `line: sequence` for every unescaped hit, which is what a gate or a pre-POST assertion calls.
+
+The sequences it covers:
 
 | Sequence | Renders as | Escaped |
 |---|---|---|
@@ -91,13 +101,17 @@ Jira's wiki renderer turns ASCII sequences into emoticon images. This is not som
 | `(on)` `(off)` | lightbulb icons | `\(on)` `\(off)` |
 | `(*)` `(*r)` `(*g)` `(*b)` `(*y)` | star icons | `\(*)` `\(*r)` ... |
 
-The parenthesised forms are the ones that actually bite: `(x)` in a comparison table, `(!)` in a caution note, and `(/)` in a path fragment are ordinary technical prose, and each becomes an image. Apply the escape AFTER the markdown conversion above and BEFORE the POST, and skip it inside `{code}` / `{noformat}` blocks, where Jira does not expand emoticons anyway.
+The parenthesised forms are the ones that actually bite: `(x)` in a comparison table, `(!)` in a caution note, and `(/)` in a path fragment are ordinary technical prose, and each becomes an image. The face forms bite through code: a Swift selector like `login(source:input:)` ends in `:)`, and the comment renders a smiley in the middle of a file reference.
+
+The program runs AFTER the markdown conversion above and BEFORE the POST. Order is load-bearing in both directions: run it earlier and the conversion re-introduces sequences behind it; skip it and `{{...}}` monospace does not save you, because Jira parses emoticons inside monospace too.
+
+Do not hand-apply this table. It was hand-applied for several releases and a smiley reached a ticket anyway  -  a long comment gives the eye no reason to stop on the `:)` at the end of a selector.
 
 Lines outside these patterns pass through verbatim. Multi-paragraph blocks are joined with one blank line.
 
 Every row above is load-bearing, including the ones that look cosmetic. The table must cover each construct the section templates in this file actually emit  -  `##` for the three required headings, `**Given**` / `**When**` / `**Then**` in the test-scenario skeleton, and `1.`-numbered scenarios. A missing row does not degrade gracefully: the "pass through verbatim" fallback POSTs `## Test Senaryoları` and `**Given**` as literal text, so the comment renders with visible `##` and stray asterisks. Single `*bold*` in Markdown means *italic* in Jira wiki  -  never map `**bold**` to `*bold*` by dropping one asterisk mechanically without checking the source was bold, not italic.
 
-There is no markdown→Jira-wiki converter program in the pipeline (`lib/` ships `md2confluence-v3.py` for Confluence only). This table is applied by the model, by hand, which is exactly why it has to be complete.
+There is no markdown→Jira-wiki converter program in the pipeline (`lib/` ships `md2confluence-v3.py` for Confluence only, and `scripts/jira-wiki-escape.mjs` covers the emoticon step alone). This conversion table is applied by the model, by hand, which is exactly why it has to be complete.
 
 ## Cross-link injection
 
@@ -128,10 +142,12 @@ Authorization: Bearer $JIRA_TOKEN
 Content-Type: application/json
 ```
 
-Body assembled with `jq --rawfile` + `curl --data-binary @file`:
+Body assembled with `jq --rawfile` + `curl --data-binary @file`, from the escaped file that *Emoticon escaping* produced:
 
 ```bash
-jq -n --rawfile body /tmp/channels-$TASK_ID-jira.txt '{body: $body}' \
+node "$HOME/.claude/scripts/jira-wiki-escape.mjs" --check /tmp/channels-$TASK_ID-jira-escaped.txt \
+  || { echo "unescaped Jira emoticon in the body - do not POST" >&2; exit 1; }
+jq -n --rawfile body /tmp/channels-$TASK_ID-jira-escaped.txt '{body: $body}' \
   > /tmp/channels-$TASK_ID-jira-payload.json
 curl -s -X POST -H "Authorization: Bearer $JIRA_TOKEN" \
      -H "Content-Type: application/json" \
@@ -141,6 +157,17 @@ curl -s -X POST -H "Authorization: Bearer $JIRA_TOKEN" \
 
 The dispatch summary line includes the comment URL with `?focusedCommentId=...` so the user can paste it into Slack/Teams.
 
+### Writing the issue description (not a comment)
+
+A comment is additive; the `description` field is not. Replacing it destroys whatever was there, which is usually the reporter's own text. There is no hand-rolled `PUT /rest/api/2/issue/{key}` anywhere in the pipeline and there must not be one: the only supported path is
+
+```bash
+bash "$HOME/.claude/lib/jira-publish.sh" --issue "$KEY" --body-file "$F" \
+  --target description --mode append
+```
+
+which escapes the body, GETs the current description, saves it under `~/.claude/logs/multi-agent/jira-backups/`, appends below a `----` rule, and exits 3 rather than replacing a non-empty field without `--confirm-overwrite`. The same script posts comments (`--target comment`), which is what an unattended run should choose when it is not sure. Contract and gate: `analysis/render.md` Phase 4 and `scripts/smoke-jira-publish.sh`.
+
 ## Wiki → Jira auto-link triad
 
 When the **Wiki** adapter writes pages on the same run AND `prefs.global.wikiToJiraComment === true`, the Wiki adapter also posts a humanizer-passed Jira comment summarizing wiki pages (component name + variant count + wiki URL). That secondary comment is independent of this adapter  -  both can coexist on the same issue. Full contract: `$HOME/.claude/multi-agent-refs/issue-jira-triad.md`.

package/pipeline/multi-agent-refs/generate-issue.md

@@ -201,7 +201,9 @@ This gate has no bypass. No flag, mode, or preference suppresses it.
 ### [10/12] Create
 
 ```bash
-jq -n --rawfile desc /tmp/generate-issue-$$.txt \
+node "$HOME/.claude/scripts/jira-wiki-escape.mjs" /tmp/generate-issue-$$.txt \
+  > /tmp/generate-issue-$$-escaped.txt
+jq -n --rawfile desc /tmp/generate-issue-$$-escaped.txt \
   --arg key "$PROJECT_KEY" --arg type "$ISSUE_TYPE" --arg summary "$SUMMARY" \
   '{fields: {project: {key: $key}, issuetype: {name: $type}, summary: $summary, description: $desc}}' \
   > /tmp/generate-issue-$$-payload.json