@stravica-ai/digital-operator-pa 0.1.0

package/dist/engineering-pa-core/src/scheduler/verify.mjs

@@ -0,0 +1,435 @@
+#!/usr/bin/env node
+/**
+ * verify.mjs -- Verify a schedule's command runs under its installed environment
+ *
+ * Usage: node node_modules/@stravica-ai/engineering-pa-core/src/scheduler/verify.mjs <schedule.json> [backend] [--timeout N]
+ *
+ * Reads a schedule JSON file and spawns its command under the same environment
+ * the named backend would install (PATH/HOME/DAVE_ROOT auto-injection on launchd,
+ * the schedule's own environment block elsewhere). This catches the silent-failure
+ * class of bug where an explicit narrow PATH masks brew binaries on Apple Silicon.
+ *
+ * The verify deliberately does not require the schedule to be installed already —
+ * it derives the env the same way install.mjs does and runs the command once. A
+ * timeout (default 30s) bounds the run; verify is meant for "does this schedule
+ * even start?" not "does it complete its full work?".
+ *
+ * Backend defaults to the auto-detected backend for the host (launchd on macOS,
+ * systemd or cron on Linux, schtasks on Windows).
+ *
+ * Exit codes:
+ *   0  ok                    — command exited zero
+ *   1  usage error
+ *   2  command exited non-zero (operational failure)
+ *   3  spawn failure          — command not found / ENOENT / EACCES / etc.
+ *   4  timeout                — command did not finish within the timeout
+ */
+
+import { readFileSync, realpathSync } from 'node:fs';
+import { spawn } from 'node:child_process';
+import { resolve, dirname, join } from 'node:path';
+import { homedir } from 'node:os';
+import { fileURLToPath } from 'node:url';
+
+import {
+  resolveWorkDir,
+  resolveEnvironment,
+  withLaunchdDefaults,
+  buildCronCommand,
+  detectNvm,
+} from './install.mjs';
+import { detect } from './detect.mjs';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+/**
+ * The environment cron's crond process actually provides to a job — a
+ * small fixed set (SHELL, a narrow system PATH, HOME, LOGNAME/USER), NOT
+ * whatever the verifying shell happens to have. This is what `env -i`
+ * testing proved on 2026-07-15 (w-2026-07-15-003): a login shell's PATH
+ * (nvm, Homebrew, pnpm global bin, …) is invisible to cron, so a schedule
+ * that "worked" under a verify run inheriting the operator's full shell
+ * env could still fail silently once actually installed.
+ * @param {object} [opts]
+ * @param {string} [opts.home]
+ * @param {string} [opts.user]
+ * @returns {Record<string,string>}
+ */
+export function minimalCronEnv({ home = homedir(), user = process.env.USER || process.env.LOGNAME || '' } = {}) {
+  return {
+    SHELL: '/bin/sh',
+    PATH: '/usr/bin:/bin',
+    HOME: home,
+    LOGNAME: user,
+    USER: user,
+  };
+}
+
+/**
+ * Compute the env the named backend would install for this schedule.
+ *
+ * - launchd: explicit env merged over auto-injected defaults (PATH, HOME, DAVE_ROOT).
+ *   Mirrors `withLaunchdDefaults(resolveEnvironment(sched))` from install.mjs.
+ * - cron: the schedule's own resolved environment layered over cron's
+ *   actual MINIMAL environment (see minimalCronEnv) — NOT the verifying
+ *   process's env. This is the honest-about-cron-reality fix: verify used
+ *   to inherit `process.env`, which reliably masked the nvm/PATH bug this
+ *   whole feature exists to catch (see module doc).
+ * - systemd / schtasks: the schedule's own resolved environment, with no
+ *   auto-injection. Verify inherits the parent shell's env on top of these
+ *   so spawn can find `node`, `bash`, etc. — matching how each backend
+ *   actually executes commands at runtime (systemd user units inherit the
+ *   user's systemd --user environment; schtasks inherits the interactive
+ *   SYSTEM/USER env). The verify replicates the "explicit env wins"
+ *   behaviour in each case.
+ *
+ * @param {object} sched
+ * @param {string} backend
+ * @returns {Record<string,string>}
+ */
+export function computeBackendEnv(sched, backend) {
+  const explicit = resolveEnvironment(sched);
+  if (backend === 'launchd') {
+    // launchd builds the agent env from EnvironmentVariables alone. Verify
+    // mirrors that: defaults + explicit, no parent-shell inheritance.
+    return withLaunchdDefaults(explicit);
+  }
+  if (backend === 'cron') {
+    return { ...minimalCronEnv(), ...explicit };
+  }
+  // systemd/schtasks: "parent env then explicit overrides". Replicate by
+  // layering explicit over process.env, dropping any keys the parent has
+  // but the schedule does not (we KEEP parent keys — explicit only
+  // narrows for keys it sets).
+  return { ...process.env, ...explicit };
+}
+
+/**
+ * Auto-detect the most-recommended backend for this host, falling back to the
+ * first available, then to 'cron' as a last resort.
+ *
+ * @returns {string}
+ */
+export function detectDefaultBackend() {
+  const { available } = detect();
+  if (available.length === 0) return 'cron';
+  const recommended = available.find(b => b.recommended);
+  return (recommended || available[0]).backend;
+}
+
+/**
+ * Read and parse a schedule JSON file.
+ * @param {string} filePath
+ * @returns {object}
+ */
+function readSchedule(filePath) {
+  const raw = readFileSync(filePath, 'utf8');
+  return JSON.parse(raw);
+}
+
+/**
+ * Spawn the configured command under the given env + workDir, with a timeout.
+ *
+ * Uses `spawn` (not `exec`) with shell:false on POSIX — the command is
+ * splittable by whitespace because schedule definitions are simple (a binary
+ * + args, no shell features). On Windows we use shell:true so `cmd.exe`
+ * handles the full string the same way schtasks would.
+ *
+ * Returns { kind, code, signal, error } where kind is one of:
+ *   'exit'    — process exited; code is the exit code (0 = ok, !0 = fail)
+ *   'spawn'   — spawn failed (ENOENT, EACCES, etc.)
+ *   'timeout' — process did not finish within timeoutMs; killed
+ *
+ * @param {string} command       The schedule.command string (whitespace-split on POSIX)
+ * @param {string} workDir       Working directory
+ * @param {Record<string,string>} env
+ * @param {number} timeoutMs
+ * @returns {Promise<{ kind: 'exit' | 'spawn' | 'timeout', code: number | null, signal: NodeJS.Signals | null, error: Error | null, stdout: string, stderr: string }>}
+ */
+// Shared settle/timeout/collect logic for an already-spawned child. Both
+// runVerify (string-command path) and runVerifyArgv (exact-argv path,
+// used to run the GENERATED cron line honestly — see below) fan into
+// this so the timeout/kill/collect behaviour never drifts between them.
+function waitForChild(child, timeoutMs) {
+  return new Promise(resolveOnce => {
+    let settled = false;
+    const settle = (value) => {
+      if (settled) return;
+      settled = true;
+      resolveOnce(value);
+    };
+
+    let stdout = '';
+    let stderr = '';
+    child.stdout.on('data', d => { stdout += d.toString(); });
+    child.stderr.on('data', d => { stderr += d.toString(); });
+
+    const timer = setTimeout(() => {
+      try { child.kill('SIGTERM'); } catch { /* already dead */ }
+      // Give it a grace window before SIGKILL.
+      setTimeout(() => { try { child.kill('SIGKILL'); } catch { /* gone */ } }, 1000).unref();
+      settle({ kind: 'timeout', code: null, signal: 'SIGTERM', error: null, stdout, stderr });
+    }, timeoutMs);
+
+    child.on('error', (err) => {
+      clearTimeout(timer);
+      settle({ kind: 'spawn', code: null, signal: null, error: err, stdout, stderr });
+    });
+
+    child.on('exit', (code, signal) => {
+      clearTimeout(timer);
+      // If we already settled (timeout), this exit fires later — settle is a no-op.
+      settle({ kind: 'exit', code, signal, error: null, stdout, stderr });
+    });
+  });
+}
+
+export function runVerify(command, workDir, env, timeoutMs) {
+  const onWindows = process.platform === 'win32';
+  let child;
+  try {
+    if (onWindows) {
+      child = spawn(command, {
+        cwd: workDir,
+        env,
+        shell: true,
+        stdio: ['ignore', 'pipe', 'pipe'],
+      });
+    } else {
+      const parts = command.trim().split(/\s+/);
+      const [bin, ...args] = parts;
+      child = spawn(bin, args, {
+        cwd: workDir,
+        env,
+        shell: false,
+        stdio: ['ignore', 'pipe', 'pipe'],
+      });
+    }
+  } catch (err) {
+    return Promise.resolve({ kind: 'spawn', code: null, signal: null, error: err, stdout: '', stderr: '' });
+  }
+  return waitForChild(child, timeoutMs);
+}
+
+/**
+ * Spawn an exact `bin` + `args` array — no string-splitting, no shell.
+ * Used to run the GENERATED cron inner script honestly: the script text
+ * (which may itself contain spaces, `&&`, quoting from env-var export
+ * statements, etc.) is passed as a single `-c` argv element to `bash`,
+ * never re-parsed by whitespace-splitting the way runVerify's string path
+ * would mangle it.
+ *
+ * @param {string} bin
+ * @param {string[]} args
+ * @param {string} workDir
+ * @param {Record<string,string>} env
+ * @param {number} timeoutMs
+ * @returns {Promise<{ kind: 'exit' | 'spawn' | 'timeout', code: number | null, signal: NodeJS.Signals | null, error: Error | null, stdout: string, stderr: string }>}
+ */
+export function runVerifyArgv(bin, args, workDir, env, timeoutMs) {
+  let child;
+  try {
+    child = spawn(bin, args, {
+      cwd: workDir,
+      env,
+      shell: false,
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+  } catch (err) {
+    return Promise.resolve({ kind: 'spawn', code: null, signal: null, error: err, stdout: '', stderr: '' });
+  }
+  return waitForChild(child, timeoutMs);
+}
+
+/**
+ * Verify a schedule by running its command once under the resolved backend
+ * env.
+ *
+ * For backend === 'cron', this does NOT run `sched.command` directly — it
+ * builds the exact GENERATED inner cron script (via install.mjs's
+ * `buildCronCommand`, the same function `scheduler install` uses to write
+ * the actual crontab line) and runs THAT via `bash -c` with an exact argv
+ * array (never a re-split string). This is the "verification is honest
+ * about cron reality" fix: verifying `sched.command` alone, under an env
+ * that inherits the verifying process's PATH, never exercised the nvm
+ * preamble or the minimal-PATH reality a real cron invocation faces —
+ * exactly how the env -i-provable bug (w-2026-07-15-003) went undetected
+ * by the pre-existing verify path.
+ *
+ * @param {string} scheduleFile - Path to the schedule JSON
+ * @param {object} [opts]
+ * @param {string} [opts.backend] - Override backend (default: auto-detect)
+ * @param {number} [opts.timeoutMs] - Timeout in ms (default: 30000)
+ * @param {boolean} [opts.hasNvm] - Test-only override; defaults to a real
+ *   filesystem check of $HOME/.nvm/nvm.sh, matching install-time detection.
+ * @param {string} [opts.cronLogPath] - Test-only override for the cron
+ *   inner script's log redirect target (defaults to
+ *   `/tmp/<agent>-<id>-verify.log` — distinct from the INSTALLED
+ *   schedule's own `/tmp/<agent>-<id>.log`, so a verify run never
+ *   clobbers/interleaves with real cron output).
+ * @returns {Promise<{ result: 'ok' | 'fail-exit' | 'fail-spawn' | 'fail-timeout', exitCode: number, sched: object, backend: string, env: Record<string,string>, workDir: string, run: object }>}
+ */
+export async function verify(scheduleFile, opts = {}) {
+  const sched = readSchedule(scheduleFile);
+
+  if (!sched.id || !sched.schedule || !sched.command) {
+    const err = new Error('Schedule file must have id, schedule, and command fields');
+    err.exitCode = 1;
+    throw err;
+  }
+
+  const backend = opts.backend || sched.backend || detectDefaultBackend();
+  const timeoutMs = opts.timeoutMs ?? 30000;
+
+  const workDir = resolveWorkDir(sched.workingDirectory);
+  const env = computeBackendEnv(sched, backend);
+
+  let run;
+  if (backend === 'cron') {
+    const explicit = resolveEnvironment(sched);
+    const hasNvm = opts.hasNvm ?? detectNvm();
+    const logPath = opts.cronLogPath ?? `/tmp/${sched.agent || 'dave'}-${sched.id}-verify.log`;
+    const { inner } = buildCronCommand(sched, workDir, explicit, { hasNvm, logPath });
+    run = await runVerifyArgv('bash', ['-c', inner], workDir, env, timeoutMs);
+  } else {
+    run = await runVerify(sched.command, workDir, env, timeoutMs);
+  }
+
+  let result;
+  let exitCode;
+  if (run.kind === 'timeout') {
+    result = 'fail-timeout';
+    exitCode = 4;
+  } else if (run.kind === 'spawn') {
+    result = 'fail-spawn';
+    exitCode = 3;
+  } else if (run.code === 0) {
+    result = 'ok';
+    exitCode = 0;
+  } else {
+    result = 'fail-exit';
+    exitCode = 2;
+  }
+
+  return { result, exitCode, sched, backend, env, workDir, run };
+}
+
+// ── CLI entry point ──────────────────────────────────────────────────
+
+function printUsage(stream = process.stderr) {
+  stream.write(
+`Usage: node verify.mjs <schedule.json> [backend] [--timeout <seconds>]
+
+Spawns the schedule's command once under the same environment the named backend
+would install. Useful as a post-install smoke test to catch silent-failure bugs
+caused by env mismatches (e.g. a narrow PATH that masks Homebrew binaries).
+
+Arguments:
+  <schedule.json>     Path to the schedule definition file.
+  [backend]           Backend whose env shape to simulate (cron, launchd,
+                      systemd, schtasks). Defaults to auto-detected backend.
+
+Flags:
+  --timeout <seconds> Kill the verify run after this many seconds (default: 30).
+  -h, --help          Print this message and exit 0.
+
+Exit codes:
+  0  command ran and exited zero
+  1  usage error
+  2  command exited non-zero
+  3  spawn failure (command not found, etc.)
+  4  timeout
+`);
+}
+
+// BUG 3 fix — see install.mjs for the full rationale: realpath both sides
+// instead of the previous realpath-vs-symlink endsWith comparison, which
+// silently no-op'd under pnpm.
+
+function isDirectlyInvoked() {
+  if (!process.argv[1]) return false;
+  try {
+    return fileURLToPath(import.meta.url) === realpathSync(resolve(process.argv[1]));
+  } catch {
+    return false;
+  }
+}
+
+if (isDirectlyInvoked()) {
+  const args = process.argv.slice(2);
+
+  if (args.includes('-h') || args.includes('--help')) {
+    printUsage(process.stdout);
+    process.exit(0);
+  }
+
+  // Parse: positional <schedule.json>, optional positional <backend>, optional --timeout N.
+  let scheduleFile = null;
+  let backend = null;
+  let timeoutSeconds = 30;
+
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a === '--timeout') {
+      const v = args[++i];
+      const n = Number(v);
+      if (!Number.isFinite(n) || n <= 0) {
+        process.stderr.write(`Error: --timeout requires a positive number, got: ${v}\n`);
+        process.exit(1);
+      }
+      timeoutSeconds = n;
+    } else if (a.startsWith('--timeout=')) {
+      const v = a.slice('--timeout='.length);
+      const n = Number(v);
+      if (!Number.isFinite(n) || n <= 0) {
+        process.stderr.write(`Error: --timeout requires a positive number, got: ${v}\n`);
+        process.exit(1);
+      }
+      timeoutSeconds = n;
+    } else if (a.startsWith('--')) {
+      process.stderr.write(`Error: unknown flag: ${a}\n`);
+      printUsage();
+      process.exit(1);
+    } else if (scheduleFile === null) {
+      scheduleFile = a;
+    } else if (backend === null) {
+      backend = a;
+    } else {
+      process.stderr.write(`Error: unexpected argument: ${a}\n`);
+      printUsage();
+      process.exit(1);
+    }
+  }
+
+  if (!scheduleFile) {
+    printUsage();
+    process.exit(1);
+  }
+
+  if (backend && !['cron', 'launchd', 'systemd', 'schtasks'].includes(backend)) {
+    process.stderr.write(`Error: unknown backend: ${backend}. Supported: cron, launchd, systemd, schtasks\n`);
+    process.exit(1);
+  }
+
+  try {
+    const out = await verify(scheduleFile, { backend, timeoutMs: timeoutSeconds * 1000 });
+    const label = `verify[${out.sched.id}@${out.backend}]`;
+    if (out.result === 'ok') {
+      process.stdout.write(`${label}: OK — command exited 0 in ${out.workDir}\n`);
+    } else if (out.result === 'fail-exit') {
+      process.stdout.write(`${label}: FAIL — command exited ${out.run.code}\n`);
+      if (out.run.stderr) process.stderr.write(out.run.stderr);
+    } else if (out.result === 'fail-spawn') {
+      const msg = out.run.error ? out.run.error.message : 'unknown spawn error';
+      process.stderr.write(`${label}: FAIL — could not spawn command: ${msg}\n`);
+      process.stderr.write(`Hint: verify the command's first token is on PATH (current PATH: ${out.env.PATH || '(unset)'})\n`);
+    } else if (out.result === 'fail-timeout') {
+      process.stderr.write(`${label}: FAIL — timed out after ${timeoutSeconds}s\n`);
+    }
+    process.exit(out.exitCode);
+  } catch (err) {
+    process.stderr.write(`Error: ${err.message}\n`);
+    process.exit(err.exitCode || 1);
+  }
+}

package/dist/engineering-pa-core/src/session-boot/autonomy-injection.mjs

@@ -0,0 +1,84 @@
+// autonomy-injection.mjs — session-boot integration surface for the
+// autonomy envelope.
+//
+// OQ-A1 recommendation: the core does NOT ship a Claude Code SessionStart
+// hook — hook infrastructure is operator-side (typically an operator's
+// boot-context tool). Core instead ships this reusable module that renders
+// the envelope's current state as an `additionalContext`-shaped markdown
+// block, and the `pa autonomy get <agent> --format json` verb that lets an
+// operator's boot hook consume the state programmatically.
+//
+// The recommended operator wiring is: the operator's SessionStart hook
+// tool spawns `pa autonomy get <agent> --format json`, imports this
+// module, and calls `buildAutonomyContext({ envelope })` to produce the
+// markdown block to inject alongside its other live-state blocks.
+
+/**
+ * Build a compact `additionalContext`-shaped markdown block for the given
+ * envelope. Same size class as a workState block — a summary of task-types
+ * grouped by state, not a full render of the envelope.
+ *
+ * Input shape (matches `pa autonomy get <agent> --format json` output):
+ *   {
+ *     agent, owner, updated,
+ *     taskTypes: [{ id, label, state, stateSince, operatorNote? }, ...]
+ *   }
+ *
+ * Returns a string suitable for the `additionalContext` field of a
+ * Claude Code SessionStart hook JSON envelope.
+ */
+export function buildAutonomyContext(envelope) {
+  if (!envelope || !envelope.agent) {
+    return '# autonomyEnvelope (live)\n\n_No envelope initialised — run `pa autonomy init <agent>` to seed one._\n';
+  }
+  const grouped = {
+    fullyApproved: [],
+    checkBeforeCommitting: [],
+    needsFullSupervision: [],
+  };
+  const taskTypes = envelope.taskTypes ?? [];
+  for (const t of taskTypes) {
+    if (grouped[t.state]) grouped[t.state].push(t);
+  }
+  const parts = [];
+  parts.push('# autonomyEnvelope (live)');
+  parts.push('');
+  parts.push(`Agent: **${envelope.agent}** | Updated: ${envelope.updated ?? '-'}`);
+  parts.push('');
+  parts.push('## fullyApproved (act, don\'t ask)');
+  parts.push('');
+  parts.push(renderGroup(grouped.fullyApproved));
+  parts.push('');
+  parts.push('## checkBeforeCommitting (draft, sign-off before commit / push / publish)');
+  parts.push('');
+  parts.push(renderGroup(grouped.checkBeforeCommitting));
+  parts.push('');
+  parts.push('## needsFullSupervision (do not act; escalate every step)');
+  parts.push('');
+  parts.push(renderGroup(grouped.needsFullSupervision));
+  parts.push('');
+  parts.push('_The envelope is the durable record. If a task-type is not listed above it defaults to needsFullSupervision — escalate._');
+  return parts.join('\n') + '\n';
+}
+
+function renderGroup(taskTypes) {
+  if (!taskTypes.length) return '_(none)_';
+  return taskTypes
+    .map((t) => `- **${t.label}** (\`${t.id}\`)${t.operatorNote ? ` — ${t.operatorNote}` : ''}`)
+    .join('\n');
+}
+
+/**
+ * Build the full Claude Code SessionStart hook envelope shape for the
+ * given autonomy envelope. Convenience wrapper — operator hook tools that
+ * want to emit the block directly can call this instead of composing the
+ * envelope themselves.
+ */
+export function buildAutonomyHookEnvelope(envelope) {
+  return {
+    hookSpecificOutput: {
+      hookEventName: 'SessionStart',
+      additionalContext: buildAutonomyContext(envelope),
+    },
+  };
+}

package/dist/engineering-pa-core/src/slice/cli.mjs

@@ -0,0 +1,139 @@
+// slice — CLI.
+//
+// Arg parsing (node:util.parseArgs, strict:true), verb routing,
+// exit-code translation per §5–§6 of the tooling standard.
+
+import { parseArgs } from 'node:util';
+
+import { runSlice } from './run.mjs';
+import { defaultRunner } from '../distill/runner.mjs';
+
+const USAGE = `slice — operator profile slice generator
+
+Usage:
+  slice generate <name> --profile <path> [options]
+  slice -h, --help                        Show this help
+
+Verbs:
+  generate <name>     Generate a named slice (e.g. "dave-boot"). The name
+                      selects a bundled prompt template under
+                      src/slice/prompts/<name>.md. To use a custom template
+                      pass --template <path> instead of a name.
+
+Options for "generate":
+  --profile <path>          Path to the operator's profile.md (required).
+  --learned-rules <path>    Path to learned-rules.md (optional).
+  --observations <dir>      Directory of recent observation .md files (optional).
+  --output <path>           Where to write the slice (required).
+  --template <path>         Override the bundled template path.
+  --runs-log <path>         Append one JSON audit line per invocation to this
+                            file (camelCase fields: ts, status, exitCode,
+                            durationSec, dryRun, outputBytes, reason).
+                            Consumed by the tasks-status monitor — when
+                            slice runs on a schedule, point this at a
+                            per-task runs.jsonl. Optional.
+  --dry-run                 Build the prompt and report; skip claude call + write.
+  -h, --help                Show this help.
+
+Exit codes:
+  0  ok
+  1  usage error
+  2  prerequisite missing / operational failure (incl. validation failure)
+  3  claude transport failure
+
+Source of truth for behaviour: @stravica-ai/engineering-pa-core/docs/tools/slice.md
+`;
+
+export async function main(
+  argv,
+  { stderr = process.stderr, stdout = process.stdout, exit = process.exit } = {},
+) {
+  try {
+    return await route(argv, { stderr, stdout, exit });
+  } catch (err) {
+    const code = err?.sliceExitCode ?? 2;
+    stderr.write(`[slice] ${err.message || err}\n`);
+    exit(code);
+  }
+}
+
+async function route(argv, { stderr, stdout, exit }) {
+  if (argv.length === 0 || argv[0] === '-h' || argv[0] === '--help') {
+    stdout.write(USAGE);
+    exit(0);
+    return;
+  }
+
+  const verb = argv[0];
+  const rest = argv.slice(1);
+
+  if (verb === 'generate') {
+    // First token after the verb is treated as the slice name (e.g. "dave-boot")
+    // IF it doesn't start with `-`. Otherwise the name is omitted and must be
+    // supplied via --template. Subsequent positionals are an error (caught by
+    // parseArgs strict mode).
+    let name = null;
+    let args = rest;
+    if (rest.length > 0 && !rest[0].startsWith('-')) {
+      name = rest[0];
+      args = rest.slice(1);
+    }
+
+    const { values } = parseArgs({
+      args,
+      options: {
+        profile: { type: 'string' },
+        'learned-rules': { type: 'string' },
+        observations: { type: 'string' },
+        output: { type: 'string' },
+        template: { type: 'string' },
+        'runs-log': { type: 'string' },
+        'dry-run': { type: 'boolean', default: false },
+        help: { type: 'boolean', short: 'h', default: false },
+      },
+      strict: true,
+    });
+
+    if (values.help) {
+      stdout.write(USAGE);
+      exit(0);
+      return;
+    }
+
+    const template = values.template ?? name;
+    if (!template) {
+      stderr.write('[slice] generate: missing slice name or --template\n');
+      stderr.write(USAGE);
+      exit(1);
+      return;
+    }
+    if (!values.profile) {
+      stderr.write('[slice] generate: --profile is required\n');
+      exit(1);
+      return;
+    }
+    if (!values.output) {
+      stderr.write('[slice] generate: --output is required\n');
+      exit(1);
+      return;
+    }
+
+    const code = await runSlice({
+      profilePath: values.profile,
+      learnedRulesPath: values['learned-rules'],
+      observationsDir: values.observations,
+      template,
+      outputPath: values.output,
+      runsLog: values['runs-log'],
+      dryRun: values['dry-run'],
+      runner: defaultRunner,
+      stderr,
+    });
+    exit(code ?? 0);
+    return;
+  }
+
+  stderr.write(`[slice] unknown command: ${verb}\n`);
+  stderr.write(USAGE);
+  exit(1);
+}