@bongos/core 1.19.315 → 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.315",
-  "core_contract": "1.19.315",
-  "source_commit": "fa29b8da2f1429be8b46153157348ad0893bb702",
+  "core_version": "1.19.316",
+  "core_contract": "1.19.316",
+  "source_commit": "8248fac14dda1af6df3a5414027a4bf9d6ba23e0",
   "source_ref": "HEAD",
-  "built_at": "2026-08-23T21:55:22.014Z",
+  "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": "194e6d23ae1dc848c9e95e48b8383a33a401686fe98169758b9084884818966b",
+  "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",
@@ -4582,12 +4582,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "501134bb188ffffca60077b5b43b4e068e5713ff2c35002380cddad4a86076b4"
+      "sha256": "6c10d47c4db2e1e159b3c4aad631491bf7818c3a89fbf3f02bc1de512b1163b3"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "4e8358d26d8d6cdd6c5378b0860ebc58671a75d40ad790bb896000e91f9bd0c7"
+      "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",
@@ -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",
@@ -6257,7 +6262,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "ce9693c479994dbf2f113c783048cd9b3dca8c3cdbc14c655ffdc0f893227eb3"
+      "sha256": "049a62ecc239e85005e2f79fea63f46edf406b53eb2b4c36e21e81281365afc7"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -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/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.315",
+  "version": "1.19.316",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@bongos/core",
-      "version": "1.19.315",
+      "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.315",
+  "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/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/src/module-api.js

@@ -1057,8 +1057,10 @@ const { validateOrRespond, LIMITS, parseId, asyncHandler, corsPublicGet, parsePa
 //         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.315'; // 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/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`);
+  }
+});