omakit 0.1.6 → 0.1.8

package/tools/marketplace/doctor.mjs

@@ -13,33 +13,51 @@
 // contract is read from, and the procedure in docs/UPSTREAM_CONTRACT.md requires
 // re-proving transport parity and committing the evidence afterwards. An
 // `upgrade` that quietly advanced the pin would break the one guarantee this
-// tool sells. So doctor reports that the pin is behind and prints the procedure.
+// tool sells. So doctor reports that the pin is behind, and that is all it
+// does: the procedure is the maintainer's, it lives in that document and in
+// this comment, and it is never printed, because the person running doctor
+// is a user of a package that does not even ship docs/. What a user can do
+// is run `omakit upgrade`, since a newer omakit may already carry the new
+// pin, and otherwise open an issue naming the paths that moved.
 //
 // That the pin goes stale unnoticed is, of course, exactly the defect class
 // `omakit watch` exists to report. It would be poor form not to apply it here.
 //
 // And "behind" is not the same as "behind in something omakit reads". Measured
 // on 2026-09-13 (docs/MEASUREMENTS.md M7): 4,201 of the marketplace's 4,293
-// commits in 30 days touched only registry.json, which omakit now reads live,
+// commits in 30 days touched only registry.json, which omakit reads live,
 // while nothing under scripts/ or .github/ISSUE_TEMPLATE/ changed since the
 // pin. A doctor that only said "behind" would say it about every run. So it
 // compares each path in PIN_PATHS between the pin and HEAD, by tree or blob
-// id, and names the ones that moved.
+// id, and splits the ones that moved by the same list registry.mjs reads
+// live from: the two data files, which a moved HEAD cannot make stale, and
+// everything else, which only a new pin can carry. Measured on 0.1.7: with
+// only registry.json and site/catalog.json moved, doctor said `note` and
+// pointed a user at docs/UPSTREAM_CONTRACT.md, though the pin was behind in
+// nothing the tool uses.
 
 import { execFileSync } from "node:child_process"
 import { readFileSync } from "node:fs"
 import { join } from "node:path"
 import { MARKETPLACE_PIN, PIN_PATHS, marketplacePinDir, pinDiskUsage, pinIsSparse, requirePin } from "./pin.mjs"
+import { LIVE_PATHS } from "./registry.mjs"
 import { credential, defaultBranchHead, getJson, UNAUTHENTICATED_LIMIT, GitHubError } from "./github.mjs"
 import { latestOnRegistry, upgradeCommand } from "./upgrade.mjs"
 import { pathHint } from "./path-hint.mjs"
 
+/** "git+https://github.com/owner/name.git" in package.json -> "https://github.com/owner/name", or null. */
+function repositoryPage(repository) {
+  const url = typeof repository === "string" ? repository : repository?.url
+  const match = String(url || "").match(/github\.com[/:]([^/]+)\/([^/]+?)(?:\.git)?\/?$/)
+  return match ? `https://github.com/${match[1]}/${match[2]}` : null
+}
+
 function tool(repoRoot) {
   try {
     const pkg = JSON.parse(readFileSync(join(repoRoot, "package.json"), "utf8"))
-    return { name: pkg.name, version: pkg.version, engines: pkg.engines?.node || null }
+    return { name: pkg.name, version: pkg.version, engines: pkg.engines?.node || null, repository: repositoryPage(pkg.repository) }
   } catch {
-    return { name: "omakit", version: "unknown", engines: null }
+    return { name: "omakit", version: "unknown", engines: null, repository: null }
   }
 }
 
@@ -102,40 +120,65 @@ export async function changedPinPaths({ pinDir, headCommit, pinCommit = MARKETPL
   return changed
 }
 
+/** A PIN_PATHS pattern as a path: "/site/catalog.json" -> "site/catalog.json". */
+const asPath = (pattern) => pattern.replace(/^\/|\/$/g, "")
+
+/** "a", "a and b", "a, b and c". */
+function list(items) {
+  return items.length < 3 ? items.join(" and ") : `${items.slice(0, -1).join(", ")} and ${items.at(-1)}`
+}
+
 /**
- * Full pin evidence for machines; human output deliberately keeps short
- * hashes. `changedPaths` is the answer from changedPinPaths(); null when the
- * comparison was not made, and then the detail says only that HEAD moved.
+ * The pin against the marketplace's HEAD, for a user. `changedPaths` is the
+ * answer from changedPinPaths(), split by LIVE_PATHS into `readLive`, the
+ * data files a moved HEAD cannot make stale because registry.mjs reads them
+ * from HEAD, and `pinned`, everything only a new pin can carry. Only the
+ * second set is worth a note; the action for it is a user's, not the
+ * maintainer's. Null when the comparison was not made, and then the detail
+ * says only that HEAD moved. Full commits in the evidence; short ones in
+ * the detail. `issues` is where a user reports a pinned path that moved,
+ * read from package.json by the caller.
  */
-export function pinFreshness(identity, head, changedPaths = null) {
+export function pinFreshness(identity, head, changedPaths = null, { issues = null } = {}) {
   const current = head.commit === identity.commit
   const branch = head.branch || "default"
+  const changed = current ? [] : changedPaths || []
+  const readLive = changed.filter((pattern) => LIVE_PATHS.includes(asPath(pattern)))
+  const pinned = changed.filter((pattern) => !LIVE_PATHS.includes(asPath(pattern)))
+  const where = `pin ${identity.commit.slice(0, 7)}; marketplace ${branch} at ${head.commit.slice(0, 7)}`
   const moved = changedPaths === null
-    ? ""
-    : changedPaths.length
-      ? `; changed since the pin: ${changedPaths.join(", ")}`
-      : "; every path omakit reads is unchanged since the pin"
+    ? "; the paths omakit reads were not compared"
+    : pinned.length
+      ? `; changed since the pin: ${pinned.join(", ")}${readLive.length ? ` (${list(readLive.map(asPath))} moved too, and ${readLive.length === 1 ? "that is" : "those are"} read live)` : ""}`
+      : readLive.length
+        ? `; only ${list(readLive.map(asPath))} moved, and ${readLive.length === 1 ? "that is" : "those are"} read live`
+        : "; nothing omakit reads moved"
+  const stale = !current && (changedPaths === null || pinned.length > 0)
   return {
     id: "pin.freshness",
-    state: current ? "ok" : "advice",
-    detail: current
-      ? `the pin is the marketplace's current ${branch}-branch HEAD`
-      : `the pin is ${identity.commit.slice(0, 7)}; the marketplace's ${branch} branch is now at ${head.commit.slice(0, 7)}${moved}`,
-    action: current ? null : "Bumping the pin is a deliberate change: docs/UPSTREAM_CONTRACT.md has the procedure, which ends in re-proving parity and committing its evidence. Nothing here does it for you.",
+    state: stale ? "advice" : "ok",
+    detail: current ? `the pin is the marketplace's current ${branch}-branch HEAD` : `${where}${moved}`,
+    action: stale
+      ? `A newer omakit may already carry the new pin: run \`omakit upgrade\`. If it does not, open an issue${issues ? ` at ${issues}/issues` : ""} naming the paths above.`
+      : null,
     evidence: {
       pinCommit: identity.commit,
       marketplaceHead: head.commit,
       branch,
-      ...(changedPaths === null ? {} : { changedPaths: current ? [] : changedPaths }),
+      ...(changedPaths === null ? {} : { changedPaths: changed, readLive, pinned }),
     },
   }
 }
 
 /**
- * @param {{ repoRoot: string, offline?: boolean, env?: object, npmPrefix?: () => string|null }} options
- *   `env` and `npmPrefix` are injectable for tests of the PATH check.
+ * @param {{ repoRoot: string, offline?: boolean, env?: object, npmPrefix?: () => string|null,
+ *           resolveHead?: typeof defaultBranchHead, latest?: typeof latestOnRegistry }} options
+ *   `env` and `npmPrefix` are injectable for tests of the PATH check;
+ *   `resolveHead` and `latest` for tests of the two checks that read the
+ *   network, whose defaults are the tool's one HEAD resolver and its one
+ *   registry read.
  */
-export async function doctor({ repoRoot, offline = false, onPhase, env = process.env, npmPrefix }) {
+export async function doctor({ repoRoot, offline = false, onPhase, env = process.env, npmPrefix, resolveHead = defaultBranchHead, latest: latestVersion = latestOnRegistry }) {
   // Optional: told what is being read while the network answers. Never
   // affects the result.
   const phase = onPhase || (() => {})
@@ -185,13 +228,13 @@ export async function doctor({ repoRoot, offline = false, onPhase, env = process
   if (!offline && identity) {
     phase("reading the marketplace's current default-branch HEAD")
     try {
-      const head = await defaultBranchHead(MARKETPLACE_PIN.repository)
+      const head = await resolveHead(MARKETPLACE_PIN.repository)
       let changedPaths = []
       if (head.commit !== identity.commit) {
         phase("comparing each path omakit reads between the pin and HEAD")
         changedPaths = await changedPinPaths({ pinDir: dir, headCommit: head.commit, pinCommit: identity.commit })
       }
-      checks.push(pinFreshness(identity, head, changedPaths))
+      checks.push(pinFreshness(identity, head, changedPaths, { issues: self.repository }))
     } catch (error) {
       add("pin.freshness", "unknown", `could not read the marketplace's HEAD (${error.code || "error"})`,
         error.code === "network-unavailable" ? "Connect to the network, or pass --offline to skip the two checks that need it." : null,
@@ -199,7 +242,7 @@ export async function doctor({ repoRoot, offline = false, onPhase, env = process
     }
 
     phase("asking the npm registry for the newest published version")
-    const latest = await latestOnRegistry(self.name)
+    const latest = await latestVersion(self.name)
     if (latest) {
       const current = latest === self.version
       add("omakit.latest", current ? "ok" : "advice",

package/tools/marketplace/form.mjs

@@ -27,6 +27,8 @@ import { requirePin } from "./pin.mjs"
 
 export const SUBMIT_FORM_PATH = ".github/ISSUE_TEMPLATE/submit-plugin.yml"
 export const OFFICIAL_SUBMISSION_MODULE = "scripts/submission.mjs"
+export const VERIFY_FORM_PATH = ".github/ISSUE_TEMPLATE/verify-plugin.yml"
+export const OFFICIAL_VERIFICATION_MODULE = "scripts/plugin-verification-request.mjs"
 
 export class ContractError extends Error {
   constructor(code, message) {
@@ -50,8 +52,8 @@ function loadOfficial(pinDir) {
   return import(pathToFileURL(join(pinDir, OFFICIAL_SUBMISSION_MODULE)).href)
 }
 
-function fieldsOf(form) {
-  if (!Array.isArray(form?.body)) throw new ContractError("form-unreadable", `${SUBMIT_FORM_PATH} has no body`)
+function fieldsOf(form, formPath = SUBMIT_FORM_PATH) {
+  if (!Array.isArray(form?.body)) throw new ContractError("form-unreadable", `${formPath} has no body`)
   return form.body
     .filter((item) => item && item.type !== "markdown")
     .map((item) => ({
@@ -65,12 +67,12 @@ function fieldsOf(form) {
     }))
 }
 
-function only(fields, predicate, what) {
+function only(fields, predicate, what, formPath = SUBMIT_FORM_PATH) {
   const found = fields.filter(predicate)
   if (found.length !== 1) {
     throw new ContractError(
       "form-shape-changed",
-      `${SUBMIT_FORM_PATH} no longer has exactly one ${what} (found ${found.length}); the pin changed shape and the submission contract must be re-read before anything is generated`,
+      `${formPath} no longer has exactly one ${what} (found ${found.length}); the pin changed shape and the submission contract must be re-read before anything is generated`,
     )
   }
   return found[0]
@@ -135,6 +137,36 @@ export async function submissionContract(options = {}) {
   return contract
 }
 
+/**
+ * The route for a plugin that is already listed: the marketplace's other
+ * form, and the one choice on it that lists a newer commit. Both read from
+ * the pin. The choice text is the option as the form spells it, found by the
+ * name the marketplace's own verification module gives that action; the two
+ * must agree, the way the submission form and `scripts/submission.mjs` must,
+ * because a choice retyped here would drift by a word and send a person to
+ * pick something the form no longer offers.
+ *
+ * @param {{ repoRoot?: string, pinDir?: string }} [options]
+ * @returns {Promise<{ formPath: string, name: string, choice: string }>}
+ */
+export async function newerCommitChoice(options = {}) {
+  const pinDir = options.pinDir || requirePin(options.repoRoot).dir
+  const form = parseYaml(readFileSync(join(pinDir, VERIFY_FORM_PATH), "utf8"))
+  const fields = fieldsOf(form, VERIFY_FORM_PATH)
+  const action = only(fields, (f) => f.type === "dropdown" && !f.multiple && f.required, "required single-select dropdown (verification action)", VERIFY_FORM_PATH)
+  const official = await import(pathToFileURL(join(pinDir, OFFICIAL_VERIFICATION_MODULE)).href)
+  const choice = (action.options || []).find((option) => option === official.upstreamUpdateVerificationAction)
+  if (!choice) {
+    throw new ContractError(
+      "form-shape-changed",
+      `${VERIFY_FORM_PATH} offers no "${official.upstreamUpdateVerificationAction}" under ${action.label}; the form and ${OFFICIAL_VERIFICATION_MODULE} at the pin disagree, and nobody is sent to a choice that is not there`,
+    )
+  }
+  const name = typeof form.name === "string" ? form.name.trim() : ""
+  if (!name) throw new ContractError("form-shape-changed", `${VERIFY_FORM_PATH} has no name`)
+  return { formPath: VERIFY_FORM_PATH, name, choice }
+}
+
 /**
  * The form and the marketplace's own constants must describe the same
  * submission. Anything else means the pin is internally inconsistent, and

package/tools/marketplace/registry.mjs

@@ -107,12 +107,32 @@ export function defaultPresentation(presentation, kinds = []) {
   return { category, tags }
 }
 
+/**
+ * "https://github.com/Owner/Name.git" and "owner/name" both become
+ * "owner/name": the path, without surrounding slashes, without a trailing
+ * .git, lowercased. Anything else is "", which matches nothing.
+ */
 function repositorySlug(value) {
+  const text = String(value ?? "").trim()
+  let path
   try {
-    return new URL(String(value)).pathname.replace(/^\/+|\/+$/g, "").replace(/\.git$/i, "").toLowerCase()
+    path = new URL(text).pathname
   } catch {
-    return ""
+    path = /^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/.test(text) ? text : ""
   }
+  return path.replace(/^\/+|\/+$/g, "").replace(/\.git$/i, "").toLowerCase()
+}
+
+/**
+ * The one rule for "the same repository": owner and name, compared
+ * case-insensitively, with a trailing .git ignored. Measured on 0.1.6: the
+ * author's own listed plugin was rendered as a failed check because the
+ * listing and the subject were compared as two strings, so this is the rule
+ * and its test, not a comparison typed where it is needed.
+ */
+export function sameRepository(a, b) {
+  const slug = repositorySlug(a)
+  return Boolean(slug) && slug === repositorySlug(b)
 }
 
 /**
@@ -400,11 +420,14 @@ export function figure(n) {
 
 /**
  * @param {{ id: string, repositoryUrl?: string|null }} subject
- * @returns {{ ok: boolean, problems: Array<{ code: string, detail: string, repository?: string|null, sameRepository?: boolean }> }}
+ * @returns {{ ok: boolean, own: boolean, problems: Array<{ code: string, detail: string, repository?: string|null, sameRepository?: boolean }> }}
  *   A `plugin-id-listed` problem names the repository that lists the id
  *   (`repository`, a slug, or null when the registry does not say) and
  *   whether that is the subject's own (`sameRepository`), because the two
- *   have different remedies: another id, or nothing to submit at all.
+ *   are different states: another id is needed, or the plugin is listed and
+ *   there is nothing to submit. `own` is the second state on its own: the id
+ *   is listed by this repository and no other code fired, so `ok` is false
+ *   and nothing is wrong.
  */
 export function checkIdentity(universe, subject) {
   const problems = []
@@ -425,18 +448,64 @@ export function checkIdentity(universe, subject) {
   }
   if (universe.listedIds.has(id)) {
     const repository = universe.listedBy?.get(id) || null
-    const sameRepository = Boolean(repository && slug && repository === slug)
     problems.push({
       code: "plugin-id-listed",
       detail: `"${id}" is already listed${repository ? ` by ${repository}` : ""}`,
       repository,
-      sameRepository,
+      sameRepository: sameRepository(repository, slug),
     })
   }
   if (slug && universe.listedRepositories.has(slug)) {
     problems.push({ code: "submission-repository-listed", detail: `${slug} is already listed`, repository: slug, sameRepository: true })
   }
-  return { ok: problems.length === 0, problems }
+  // The subject's own listing: the id is listed, by this repository, and
+  // nothing else is wrong with the id. That is not a problem with the
+  // submission, it is the absence of one; the caller reports it as a state.
+  const own = problems.length > 0
+    && problems.some((problem) => problem.code === "plugin-id-listed" && problem.sameRepository)
+    && problems.every((problem) => problem.sameRepository)
+  return { ok: problems.length === 0, own, problems }
+}
+
+/**
+ * What the marketplace records about one listing, for the plugin that is
+ * already listed by its own repository: read from the catalog first, which
+ * carries the verification fields, and from the registry source when the
+ * catalog has no entry. Every field is null when nothing records it; nothing
+ * is guessed.
+ *
+ * @param {{ registry: object, catalog: object }} live
+ * @param {string} id
+ * @returns {{ repository: string|null, id: string, addedAt: string|null, verificationCommit: string|null,
+ *             verificationStatus: string|null, verificationCheckedAt: string|null }|null}
+ */
+export function listingOf(live, id) {
+  const text = (value) => (typeof value === "string" && value ? value : null)
+  const plugin = (Array.isArray(live.catalog?.plugins) ? live.catalog.plugins : []).find((entry) => entry?.id === id)
+  if (plugin) {
+    return {
+      repository: text(plugin.repo),
+      id,
+      addedAt: text(plugin.addedAt) || text(plugin.listedAt),
+      verificationCommit: text(plugin.verificationCommit)?.toLowerCase() || text(plugin.listingValidatedCommit)?.toLowerCase() || null,
+      verificationStatus: text(plugin.verificationStatus),
+      verificationCheckedAt: text(plugin.verificationCheckedAt) || text(plugin.listingValidatedAt),
+    }
+  }
+  const sources = Array.isArray(live.registry?.sources) ? live.registry.sources : Object.values(live.registry?.sources || {})
+  const source = sources.find((entry) => {
+    const ids = entry?.plugins && typeof entry.plugins === "object" && !Array.isArray(entry.plugins) ? Object.keys(entry.plugins) : []
+    return ids.includes(id) || (entry?.automatedSecurityBaseline?.pluginIds || []).includes(id)
+  })
+  if (!source) return null
+  return {
+    repository: text(source.repo),
+    id,
+    addedAt: text(source.addedAt) || text(source.listedAt),
+    verificationCommit: text(source.listingValidatedCommit)?.toLowerCase() || null,
+    verificationStatus: text(source.automatedSecurityBaseline?.outcome),
+    verificationCheckedAt: text(source.listingValidatedAt),
+  }
 }
 
 export { repositorySlug }

package/tools/marketplace/report.mjs

@@ -23,10 +23,11 @@ import {
 
 const body = " ".repeat(GUTTER)
 
-/** The state a check renders in: an advisory failure is a note, not a FAIL, and a check that waited on another is a question. */
+/** The state a check renders in: an advisory failure is a note, not a FAIL, a check that waited on another is a question, and a check a flag skipped says so. */
 function stateOf(check) {
   if (check.verdict === "pass") return "pass"
   if (check.verdict === "unknown") return "unknown"
+  if (check.verdict === "skipped") return "skipped"
   return check.severity === "advisory" ? "advisory" : "fail"
 }
 
@@ -101,10 +102,10 @@ export function renderSubmit(result, { colour = colourEnabled() } = {}) {
   out.push(...field("marketplace", `${result.pin.commit}, baseline ${result.pin.baselineVersion}, ${result.pin.enforcementMode}`, c))
   out.push("")
 
-  // Passing checks run together, and so does a check that waited on another:
-  // both are two quiet lines. Anything else gets a blank line on each side,
-  // collapsed where two blocks meet.
-  const quiet = (state) => state === "pass" || state === "unknown"
+  // Passing checks run together, and so do a check that waited on another
+  // and one a flag skipped: all are two quiet lines. Anything else gets a
+  // blank line on each side, collapsed where two blocks meet.
+  const quiet = (state) => state === "pass" || state === "unknown" || state === "skipped"
   let previous = "pass"
   for (const [index, check] of result.checks.entries()) {
     const state = stateOf(check)
@@ -122,7 +123,26 @@ export function renderSubmit(result, { colour = colourEnabled() } = {}) {
     out.push("")
   }
 
-  if (!result.ready) {
+  if (result.outcome === "listed") {
+    // The third outcome. Nothing was refused and nothing is wrong: the plugin
+    // is listed by this repository, so there is no body and no reproduce
+    // line, and the route to a newer commit is the marketplace's other form.
+    // Measured on 0.1.6: this state was drawn as FAIL and REFUSED, and closed
+    // with "Fix it, then run submit again" under a remedy that said there was
+    // nothing to submit.
+    const listing = result.listing
+    out.push(...verdict("pass", "LISTED", `${listing.id} is already listed by this repository, so the submission form is not the route.`, c))
+    out.push("")
+    out.push(...field("listed", listing.verificationCommit ? c("name", listing.verificationCommit) : "no verification commit recorded", c, { wrapValue: false }))
+    out.push(...continuation(`${listing.verificationStatus || "status unrecorded"}, checked ${listing.verificationCheckedAt || "at an unrecorded time"}, read from the ${listing.source === "head" ? "marketplace's current HEAD" : "pin"}`, c))
+    out.push(...field("local HEAD", c("name", listing.localCommit), c, { wrapValue: false }))
+    out.push(...continuation(listing.sameCommit ? "the same commit" : "not the listed commit", c))
+    out.push("")
+    out.push(...wrap(`${listing.sameCommit ? "To get a newer commit listed later" : "To get it listed"}, open the marketplace's "${listing.updateRoute.form}" form and choose "${listing.updateRoute.choice}". \`omakit watch <the submission issue>\` shows which commit is listed now.`, {}, c))
+    return out.join("\n")
+  }
+
+  if (result.outcome === "refused") {
     // Root causes only: a check that waited on a failed one is not listed,
     // and the count says how many waited.
     const failed = result.checks.filter((check) => result.blocking.includes(check.id))
@@ -149,7 +169,12 @@ export function renderSubmit(result, { colour = colourEnabled() } = {}) {
   const validation = result.validationCommit.defaultBranchHead
     ? `${result.validationCommit.local} is the ${result.validationCommit.branch || "default"}-branch HEAD, so it is the commit the marketplace will validate.`
     : `${result.validationCommit.local} is the local commit; the marketplace validates the default-branch HEAD it resolves when the issue is opened.`
-  out.push(...verdict("pass", "READY", `every blocking check passed. ${validation}`, c))
+  // A skipped check is said on the READY line itself, so the one line an
+  // agent quotes does not read as "everything passed" when one check never
+  // ran. The count is the whole `skipped` list; today only --offline skips.
+  const skipped = (result.skipped || []).length
+  const skippedNote = skipped ? ` ${skipped === 1 ? "1 check" : `${skipped} checks`} skipped (--offline).` : ""
+  out.push(...verdict("pass", "READY", `every blocking check passed.${skippedNote} ${validation}`, c))
   out.push("")
   out.push(...section("issue title", c))
   out.push(c("heading", result.issue.title))

package/tools/marketplace/style.mjs

@@ -162,6 +162,7 @@ export const DENSITY = Object.freeze({
   medium: "▒", // ▒  unknown: neither here nor there
   light: "░", // ░  information: present, weightless
   floor: "▁", // ▁  settled: a pass, a rule, the track the scanner runs on
+  ceiling: "▔", // ▔  skipped: the floor's own ink, never landed, because a flag said not to look
 })
 
 /** The glyph that starts the one line that fixes things. */
@@ -170,15 +171,23 @@ export const ARROW = "→"
 // --- the status vocabulary ---------------------------------------------------
 
 /**
- * Five states, and only five. Each has one glyph, one word and one tint, and
+ * Six states, and only six. Each has one glyph, one word and one tint, and
  * every command prints them through `mark()` below. `pass` and `fail` are
  * verdicts; `advisory` is a failure that does not block; `info` is a fact with
- * no verdict; `unknown` is a check that could not be made.
+ * no verdict; `unknown` is a check that could not be made; `skipped` is a
+ * check that was not made because a flag said not to (`--offline`).
  *
  * The glyph is the density ramp read as severity: the more ink, the more it
  * matters. The word is the same thing in letters, and its case carries it too:
  * FAIL is the only upper-case mark, so it is the one the eye lands on in a
  * column of lower-case ones, with or without colour.
+ *
+ * `skipped` and `unknown` are one family: neither has a verdict, both wear the
+ * same tint, and only the glyph and the word tell them apart. Measured on
+ * 0.1.6: `--offline` drew the skipped validation-commit check as `▁ ok`, and
+ * `--json` said `"verdict": "pass"`, for a comparison that never happened. The
+ * skipped mark is the floor's ink at the ceiling: the same weight as a pass,
+ * visibly not landed on one, on a theme that shows no hue.
  */
 export const STATUS = Object.freeze({
   pass: Object.freeze({ glyph: DENSITY.floor, word: "ok", tint: "pass" }),
@@ -186,6 +195,7 @@ export const STATUS = Object.freeze({
   advisory: Object.freeze({ glyph: DENSITY.dark, word: "note", tint: "advisory" }),
   info: Object.freeze({ glyph: DENSITY.light, word: "info", tint: "info" }),
   unknown: Object.freeze({ glyph: DENSITY.medium, word: "?", tint: "unknown" }),
+  skipped: Object.freeze({ glyph: DENSITY.ceiling, word: "skip", tint: "unknown" }),
 })
 
 /** The width of the widest mark, "█ FAIL"; every mark is padded to it so the names beside them align. */
@@ -360,7 +370,7 @@ export function wrap(text, { indent = 0, width: total = COLUMNS, first = indent
  * after it starts at GUTTER. This is the only place a status is turned into
  * characters.
  *
- * @param {"pass"|"fail"|"advisory"|"info"|"unknown"} state
+ * @param {"pass"|"fail"|"advisory"|"info"|"unknown"|"skipped"} state
  * @param {(name: string, text: string) => string} c
  */
 export function mark(state, c) {