[CTX] comments are read by humans first. This release makes their structure visible.
Added — optional visual structure
Every section used to render at the same visual weight: a blocker looked like a decision looked like a Done bullet, and a long handoff pushed Next: — the line a reader always wants — below a twelve-bullet Done: list.
Three treatments, all optional and render-only:
| Section | Jira (ADF) | GitHub / GitLab |
|---|---|---|
Blockers: / Risk: |
panel, panelType: warning |
> [!WARNING] |
Done: over ~6 bullets |
expand |
<details><summary> |
after the Status: block |
rule |
--- |
The logical format is untouched. A plain comment is exactly as compliant as a decorated one, and short comments should stay plain — a three-line [CTX] gains nothing from a collapsible section.
The rule behind it
attrsmust never carry meaning. Every label and value lives in a text node inside the container. A container title or<summary>is a duplicate affordance, never the sole carrier of a label.
This came out of a live probe rather than a preference. A comment that put Done: in expand.attrs.title lost the label entirely on read while still validating compliant — validate-ctx.sh only tests Status:/Next:, so it structurally cannot see that class of loss. Had it shipped, every /resume would have quietly degraded.
The same reasoning puts status lozenges, inlineCard smart links and date nodes on an explicit forbidden list. They are the best-looking options on offer, which is exactly why they are named rather than left to judgment.
Reader contract
Containers make block-aware extraction a contract rather than an assumption. A naive walk over top-level nodes concatenates a container's contents — two Done: bullets inside an expand come back as one run-on line — and nothing downstream catches it, because the body still has its skeleton and still classifies compliant.
tracker-adapter › Jira read path now states the requirement and names the failure. New golden fixture examples/compliant-nested.txt locks the extracted shape into the test suite.
Compatibility
- The
[CTX]v1 contract is unchanged —Header + Status: + Next:remain the only required elements. - Every treatment is additive and optional; nothing needs rewriting.
- GitLab alerts require GitLab ≥ 17.10. Below that, and on any renderer lacking a treatment, emit the plain labelled section rather than a half-rendered container.
Upgrading
Nothing to do. If you pin, move the pin to v0.8.3.