Skip to content

change(governance): decouple speccing from shipping, add /considered/ - #121

Merged
jdevalk merged 1 commit into
mainfrom
add/considered-register
Jul 31, 2026
Merged

change(governance): decouple speccing from shipping, add /considered/#121
jdevalk merged 1 commit into
mainfrom
add/considered-register

Conversation

@jdevalk

@jdevalk jdevalk commented Jul 23, 2026

Copy link
Copy Markdown
Owner

Implements the two rule changes you asked for, plus the public register the second one needs.

1. Speccing no longer requires shipping

The old rule was:

do not promote a convention to spec status without us shipping a working implementation first. The site is the proof-of-feasibility.

That forced a false choice whenever a topic was right for readers but irrelevant to a small static site — and it quietly encouraged the worst outcome, implementing something we don't need purely to earn the right to document it.

Replaced with three honest page shapes, all fine:

  1. Specced and shipped — the common case, keeps the "this site ships it; see X" callout.
  2. Specced, deliberately not shipped — carries a one-line note saying so, with the reason.
  3. Not specced — see below.

Shape 2's note is treated as content, not an apology. "This site does not ship it: we are static, so no response ever means this changed" tells the reader something true about when the topic applies. Silence would not.

2. Adoption, not finality, is the bar — and thin adoption is your call

A final RFC with permanent IANA registration still doesn't earn a page if nothing implements it; the page would recommend a header no cache reads. The converse also holds — a widely-deployed convention can earn a page before its RFC lands.

Where adoption looks thin, the routine must now surface it rather than decide: not open the PR, not silently drop it, but put it in Slack with what was checked (MDN/BCD, Chrome Platform Status, the relevant CDN or server docs) and wait for you.

3. New: /considered/ — "Considered, not adopted"

Hand-curated collection at src/content/considered/, same shape as the changelog (not derived — nothing generates it). Per entry: title, date, reason, sources, and revisit — what would change our mind, which is what keeps the register from becoming a graveyard.

Three reasons, each with a standing definition on the page:

Reason Meaning
too-early Real and final, but nothing implements it yet
out-of-scope A way of building a site, not something a site does
too-narrow Real, implemented, auditable — but applies to too few sites

Grouped by reason rather than date: it reads as a register of decisions, not a timeline.

Seeded with four real decisions, all from actual history rather than invented:

  • HTTP Cache Groups (RFC 9875)too-early. Final and IANA-registered, but no MDN page or BCD key, no Chrome Platform Status entry, nothing in Cloudflare's cache docs or changelog, and no sign in Fastly, Varnish, nginx or Squid. Souin is the one candidate and documents itself against the pre-RFC draft.
  • HTTP QUERY (RFC 10008)out-of-scope. A property of an API, not of a website.
  • CSS subgridout-of-scope. Records why add(foundations): CSS subgrid page #82 was closed. This is the reference case for newly-Baseline authoring features generally, which is why it's worth having written down.
  • WebSubtoo-narrow. Real, implemented, auditable, but hub publishing is a fediverse/IndieWeb speciality.

Entries are decisions already taken, not a queue. When a reason expires, the entry gets deleted in the same PR that adds the spec page.

Wiring

Header and footer nav · OG image (/og/considered.png) · llms.txt Project section · a "When a topic is absent" section in SKILL.md (digest re-signed) so an agent checks the register before reporting a gap or re-proposing something already turned down · matching guidance in CONTRIBUTING.md for human contributors.

ops/routines/daily-standards-scan.md is updated too, so the next scheduled run picks up the new rules automatically — including a requirement that every turn-down gets a /considered/ entry, and that the Slack "skipped, and why" section agrees with the register.

Checks

Rendered and verified at /considered/ in the dev server — three reason groups, four entries, revisit notes and source links all present.

npm run build ✓ · npm run check ✓ (0 errors) · npm run lint ✓ · npm run format:check ✓ · npm run check:skill

Two things for you to decide

  1. Naming. I read "specs we have decided not to ship yet" as standards we decided not to write up — since rule 1 makes not-shipping the unremarkable case, the noteworthy decision is not speccing at all. If you meant the other thing (a list of specced topics we don't implement), that's a different page and I'll rebuild it.
  2. No changelog entry. Per CLAUDE.md the changelog is about the spec's content, pages not plumbing, and this adds no spec page. Happy to add a changed entry if you'd rather the register's arrival were announced.

🤖 Generated with Claude Code

Two rule changes, plus the public register the second one needs.

1. Speccing no longer requires shipping.

The old rule ("do not promote a convention to spec status without us shipping a
working implementation first — the site is the proof-of-feasibility") forced a
false choice whenever a topic was right for readers but irrelevant to a small
static site. It also encouraged the worst outcome: implementing something we
don't need, purely to earn the right to document it.

Replaced with three honest page shapes — specced and shipped, specced and
deliberately not shipped, or not specced — where shape 2 carries a one-line note
on the page saying we don't ship it and why. That note is content, not an
apology: "we are static, so no response ever means this changed" tells the
reader something real about when the topic applies.

2. Adoption, not finality, is the bar for adding a page — and thin adoption is
   the maintainer's call.

A final RFC with permanent IANA registration still doesn't earn a page if
nothing implements it; the page would recommend a header no cache reads. The
converse also holds — a widely-deployed convention can earn a page before its
RFC lands. Where adoption looks thin, an agent must surface it rather than
either shipping the page or silently dropping it.

3. New: src/content/considered/ → /considered/ ("Considered, not adopted").

Hand-curated collection, same shape as changelog (not derived, nothing
generates it). Per entry: title, date, reason (too-early | out-of-scope |
too-narrow), sources, and `revisit` — what would change our mind, which is what
keeps the register from being a graveyard. Grouped by reason rather than date,
because it reads as a register of decisions, not a timeline.

Seeded with four real decisions:
- HTTP Cache Groups (RFC 9875) — too-early. Final and IANA-registered, but no
  MDN page or BCD key, no Chrome Platform Status entry, nothing in Cloudflare's
  cache docs or changelog, and no sign in Fastly/Varnish/nginx/Squid. Souin is
  the one candidate and documents itself against the pre-RFC draft.
- HTTP QUERY (RFC 10008) — out-of-scope. A property of an API, not a website.
- CSS subgrid — out-of-scope. Records why PR #82 was closed; this is the
  reference case for newly-Baseline authoring features generally.
- WebSub — too-narrow. Real, implemented, auditable, but hub publishing is a
  fediverse/IndieWeb speciality.

Entries are decisions already taken, not a queue. When a reason expires, the
entry is deleted in the same PR that adds the spec page.

Wiring: header + footer nav, OG image, llms.txt Project section, and a
"When a topic is absent" section in SKILL.md (digest re-signed) so an agent
checks the register before reporting a gap or re-proposing a rejected topic.
CONTRIBUTING.md gains the same guidance for human contributors.

Verified: page renders correctly at /considered/ in the dev server, three reason
groups, four entries. build ✓ lint ✓ format ✓ check ✓ (0 errors) check:skill ✓

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@cloudflare-workers-and-pages

Copy link
Copy Markdown

Deploying specification-website with  Cloudflare Pages  Cloudflare Pages

Latest commit: c893601
Status: ✅  Deploy successful!
Preview URL: https://b6601c2f.specification-website.pages.dev
Branch Preview URL: https://add-considered-register.specification-website.pages.dev

View logs

@jdevalk
jdevalk merged commit 0e27e0f into main Jul 31, 2026
7 of 8 checks passed
@jdevalk
jdevalk deleted the add/considered-register branch July 31, 2026 09:15
jdevalk added a commit that referenced this pull request Jul 31, 2026
… unsigned (rebuild of #123) (#139)

* change(ard): drop the trust-manifest signature; publish the catalogue unsigned

Rebuild of #123 on current main, which #121 conflicted with.

The signature protected three static fields and was verified by a JWK Set
on the same origin as the catalogue it vouched for, so it folded to exactly
the compromise it existed to detect. It also left `entries` — where the MCP
and A2A endpoint URLs live — unsigned.

Removes host.trustManifest, the jwks _headers block and api-catalog entry,
the sign:ard / check:ard scripts and the CI step. The spec page gains the
reasoning: sign only when the verifying key is anchored independently of
the signed document.

Two files still need deleting; see the PR body.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

* change(ard): remove the signing script and JWK Set

Completes the removal: public/.well-known/jwks.json and
scripts/sign-ard-catalog.mjs. Nothing references either — the _headers
block, the api-catalog entry, the npm scripts and the CI step went in the
previous commit.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

* change(ard): date the removal 31 July, the day it ships

The changelog entry, the spec page's `updated`, and the superseded banners
all read 23 July — when the change was written, not when it lands.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
jdevalk added a commit that referenced this pull request Jul 31, 2026
The register recorded WebSub as turned down (too-narrow). This PR adds the
page, so per the workflow #121 defines the entry is deleted in the same PR
that supersedes it. The `too-narrow` group now has no entries and drops out
of /considered/ on its own — considered.astro filters empty groups.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
jdevalk added a commit that referenced this pull request Jul 31, 2026
* add(foundations): WebSub — push notification for feeds

WebSub was republished as a W3C Recommendation on 2 June 2026 (new XSS
mitigations in Security Considerations), and the repo had no page for it
despite covering feed discovery and feed hygiene. rel="hub" and
rel="self" are both IANA-registered link relations and auditable from
outside the site, so this is a website property rather than a build
technique.

Status: optional — it only applies if you publish a feed and have a hub
to point at; the platform does not break without it.

- new page src/content/spec/foundations/websub.md (order 130, after
  feed-discovery/110 and feed-hygiene/120)
- relatedSlugs wired on feed-discovery, feed-hygiene and link-headers
- changelog entry 2026-07-30-websub.md
- OG images regenerated; SKILL.md page count 164 -> 165 + digest resigned

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

* chore(websub): retire the /considered/ entry, resign SKILL for 166 pages

The register recorded WebSub as turned down (too-narrow). This PR adds the
page, so per the workflow #121 defines the entry is deleted in the same PR
that supersedes it. The `too-narrow` group now has no entries and drops out
of /considered/ on its own — considered.astro filters empty groups.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
jdevalk added a commit that referenced this pull request Jul 31, 2026
* add(foundations): WebSub — push notification for feeds

WebSub was republished as a W3C Recommendation on 2 June 2026 (new XSS
mitigations in Security Considerations), and the repo had no page for it
despite covering feed discovery and feed hygiene. rel="hub" and
rel="self" are both IANA-registered link relations and auditable from
outside the site, so this is a website property rather than a build
technique.

Status: optional — it only applies if you publish a feed and have a hub
to point at; the platform does not break without it.

- new page src/content/spec/foundations/websub.md (order 130, after
  feed-discovery/110 and feed-hygiene/120)
- relatedSlugs wired on feed-discovery, feed-hygiene and link-headers
- changelog entry 2026-07-30-websub.md
- OG images regenerated; SKILL.md page count 164 -> 165 + digest resigned

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

* add(websub): ship a self-hub for this site's two feeds

Makes the site a worked example of /spec/foundations/websub/ rather than a
page describing something we do not run.

A *self-hub*: hub.topic is allowlisted to /rss.xml and /changelog/rss.xml,
so the endpoint cannot fetch arbitrary URLs or relay anyone else's content.
That constraint is what makes a hub reasonable to run here — an open hub is
a public service with a very different risk profile.

- functions/websub.ts — subscribe/unsubscribe (WebSub 5.1), verification of
  intent (5.3), content distribution with Link rel=hub/self and an
  X-Hub-Signature HMAC-SHA256 (5.4), plus a bearer-gated hub.mode=publish
  (the PubSubHubbub 0.4 convention; WebSub 4 leaves this out of scope).
- migrations/0001 — D1 subscription store. Leases expire lazily at
  distribution time, so the hub needs no cron trigger.
- .github/workflows/websub-ping.yml — pings the hub after a content push,
  mirroring deploy-mcp.yml's trigger. Waits for the Pages deploy first;
  distributing a stale feed is worse than distributing late.
- scripts/test-websub.mjs (npm run test:websub) — 35 assertions over the
  callback guard, lease clamping, constant-time token compare, and the HMAC
  against the RFC 4231 known vector.
- privacy.astro — subscribing is the first thing on this site that stores
  data a visitor gives us. Says what is kept, for how long, and who sees it.

The D1 binding is committed COMMENTED OUT and the hub 503s without it, so
this is inert and safe to merge before the database exists. The rel="hub"
advertisement is held back to the same commit that provisions D1 — shipping
a hub link with nothing behind it is the exact failure the spec page warns
about. wrangler.toml carries the go-live checklist.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

* chore(websub): retire the /considered/ entry, resign SKILL for 166 pages

The register recorded WebSub as turned down (too-narrow). This PR adds the
page, so per the workflow #121 defines the entry is deleted in the same PR
that supersedes it. The `too-narrow` group now has no entries and drops out
of /considered/ on its own — considered.astro filters empty groups.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant