From 6d42b783cecbef44b4a94e021a42d0a391543fb7 Mon Sep 17 00:00:00 2001 From: William Thorsen Date: Wed, 12 Aug 2026 22:35:22 -0700 Subject: [PATCH 1/2] agents|fix: Require plain bullets on update-jira-ticket's Markdown path Adds a step to `update-jira-ticket`'s Markdown path directing that task-list syntax be converted to plain `-` bullets before submission. Jira's Markdown-to-ADF converter does not map `- [ ]` to a task item; it escapes the brackets, so the line persists as a bullet reading `\[ \] ...`. The step names artefact-sourced content as in scope, since `design-and-plan` and `create-ticket` both template acceptance criteria as checkboxes. The step also records that native checkboxes exist only as ADF `taskList` / `taskItem` nodes and that `contentFormat` governs the whole field rather than a section of it, so a checklist does not warrant authoring the description as ADF. The path's existing guidance reserves ADF for fidelity Markdown cannot express, which describes task lists exactly, so the carve-out is stated rather than left to inference. --- packages/agents/content/skills/update-jira-ticket/SKILL.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/packages/agents/content/skills/update-jira-ticket/SKILL.md b/packages/agents/content/skills/update-jira-ticket/SKILL.md index 8c4cf4a1..1d29f74d 100644 --- a/packages/agents/content/skills/update-jira-ticket/SKILL.md +++ b/packages/agents/content/skills/update-jira-ticket/SKILL.md @@ -23,7 +23,8 @@ Use this branch when a `contentFormat`-based tool (e.g. `editJiraIssue`) is avai 1. **Author Markdown.** Prefer a local Markdown artefact when one exists; otherwise compose in Markdown. Pass it via `contentFormat: "markdown"`. 2. **Prefer Markdown over ADF.** Reserve `contentFormat: "adf"` for content whose fidelity Markdown cannot express (panels, status lozenges, expand blocks, layout columns). ADF is full-fidelity JSON but verbose and harder to author, so reach for it only when Markdown genuinely falls short. -3. **Do not sanitize.** The HTML allowlist, the composition rules, and the pre-flight checker under [HTML path](#html-path) **do not apply** here, and you must **not** run `update-jira-ticket.mjs`. Those rules exist solely to survive Jira's HTML→ADF conversion, and that converter is never invoked when you submit Markdown or ADF — so there is nothing for them to guard against. Rendering content to allowlist HTML and running the checker on this path is wasted work. +3. **Write checklists as plain bullets.** Jira's Markdown converter does not map `- [ ]` / `- [x]` to ADF task items. It escapes the brackets, so the line persists as a bullet reading `\[ \] ...`. Convert task-list syntax to plain `-` bullets before submitting, including when the source is a local artefact that uses checkboxes, as ticket artefacts from `design-and-plan` and `create-ticket` do. Native checkboxes exist only as ADF `taskList` / `taskItem` nodes, and `contentFormat` governs the whole field rather than a section of it, so a checklist never justifies authoring the entire description as ADF. +4. **Do not sanitize.** The HTML allowlist, the composition rules, and the pre-flight checker under [HTML path](#html-path) **do not apply** here, and you must **not** run `update-jira-ticket.mjs`. Those rules exist solely to survive Jira's HTML→ADF conversion, and that converter is never invoked when you submit Markdown or ADF — so there is nothing for them to guard against. Rendering content to allowlist HTML and running the checker on this path is wasted work. That is the entire path. Everything under [HTML path](#html-path) is irrelevant when a `contentFormat` tool is available. From 5ba2f5fed0e3a33303bf94980b70cd1a7fa4ade4 Mon Sep 17 00:00:00 2001 From: William Thorsen Date: Wed, 12 Aug 2026 22:35:59 -0700 Subject: [PATCH 2/2] agents|fix: Rule out checkbox brackets on update-jira-ticket's HTML path Adds a task-list rule to `update-jira-ticket`'s HTML path: the conversion step now prescribes a plain `
  • `, and the antipattern list names carrying the brackets through as literal text. The allowlist excludes `input`, so a checkbox has no HTML representation, but `
  • [ ] ...
    • ` is valid allowlist HTML that the pre-flight checker passes, leaving the same literal brackets in the Jira description that the Markdown path produces. The rule lives in the guidance rather than in the pre-flight checker, whose every rule maps to a documented `INVALID_INPUT` trigger; bracket text triggers none. --- packages/agents/content/skills/update-jira-ticket/SKILL.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/packages/agents/content/skills/update-jira-ticket/SKILL.md b/packages/agents/content/skills/update-jira-ticket/SKILL.md index 1d29f74d..48b39c35 100644 --- a/packages/agents/content/skills/update-jira-ticket/SKILL.md +++ b/packages/agents/content/skills/update-jira-ticket/SKILL.md @@ -35,7 +35,7 @@ Use this branch only when the available tool is the HTML-surface `update_jira_is ### The correct path for the HTML tool 1. **Source content as Markdown.** Prefer a local Markdown artefact when one exists. Otherwise, compose in Markdown first — never author HTML directly. -2. **Convert Markdown to HTML using only the allowlist below.** Anything outside the allowlist must be omitted or rewritten. +2. **Convert Markdown to HTML using only the allowlist below.** Anything outside the allowlist must be omitted or rewritten. Task-list syntax (`- [ ]` / `- [x]`) becomes a plain `
  • `; never carry the brackets through as literal text. 3. **Run the pre-flight checker against the rendered HTML.** Fix everything it flags, then re-run until it returns `ok: true`. See [Pre-flight checker](#pre-flight-checker) for the contract. 4. **Pass the HTML inline** to `description_html` or `comment_html`. 5. **Never pass a file path** to `description_html` / `comment_html`. File-path mode is forbidden — it has been observed to fail with `INVALID_INPUT`. @@ -222,6 +222,7 @@ If recorded failures distribute across truly **unknown classes** (no clear patte - Skipping the pre-flight check before invoking `update_jira_issue` / `create_jira_issue`. - Creating a probe ticket without the `mcp-probe` label, the deterministic title, and the description prefix. - Hand-authoring HTML containing constructs outside the allowlist. +- Carrying `- [ ]` / `- [x]` brackets into `
  • ` text instead of rendering a plain bullet. - Combining `` with other inline marks on the same text run. - Using named HTML entities other than `&`, `<`, `>` in text content. - Passing a file path to `description_html` / `comment_html`.