change(governance): decouple speccing from shipping, add /considered/ - #121
Merged
Conversation
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>
Deploying specification-website with
|
| 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 |
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>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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:
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:
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, andrevisit— 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:
too-earlyout-of-scopetoo-narrowGrouped 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:
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.out-of-scope. A property of an API, not of a website.out-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.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 gets deleted in the same PR that adds the spec page.
Wiring
Header and footer nav · OG image (
/og/considered.png) ·llms.txtProject section · a "When a topic is absent" section inSKILL.md(digest re-signed) so an agent checks the register before reporting a gap or re-proposing something already turned down · matching guidance inCONTRIBUTING.mdfor human contributors.ops/routines/daily-standards-scan.mdis 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
changedentry if you'd rather the register's arrival were announced.🤖 Generated with Claude Code