cursedbelt 1.0.0 → 2.3.0

package/src/server/retention/store.ts

@@ -27,15 +27,22 @@
  * back up, copy to a box, or read at a glance.
  *
  * ── Where it lives ──────────────────────────────────────────────────────────
- * `~/.app-managed/retention` on this Mac — the App_Managed_Home contract's spot
- * for outside-repo state, and shared by every local app so the station sees one
- * fleet. A deployed box has no `~/.app-managed` and (under `ProtectSystem=strict`)
- * only its data dir is writable, so it falls back to `$APP_DATA_DIR/retention`:
- * the app still sweeps on the same code and the same defaults, and a station
- * instance on that box reads that box's fleet. The resolution probes
- * WRITABILITY rather than assuming, because the failure it prevents — an app
- * whose every publish silently EROFS-es — is invisible until someone asks why
- * the UI is empty.
+ * `<app-data-home>/retention` — one root shared by every local app, so the
+ * station sees one fleet. The home is CONFIGURATION ({@link resolveAppDataHome}):
+ * `$APP_DATA_HOME` when a machine keeps every app's data under one root, else the
+ * OS's own convention (`$XDG_DATA_HOME`, `~/Library/Application Support`).
+ *
+ * 🔴 It was `~/<a private dotfolder>` until 2026-09-13, hardcoded, in a PUBLISHED
+ * package — so anyone who installed cursedbelt got a library hunting for one
+ * person's directory layout. A library may know what its caller told it and what
+ * the OS says; it may not know the name of a folder in somebody's home.
+ *
+ * A deployed box under `ProtectSystem=strict` has only its own data dir writable,
+ * so it falls back to `$APP_DATA_DIR/retention`: the app still sweeps on the same
+ * code and the same defaults, and a station instance on that box reads that box's
+ * fleet. The resolution probes WRITABILITY rather than assuming, because the
+ * failure it prevents — an app whose every publish silently EROFS-es — is
+ * invisible until someone asks why the UI is empty.
  */
 import {
 	existsSync,
@@ -46,8 +53,8 @@ import {
 	rmSync,
 	writeFileSync,
 } from "node:fs";
-import { homedir } from "node:os";
 import { join } from "node:path";
+import { APP_DATA_HOME_ENV, resolveAppDataHome } from "../paths/appDataHome";
 import type { RetentionDeclaration, RetentionOverride } from "./policy";
 import { retentionKey } from "./policy";
 
@@ -155,15 +162,15 @@ export function resolveRetentionHome(
 	if (cachedHome) return cachedHome;
 	const candidates: string[] = [];
 	if (env.RETENTION_HOME) candidates.push(env.RETENTION_HOME);
-	if (env.APP_MANAGED_HOME) candidates.push(join(env.APP_MANAGED_HOME, "retention"));
-	// `env.HOME` rather than `homedir()` alone so a caller passing an env object
-	// gets a resolution it can actually control — the tests need to reason about a
-	// machine WITHOUT a shared app-managed home, which is every deployed box.
-	const conventional = join(env.HOME ?? homedir(), ".app-managed");
-	// Only prefer the shared Mac home when it already exists: on a deployed box
-	// creating it would either fail (read-only namespace) or strand a publication
-	// somewhere no station instance looks.
-	if (existsSync(conventional)) candidates.push(join(conventional, "retention"));
+	// An explicitly CONFIGURED home is used whether or not it exists yet — the
+	// operator naming it is the statement that it is the right place.
+	const configured = env[APP_DATA_HOME_ENV]?.trim();
+	if (configured) candidates.push(join(configured, "retention"));
+	const conventional = resolveAppDataHome({ env });
+	// The OS convention is only PREFERRED when it is already there: on a deployed
+	// box creating it would either fail (read-only namespace) or strand a
+	// publication somewhere no station instance looks.
+	if (!configured && existsSync(conventional)) candidates.push(join(conventional, "retention"));
 	if (env.APP_DATA_DIR) candidates.push(join(env.APP_DATA_DIR, "retention"));
 	candidates.push(join(conventional, "retention"));
 

package/src/server/runtime/localHost.spec.ts

@@ -9,6 +9,7 @@ import { tmpdir } from 'node:os';
 import path from 'node:path';
 import type { Argon2idDeriver } from 'cwip/guard';
 import { setArgon2idDeriver } from 'cwip/guard';
+import { resolveAppDataHome } from '../paths/appDataHome';
 import {
   createLocalDevServices,
   createLocalGuardServices,
@@ -29,16 +30,34 @@ afterEach(() => {
 });
 
 describe('resolveAppDataRoot', () => {
-  it('hangs off the ONE app-managed home, never a bespoke ~/.<app>', () => {
-    const root = resolveAppDataRoot({ appId: 'demo', env: { APP_MANAGED_HOME: '/srv/managed' } });
+  it('hangs off the ONE configured app-data home, never a bespoke ~/.<app>', () => {
+    const root = resolveAppDataRoot({ appId: 'demo', env: { APP_DATA_HOME: '/srv/managed' } });
     expect(root).toBe(path.join('/srv/managed', 'instances', 'demo'));
   });
 
   it('lets an explicit override win outright', () => {
-    expect(resolveAppDataRoot({ appId: 'demo', override: '/data/demo', env: { APP_MANAGED_HOME: '/srv' } })).toBe(
+    expect(resolveAppDataRoot({ appId: 'demo', override: '/data/demo', env: { APP_DATA_HOME: '/srv' } })).toBe(
       '/data/demo',
     );
   });
+
+  /*
+   * 🔴 With nothing configured it lands on the OS's convention, NOT on a folder
+   * this library invented in somebody's home. That was the published defect
+   * (2026-09-13): `cursedbelt@1.0.0` resolved the previous generation's private
+   * state root for every installer of the package.
+   */
+  it("falls back to the OS convention, not to anybody's private folder", () => {
+    const root = resolveAppDataRoot({ appId: 'demo', env: { HOME: '/home/nobody' } });
+    expect(root).toBe(path.join(resolveAppDataHome({ env: { HOME: '/home/nobody' } }), 'instances', 'demo'));
+    expect(root).not.toContain('app-managed');
+    expect(root.startsWith('/home/nobody/')).toBe(true);
+  });
+
+  it('ignores the previous generation env var entirely', () => {
+    const env = { HOME: '/home/nobody', APP_MANAGED_HOME: '/nowhere/inherited' };
+    expect(resolveAppDataRoot({ appId: 'demo', env })).not.toContain('/nowhere/inherited');
+  });
 });
 
 describe('loadOrMintKeyFile', () => {

package/src/server/runtime/localHost.ts

@@ -12,8 +12,10 @@
  * So this is the local host, once, as a tested unit. It owns four things a
  * machine-level host owns and a library must not:
  *
- *   1. **Where the app's data lives** — `~/.app-managed/instances/<appId>`, honoring
- *      `APP_MANAGED_HOME` through cwip's ONE resolver (never a bespoke `~/.<app>`).
+ *   1. **Where the app's data lives** — `<app-data-home>/instances/<appId>`, where
+ *      the home is CONFIGURATION ({@link resolveAppDataHome}): an explicit
+ *      argument, else `$APP_DATA_HOME`, else the OS convention. Never a bespoke
+ *      `~/.<app>` directory, and never a folder named after one machine's owner.
  *   2. **Key custody.** The object-store URL signing key and the telemetry row
  *      integrity key are minted once, persisted `0600`, and read back **as bytes**
  *      — never as a string (V6 `key-material-as-string`; a hex string of a key
@@ -34,7 +36,6 @@
 import { Database } from 'bun:sqlite';
 import { generateKeyPairSync } from 'node:crypto';
 import { chmodSync, existsSync, mkdirSync, readFileSync, readdirSync, statSync, type Stats, writeFileSync } from 'node:fs';
-import { homedir } from 'node:os';
 import path from 'node:path';
 import {
   assertArgon2idReady,
@@ -59,10 +60,10 @@ import type { DevServiceDeps, GuardServiceDeps } from './recipe';
 import {
   createTelemetryWriter,
   openTelemetryDatabase,
-  resolveAppManagedHome,
   type TelemetryDatabase,
   type TelemetryWriter,
 } from 'cwip/telemetry';
+import { resolveAppDataHome } from '../paths/appDataHome';
 
 /** Bytes in a minted key file. Matches cwip's `CC_KEY_BYTES`. */
 export const HOST_KEY_BYTES = 32;
@@ -71,21 +72,23 @@ export interface ResolveAppDataRootOptions {
   readonly appId: string;
   /** Explicit override (a `--data-root` flag, `CC_DATA_ROOT`). Wins outright. */
   readonly override?: string;
-  /** Environment to read `APP_MANAGED_HOME` from. Injected by tests. */
+  /** Environment to read `APP_DATA_HOME` from. Injected by tests. */
   readonly env?: Record<string, string | undefined>;
 }
 
 /**
- * `<app-managed-home>/instances/<appId>` — the app's data root.
+ * `<app-data-home>/instances/<appId>` — the app's data root.
  *
  * A HOST function, not a library one: `openDomainHandles` still refuses to derive
- * a path, and this is the thing that hands it one.
+ * a path, and this is the thing that hands it one. The home underneath it is
+ * {@link resolveAppDataHome} — configuration, then the OS convention, and nothing
+ * else. A published package may not go looking for a directory it invented in
+ * somebody's home.
  */
 export function resolveAppDataRoot(options: ResolveAppDataRootOptions): string {
   const override = options.override?.trim();
   if (override) return path.resolve(override);
-  const home = options.env ? resolveAppManagedHome(options.env) : resolveAppManagedHome();
-  return path.join(home || path.join(homedir(), '.app-managed'), 'instances', options.appId);
+  return path.join(resolveAppDataHome({ env: options.env }), 'instances', options.appId);
 }
 
 /**

package/src/server/runtime/meterRollup.pg.test.ts

@@ -98,6 +98,7 @@ const shipAll = async (...list: readonly Node[]): Promise<void> => {
   }
 };
 
+// SKIPPED unless CC_PG_URL names a throwaway Postgres — this suite's subject IS the engine. `bun run test:pg` supplies one.
 describe.skipIf(!URL_)('the shared meter against a real Postgres (04 item 4e)', () => {
   // 120s rather than Bun's 5s, for the reason `pooledControlStores.pg.test.ts`
   // records: this hook issues real DDL against a real engine, and on a shared CI

package/src/server/runtime/recipe.ts

@@ -249,10 +249,10 @@ export function resolveManagedDomains(
 
 export interface OpenDomainHandlesOptions {
   /**
-   * Where the per-domain SQLite files live (host-resolved, e.g.
-   * `~/.app-managed/instances/<appId>/`). Required unless every needed domain
-   * is supplied via `handles` — the library never invents a path from env
-   * (handle-injection law).
+   * Where the per-domain SQLite files live (host-resolved, e.g. an
+   * `instances/<appId>/` directory under the host's own app-data root).
+   * Required unless every needed domain is supplied via `handles` — the
+   * library never invents a path from env (handle-injection law).
    */
   readonly root?: string;
   /**

package/src/server/runtime/retentionJob.pg.test.ts

@@ -61,6 +61,7 @@ const meterCount = async (): Promise<number> =>
 const auditCount = async (): Promise<number> =>
   Number(((await sql.unsafe(`SELECT COUNT(*)::int AS n FROM ${AUDIT_TRAIL_TABLE}`)) as Array<{ n: number }>)[0]?.n ?? -1);
 
+// SKIPPED unless CC_PG_URL names a throwaway Postgres — this suite's subject IS the engine. `bun run test:pg` supplies one.
 describe.skipIf(!URL_)('the retention job against a real Postgres (01 §4)', () => {
   // 120s rather than Bun's 5s, for the reason the sibling pg suites record: this
   // hook issues real DDL, and on a shared runner a timeout surfaces as a

package/src/server/search/pgSearchProvider.pg.test.ts

@@ -78,6 +78,7 @@ const doc = (id: string, title: string, body: string, tenantId = TENANT) => ({
   body,
 });
 
+// SKIPPED unless CC_PG_URL names a throwaway Postgres — this suite's subject IS the engine. `bun run test:pg` supplies one.
 describe.skipIf(!ADMIN_URL)('createPgSearchProvider against a real Postgres (04 §3)', () => {
   // 120s for the same reason the control-plane suite gives: this hook drops and
   // rebuilds a whole role, database and schema, and on a shared CI runner a 5s

package/src/server/storage/binaryServerProcessing.integration.spec.ts

@@ -13,10 +13,14 @@ import { fsHlsMasterKey, fsMp4Key, fsPosterKey } from './types';
 // into its own store. Skips cleanly when the checkout or ffmpeg is absent.
 // Mirrors transcode.integration.spec.ts's harness.
 
-const BS_DIR = process.env.BINARY_SERVER_DIR ?? '/Users/curt/code/local/binary-server';
-const BS_PRESENT = existsSync(path.join(BS_DIR, 'src', 'index.ts'));
+const BS_DIR = process.env.BINARY_SERVER_DIR ?? '';
+const BS_PRESENT = BS_DIR !== '' && existsSync(path.join(BS_DIR, 'src', 'index.ts'));
 const FFMPEG_PRESENT = Bun.which('ffmpeg') !== null;
 
+// SKIPPED until a real binary-server checkout is present: point BINARY_SERVER_DIR at one.
+// There is deliberately no default — a published package must not go looking in one machine's
+// directory layout — and `binary-server` has not been re-homed here, so this skips on every host today.
+// ffmpeg must be on PATH too: the proof is that the REMOTE side runs real ffmpeg, not that the client posted a job.
 describe.skipIf(!BS_PRESENT || !FFMPEG_PRESENT)(
   'binaryServerProcessing → real binary-server (integration)',
   () => {

package/src/server/storage/chunked.integration.spec.ts

@@ -22,8 +22,8 @@ import type { MediaCtx } from './types';
 // chunk DIRECT to bs → bs assembles on the last chunk → complete registers the catalogue row over
 // the assembled bytes — and read the bytes back through the store. Skips cleanly when the local
 // binary-server checkout isn't present (CI / other machines).
-const BS_DIR = process.env.BINARY_SERVER_DIR ?? '/Users/curt/code/local/binary-server';
-const BS_PRESENT = existsSync(path.join(BS_DIR, 'src', 'index.ts'));
+const BS_DIR = process.env.BINARY_SERVER_DIR ?? '';
+const BS_PRESENT = BS_DIR !== '' && existsSync(path.join(BS_DIR, 'src', 'index.ts'));
 const ISSUER = 'https://demo.local';
 const APP_ID = 'demo';
 const CTX: MediaCtx = { userId: 'user-stub', tenantId: 'user-stub' };
@@ -38,6 +38,9 @@ const pem = (der: ArrayBuffer, label: string) =>
       .match(/.{1,64}/g) ?? []
   ).join('\n')}\n-----END ${label}-----\n`;
 
+// SKIPPED until a real binary-server checkout is present: point BINARY_SERVER_DIR at one.
+// There is deliberately no default — a published package must not go looking in one machine's
+// directory layout — and `binary-server` has not been re-homed here, so this skips on every host today.
 describe.skipIf(!BS_PRESENT)('chunked upload → real binary-server (integration)', () => {
   let server: TestServer | null = null;
   let tmp = '';

package/src/server/storage/fileUploadClient-chunked.integration.spec.ts

@@ -26,8 +26,8 @@ import type { MediaCtx } from './types';
 // generated app uses in production — and pins the load-bearing property: the app origin sees
 // ONLY the small init/complete JSON calls, while every chunk PUTs DIRECT to binary-server.
 // Skips cleanly when the local binary-server checkout isn't present (CI / other machines).
-const BS_DIR = process.env.BINARY_SERVER_DIR ?? '/Users/curt/code/local/binary-server';
-const BS_PRESENT = existsSync(path.join(BS_DIR, 'src', 'index.ts'));
+const BS_DIR = process.env.BINARY_SERVER_DIR ?? '';
+const BS_PRESENT = BS_DIR !== '' && existsSync(path.join(BS_DIR, 'src', 'index.ts'));
 const ISSUER = 'https://demo.local';
 const APP_ID = 'demo';
 const CTX: MediaCtx = { userId: 'user-stub', tenantId: 'user-stub' };
@@ -42,6 +42,9 @@ const pem = (der: ArrayBuffer, label: string) =>
       .match(/.{1,64}/g) ?? []
   ).join('\n')}\n-----END ${label}-----\n`;
 
+// SKIPPED until a real binary-server checkout is present: point BINARY_SERVER_DIR at one.
+// There is deliberately no default — a published package must not go looking in one machine's
+// directory layout — and `binary-server` has not been re-homed here, so this skips on every host today.
 describe.skipIf(!BS_PRESENT)('fileUploadClient chunked path → real binary-server (integration)', () => {
   let server: TestServer | null = null;
   let tmp = '';

package/src/server/storage/files/adapter.photo.display.spec.ts

@@ -75,6 +75,7 @@ async function heicBytes(): Promise<Uint8Array | null> {
   return bytes;
 }
 
+// SKIPPED on a host without ffmpeg/ffprobe — it synthesizes and decodes real media. Runs by default wherever ffmpeg is installed.
 describe.skipIf(!haveFfmpeg)('photo display derivative (HEIC)', () => {
   let db: Database;
   let root: string;

package/src/server/storage/imageThumbnail.spec.ts

@@ -44,6 +44,7 @@ async function makeHeic(dest: string): Promise<boolean> {
   return proc.exitCode === 0;
 }
 
+// SKIPPED on a host without ffmpeg/ffprobe — it synthesizes and decodes real media. Runs by default wherever ffmpeg is installed.
 describe.skipIf(!haveFfmpeg)('ffmpegImageThumbnail', () => {
   test('decodes an HEVC/HEIC-style still into a width-capped JPEG', async () => {
     const root = await mkdtemp(path.join(tmpdir(), 'cb-imgthumb-'));

package/src/server/storage/transcode.integration.spec.ts

@@ -13,9 +13,12 @@ import { pickFreePort, startTestServer, type TestServer } from 'cwip/testing';
 // Contract: POST /api/transcode → { jobId }, GET /api/transcode/:jobId → { status, progress?, result? }.
 // Auth: x-internal-secret header must match process.env.INTERNAL_SECRET.
 
-const BS_DIR = process.env.BINARY_SERVER_DIR ?? '/Users/curt/code/local/binary-server';
-const BS_PRESENT = existsSync(path.join(BS_DIR, 'src', 'index.ts'));
+const BS_DIR = process.env.BINARY_SERVER_DIR ?? '';
+const BS_PRESENT = BS_DIR !== '' && existsSync(path.join(BS_DIR, 'src', 'index.ts'));
 
+// SKIPPED until a real binary-server checkout is present: point BINARY_SERVER_DIR at one.
+// There is deliberately no default — a published package must not go looking in one machine's
+// directory layout — and `binary-server` has not been re-homed here, so this skips on every host today.
 describe.skipIf(!BS_PRESENT)('transcode API → real binary-server (integration)', () => {
   let port: number;
   let storeDir: string;

package/src/server/storage/videoProcessor.posterOnly.spec.ts

@@ -33,6 +33,7 @@ async function makeSource(dest: string, duration = 2): Promise<void> {
 }
 
 // posterOnly is the memory-constrained-host path: a poster + duration, but NO heavy HLS/re-encode.
+// SKIPPED on a host without ffmpeg/ffprobe — it synthesizes and decodes real media. Runs by default wherever ffmpeg is installed.
 describe.skipIf(!haveFfmpeg)('processVideo posterOnly', () => {
   test('extracts a poster + duration, ready, no HLS', async () => {
     const root = await mkdtemp(path.join(tmpdir(), 'cb-poster-only-'));

package/src/shared/errors.ts

@@ -11,7 +11,7 @@
  *
  * Clients parse exactly this shape, so there is no per-route error drift — and no
  * drift between a cwip-based server (which already emits it via `cwip/server`'s
- * `errorHandler`) and a cursedbelt/cursedshell one. The extra fields are additive:
+ * `errorHandler`) and a cursedshell one. The extra fields are additive:
  * a client that only reads `message`/`code`/`context` keeps working unchanged.
  *
  * `ApiError` is the ergonomic throwable: `throw new ApiError(404, 'not found')`.

package/src/skippedTestsAreAnswered.spec.ts

@@ -0,0 +1,215 @@
+/**
+ * 🔴 NO COMMENT, NO SKIP — and the doc that answers "what were they for" must stay true.
+ *
+ * ## What this cost, 2026-09-13
+ *
+ * `bun run verify` reported **5,132 pass / 82 skip / 0 fail**. Nobody could say what the 82
+ * were. Each had been written because something mattered and each had stopped running for a
+ * reason that was, by then, invisible: the gate condition was in the code
+ * (`describe.skipIf(!URL_)`), but *why that variable is unset on every host we own* was in
+ * nobody's head. A suite that carries a number like that quietly is a suite whose green means
+ * less than it says.
+ *
+ * Answering it took 16m 5s of agent time — the figure the runner's ledger recorded for the task,
+ * not an estimate — spent booting a throwaway Postgres, locating a binary-server checkout, and
+ * running each gated suite by hand to learn whether it still passes. All 82 turned out to be
+ * healthy, environment-gated proofs. That is the good outcome, and it is exactly why the next
+ * person must not have to re-derive it: the cost was never the fixing, it was the *finding
+ * out*.
+ *
+ * ## So this is a check, not a paragraph
+ *
+ * Two assertions, both of which fail the moment the record stops matching the code:
+ *
+ *  1. **Every skip site in `src` carries its reason in the comment directly above it.** A new
+ *     `describe.skipIf` with no comment is a red gate, at the moment it is written, by the
+ *     person who knows the answer — which is the only moment the answer is cheap.
+ *  2. **`docs/skipped-tests.md` names exactly the files that have one.** A skip that is
+ *     deleted or added without updating the record reds too, so the doc cannot rot into the
+ *     confident-but-wrong state that makes a doc worse than nothing.
+ *
+ * It deliberately does NOT assert a skip COUNT. The counts move with the host — ffmpeg
+ * installed or not, `CC_PG_URL` set or not — and a check that reds because someone installed
+ * `sharp` teaches people to delete the check.
+ */
+import { describe, expect, test } from 'bun:test';
+import { readdirSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const SRC = fileURLToPath(new URL('.', import.meta.url));
+const REPO = path.resolve(SRC, '..');
+const SELF = 'src/skippedTestsAreAnswered.spec.ts';
+const DOC = 'docs/skipped-tests.md';
+
+/**
+ * A skip site: `describe.skip`, `.todo`, `.failing`, `.skipIf`, `.todoIf` on any of bun's three
+ * entry points, plus the jasmine-era `xit(` / `xdescribe(`.
+ *
+ * Anchored on the entry point so that ordinary identifiers containing "skip" — `skipDirs`,
+ * `skipToken`, `skipKdfReadinessGate`, all of which live in this package — are not sites.
+ */
+const SKIP_SITE = /\b(?:describe|it|test)\s*\.\s*(?:skip|todo|failing|skipIf|todoIf)\b|\bx(?:it|describe)\s*\(/;
+
+/** A comment line, in either style, as it appears immediately above a skip site. */
+const COMMENT_LINE = /^\s*(?:\/\/|\/\*|\*)/;
+
+export interface SkipSite {
+  /** 1-indexed, so a failure message is clickable. */
+  readonly line: number;
+  readonly text: string;
+  /** The contiguous comment block directly above, with no blank line between it and the site. */
+  readonly reason: string;
+}
+
+/**
+ * Every skip site in one file's source, each carrying whatever comment sits directly above it.
+ *
+ * "Directly above" is strict on purpose: a blank line between the comment and the site ends the
+ * block. The failure this guards against is a skip drifting away from the explanation that was
+ * once next to it, and a blank line is exactly how that drift starts.
+ */
+export const findSkipSites = (source: string): SkipSite[] => {
+  const lines = source.split('\n');
+  const sites: SkipSite[] = [];
+  for (let i = 0; i < lines.length; i += 1) {
+    const text = lines[i] as string;
+    if (!SKIP_SITE.test(text)) continue;
+    const above: string[] = [];
+    for (let j = i - 1; j >= 0; j -= 1) {
+      const prev = lines[j] as string;
+      if (!COMMENT_LINE.test(prev)) break;
+      above.unshift(prev);
+    }
+    sites.push({ line: i + 1, text: text.trim(), reason: above.join('\n') });
+  }
+  return sites;
+};
+
+/** A reason has to be ABOUT the skip. Any comment at all would pass otherwise. */
+export const isAnswered = (site: SkipSite): boolean => /skip/i.test(site.reason);
+
+/** Every `src` file that contains at least one skip site, repo-relative and sorted. */
+const scanSrc = (): Map<string, SkipSite[]> => {
+  const found = new Map<string, SkipSite[]>();
+  for (const entry of readdirSync(SRC, { recursive: true })) {
+    const name = String(entry);
+    if (!/\.tsx?$/.test(name)) continue;
+    const rel = `src/${name.split(path.sep).join('/')}`;
+    if (rel === SELF) continue; // the checker names the patterns it bans, so it cannot scan itself
+    const sites = findSkipSites(readFileSync(path.join(SRC, name), 'utf8'));
+    if (sites.length > 0) found.set(rel, sites);
+  }
+  return new Map([...found].sort(([a], [b]) => a.localeCompare(b)));
+};
+
+/**
+ * The suites `docs/skipped-tests.md` claims to cover.
+ *
+ * Only backticked paths in a TABLE ROW count, so the prose above and below the table stays free
+ * to mention any file it likes — including this one.
+ */
+const documentedSuites = async (): Promise<Set<string>> => {
+  const doc = await Bun.file(path.join(REPO, DOC)).text();
+  const rows = doc.split('\n').filter((l) => l.trimStart().startsWith('|'));
+  const named = new Set<string>();
+  for (const row of rows) for (const m of row.matchAll(/`(src\/[^`]+\.tsx?)`/g)) named.add(m[1] as string);
+  return named;
+};
+
+describe('every skip in src answers for itself', () => {
+  test('each skip site carries its reason in the comment directly above it', () => {
+    const unanswered: string[] = [];
+    for (const [file, sites] of scanSrc())
+      for (const site of sites) if (!isAnswered(site)) unanswered.push(`${file}:${site.line}  ${site.text}`);
+
+    expect(
+      unanswered,
+      `A skipped test with no stated reason is a question nobody can answer later — answering the 82 already here\n` +
+        `cost a task of its own on 2026-09-13 (16m 5s, per the runner's ledger). Put one line directly above the\n` +
+        `skip saying what it is WAITING FOR (a service, a fixture, a\n` +
+        `browser, a decision), mentioning the word "skip", and add a row to ${DOC}. If it passes today, unskip it\n` +
+        `instead. Never delete a test to make the number fall.\n\nUnanswered:\n  ${unanswered.join('\n  ')}`,
+    ).toEqual([]);
+  });
+});
+
+describe(`${DOC} matches the suite`, () => {
+  test('it names every file that carries a skip', async () => {
+    const documented = await documentedSuites();
+    const missing = [...scanSrc().keys()].filter((f) => !documented.has(f));
+    expect(
+      missing,
+      `These files gained a skip that ${DOC} does not mention. Add a table row: what it waits for, how to run it,\n` +
+        `and when it was last seen green.\n\n  ${missing.join('\n  ')}`,
+    ).toEqual([]);
+  });
+
+  test('it names no file that has stopped carrying one', async () => {
+    const live = scanSrc();
+    const stale = [...(await documentedSuites())].filter((f) => !live.has(f));
+    expect(
+      stale,
+      `${DOC} still lists these as skipped, but they no longer contain a skip site. Good news — delete the rows\n` +
+        `(and move the count) so the record stops claiming something that is no longer true.\n\n  ${stale.join('\n  ')}`,
+    ).toEqual([]);
+  });
+});
+
+/**
+ * The detector's own failure path. A gate nobody has seen RED is a gate nobody knows works, and
+ * this one's whole value is that it fires on the day a skip is introduced.
+ */
+describe('the detector itself', () => {
+  test('an uncommented skip is a finding', () => {
+    const sites = findSkipSites(["describe.skipIf(!URL_)('x', () => {", '});'].join('\n'));
+    expect(sites).toHaveLength(1);
+    expect(isAnswered(sites[0] as SkipSite)).toBe(false);
+  });
+
+  test('a skip whose comment explains the skip is not', () => {
+    const sites = findSkipSites(
+      ['// SKIPPED unless CC_PG_URL names a real Postgres.', "describe.skipIf(!URL_)('x', () => {", '});'].join('\n'),
+    );
+    expect(isAnswered(sites[0] as SkipSite)).toBe(true);
+  });
+
+  test('a comment about something else does NOT answer for the skip', () => {
+    const sites = findSkipSites(
+      ['// posterOnly is the memory-constrained-host path.', "describe.skipIf(!ffmpeg)('x', () => {", '});'].join('\n'),
+    );
+    expect(isAnswered(sites[0] as SkipSite)).toBe(false);
+  });
+
+  test('a blank line between the comment and the skip breaks the block', () => {
+    const sites = findSkipSites(
+      ['// SKIPPED unless CC_PG_URL is set.', '', "describe.skipIf(!URL_)('x', () => {", '});'].join('\n'),
+    );
+    expect(sites[0]?.reason).toBe('');
+    expect(isAnswered(sites[0] as SkipSite)).toBe(false);
+  });
+
+  test('a JSDoc block above the skip counts as the reason', () => {
+    const sites = findSkipSites(
+      ['/**', ' * SKIPPED until the browser harness exists.', ' */', "it.skip('x', () => {});"].join('\n'),
+    );
+    expect(isAnswered(sites[0] as SkipSite)).toBe(true);
+  });
+
+  test('it finds the other spellings too', () => {
+    expect(findSkipSites("it.todo('later');")).toHaveLength(1);
+    expect(findSkipSites("test.failing('known bad');")).toHaveLength(1);
+    expect(findSkipSites("xit('old style', () => {});")).toHaveLength(1);
+    expect(findSkipSites("xdescribe('old style', () => {});")).toHaveLength(1);
+  });
+
+  test('an identifier that merely contains "skip" is not a skip site', () => {
+    expect(findSkipSites('const skip = new Set(opts.skipDirs ?? []);')).toEqual([]);
+    expect(findSkipSites('if (options.skipKdfReadinessGate !== true) assertArgon2idReady();')).toEqual([]);
+    expect(findSkipSites('const q = useQuery({ queryKey: k, initialPageParam: skipToken });')).toEqual([]);
+  });
+
+  test('this package has skip sites to find — a detector that finds nothing proves nothing', () => {
+    expect(scanSrc().size).toBeGreaterThan(0);
+  });
+});