What broke

The observatory's site builds two plain-text indexes for other machines to read: a short one and a full one. Both carry an attribution line that tells a reader to link back to the exact entry it used. That line was written with a placeholder, <slug>, standing in for an entry's name, and the site's own address was joined to it: https://softwareobservatory.com/sensors/<slug>/.

A placeholder is prose for a person. An absolute address is a pointer a computer follows. Written together they make a pointer to a page that does not exist, because <slug> was never filled in.

The same line appears in three places: once in the short index, twice in the full one. The short-index copy was fixed once — made relative so the checker would ignore it — then the fix was reverted the same morning to keep the attribution address absolute, and the placeholder leaked again. The full-index copies were never touched.

How it showed

The site runs a weekly scan of every outbound link and flags any that answer "page not found" or run out of time. Two weeks running it reported the same line:

BROKEN external: https://softwareobservatory.com/sensors/<slug (HTTP 404)

The address leads to the site's own domain with a placeholder where an entry name should be. The checker is correct: that page does not exist. The same run also flagged one genuinely rotted citation, an outside paper whose old server no longer answers; that is the scan doing its job, and it is a different, smaller finding from the one this case is about.

What was watching

Snapshot tests — the golden copies of the generated text — were present and blind. When the placeholder was reverted back into the short index, the golden copy was re-blessed in the same change, so the comparison passed and certified the regression instead of catching it. A snapshot updated without being read is a snapshot that records the bug as the new correct answer.

Pre-promotion invariant gates — the weekly external-link scan — is the sensor that finally fired. It fired a week after the placeholder shipped, on a schedule, after the broken address was already live on the public site.

The build's own structural gates ran at every build and were blind. They check counts and structured data, and none ask the one question that matters here: did a placeholder escape into a position meant for a real address.

Where it sits

This is a structural failure: the generator emitted an address that is not an address, and no structural gate noticed it at build time. It is also a test-effectiveness failure: the golden snapshot that should have caught the change instead approved it, so the test gave no durable reading about the output it was guarding.

The snapshot tests sensor is supposed to be exactly the guard for this class — output that changed without intent. It failed here not for lack of a snapshot, but because the snapshot was updated to match the regression. The pre-promotion invariant gates sensor could only catch the placeholder after it was live, because nothing checked for placeholders locally while the build ran.

What we did

The control is a build gate: after the site is generated, the build scans its plain-text output for any http(s) address that still contains a literal <...> placeholder, and fails if it finds one. A placeholder can no longer ship inside a position meant for a real address. The source lines that produced the leak now write the placeholder as a named path — /sensors/<slug>/ with a concrete example entry beside it, the same convention the rest of the file already uses — so the attribution instruction survives without looking like a live address.

The fix is filed as a pull request and not yet merged, so this case is marked partial.

What now fails loudly

• A placeholder inside an address stops the build. The new gate fails the

moment any generated surface contains an http(s) address with a literal <...> token in it, before the site is published.

• The golden snapshot is no longer the last line of defence. Where the

snapshot had silently blessed the placeholder, the gate now refuses it outright, so a future edit that reintroduces the placeholder fails at build time rather than a week later in the network scan.