heyspex 0.1.0 → 0.2.0

package/scripts/hs-gateway.mjs

@@ -0,0 +1,115 @@
+#!/usr/bin/env node
+// hs-gateway.mjs — `hs gateway <command>` face of the user-customizable
+// gateway (HS-WEC3; design: specs/research/HS-P861-G9JR-RES-*).
+//
+//   hs gateway validate [slug] [--json]   validate user skills + scope coverage
+//   hs gateway register …                 blocked on HS-DCCP (prints why, exit 2)
+//
+// Validation is read-only and report-only: it never edits, deletes, or
+// auto-disables user content, and never rewrites a scope declaration.
+
+import path from 'node:path';
+import process from 'node:process';
+
+import { buildGatewayReport, USER_SKILLS_REL } from './gateway-skills-lib.mjs';
+
+const BLOCKED_COMMANDS = new Set(['register', 'rotate-credentials', 'disable', 'unregister', 'list']);
+
+function usage() {
+  process.stderr.write(
+    [
+      'Usage: hs gateway <command>',
+      '',
+      '  validate [slug] [--json]   Validate user-authored skill files under',
+      `                             ${USER_SKILLS_REL}${path.sep}<slug>${path.sep}SKILL.md and report`,
+      '                             skills whose declared scope no registered server provides.',
+      '  register | rotate-credentials | disable | unregister | list',
+      '                             Not available yet — server registration lands with',
+      '                             HS-DCCP-EPIC-thin-project-scoped-mcp-connector.',
+      '',
+    ].join('\n'),
+  );
+}
+
+function renderHuman(report, { slugFilter }) {
+  const lines = [];
+  const { skills, registry, orphans } = report;
+  if (!skills.exists) {
+    lines.push(`No user skills — ${USER_SKILLS_REL} does not exist yet.`);
+    lines.push(`Author one at ${path.join(USER_SKILLS_REL, '<slug>', 'SKILL.md')} (see the README there or the HS-P861 research doc for the frontmatter format).`);
+    return { text: lines.join('\n'), exitCode: 0 };
+  }
+
+  const shown = slugFilter ? skills.skills.filter((s) => s.slug === slugFilter) : skills.skills;
+  if (slugFilter && shown.length === 0) {
+    return { text: `No user skill named "${slugFilter}" under ${skills.root}.`, exitCode: 1 };
+  }
+
+  for (const s of shown) {
+    const flag = s.ok ? (s.warnings.length ? 'warn' : ' ok ') : 'FAIL';
+    lines.push(`[${flag}] ${s.slug}  (${s.relPath})`);
+    for (const e of s.errors) lines.push(`         error: ${e.message}`);
+    for (const w of s.warnings) lines.push(`         warning: ${w.message}`);
+  }
+  for (const m of skills.misplaced) lines.push(`[warn] ${m.name} — ${m.reason}`);
+
+  lines.push('');
+  if (!registry.available) lines.push(`Server registry: not yet available — ${registry.reason ?? report.orphans.registry_reason ?? ''}`.trimEnd());
+  const orphanList = slugFilter ? orphans.orphans.filter((o) => o.slug === slugFilter) : orphans.orphans;
+  if (orphanList.length) {
+    lines.push(`Scope coverage: ${orphanList.length} skill(s) declare a scope no registered server provides (they stay inert until fixed):`);
+    for (const o of orphanList) lines.push(`  - ${o.slug}: ${o.missing.join(', ')}`);
+  } else {
+    lines.push('Scope coverage: no orphaned scope declarations.');
+  }
+
+  const invalidShown = shown.filter((s) => !s.ok).length;
+  lines.push('');
+  lines.push(`${shown.length} skill(s) checked · ${invalidShown} invalid · ${orphanList.length} orphaned`);
+  return { text: lines.join('\n'), exitCode: invalidShown > 0 ? 1 : 0 };
+}
+
+async function main(argv) {
+  const command = argv[0];
+  if (!command || command === '--help' || command === '-h') {
+    usage();
+    return command ? 0 : 2;
+  }
+
+  if (BLOCKED_COMMANDS.has(command)) {
+    process.stderr.write(
+      `hs gateway ${command}: not available yet — user MCP server registration (registration table, encrypted credentials, live probe) lands with HS-DCCP-EPIC-thin-project-scoped-mcp-connector, which is still open. Skill validation works today: hs gateway validate\n`,
+    );
+    return 2;
+  }
+
+  if (command !== 'validate') {
+    process.stderr.write(`hs gateway: unknown command "${command}"\n\n`);
+    usage();
+    return 2;
+  }
+
+  const rest = argv.slice(1);
+  const json = rest.includes('--json');
+  const slugFilter = rest.find((a) => !a.startsWith('--')) ?? null;
+  const vaultRoot = process.env.HS_VAULT_ROOT ? path.resolve(process.env.HS_VAULT_ROOT) : process.cwd();
+
+  const report = buildGatewayReport(vaultRoot);
+  if (json) {
+    const filtered = slugFilter
+      ? {
+          ...report,
+          skills: { ...report.skills, skills: report.skills.skills.filter((s) => s.slug === slugFilter) },
+          orphans: { ...report.orphans, orphans: report.orphans.orphans.filter((o) => o.slug === slugFilter) },
+        }
+      : report;
+    process.stdout.write(`${JSON.stringify(filtered, null, 2)}\n`);
+    return filtered.skills.skills.some((s) => !s.ok) ? 1 : 0;
+  }
+
+  const { text, exitCode } = renderHuman(report, { slugFilter });
+  process.stdout.write(`${text}\n`);
+  return exitCode;
+}
+
+process.exit(await main(process.argv.slice(2)));

package/scripts/hs-mode.mjs

@@ -0,0 +1,125 @@
+#!/usr/bin/env node
+// hs-mode.mjs — CLI for the HeySpex master on/off switch.
+//
+//   hs mode            → status
+//   hs mode status     → what is on, what is off, and why
+//   hs mode on|off     → flip the whole layer
+//   hs mode toggle     → flip to the opposite of the current mode
+//
+// Flags: --json (machine-readable), --quiet (exit code only).
+// Exit codes: 0 ok · 1 usage · 2 flip failed.
+
+import { REPO_ROOT, resolveMode, setMode, mcpEnabled, claudeMdStubbed } from './heyspex-mode.mjs';
+
+const argv = process.argv.slice(2).filter((a) => a !== 'mode');
+const flags = new Set(argv.filter((a) => a.startsWith('--')));
+const verb = argv.find((a) => !a.startsWith('--')) ?? 'status';
+const JSON_OUT = flags.has('--json');
+const QUIET = flags.has('--quiet');
+
+const say = (s = '') => { if (!QUIET && !JSON_OUT) console.log(s); };
+
+function statusReport() {
+  const { mode, source, overriddenByEnv, persisted, state } = resolveMode(REPO_ROOT);
+  return {
+    mode,
+    source,
+    overriddenByEnv,
+    persisted,
+    changedAt: state?.changedAt ?? null,
+    surfaces: {
+      hooks: mode === 'on' ? 'live' : 'silenced',
+      mcp: mcpEnabled(REPO_ROOT) ? 'enabled' : 'disabled',
+      statusline: mode === 'on' ? 'live' : 'blank',
+      claudeMd: claudeMdStubbed(REPO_ROOT) ? 'stubbed' : 'full agent contract',
+    },
+  };
+}
+
+function printStatus(r) {
+  const badge = r.mode === 'on' ? 'ON' : 'OFF';
+  say(`HeySpex is ${badge}  (from ${r.source})`);
+  say('');
+  say(`  hooks       ${r.surfaces.hooks}`);
+  say(`  MCP server  ${r.surfaces.mcp}`);
+  say(`  statusline  ${r.surfaces.statusline}`);
+  say(`  CLAUDE.md   ${r.surfaces.claudeMd}`);
+  if (r.changedAt) say(`\n  last changed ${r.changedAt}`);
+  if (r.overriddenByEnv) {
+    say('');
+    say(`  ! HEYSPEX_MODE is set in this shell and overrides the saved mode`);
+    say(`    (saved: ${r.persisted}). Unset it to go back to the saved value.`);
+  }
+  // A mismatch here means Claude Code was never restarted after the flip.
+  const mcpShouldBe = r.mode === 'on' ? 'enabled' : 'disabled';
+  if (r.surfaces.mcp !== mcpShouldBe) {
+    say(`\n  ! MCP server is ${r.surfaces.mcp} but mode is ${r.mode} — rerun \`hs mode ${r.mode}\`.`);
+  }
+}
+
+if (flags.has('--help') || flags.has('-h')) {
+  console.log(`hs mode — turn the HeySpex agent layer on or off
+
+Usage:
+  hs mode [status]        Show what is on, what is off, and why
+  hs mode on              Turn HeySpex on  (hooks, MCP, statusline, agent contract)
+  hs mode off             Turn HeySpex off (this repo behaves like a plain codebase)
+  hs mode toggle          Flip to the opposite mode
+
+Flags:
+  --force                 With \`on\`: restore CLAUDE.md even if you edited it
+                          while HeySpex was off (your version is overwritten;
+                          the real contract is at .heyspex/mode-backup/).
+  --json                  Machine-readable output
+  --quiet                 Exit code only
+  --help, -h              This help
+
+Both \`on\` and \`off\` require restarting Claude Code: the MCP server and
+CLAUDE.md are read once at startup. Hooks and the statusline take effect
+immediately.
+
+Per-shell override without touching saved state:
+  HEYSPEX_MODE=off claude        # off for this session only
+`);
+  process.exit(0);
+}
+
+if (verb === 'status') {
+  const r = statusReport();
+  if (JSON_OUT) console.log(JSON.stringify(r, null, 2));
+  else printStatus(r);
+  process.exit(0);
+}
+
+let target = verb;
+if (verb === 'toggle') target = resolveMode(REPO_ROOT).mode === 'on' ? 'off' : 'on';
+
+if (target !== 'on' && target !== 'off') {
+  process.stderr.write(`hs mode: expected \`on\`, \`off\`, \`toggle\`, or \`status\` (got \`${verb}\`)\n`);
+  process.exit(1);
+}
+
+const before = resolveMode(REPO_ROOT).mode;
+const result = setMode(target, { repoRoot: REPO_ROOT, force: flags.has('--force') });
+
+if (!result.ok) {
+  if (JSON_OUT) console.log(JSON.stringify(result, null, 2));
+  else process.stderr.write(`hs mode: could not turn HeySpex ${target} — ${result.error}\n`);
+  process.exit(2);
+}
+
+if (JSON_OUT) {
+  console.log(JSON.stringify({ ...result, previous: before, ...statusReport() }, null, 2));
+  process.exit(0);
+}
+
+say(before === target ? `HeySpex was already ${target} — reapplied.` : `HeySpex is now ${target.toUpperCase()}.`);
+say('');
+for (const step of result.steps) say(`  ${step.surface.padEnd(12)} ${step.action}${step.reason ? ` (${step.reason})` : ''}`);
+say('');
+say('  Restart Claude Code for the MCP server and CLAUDE.md to take effect.');
+if (target === 'off') {
+  say('  Turn it back on any time with:  npm run heyspex:on');
+} else {
+  say('  Verify the whole setup with:    npm run doctor');
+}

package/scripts/hs-next.mjs

@@ -0,0 +1,441 @@
+#!/usr/bin/env node
+/**
+ * hs next — on-deck resolver CLI fallback ([[HS-TASK-ISK7]]).
+ * Dispatched from bin/hs.mjs. One call, no MCP required.
+ */
+import process from 'node:process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+import readline from 'node:readline/promises';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import {
+  isRunFrontToken,
+  normalizeRunFrontToken,
+  runFrontCliHint,
+} from '../vendor/heyspex-mcp/run-front.mjs';
+import { normalizeBareSpecIdToken } from '../vendor/heyspex-mcp/spec-id-lib.mjs';
+import { resolveCodeRoot } from './lib/shared-path-helpers.mjs';
+
+process.env.HEYSPEX_DISABLE_STDIO_BOOTSTRAP = '1';
+
+// This script's own install location — vendor/heyspex-mcp/cli.mjs is CODE,
+// not vault content, so it must resolve against the code checkout, not
+// HS_VAULT_ROOT. Since the repo split, HS_VAULT_ROOT can point at a vault-only
+// checkout (e.g. heyspex-specs) with no vendor/ at all
+// ([[HS-1LCC-4XKS-DIAG-frozen-checks-run-against-the-vault]]).
+const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+
+const HELP = `hs next — resolve the on-deck /hs-next brief
+
+Usage:
+  hs next [front] [spec_id] [--summary] [--json] [--text] [--ignore-focus] [--include-horizon]
+  hs next --help
+
+Spec id (optional):
+  A bare key works everywhere a full id does: hs next CJV2 == hs next HS-CJV2.
+
+Front (optional — the default is whatever 'hs next front' last set; handheld until then):
+  handheld                 Handheld: drive one on-deck task, you in the loop
+  assist | assisted          Assisted: arm a dispatcher run on the milestone, you on the loop
+  auto | autonomous          Autonomous: arm an unattended dispatcher run on the milestone
+
+Flags:
+  --summary          Lightweight claim banner only (default: on)
+  --no-summary       Full execution brief (post-claim shape)
+  --json             Machine-readable JSON on stdout
+  --text             Print user_prompt_markdown only (default when not --json)
+  --ignore-focus     Skip focus pin / manifest focus override
+  --include-horizon  Include horizon backlog when queue is empty
+  --roadmap <id>     Roadmap id (default: HS-ROADMAP-PRODUCT)
+  --front <name>     Explicit front (${runFrontCliHint()})
+
+At a terminal, a claim-ready brief ends with a real y/N question: answer y
+(or yes / proceed / confirm) to claim the spec and launch an agent on it
+(same as: hs next <id> --launch --claim). Piped or --json output never
+prompts; it prints that command instead. HS_NEXT_NO_PROMPT=1 disables the
+question.
+
+Under an assist/auto front the terminal question is "Arm the run?" instead:
+yes arms it (same as: hs next assist|auto <HS-MIL…> --launch), which writes
+the queue + front files the running dispatcher reads — no terminal opens. An
+epic or task id arms its parent milestone, because the dispatcher runs at
+milestone grain.
+
+Examples:
+  hs next HS-EPIC-YQ5A --summary --json
+  hs next CJV2                      (same as: hs next HS-CJV2)
+  hs next auto HS-EPIC-YQ5A --summary --json
+  hs next assist HS-MIL-DECK --text
+
+Launch + per-kind defaults (needs the console): this help covers the brief
+resolver only. hs next <id> --launch, hs next model|permission-mode [kind]
+[value] and hs next claim [on|off] are handled by the console half - run
+  hs next --launch --help
+for that help.
+`;
+
+export const EXIT = {
+  OK: 0,
+  USAGE: 1,
+  RESOLVE_FAILED: 2,
+};
+
+/** @param {string[]} argv tokens after "next" */
+/** Replies that mean "yes, claim it" at the terminal prompt (case-insensitive). */
+export const CLAIM_CONFIRM_TOKENS = new Set(['y', 'yes', 'proceed', 'confirm']);
+
+const AGENT_CLAIM_LINE =
+  /^Ready to claim \*\*.+?\*\* `[^`]+` to \*\*.+?\*\*(?:, as \*\*[^*]*\*\*)?\. Type `proceed`.*$/m;
+
+/**
+ * The on-deck brief's last line is written for an agent sitting in a chat
+ * ("Type `proceed` ... to claim it and begin"). At a shell nothing listens
+ * for that reply — typing `yes` into PowerShell runs a command named `yes`.
+ * Rewrite the line for a terminal: keep "Ready to claim ... to <intent>",
+ * drop the agent-identity clause (no agent is attached yet), and say what
+ * actually claims it from here. Returns the markdown unchanged when the
+ * brief is not a claim question.
+ */
+export function renderTerminalClaimPrompt(md, result, { interactive = false } = {}) {
+  const claimId = result?.claim_target?.spec_id;
+  if (result?.agent_dispatch?.phase !== 'claim_authorization' || !claimId) return md;
+  const m = AGENT_CLAIM_LINE.exec(md);
+  if (!m) return md;
+  const head = m[0]
+    .replace(/, as \*\*[^*]*\*\*\./, '.')
+    .replace(/\. Type `proceed`.*$/, '.');
+  const launchCmd = `hs next ${claimId} --launch --claim`;
+  const line = interactive
+    ? head
+    : `${head}\nTo claim it and launch an agent on it: \`${launchCmd}\``;
+  return md.replace(m[0], line);
+}
+
+/** Ask at the terminal whether to claim + launch. Resolves to true on a yes-token. */
+async function askClaimAtTerminal(claimId) {
+  return askYesNoAtTerminal(`Claim ${claimId} and launch an agent on it now? [y/N] `);
+}
+
+/** One y/N question at the terminal. Resolves to true on a yes-token. */
+async function askYesNoAtTerminal(question) {
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    const answer = await rl.question(question);
+    return CLAIM_CONFIRM_TOKENS.has(answer.trim().toLowerCase());
+  } finally {
+    rl.close();
+  }
+}
+
+/** Hand off to the console half of `hs next` (POST /api/agent/start); exits with its code. */
+function launchClaimedSpec(claimId) {
+  spawnHsNext([claimId, '--launch', '--claim']);
+}
+
+/** Run `hs next <args…>` through the console half and exit with its code. */
+function spawnHsNext(nextArgs) {
+  const hsBin = path.join(PACKAGE_ROOT, 'bin', 'hs.mjs');
+  const child = spawn(process.execPath, [hsBin, 'next', ...nextArgs], {
+    cwd: PACKAGE_ROOT,
+    stdio: 'inherit',
+    env: process.env,
+  });
+  child.on('exit', (code, signal) => process.exit(signal ? 1 : (code ?? 0)));
+  child.on('error', (err) => {
+    process.stderr.write(`hs next: failed to launch: ${err.message}\n`);
+    process.exit(EXIT.RESOLVE_FAILED);
+  });
+}
+
+/**
+ * The stored default front — `launchModels.defaultRunMode` in
+ * `spex-console/settings.json`, the file `hs next front <name>` and the
+ * console's Pin & Launch modal both write. Read straight off disk so a bare
+ * `hs next <id>` needs no console. Null when unset or unreadable (caller
+ * keeps handheld).
+ * @param {string} codeRoot
+ * @returns {import('../vendor/heyspex-mcp/run-front.mjs').RunFront | null}
+ */
+export function readDefaultRunFront(...roots) {
+  // The console keeps settings.json under its ACTIVE VAULT root (repoRoot() is
+  // the vault checkout), so the vault root is tried first; the code checkout
+  // is the pre-split location and stays as the fallback.
+  for (const root of roots) {
+    if (!root) continue;
+    try {
+      const raw = fs.readFileSync(path.join(root, 'spex-console', 'settings.json'), 'utf8');
+      const parsed = JSON.parse(raw);
+      const front = normalizeRunFrontToken(parsed?.launchModels?.defaultRunMode);
+      if (front) return front;
+    } catch {
+      // try the next root
+    }
+  }
+  return null;
+}
+
+/** `assist` / `auto` — the word the CLI takes for a run front. */
+export function frontWord(front) {
+  return front === 'autonomous' ? 'auto' : 'assist';
+}
+
+/**
+ * Under a run front (assisted / autonomous) the brief is not a one-task claim
+ * question — the unit the dispatcher takes is a MILESTONE. Resolve which one:
+ * the id itself when it is a milestone, else the top of the claim target's
+ * breadcrumb (an epic or task arms its parent milestone). Null under handheld
+ * or when no milestone can be named.
+ * @param {Record<string, any> | null | undefined} result
+ * @param {string} front
+ * @returns {{ milestoneId: string, from: 'milestone' | 'epic' | 'task', specId: string } | null}
+ */
+export function resolveArmTarget(result, front) {
+  if (!result || (front !== 'assisted' && front !== 'autonomous')) return null;
+  const specPath = String(result.spec_path || '').replace(/\\/g, '/');
+  const specId = result.spec_id ? String(result.spec_id) : '';
+  if (specId && /(^|\/)milestones\//.test(specPath)) {
+    return { milestoneId: specId, from: 'milestone', specId };
+  }
+  const crumb = result.claim_target?.hierarchy_breadcrumb;
+  const top = Array.isArray(crumb) && crumb.length > 1 ? String(crumb[0]) : '';
+  if (!top) return null;
+  const from = /(^|\/)epics\//.test(specPath) ? 'epic' : 'task';
+  return { milestoneId: top, from, specId: specId || String(result.claim_target?.spec_id || '') };
+}
+
+/** The console-half command that arms the run for `target`. */
+export function armCommand(target, front) {
+  return `hs next ${frontWord(front)} ${target.milestoneId} --launch`;
+}
+
+/** Terminal-facing lines that replace the one-task claim question under a run front. */
+export function renderArmLines(target, front) {
+  const lines = ['', '---', ''];
+  if (target.from !== 'milestone') {
+    lines.push(
+      `${front} runs arm at milestone grain — ${target.specId} sits under milestone ${target.milestoneId}, so that whole milestone is what gets queued.`,
+    );
+  }
+  lines.push(`To arm the ${front} run: \`${armCommand(target, front)}\``);
+  return lines.join('\n');
+}
+
+export function parseNextArgs(argv) {
+  let specId;
+  let roadmapId;
+  /** @type {import('../vendor/heyspex-mcp/run-front.mjs').RunFront} */
+  let front = 'handheld';
+  let frontExplicit = false;
+  let summary = true;
+  let json = false;
+  let text = false;
+  let ignoreFocus = false;
+  let includeHorizon = false;
+
+  for (let i = 0; i < argv.length; i += 1) {
+    const a = argv[i];
+    if (a === '--help' || a === '-h') return { help: true };
+    if (a === '--json') {
+      json = true;
+      continue;
+    }
+    if (a === '--text') {
+      text = true;
+      continue;
+    }
+    if (a === '--summary') {
+      summary = true;
+      continue;
+    }
+    if (a === '--no-summary') {
+      summary = false;
+      continue;
+    }
+    if (a === '--ignore-focus') {
+      ignoreFocus = true;
+      continue;
+    }
+    if (a === '--include-horizon') {
+      includeHorizon = true;
+      continue;
+    }
+    if (a === '--roadmap') {
+      const v = argv[++i];
+      if (!v) return { error: { code: EXIT.USAGE, message: '--roadmap requires a value' } };
+      roadmapId = v;
+      continue;
+    }
+    if (a === '--front') {
+      const v = argv[++i];
+      if (!v) return { error: { code: EXIT.USAGE, message: '--front requires a value' } };
+      const normalized = normalizeRunFrontToken(v);
+      if (!normalized) {
+        return {
+          error: {
+            code: EXIT.USAGE,
+            message: `unknown front: ${v} (expected ${runFrontCliHint()})`,
+          },
+        };
+      }
+      front = normalized;
+      frontExplicit = true;
+      continue;
+    }
+    if (a.startsWith('-')) {
+      return { error: { code: EXIT.USAGE, message: `unknown flag: ${a}` } };
+    }
+    if (isRunFrontToken(a)) {
+      front = normalizeRunFrontToken(a);
+      frontExplicit = true;
+      continue;
+    }
+    // A bare key resolves like a full id: `hs next CJV2` is `hs next HS-CJV2`
+    // (owner ruling 2026-09-01). Only tokens that already failed as a front or
+    // a flag reach here, so this widens what used to be a hard error rather
+    // than changing any input that already worked.
+    if (!specId) {
+      const normalized = normalizeBareSpecIdToken(a);
+      if (normalized) {
+        specId = normalized;
+        continue;
+      }
+    }
+    return { error: { code: EXIT.USAGE, message: `unexpected argument: ${a}` } };
+  }
+
+  return {
+    args: {
+      spec_id: specId,
+      roadmap_id: roadmapId,
+      front,
+      front_explicit: frontExplicit,
+      summary,
+      json,
+      text: text || !json,
+      ignore_focus: ignoreFocus,
+      include_horizon: includeHorizon,
+    },
+  };
+}
+
+async function main() {
+  const parsed = parseNextArgs(process.argv.slice(2));
+  if (parsed.help) {
+    process.stdout.write(`${HELP}\n`);
+    process.exit(EXIT.OK);
+  }
+  if (parsed.error) {
+    process.stderr.write(`hs next: ${parsed.error.message}\n`);
+    process.exit(parsed.error.code);
+  }
+
+  const vaultRoot = process.env.HS_VAULT_ROOT;
+  if (!vaultRoot) {
+    process.stderr.write('hs next: HS_VAULT_ROOT is not set (the dispatcher must pass it).\n');
+    process.exit(EXIT.USAGE);
+  }
+
+  const codeRoot = resolveCodeRoot({ packageRoot: PACKAGE_ROOT });
+  // No front word typed: the stored default (`hs next front <name>`) decides.
+  if (!parsed.args.front_explicit) {
+    const stored = readDefaultRunFront(vaultRoot, codeRoot);
+    if (stored) parsed.args.front = stored;
+  }
+  // resolveNextOnDeckPayload / applyOnDeckHttpAugments / injectCloudWipState
+  // live in on-deck-brief.mjs, not cli.mjs (cli.mjs never re-exports them —
+  // every other caller, e.g. prompts.mjs and claim-tools.mjs, imports them
+  // straight from on-deck-brief.mjs).
+  const onDeckBriefPath = path.join(codeRoot, 'vendor', 'heyspex-mcp', 'on-deck-brief.mjs');
+  const { resolveNextOnDeckAroundActiveClaims, applyOnDeckHttpAugments, injectCloudWipState } =
+    await import(pathToFileURL(onDeckBriefPath).href);
+  const config = {
+    vaultRoot,
+    defaultRoadmapId: process.env.HEYSPEX_ROADMAP_ID || 'HS-ROADMAP-PRODUCT',
+  };
+  const toolArgs = {
+    summary: parsed.args.summary,
+    ignore_focus: parsed.args.ignore_focus,
+    include_horizon: parsed.args.include_horizon,
+    front: parsed.args.front,
+  };
+  if (parsed.args.spec_id) toolArgs.spec_id = parsed.args.spec_id;
+  if (parsed.args.roadmap_id) toolArgs.roadmap_id = parsed.args.roadmap_id;
+
+  // Cloud reliance ([[HS-VOCF]]): the hand-off ledger lives in Neon there, so
+  // pre-fetch it (GET /api/wip via the MCP transport) and let the WIP enricher
+  // surface the row instead of the stale local file. Best-effort — falls back
+  // to the file ledger on any failure.
+  const argsWithCloudWip = await injectCloudWipState(vaultRoot, toolArgs);
+  // Steps past tasks another agent actively holds and lists who holds what,
+  // so a second terminal gets the next launchable task ([[HS-3C9M-A4TX-CAP]]).
+  const { error, result } = await resolveNextOnDeckAroundActiveClaims(
+    vaultRoot,
+    config,
+    argsWithCloudWip,
+  );
+  if (error) {
+    if (parsed.args.json) {
+      process.stderr.write(`${JSON.stringify({ error })}\n`);
+    } else {
+      process.stderr.write(`hs next: ${error.error ?? 'RESOLVE_FAILED'} — ${error.message ?? ''}\n`);
+    }
+    process.exit(EXIT.RESOLVE_FAILED);
+  }
+
+  await applyOnDeckHttpAugments(result, toolArgs);
+
+  if (parsed.args.json) {
+    process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+    process.exit(EXIT.OK);
+  }
+
+  const rawMd = result?.user_prompt_markdown ?? result?.prompt_markdown ?? '';
+  const interactive =
+    Boolean(process.stdin.isTTY && process.stdout.isTTY) && !process.env.HS_NEXT_NO_PROMPT;
+  // A run front never asks to claim one task — drop the agent claim line and
+  // ask about arming the milestone instead.
+  const arm = resolveArmTarget(result, parsed.args.front);
+  const md = arm
+    ? rawMd.replace(AGENT_CLAIM_LINE, '').trimEnd()
+    : renderTerminalClaimPrompt(rawMd, result, { interactive });
+  process.stdout.write(`${md}\n`);
+
+  if (arm) {
+    // The brief's own orchestration section (phase arm_run) already names the
+    // command; only print the CLI's lines when an older brief shape lacks it.
+    if (result?.agent_dispatch?.phase !== 'arm_run') {
+      process.stdout.write(`${renderArmLines(arm, parsed.args.front)}\n`);
+    }
+    if (!interactive) process.exit(EXIT.OK);
+    if (await askYesNoAtTerminal(`Arm the ${parsed.args.front} run on ${arm.milestoneId} now? [y/N] `)) {
+      spawnHsNext([frontWord(parsed.args.front), arm.milestoneId, '--launch']);
+      return;
+    }
+    process.stdout.write(`Not armed. Later: ${armCommand(arm, parsed.args.front)}\n`);
+    process.exit(EXIT.OK);
+  }
+
+  const claimId = result?.claim_target?.spec_id;
+  const isClaimQuestion = result?.agent_dispatch?.phase === 'claim_authorization' && claimId;
+  if (!interactive || !isClaimQuestion) process.exit(EXIT.OK);
+
+  // Attached to a real terminal: actually wait for the answer the brief asks
+  // for, then hand off to the launch half of `hs next` on yes.
+  if (await askClaimAtTerminal(claimId)) {
+    launchClaimedSpec(claimId);
+    return;
+  }
+  process.stdout.write(`Not claimed. Later: hs next ${claimId} --launch --claim\n`);
+  process.exit(EXIT.OK);
+}
+
+const invoked = process.argv[1]
+  && fileURLToPath(import.meta.url) === path.resolve(process.argv[1]);
+
+if (invoked) {
+  main().catch((err) => {
+    process.stderr.write(`hs next: ${err instanceof Error ? err.message : String(err)}\n`);
+    process.exit(EXIT.RESOLVE_FAILED);
+  });
+}