@piercebarney/whs-eleventy 2026.9.8 → 2026.9.13

package/cli.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 // whs — the web house style's Eleventy + Netlify tooling.
 //
+//   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 links                              built-output link / CSP / JSON-LD integrity
@@ -16,6 +17,7 @@ const path = require("node:path");
 const { spawnSync } = require("node:child_process");
 
 const COMMANDS = {
+  status: "status.js",
   compliance: "compliance.js",
   doctor: "doctor.js",
   links: "check-links.js",

package/lib/_project.js

@@ -40,12 +40,16 @@ function openRequests(root = ROOT) {
 //   1. WHS_STANDARD env var (the authoring repo points this at itself)
 //   2. the copy bundled into this package at publish time (standard/)
 //   3. the legacy ~/.claude/standards/web-house-style symlink
+// With { preferLocal: true } the ~/.claude checkout is tried before the bundled
+// copy (still behind WHS_STANDARD) — for `whs status`, which asks whether a
+// newer standard exists on this machine rather than measuring against the pin.
 // Returns an absolute dir path, or null if none of them has a core.md.
-function resolveStandard() {
+function resolveStandard({ preferLocal = false } = {}) {
+  const bundled = path.join(__dirname, "..", "standard");
+  const local = path.join(os.homedir(), ".claude", "standards", "web-house-style");
   const candidates = [
     process.env.WHS_STANDARD,
-    path.join(__dirname, "..", "standard"),
-    path.join(os.homedir(), ".claude", "standards", "web-house-style"),
+    ...(preferLocal ? [local, bundled] : [bundled, local]),
   ].filter(Boolean);
   for (const dir of candidates) {
     if (fs.existsSync(path.join(dir, "core.md"))) return dir;

package/lib/compliance.js

@@ -717,9 +717,9 @@ function changelogSlugs(changelog, pin) {
   return [...slugs];
 }
 
-function versionDrift() {
+function versionDrift(standardDir = STANDARD) {
   const pin = (claudeMd.match(/standard-version:\s*([0-9-]+)/) || [])[1];
-  if (!STANDARD) {
+  if (!standardDir) {
     return {
       pin,
       current: null,
@@ -728,12 +728,12 @@ function versionDrift() {
       ],
     };
   }
-  const coreMd = read("core.md", STANDARD) || "";
+  const coreMd = read("core.md", standardDir) || "";
   const current = (coreMd.match(/\*\*Version:\*\*\s*([0-9-]+)/) || [])[1];
   if (!pin || !current) return { pin, current, rows: [] };
   if (pin >= current) return { pin, current, rows: [] };
 
-  const changelog = read("CHANGELOG.md", STANDARD) || "";
+  const changelog = read("CHANGELOG.md", standardDir) || "";
   // Worst-case severity per slug: one breaking touch marks it breaking for
   // good, even if a later (or earlier) entry touching the same slug since
   // the pin was non-breaking.
@@ -832,4 +832,11 @@ if (require.main === module) main();
 
 // CHECKS is exported for the "coverage" test — nothing else should read it as
 // data (call runCompliance() for results).
-module.exports = { runCompliance, summarize, changelogSlugs, changelogEntries, CHECKS };
+module.exports = {
+  runCompliance,
+  summarize,
+  changelogSlugs,
+  changelogEntries,
+  versionDrift,
+  CHECKS,
+};

package/lib/status.js

@@ -0,0 +1,103 @@
+// Standard-version drift, at a glance (core.md#compliance). The delta-only
+// slice of `whs compliance` — how far the project's pinned standard-version is
+// behind the standard, and which chapters that means re-checking — without the
+// full codebase sweep. Cheap enough to run on every Claude Code SessionStart.
+//
+//   whs status           print the version delta + the re-check rows
+//   whs status --hook     silent when current; one line when behind (for the
+//                         SessionStart hook — never non-zero, never noisy)
+//
+// Exit code is always 0: like `compliance` without --strict, drift is a
+// backlog signal, not a build break.
+
+const fs = require("node:fs");
+const path = require("node:path");
+
+const { versionDrift } = require("./compliance.js");
+const { resolveStandard } = require("./_project.js");
+
+// `status` answers "is there a newer standard available on this machine?" — so
+// it resolves the standard text with { preferLocal: true }: the local canonical
+// checkout (the ~/.claude symlink the README keeps) wins over the tooling's
+// bundled snapshot when it exists. `whs compliance` deliberately measures the
+// codebase against the bundled snapshot; `status` measures the pin against the
+// freshest tree available, which is what a "you're behind" nudge should
+// reflect. Machines without the symlink (CI, a fresh clone) fall back to the
+// bundled snapshot unchanged. WHS_STANDARD still wins over both.
+
+// Distinct CHANGELOG dates after the pin — the "N versions behind" count. The
+// standard versions by date, and several entries can share one date (one
+// release); this counts releases, not entries.
+function versionsBehind(pin, std) {
+  if (!std || !pin) return 0;
+  try {
+    const changelog = fs.readFileSync(path.join(std, "CHANGELOG.md"), "utf8");
+    const dates = new Set();
+    for (const line of changelog.split("\n")) {
+      const m = line.match(/^##\s+([0-9]{4}-[0-9]{2}-[0-9]{2})\b/);
+      if (m && m[1] > pin) dates.add(m[1]);
+    }
+    return dates.size;
+  } catch {
+    return 0;
+  }
+}
+
+function main() {
+  const hook = process.argv.includes("--hook");
+  const std = resolveStandard({ preferLocal: true });
+  const { pin, current, rows } = versionDrift(std);
+
+  const unresolved =
+    rows.length === 1 && rows[0].startsWith("MANUAL: standard text not resolvable");
+  if (unresolved) {
+    if (!hook) console.log(rows[0]);
+    return;
+  }
+
+  if (!rows.length) {
+    if (!hook) {
+      console.log(
+        pin && current
+          ? `web house style: up to date (pinned ${pin}, standard at ${current})`
+          : "web house style: standard-version not pinned in CLAUDE.md",
+      );
+    }
+    return;
+  }
+
+  const breaking = rows.filter((r) => r.startsWith("BREAKING:")).length;
+  const versions = versionsBehind(pin, std);
+  const behind = `${versions} version${versions === 1 ? "" : "s"} behind`;
+  const recheck = `${rows.length} re-check${rows.length === 1 ? "" : "s"}${
+    breaking ? ` (${breaking} breaking)` : ""
+  }`;
+
+  if (hook) {
+    console.log(
+      `⚠ web house style: ${behind}, ${recheck} — pinned ${pin}, standard at ${current}. ` +
+        `Run /whs:upgrade to catch up.`,
+    );
+    return;
+  }
+
+  console.log(
+    `\nstandard-version: pinned ${pin}, standard at ${current} — ${behind}, ${recheck}\n`,
+  );
+  for (const row of rows) console.log(`  ${row}`);
+
+  const hasUpgrade = fs.existsSync(
+    path.join(process.cwd(), ".claude", "commands", "whs", "upgrade.md"),
+  );
+  console.log(
+    hasUpgrade
+      ? "\nRun /whs:upgrade in a Claude Code session to work this backlog.\n"
+      : "\nThis project predates /whs:upgrade. Copy .claude/commands/whs/upgrade.md,\n" +
+          ".claude/hooks/standard-drift.sh, and the settings.json SessionStart entry\n" +
+          "from templates/eleventy-netlify/ in the standard, then run /whs:upgrade.\n",
+  );
+}
+
+if (require.main === module) main();
+
+module.exports = { versionsBehind };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@piercebarney/whs-eleventy",
-  "version": "2026.9.8",
+  "version": "2026.9.13",
   "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"

package/standard/CHANGELOG.md

@@ -4,7 +4,10 @@ Slug-keyed. A change to a shared concept (a `core.md` chapter) lists the slug so
 "when did the deploy philosophy last change, and which docs moved" is answerable
 at a glance. Stack-only changes list the file.
 
-Format: `## <date>` → `### core: <slug>` / `### <stack>` entries.
+Format: `## <date>` → `### core: <slug>` / `### <stack>` entries. Template
+`.claude/` tooling (commands, agents, hooks) and repo-root routing files (e.g.
+`COWORK.md`) are recorded here too, under `### templates/<stack>` / `### <file>`
+— the same as any mechanism an adopting project consumes.
 
 **Severity.** Every `## <date>` heading also carries `[breaking]` or
 `[non-breaking]`. An entry is **breaking** if a project that was fully
@@ -18,6 +21,182 @@ enforced, new *opt-in* chapters/capabilities, tooling-only changes — is
 
 ---
 
+## 2026-09-12 — A same-day-release suffix, two feedback fixes, and an /whs:upgrade false-negative [non-breaking]
+
+### templates/eleventy-netlify
+
+`/whs:upgrade`'s "Before starting" guard stopped immediately whenever
+`npm run status` reported the pin current — trusting a signal that itself
+trusts whatever `@piercebarney/whs-eleventy` version happens to be
+installed. Found today: that installed version's `resolveStandard()`
+predates the `preferLocal` live-checkout preference entirely, so it always
+reads its own frozen bundled snapshot — meaning `npm run status` can report
+"up to date" while the real standard has moved well past it, and the guard
+would stop before ever reaching the CHANGELOG read that would have caught
+it. The guard now also checks `~/.claude/standards/web-house-style/
+CHANGELOG.md` directly for any `## <date>` heading after the pin, and only
+stops if that agrees with `npm run status`.
+
+### bin/check
+
+`feedback/` is now excluded from check 4's real-adopter-name denylist.
+Reported same-day: `feedback/README.md`'s own filing template asks for the
+real adopter's directory name in `project:`, which the denylist rejected —
+the documented feedback process couldn't pass its own gate as written. The
+sterility grep (check 3) still applies to everything else in a report; only
+the project-name denylist is exempted, and only for `feedback/`.
+
+### bin/set-version, CLAUDE.md
+
+Same problem, a real fix instead of a workaround: `bin/set-version` now
+accepts `<YYYY-MM-DD>-N` for a same-day re-release, and refuses a bare
+re-run of a date already in use (telling you to add a suffix) instead of
+silently no-opping. The doc pins (`core.md`, `stacks/*.md`, `index.json`,
+every `standard-version:`) take the full suffixed string; `bin/check`'s
+version-agreement check now compares base dates (suffix stripped) so a
+suffixed pin still agrees with `packages/*/package.json`, which is left
+untouched on purpose — no same-day-aware npm version scheme exists, so a
+suffixed pin gets no git tag and no npm publish, a narrow, documented
+exception to "a pin corresponds to both a git tag and the npm version."
+This version bump (to 2026-09-12-2) is the suffix mechanism's own first
+real use, closing out both feedback reports filed today.
+
+---
+
+## 2026-09-11 — Feature flags, with ads as the reference implementation [non-breaking]
+
+### core: config-idiom
+
+Feature flags formalized as a named pattern: boolean env vars, one name per
+concern (`FEATURE_<NAME>`), read through the same centralised env-access
+module as build context. Additive — `#config-idiom` already required
+centralised environment access; this names the flag shape so future features
+follow one convention instead of inventing their own.
+
+### core: ads
+
+Ad serving now also respects a kill-switch flag (`#config-idiom`), independent
+of the `ads:` provider declaration — the declaration controls whether the
+plumbing exists, the flag controls whether it's currently allowed to render.
+Defaults to on, so an unset flag preserves prior behavior.
+
+### templates/eleventy-netlify
+
+`_data/build.js` gains `flags.ads` (`FEATURE_ADS`, default on); `ad-slot.njk`
+and `add-ons/ads/layout-head.njk` gate on it. `bin/deploy` and `deploy.yml`
+read the flag's current value from Netlify's own stored environment variables
+(`netlify env:get FEATURE_ADS --context production`) immediately before the
+production build, so the toggle lives in Netlify's dashboard and takes effect
+on the next deploy — consistent with `#ci-cd`'s "deploys are deliberate";
+there is no live no-redeploy toggle for any switch in this standard, ads
+included.
+
+## 2026-09-11 — Implementation work always runs through an agent [non-breaking]
+
+### templates/eleventy-netlify
+
+`CLAUDE.md`'s House-style prose gains a standing convention: any request that
+becomes an actual change is run through the same plan → delegate → verify →
+record loop `/whs:build` already uses per stage — a named stage agent
+(`brand`/`content`/`layout`/`pack`) when the work is its territory, the new
+`infra` agent for config/CI-CD/deploy/security-header/secrets/feature-flag
+work, a general-purpose agent otherwise — never edited inline in the main
+session, except a single `Edit`/`Write` touching 5 lines or fewer in one file.
+`/whs:upgrade`'s step 3 ("otherwise edit directly") is updated to match: it
+now delegates (to `infra` or general-purpose) instead. The exception is
+mechanically enforced, not just documented: `.claude/hooks/agent-only.js`, a
+`PreToolUse` hook wired into `.claude/settings.json`, denies a main-session
+`Edit`/`Write` over the 5-line threshold and any main-session `MultiEdit`,
+telling the assistant to delegate instead — a subagent's own edits (identified
+by the `agent_id` field the hook payload carries only inside a subagent call)
+are never blocked. The "changed lines" check is a positional line compare, not
+a real diff — a full-file rewrite that happens to keep every line in the same
+position reads as small; documented as a known limitation in the hook's own
+comments and `infra.md`, not silently assumed exact.
+
+## 2026-09-10 — COWORK.md backfilled, a sterility fix, and a tooling cleanup [non-breaking]
+
+### COWORK.md
+
+Backfilled — landed the same day as the entry below but as its own commit with
+no CHANGELOG entry. The router file a Cowork (Claude Desktop) Project's
+instructions point at: routes between new-project setup (ideates, live-checks
+whether the chosen stack actually has a working pipeline before committing to
+it, stages the brief, scaffolds via `new-project.sh`, hands off to
+`/whs:build`), content work on an existing project (already solved by
+`CONTENT.md` — just recognizes and points at it, plus a standing
+`standard-version` drift check), and converting an existing non-WHS project
+(deliberately parked, same stance as the deferred stacks). Depended on two
+small fixes, also unrecorded until now: `bin/init` seeds a given `--brief`
+file into the new project's `.claude/brief.md`; `/whs:build` defaults to
+reading it from there.
+
+### PROJECT-OVERVIEW.md, CHANGELOG.md
+
+Closed a sterility leak: both named the one real project that has adopted the
+standard in plain text, which `CLAUDE.md`'s "Keep it sterile" bans. Replaced
+with an unnamed reference, substance preserved.
+
+### bin/check
+
+Added a sub-check (4b): a maintained denylist of known real adopting-project
+names/slugs, `git grep`'d over tracked files. The existing sterile grep (check
+4) only catches a leaked domain or AdSense publisher id by shape; a bare
+project name has no such shape and was passing silently.
+
+### packages/whs-eleventy
+
+Cleanup, no behavior change: `whs status` resolved the standard by mutating
+`process.env.WHS_STANDARD` before requiring `compliance.js` — a side-channel.
+`resolveStandard()` now takes a `{ preferLocal }` option instead;
+`versionDrift()` takes the resolved standard dir as an optional argument.
+Publishes to npm at the next dated release (no `package.json` version bump
+here — nothing changes what a compliant project must do).
+
+## 2026-09-10 — a one-command standard-version catch-up, and drift that surfaces itself [non-breaking]
+
+Catching an adopted project up to a moved-on standard was a hand-written prompt
+every time. The detection existed (`whs compliance`'s severity-tagged
+`re-check #<slug>` rows) but was passive — nothing said "you're behind" unless
+someone ran it. `core.md#compliance` already expects the assistant to run
+compliance "whenever `standard-version:` is behind"; this makes the Eleventy
+stack actually do that, and adds the command that works the result. Non-breaking:
+a project compliant before is still compliant — this is an opt-in reporter, a
+session-start notice, and a new command; no requirement changes. Eleventy-only
+pilot, same stance as `/whs:build`; Phoenix/SvelteKit keep the by-hand path
+until they have a tooling package.
+
+### stacks/eleventy-netlify.md: compliance
+
+- Documented `whs status` (the drift row alone — pinned vs. current version,
+  versions behind, the `re-check` list — no codebase sweep) and its
+  `SessionStart` wiring in the `compliance` section's **Wiring** bullet. Added a
+  migration-section note: an already-adopted project that has only fallen behind
+  runs `/whs:upgrade`; one scaffolded before the command shipped copies three
+  files from the template first.
+
+### templates/eleventy-netlify
+
+- New `/whs:upgrade` command (`.claude/commands/whs/upgrade.md`) — reads the
+  CHANGELOG delta since the pin, bumps `@piercebarney/whs-eleventy`, works the
+  `compliance` backlog one `re-check` row at a time (delegating to the
+  `brand`/`content`/`layout`/`pack` stage agents where a slug is theirs), then
+  re-pins `standard-version`. Never deploys. Structured like `/whs:build`.
+- New `.claude/hooks/standard-drift.sh` + a `SessionStart` entry in
+  `.claude/settings.json` — runs `whs status --hook` at the top of every Claude
+  Code session; one line when the pin is behind, silent when current, never
+  blocks.
+- `package.json` gains a `status` script (`whs status`).
+- `CLAUDE.md` points at `/whs:upgrade` for the behind-the-standard case.
+
+### packages/whs-eleventy
+
+- New `whs status` subcommand (`lib/status.js`) — reuses `compliance.js`'s
+  `versionDrift()` (now exported) and reports the delta without running the
+  `CHECKS` sweep. `--hook` mode: one compact line when behind, nothing when
+  current, always exit 0. Registered in `cli.js`. Tests in `test/status.test.js`
+  plus a `versionDrift`-export assertion in `test/compliance.test.js`.
+
 ## 2026-09-08 — content-ops: reservation becomes a real opt-in, not a hardcoded default [non-breaking]
 
 Found while building `/whs:build`'s Content stage agent, which needs to know
@@ -50,6 +229,39 @@ true, contradicting the standard's own stated default.
   keeps `CONTENT.md` + `requests/` and the reserved paragraph; the default
   keeps neither and shows the in-repo paragraph instead.
 
+## 2026-09-08 — /whs:build, the four stage agents, and opt-in verify.sh [non-breaking]
+
+Backfilled: this landed the same day as the content-ops entry above but had no
+CHANGELOG entry of its own — a whole build-automation capability was visible
+only in git log. Recorded now so the log is a complete account of what a
+compliant project can rely on, not just what happened to get a dated entry.
+
+### templates/eleventy-netlify
+
+- `/whs:build` (`.claude/commands/whs/build.md`) — a Claude Code command that
+  runs a scaffolded project's post-`bin/init` work as four fixed stages, always
+  in order: Brand → Content → Pages & Layout → Add-on packs. Each stage plans
+  first (asking only when the brief/standard doesn't already answer something
+  and getting it wrong would force rework), delegates execution to a dedicated
+  agent, verifies against `npm run check`, and commits before moving to the
+  next stage. Never deploys. Piloted on `eleventy-netlify` only — same "don't
+  build a path nothing needs yet" stance as Phoenix/SvelteKit's deferred
+  tooling (`TODO.md`).
+- Four stage agents (`.claude/agents/{brand,content,layout,pack}.md`), each
+  anchored to a named authority: Brad Frost for Brand (tokens before
+  components), Karen McGrane for Content (structure before prose — checks
+  `CONTENT.md`'s reservation status before writing anything), Nielsen/Krug for
+  Pages & Layout (identify the primary friction point before designing), Kent
+  Beck for Add-on packs (one pack per invocation, its own commit, tests first).
+
+### templates/*
+
+- Opt-in `.claude/verify.sh` in all three stack templates, wired to a global
+  Claude Code Stop hook that lives outside this repo (the operator's own
+  `~/.claude/hooks/verify-stop.sh`): a session can't report a build done while
+  the project's own gate is red. No-ops for a project that never creates the
+  script.
+
 ## 2026-09-04 — sveltekit-netlify's brand token layer, and a Pico gap that predates it [non-breaking]
 
 Third of the four functional gaps being closed ahead of the real project
@@ -411,7 +623,7 @@ tag, so `whs compliance --strict` actually gates on being behind on a
 breaking change rather than treating every changed slug — a typo fix and a
 broken-mechanism correction alike — as the same easy-to-miss `MANUAL` note.
 This is the concrete fix for the gap `TODO.md` #1's evidence section
-documented: `everydaymoneycalc` being 8 entries behind (several of them
+documented: the one real adopting project being 8 entries behind (several of them
 breaking, per the backfill above) produced no signal beyond a note buried in
 a `MANUAL` list.
 

package/standard/core.md

@@ -1,6 +1,6 @@
 # Web project house style — CORE (stack-agnostic)
 
-**Version:** 2026-09-08 · **Status:** active
+**Version:** 2026-09-13 · **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
@@ -79,6 +79,12 @@ contents, and uses one mechanism per concern.
   sidecar files).
 - Environment access is centralised (see `#seo-urls` for the build-context
   module and `#secrets` for tokens).
+- **Feature flags** are boolean environment variables, one named flag per
+  concern (`FEATURE_<NAME>`), read through the same centralised env-access
+  module as build context — never a scattered `process.env` read. Each flag
+  defaults to preserving current behaviour when unset, and is documented in
+  `.env.example` with what it gates (`#ads`'s visibility flag is the worked
+  example).
 
 **Verify.** Review.
 
@@ -704,6 +710,12 @@ ad directives, and documented.
   gated on the same `isProduction` flag as `noindex`. Serving ads on a preview /
   staging URL wastes impressions, risks an invalid-traffic policy strike, and
   pollutes analytics.
+- **Kill switch.** Ad serving (loader, CMP, and units) also respects a feature
+  flag (`#config-idiom`) independent of the `ads:` provider declaration — the
+  declaration controls whether the plumbing (CSP, CMP, `ads.txt`) exists at
+  all; the flag controls whether it's currently allowed to render. Defaults to
+  on, so an unset flag preserves existing behaviour; flipping it off is the
+  fast path to pausing ads without a code change.
 - **Root files.** `ads.txt` (and `app-ads.txt` if the account has apps) at the
   site root, listing authorized sellers, is generated from data or is a reviewed
   file — not hand-edited over time. Excluded from the sitemap. Treated like
@@ -725,7 +737,8 @@ standard honest and makes the tradeoff explicit and reviewable.
 **Verify.** The audit page has an **Ads** panel (only when `ads:` ≠ `none`):
 `ads.txt` present and parseable; the CMP script present; the CSP grants exactly
 the declared ad origins; any `'unsafe-*'` exception noted; the loader gated on
-`isProduction`. The link/reference check (`#internal-links`) fails on any
+`isProduction`; the kill switch's current state (active vs. paused). The
+link/reference check (`#internal-links`) fails on any
 `adsbygoogle` / ad-provider reference in a non-production build and on a missing
 `ads.txt` in the production output. Manually, in a fresh browser on production:
 decline consent → no ad requests in the network panel; accept → ads load; check
@@ -1422,7 +1435,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-09-08  # recommended — enables standard-version drift tracking (#compliance)
+- standard-version: 2026-09-13  # recommended — enables standard-version drift tracking (#compliance)
 ```
 
 If the section is absent, the assistant's first action is to run the flow above