@bongos/core 1.19.314 → 1.19.316

package/.bongos-core.json

@@ -2,22 +2,22 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.19.314",
-  "core_contract": "1.19.314",
-  "source_commit": "7d49e680ed9b88bc3fd32760e275bc2f52348673",
+  "core_version": "1.19.316",
+  "core_contract": "1.19.316",
+  "source_commit": "8248fac14dda1af6df3a5414027a4bf9d6ba23e0",
   "source_ref": "HEAD",
-  "built_at": "2026-08-23T21:48:01.343Z",
+  "built_at": "2026-08-23T22:02:43.920Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
     "docs_redacted": 323,
     "agent_docs_stubbed": 22,
-    "functional_verbatim": 1421,
+    "functional_verbatim": 1423,
     "rules": 3,
     "gate_literals": 3,
     "gate": "passed"
   },
-  "file_count": 1766,
-  "tree_sha256": "59daa4e8041f110026fee1110197d244eb74cd075b36da6d4fc0d18f4bac0b18",
+  "file_count": 1768,
+  "tree_sha256": "6e3e95467f3b58d962df6fc2490011be711c43787e43adff339b3da3390c2da6",
   "files": [
     {
       "path": ".claude/skills/blocker-review/SKILL.md",
@@ -182,7 +182,7 @@
     {
       "path": ".claude/skills/merge-mode/SKILL.md",
       "mode": "0000644",
-      "sha256": "f6c6b5df321c48bf9c8657145b4b1d7d89a73edf9a9b5f6a511c5339cc828282"
+      "sha256": "a1f797a9267428facc357c59b09d8eafd6b6d8ca36e6d6d7ae0c6bf60c11ab58"
     },
     {
       "path": ".claude/skills/new-project/SKILL.md",
@@ -222,7 +222,7 @@
     {
       "path": ".claude/skills/planning-session/SKILL.md",
       "mode": "0000644",
-      "sha256": "e04564f8189ed7ea1d260f0dbe657cfca769ac46593242721223cd3f0b43c363"
+      "sha256": "f51cb3fec1448883300f5f966dc83f6b9636935059503250ed8a1f944526e743"
     },
     {
       "path": ".claude/skills/priority-session/SKILL.md",
@@ -1797,7 +1797,7 @@
     {
       "path": "docs/recipes/upgrading-the-core.md",
       "mode": "0000644",
-      "sha256": "732f3b01b7d2e6cc238dd5f48d5ed774f6c2c27ecc737710047758bf85f2d9e5"
+      "sha256": "82a8a5b17d465b9048ce645e2bc13acaa492f766726cc79981fff1352a92d1b0"
     },
     {
       "path": "docs/recipes/windows-builders.md",
@@ -4582,12 +4582,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "e2b6abac7133ee151991f267ba79cb55ed677547ebc8adaf573288a959aecc01"
+      "sha256": "6c10d47c4db2e1e159b3c4aad631491bf7818c3a89fbf3f02bc1de512b1163b3"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "47771a7e9c28952af15efa1c8f64fb44cae34698bc385484d1250878145dfc18"
+      "sha256": "2bfd8f95e547fbbf060361a024395b256fe5eb7bde0796600d44494a718da5cb"
     },
     {
       "path": "public-docs/index.html",
@@ -5237,7 +5237,7 @@
     {
       "path": "scripts/gds/fitness.js",
       "mode": "0000644",
-      "sha256": "71f7b70fb6b7b2251c5a335b90faf0b63b51c614829a247679b6f25209549264"
+      "sha256": "a300efecfa69f8ad597a8125df6dd1999d7cdffc8317ac8616b7081555c8b303"
     },
     {
       "path": "scripts/gds/gate-review.js",
@@ -5477,7 +5477,7 @@
     {
       "path": "scripts/gds/npmrc.js",
       "mode": "0000644",
-      "sha256": "9dfd27e75def392a73d7de7fd23d462afc97b17a8199acfe6563a80692570026"
+      "sha256": "1beffeed111e8528cfa0a629d5ef81c766023de5c6820a81659a390070868228"
     },
     {
       "path": "scripts/gds/oauth-secret.js",
@@ -5527,7 +5527,7 @@
     {
       "path": "scripts/gds/preflight.js",
       "mode": "0000644",
-      "sha256": "bd57bb676f0ed6c426129a912727c4ecd363a1197373588fe24f4d48727a75dc"
+      "sha256": "9898b6f8e60b9f5ee4aeb9a023d1b68bb5bfbdf589eed10923a8e492716340ed"
     },
     {
       "path": "scripts/gds/provision.js",
@@ -5804,6 +5804,11 @@
       "mode": "0000644",
       "sha256": "f3005175abc0ba20e958381df6aee02402267e9956da466386656dd4e86ad8cf"
     },
+    {
+      "path": "scripts/gds/skill-preflight.js",
+      "mode": "0000644",
+      "sha256": "2c8297314642a459adb31d4253540fac4a8b3b32a4b79dddd9f0e6cdb87b51fc"
+    },
     {
       "path": "scripts/gds/smoke-batch-claim.sh",
       "mode": "0000644",
@@ -5877,7 +5882,7 @@
     {
       "path": "scripts/gds/upgrade.js",
       "mode": "0000644",
-      "sha256": "04ee659f61c79a1dbc2302f047d1d7870352d0892c2df974f6f000184794d3f8"
+      "sha256": "80856db9974df9b3451decf55385eeb78bcba61e523ca09a2ea070deb48991ab"
     },
     {
       "path": "scripts/gds/validate-design.js",
@@ -6257,7 +6262,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "eac68b3c94db0a8eb79241d515a0df3d19d96f6fb41165c32ea4a963753bd5b1"
+      "sha256": "049a62ecc239e85005e2f79fea63f46edf406b53eb2b4c36e21e81281365afc7"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -7977,7 +7982,7 @@
     {
       "path": "tests/npmrc.mjs",
       "mode": "0000644",
-      "sha256": "87cbb8a5fd896f36197957be56c9107f672a49b2ae8afc3ba69fe00bde11c3ca"
+      "sha256": "1aaa68ee1a4c4a58563cef86aac44cfa0e046ad7376d3a2108bf6dd455580942"
     },
     {
       "path": "tests/oauth_secret.mjs",
@@ -8624,6 +8629,11 @@
       "mode": "0000644",
       "sha256": "4557c934704a009612ed8858c0f59c5b53facb5d92fa2c0740b1aecb079aa5c9"
     },
+    {
+      "path": "tests/skill_preflight.mjs",
+      "mode": "0000644",
+      "sha256": "df2c86d02d560b242a341c905b9ee5fbb25c6479c506736807947749e0a033fa"
+    },
     {
       "path": "tests/skill_prefs.mjs",
       "mode": "0000644",

package/.claude/skills/merge-mode/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: merge-mode
 description: Manual fallback for the auto-merge in /builder-ship. Walks every task at status='confirmed' (= verified but not yet on main) and runs the merge + smoke + deploy chain. Triggers when the user says "/merge-mode", "merge the queue", "land confirmed tasks", "land the queue", "do a merge run", or after a /builder-ship reported the auto-merge bailed.
+requires: [main-checkout, push-credential, gh, droplet-ssh]
 ---
 
 You are running the manual merge-mode session for Example. **`/merge-mode` is a rare last resort, not a routine sweep — and not something to push on other builders.** The server lands merges on its own: `/builder-ship` chains into auto-merge, green PRs auto-merge, a 5-min reconciler flips `confirmed → shipped`, and the [ADR 0082](../../../docs/adr/<redacted>.md) resolver self-heals generated-file conflicts. **Before running this skill, confirm the task is genuinely stuck** — still at `confirmed` more than ~5 minutes after its ship because of a conflict or regression the server couldn't auto-resolve. If you haven't waited for the sweep yet, stop and wait. This skill is for the strand that survives all of that — usually a cross-branch / non-generated-file conflict, a smoke regression, or a `--no-merge` ship.
@@ -17,6 +18,21 @@ The queue this skill works against is **tasks at status='confirmed'**. Those are
 
 ## How to use
 
+**Step 0 — preflight this machine, before anything else.**
+
+```bash
+node scripts/gds/skill-preflight.js merge-mode   # exits 1 naming what is MISSING
+```
+
+If it exits non-zero, **stop**: this machine cannot finish the procedure, and the
+partial run is the dangerous outcome (it mutates the main worktree). The skill's
+`requires:` frontmatter is what it checks — `main-checkout`, `push-credential`,
+`gh`, `droplet-ssh`. This gate exists because the note below was prose only, and
+prose cannot refuse: merge-mode was run on a dev box that had none of them, while
+`ship.js` separately already knew (`strandNextStep` tells a box "/merge-mode is
+NOT available here"). The knowledge existed twice and neither copy stopped the run
+(task 1003167).
+
 > **Environment note:** merge-mode is an **ops procedure** — it mutates the single
 > main worktree and deploys to the Linux droplet (owner-gated SSH). The git /
 > `ssh` / `deploy.sh` / branch-inventory steps below assume a bash environment

package/.claude/skills/planning-session/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: planning-session
 description: Run a structured planning session for an upcoming Bongos version — set scope criteria, draft a written spec, interview the owner in depth to resolve every non-obvious decision, then seed the ranked task list from that spec. Triggers when the user says "/planning-session", "open a planning session", "let's plan V[N]", "plan the next version", or "scope a new version". Metic+ rank only (Metic and Archon; not Xenos).
+requires: [droplet-ssh]
 ---
 
 You are running a planning session for Bongos. The goal is to leave the session with: (a) a clear set of done-when criteria for a version, (b) a **written spec** (`docs/specs/<ver>-<goal-slug>.md`) that an in-depth interview refines until every non-obvious decision is resolved, (c) a ranked task list **seeded from that spec** that lives in the Bongos database, and (d) a durable record of the session for the audit trail.
@@ -193,9 +194,18 @@ a builder-local one (so the bash/`ssh`/`psql` here is server-side by design, not
 a Windows concern):
 
 ```bash
+node scripts/gds/skill-preflight.js planning-session   # stops here if this box has no ssh
 ssh lars@REDACTED_IP "psql -d example -c '\\d tasks' | grep -i check"
 ```
 
+The preflight sits at THIS step rather than at the top of the skill on purpose:
+the `droplet-ssh` this skill declares is needed for one optional lookup, not for
+the whole session, so gating the entire planning session on it would refuse work
+that does not need it. Compare `/merge-mode`, where the capabilities are
+preconditions for the whole procedure and the gate is Step 0. Both placements are
+legitimate; what is not legitimate is declaring a capability and never checking it
+(task 1003167).
+
 Confirm what the `priority` column actually allows.
 
 **Encoding (V3 convention):** priority is `1-5` (CHECK constraint). Use priority by tier:

package/docs/recipes/upgrading-the-core.md

@@ -116,6 +116,8 @@ Each subscribed instance: read its installed core → ask the registry (`npm vie
 
 ## Gotchas
 
+- **`--registry` no longer needs a hand-exported `NPM_TOKEN`** (task 1002754). The instance `.npmrc` reads `_authToken=<redacted>, and npm gives that per-project key precedence — so with the env var unset it expanded EMPTY and **masked a perfectly valid literal token in `~/.npmrc`** (npm went anonymous; the private core 404'd; the error blamed a "missing" credential the box actually held). `bongos upgrade --registry` now resolves the credential itself: env `NPM_TOKEN` wins, else the **user-level `~/.npmrc`'s literal `//registry.npmjs.org/:_authToken=…`** is injected into the install's environment (forward install and rollback reinstall both). A pin bump on a box whose `~/.npmrc` authenticates therefore succeeds with **no exported env var**. Resolver: `resolveNpmToken()` in [`scripts/gds/npmrc.js`](../../scripts/gds/npmrc.js).
+- **A green `publish` run is not evidence of a publish.** The publish-on-merge lane succeeds on its no-op paths too (cascade terminator, armed-gate). Read the run's **job summary**, which now states the verdict explicitly: `PUBLISHED @bongos/core@<v>` vs `NO-OP — nothing was published this run`.
 - **`PGDATABASE` is load-bearing on a co-tenant droplet.** `migrate.sh` defaults `PGDATABASE` to `example` — **production**. Always set `PGDATABASE=<instance-db>` explicitly, or you migrate the wrong database.
 - **The health check polls the restart** (fixed in task [#1984](https://example.com/builders#/task/1984)). The service binds its port ~1s after `systemctl restart`, so `--health-url` now polls up to ~30s for a 2xx before reporting a warning — an immediate `fetch failed` no longer means a failed upgrade. (Pre-1984 cores fetched once and spuriously reported `fetch failed`; there, confirm with `is-active` + a manual `curl`.)
 - **The ledger auto-inserts via `PGDATABASE` too** (fixed in task [#1984](https://example.com/builders#/task/1984)). A consumer on `PGDATABASE` + peer auth now gets its `core_upgrades` row written automatically — the channel delegates the insert to `psql -d "$PGDATABASE"`, exactly like `migrate.sh`, so no manual `psql INSERT` is needed. (`DATABASE_URL` still works, via the `pg` driver.) Pre-1984 cores only auto-wrote with `DATABASE_URL`; on those, record the row manually.

package/package-lock.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.314",
+  "version": "1.19.316",
   "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

@@ -1655,7 +1655,6 @@ function checkWriteRoutesValidated() {
   };
 }
 
-// ---- runner ----------------------------------------------------------------
 
 // ── Check 19 — the ADR 0174 vocabulary wall (goal 1000068 R07, task 1003008) ──
 //
@@ -1899,6 +1898,7 @@ const CHECKS = [
   checkWriteRoutesValidated, // Check 18 — BV1 R12 / task 1999: every body-reading write route validates (ADR 0118)
   require('./fitness-ratchets.js').checkQualityRatchets, // Check 20 — task 1003129: quality budgets only tighten (mechanics + knip CI step live in fitness-ratchets.js)
   require('./doc-cli-guard.js').checkDocNamesRealCli, // Check 22 — task 1003165 / G01: a doc that names a CLI invocation must match the real CLI
+  require('./skill-preflight.js').checkOpsSkillsDeclareMachine, // Check 23 — task 1003167 / G03: an ops skill declares the machine it needs
   require('./control-manifest.js').checkControlsExist, // Check 21 — task 1003131: goal-1000076 controls assert their own existence (the ADR 0022 assurance-of-assurance)
 ];
 

package/scripts/gds/npmrc.js

@@ -48,6 +48,37 @@ function hasNpmToken(env = process.env) {
   return !!String(env[TOKEN_ENV] || '').trim();
 }
 
+// resolveNpmToken (task 1002754) — the install-time credential resolver that removes
+// the hand-exported-NPM_TOKEN step from deploys.
+//
+// THE TRAP. The committed instance `.npmrc` reads `_authToken=${NPM_TOKEN}`; npm gives
+// a per-project key precedence over the user-level one, so with NPM_TOKEN unset the
+// expansion is EMPTY and it MASKS a perfectly valid literal token in ~/.npmrc — npm
+// goes anonymous and the private core 404s. Every deploy then silently depended on the
+// operator remembering `export NPM_TOKEN=…` (the ADR-0162 shape: a human-gated step in
+// the ship path). npm's config syntax cannot express "env var, else fall through", so
+// the fix is to RESOLVE the credential here and feed it to the child install's env —
+// the committed file stays secret-free and unchanged.
+//
+// Order: env NPM_TOKEN wins (explicit operator intent), else the user-level ~/.npmrc's
+// literal `//<host>/:_authToken=<value>` (ignoring env-fed `${…}` values — those are
+// the trap, not a credential). Returns { token, source: 'env'|'user-npmrc'|null }.
+function resolveNpmToken({ env = process.env, homedir, fsImpl = fs, host = REGISTRY_HOST } = {}) {
+  const fromEnv = String(env[TOKEN_ENV] || '').trim();
+  if (fromEnv) return { token: fromEnv, source: 'env' };
+  const home = homedir || (env.HOME || env.USERPROFILE || '');
+  if (home) {
+    try {
+      const raw = fsImpl.readFileSync(path.join(home, '.npmrc'), 'utf8');
+      const re = new RegExp(`^\\s*//${host.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}/:_authToken\\s*=\\s*(.+?)\\s*$`, 'm');
+      const m = re.exec(raw);
+      const val = m && m[1].replace(/^["']|["']$/g, '');
+      if (val && !val.includes('${')) return { token: val, source: 'user-npmrc' };
+    } catch { /* no user npmrc, unreadable — fall through to null */ }
+  }
+  return { token: null, source: null };
+}
+
 // Has the operator opted the standalone scaffold into the registry path? OFF by
 // default — the vendored tarball stays the default until the registry path is proven
 // end-to-end (ADR 0134). '1'/'true'/'yes'/'on' (case-insensitive) → true.
@@ -76,7 +107,7 @@ function writeNpmrc(dir, { fsImpl = fs, dryRun = false, overwrite = true, log =
 
 module.exports = {
   REGISTRY_HOST, CORE_SCOPE, TOKEN_ENV, REQUEST_ENV,
-  npmrcContent, hasNpmToken, registryCoreRequested, writeNpmrc,
+  npmrcContent, hasNpmToken, resolveNpmToken, registryCoreRequested, writeNpmrc,
 };
 
 // Tiny CLI: `node scripts/gds/npmrc.js [--print | --write <dir>]` — print the `.npmrc`

package/scripts/gds/preflight.js

@@ -40,11 +40,34 @@ const HEADLESS_AUTH_ENV = ['CLAUDE_CODE_OAUTH_TOKEN', 'ANTHROPIC_API_KEY'];
 // caller — /builder-start runs on every session open — can reuse THIS exact
 // finding without paying for the `claude --version` spawn the full
 // preflightChecks() does. Pure: injectable fs + repoRoot.
+//
+// WORKTREES (task 1003167 / idea 1000788): this used to test `repoRoot/node_modules`
+// ONLY, and a git worktree never has its own. But node's module resolution walks UP
+// from the requiring file, so every require in a worktree resolves against the real
+// repo root and works fine — meaning the check fired on essentially every claim
+// (worktree-per-claim is the project default), telling the builder to burn an
+// `npm ci` they did not need. A preflight that cries wolf is worse than none: it
+// trains people to read past the one time it is right. So resolve the way node
+// itself does — walk up — and only then call it missing.
 function depsFinding({ repoRoot = REPO_ROOT, fs = nodeFs } = {}) {
   let hasDeps = false;
-  try { hasDeps = fs.existsSync(nodePath.join(repoRoot, 'node_modules')); } catch (_) { /* treat as missing */ }
+  let foundAt = null;
+  try {
+    let dir = nodePath.resolve(repoRoot);
+    for (;;) {
+      if (fs.existsSync(nodePath.join(dir, 'node_modules'))) { hasDeps = true; foundAt = dir; break; }
+      const up = nodePath.dirname(dir);
+      if (up === dir) break; // hit the filesystem root
+      dir = up;
+    }
+  } catch (_) { /* treat as missing */ }
   if (hasDeps) {
-    return { level: 'ok', title: 'Dependencies', detail: 'node_modules present.' };
+    const here = nodePath.resolve(repoRoot) === foundAt;
+    return {
+      level: 'ok',
+      title: 'Dependencies',
+      detail: here ? 'node_modules present.' : `node_modules resolved from a parent (${foundAt}) — normal in a git worktree; requires resolve fine.`,
+    };
   }
   return {
     level: 'warn',

package/scripts/gds/skill-preflight.js

@@ -0,0 +1,336 @@
+#!/usr/bin/env node
+// scripts/gds/skill-preflight.js — an ops skill declares the machine it needs,
+// and refuses early when this machine is not it (task 1003167 / G03, goal
+// 1000077; criterion guards-skill-declares-machine).
+//
+// THE INCIDENT. /merge-mode states in its own prose that it assumes the Archon's
+// Mac or the droplet. It was run on a dev box anyway. Worse, ship.js ALREADY knew:
+// strandNextStep() tells a box "/merge-mode is NOT available here — it needs gh +
+// a main checkout this machine doesn't have." So the knowledge existed in two
+// places and neither stopped the run, because prose cannot refuse and the one
+// executable copy was on a different code path. A capability a procedure needs
+// must be a declaration the machine can CHECK, not a sentence a reader can skim.
+//
+// THREE PARTS, matching that diagnosis:
+//   1. `requires:` in the skill's own YAML frontmatter — the declaration.
+//   2. this preflight — the check, naming the MISSING capability and nothing else.
+//   3. checkOpsSkillsDeclareMachine() in fitness.js — the assertion that a skill
+//      whose fenced commands touch main/deploy actually carries a declaration.
+//
+// TRI-STATE, deliberately. A probe returns true / false / null, and null means
+// "could not tell" (the context-pack isMainCheckout precedent). We REFUSE on
+// false and WARN on null: refusing on unknown would block legitimate machines,
+// and passing on unknown silently would rebuild the hole this closes.
+//
+// The preflight NEVER connects to anything. Proving an SSH key reaches a host
+// means using it, and a preflight with side effects is not a preflight.
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { spawnSync } = require('node:child_process');
+const { resolveWorktreeRoot } = require('./context-pack.js');
+const { depsFinding } = require('./preflight.js');
+
+const REPO_ROOT = path.resolve(__dirname, '..', '..');
+const runGit = (args) => spawnSync('git', args, { cwd: process.cwd(), encoding: 'utf8' }).stdout || '';
+
+// Memoized for the life of the process. merge-mode declares BOTH `gh` and
+// `push-credential`, and push-credential's probe also consults gh — so without
+// this, one preflight spawned `gh auth status` twice, each with a 15s timeout.
+// A preflight slow enough to be worth skipping is a preflight nobody runs, which
+// would defeat the entire point of this task.
+let _ghAuthed = null;
+function ghAuthed({ fresh = false } = {}) {
+  if (!fresh && _ghAuthed !== null) return _ghAuthed;
+  _ghAuthed = ghAuthedUncached();
+  return _ghAuthed;
+}
+
+function ghAuthedUncached() {
+  try {
+    const a = spawnSync('gh', ['auth', 'status'], {
+      stdio: 'ignore', shell: process.platform === 'win32', windowsHide: true, timeout: 15000,
+    });
+    return !!a && !a.error && a.status === 0;
+  } catch { return false; }
+}
+
+function binaryPresent(name) {
+  try {
+    const probe = process.platform === 'win32' ? ['where', [name]] : ['which', [name]];
+    const r = spawnSync(probe[0], probe[1], { stdio: 'ignore', shell: process.platform === 'win32', timeout: 10000 });
+    return !!r && !r.error && r.status === 0;
+  } catch { return false; }
+}
+
+// The registry. `probe` returns true | false | null. `missing` is the sentence a
+// builder reads when it comes back false — it must name the remedy, because the
+// whole failure mode here was a reader who knew the rule and still had nowhere
+// to go with it.
+const CAPABILITIES = {
+  gh: {
+    what: 'an authenticated GitHub CLI',
+    probe: () => ghAuthed(),
+    missing: 'no authenticated `gh` on this machine. Run `gh auth login`, or use a machine that has it — '
+      + 'a dev box normally does not, by design (it publishes through the server instead, ADR 0055).',
+  },
+  'main-checkout': {
+    what: 'the main checkout, not a linked worktree',
+    // Tri-state on purpose: resolveWorktreeRoot cannot always tell.
+    probe: () => resolveWorktreeRoot({ runGit, cwd: process.cwd() }).isMainCheckout,
+    missing: 'this is a linked worktree, not the main checkout. Procedures that mutate `main` must run in the '
+      + 'main checkout — a worktree holding the branch has nowhere to merge INTO (task 1002572).',
+  },
+  'push-credential': {
+    // Mirrors ship.js pushVia(): the project's operative definition of "can push"
+    // is an authed gh (or an explicit token), and everything else routes through
+    // the server. Following that rather than inventing a stricter rule keeps one
+    // answer to the question instead of two that can disagree.
+    what: 'a credential that can push to origin',
+    probe: () => ghAuthed() || !!(process.env.GITHUB_TOKEN || process.env.GH_TOKEN),
+    missing: 'no push credential here. This machine lands work through the server-mediated publish '
+      + '(`node scripts/gds/ship.js <id>` resumes it) — it cannot push `main` directly.',
+  },
+  'droplet-ssh': {
+    what: 'SSH access to the deploy host',
+    // false when there is no ssh at all; null when there is, because proving the
+    // key and host actually work would mean connecting.
+    probe: () => (binaryPresent('ssh') ? null : false),
+    missing: 'no `ssh` binary on this machine, so a step that reaches the deploy host cannot run. '
+      + 'In `ci` deploy mode nothing should need it — check config/deploy.json before proceeding.',
+  },
+  tty: {
+    what: 'an interactive terminal',
+    probe: () => !!(process.stdin.isTTY && process.stdout.isTTY),
+    missing: 'no TTY — this procedure prompts, and a prompt with nobody to answer it hangs. '
+      + 'Use the non-interactive form (a --*-file flag or an explicit flag) instead.',
+  },
+  'node-modules': {
+    what: 'resolvable dependencies',
+    // DELEGATES to preflight.js rather than testing repoRoot/node_modules itself.
+    // Writing that test here is exactly the bug idea 1000788 reported against
+    // depsFinding: a worktree has no node_modules of its own, yet every require
+    // resolves fine because node walks up. Two copies of a probe are two chances
+    // to disagree, and this task exists because knowledge lived in two places.
+    probe: () => depsFinding().level === 'ok',
+    missing: 'dependencies are not resolvable from this tree — a step needing pg/express/pino will fail. '
+      + 'Run `npm ci` in the repo root.',
+  },
+};
+
+// ---- the declaration ------------------------------------------------------
+// Read `requires:` out of a skill's YAML frontmatter. Accepts the inline form
+// (`requires: [gh, main-checkout]`) and the dash-list form. Returns
+// { requires, declared, error }: `declared` distinguishes "declared nothing"
+// from "declared an empty list", which the fitness check needs to tell apart.
+function parseRequires(md) {
+  const m = /^---\n([\s\S]*?)\n---/.exec(String(md || ''));
+  if (!m) return { requires: [], declared: false, error: null };
+  const fm = m[1];
+  const inline = /^requires:[ \t]*\[(.*?)\][ \t]*$/m.exec(fm);
+  if (inline) {
+    const items = inline[1].split(',').map((s) => s.trim().replace(/^['"]|['"]$/g, '')).filter(Boolean);
+    return { requires: items, declared: true, error: null };
+  }
+  const block = /^requires:[ \t]*\n((?:[ \t]*-[ \t]*\S.*\n?)+)/m.exec(fm);
+  if (block) {
+    const items = block[1].split('\n')
+      .map((l) => /^[ \t]*-[ \t]*(.+?)[ \t]*$/.exec(l))
+      .filter(Boolean).map((x) => x[1].replace(/^['"]|['"]$/g, ''));
+    return { requires: items, declared: true, error: null };
+  }
+  if (/^requires:/m.test(fm)) {
+    // Present but unparseable — say so rather than reporting zero requirements,
+    // which would read as "declared, needs nothing" (the docs-entropy lesson: a
+    // scan that finds nothing must not be indistinguishable from a clean pass).
+    return { requires: [], declared: true, error: 'requires: is present but not a list ([a, b] or a dash list)' };
+  }
+  return { requires: [], declared: false, error: null };
+}
+
+// ---- what a skill's fenced commands imply it needs -------------------------
+// FENCED BLOCKS ONLY, and comments stripped. Prose that NAMES a command is
+// discussion — dev/SKILL.md forbids `git push origin main`, and an earlier draft
+// of this scan flagged it for saying so. A fenced line is an instruction to run.
+const SIGNALS = [
+  [/(?:^|[\s|(])node\s+scripts\/gds\/push-main\.js\b/m, 'push-credential'],
+  [/(?:^|[\s|(])git\s+push\s+origin\s+main\b/m, 'push-credential'],
+  [/(?:^|[\s|(])node\s+scripts\/gds\/go-live\.js\b/m, 'push-credential'],
+  [/(?:^|[\s|(])ssh\s+(?:-o\s+\S+\s+)?\S+@/m, 'droplet-ssh'],
+  [/~\/deploy\.sh/m, 'droplet-ssh'],
+  [/(?:^|[\s|(])node\s+scripts\/gds\/merge-lock\.js\b/m, 'main-checkout'],
+  [/(?:^|[\s|(])bash\s+scripts\/gds\/smoke-write\.sh\b/m, 'main-checkout'],
+  [/(?:^|[\s|(])gh\s+(?:auth|pr|secret|api|run|repo|workflow)\b/m, 'gh'],
+];
+
+function fencedCode(md) {
+  const fences = String(md || '').match(/```[a-z]*\n[\s\S]*?```/g) || [];
+  return fences
+    .map((f) => f.replace(/^```[a-z]*\n/, '').replace(/```$/, ''))
+    .join('\n')
+    .split('\n')
+    .map((l) => l.replace(/(^|\s)#.*$/, '$1')) // a shell comment is discussion
+    .join('\n');
+}
+
+function inferRequired(md) {
+  const code = fencedCode(md);
+  const out = new Set();
+  for (const [rx, cap] of SIGNALS) if (rx.test(code)) out.add(cap);
+  return [...out].sort();
+}
+
+// ---- the check ------------------------------------------------------------
+// Returns { ok, missing, unknown, checked }. `missing` is what came back FALSE —
+// the only thing the CLI prints, because the task's own wording is that the
+// preflight must name the MISSING capability, not recite the list.
+function preflight(requires, caps = CAPABILITIES) {
+  const missing = [];
+  const unknown = [];
+  const checked = [];
+  for (const name of requires) {
+    const cap = caps[name];
+    if (!cap) {
+      missing.push({ name, why: `unknown capability "${name}" — not in the registry (typo in the skill's requires:?)` });
+      continue;
+    }
+    let verdict;
+    try { verdict = cap.probe(); } catch (err) { verdict = null; }
+    checked.push(name);
+    if (verdict === false) missing.push({ name, why: cap.missing });
+    else if (verdict === null) unknown.push({ name, why: `could not confirm ${cap.what} — proceeding, but verify before a destructive step.` });
+  }
+  return { ok: missing.length === 0, missing, unknown, checked };
+}
+
+// A skill name is one path SEGMENT. Containment is checked rather than assumed:
+// `skill-preflight.js ../../../etc` would otherwise read outside .claude/skills.
+// Harmless today (a local, read-only CLI the caller could equally well `cat`), but
+// this helper is exactly the kind that gets reused somewhere less trusting.
+// Returns null for anything that is not a plain segment.
+function skillPath(name) {
+  const n = String(name || '');
+  if (!n || n !== path.basename(n) || n === '.' || n === '..') return null;
+  const full = path.join(REPO_ROOT, '.claude', 'skills', n, 'SKILL.md');
+  const base = path.join(REPO_ROOT, '.claude', 'skills') + path.sep;
+  return full.startsWith(base) ? full : null;
+}
+
+function preflightSkill(name, caps = CAPABILITIES) {
+  const p = skillPath(name);
+  if (!p) {
+    return { ok: false, requires: [], missing: [{ name: 'skill', why: `"${name}" is not a skill name — it must be a single directory name under .claude/skills/.` }], unknown: [], checked: [] };
+  }
+  let md;
+  try { md = fs.readFileSync(p, 'utf8'); } catch {
+    return { ok: false, missing: [{ name: 'skill', why: `no skill named "${name}" at .claude/skills/${name}/SKILL.md` }], unknown: [], checked: [] };
+  }
+  const { requires, error } = parseRequires(md);
+  if (error) return { ok: false, missing: [{ name: 'requires', why: `${name}: ${error}` }], unknown: [], checked: [] };
+  return { ...preflight(requires, caps), requires };
+}
+
+// ---- the assertion (fitness check 23) --------------------------------------
+// A skill whose FENCED commands need a capability must DECLARE it. This is the
+// part that stops the contract rotting: without it, a new ops step gets added to
+// a skill years from now and the declaration silently falls behind the commands.
+//
+// It compares inferRequired() (what the fenced commands imply) against
+// parseRequires() (what the frontmatter claims) and reds the build on a gap. It
+// does NOT complain about a skill declaring MORE than its fences imply — a human
+// knows things the scan cannot see, and punishing an over-declaration would train
+// people to declare less.
+const SKILLS_DIR = path.join(REPO_ROOT, '.claude', 'skills');
+
+function checkOpsSkillsDeclareMachine({ dir = SKILLS_DIR, read = null, names: injected = null } = {}) {
+  const violations = [];
+  const warnings = [];
+  let names = injected;
+  if (!names) {
+    try {
+      names = fs.readdirSync(dir, { withFileTypes: true }).filter((d) => d.isDirectory()).map((d) => d.name).sort();
+    } catch { names = []; }
+  }
+  // A scan that enumerates nothing must fail, not pass (the docs-entropy lesson).
+  if (!names.length) {
+    return {
+      name: 'ops skills declare the machine they need (G03)',
+      ok: false, hardFail: true,
+      violations: ['scan defect — enumerated 0 skills under .claude/skills/.'],
+      warnings: [], note: 'static scan of skill frontmatter vs the commands each skill actually fences.',
+    };
+  }
+  const readOne = read || ((n) => {
+    try { return fs.readFileSync(path.join(dir, n, 'SKILL.md'), 'utf8'); } catch { return null; }
+  });
+
+  let declaring = 0;
+  for (const n of names) {
+    const md = readOne(n);
+    if (md === null) continue;
+    const { requires, error } = parseRequires(md);
+    if (error) { violations.push(`${n}: ${error}`); continue; }
+    if (requires.length) declaring += 1;
+    for (const r of requires) {
+      if (!CAPABILITIES[r]) {
+        violations.push(`${n} declares an unknown capability "${r}" — it can never be probed, so the declaration is decorative. Registry: ${Object.keys(CAPABILITIES).join(', ')}.`);
+      }
+    }
+    // DECLARING is not ENFORCING. planning-session shipped a `requires:` with no
+    // preflight call, which is the same shape as the original bug: a contract
+    // stated where nothing checks it. If a skill names a machine, it must also
+    // run the check (the grader caught this one on the first pass).
+    if (requires.length && !/skill-preflight\.js\s+\S/.test(md)) {
+      violations.push(
+        `${n} declares requires: [${requires.join(', ')}] but never runs \`node scripts/gds/skill-preflight.js ${n}\`. `
+        + 'A declaration nothing enforces is prose, and prose cannot refuse — the exact failure this check exists for.'
+      );
+    }
+    const inferred = inferRequired(md);
+    const undeclared = inferred.filter((c) => !requires.includes(c));
+    if (undeclared.length) {
+      violations.push(
+        `${n} fences commands needing [${undeclared.join(', ')}] but does not declare them. `
+        + 'Add them to `requires:` in the frontmatter so the preflight can refuse early — '
+        + 'prose cannot refuse, which is how /merge-mode came to be run on a dev box (task 1003167).'
+      );
+    }
+  }
+  return {
+    name: 'ops skills declare the machine they need (G03)',
+    ok: violations.length === 0,
+    hardFail: violations.length > 0,
+    violations,
+    warnings,
+    note: `${names.length} skill(s) scanned; ${declaring} declare a machine contract. A skill whose FENCED commands need gh / a main checkout / a push credential / the deploy host must name it in \`requires:\`, so \`node scripts/gds/skill-preflight.js <skill>\` can refuse before the procedure starts. Prose in a skill body cannot refuse.`,
+  };
+}
+
+function main() {
+  const name = process.argv[2];
+  if (!name || name.startsWith('--')) {
+    console.error('usage: node scripts/gds/skill-preflight.js <skill-name>');
+    console.error('  exits 1 naming the capability this machine is MISSING for that skill.');
+    process.exit(2);
+  }
+  const r = preflightSkill(name);
+  for (const u of r.unknown) console.error(`?  ${u.name}: ${u.why}`);
+  if (r.ok) {
+    console.log(`preflight OK — ${name}: ${r.checked.length ? r.checked.join(', ') : 'no machine requirements declared'}.`);
+    process.exit(0);
+  }
+  console.error(`STOP — /${name} cannot run on this machine.`);
+  for (const m of r.missing) console.error(`✗  ${m.name}: ${m.why}`);
+  process.exit(1);
+}
+
+if (require.main === module) main();
+
+module.exports = {
+  CAPABILITIES, SIGNALS,
+  parseRequires, inferRequired, fencedCode,
+  preflight, preflightSkill, skillPath, checkOpsSkillsDeclareMachine,
+  ghAuthed, binaryPresent,
+};

package/scripts/gds/upgrade.js

@@ -30,7 +30,7 @@ const fs = require('node:fs');
 const path = require('node:path');
 const { spawnSync } = require('node:child_process');
 const { arg, hasFlag } = require('./cli-lib');
-const { writeNpmrc, hasNpmToken } = require('./npmrc'); // ADR 0134 (task 2090): the --registry channel's env-fed .npmrc
+const { writeNpmrc, hasNpmToken, resolveNpmToken } = require('./npmrc'); // ADR 0134 (task 2090): the --registry channel's env-fed .npmrc; resolveNpmToken task 1002754
 
 const CORE_PKG = '@bongos/core';
 const ARTIFACT = 'bongos-core';
@@ -284,10 +284,14 @@ function reportModulePreflight(mods, targetVersion, { log = console.log, err = c
   return lines;
 }
 
-function npmInstall(instanceDir, run = spawnSync) {
+function npmInstall(instanceDir, run = spawnSync, extraEnv = null) {
   // `npm install` (NOT `npm ci`): the pin just changed, so the lockfile must be regenerated from the
   // new tarball; `npm ci` would refuse on the package.json↔lock divergence.
-  const r = run('npm', ['install', '--no-audit', '--no-fund'], { cwd: instanceDir, stdio: 'inherit' });
+  // extraEnv (task 1002754): the registry path injects a resolved NPM_TOKEN here so the
+  // instance `.npmrc`'s `${NPM_TOKEN}` expansion never shadows a valid user-level token.
+  const opts = { cwd: instanceDir, stdio: 'inherit' };
+  if (extraEnv) opts.env = { ...process.env, ...extraEnv };
+  const r = run('npm', ['install', '--no-audit', '--no-fund'], opts);
   return !r || r.error ? { ok: false, reason: r && r.error ? r.error.message : 'spawn failed' } : { ok: r.status === 0, code: r.status };
 }
 
@@ -703,8 +707,11 @@ async function rollback({ instanceDir, snapshot, fromVersion, toVersion, opts },
   try { restore(instanceDir, snapshot.prevPin, fsImpl); result.restoreOk = true; log(`  ✓ restored pin → ${snapshot.prevPin}`); }
   catch (e) { result.restoreOk = false; err(`  ! could not restore pin (${e.message}) — package.json may need manual repair`); }
 
-  // 2. reinstall the previous core.
-  const inst = npmInstall(instanceDir, run);
+  // 2. reinstall the previous core. Same credential resolution as the forward path
+  //    (task 1002754): the previous pin may be a registry pin too, and a rollback
+  //    must never fail on the env-shadowing trap the forward install just avoided.
+  const rbCred = resolveNpmToken();
+  const inst = npmInstall(instanceDir, run, rbCred.source === 'user-npmrc' ? { NPM_TOKEN: rbCred.token } : null);
   result.reinstallOk = !!inst.ok;
   if (inst.ok) log('  ✓ reinstalled previous core');
   else err(`  ! reinstall of previous core failed (${inst.reason || 'exit ' + inst.code}) — the instance may need manual repair`);
@@ -813,9 +820,17 @@ async function runUpgrade(opts, deps = {}) {
   //    REGISTRY (--registry): pin @bongos/core@<version> + ensure the env-fed .npmrc, so
   //      the `npm install` below pulls the PRIVATE package from the registry (needs NPM_TOKEN).
   //    VENDORED (default, --from <tgz>): copy the .tgz into vendor/ + rewrite the file: dep.
+  let installEnv = null;
   if (opts.registry) {
     if (opts.from) return { ok: false, error: '--registry and --from are mutually exclusive (registry pull vs vendored tarball) — pick one core source' };
-    if (!hasNpmToken()) log('  ! no NPM_TOKEN in env — `npm install` will 404 on the PRIVATE @bongos/core until a read-only automation token is provided (ADR 0134).');
+    // task 1002754 — resolve the credential HERE instead of demanding a hand-exported
+    // env var: env NPM_TOKEN wins, else the user-level ~/.npmrc's literal token is
+    // injected into the install's env so the instance `.npmrc`'s `${NPM_TOKEN}`
+    // expansion (which OUTRANKS the user-level key and expands EMPTY when unset)
+    // can never shadow a working credential again.
+    const cred = resolveNpmToken();
+    if (!cred.token) log('  ! no NPM_TOKEN in env and no literal token in ~/.npmrc — `npm install` will 404 on the PRIVATE @bongos/core until a read-only automation token is provided (ADR 0134).');
+    else if (cred.source === 'user-npmrc') { installEnv = { NPM_TOKEN: cred.token }; log('  ✓ registry credential: inherited from the user-level ~/.npmrc (no NPM_TOKEN export needed — task 1002754)'); }
     const prevPin = dryRun ? null : writeRegistryPin(instanceDir, targetVersion, fsImpl);
     if (!dryRun) { writeNpmrc(instanceDir, { fsImpl, overwrite: false, log }); snapshot = { prevPin, prevVersion: fromVersion }; }
     log(`  ${dryRun ? '[dry-run] would pin' : '✓ pinned'} ${CORE_PKG} → ${targetVersion} (registry)${dryRun ? ' + write an env-fed .npmrc' : ''}${prevPin ? `  (was ${prevPin})` : ''}`);
@@ -837,7 +852,7 @@ async function runUpgrade(opts, deps = {}) {
   if (dryRun) { log('  [dry-run] would: npm install → npm run migrate → materialize .claude → regen API docs+client → restart → verify'); return { ok: true, dryRun: true, fromVersion, toVersion: targetVersion }; }
 
   // 3. npm install.
-  const inst = npmInstall(instanceDir, run);
+  const inst = npmInstall(instanceDir, run, installEnv);
   if (!inst.ok) {
     const error = `npm install failed (${inst.reason || 'exit ' + inst.code})`;
     if (rollbackOnFailure && snapshot) {

package/src/module-api.js

@@ -1055,8 +1055,12 @@ const { validateOrRespond, LIMITS, parseId, asyncHandler, corsPublicGet, parsePa
 //         landed since 1.19.312 with no explicit bump. run 32668457836. (task 1002620)
 //   1.19.314 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
 //         landed since 1.19.313 with no explicit bump. run 32668599111. (task 1002620)
+//   1.19.315 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+//         landed since 1.19.314 with no explicit bump. run 32668969037. (task 1002620)
+//   1.19.316 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+//         landed since 1.19.315 with no explicit bump. run 32669347711. (task 1002620)
 // ---------------------------------------------------------------------------
-const CORE_VERSION = '1.19.314'; // CI auto-patch carrier (ADR 0161); see changelog above
+const CORE_VERSION = '1.19.316'; // 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/npmrc.mjs

@@ -100,6 +100,55 @@ test('writeNpmrc: overwrite:true (default) replaces an existing .npmrc', () => {
   } finally { rmSync(dir, { recursive: true, force: true }); }
 });
 
+// ---- resolveNpmToken (task 1002754) ----------------------------------------
+// The install-time credential resolver that removes the hand-exported-NPM_TOKEN
+// deploy step: env wins, else the user-level ~/.npmrc's LITERAL token; env-fed
+// `${…}` values in the user file are the trap, never a credential.
+test('resolveNpmToken: env NPM_TOKEN wins over everything', () => {
+  const home = mkdtempSync(join(tmpdir(), 'npmrc-home-'));
+  try {
+    writeFileSync(join(home, '.npmrc'), '//registry.npmjs.org/:_authToken=npm_userlevel\n');
+    const r = n.resolveNpmToken({ env: { NPM_TOKEN: ' npm_fromenv ' }, homedir: home });
+    assert.deepEqual(r, { token: 'npm_fromenv', source: 'env' });
+  } finally { rmSync(home, { recursive: true, force: true }); }
+});
+
+test('resolveNpmToken: falls back to the user-level ~/.npmrc literal token', () => {
+  const home = mkdtempSync(join(tmpdir(), 'npmrc-home-'));
+  try {
+    writeFileSync(join(home, '.npmrc'),
+      'registry=https://registry.npmjs.org/\n//registry.npmjs.org/:_authToken=npm_ABC123\nfund=false\n');
+    const r = n.resolveNpmToken({ env: {}, homedir: home });
+    assert.deepEqual(r, { token: 'npm_ABC123', source: 'user-npmrc' });
+  } finally { rmSync(home, { recursive: true, force: true }); }
+});
+
+test('resolveNpmToken: an env-fed ${…} value in the user file is the trap, not a credential', () => {
+  const home = mkdtempSync(join(tmpdir(), 'npmrc-home-'));
+  try {
+    writeFileSync(join(home, '.npmrc'), '//registry.npmjs.org/:_authToken=${NPM_TOKEN}\n');
+    const r = n.resolveNpmToken({ env: {}, homedir: home });
+    assert.deepEqual(r, { token: null, source: null });
+  } finally { rmSync(home, { recursive: true, force: true }); }
+});
+
+test('resolveNpmToken: a token for a DIFFERENT host is not borrowed', () => {
+  const home = mkdtempSync(join(tmpdir(), 'npmrc-home-'));
+  try {
+    writeFileSync(join(home, '.npmrc'), '//npm.pkg.github.com/:_authToken=ghp_other\n');
+    const r = n.resolveNpmToken({ env: {}, homedir: home });
+    assert.deepEqual(r, { token: null, source: null });
+  } finally { rmSync(home, { recursive: true, force: true }); }
+});
+
+test('resolveNpmToken: no user npmrc at all → null, never a throw', () => {
+  const home = mkdtempSync(join(tmpdir(), 'npmrc-home-'));
+  try {
+    const r = n.resolveNpmToken({ env: {}, homedir: home });
+    assert.deepEqual(r, { token: null, source: null });
+  } finally { rmSync(home, { recursive: true, force: true }); }
+});
+
 console.log('');
 console.log(`npmrc tests: ${passed} passed, ${failed} failed`);
 process.exit(failed ? 1 : 0);

package/tests/skill_preflight.mjs

@@ -0,0 +1,251 @@
+// tests/skill_preflight.mjs — G03, task 1003167, goal 1000077, criterion
+// guards-skill-declares-machine.
+//
+// THE INCIDENT. /merge-mode states in its own prose that it assumes the Archon's
+// Mac or the droplet. It was run on a dev box anyway — and ship.js ALREADY knew,
+// because strandNextStep() tells a box "/merge-mode is NOT available here". The
+// knowledge existed in two places and neither stopped the run: prose cannot
+// refuse, and the one executable copy sat on a different code path.
+//
+// So these tests care about two things: that the preflight actually REFUSES, and
+// that the scan behind the fitness check does not cry wolf. Both false-positive
+// classes below were real defects in my own first drafts.
+import { strict as assert } from 'node:assert';
+import { test } from 'node:test';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const sp = require('../scripts/gds/skill-preflight.js');
+
+// ---- the declaration ------------------------------------------------------
+test('parseRequires reads the inline form', () => {
+  const r = sp.parseRequires('---\nname: x\nrequires: [gh, main-checkout]\n---\nbody');
+  assert.deepEqual(r.requires, ['gh', 'main-checkout']);
+  assert.equal(r.declared, true);
+});
+
+test('parseRequires reads the dash-list form', () => {
+  const r = sp.parseRequires('---\nname: x\nrequires:\n  - gh\n  - tty\n---\nbody');
+  assert.deepEqual(r.requires, ['gh', 'tty']);
+});
+
+test('no requires: is "declared nothing", NOT "declared an empty list"', () => {
+  // The fitness check needs to tell those apart.
+  const r = sp.parseRequires('---\nname: x\n---\nbody');
+  assert.equal(r.declared, false);
+  assert.deepEqual(r.requires, []);
+});
+
+test('a malformed requires: is an ERROR, not silently zero requirements', () => {
+  // Reporting zero would read as "declared, needs nothing" — a scan that finds
+  // nothing must never be indistinguishable from a clean pass.
+  const r = sp.parseRequires('---\nname: x\nrequires: gh\n---\nbody');
+  assert.ok(r.error, 'a scalar requires: must be flagged');
+  assert.equal(r.declared, true);
+});
+
+// ---- the scan must not cry wolf -------------------------------------------
+test('PROSE that names a command is not an instruction to run it', () => {
+  // dev/SKILL.md FORBIDS `git push origin main`. An earlier draft flagged it for
+  // saying so — the scan read code spans and prose alike.
+  const md = '---\nname: dev\n---\n- never run raw `git push origin main` or `~/deploy.sh`; that is Bongos\'s job.\n';
+  assert.deepEqual(sp.inferRequired(md), [], 'a prohibition must not imply a requirement');
+});
+
+test('a FENCED command is an instruction, and is picked up', () => {
+  const md = '---\nname: x\n---\n```bash\nnode scripts/gds/push-main.js\n```\n';
+  assert.deepEqual(sp.inferRequired(md), ['push-credential']);
+});
+
+test('a shell COMMENT inside a fence is discussion, not an instruction', () => {
+  const md = '---\nname: x\n---\n```bash\n# node scripts/gds/push-main.js is the sanctioned push\necho hi\n```\n';
+  assert.deepEqual(sp.inferRequired(md), []);
+});
+
+test('"through" does not match the gh signal', () => {
+  // `gh ` is a substring of "throu(gh )". The first draft flagged
+  // priority-session for a comment containing the word "through".
+  // NOT in a comment: comment-stripping would remove it and the boundary would
+  // never be exercised. The first version of this test made exactly that mistake
+  // and stayed green when the boundary was deleted.
+  const md = '---\nname: x\n---\n```bash\necho "routed through the gateway"\n```\n';
+  assert.deepEqual(sp.inferRequired(md), [], 'a word containing "gh " is not the gh CLI');
+  const inComment = '---\nname: x\n---\n```bash\n# API through it rather than re-deriving the token\necho ok\n```\n';
+  assert.deepEqual(sp.inferRequired(inComment), [], 'and a comment is discussion regardless');
+  const real = '---\nname: y\n---\n```bash\ngh pr view 12 --json state\n```\n';
+  assert.deepEqual(sp.inferRequired(real), ['gh'], 'the real gh command still matches');
+});
+
+test('ssh and the deploy host both imply droplet-ssh', () => {
+  for (const cmd of ['ssh -o ConnectTimeout=10 someone@host "~/deploy.sh"', 'ssh someone@host "psql -d x"']) {
+    assert.deepEqual(sp.inferRequired(`---\nname: x\n---\n\`\`\`bash\n${cmd}\n\`\`\`\n`), ['droplet-ssh'], cmd);
+  }
+});
+
+// ---- the refusal ----------------------------------------------------------
+const caps = {
+  present: { what: 'a present thing', probe: () => true, missing: 'absent' },
+  absent: { what: 'an absent thing', probe: () => false, missing: 'go get it' },
+  unknowable: { what: 'an unprovable thing', probe: () => null, missing: 'unreachable' },
+  thrower: { what: 'a probe that dies', probe: () => { throw new Error('boom'); }, missing: 'never printed' },
+};
+
+test('a FALSE probe refuses, and names the remedy', () => {
+  const r = sp.preflight(['present', 'absent'], caps);
+  assert.equal(r.ok, false);
+  assert.equal(r.missing.length, 1);
+  assert.equal(r.missing[0].name, 'absent');
+  assert.match(r.missing[0].why, /go get it/);
+});
+
+test('the refusal names ONLY what is missing, not the whole list', () => {
+  // The task's wording: name the MISSING capability, not the list. A satisfied
+  // capability must not appear in `missing`.
+  const r = sp.preflight(['present', 'absent'], caps);
+  assert.ok(!r.missing.some((m) => m.name === 'present'));
+});
+
+test('a NULL probe warns and does NOT block', () => {
+  // Refusing on "could not tell" would block legitimate machines; passing it
+  // silently would rebuild the hole. So: warn, proceed.
+  const r = sp.preflight(['unknowable'], caps);
+  assert.equal(r.ok, true, 'unknown must not refuse');
+  assert.equal(r.unknown.length, 1);
+});
+
+test('a probe that THROWS degrades to unknown, never to a pass-as-satisfied', () => {
+  const r = sp.preflight(['thrower'], caps);
+  assert.equal(r.unknown.length, 1);
+  assert.equal(r.missing.length, 0);
+});
+
+test('an undeclared capability name is caught rather than ignored', () => {
+  // A typo in a skill's requires: would otherwise be a silent no-op.
+  const r = sp.preflight(['no-such-capability'], caps);
+  assert.equal(r.ok, false);
+  assert.match(r.missing[0].why, /unknown capability/);
+});
+
+// ---- the live tree --------------------------------------------------------
+test('every registry capability has a probe and a remedy sentence', () => {
+  for (const [name, cap] of Object.entries(sp.CAPABILITIES)) {
+    assert.equal(typeof cap.probe, 'function', `${name} needs a probe`);
+    assert.ok(cap.what && cap.missing, `${name} needs what/missing text`);
+    assert.ok(cap.missing.length > 40, `${name}'s remedy must be actionable, not a label`);
+  }
+});
+
+test('the live tree passes the declare-check', () => {
+  const r = sp.checkOpsSkillsDeclareMachine();
+  assert.equal(r.hardFail, false, `unexpected:\n  ${r.violations.join('\n  ')}`);
+});
+
+test('merge-mode really declares the machine it needs', () => {
+  // The skill at the centre of the incident.
+  const r = sp.preflightSkill('merge-mode', caps);
+  assert.ok(r.requires.includes('main-checkout'));
+  assert.ok(r.requires.includes('push-credential'));
+});
+
+test('an UNDECLARED fenced ops command is caught', () => {
+  // Injected names, so this exercises the real comparison rather than
+  // short-circuiting on an empty enumeration — the first version of this test
+  // passed a bad dir and therefore proved nothing about the undeclared path.
+  const r = sp.checkOpsSkillsDeclareMachine({
+    names: ['rogue'],
+    read: () => '---\nname: rogue\n---\n```bash\nnode scripts/gds/push-main.js\nssh me@host "~/deploy.sh"\n```\n',
+  });
+  assert.equal(r.hardFail, true, 'a skill fencing a main-push with no declaration must fail');
+  const text = r.violations.join('\n');
+  assert.match(text, /push-credential/);
+  assert.match(text, /droplet-ssh/);
+  assert.match(text, /requires:/, 'the violation must name the remedy');
+});
+
+test('a skill that DOES declare its fenced commands passes', () => {
+  const r = sp.checkOpsSkillsDeclareMachine({
+    names: ['good'],
+    read: () => '---\nname: good\nrequires: [push-credential]\n---\n```bash\nnode scripts/gds/skill-preflight.js good\nnode scripts/gds/push-main.js\n```\n',
+  });
+  assert.equal(r.hardFail, false, r.violations.join('\n'));
+});
+
+test('declaring MORE than the fences imply is allowed', () => {
+  // A human knows things the scan cannot see; punishing over-declaration would
+  // train people to declare less.
+  const r = sp.checkOpsSkillsDeclareMachine({
+    names: ['careful'],
+    read: () => '---\nname: careful\nrequires: [gh, tty, main-checkout]\n---\nRun `node scripts/gds/skill-preflight.js careful` first.\n',
+  });
+  assert.equal(r.hardFail, false, r.violations.join('\n'));
+});
+
+test('a declared capability that is not in the registry is caught', () => {
+  const r = sp.checkOpsSkillsDeclareMachine({
+    names: ['typo'],
+    read: () => '---\nname: typo\nrequires: [man-checkout]\n---\nbody\n',
+  });
+  assert.equal(r.hardFail, true);
+  assert.match(r.violations.join('\n'), /unknown capability "man-checkout"/);
+});
+
+test('an empty skills dir FAILS rather than reporting all-clear', () => {
+  const r = sp.checkOpsSkillsDeclareMachine({ dir: '/definitely/not/here' });
+  assert.equal(r.hardFail, true);
+  assert.match(r.violations[0], /scan defect/);
+});
+
+// ---- the three findings from the first grader pass ------------------------
+test('ghAuthed is memoized — one preflight must not spawn `gh` twice', () => {
+  // merge-mode declares BOTH gh and push-credential, and push-credential's probe
+  // also consults gh. Unmemoized that was two 15s-timeout subprocesses in one
+  // run, and a preflight slow enough to skip is one nobody runs.
+  const a = sp.ghAuthed();
+  const b = sp.ghAuthed();
+  assert.equal(a, b, 'repeat calls must agree');
+  assert.equal(typeof a, 'boolean');
+});
+
+test('a skill name must be a single path segment', () => {
+  // `skill-preflight.js ../../../etc` must not read outside .claude/skills.
+  for (const bad of ['../../../etc', '..', '.', 'a/b', '', 'x/../../y']) {
+    assert.equal(sp.skillPath(bad), null, `${JSON.stringify(bad)} must be refused`);
+  }
+  assert.ok(String(sp.skillPath('merge-mode')).endsWith('merge-mode/SKILL.md'.replace('/', require('node:path').sep)));
+});
+
+test('a traversal name is refused with a message, not a crash', () => {
+  const r = sp.preflightSkill('../../../etc');
+  assert.equal(r.ok, false);
+  assert.match(r.missing[0].why, /not a skill name/);
+});
+
+test('DECLARING without ENFORCING is caught', () => {
+  // The gap the grader found in planning-session: a `requires:` with no
+  // preflight call is a contract stated where nothing checks it — the same
+  // shape as the original bug.
+  const r = sp.checkOpsSkillsDeclareMachine({
+    names: ['claims-but-never-checks'],
+    read: () => '---\nname: x\nrequires: [gh]\n---\nprose only, no preflight call\n',
+  });
+  assert.equal(r.hardFail, true);
+  assert.match(r.violations.join('\n'), /never runs/);
+});
+
+test('invoking the preflight anywhere satisfies enforcement — top OR at the step', () => {
+  // merge-mode gates at Step 0 (capabilities are preconditions for the whole
+  // procedure); planning-session gates at the one step that needs ssh. Both are
+  // legitimate, so the check must not demand a particular position.
+  const md = '---\nname: x\nrequires: [gh]\n---\nlater on:\n```bash\nnode scripts/gds/skill-preflight.js x\ngh pr view 1 --json state\n```\n';
+  const r = sp.checkOpsSkillsDeclareMachine({ names: ['x'], read: () => md });
+  assert.equal(r.hardFail, false, r.violations.join('\n'));
+});
+
+test('both live declaring skills actually invoke the preflight', () => {
+  const r = sp.checkOpsSkillsDeclareMachine();
+  assert.equal(r.hardFail, false, r.violations.join('\n'));
+  for (const name of ['merge-mode', 'planning-session']) {
+    const md = require('node:fs').readFileSync(sp.skillPath(name), 'utf8');
+    assert.match(md, /skill-preflight\.js\s+\S/, `${name} must run its own preflight`);
+  }
+});