@bongos/core 1.19.376 → 1.19.377

package/.bongos-core.json

@@ -2,22 +2,22 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.19.376",
-  "core_contract": "1.19.376",
-  "source_commit": "a431d7ef6e3018eeb8b16fbf2616b7b99ec4d5d5",
+  "core_version": "1.19.377",
+  "core_contract": "1.19.377",
+  "source_commit": "90c7b43a6f0265aaf5d5c117cbe2721c18bd6c35",
   "source_ref": "HEAD",
-  "built_at": "2026-08-25T23:21:03.279Z",
+  "built_at": "2026-08-26T23:56:55.300Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
     "docs_redacted": 335,
     "agent_docs_stubbed": 22,
-    "functional_verbatim": 1557,
+    "functional_verbatim": 1565,
     "rules": 3,
     "gate_literals": 3,
     "gate": "passed"
   },
-  "file_count": 1914,
-  "tree_sha256": "6c7b5981caac40dce57dfecbee01587f18c3b4e5b4cb8fa65ebde70c9869ef53",
+  "file_count": 1922,
+  "tree_sha256": "ef3ea529acb199c38d7dc4bb8bc657b694727f8e8ffaa8fdf2af230913416726",
   "files": [
     {
       "path": ".claude/skills/blocker-review/SKILL.md",
@@ -4154,6 +4154,16 @@
       "mode": "0000644",
       "sha256": "0027e5e8a3b718a16dcae5ad4387b4773525d429944e712228fbd38a5335e23a"
     },
+    {
+      "path": "modules/lifecycle/kickoff-checklist.js",
+      "mode": "0000644",
+      "sha256": "829dd13fb87033dba1db8d3003a0359e1be8bb97198df419edb2617558bfd984"
+    },
+    {
+      "path": "modules/lifecycle/kickoff-seed.js",
+      "mode": "0000644",
+      "sha256": "f26a507ea55169df9f4841edb2347610f3dea9b7eac729c034c038a0edd1c7af"
+    },
     {
       "path": "modules/lifecycle/lifecycle.js",
       "mode": "0000644",
@@ -4187,7 +4197,7 @@
     {
       "path": "modules/lifecycle/module.json",
       "mode": "0000644",
-      "sha256": "30653b4064be8933894679ac4e272711edcc629e151d87017e2b2e45be96d78f"
+      "sha256": "401e4121a3f335ae0ae532b6b7ccff63e668b3a53520a0ff3f0d1a4223b02020"
     },
     {
       "path": "modules/lifecycle/pollers/publish-reconciler.js",
@@ -4244,6 +4254,11 @@
       "mode": "0000644",
       "sha256": "0e9430101ce99d0a84f1893d13bcf1434af13325c2ce531e693b6bce42cb9385"
     },
+    {
+      "path": "modules/lifecycle/routes/kickoff-seed.js",
+      "mode": "0000644",
+      "sha256": "f5090caaf0d0f32feff5bf4263e65ecf831ad6fd10ae5b053788c987e1a86399"
+    },
     {
       "path": "modules/lifecycle/routes/lifecycle.js",
       "mode": "0000644",
@@ -4927,12 +4942,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "0cdd9747593cc2fb83327041cf2d869234271cf7e3dcc7ecfb626c43ed262155"
+      "sha256": "e5e8b0e3c6879a8636f96f6bdce1c4fd8d9b06521e431bd6051bb2be2ea96518"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "00ff5e9289bc25cc0e6d1a7226259b52b906eaf887c9dd417067d41193877d7c"
+      "sha256": "3057a201c65b95c06512dfbf5642b4d3de10c513382e771b478f0eb43dad3ff8"
     },
     {
       "path": "public-docs/index.html",
@@ -5627,7 +5642,7 @@
     {
       "path": "scripts/gds/fitness.js",
       "mode": "0000644",
-      "sha256": "95f116e70ba6d6e890705ff862a5c5011002c42a58ba60553c50ec2d656dcf3b"
+      "sha256": "4dec7f6bee219ca3c11dbf5b9c3380de286264a66830fd8e2d37018a989eb83e"
     },
     {
       "path": "scripts/gds/gate-review.js",
@@ -5747,7 +5762,7 @@
     {
       "path": "scripts/gds/init.js",
       "mode": "0000644",
-      "sha256": "bde86f3f65cdd4a1ad0e143c58f6517328dd7cdee7c1194c0fa614aaf9df56f6"
+      "sha256": "280197b62032374c11824c4f97ec713725e28e2b57cfd6c8aa42d493b02c4ed7"
     },
     {
       "path": "scripts/gds/install-git-hooks.js",
@@ -6399,6 +6414,11 @@
       "mode": "0000644",
       "sha256": "88b9b721b3911957b13aa5e8023e6d41534e34afd4bbc70f40435efc52e2017b"
     },
+    {
+      "path": "scripts/gds/test-path-guard.js",
+      "mode": "0000644",
+      "sha256": "d3e542cf977f9aadad8f856defa6d809f3604e184cd261fbee7738aa1da736ea"
+    },
     {
       "path": "scripts/gds/triage.js",
       "mode": "0000644",
@@ -6542,7 +6562,7 @@
     {
       "path": "src/bongos/auth-admission.js",
       "mode": "0000644",
-      "sha256": "0d2e4aaf4b99ac4b1122c182f279ae622f53d8896baa31d796c5bb0f4ef6532c"
+      "sha256": "9978b10e2e675b6f7c1211dd74c8cf302395b2f47062eba5df376203ee77d341"
     },
     {
       "path": "src/bongos/auth-config.js",
@@ -6817,7 +6837,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "94c29ffd7acffe072f72060e6bf7deb322031a3521e935f77f4069cf7da1a699"
+      "sha256": "5287468c8e1a2ba691e02ff2150bcb425b00db6c0ce676b063d32cb20ef640c5"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -7694,6 +7714,11 @@
       "mode": "0000644",
       "sha256": "5466ddf0b7e0298206d46da7b84cfd3826e0f549395088bf5ed91397d15f1746"
     },
+    {
+      "path": "tests/first_admin_kickoff_seed.mjs",
+      "mode": "0000644",
+      "sha256": "8006f4696e6bae21b84c9e8ec25cb7a7d34c5899f187d2ac59b2a6dcbb6f92d1"
+    },
     {
       "path": "tests/first_run_engine_check.mjs",
       "mode": "0000644",
@@ -8374,6 +8399,16 @@
       "mode": "0000644",
       "sha256": "db9ad86df4c9593db89f91ef2306c30eb33ae56bebe5b210a4b3a1912f67d42c"
     },
+    {
+      "path": "tests/kickoff_checklist.mjs",
+      "mode": "0000644",
+      "sha256": "d0849053675cb4705fe6774b1a8ac6b3edb5b43a758775446fad257be6cb9ba3"
+    },
+    {
+      "path": "tests/kickoff_seed.mjs",
+      "mode": "0000644",
+      "sha256": "416d413757a13fbddb5841ea8a2c503077d7e6067bc1c58ce1f4d416b8d8487f"
+    },
     {
       "path": "tests/known_failing_ratchet.mjs",
       "mode": "0000644",
@@ -8832,7 +8867,7 @@
     {
       "path": "tests/provisioning_onboard_mode.mjs",
       "mode": "0000644",
-      "sha256": "7749df454ac3cca7c7e5ea1acc94ead15d1c9f87b38fe2028a1c93c8adf31bcf"
+      "sha256": "97d04ee39cc06b720d4a5b42f3e3cc614f64d9462b27471a1af7598b5e2929be"
     },
     {
       "path": "tests/provisioning_settings.mjs",
@@ -9057,7 +9092,7 @@
     {
       "path": "tests/search_ingest.mjs",
       "mode": "0000644",
-      "sha256": "504a855803d88468667663f663656dfd8e25726b90a412e34bcf55da0ad57d5e"
+      "sha256": "8d685a46ab9f4cf9aaa71b9ee78774d95c16daa27c15a229b8628a97688b9a55"
     },
     {
       "path": "tests/search_ingest_db.mjs",
@@ -9192,7 +9227,7 @@
     {
       "path": "tests/setup_smoke.mjs",
       "mode": "0000644",
-      "sha256": "919541c9444b7dc60f33a1e56b2f7defaf07ea1da5fb4b0c9760ca1bb9e7f1e0"
+      "sha256": "c55f6c506758d973b7cbe750a873e8c38d02006e1495f027fedb0ebfc84c7186"
     },
     {
       "path": "tests/ship_api_client_pathspec.mjs",
@@ -9459,6 +9494,11 @@
       "mode": "0000644",
       "sha256": "3ff18b286a68b244a272b3f2606ae33b298622347aae97305152f235ca57b330"
     },
+    {
+      "path": "tests/test_path_guard.mjs",
+      "mode": "0000644",
+      "sha256": "bbb0b063bffc6e394114bc4895da5006d8797a0317ed38f1c7f9b989841d5eab"
+    },
     {
       "path": "tests/tool-scan-fixtures/README.md",
       "mode": "0000644",

package/modules/lifecycle/kickoff-checklist.js

@@ -0,0 +1,138 @@
+// modules/lifecycle/kickoff-checklist.js — the kickoff checklist: the launch steps a fresh
+// instance needs that the platform CANNOT do for its owner, as task specs (task 1003239).
+//
+// ONE list, two filers. `bongos init` files it at scaffold time on the self-host path
+// (scripts/gds/init.js kickoffTasks); the lifecycle module files it at the founder's
+// FIRST SIGN-IN on the control-plane path (modules/lifecycle/kickoff-seed.js), where
+// the scaffold ran `init --no-seed` and no Archon existed to file anything — walk
+// finding W4: the founder reached an empty board. Moved here from init.js so both
+// filers read the same steps and the copy cannot drift. It lives with the lifecycle
+// module because tasks are its domain and the kernel doorway must not grow a domain
+// import (ADR 0091 §1); init is a core CLI and, like abandon.js or audit-deps.js,
+// may require module code directly. Pure — imports nothing.
+//
+// Each step becomes a real, claimable task so it is tracked, never silently skipped
+// (grounded in the onboarding/deploy surfaces; the task 1204 mapping pass). Per-module
+// prerequisites are appended only for the modules the owner enabled.
+
+'use strict';
+
+// The one kickoff step the provisioning module AUTOMATES (ADR 0111 §3): standing up
+// production hosting/TLS/DNS/managed-DB. Kept as a named builder so init can either
+// FILE it (no provisioning requested, or the request couldn't be enqueued) or OMIT
+// it (a request went in — the control-plane runner covers this leg).
+function productionTopologyKickoff() {
+  return {
+    title: 'Production topology: TLS, real origins, managed Postgres',
+    kind: 'infra',
+    description: 'For a real (non-localhost) launch: front the instance with TLS (Caddy/Cloudflare/nginx), point ' +
+      'publicOrigin/buildersOrigin/statusOrigin at the real domain (the OAuth callback depends on this), and move off the bundled container DB volume to managed/backed-up Postgres.',
+  };
+}
+
+// The admission step as the SELF-HOST owner meets it: an env flag on their own box.
+const ADMISSION_SELF_HOST = {
+  title: 'Set the admission posture and invite the first builders',
+  kind: 'infra',
+  description: 'Enrollment is invite-only by default. Beyond you, no one can join until you approve an access request ' +
+    'or set <ENVPREFIX>_OPEN_XENOS_ENROLLMENT=1. Decide who can join and invite/approve the first builders.',
+};
+
+// The same decision as a HUB-PROVISIONED founder meets it: the door is the project's
+// "How people join" setting on the hub (task 1003044), never an env var they cannot
+// reach; invites are the Watch page's "Invite by GitHub username". Names only surfaces
+// that exist — a blank board is better than untrue copy (task 1003239).
+const ADMISSION_AT_FIRST_SIGN_IN = {
+  title: 'Decide how people join, and invite the first builders',
+  kind: 'infra',
+  description: 'Unless you opened the door when you created the project, nobody beyond you can join until you invite them. ' +
+    'Set "How people join" (open / apply to join / invite-only) from your project\'s manage page on the hub, ' +
+    'and invite the first builders by GitHub username from your project\'s Watch page.',
+};
+
+const MERGE_GATE = {
+  title: 'Arm the merge gate before a second builder joins (ci deploy mode)',
+  kind: 'infra',
+  description: 'For a shared instance on ci deploy mode, enable branch protection on main + required checks ' +
+    '(unit / secret-scan / gate-review), so untrusted builders cannot push straight to production. No review requirement — gates are CI checks, not human approvals (ADR 0162). Skippable for a solo/local instance.',
+};
+
+const INSTANCE_LOOK = {
+  title: 'Fill the instance look with your own LLM',
+  // 'ideator' is a DISCIPLINE, not a kind — tasks_kind_check rejects it as a
+  // kind and the task silently vanished from the checklist (the one non-infra
+  // kickoff step). Deciding the instance look is a decision by an ideator.
+  kind: 'decision',
+  discipline: 'ideator',
+  description: 'init wrote a lean config/branding.json and left the LOOK to you (a locked project rule: brand with your ' +
+    'own LLM, not a generator). Hand docs/branding-fill-prompt.md to your AI to design a palette/fonts/wordmark, or keep the vanilla look.',
+};
+
+// Steps that are already TRUE the moment a hub-provisioned founder signs in: auth
+// works (they just used it), the sign-in is this one, and the scaffold bound the repo
+// and chose the deploy mode. Filed on the self-host path only.
+function selfHostOnlySteps(spec, origin) {
+  return [
+    {
+      title: 'Register a GitHub OAuth app and set its credentials',
+      kind: 'infra',
+      description: 'Auth is the hard prerequisite for every sign-in — without it the server returns 503 ' +
+        'auth_not_configured and nobody (including you) can log in. Create a GitHub OAuth app, set ' +
+        `<ENVPREFIX>_GITHUB_CLIENT_ID/SECRET, tick "Enable Device Flow" (a separate save), and set the callback URL to ${origin}/api/gds/auth/web/callback.`,
+    },
+    {
+      title: `Sign in once as ${spec.firstAdmin} to seat the founding owner`,
+      kind: 'infra',
+      description: `A fresh database has no owner. Signing in as the configured firstAdmin (${spec.firstAdmin}) ` +
+        'the first time auto-seats that account as the founding Archon (owner). Config alone does nothing — you must actually sign in.',
+    },
+    {
+      title: 'Confirm the GitHub repo binding and deploy mode',
+      kind: 'infra',
+      description: `This instance ships work to ${spec.repo.owner}/${spec.repo.name}. Confirm the git remote / repo binding ` +
+        'and pick deploy mode in config/deploy.json (ci = server-mediated PR auto-merge, or laptop). A wrong/absent repo binding lets a task grade but never merge.',
+    },
+  ];
+}
+
+// Per-module prerequisites — a key the module cannot run without.
+function moduleKeySteps(spec) {
+  const enabled = new Set(Array.isArray(spec.modules) ? spec.modules : []);
+  const tasks = [];
+  if (enabled.has('art-pipeline')) {
+    tasks.push({ title: 'Provide a Google Gemini API key for the art pipeline', kind: 'infra',
+      description: 'The art-pipeline module needs a Google AI Studio (Gemini) key (GOOGLE_AI_STUDIO_KEY, a shared key, or per-builder keys) or it cannot generate art.' });
+  }
+  if (enabled.has('discord')) {
+    tasks.push({ title: 'Provide Discord bot token + webhooks', kind: 'infra',
+      description: 'The discord module needs a bot token + webhook URLs + DISCORD_BOT_ENABLED=true. Note: outbound/link surfaces fire on credentials even if the module flag is later turned off.' });
+  }
+  if (enabled.has('dev-box')) {
+    tasks.push({ title: 'Provide a DigitalOcean API token for dev boxes', kind: 'infra',
+      description: 'The dev-box module needs a DigitalOcean API token (and optionally Cloudflare) on the operator control plane before any builder box can be provisioned.' });
+  }
+  return tasks;
+}
+
+// kickoffChecklist(spec, opts) → task specs ({ title, kind, description[, discipline] }).
+//   provisioned — the owner opted into provisioning at init: the control-plane runner
+//                 covers production topology, so that step is omitted (ADR 0111 §3).
+//   firstSignIn — filed the moment the founder of a hub-provisioned project is seated:
+//                 only the steps still true after the standup, with the admission door
+//                 described as the hub setting it now is.
+// Pure — no I/O; the caller files them.
+function kickoffChecklist(spec = {}, { provisioned = false, firstSignIn = false } = {}) {
+  const origin = (spec.domains && spec.domains.publicOrigin) || 'http://localhost:3000';
+  const tasks = firstSignIn ? [] : selfHostOnlySteps(spec, origin);
+  tasks.push(firstSignIn ? ADMISSION_AT_FIRST_SIGN_IN : ADMISSION_SELF_HOST);
+  tasks.push(MERGE_GATE);
+  // Production topology is either AUTOMATED (the owner opted into provisioning — the
+  // control-plane runner stands up TLS/DNS/managed-DB) or a tracked manual step.
+  // Keep it in its infra slot, before the look step, when it's still manual.
+  if (!provisioned && !firstSignIn) tasks.push(productionTopologyKickoff());
+  tasks.push(INSTANCE_LOOK);
+  tasks.push(...moduleKeySteps(spec));
+  return tasks.map((t) => ({ ...t }));
+}
+
+module.exports = { kickoffChecklist, productionTopologyKickoff };

package/modules/lifecycle/kickoff-seed.js

@@ -0,0 +1,69 @@
+// modules/lifecycle/kickoff-seed.js — file the kickoff checklist at the founder's first
+// sign-in (task 1003239; behind the `lifecycle.kickoffSeed` port).
+//
+// WHY HERE, WHY THEN. `bongos init` files the kickoff checklist as tasks — but the
+// control-plane scaffold runs `init --no-seed` (scripts/gds/provision-repo.js), and a
+// hub-provisioned project has no Archon until its founder signs in, so nothing could
+// be filed earlier: the founder reached an EMPTY board (walk finding W4). The kernel's
+// first-admin seating (src/bongos/auth-admission.js) resolves this port the moment the
+// owner is seated — the first moment the checklist CAN be filed.
+//
+// IDEMPOTENT BY EMPTINESS, not by path. It seeds only when the tasks table is empty:
+// the self-host path already filed its checklist before anyone signed in, so it is
+// skipped there with no "was I provisioned" marker to keep true. The caller treats a
+// failure as best-effort — a seed hiccup must never fail the sign-in that just seated
+// the owner.
+//
+// THE BOUNDARY (ADR 0093 §1): core is reached only through ../../src/module-api.js.
+
+'use strict';
+
+const api = require('../../src/module-api');
+const db = require('./db');
+const { kickoffChecklist } = require('./kickoff-checklist');
+
+// The spec the checklist reads, from the instance's own branding pack. `modules` is
+// empty on purpose: a hub-provisioned project is scaffolded with every optional module
+// off, and its founder cannot have enabled one before their first sign-in.
+function specFromBranding(b = api.branding()) {
+  return {
+    firstAdmin: b.firstAdmin,
+    repo: b.repo || {},
+    domains: { publicOrigin: b.domains && b.domains.publicOrigin },
+    modules: [],
+  };
+}
+
+// The version the checklist lands under: the building one, else the first by id. The
+// scaffold seeds exactly one (provision-repo.js seedFirstVersionCmd).
+const FIRST_VERSION_SQL = `SELECT id FROM versions ORDER BY (status = 'building') DESC, id ASC LIMIT 1`;
+
+// seedKickoffIfEmpty({ builderId }, deps) → { seeded, versionId } | { seeded: 0, skipped }.
+// deps.pool / deps.createTask / deps.spec are test seams; production reads the doorway.
+async function seedKickoffIfEmpty({ builderId = null } = {}, deps = {}) {
+  const pool = deps.pool || api.pool;
+  const insert = deps.createTask || ((row) => db.createTask(row));
+  const { rows: [{ n }] } = await pool.query('SELECT count(*)::int AS n FROM tasks');
+  if (n > 0) return { seeded: 0, skipped: 'tasks_exist' };
+  const { rows: versions } = await pool.query(FIRST_VERSION_SQL);
+  if (!versions.length) return { seeded: 0, skipped: 'no_version' };
+  const versionId = versions[0].id;
+  const steps = kickoffChecklist(deps.spec || specFromBranding(), { firstSignIn: true });
+  let seeded = 0;
+  for (const t of steps) {
+    await insert({
+      versionId,
+      title: t.title,
+      description: t.description || '',
+      status: 'ready',
+      kind: t.kind || 'infra',
+      discipline: t.discipline || 'engineer',
+      source: 'first-sign-in',
+      createdBy: builderId,
+    });
+    seeded += 1;
+  }
+  return { seeded, versionId };
+}
+
+module.exports = { seedKickoffIfEmpty, specFromBranding, FIRST_VERSION_SQL };

package/modules/lifecycle/module.json

@@ -21,14 +21,16 @@
       "help-requests",
       "recommendations",
       "closeness",
-      "visuals"
+      "visuals",
+      "kickoff-seed"
     ],
     "pollers": [
       "publish-reconciler"
     ]
   },
   "provides": [
-    "lifecycle"
+    "lifecycle",
+    "lifecycle.kickoffSeed"
   ],
   "consumes": []
 }

package/modules/lifecycle/routes/kickoff-seed.js

@@ -0,0 +1,29 @@
+'use strict';
+
+// modules/lifecycle/routes/kickoff-seed.js — registers the `lifecycle.kickoffSeed` port
+// (task 1003239): the founder's first board, filed the moment the kernel seats them.
+//
+// Resolved by ONE caller — the first-admin bootstrap in src/bongos/auth-admission.js —
+// through resolveOptional, so an instance without this module signs in exactly as
+// before. A route factory for a routeless capability, for the reason routes/lifecycle.js
+// and routes/rank-sync.js give: mountModuleRoutes is the boot hook that runs in the live
+// server AND whenever a test rebuilds the router. The router stays EMPTY — seeding has
+// no HTTP surface, and an endpoint here would let anyone re-file a founder's checklist.
+
+const express = require('express');
+const api = require('../../../src/module-api');
+const seed = require('../kickoff-seed');
+
+// Delegates at call time (never spreads) so a stubbed seed still bites.
+const kickoffSeedPort = {
+  seedIfEmpty: (...a) => seed.seedKickoffIfEmpty(...a),
+};
+
+module.exports = function buildLifecycleKickoffSeedRouter() {
+  if (!api.hasProvider('lifecycle.kickoffSeed')) {
+    api.registerProvider('lifecycle.kickoffSeed', kickoffSeedPort);
+  }
+  return express.Router();
+};
+
+module.exports.kickoffSeedPort = kickoffSeedPort;

package/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.376",
+  "version": "1.19.377",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@bongos/core",
-      "version": "1.19.376",
+      "version": "1.19.377",
       "license": "AGPL-3.0-or-later",
       "dependencies": {
         "express": "^4.21.2",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.376",
+  "version": "1.19.377",
   "description": "Cloud Bongos — the AI-first build platform core (GDS + platform surfaces + module system), installed as a versioned dependency (ADR 0108).",
   "license": "AGPL-3.0-or-later",
   "main": "src/platform-server.js",

package/scripts/gds/fitness.js

@@ -1308,6 +1308,7 @@ const CHECKS = [
   require('./routine-schedule.js').checkRoutineCadencesScheduled, // Check 25 — task 1003209: a routine that declares a cadence must have a scheduler firing it AT that period (ADR 0188)
   require('./baseline-staleness.js').checkBaselineFloors, // Check 26 — task 1003210: a shrink-only baseline that never shrinks is unmanaged debt; a floor exempting one must say why
   require('./client-baseurl-guard.js').checkClientBaseUrl,
+  require('./test-path-guard.js').checkTestsUseFileUrlToPath, // Check 30 — task 1002889: a test builds its repo root with fileURLToPath, never URL.pathname (a %20 or a Windows drive slash makes require() throw at load; CI's spaceless checkout can't see it)
   // Check 29 — task 1003275 / ADR 0189: a work category ORIENTS a human and steers
   // Claude; it authorises nothing. The owner said so twice, and the goal's own prose
   // predicts the failure: a second thing that looks like a hierarchy gets mistaken

package/scripts/gds/init.js

@@ -218,18 +218,11 @@ function provisioningRequest(spec) {
   return body;
 }
 
-// The one kickoff step the provisioning module AUTOMATES (ADR 0111 §3): standing up
-// production hosting/TLS/DNS/managed-DB. Kept as a named builder so init can either
-// FILE it (no provisioning requested, or the request couldn't be enqueued) or OMIT
-// it (a request went in — the control-plane runner covers this leg).
-function productionTopologyKickoff() {
-  return {
-    title: 'Production topology: TLS, real origins, managed Postgres',
-    kind: 'infra',
-    description: 'For a real (non-localhost) launch: front the instance with TLS (Caddy/Cloudflare/nginx), point ' +
-      'publicOrigin/buildersOrigin/statusOrigin at the real domain (the OAuth callback depends on this), and move off the bundled container DB volume to managed/backed-up Postgres.',
-  };
-}
+// The kickoff checklist itself (and the production-topology step the provisioning
+// module can automate) now live in modules/lifecycle/kickoff-checklist.js — ONE list shared
+// with the lifecycle module, which files the same steps at the founder's first
+// sign-in on the control-plane path (task 1003239). init keeps its names.
+const { kickoffChecklist, productionTopologyKickoff } = require('../../modules/lifecycle/kickoff-checklist');
 
 // The lean instance branding.json: ONLY the fields the owner supplied. Everything
 // else (theme, copy, rank labels, box subdomain pattern) resolves from
@@ -325,74 +318,11 @@ function mergeCoreDependency(pkg, { corePkg = CORE_PKG, coreRange, name = 'cloud
   return { pkg: next, action: 'added' };
 }
 
-// The kickoff checklist, as tasks. These are the steps init CANNOT do for you —
-// the human-only setup a fresh instance needs to actually launch (grounded in
-// the onboarding/deploy surfaces; see the task 1204 mapping pass). Each becomes
-// a real, claimable task so it's tracked, never silently skipped. Per-module
-// prerequisites are appended only for the modules the owner enabled.
+// The kickoff checklist, as tasks — the steps init CANNOT do for you (the shared
+// list, self-host shape). Production topology is omitted when the owner opted into
+// provisioning: the control-plane runner covers that leg (ADR 0111 §3).
 function kickoffTasks(spec) {
-  const origin = (spec.domains && spec.domains.publicOrigin) || 'http://localhost:3000';
-  const tasks = [
-    {
-      title: 'Register a GitHub OAuth app and set its credentials',
-      kind: 'infra',
-      description: 'Auth is the hard prerequisite for every sign-in — without it the server returns 503 ' +
-        'auth_not_configured and nobody (including you) can log in. Create a GitHub OAuth app, set ' +
-        `<ENVPREFIX>_GITHUB_CLIENT_ID/SECRET, tick "Enable Device Flow" (a separate save), and set the callback URL to ${origin}/api/gds/auth/web/callback.`,
-    },
-    {
-      title: `Sign in once as ${spec.firstAdmin} to seat the founding owner`,
-      kind: 'infra',
-      description: `A fresh database has no owner. Signing in as the configured firstAdmin (${spec.firstAdmin}) ` +
-        'the first time auto-seats that account as the founding Archon (owner). Config alone does nothing — you must actually sign in.',
-    },
-    {
-      title: 'Confirm the GitHub repo binding and deploy mode',
-      kind: 'infra',
-      description: `This instance ships work to ${spec.repo.owner}/${spec.repo.name}. Confirm the git remote / repo binding ` +
-        'and pick deploy mode in config/deploy.json (ci = server-mediated PR auto-merge, or laptop). A wrong/absent repo binding lets a task grade but never merge.',
-    },
-    {
-      title: 'Set the admission posture and invite the first builders',
-      kind: 'infra',
-      description: 'Enrollment is invite-only by default. Beyond you, no one can join until you approve an access request ' +
-        'or set <ENVPREFIX>_OPEN_XENOS_ENROLLMENT=1. Decide who can join and invite/approve the first builders.',
-    },
-    {
-      title: 'Arm the merge gate before a second builder joins (ci deploy mode)',
-      kind: 'infra',
-      description: 'For a shared instance on ci deploy mode, enable branch protection on main + required checks ' +
-        '(unit / secret-scan / gate-review), so untrusted builders cannot push straight to production. No review requirement — gates are CI checks, not human approvals (ADR 0162). Skippable for a solo/local instance.',
-    },
-  ];
-  // Production topology is either AUTOMATED (the owner opted into provisioning — the
-  // control-plane runner stands up TLS/DNS/managed-DB) or a tracked manual step.
-  // Keep it in its infra slot, before the look step, when it's still manual. (ADR 0111 §3)
-  if (!provisioningRequest(spec)) tasks.push(productionTopologyKickoff());
-  tasks.push({
-    title: 'Fill the instance look with your own LLM',
-    // 'ideator' is a DISCIPLINE, not a kind — tasks_kind_check rejects it as a
-    // kind and the task silently vanished from the checklist (the one non-infra
-    // kickoff step). Deciding the instance look is a decision by an ideator.
-    kind: 'decision',
-    discipline: 'ideator',
-    description: 'init wrote a lean config/branding.json and left the LOOK to you (a locked project rule: brand with your ' +
-      'own LLM, not a generator). Hand docs/branding-fill-prompt.md to your AI to design a palette/fonts/wordmark, or keep the vanilla look.',
-  });
-  const enabled = new Set(Array.isArray(spec.modules) ? spec.modules : []);
-  if (enabled.has('art-pipeline')) {
-    tasks.push({ title: 'Provide a Google Gemini API key for the art pipeline', kind: 'infra',
-      description: 'The art-pipeline module needs a Google AI Studio (Gemini) key (GOOGLE_AI_STUDIO_KEY, a shared key, or per-builder keys) or it cannot generate art.' });
-  }
-  if (enabled.has('discord')) {
-    tasks.push({ title: 'Provide Discord bot token + webhooks', kind: 'infra',
-      description: 'The discord module needs a bot token + webhook URLs + DISCORD_BOT_ENABLED=true. Note: outbound/link surfaces fire on credentials even if the module flag is later turned off.' });
-  }
-  if (enabled.has('dev-box')) {
-    tasks.push({ title: 'Provide a DigitalOcean API token for dev boxes', kind: 'infra',
-      description: 'The dev-box module needs a DigitalOcean API token (and optionally Cloudflare) on the operator control plane before any builder box can be provisioned.' });
-  }
-  return tasks;
+  return kickoffChecklist(spec, { provisioned: !!provisioningRequest(spec) });
 }
 
 // Normalize a raw spec (from --from or the interview) to canonical shape +

package/scripts/gds/test-path-guard.js

@@ -0,0 +1,99 @@
+#!/usr/bin/env node
+// scripts/gds/test-path-guard.js — a test must not build a filesystem path from
+// `URL.pathname` (task 1002889).
+//
+// THE BUG THIS EXISTS TO STOP. `new URL('..', import.meta.url).pathname` is a URL
+// path, not a filesystem path: percent-encoding survives (a space stays `%20`) and
+// on Windows it carries a leading slash before the drive letter. Handed to
+// require() or fs it resolves nowhere — four tests threw MODULE_NOT_FOUND at load
+// on the owner's checkout, whose path has a space in it.
+//
+// WHY A FITNESS CHECK AND NOT A TEST. CI checks out to a path with no space, so the
+// broken form passes there and the suite reads green while being unrunnable on a
+// Windows dev machine. CI can never catch the regression on its own; a static scan
+// at a different altitude can.
+//
+// THE FIX IT POINTS AT. `fileURLToPath(new URL('..', import.meta.url))` from
+// node:url (tests/fitness.mjs), or a plain relative require through
+// createRequire(import.meta.url) (tests/provisioning_teardown_intent.mjs).
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { execFileSync } = require('node:child_process');
+
+const REPO_ROOT = path.resolve(__dirname, '..', '..');
+const NAME = 'a test builds its repo root with fileURLToPath, never URL.pathname (task 1002889)';
+
+// `import.meta.url).pathname` — the URL-path-as-filesystem-path defect, in both its
+// forms: new URL('..', import.meta.url).pathname and new URL(import.meta.url).pathname.
+const PATHNAME_ROOT = /import\.meta\.url\s*\)\s*\.pathname\b/;
+
+// Every tracked test file. Only tests use import.meta.url this way; source is CJS.
+function trackedTestFiles() {
+  try {
+    const out = execFileSync('git', ['ls-files', 'tests/*.mjs', 'tests/*.js', 'tests/**/*.mjs', 'tests/**/*.js'],
+      { cwd: REPO_ROOT, encoding: 'utf8' });
+    return [...new Set(out.split('\n').map((s) => s.trim()).filter(Boolean))];
+  } catch {
+    return [];
+  }
+}
+
+function scanTests(files, read) {
+  const violations = [];
+  let scanned = 0;
+  for (const rel of files) {
+    const src = read(rel);
+    if (src == null) continue;
+    scanned += 1;
+    const lines = src.split('\n');
+    for (let i = 0; i < lines.length; i += 1) {
+      if (!PATHNAME_ROOT.test(lines[i])) continue;
+      violations.push(
+        `${rel}:${i + 1} builds a filesystem path from URL.pathname — a space becomes %20 and a Windows `
+        + 'drive gains a leading slash, so require()/fs throw MODULE_NOT_FOUND at load. Use '
+        + "fileURLToPath(new URL('..', import.meta.url)) from node:url, or a relative require via "
+        + 'createRequire(import.meta.url).',
+      );
+    }
+  }
+  return { violations, scanned };
+}
+
+function checkTestsUseFileUrlToPath({ files, read } = {}) {
+  const list = files || trackedTestFiles();
+  if (!list.length) {
+    return {
+      name: NAME, ok: false, hardFail: true,
+      violations: ['scan defect — enumerated 0 tracked test files; a broken enumeration, not a clean result.'],
+      warnings: [], note: 'static scan of tests/ for a URL.pathname used as a filesystem path.',
+    };
+  }
+  const reader = read || ((rel) => {
+    try { return fs.readFileSync(path.join(REPO_ROOT, rel), 'utf8'); } catch { return null; }
+  });
+  const { violations, scanned } = scanTests(list, reader);
+  return {
+    name: NAME,
+    ok: violations.length === 0,
+    hardFail: violations.length > 0,
+    violations,
+    warnings: [],
+    note: `${scanned} test file(s) scanned: none may hand \`import.meta.url).pathname\` to require()/fs — `
+      + 'it keeps %20 and a Windows drive slash, so the file is unrunnable on a checkout with a space '
+      + 'in its path while CI (no space) stays green. fileURLToPath() or a relative require is the form.',
+  };
+}
+
+function main() {
+  const r = checkTestsUseFileUrlToPath();
+  for (const v of r.violations) console.error(`✗ ${v}`);
+  console.log(`${r.hardFail ? 'FAIL' : 'PASS'}  ${r.note}`);
+  process.exit(r.hardFail ? 1 : 0);
+}
+
+if (require.main === module) main();
+
+module.exports = { checkTestsUseFileUrlToPath, scanTests, trackedTestFiles, PATHNAME_ROOT };

package/src/bongos/auth-admission.js

@@ -261,6 +261,7 @@ async function maybeSeatFirstAdmin(builder) {
     const seated = await seatFirstAdminIfUnclaimed(builder.id, builder.github_login);
     if (seated) {
       log.info(`[auth] first-admin bootstrap: seated ${builder.github_login} as Archon (configured firstAdmin, no prior Archon).`);
+      await seedKickoffChecklist(builder.id);
       return { ...builder, rank: 'archon' };
     }
   } catch (err) {
@@ -269,6 +270,27 @@ async function maybeSeatFirstAdmin(builder) {
   return builder;
 }
 
+// seedKickoffChecklist — the founder's first board (task 1003239). A hub-provisioned
+// project reaches its first sign-in with an EMPTY tasks table (the scaffold ran init
+// --no-seed; no Archon existed to file anything), so the moment the founder is seated
+// is the first moment the kickoff checklist CAN be filed. Resolved through the
+// `lifecycle.kickoffSeed` port — this is a KERNEL_FILE and may not require a module
+// (ADR 0083 / ADR 0091 §1); the port itself skips a board that already has tasks.
+// BEST-EFFORT: a seed hiccup must never fail the sign-in that just seated the owner.
+// deps.port is a test seam; production resolves the seam registry.
+async function seedKickoffChecklist(builderId, deps = {}) {
+  const port = deps.port !== undefined ? deps.port : seams.resolveOptional('lifecycle.kickoffSeed');
+  if (!port) return null;
+  try {
+    const r = await port.seedIfEmpty({ builderId });
+    if (r && r.seeded) log.info(`[auth] first-admin bootstrap: filed ${r.seeded} kickoff task(s) under ${r.versionId} — the founder's first board.`);
+    return r;
+  } catch (err) {
+    log.error(`[auth] first-admin bootstrap: kickoff seed failed (non-fatal): ${err.message}`);
+    return null;
+  }
+}
+
 // safeSyncRankRole — give a builder the seeded rank-role matching their rank at
 // REGISTRATION (BV1.R95b, ADR 0151). governance_002's builder→role backfill is
 // run-once, so before this every builder admitted after that migration had no role
@@ -303,6 +325,7 @@ module.exports = {
   firstTimeAdmissionBlocked,
   joinabilityMode,
   maybeSeatFirstAdmin,
+  seedKickoffChecklist,
   membershipKind,
   openEnrollmentEnabled,
   reportActivityRollup,

package/src/module-api.js

@@ -1192,8 +1192,10 @@ const { validateOrRespond, LIMITS, parseId, asyncHandler, corsPublicGet, parsePa
 //         landed since 1.19.374 with no explicit bump. run 32909701598. (task 1002620)
 //   1.19.376 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
 //         landed since 1.19.375 with no explicit bump. run 32910331206. (task 1002620)
+//   1.19.377 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+//         landed since 1.19.376 with no explicit bump. run 33025011131. (task 1002620)
 // ---------------------------------------------------------------------------
-const CORE_VERSION = '1.19.376'; // CI auto-patch carrier (ADR 0161); see changelog above
+const CORE_VERSION = '1.19.377'; // CI auto-patch carrier (ADR 0161); see changelog above
 
 // A namespaced logger so a module's log lines are attributable + consistent.
 // Usage: const log = api.logger('dev-box'); log.info('mounted');

package/tests/first_admin_kickoff_seed.mjs

@@ -0,0 +1,56 @@
+// tests/first_admin_kickoff_seed.mjs — the kernel side of task 1003239: the first-admin
+// bootstrap files the founder's first board through the `lifecycle.kickoffSeed` port,
+// and NOTHING about that can fail the sign-in that just seated the owner.
+//
+// DB-free: the helper is exercised with an injected port (deps.port), the same seam the
+// production call resolves from the registry. Covers the three shapes the port can take
+// at runtime — absent (an instance without the lifecycle module), throwing, seeding.
+//
+// Run:  node --test tests/first_admin_kickoff_seed.mjs
+
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const { seedKickoffChecklist } = require('../src/bongos/auth-admission.js');
+const seams = require('../src/module-seams.js');
+
+test('no port registered → a quiet null, never a throw (an instance without lifecycle signs in as before)', async () => {
+  assert.equal(seams.hasProvider('lifecycle.kickoffSeed'), false, 'nothing in-process registered the port');
+  assert.equal(await seedKickoffChecklist(1), null);
+});
+
+test('an absent port passed explicitly is the same quiet null', async () => {
+  assert.equal(await seedKickoffChecklist(1, { port: null }), null);
+});
+
+test('a throwing port is swallowed — best-effort, the seat stands', async () => {
+  const port = { seedIfEmpty: async () => { throw new Error('db went away'); } };
+  assert.equal(await seedKickoffChecklist(1, { port }), null);
+});
+
+test('a seeding port is handed the seated builder id and its result flows back', async () => {
+  const calls = [];
+  const port = { seedIfEmpty: async (arg) => { calls.push(arg); return { seeded: 3, versionId: 'V1' }; } };
+  const r = await seedKickoffChecklist(42, { port });
+  assert.deepEqual(calls, [{ builderId: 42 }]);
+  assert.deepEqual(r, { seeded: 3, versionId: 'V1' });
+});
+
+test('a skipping port (board already populated) flows back untouched', async () => {
+  const port = { seedIfEmpty: async () => ({ seeded: 0, skipped: 'tasks_exist' }) };
+  assert.deepEqual(await seedKickoffChecklist(42, { port }), { seeded: 0, skipped: 'tasks_exist' });
+});
+
+test('production resolves the port from the seam registry', async () => {
+  const calls = [];
+  seams.registerProvider('lifecycle.kickoffSeed', { seedIfEmpty: async (arg) => { calls.push(arg); return { seeded: 1, versionId: 'V1' }; } });
+  try {
+    const r = await seedKickoffChecklist(9);
+    assert.deepEqual(calls, [{ builderId: 9 }]);
+    assert.equal(r.seeded, 1);
+  } finally {
+    seams._reset();
+  }
+});

package/tests/kickoff_checklist.mjs

@@ -0,0 +1,107 @@
+// tests/kickoff_checklist.mjs — the shared kickoff checklist (task 1003239).
+//
+// One list, two filers: `bongos init` at scaffold time (self-host) and the lifecycle
+// module at the founder's first sign-in (hub-provisioned, where init ran --no-seed).
+// The first-sign-in shape must contain only what is still TRUE after a hub standup,
+// and must never name a surface that does not exist — the task's own rule: a blank
+// board beats untrue copy.
+//
+// Run:  node --test tests/kickoff_checklist.mjs
+
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const { kickoffChecklist, productionTopologyKickoff } = require('../modules/lifecycle/kickoff-checklist.js');
+const { VALID_KINDS, VALID_DISCIPLINES } = require('../modules/lifecycle/task-classifier.js');
+
+const spec = () => ({
+  firstAdmin: 'founder', repo: { owner: 'o', name: 'n' },
+  domains: { publicOrigin: 'https://p.example' }, modules: [],
+});
+
+test('default (self-host): the seven owner-manual steps, topology included', () => {
+  const t = kickoffChecklist(spec());
+  assert.equal(t.length, 7);
+  assert.ok(t.some((x) => /OAuth/i.test(x.title)), 'OAuth app step');
+  assert.ok(t.some((x) => /founding owner/i.test(x.title)), 'first sign-in step');
+  assert.ok(t.some((x) => /repo binding/i.test(x.title)), 'repo binding step');
+  assert.ok(t.some((x) => /Production topology/i.test(x.title)), 'topology step');
+  assert.ok(t.every((x) => x.title && x.description), 'every step has a title + description');
+});
+
+test('provisioned: only the topology step is omitted', () => {
+  const t = kickoffChecklist(spec(), { provisioned: true });
+  assert.equal(t.length, 6);
+  assert.ok(!t.some((x) => /Production topology/i.test(x.title)));
+  assert.ok(t.some((x) => /OAuth/i.test(x.title)), 'the self-host owner still registers their OAuth app');
+});
+
+test('firstSignIn: only what is still true after a hub standup', () => {
+  const t = kickoffChecklist(spec(), { firstSignIn: true });
+  assert.deepEqual(
+    t.map((x) => x.title),
+    [
+      'Decide how people join, and invite the first builders',
+      'Arm the merge gate before a second builder joins (ci deploy mode)',
+      'Fill the instance look with your own LLM',
+    ],
+  );
+  for (const x of t) {
+    assert.ok(!/OAuth|founding owner|repo binding|topology/i.test(x.title + x.description),
+      `"${x.title}" names a step the standup already did`);
+  }
+});
+
+test('firstSignIn: the admission step points at surfaces that exist, never an env var', () => {
+  const join = kickoffChecklist(spec(), { firstSignIn: true })[0];
+  assert.ok(!/ENVPREFIX|OPEN_XENOS_ENROLLMENT|config\//.test(join.description), 'no env var or config file a hub founder cannot reach');
+  assert.match(join.description, /How people join/, 'the hub setting (task 1003044)');
+  assert.match(join.description, /manage page/, 'where the setting lives');
+  assert.match(join.description, /Watch page/, 'where invites live');
+  assert.match(join.description, /GitHub username/, 'how an invite is addressed');
+});
+
+test('firstSignIn: per-module keys still follow the enabled modules', () => {
+  const t = kickoffChecklist({ ...spec(), modules: ['art-pipeline', 'discord'] }, { firstSignIn: true });
+  assert.equal(t.length, 5);
+  assert.ok(t.some((x) => /Gemini/i.test(x.title)));
+  assert.ok(t.some((x) => /Discord/i.test(x.title)));
+});
+
+test('firstSignIn: never reads spec.repo or spec.firstAdmin (the steps that need them are omitted)', () => {
+  assert.doesNotThrow(() => kickoffChecklist({}, { firstSignIn: true }));
+  assert.equal(kickoffChecklist({}, { firstSignIn: true }).length, 3);
+});
+
+test('every variant satisfies the DB CHECK vocabulary (tasks_kind_check / tasks_discipline_check)', () => {
+  const full = { ...spec(), modules: ['art-pipeline', 'discord', 'dev-box'] };
+  const all = [
+    ...kickoffChecklist(full),
+    ...kickoffChecklist(full, { provisioned: true }),
+    ...kickoffChecklist(full, { firstSignIn: true }),
+    productionTopologyKickoff(),
+  ];
+  for (const t of all) {
+    assert.ok(VALID_KINDS.has(t.kind), `"${t.title}": kind '${t.kind}' violates tasks_kind_check`);
+    if (t.discipline !== undefined) {
+      assert.ok(VALID_DISCIPLINES.has(t.discipline), `"${t.title}": discipline '${t.discipline}' violates tasks_discipline_check`);
+    }
+  }
+});
+
+test('the look step is a decision BY an ideator in every variant', () => {
+  for (const opts of [{}, { provisioned: true }, { firstSignIn: true }]) {
+    const look = kickoffChecklist(spec(), opts).find((t) => /instance look/i.test(t.title));
+    assert.ok(look, `look step present for ${JSON.stringify(opts)}`);
+    assert.equal(look.kind, 'decision');
+    assert.equal(look.discipline, 'ideator');
+  }
+});
+
+test('returns fresh objects — a filer mutating one cannot poison the next call', () => {
+  const a = kickoffChecklist(spec(), { firstSignIn: true });
+  a[0].title = 'mutated';
+  assert.notEqual(kickoffChecklist(spec(), { firstSignIn: true })[0].title, 'mutated');
+});

package/tests/kickoff_seed.mjs

@@ -0,0 +1,93 @@
+// tests/kickoff_seed.mjs — the lifecycle module files the kickoff checklist at the
+// founder's first sign-in, and only onto an EMPTY board (task 1003239).
+//
+// The seed is idempotent by emptiness, not by path: the self-host path already filed
+// its checklist before anyone signed in, so it must be skipped there without any
+// "was I provisioned" marker. Every case runs against an in-memory pool + insert —
+// no database.
+//
+// Run:  node --test tests/kickoff_seed.mjs
+
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const { seedKickoffIfEmpty, specFromBranding } = require('../modules/lifecycle/kickoff-seed.js');
+const buildRouter = require('../modules/lifecycle/routes/kickoff-seed.js');
+const api = require('../src/module-api.js');
+
+const spec = { firstAdmin: 'founder', repo: { owner: 'o', name: 'n' }, domains: { publicOrigin: 'https://p.example' }, modules: [] };
+
+function fakePool({ taskCount, versions }) {
+  const queries = [];
+  return {
+    queries,
+    query: async (sql) => {
+      queries.push(sql);
+      if (/FROM tasks/.test(sql)) return { rows: [{ n: taskCount }] };
+      if (/FROM versions/.test(sql)) return { rows: versions };
+      throw new Error(`unexpected query: ${sql}`);
+    },
+  };
+}
+
+test('an empty board gets the first-sign-in checklist, as ready tasks attributed to the founder', async () => {
+  const inserted = [];
+  const pool = fakePool({ taskCount: 0, versions: [{ id: 'V1' }] });
+  const r = await seedKickoffIfEmpty({ builderId: 7 }, { pool, spec, createTask: async (row) => { inserted.push(row); return row; } });
+  assert.deepEqual(r, { seeded: 3, versionId: 'V1' });
+  assert.equal(inserted.length, 3);
+  for (const row of inserted) {
+    assert.equal(row.versionId, 'V1');
+    assert.equal(row.status, 'ready', 'claimable from the first board, not backlog');
+    assert.equal(row.source, 'first-sign-in');
+    assert.equal(row.createdBy, 7);
+    assert.ok(row.title && row.description);
+  }
+  assert.match(inserted[0].title, /how people join/i);
+});
+
+test('a board that already has tasks is left alone (the self-host path seeded at init)', async () => {
+  const inserted = [];
+  const pool = fakePool({ taskCount: 12, versions: [{ id: 'V1' }] });
+  const r = await seedKickoffIfEmpty({ builderId: 7 }, { pool, spec, createTask: async (row) => inserted.push(row) });
+  assert.deepEqual(r, { seeded: 0, skipped: 'tasks_exist' });
+  assert.equal(inserted.length, 0);
+  assert.ok(!pool.queries.some((q) => /FROM versions/.test(q)), 'never even looks for a version');
+});
+
+test('no version to file under → skipped, nothing inserted', async () => {
+  const inserted = [];
+  const pool = fakePool({ taskCount: 0, versions: [] });
+  const r = await seedKickoffIfEmpty({ builderId: 7 }, { pool, spec, createTask: async (row) => inserted.push(row) });
+  assert.deepEqual(r, { seeded: 0, skipped: 'no_version' });
+  assert.equal(inserted.length, 0);
+});
+
+test('the version query prefers the building one, then the first by id', async () => {
+  const pool = fakePool({ taskCount: 0, versions: [{ id: 'V1' }] });
+  await seedKickoffIfEmpty({ builderId: 1 }, { pool, spec, createTask: async () => {} });
+  const q = pool.queries.find((s) => /FROM versions/.test(s));
+  assert.match(q, /status = 'building'/);
+  assert.match(q, /LIMIT 1/);
+});
+
+test('specFromBranding reads the instance pack and keeps modules empty', () => {
+  const s = specFromBranding({ firstAdmin: 'f', repo: { owner: 'a', name: 'b' }, domains: { publicOrigin: 'https://x' } });
+  assert.deepEqual(s, { firstAdmin: 'f', repo: { owner: 'a', name: 'b' }, domains: { publicOrigin: 'https://x' }, modules: [] });
+  assert.deepEqual(specFromBranding({}).repo, {});
+});
+
+test('the route factory registers the port once, returns an empty router, and the port delegates', async () => {
+  const before = api.hasProvider('lifecycle.kickoffSeed');
+  const router = buildRouter();
+  buildRouter(); // a rebuild must not trip the single-provider guard
+  assert.ok(api.hasProvider('lifecycle.kickoffSeed'));
+  assert.equal(typeof router, 'function');
+  assert.equal(router.stack.length, 0, 'seeding has no HTTP surface');
+  const port = api.resolveOptional('lifecycle.kickoffSeed');
+  const r = await port.seedIfEmpty({ builderId: 3 }, { pool: fakePool({ taskCount: 1, versions: [] }), spec });
+  assert.deepEqual(r, { seeded: 0, skipped: 'tasks_exist' });
+  assert.equal(before, false, 'this test registered it, nothing else in-process had');
+});

package/tests/provisioning_onboard_mode.mjs

@@ -21,9 +21,8 @@ import { createRequire } from 'node:module';
 import http from 'node:http';
 
 const require = createRequire(import.meta.url);
-const ROOT = new URL('..', import.meta.url).pathname;
 
-const provisioning = require(`${ROOT}/modules/provisioning/provisioning.js`);
+const provisioning = require('../modules/provisioning/provisioning.js');
 
 let passed = 0, failed = 0;
 function t(name, fn) {
@@ -99,11 +98,11 @@ provisioning.enqueueIntent = async () => ({ intent: { id: 1, state: 'pending' },
 provisioning.recordEvent = async () => {};
 provisioning.getInstanceBySlug = async () => null;
 
-const api = require(`${ROOT}/src/module-api.js`);
+const api = require('../src/module-api.js');
 api.requireBuilder = (req, _res, next) => { req.builder = { id: 7, github_login: 'owner' }; next(); };
 
 const express = require('express');
-const provisioningRoutes = require(`${ROOT}/modules/provisioning/routes/provisioning.js`);
+const provisioningRoutes = require('../modules/provisioning/routes/provisioning.js');
 const app = express();
 app.use(express.json());
 app.use((_req, res, next) => {

package/tests/search_ingest.mjs

@@ -11,6 +11,7 @@
 
 import { strict as assert } from 'node:assert';
 import { createRequire } from 'node:module';
+import { fileURLToPath } from 'node:url';
 
 const require = createRequire(import.meta.url);
 const ingest = require('../scripts/gds/search-ingest-md.js');
@@ -61,7 +62,7 @@ test('SENSITIVE_DOC_GLOBS is the curated source of truth (subtrees end with /)',
 
 test('collectMarkdown finds the repo corpus but excludes node_modules/.git/worktrees/public', () => {
   const path = require('node:path');
-  const repoRoot = path.resolve(new URL('..', import.meta.url).pathname);
+  const repoRoot = path.resolve(fileURLToPath(new URL('..', import.meta.url)));
   const real = collectMarkdown(repoRoot, repoRoot);
   // Assert on paths RELATIVE to the repo root — the suite may run from inside a
   // git worktree (…/.claude/worktrees/<name>/…), so the ABSOLUTE paths would all
@@ -77,7 +78,7 @@ test('collectMarkdown finds the repo corpus but excludes node_modules/.git/workt
 
 test('chunkFile yields well-formed rows (source_kind doc, hash, rank, sequential index)', () => {
   const path = require('node:path');
-  const repoRoot = path.resolve(new URL('..', import.meta.url).pathname);
+  const repoRoot = path.resolve(fileURLToPath(new URL('..', import.meta.url)));
   const rows = chunkFile(path.join(repoRoot, 'docs', 'adr', '0016-trust-boundary-server-enforced-permissions.md'));
   assert.ok(rows.length > 0);
   rows.forEach((r, i) => {

package/tests/setup_smoke.mjs

@@ -22,8 +22,9 @@ import { spawnSync } from 'node:child_process';
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
+import { fileURLToPath } from 'node:url';
 
-const REPO_ROOT = path.resolve(path.dirname(new URL(import.meta.url).pathname), '..');
+const REPO_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 const SETUP_JS = path.join(REPO_ROOT, 'scripts/gds/setup.js');
 
 const tests = [];
@@ -36,7 +37,8 @@ function makeFreshHome() {
 
 function runSetup(args, env = {}) {
   return spawnSync('node', [SETUP_JS, ...args], {
-    env: { ...process.env, ...env },
+    // os.homedir() reads USERPROFILE on Windows, so a HOME override alone leaks the real home there.
+    env: { ...process.env, ...env, ...(env.HOME ? { USERPROFILE: env.HOME } : {}) },
     encoding: 'utf8',
     timeout: 15000,
   });

package/tests/test_path_guard.mjs

@@ -0,0 +1,126 @@
+// tests/test_path_guard.mjs — the guard that keeps a test runnable on a checkout
+// whose path has a space in it (task 1002889).
+//
+// Four tests built their repo root from URL.pathname and threw MODULE_NOT_FOUND at
+// load on the owner's Windows checkout, while CI (no space in its path) stayed
+// green. The guard is tested on synthetic sources, not only the live tree: a scan
+// that passes because the tree is clean today proves nothing about what it REFUSES.
+//
+// The defective form is spelled by concatenation below so this file never trips the
+// guard it tests.
+//
+// Of the four files the task named, tests/provisioning_github_app_routes.mjs had
+// already been converted before this landed (915d273b, task 1003236 — fileURLToPath
+// at its line 17), so it is absent from this change on purpose; the live-tree case
+// at the bottom is what proves all four are clean.
+//
+// Run:  node tests/test_path_guard.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const { checkTestsUseFileUrlToPath, scanTests } = require('../scripts/gds/test-path-guard.js');
+
+let passed = 0;
+let failed = 0;
+function test(name, fn) {
+  try { fn(); passed++; console.log(`  ok  ${name}`); }
+  catch (err) { failed++; console.error(`  FAIL ${name}\n    ${err.message}`); }
+}
+
+const from = (map) => ({
+  files: Object.keys(map),
+  read: (rel) => (rel in map ? map[rel] : null),
+});
+
+const BAD_TAIL = 'import.meta.url)' + '.pathname';
+
+// --- THE DEFECT ------------------------------------------------------------
+
+test('the shipped defect is refused, with its line and the fix', () => {
+  const { violations } = scanTests(...Object.values(from({
+    'tests/bad.mjs':
+      "import { createRequire } from 'node:module';\n"
+      + `const ROOT = new URL('..', ${BAD_TAIL};\n`
+      + 'const mod = require(`${ROOT}/modules/x.js`);\n',
+  })));
+  assert.equal(violations.length, 1);
+  assert.match(violations[0], /bad\.mjs:2/, 'names the file and line');
+  assert.match(violations[0], /%20/, 'says WHY it breaks');
+  assert.match(violations[0], /fileURLToPath/, 'and what to write instead');
+});
+
+test('the dirname form is the same defect', () => {
+  const { violations } = scanTests(...Object.values(from({
+    'tests/smoke.mjs': `const REPO_ROOT = path.resolve(path.dirname(new URL(${BAD_TAIL}), '..');\n`,
+  })));
+  assert.equal(violations.length, 1);
+});
+
+test('every site in a file is reported, not just the first', () => {
+  const { violations } = scanTests(...Object.values(from({
+    'tests/two.mjs':
+      `const a = path.resolve(new URL('..', ${BAD_TAIL});\n`
+      + 'x();\n'
+      + `const b = path.resolve(new URL('..', ${BAD_TAIL});\n`,
+  })));
+  assert.equal(violations.length, 2);
+  assert.match(violations[1], /two\.mjs:3/);
+});
+
+// --- WHAT IT MUST NOT FLAG -------------------------------------------------
+
+test('fileURLToPath and a relative createRequire are the correct forms — never flagged', () => {
+  const { violations } = scanTests(...Object.values(from({
+    'tests/good_a.mjs':
+      "import { fileURLToPath } from 'node:url';\n"
+      + "const ROOT = fileURLToPath(new URL('..', import.meta.url));\n",
+    'tests/good_b.mjs':
+      "const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');\n",
+    'tests/good_c.mjs':
+      "const require = createRequire(import.meta.url);\n"
+      + "const mod = require('../modules/x.js');\n",
+  })));
+  assert.deepEqual(violations, []);
+});
+
+test('a request URL parsed for its pathname is not the defect', () => {
+  // http tests routinely do this; the guard is about import.meta.url only.
+  const { violations } = scanTests(...Object.values(from({
+    'tests/routes.mjs': "const { pathname } = new URL(req.url, 'http://x');\nconst p = new URL(req.url, base).pathname;\n",
+  })));
+  assert.deepEqual(violations, []);
+});
+
+// --- THE SCAN MUST NOT SILENTLY SUCCEED ------------------------------------
+
+test('an empty enumeration is a hard FAIL, not a clean pass', () => {
+  const r = checkTestsUseFileUrlToPath({ files: [], read: () => null });
+  assert.equal(r.hardFail, true);
+  assert.match(r.violations[0], /scan defect/);
+});
+
+test('an unreadable file is skipped without being counted as scanned', () => {
+  const { scanned } = scanTests(['gone.mjs'], () => null);
+  assert.equal(scanned, 0);
+});
+
+test('the check reports hardFail so CI actually stops', () => {
+  const r = checkTestsUseFileUrlToPath(from({
+    'tests/bad.mjs': `const ROOT = new URL('..', ${BAD_TAIL};\n`,
+  }));
+  assert.equal(r.ok, false);
+  assert.equal(r.hardFail, true);
+});
+
+// --- THE LIVE TREE ---------------------------------------------------------
+
+test('the tracked tests/ tree is clean (the four sites of task 1002889 are fixed)', () => {
+  const r = checkTestsUseFileUrlToPath();
+  assert.equal(r.hardFail, false, r.violations.join('\n'));
+  assert.ok(/^\d+ test file\(s\) scanned/.test(r.note) && !r.note.startsWith('0 '), r.note);
+});
+
+console.log(`\ntest_path_guard: ${passed} passed, ${failed} failed`);
+process.exit(failed ? 1 : 0);