do-better 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Chris Williams
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,265 @@
+# do-better
+
+> Point an agent at an existing codebase and ask: *what should be better here,
+> in what order, and how do we prove we didn't break anything?* Then produce a
+> defensible technical roadmap — not vibes, **verified findings**.
+
+**do-better** is comprehension → fault/improvement identification → technical
+roadmap, for existing codebases — the "just do better" work, not new-feature
+build. It is a sibling to
+[skill-mining](https://github.com/voodootikigod/skill-mining) (extracts latent
+*knowledge* from a repo) and [aidlc](https://github.com/voodootikigod/aidlc)
+(executes builds): do-better produces *judgment + plan*, and is the
+**brownfield front-end to the ADLC**. It never executes fixes — each roadmap
+item hands off to ADLC P3/P4 as a cold-start-tested ticket.
+
+What makes the output defensible:
+
+- Every claim carries a `file:line@sha` citation, verified deterministically
+  and pinned to a commit SHA. Stale claims are flagged, never trusted.
+- Every finding survived **reproduce-or-kill** adversarial verification —
+  unverified findings never reach output.
+- Sampling is **declared, never silent** — the coverage manifest states what
+  was deep-read, scanned, and skipped.
+- The roadmap lists what was **declined** and the risk of inaction, not just
+  what made the cut.
+
+Dual mode, like skill-mining: a cross-harness skill
+([`do-better/SKILL.md`](do-better/SKILL.md)) any agent harness can run
+manually, plus an `npx do-better` CLI that automates the same lifecycle with
+the same gates.
+
+## Install
+
+```bash
+# Zero-install (recommended)
+npx do-better run
+
+# Or as a cross-harness agent skill
+npx skills add voodootikigod/do-better
+```
+
+Set an LLM key (Anthropic default; Gemini, OpenAI, and local endpoints supported):
+
+```bash
+export ANTHROPIC_API_KEY="..."      # default, detected first
+# or: export GEMINI_API_KEY="..."   # with --provider gemini
+# or: export OPENAI_API_KEY="..."   # with --provider openai
+# or (data-governance / air-gapped): any OpenAI-compatible local server
+#   export DOBETTER_LOCAL_BASE_URL="http://localhost:11434/v1"   # e.g. Ollama
+#   export DOBETTER_LOCAL_MODEL="qwen2.5-coder"                  # with --provider local
+```
+
+No key at all? `--offline` degrades to static analysis and structure-only
+artifacts — every degradation declared, never silent.
+
+Requires Node >= 18 and a **git repository** as the target (claims are
+SHA-pinned; no git, no run). Zero runtime dependencies.
+
+## The loop
+
+```
+D-1 Scan ──▶ D0 Charter ──▶ D1 Comprehend ──▶ D2 Identify ──▶ D3 Roadmap ──▶ D4 Rail ──▶ Handoff
+ cheap facts   interview +     7 artifacts,      refute-chartered  score/sequence/  pin behavior   tickets →
+ + codemap     weights         parallax-checked  finders + verify  ticket           with rails     ADLC P3/P4
+               [HUMAN GATE 1]  divergence gate   dry + 0-unverified coldstart gate + rails green +
+                                                                    [HUMAN GATE 2]   hollow audit
+
+                        ↻ refresh — idempotent living-document re-run (only changed files)
+```
+
+Exactly **two human gates**: charter approval and roadmap approval. Everything
+else is deterministic or threshold-based. Enterprise engagements pause for days
+at human gates; `state.json` makes every phase resumable, so a pause costs
+nothing.
+
+## Usage
+
+```bash
+npx do-better scan        # D-1  — cheap repo scan: facts, incantations, codemap draft
+npx do-better charter     # D0   — interactive stakeholder interview, seeded by scan facts
+npx do-better charter --approve   # approve the (possibly edited) charter   [HUMAN GATE 1]
+npx do-better audit       # D1+D2 — comprehend (7 artifacts) + identify (verified findings)
+npx do-better roadmap     # D3   — score, sequence, tickets, coldstart gate
+npx do-better roadmap --approve   # approve the (possibly edited) roadmap   [HUMAN GATE 2]
+npx do-better rail        # D4   — characterization rails + hollow-test audit
+npx do-better run         # full pipeline; stops cleanly at human gates, resumes after --approve
+npx do-better refresh     # idempotent re-run; diffs vs pinned SHA; only changed files
+```
+
+### Flags
+
+| Flag | Applies to | Meaning |
+|---|---|---|
+| `--provider anthropic\|gemini\|openai\|local` | all | Force the LLM provider. Default: env autodetect, Anthropic first (a configured `DOBETTER_LOCAL_BASE_URL` is detected last). `local` targets any OpenAI-compatible endpoint (`DOBETTER_LOCAL_BASE_URL` + `DOBETTER_LOCAL_MODEL`). A named provider without its key/URL is an error — never a silent fallback. |
+| `--budget <usd>` | all | Hard USD ceiling. A call that would exceed it refuses and stops with resume instructions; per-phase spend lives in `state.json`. |
+| `--offline` | all | No LLM calls — static analysis + structure-only artifacts, every degradation declared. |
+| `--model-cheap <id>` / `--model-mid <id>` / `--model-frontier <id>` | all | Override the model for one tier (see Model tiering). |
+| `--target <dir>` | all | Target repo (also the second positional). Default `.`. |
+| `--approve` | `charter`, `roadmap` | Approve the human-gated artifact as it stands on disk (post-edit hashes are recorded, not rejected). |
+| `--n <N>` / `--threshold <t>` | `audit` | D1 parallax fan width (default 3) **and** the D2 finder-pool ceiling / divergence threshold (default 0.25). In D2, `--n` caps a charter-weighted pool of distinct-lens finders (table below); unset, the D2 pool ceiling is 1 (pooling opt-in). |
+| `--yes` | `rail`, others | Skip confirmations (e.g. the rails commit). Never skips the two human gates. |
+| `--json` | all | Machine-readable summary on stdout. |
+| `-h`, `--help` | all | Help. |
+
+**D2 charter-weighted finder-pool width.** `--n` is the ceiling; each pass fans
+that many finders, each under a distinct lens, so "dry" means the codebase is
+exhausted rather than that a single context converged:
+
+| Charter weight | Effective pool width |
+|---|---|
+| 4–5 | `--n` (full width) |
+| 2–3 | `max(1, floor(--n / 2))` |
+| 1 | `1` (no pooling) |
+
+`--n 1` reproduces the pre-pool single-finder call counts exactly (every
+dimension is width 1). Unset, the D2 ceiling is 1; lens rotation across passes
+is always on, while the within-pass fan-out is opt-in via `--n`.
+
+### Exit codes
+
+The adlc-universal contract:
+
+| Code | Meaning |
+|---|---|
+| `0` | Success — **including a clean human-gate pause** with printed resume instructions. |
+| `1` | Operational error: bad input, missing file, no provider/key, network or LLM failure after retries, budget exceeded. |
+| `2` | Deterministic gate failure: divergence over threshold, a `(dimension × packet)` cell not dry / unverified findings, coldstart gaps unrepaired, rails red, hollow-audit survivor. |
+
+### D2 coverage & sizing `--budget`
+
+D2 no longer rotates a single ≤30 KB window over the deep-read set — it
+**partitions the whole set into packets** (every deep-read file lands in exactly
+one packet; an oversized file becomes its own truncated singleton) and loops
+each `(dimension × packet)` cell until dry. That guarantees every deep-read byte
+is actually shown to a finder, but it also means finder calls scale with the
+number of packets. After a run, `.dobetter/comprehension/coverage-manifest.md`
+gains a **`## D2 finder coverage`** section recording, per dimension, the files
+examined, packet count, total passes, and any truncated slices (unreadable
+files land under `### Unexamined`).
+
+Finder calls scale as **`dimensions × packets × passes × N`**, so size
+`--budget` before a run. For a reference repo of ~8 dimensions and ~5 packets,
+with the dry loop settling near its `K_DRY = 2` floor (best case) and its
+`MAX_PASSES = 8` cap (worst case):
+
+| Term | Value | Notes |
+|---|---|---|
+| dimensions | 8 | taxonomy floor (+ any charter extras) |
+| packets | ~5 | reference shape; grows with deep-read size / file size |
+| passes per cell | 2 – 8 | `K_DRY = 2` when a cell settles immediately; `MAX_PASSES = 8` cap |
+| N | `poolN` | finder pool width per pass — charter-weighted (see the pooling table above); `--n 1` (or unset) reproduces single-finder counts |
+| **finder calls** | **80·N – 320·N** | `8 × 5 × {2‥8} × N`; verification adds ≤1 repro + ≤1 verdict per surviving candidate |
+
+`--budget` is the hard ceiling: a call that would exceed it refuses and stops
+with resume instructions, and every finding verified so far is already on disk
+(findings are written per candidate, not batched). A same-sha resume skips the
+packets already recorded dry — zero re-issued finder calls for them.
+
+### Environment variables
+
+| Var | Purpose |
+|---|---|
+| `ANTHROPIC_API_KEY` / `GEMINI_API_KEY` / `OPENAI_API_KEY` | Provider credentials (autodetected in that order). |
+| `DOBETTER_LOCAL_BASE_URL` | Base URL of an OpenAI-compatible local endpoint (e.g. `http://localhost:11434/v1`) for `--provider local`. Autodetected last, after the hosted keys above. |
+| `DOBETTER_LOCAL_MODEL` | Model name to request from the local endpoint (e.g. `qwen2.5-coder`). |
+| `DOBETTER_LOCAL_API_KEY` | Optional bearer token for the local endpoint (many local servers ignore it). |
+| `DOBETTER_ADLC_DIR` | Path to an aidlc checkout for the composed tools (else sibling-dir probe, else `npx @adlc/<tool>`). |
+| `DOBETTER_SKILL_MINING_DIR` | Path to a skill-mining checkout (else sibling probe, else `npx skill-mining`). |
+| `DOBETTER_ANSWERS` | Path to a JSON `string[]` of scripted charter answers (non-interactive runs, CI, tests). |
+| `DOBETTER_FAKE_LLM` | Test seam: path to a module default-exporting an async `fake({prompt,system,tier,label,jsonMode})` — bypasses all providers/keys and no network path is reachable. |
+| `DOBETTER_DEBUG` | Print stack traces on error. |
+
+## Artifact layout
+
+Everything is committed to the target repo under `.dobetter/`:
+
+```
+.dobetter/
+  charter.md            # D0 output, human-approved; dimension weights
+  comprehension/
+    codemap.md
+    architecture.md     # intended design vs actual drift
+    behavior-inventory.md   # KEYSTONE — observable behaviors: routes, jobs, CLIs, events
+    dependencies.md     # versions, EOL/CVE, coupling hotspots
+    rails-map.md        # covered vs load-bearing-but-untested
+    glossary.md         # business terms ↔ code terms
+    coverage-manifest.md    # deep-read X%, scanned Y% — declared, never silent
+  findings/             # one file per VERIFIED finding; file:line + commit-SHA evidence,
+                        # dimension, severity, reproduction record
+  ROADMAP.md            # executive deliverable (Now/Next/Later, declined, risk-of-inaction)
+  backlog/              # ADLC-shaped tickets; tickets.json is coldstart-consumable as-is
+  rails/manifest.md     # pointers — actual tests live in the repo's test tree
+  state.json            # run history, SHA pins, per-phase spend, prior-roadmap hashes
+```
+
+The **behavior inventory is the keystone**: it is the denominator for "retain
+existing functionality," the scope source for rails, and the baseline for
+regression detection on refresh.
+
+## Composition contracts
+
+- **skill-mining** — invoked as a D1 comprehension sub-step; mined skills are
+  comprehension artifacts and ride along for the execution phase.
+- **aidlc** — `backlog/tickets.json` conforms to the ADLC P2 ticket schema
+  (atomic, fresh-agent executable, explicit contracts, coldstart-tested) and is
+  consumable by `coldstart --tickets .dobetter/backlog/tickets.json`
+  unmodified. Rails conform to P3 doctrine (separate context, frozen,
+  hollow-audited). Reused packages: `parallax` (D1 divergence gate),
+  `coldstart` (D3 gate), `hollow-test` (D4 audit), `preflight` (D4 env check),
+  `behavior-diff` (refresh regression detection).
+- **grill-me** — the D0 charter interview is grill-me with a codebase-check
+  clause, seeded by D-1 facts: questions cite real scan facts, and anything the
+  codebase already answers is established, not asked.
+
+Every composed tool **degrades gracefully and loudly** when absent: parallax →
+declared single-reading mode + mandatory human skim; coldstart → native
+cheap-tier probe; hollow-test → deletion spot-check; preflight → basic env
+probe; behavior-diff → SHA/file-diff staleness only; skill-mining → sub-step
+skipped. Each degradation is recorded in `coverage-manifest.md` and the gate
+records — weaker is acceptable, silent is not.
+
+## Model tiering
+
+Tiered by **cost of detecting error**, not prestige (override per tier with
+`--model-cheap/--model-mid/--model-frontier`):
+
+| Tier | Phases | Why safe |
+|---|---|---|
+| cheap (Haiku-class) | D-1 scan, codemap draft, dependency inventory, coldstart probes | Mechanical; errors caught instantly and deterministically |
+| mid (Sonnet-class) | D1 readers, D2 finders, D4 rail drafting | Adversarial verification + hollow-test catch their errors |
+| frontier | D0 charter synthesis, D2 finding verdicts, D3 roadmap judgment | Errors here sail through every gate undetected |
+
+## Success metrics
+
+1. **Ticket survival rate** — % of backlog items accepted into execution
+   without reworking the ticket itself.
+2. **Zero retained-functionality regressions** traced to rails gaps.
+
+**Refused vanity metrics**: findings count, roadmap length, artifact volume.
+A hundred plausible findings are worth less than ten verified ones; do-better's
+verification stage exists to kill, and the kill count is diagnostic, not
+shameful. If a do-better report impresses by sheer volume, it has failed.
+
+## What's in here
+
+```
+do-better/
+├── bin/cli.js                    # the CLI (npx do-better)
+├── src/                          # phase modules: scan, charter, comprehend, identify,
+│                                 # roadmap, rail, refresh + llm/adlc/state/artifacts
+├── do-better/
+│   ├── SKILL.md                  # the cross-harness skill (the lifecycle itself)
+│   └── references/
+│       ├── taxonomy.md           # the 8-dimension fixed floor + per-dimension finder charters
+│       ├── refute-charter.md     # D2 finder doctrine: adversarial refutation
+│       ├── verification.md       # reproduce-or-kill protocol + citation rules
+│       ├── scoring.md            # impact × confidence ÷ effort, sequencing rules
+│       └── templates/            # charter, finding, roadmap, ticket, rail shapes
+└── test/                         # node --test; no network, fake LLM + fake adlc fixtures
+```
+
+## License
+
+MIT © 2026 Chris Williams ([@voodootikigod](https://github.com/voodootikigod)).
+See [LICENSE](LICENSE).

package/bin/cli.js

@@ -0,0 +1,262 @@
+#!/usr/bin/env node
+// do-better CLI — parse → configure → dispatch → exit codes.
+// Exit codes: 0 success or clean human-gate pause; 1 operational error;
+// 2 deterministic gate failure.
+
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import {
+  GateError,
+  HELP_TEXT,
+  OpError,
+  colors,
+  gitHeadSha,
+  log,
+  stderrLog,
+  makeExec,
+  nowIso,
+  parseArgs,
+} from "../src/utils.js";
+import {
+  beginRun,
+  defaultState,
+  finishRun,
+  loadState,
+  nextIncompletePhase,
+  saveState,
+} from "../src/state.js";
+
+const VERSION = "0.1.0";
+
+// Printed when a human gate pauses the pipeline (D8) and the phase module did
+// not supply its own instruction text in gate.detail.
+const HUMAN_GATE_INSTRUCTIONS = {
+  charter:
+    "Charter drafted at .dobetter/charter.md — review/edit, then run: do-better charter --approve",
+  roadmap:
+    "Roadmap drafted — review .dobetter/ROADMAP.md + backlog/, then run: do-better roadmap --approve",
+};
+
+function importPhase(name) {
+  return import(new URL(`../src/${name}.js`, import.meta.url));
+}
+
+// Machine-readable run stats for the --json envelope (H17): spend and the
+// identify verified/killed counts, all already sitting in state at emit time.
+function stateStats(state) {
+  const identify = state?.phases?.identify ?? {};
+  return {
+    spendUSD: Number.isFinite(state?.budget?.spentUSD) ? state.budget.spentUSD : 0,
+    verified: Number.isInteger(identify.verified) ? identify.verified : null,
+    killed: Number.isInteger(identify.killed) ? identify.killed : null,
+  };
+}
+
+function makeAsk(env) {
+  if (env.DOBETTER_ANSWERS) {
+    const answersPath = path.resolve(env.DOBETTER_ANSWERS);
+    if (!fs.existsSync(answersPath)) {
+      throw new OpError(`DOBETTER_ANSWERS file not found: ${answersPath}`);
+    }
+    let answers;
+    try {
+      answers = JSON.parse(fs.readFileSync(answersPath, "utf8"));
+    } catch (e) {
+      throw new OpError(`DOBETTER_ANSWERS is not valid JSON: ${e.message}`);
+    }
+    if (!Array.isArray(answers) || answers.some((a) => typeof a !== "string")) {
+      throw new OpError("DOBETTER_ANSWERS must be a JSON array of strings");
+    }
+    let i = 0;
+    // Exhausted answers → empty string (accept the recommendation).
+    return { ask: async () => answers[i++] ?? "", close: () => {} };
+  }
+  if (process.stdin.isTTY) {
+    let rl = null;
+    const getRl = async () => {
+      if (!rl) {
+        const { createInterface } = await import("node:readline/promises");
+        rl = createInterface({ input: process.stdin, output: process.stdout });
+      }
+      return rl;
+    };
+    return {
+      ask: async (question) => (await getRl()).question(question),
+      close: () => rl?.close(),
+    };
+  }
+  return { ask: null, close: () => {} };
+}
+
+async function main() {
+  const flags = parseArgs(process.argv.slice(2));
+
+  if (flags.help) {
+    console.log(HELP_TEXT);
+    return 0;
+  }
+  if (!flags.command) {
+    if (flags.target !== ".") log.error(`Unknown command: ${flags.target}`);
+    console.log(HELP_TEXT);
+    return 1;
+  }
+
+  const root = path.resolve(flags.target);
+  if (!fs.existsSync(root) || !fs.statSync(root).isDirectory()) {
+    throw new OpError(`Target directory not found: ${root}`);
+  }
+  const dotdir = path.join(root, ".dobetter");
+  const exec = makeExec();
+
+  let headSha = null;
+  try {
+    headSha = gitHeadSha(root, exec);
+  } catch {
+    headSha = null; // scan enforces the git-repo requirement with a clear message
+  }
+
+  let { state } = loadState(dotdir);
+  if (!state) state = defaultState({ headSha, now: nowIso() });
+
+  // Service layers (dynamic so --help / usage errors never need them).
+  const { createLLM } = await importPhase("llm");
+  const { locateAdlc } = await importPhase("adlc");
+  const llm = createLLM({ flags, state, env: process.env });
+  const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+  const adlc = locateAdlc({ env: process.env, packageRoot, targetRoot: root });
+  const { ask, close: closeAsk } = makeAsk(process.env);
+
+  if (!flags.json) console.log(colors.dim(`do-better v${VERSION} · ${flags.command} · ${root}`));
+
+  // Under --json, stdout must carry ONLY the final JSON envelope — route all
+  // phase-module progress (ctx.log.phase/step/…) to stderr (H17).
+  const activeLog = flags.json ? stderrLog : log;
+  let ctx = { root, dotdir, state, llm, adlc, flags, log: activeLog, now: nowIso, exec, ask };
+  let runId = null;
+  let paused = false;
+  let lastSummary = "";
+
+  const runPhase = async (name, fnName = "run") => {
+    const mod = await importPhase(name);
+    const fn = mod[fnName];
+    if (typeof fn !== "function") {
+      throw new OpError(`Phase module "${name}" does not export ${fnName}()`);
+    }
+    const res = await fn(ctx);
+    state = res.state;
+    ctx = { ...ctx, state };
+    saveState(dotdir, state);
+    if (res.summary) {
+      lastSummary = res.summary;
+      if (!flags.json) log.info(res.summary);
+    }
+    if (res.gate && res.gate.human && !res.gate.passed) {
+      paused = true;
+      const instructions = res.gate.detail || HUMAN_GATE_INSTRUCTIONS[res.gate.name] || "";
+      if (!flags.json && instructions) log.warn(instructions);
+    }
+    return res;
+  };
+
+  try {
+    ({ state, runId } = beginRun(state, {
+      command: flags.command,
+      provider: llm.provider ?? null,
+      headSha,
+      now: nowIso(),
+    }));
+    ctx = { ...ctx, state };
+
+    switch (flags.command) {
+      case "scan":
+        await runPhase("scan");
+        break;
+      case "charter":
+        await runPhase("charter", flags.approve ? "approve" : "run");
+        break;
+      case "audit":
+        await runPhase("comprehend");
+        if (!paused) await runPhase("identify");
+        break;
+      case "roadmap":
+        await runPhase("roadmap", flags.approve ? "approve" : "run");
+        break;
+      case "rail":
+        await runPhase("rail");
+        break;
+      case "refresh":
+        await runPhase("refresh");
+        break;
+      case "run": {
+        let next;
+        while (!paused && (next = nextIncompletePhase(state)) !== null) {
+          await runPhase(next);
+          if (paused) break;
+          if (nextIncompletePhase(state) === next) {
+            throw new OpError(`Phase "${next}" did not complete; cannot continue the pipeline.`);
+          }
+        }
+        if (!paused && nextIncompletePhase(state) === null && !flags.json) {
+          log.success(
+            "All phases complete. Each ticket in .dobetter/backlog/ is ready for ADLC P3/P4 intake.",
+          );
+        }
+        break;
+      }
+      default:
+        throw new OpError(`Unknown command: ${flags.command}`);
+    }
+
+    state = finishRun(state, runId, { now: nowIso(), ok: true });
+    saveState(dotdir, state);
+    if (flags.json) {
+      console.log(JSON.stringify({
+        command: flags.command, ok: true, paused, summary: lastSummary,
+        artifactsDir: path.relative(process.cwd(), dotdir) || ".dobetter",
+        ...stateStats(state),
+      }));
+    }
+    return 0;
+  } catch (err) {
+    if (err && err.state) state = err.state;
+    if (runId) {
+      try {
+        state = finishRun(state, runId, { now: nowIso(), ok: false });
+      } catch {
+        /* keep the original error */
+      }
+    }
+    try {
+      saveState(dotdir, state);
+    } catch {
+      /* never mask the original error with a save failure */
+    }
+    // A CI wrapper gets a parseable failure envelope on stdout (H17); the human
+    // message still prints to stderr via the top-level handler. Exit code is set
+    // there too, so the two stay consistent.
+    if (flags.json) {
+      const error = err instanceof GateError
+        ? { kind: "gate", gate: err.gate, detail: err.detail }
+        : { kind: err instanceof OpError ? "operational" : "error", message: err instanceof Error ? err.message : String(err) };
+      console.log(JSON.stringify({ command: flags.command, ok: false, error, ...stateStats(state) }));
+    }
+    throw err;
+  } finally {
+    closeAsk();
+  }
+}
+
+try {
+  process.exitCode = await main();
+} catch (err) {
+  if (err instanceof GateError) {
+    log.error(`Gate failed: ${err.gate} — ${err.detail}`);
+    if (process.env.DOBETTER_DEBUG) log.errorTrace(err);
+    process.exitCode = 2;
+  } else {
+    log.error(err instanceof Error ? err.message : String(err));
+    if (process.env.DOBETTER_DEBUG) log.errorTrace(err);
+    process.exitCode = typeof err?.exitCode === "number" ? err.exitCode : 1;
+  }
+}