The ticket-archaeology guard reads an all-numeric hex colour as an issue ref

Context

Hit while committing #16538. Every edit to src/component/Helix.mjs failed the pre-commit hook on a line the change never touched:

check-ticket-archaeology: 1 decay-prone ref(s) in durable comments:
  src/component/Helix.mjs:29: * @member {String} backgroundColor_='#000000'

#000000 is a hex colour. The guard reads it as an issue reference.

The Problem

The guard's own docblock claims the protection it does not provide. buildScripts/util/check-ticket-archaeology.mjs:22-24:

// Decay-prone tracking anchors that must not live in durable source comments. `#\d{4,}\b` targets
// issue/PR numbers (Neo tickets are 5 digits) while a trailing word boundary avoids matching hex colors
// like `#1234ff`; the named forms catch the prose variants.
export const TICKET_PATTERNS = [
    /#\d{4,}\b/,

The trailing \b does exactly what the comment says — for the example the comment picks. #1234ff has letters after the digits, so \d{4,} cannot reach a word boundary and the match fails. An all-numeric colour has no letters to stop it: #000000 is six digits, \d{4,} consumes all six, \b succeeds at the string end, and the guard fires.

So the exclusion holds for #1234ff and fails for #000000, #111111, #123456, #332211. The prose reads as a general guarantee; it is a guarantee about one example.

Measured blast radius — the checker run over every tracked src/**/*.mjs, rather than counting pattern matches:

Three files cannot be committed without an escape marker, on lines the committing change need not touch. src/component/Helix.mjs was the fourth until #16538 added the marker as a stopgap.

The cost is not the three files. It is that the escape marker is the only route, and it makes a false statement in the source: ticket-ref-ok asserts a ticket reference is deliberate, when there is no ticket reference. Every use of it here teaches the next reader that a hex colour is a tracking anchor someone chose to keep.

The Architectural Reality

• buildScripts/util/check-ticket-archaeology.mjs:26 — the pattern.
• :20 — ESCAPE_MARKER = 'ticket-ref-ok', matched per-line, so the marker must sit on the offending line. In a JSDoc block that means appending lint prose to an @member tag.
• Neo ticket numbers are 5 digits and currently in the 16000s; 6-digit hex colours collide by construction, and 4-digit numeric colours (#0000) would too.

The Fix

Distinguish the two by what precedes the #, or by what the digits are attached to. A colour literal in Neo's comments appears as a value — ='#000000', `#000000`, or after a colon — while a ticket ref appears as a bare word in prose. The narrowest change that keeps every true positive:

• require a non-value context before # (not immediately preceded by ', ", `, or =), or
• exclude a match whose digit run is exactly 6 or 3 and is delimited as a literal.

The first is preferable: it keys on the syntax that makes something a value, not on digit-count numerology that a future 6-digit ticket number would break.

Whatever shape it takes, it must keep firing on a real ref in a quoted string — 'see <a href="#/news/tickets/16538">#16538</a>' in a comment is still decay-prone. The fix is about the value position, not about quotes alone.

Contract Ledger Matrix

Decision Record impact

none — a lint pattern inside one build script.

Acceptance Criteria

• #000000, #111111, #123456 in a durable comment do not trip the guard, proven by a spec that fails against today's pattern.
• #16538, #1234, and a ref inside a quoted string in prose still do — the true positives are asserted alongside, or a pattern matching nothing passes the first criterion.
• #1234ff still passes, so the existing exclusion is not regressed while widening it.
• The docblock at :22-24 describes the actual rule rather than one example of it.
• The three named src/ files commit without an escape marker.
• The stopgap marker at src/component/Helix.mjs:29 is removed.

Out of Scope

• The other entries in TICKET_PATTERNS (the named prose forms) — no false positive observed, and widening the sweep would risk the true positives this guard exists for.
• Whether ESCAPE_MARKER should be block-scoped rather than line-scoped. Real friction — a JSDoc @member line is a poor host for lint prose — but a separate concern from the false positive, and fixing this one removes the reason to reach for it here.

Avoided Traps

• Excluding anything in quotes. A real ref in a quoted string is still decay-prone; the discriminator is value position, not quoting.
• Keying on digit count. #000000 is six digits and so is a plausible future ticket number. Numerology that works today by accident of the counter is not a rule.
• Leaving the marker as the answer. It unblocks and it lies: ticket-ref-ok asserts a deliberate ticket reference where none exists, and it accumulates one false statement per affected file.

Related

#16538 / PR #16552 (where the stopgap marker lives, and where the false-positive line is) · #16528 (artifact concision) is unrelated despite both touching authoring guards.

Live latest-open sweep: checked latest 20 open issues at 2026-08-05T14:14:27Z; A2A in-flight claim sweep over the 12 most recent messages at 13:57Z. No equivalent found, no in-flight claim.

Origin Session ID: 8921d480-6087-4bfa-abe0-4f47873e06c4

Retrieval Hint: query_raw_memories("check-ticket-archaeology hex colour false positive all-numeric <a href="#/news/tickets/000000">#000000</a> escape marker blocks commit")

Retrieval Hint: the discriminator is /#\d{4,}\b/ against #000000 versus #1234ff — letters after the digits are what the trailing word boundary actually relies on.