@piercebarney/whs-eleventy 2026.9.13 → 2026.9.22

package/lib/doctor.js

@@ -21,7 +21,7 @@
 const fs = require("node:fs");
 const path = require("node:path");
 const { execSync } = require("node:child_process");
-const { ROOT, projectRequire, openRequests } = require("./_project.js");
+const { ROOT, projectRequire, tryProjectRequire, openRequests } = require("./_project.js");
 const { asRegexMap } = require("./header-expect.js");
 
 const CACHE = path.join(ROOT, ".cache", "doctor.json");
@@ -29,7 +29,6 @@ const CACHE = path.join(ROOT, ".cache", "doctor.json");
 // Loaded lazily (inside the functions) so requiring this module for its API
 // doesn't fail in a dir without a project tree.
 const loadSite = () => projectRequire("src/_data/site.js");
-const loadThirdparties = () => projectRequire("src/_data/thirdparties.js");
 
 // Expected header value patterns — the single source (header-expect.js) also
 // feeds the /audit/ page's live-header check via _data/headerExpect.js.
@@ -51,8 +50,8 @@ function runRepoChecks({ preflight = false } = {}) {
   const checks = [];
   const add = (id, label, ok, severity, detail) =>
     checks.push({ id, label, ok, severity: ok ? "ok" : severity, detail });
-  const site = loadSite();
-  const thirdparties = loadThirdparties();
+  const site = tryProjectRequire("src/_data/site.js", null);
+  const thirdparties = tryProjectRequire("src/_data/thirdparties.js", null);
 
   // 1. Security headers declared in netlify.toml
   const toml = readText("netlify.toml");
@@ -74,21 +73,31 @@ function runRepoChecks({ preflight = false } = {}) {
     );
 
     // 2. Every origin the CSP grants is a declared third party
-    const cspMatch = toml.match(/Content-Security-Policy\s*=\s*"([^"]+)"/);
-    const cspOrigins = cspMatch
-      ? [...new Set((cspMatch[1].match(/https?:\/\/[^\s;'"]+/g) || []).map(originOf))]
-      : [];
-    const declaredOrigins = new Set(
-      thirdparties.flatMap((t) => [t.origin, ...(t.cspOrigins || [])]),
-    );
-    const undeclared = cspOrigins.filter((o) => !declaredOrigins.has(o));
-    add(
-      "csp-thirdparties",
-      "CSP origins all appear in src/_data/thirdparties.js",
-      undeclared.length === 0,
-      "warn",
-      undeclared.length ? `undeclared: ${undeclared.join(", ")}` : "in sync",
-    );
+    if (!thirdparties) {
+      add(
+        "csp-thirdparties",
+        "CSP origins all appear in src/_data/thirdparties.js",
+        false,
+        "blocker",
+        "src/_data/thirdparties.js missing",
+      );
+    } else {
+      const cspMatch = toml.match(/Content-Security-Policy\s*=\s*"([^"]+)"/);
+      const cspOrigins = cspMatch
+        ? [...new Set((cspMatch[1].match(/https?:\/\/[^\s;'"]+/g) || []).map(originOf))]
+        : [];
+      const declaredOrigins = new Set(
+        thirdparties.flatMap((t) => [t.origin, ...(t.cspOrigins || [])]),
+      );
+      const undeclared = cspOrigins.filter((o) => !declaredOrigins.has(o));
+      add(
+        "csp-thirdparties",
+        "CSP origins all appear in src/_data/thirdparties.js",
+        undeclared.length === 0,
+        "warn",
+        undeclared.length ? `undeclared: ${undeclared.join(", ")}` : "in sync",
+      );
+    }
   }
 
   // 3. .nvmrc matches the running Node major
@@ -190,8 +199,18 @@ function runRepoChecks({ preflight = false } = {}) {
   }
 
   // 8. site.url is a clean absolute origin
-  const cleanUrl = /^https:\/\/[^/]+\.[a-z]{2,}$/i.test(site.url);
-  add("site-url", "src/_data/site.js url is a clean https origin", cleanUrl, "warn", site.url);
+  if (!site) {
+    add(
+      "site-url",
+      "src/_data/site.js url is a clean https origin",
+      false,
+      "blocker",
+      "src/_data/site.js missing",
+    );
+  } else {
+    const cleanUrl = /^https:\/\/[^/]+\.[a-z]{2,}$/i.test(site.url);
+    add("site-url", "src/_data/site.js url is a clean https origin", cleanUrl, "warn", site.url);
+  }
 
   return checks;
 }

package/lib/status.js

@@ -4,8 +4,11 @@
 // 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)
+//   whs status --hook     silent when current; one line when behind, plus one
+//                         more if the project's src/_data/dashboard.js
+//                         (core.md#adopting's one-time setup checklist) has
+//                         unconfirmed items (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.
@@ -14,7 +17,29 @@ const fs = require("node:fs");
 const path = require("node:path");
 
 const { versionDrift } = require("./compliance.js");
-const { resolveStandard } = require("./_project.js");
+const { resolveStandard, tryProjectRequire } = require("./_project.js");
+
+// Best-effort: count src/_data/dashboard.js items still missing a verifiedOn
+// date (core.md#adopting's one-time setup checklist, rendered on /audit/'s
+// Infra tab). Never throws — a missing or malformed dashboard.js just means
+// nothing to report, same as doctor.js's live tier treats "unavailable".
+function pendingDashboardCount() {
+  const dashboard = tryProjectRequire("src/_data/dashboard.js", null);
+  if (!dashboard || !Array.isArray(dashboard.items)) return 0;
+  return dashboard.items.filter((i) => !(i && String(i.verifiedOn || "").trim())).length;
+}
+
+function printDashboardPending() {
+  let pending;
+  try {
+    pending = pendingDashboardCount();
+  } catch {
+    return;
+  }
+  if (pending > 0) {
+    console.log(`${pending} manual checklist item(s) pending — see /audit/`);
+  }
+}
 
 // `status` answers "is there a newer standard available on this machine?" — so
 // it resolves the standard text with { preferLocal: true }: the local canonical
@@ -52,6 +77,7 @@ function main() {
     rows.length === 1 && rows[0].startsWith("MANUAL: standard text not resolvable");
   if (unresolved) {
     if (!hook) console.log(rows[0]);
+    else printDashboardPending();
     return;
   }
 
@@ -62,6 +88,8 @@ function main() {
           ? `web house style: up to date (pinned ${pin}, standard at ${current})`
           : "web house style: standard-version not pinned in CLAUDE.md",
       );
+    } else {
+      printDashboardPending();
     }
     return;
   }
@@ -78,6 +106,7 @@ function main() {
       `⚠ web house style: ${behind}, ${recheck} — pinned ${pin}, standard at ${current}. ` +
         `Run /whs:upgrade to catch up.`,
     );
+    printDashboardPending();
     return;
   }
 

package/package.json

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

@@ -21,6 +21,240 @@ enforced, new *opt-in* chapters/capabilities, tooling-only changes — is
 
 ---
 
+## 2026-09-22 [non-breaking]
+
+### packages/whs-eleventy
+
+`doctor.js`'s `runRepoChecks()` crashed with an unhandled `MODULE_NOT_FOUND`
+when a project had no `src/` tree at all, instead of reporting the missing
+layout as a finding — found while adopting a real project via `/whs:adopt`
+and filed as `feedback/2026-09-22-doctor-crashes-on-no-src-layout.md`. Fixed
+in `7b43511`; this release publishes the fix. No `core.md` chapter,
+`stacks/*.md`, or `index.json` content changed.
+
+---
+
+## 2026-09-18 — Republish 2026-09-17-2 as a clean bare-date version [non-breaking]
+
+No new content. This bump republishes everything already documented under
+the 2026-09-17 entries below as a clean bare-date version, specifically to
+trigger the npm publish of `@piercebarney/whs-eleventy` that the
+2026-09-17-2 same-day-suffix mechanism deliberately does not trigger on its
+own (per that suffix's own documented exception in `CLAUDE.md`'s Versions
+section: a suffixed pin gets no git tag and no npm publish). `core.md`,
+`stacks/*.md`, `index.json`, and every `standard-version:` pin move from
+`2026-09-17-2` to `2026-09-18`; `packages/whs-eleventy/package.json` moves to
+the corresponding npm version. Nothing else changes.
+
+---
+
+## 2026-09-17 — /whs:new, and both commands go global [non-breaking]
+
+### core: adopting
+
+A new paragraph, "Mechanized new-project start," names `/whs:new` —
+`templates/commands/whs/new.md` — as the pre-scaffold sibling to
+`/whs:build`/`/whs:upgrade`/`/whs:adopt`: it mechanizes this chapter's
+"Starting point" paragraph plus the six-question flow for a project that
+doesn't exist yet. Before the user commits to a framework it reports each
+stack's real readiness — derived live from `index.json`'s `status` field
+plus an actual filesystem check for that stack's `bin/init` and stage
+agents, not a static description that can drift — then applies this
+paragraph's own fit test: an idea that doesn't honestly fit any offered
+stack routes to the same `feedback/` mechanism `/whs:adopt` already uses,
+filed before scaffolding rather than worked around. Knowingly choosing a
+stack still marked `draft` is explicitly **not** that case — it's an
+informed choice against an already-tracked, deliberately-deferred
+limitation, not a new gap. Once a stack is chosen it scaffolds via the
+existing, unmodified `templates/new-project.sh` and hands off to
+`/whs:build` where a guided build actually exists (Eleventy today);
+for a draft-stack scaffold it reports the partial result honestly and
+points at that stack's own `TEMPLATE.md`.
+
+### stacks/eleventy-netlify.md
+
+A short cross-reference in its own `#adopting` section: for a brand-new
+project, `/whs:new` will report Eleventy fully ready — scaffold, the full
+`/whs:build` pipeline, and compliance tooling all already in place, the
+one stack where the readiness table's top row is real today.
+
+### stacks/phoenix.md, stacks/sveltekit-netlify.md
+
+Each gets the matching honest counterpart: `/whs:new` reports them as
+`draft` — scaffold-only via `templates/new-project.sh`, no `bin/init`
+(manual placeholder fill per each stack's own `TEMPLATE.md`), no guided
+`/whs:build` equivalent, no compliance tooling — the same gap list their
+own `#adopting` sections already carry, not a new one.
+
+### templates/commands
+
+New file, `templates/commands/whs/new.md` — the fourth command in the
+`/whs:build` / `/whs:upgrade` / `/whs:adopt` family, this one for a
+destination that doesn't exist yet, not even a directory. It walks
+`templates/concept-brief.md` conversationally (the same ideation
+`COWORK.md`'s "New project" flow already does, run here instead), stops
+before answering the framework question to show the live readiness table,
+applies the fit test with its three outcomes (fits cleanly, including a
+knowing `draft` choice / no offered stack fits, routing to `feedback/` /
+abandon), then scaffolds via `templates/new-project.sh` unmodified and
+reports one of three real outcomes matching the script's actual behavior:
+`bin/init` ran (Eleventy), a partial scaffold with no `bin/init` (Phoenix,
+SvelteKit today), or a genuine unexpected failure.
+
+### README.md
+
+Both `/whs:new` and `/whs:adopt` switch distribution model: instead of a
+per-project `cp` of the command file into `.claude/commands/whs/`, the
+`## Home` section now documents a single global symlink,
+`~/.claude/commands/whs/` → this repo's `templates/commands/whs/`, set up
+once per machine. This is a real behavior change for `/whs:adopt`, not
+just new documentation for `/whs:new`: a machine that already did the old
+per-project copy-in keeps working for that project, but every new project
+now picks up both commands automatically, and editing a command's source
+here updates what's "installed" everywhere with no copy-and-drift step.
+The "Onboarding an existing project" subsection drops its old copy
+instructions and now just points at `## Home`.
+
+This bump moves the doc pins to `2026-09-17-2` (a same-day suffix — see
+this repo's `CLAUDE.md`'s Versions section): `2026-09-17` was already used
+today for the `/whs:adopt` entry below. `packages/*/package.json` is left
+untouched on purpose; this release gets no git tag and no npm publish on
+its own.
+
+---
+
+## 2026-09-17 — /whs:adopt mechanizes onboarding for a preexisting project [non-breaking]
+
+### core: adopting
+
+A new paragraph, "Mechanized onboarding," names `/whs:adopt` — copied from
+`templates/commands/whs/adopt.md` into a project's own
+`.claude/commands/whs/adopt.md` — as the command that runs this entire
+chapter end-to-end inside a project that has never adopted the standard,
+including one on a stack this repo has no binding for. It detects the
+stack, runs the six-question flow already documented here, and, before
+writing anything, judges whether the project is even compatible with the
+standard: a genuine out-of-scope project (native mobile, an embedded CLI,
+anything the standard's domain never covered) gets a clean decline with
+nothing written or filed; a real gap in the standard routes to the existing
+`feedback/` mechanism, the same "Starting point" reasoning this chapter
+already applies to a new-project brief that doesn't honestly fit an offered
+stack. Once adoption proceeds it writes the `## House style` block, wires in
+real tooling where it exists, and produces — but deliberately does not
+work — an initial migration backlog, which stays incremental by hand or via
+`/whs:upgrade` afterward. Nothing here changes what a compliant project
+already had to do; this is a new, opt-in way to reach the same state
+`core.md#adopting` already describes.
+
+### stacks/eleventy-netlify.md
+
+Its own `#adopting` section gets a short cross-reference: for a project
+`/whs:adopt` onboards, it proposes `@piercebarney/whs-eleventy` as a
+devDependency plus `check`/`compliance`/`status` npm scripts (asking first
+if a conflicting script already exists or the build setup looks
+non-trivial), then runs `npm run compliance` for the initial backlog — the
+one stack where the mechanized path can actually run a real check.
+
+### stacks/phoenix.md, stacks/sveltekit-netlify.md
+
+Each gets the same kind of cross-reference, honestly scoped down: since
+neither draft binding has compliance-sweep tooling yet (the same
+`mix a11y`/`links.check`/`whs.check` gap their own `#adopting` sections
+already note), `/whs:adopt` can still detect the stack and record the
+`## House style` block with the gate command filled in from what the
+project already runs (`mix check` / `npm run check`), but the migration
+backlog for these two comes from walking `core.md`'s chapters by hand
+rather than from an automated sweep.
+
+### templates/commands
+
+New file, `templates/commands/whs/adopt.md` — the command itself, the
+third in the `/whs:build` / `/whs:upgrade` / `/whs:adopt` family, this one
+for a project that's never touched the standard at all. Unlike the other
+two it assumes nothing scaffolded yet (no stage agents, no `## House style`
+block, possibly no stack binding), so it runs mostly inline: two guards
+before starting (an already-adopted project gets pointed at `/whs:upgrade`
+instead; a directory with no manifest at all gets pointed at
+`templates/new-project.sh` instead), then stack detection, the
+six-question flow, the compatibility judgment with its three outcomes
+(compatible / out-of-scope-not-a-defect / genuine-gap-file-a-feedback-note),
+recording the `## House style` block, tiered tooling wiring, and a
+committed `.claude/whs-migration-backlog.md` as the durable artifact —
+never a chat transcript — of what the project still owes.
+
+### README.md
+
+New "Onboarding an existing project" subsection under "How to use it,"
+documenting the one-time manual copy-in (`cp
+~/.claude/standards/web-house-style/templates/commands/whs/adopt.md
+.claude/commands/whs/adopt.md`) and pointing at `/whs:adopt` — the same
+"standard checked out at `~/.claude/standards/web-house-style/`"
+assumption every adopted project's own `CLAUDE.md` directive already
+makes, no new install mechanism.
+
+### CLAUDE.md, .claude/agents/infra.md
+
+Both the root `CLAUDE.md` agent-roster listing and `infra`'s own Scope
+section are extended to name stack-agnostic content living directly at the
+`templates/` root — not nested inside any single `templates/<stack>/`,
+e.g. `templates/concept-brief.md`, `templates/new-project.sh`, and now
+`templates/commands/` — as `infra`'s territory. `/whs:adopt` is the first
+file to actually land there; without this the delegation rule this repo's
+own `CLAUDE.md` requires had no answer for who owns it.
+
+---
+
+## 2026-09-13 — One-time adopting setup becomes a tracked, dated confirmation [non-breaking]
+
+### core: adopting
+
+The one-time human setup a project owes after adopting/converting/upgrading
+(secrets, host config, DNS) is now tracked the same way `#compliance` already
+tracks its `MANUAL` rows: a committed, dated `verifiedOn` confirmation per
+item, plus a best-effort, non-blocking session-start check that flags
+unconfirmed items. This is not a gate — same reasoning `#compliance` gives
+for keeping `MANUAL` rows out of `#the-gate` — so nothing that was compliant
+before this change becomes non-compliant after it; the mechanism is purely
+additive.
+
+### templates/eleventy-netlify
+
+Implements the contract for real: `bin/init` now seeds
+`src/_data/dashboard.js` with the one-time setup items, committed as part of
+the initial commit (a reviewer-caught ordering bug in the original build,
+now fixed). `packages/whs-eleventy`'s `whs status --hook` (already
+SessionStart-hooked) counts unconfirmed dashboard items and prints a
+best-effort pending-count line. The dangling `BUILD-STATUS.md` reference —
+never actually created by anything — is retired from `bin/init` and
+`TEMPLATE.md`.
+
+### stacks/sveltekit-netlify, stacks/phoenix
+
+Each gets a short honest note in its `#adopting` mirror that this tracking
+isn't built for that stack yet. No functional or template changes.
+
+This bump moves the doc pins to `2026-09-13-2` (a same-day suffix — see this
+repo's `CLAUDE.md`'s Versions section): `2026-09-13` was already used today
+for the republish entry below. `packages/whs-eleventy/package.json` is left
+untouched on purpose; this release gets no git tag and no npm publish on its
+own.
+
+---
+
+## 2026-09-13 — Republish 2026-09-12-2 as a clean bare-date version [non-breaking]
+
+No new content. This bump republishes everything already documented under
+the 2026-09-11 and 2026-09-12 entries below as a clean bare-date version,
+specifically to trigger the npm publish of `@piercebarney/whs-eleventy` that
+the 2026-09-12-2 same-day-suffix mechanism deliberately does not trigger on
+its own (per that suffix's own documented exception in `CLAUDE.md`'s
+Versions section: a suffixed pin gets no git tag and no npm publish). `core.md`,
+`stacks/*.md`, `index.json`, and every `standard-version:` pin move from
+`2026-09-12-2` to `2026-09-13`; `packages/whs-eleventy/package.json` moves to
+the corresponding npm version. Nothing else changes.
+
+---
+
 ## 2026-09-12 — A same-day-release suffix, two feedback fixes, and an /whs:upgrade false-negative [non-breaking]
 
 ### templates/eleventy-netlify

package/standard/core.md

@@ -1,6 +1,6 @@
 # Web project house style — CORE (stack-agnostic)
 
-**Version:** 2026-09-13 · **Status:** active
+**Version:** 2026-09-22 · **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
@@ -1394,6 +1394,38 @@ brief cannot honestly fit an offered stack, that is a `feedback/` note (below)
 filed *before* the build — resolved as a new binding, or the nearest stack with
 the compromise recorded.
 
+**Mechanized new-project start.** `/whs:new` — `templates/commands/whs/new.md`,
+available the same way as `/whs:adopt` via the `~/.claude/commands/whs/`
+symlink (`README.md`'s `## Home` section) — mechanizes this "Starting point"
+paragraph plus the six-question flow above,
+for a project that doesn't exist yet. Before asking the user to commit to a
+framework, it reports each stack's actual readiness live — derived from
+`index.json`'s status plus a real filesystem check (does that stack's
+`bin/init` exist? do its stage agents exist?), not a static description that
+can drift out of date — naming explicitly which stacks carry a full pipeline
+(scaffold plus a guided build) versus a draft scaffold with known,
+already-tracked gaps. It then applies this paragraph's own test: if the
+described idea doesn't honestly fit any offered stack, that's the same
+`feedback/` path above, filed before scaffolding rather than worked around —
+knowingly choosing a stack still marked `draft` is *not* that case; it's an
+informed choice against an already-tracked, deliberately-deferred limitation,
+not a new gap. Once a stack is chosen, `/whs:new` hands off to `/whs:build`
+where a guided build actually exists (Eleventy today); for a draft-stack
+scaffold it reports the partial result honestly and points at that stack's
+own `TEMPLATE.md`.
+
+**One-time setup.** Adopting, converting, or upgrading against the standard
+often leaves a project owing **one-time human setup** no script can finish for
+it — hosting/repo config, DNS, minting a secret (`#secrets`). That debt is
+tracked the same way `#compliance` already tracks a `MANUAL` row: a committed
+item carrying a dated `verifiedOn` confirmation, not a message printed once
+to a terminal and forgotten. A session-start check flags any item still
+unconfirmed so it can't go silently stale — **not a gate**; per
+`#compliance`'s own reasoning for staying out of `#the-gate`, visibility beats
+blocking so an unrelated pending item never freezes incremental adoption. The
+concrete shape — which items, how they're seeded, how the check runs — lives
+in each impl doc's own new-project checklist.
+
 **Record** the result near the top of the project's `.claude/CLAUDE.md` /
 `AGENTS.md` as a `## House style` section — a directive paragraph plus a data
 block. The recommended text:
@@ -1435,7 +1467,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-13  # recommended — enables standard-version drift tracking (#compliance)
+- standard-version: 2026-09-22  # recommended — enables standard-version drift tracking (#compliance)
 ```
 
 If the section is absent, the assistant's first action is to run the flow above
@@ -1464,6 +1496,25 @@ worked incrementally (the impl doc's migration path is the ordered version of
 that backlog). The project is not expected to be all-`PASS` on day one; it is
 expected to know exactly where it isn't.
 
+**Mechanized onboarding.** `/whs:adopt` — copied from
+`templates/commands/whs/adopt.md` into a project's own
+`.claude/commands/whs/adopt.md` — runs this entire section end-to-end inside a
+preexisting, never-adopted project: it detects the stack, runs the six-question
+flow above, then, before writing anything, judges whether the project is
+actually compatible with the standard. Two failure modes are distinct there:
+the project may simply be out of the standard's domain (not a defect — nothing
+gets filed or written), or the standard may have a genuine gap for a real need
+the project has, which routes to the same `feedback/` mechanism below
+(**Feedback to the standard**) before or alongside finalizing adoption, exactly
+as this section's own "Starting point" paragraph already does for a new-project
+brief that doesn't honestly fit an offered stack. Once adoption proceeds, it
+writes the `## House style` block above, then, where stack tooling exists to
+wire in, runs an initial compliance pass. It **produces** the initial
+migration backlog; it does not work it — working the backlog stays
+incremental, by hand or later via `/whs:upgrade` once the project is
+version-pinned and catching up to a newer standard release. `/whs:adopt` and
+`/whs:upgrade` are deliberately different commands with different scopes.
+
 **Feedback to the standard.** Adopting the house style is what surfaces its
 bugs — a check that misfires, a `core.md` ↔ impl-doc contradiction, a Contract
 that doesn't survive a real codebase, a need it never anticipated. That signal