@piercebarney/whs-eleventy 2026.10.6 → 2026.10.8

package/README.md

@@ -7,9 +7,10 @@ the stack runs, so a fix lands once and `npm update` carries it everywhere.
 ```
 whs compliance [--strict]              codebase-vs-standard conformance sweep
 whs doctor [--live|--deploy-preflight] infrastructure drift check
+whs html                               html-validate (standard preset) over every _site/ page
 whs links                              built-output link / CSP / JSON-LD integrity
 whs a11y                               axe-core WCAG 2.1 A/AA scan of _site/
-whs content-check                      lint · validate · build · links (no browser)
+whs content-check                      lint · validate · build · html · links (no browser)
 whs --version                          tooling + bundled-standard version
 ```
 
@@ -29,6 +30,7 @@ Then in `package.json`:
 ```json
 {
   "scripts": {
+    "html": "whs html",
     "links": "whs links",
     "a11y": "whs a11y",
     "doctor": "whs doctor",

package/cli.js

@@ -4,6 +4,7 @@
 //   whs status [--hook]                    standard-version drift, at a glance
 //   whs compliance [--strict]              codebase-vs-standard conformance sweep
 //   whs doctor [--live|--deploy-preflight] infrastructure drift check
+//   whs html                               html-validate (standard preset) over every _site/ page
 //   whs links                              built-output link / CSP / JSON-LD integrity
 //   whs a11y                               axe-core WCAG 2.1 A/AA scan of _site/
 //   whs content-check                      the content-relevant slice of the gate
@@ -20,6 +21,7 @@ const COMMANDS = {
   status: "status.js",
   compliance: "compliance.js",
   doctor: "doctor.js",
+  html: "html.js",
   links: "check-links.js",
   a11y: "a11y.js",
   "content-check": "content-check.js",

package/lib/compliance.js

@@ -217,6 +217,12 @@ const CHECKS = {
 
   rendering: () => {
     if (!has("src/404.njk")) return { status: FAIL, note: "no src/404.njk" };
+    // core.md#rendering requires every built page to be valid HTML — mirrors
+    // the a11y chapter's own "is the scan actually wired into the gate" check
+    // below, rather than trusting that the stage exists just because the
+    // package ships one.
+    if (!/\bhtml\b/.test(JSON.parse(read("package.json") || "{}").scripts?.check || ""))
+      return { status: FAIL, note: "no html stage in the gate" };
     // A page whose <main> is empty/near-empty in the built output is the
     // classic "content only appears after client JS runs" regression the
     // Contract forbids — a crude but real content-presence check, distinct
@@ -232,7 +238,10 @@ const CHECKS = {
         status: FAIL,
         note: `${thin.length} page(s) with near-empty <main> — content may be client-rendered only`,
       };
-    return { status: PASS, note: "server-rendered HTML with real content; 404 page present" };
+    return {
+      status: PASS,
+      note: "server-rendered HTML with real content; 404 page present; html-validate stage in the gate",
+    };
   },
 
   assets: () => {

package/lib/content-check.js

@@ -1,6 +1,7 @@
 // The content-relevant slice of the gate, for an agent editing content
-// (CONTENT.md). Runs lint → validate → build → links — no browser, so no a11y
-// (that's backstopped by `npm run check` in bin/deploy before anything ships).
+// (CONTENT.md). Runs lint → validate → build → html → links — no browser, so
+// no a11y (that's backstopped by `npm run check` in bin/deploy before
+// anything ships).
 //
 //   whs content-check
 //
@@ -79,7 +80,7 @@ function main() {
     console.log(`\nℹ  ${reqs.length} open request(s) in requests/ awaiting the build arm.\n`);
   }
 
-  const steps = ["lint", "validate", "build", "links"];
+  const steps = ["lint", "validate", "build", "html", "links"];
   for (const s of steps) {
     process.stdout.write(`content-check: npm run ${s}\n`);
     try {
@@ -89,7 +90,7 @@ function main() {
       process.exit(1);
     }
   }
-  console.log("\ncontent-check: ok — lint · validate · build · links");
+  console.log("\ncontent-check: ok — lint · validate · build · html · links");
 }
 
 module.exports = { strayFiles, parsePorcelain, splitStray, RESERVED_SET };

package/lib/doctor.js

@@ -34,7 +34,7 @@ const loadSite = () => projectRequire("src/_data/site.js");
 // feeds the /audit/ page's live-header check via _data/headerExpect.js.
 const HEADER_EXPECT = asRegexMap();
 
-const GATE_STAGES = ["lint", "validate", "test", "build", "links", "a11y"];
+const GATE_STAGES = ["lint", "validate", "test", "build", "html", "links", "a11y"];
 
 function readText(rel) {
   try {
@@ -122,7 +122,7 @@ function runRepoChecks({ preflight = false } = {}) {
   const absent = GATE_STAGES.filter((s) => !check.includes(s));
   add(
     "gate-stages",
-    "`npm run check` runs lint · validate · test · build · links · a11y",
+    "`npm run check` runs lint · validate · test · build · html · links · a11y",
     check !== "" && absent.length === 0,
     "warn",
     absent.length ? `not referenced: ${absent.join(", ")}` : "complete",

package/lib/html.js

@@ -0,0 +1,61 @@
+// HTML validity — the `html` step of the gate (whs html). Walks the built
+// _site/ recursively (every *.html — error pages and /audit/ included, not
+// just the sitemap) and runs html-validate's `html-validate:standard` preset
+// against each file, exiting non-zero on any error.
+//
+// `standard`, not `recommended`: recommended layers in style opinions (e.g.
+// uppercase DOCTYPE) that core.md#rendering's Contract never asked for — spec
+// conformance only (core.md#rendering: "no stray end tags, no bad nesting, no
+// duplicate ids"). An inline `<!-- [html-validate-disable-next] -->` comment
+// is the escape hatch for a rule that's a false positive on a specific line;
+// no per-project config file — one fixed config keeps every project on the
+// stack checked the same way.
+
+const fs = require("node:fs");
+const path = require("node:path");
+const { HtmlValidate } = require("html-validate");
+
+const SITE = "_site";
+
+function walkHtml(dir) {
+  const out = [];
+  for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
+    const p = path.join(dir, e.name);
+    if (e.isDirectory()) out.push(...walkHtml(p));
+    else if (e.name.endsWith(".html")) out.push(p);
+  }
+  return out;
+}
+
+async function main() {
+  if (!fs.existsSync(SITE)) {
+    console.error("html: _site/ missing — build first");
+    process.exit(1);
+  }
+
+  const files = walkHtml(SITE);
+  if (!files.length) {
+    console.error("html: no *.html files found under _site/");
+    process.exit(1);
+  }
+
+  const hv = new HtmlValidate({ extends: ["html-validate:standard"] });
+  const { valid, results } = await hv.validateMultipleFiles(files);
+
+  const failing = results.filter((r) => r.messages.length);
+  if (!valid || failing.length) {
+    const totalErrors = failing.reduce((n, r) => n + r.errorCount, 0);
+    console.error(`\nhtml: ${totalErrors} error(s) across ${failing.length} page(s):\n`);
+    for (const r of failing) {
+      console.error(`  ${path.relative(SITE, r.filePath)}`);
+      for (const m of r.messages) {
+        console.error(`    [${m.ruleId}] ${m.line}:${m.column} — ${m.message}`);
+      }
+    }
+    process.exit(1);
+  }
+
+  console.log(`  html: ${files.length} pages, valid per the WHATWG HTML Living Standard`);
+}
+
+main();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@piercebarney/whs-eleventy",
-  "version": "2026.10.6",
+  "version": "2026.10.8",
   "description": "The web house style's Eleventy + Netlify tooling — the compliance sweep, the infra doctor, the link/CSP integrity check, and the a11y scan, shared by every project on the stack.",
   "bin": {
     "whs": "cli.js"
@@ -32,6 +32,7 @@
   },
   "dependencies": {
     "axe-core": "^4.13.0",
+    "html-validate": "^11.16.0",
     "node-html-parser": "^9.0.2",
     "sirv": "^3.0.2"
   },

package/standard/CHANGELOG.md

@@ -21,6 +21,142 @@ enforced, new *opt-in* chapters/capabilities, tooling-only changes — is
 
 ---
 
+## 2026-10-08 [breaking]
+
+### core: rendering
+
+`#rendering`'s Contract never required HTML *validity* — only that content
+render without client JS and that server/client rendering logic not be
+duplicated. It now adds: every built page — including error pages and
+`/audit/` — must be valid HTML per the **WHATWG HTML Living Standard** (the
+spec W3C itself defers to). Spec conformance only (no stray end tags, no bad
+nesting, no duplicate `id`s) — no style opinions such as DOCTYPE case or
+attribute quoting. Rationale: browsers repair malformed markup silently, so
+invalid structure otherwise ships unseen, and WCAG 2.2 dropped its 4.1.1
+Parsing criterion, so an axe scan no longer catches it either. Decided by
+the owner in `feedback/2026-09-26-external-standards-survey.md`
+("Sequencing" step 2, row 3).
+
+### core: the-gate
+
+`#the-gate`'s drift-guarded stage order gains an **HTML validity** step,
+placed after `build` and before `link/reference integrity`: lint/format
+check → content validation → domain tests → build → HTML validity →
+link/reference integrity → a11y scan.
+
+**Breaking:** a project that was fully compliant before this change (a gate
+that ran build → links → a11y with no HTML-validity step) is no longer
+compliant after it — `#the-gate` now requires an HTML-validity stage that
+didn't exist as a requirement before, and `whs compliance` / `whs doctor`
+(see `packages/whs-eleventy` below) now `FAIL`/warn on its absence rather
+than silently passing.
+
+**Adopter action (eleventy):** `npm update @piercebarney/whs-eleventy`, add
+`"html": "whs html"` to `package.json` scripts, add `npm run html` to
+`check` (after `build`, before `links`), then fix any invalid markup the new
+check reports. Re-pin `standard-version` to `2026-10-08` once done.
+
+### packages/whs-eleventy
+
+New `whs html` command (`lib/html.js`): walks every `*.html` file under the
+built `_site/` recursively (error pages and `/audit/` included, not just the
+sitemap) and runs it through `html-validate`'s `html-validate:standard`
+preset (spec conformance only — not `recommended`'s style opinions), exiting
+non-zero on any error. New dependency `html-validate ^11.16.0`. `whs
+compliance`'s `#rendering` check now `FAIL`s if the project's `check` script
+doesn't reference an `html` stage. `whs doctor`'s `GATE_STAGES` list and its
+`gate-stages` check gain `html`. `whs content-check`'s lighter slice
+(`lint → validate → build → links`) gains `html`, run before `links`. Tests
+added for the new compliance/content-check behavior.
+
+### templates/eleventy-netlify
+
+Wires the new stage: `package.json` gains an `"html": "whs html"` script and
+inserts `npm run html` into `check` between `build` and `links`; `ci.yml`'s
+inline gate-order comment updated to match. `CLAUDE.md`, `README.md`, and
+`CONTENT.md` document the new stage in their gate-order prose.
+`standard-version` re-pinned to `2026-10-08`.
+
+### templates/sveltekit-netlify
+
+Implements the chapter for the first time (no prior HTML-validity tooling
+existed for this stack): new `html-validate` devDependency, a
+`.htmlvalidate.json` extending `html-validate:standard`, a new `"html":
+"html-validate \"build/**/*.html\""` script run recursively over every
+built page, and `npm run html` added to `check` after `build`. `README.md`,
+`TEMPLATE.md`, and `ci.yml`'s inline gate-order comment updated to match.
+This stack has no static error/404 page yet (`adapter-static`, no
+`fallback`, no `+error.svelte`), so `core.md#rendering`'s "error pages"
+clause has nothing to check today — the recursive glob will pick one up
+automatically the day this binding adds one.
+
+### stacks/eleventy-netlify.md, stacks/sveltekit-netlify.md
+
+Each `#rendering` Core-contract pointer line now mentions the "every built
+page is valid HTML" requirement; each documents its stack's real mechanism
+(`whs html` / `html-validate` respectively) and its place in `#the-gate`'s
+now-seven-step order.
+
+### stacks/phoenix.md
+
+Documented as a **`TODO`** in `#rendering`/`#the-gate` — no template change,
+no tooling exists yet. The candidate approach is recorded (a ConnCase/
+LiveView test fetching each sitemap route through html-validate or the Nu
+Html Checker, wired as a `mix html_validity` alias). The `mix check`
+placeholder-step snippet's order is also corrected while touching this
+section: it previously listed `a11y` before `links.check`, ahead of where
+`#the-gate`'s HTML-validity → links → a11y order calls for; it's now
+`html_validity → links.check → a11y`, fixing that pre-existing drift as well
+as adding the new placeholder step.
+
+**Gaps, not fixed by this change:** Phoenix has no HTML-validity tooling —
+`TODO`, same pattern as its existing `a11y`/`links.check` gaps. SvelteKit's
+template has no 404/error page today, so nothing exists yet for its new
+`html` step to check on that front.
+
+**Adopter action (sveltekit):** `npm install` (picks up `html-validate` +
+`.htmlvalidate.json`), add `"html": "html-validate \"build/**/*.html\""` to
+scripts and into `check` after `build`, re-pin `standard-version`.
+
+---
+
+## 2026-10-07 [breaking]
+
+### core: a11y
+
+`core.md#a11y`'s Contract never named a WCAG version/level as its
+conformance target — only "WCAG AA" for contrast. It now declares **WCAG 2.1
+Level AA** explicitly as the target, anchored to US law (the ADA Title II
+rule and US web-accessibility litigation/settlements reference WCAG 2.1 AA;
+Section 508's WCAG 2.0 AA is already covered by it) rather than WCAG 2.2 AA
+— the upgrade trigger to 2.2 AA is recorded, not scheduled, for once US rules
+reference it. **Breaking:** a project that was previously compliant by
+meeting the checklist plus passing the automated scan must now conform to
+all of WCAG 2.1 AA, including criteria the checklist and scan don't
+individually name (e.g. captions, reflow, keyboard operability everywhere)
+— a real added requirement, not just a clarification of an already-met bar.
+No tooling change: Eleventy's `whs a11y` scan already runs `wcag2a`/
+`wcag2aa`/`wcag21a`/`wcag21aa` — it already matched this target. SvelteKit's
+and Phoenix's scan gaps (no automated a11y tooling yet) are pre-existing and
+unrelated to this change. Decided by the owner in
+`feedback/2026-09-26-external-standards-survey.md` ("Decisions (2026-09-26)"
+item 1); see that file for the full WCAG-version rationale, including why
+2.1 and not 2.2.
+
+### core: styling
+
+The contrast line in `#styling` now also says "WCAG 2.1 AA" (was "WCAG AA"),
+matching the version now named in `#a11y`.
+
+### stacks/eleventy-netlify.md, stacks/phoenix.md, stacks/sveltekit-netlify.md
+
+Each of `stacks/eleventy-netlify.md`, `stacks/phoenix.md`, and
+`stacks/sveltekit-netlify.md`'s `#a11y` Core-contract pointer line now
+mentions WCAG 2.1 AA alongside the existing checklist/scan pointer — no
+change to any stack's own mechanism.
+
+---
+
 ## 2026-10-06 [breaking]
 
 ### packages/whs-eleventy

package/standard/core.md

@@ -1,6 +1,6 @@
 # Web project house style — CORE (stack-agnostic)
 
-**Version:** 2026-10-06 · **Status:** active
+**Version:** 2026-10-08 · **Status:** active
 
 This is the stack-agnostic contract every web project follows, regardless of
 framework, host, or CSS system. It says **what** must be true, with concrete
@@ -173,7 +173,8 @@ validation status.
 
 **Contract.** Core content and navigation work with no client JavaScript. Client
 JS enhances; it never gates the essentials. Any logic that renders on both the
-server and the client is written once.
+server and the client is written once. Every built page is valid HTML per the
+WHATWG HTML Living Standard.
 
 **Specs.**
 - The server-rendered (or prerendered) HTML is complete: a crawler or a
@@ -186,9 +187,17 @@ server and the client is written once.
 - Nothing that matters (core content, primary CTA) blocks on a network fetch.
   Live data arrives after first paint and degrades to a clear fallback state
   (see `#third-parties`).
+- Every built page — including error pages and `/audit/` — is valid HTML per
+  the **WHATWG HTML Living Standard** (the spec W3C itself defers to): no stray
+  end tags, no bad nesting, no duplicate `id`s. Browsers repair malformed
+  markup silently, so invalid structure otherwise ships unseen; WCAG 2.2
+  dropped its 4.1.1 Parsing criterion, so an axe scan no longer catches it
+  either. The check is spec conformance only — no style opinions (DOCTYPE
+  case, attribute quoting, and the like).
 
 **Verify.** Load a key page with JS disabled: content and links present.
-Grep for duplicated render logic.
+Grep for duplicated render logic. An HTML validator runs over every built
+page — including error pages and `/audit/` — in the gate.
 
 **Implementation.** See your stack's impl doc, same slug.
 
@@ -244,7 +253,7 @@ contrast-correct at the token level.
 - **Strict-CSP-safe:** no `style-src 'unsafe-inline'`, no inline `style=`
   attributes in templates, no per-page `<style>` blocks. Utility-class systems
   (Tailwind) are fine; inline style strings are not.
-- Contrast meets WCAG AA. When a pair fails, fix the **token**, not the usage.
+- Contrast meets WCAG 2.1 AA. When a pair fails, fix the **token**, not the usage.
 - Theme is applied via a data attribute set before first paint (`#theme`).
 - A second stylesheet only for a genuinely separable widget, justified in a
   comment.
@@ -834,8 +843,11 @@ states.
 
 ## a11y — Accessibility checklist
 
-**Contract.** Every page meets the checklist below. An automated a11y scan over
-every page runs in the gate — and is understood to catch regressions, not
+**Contract.** Every page conforms to **WCAG 2.1 Level AA** — the level US
+accessibility law references (the ADA Title II rule; Section 508's WCAG 2.0 AA
+is covered by it). The checklist below is the house's concrete mechanism for
+the parts of AA most often missed, not the whole of it. An automated a11y scan
+over every page runs in the gate — and is understood to catch regressions, not
 everything.
 
 **Specs.**
@@ -858,7 +870,7 @@ everything.
   keyboard button — don't re-bind Enter/Space or add `role`/`tabindex`.
 - **Icons:** decorative → `aria-hidden="true"`; meaningful → `<title>` in the
   SVG or `aria-label` on the control.
-- **Contrast** meets WCAG AA; fix failures at the token (`#brand-source`), not
+- **Contrast** meets WCAG 2.1 AA; fix failures at the token (`#brand-source`), not
   with a one-off override.
 - **Focus visibility:** a visible focus ring on every interactive element; if
   you override the default, keep one.
@@ -883,8 +895,9 @@ enforcement point runs that same command — never a hand-picked subset.
 
 **Specs.**
 - One gate command runs, ordered cheapest-first: lint/format check → content
-  validation → domain tests → build → link/reference integrity → a11y scan.
-  (Optionally a performance budget once the site has a baseline.)
+  validation → domain tests → build → HTML validity → link/reference
+  integrity → a11y scan. (Optionally a performance budget once the site has a
+  baseline.)
 - The same command is invoked by: the pre-push git hook, the CI workflow, the
   deploy script, and the assistant before it reports work complete.
 - There is **no "CI-only" variant** and no partial local run. If the gate
@@ -1467,7 +1480,7 @@ governs it and follow that chapter — the slugs are the index (a `<script>` →
 - production-url: https://example.com
 - content-type: tool           # tool | article  (article => feeds)
 - publishing-rate: ~5 pages/week
-- standard-version: 2026-10-06  # recommended — enables standard-version drift tracking (#compliance)
+- standard-version: 2026-10-08  # recommended — enables standard-version drift tracking (#compliance)
 ```
 
 If the section is absent, the assistant's first action is to run the flow above