@khoavu882/doflow 0.0.0-stage → 2.0.0-beta.3

package/core/shared/scripts/doflow/bin/doflow-run

@@ -0,0 +1,592 @@
+#!/usr/bin/env bash
+# doflow-run — the single runtime seam every skill calls through.
+#
+# One verb namespace (design.md §4.2), one place that decides whether a verb is served by a
+# shell helper or the Node CLI, and one place that records that a verb ran. Callers never learn
+# which side serves a verb, which is what lets a verb move between them without touching skills.
+#
+# Self-resolution is from this file's own REAL path, symlinks followed — never fixed-depth
+# `../../../..` arithmetic. Its predecessor `doflow.sh` did exactly that: installed at
+# ~/.doflow/scripts/doflow/ it computed a repo root of /Users and every Node-backed verb died
+# with "Cannot find module '/Users/bin/doflow.js'". The same script must answer identically from
+# a source checkout, a project-local `.doflow/`, a global `~/.doflow/`, and from a symlink on
+# PATH pointing at any of them.
+#
+# Usage: doflow-run <verb> [args...]
+#   Every verb accepts --json. Exit 0 = success, 1 = an actionable finding, 2 = usage or
+#   resolution error. Arguments, stdin and exit status pass through the dispatcher unmodified —
+#   `sync-context` reads its block body from stdin, so anything that buffered or consumed it here
+#   would break that verb rather than merely inconvenience it.
+
+set -euo pipefail
+
+# ------------------------------------------------------------------------------ failure capture
+
+# DoFlow's own failures, recorded on this machine (feature 046, IC-011, IC-014, IC-017). A side
+# channel: it never changes what the dispatcher prints or the status it exits with, never blocks
+# anything, and is silent. It runs in a subshell with all output discarded and ends in `|| true`, so
+# `set -euo pipefail` never stops on it; nothing in it can reach the dispatcher's own options or
+# variables. Appends one JSON line of at most 1000 bytes (longer appends from concurrent writers can
+# interleave) and never rotates: rotation is done by the Node writers only (IC-015, DEC-019). It is
+# a no-op when no failure home can be resolved (HOME unset, or XDG_CONFIG_HOME relative) and while
+# capture is off (the `off` sentinel file wins; DOFLOW_FAILURE_CAPTURE=off|0|false|no also turns it
+# off). The line carries only names from DoFlow's own tables and the working directory: never an
+# argument, stdin or the environment.
+#   capture_failure <command> <kind> <exit status>
+CAPTURE_VERB=""
+
+capture_failure_write() {
+  local command="${1:-}" kind="${2:-}" status="${3:-}"
+  local home="" setting="" version="" candidate="" project="" harness="" at="" line="" cwd="" hp=""
+  export LC_ALL=C
+
+  if [ -n "${XDG_CONFIG_HOME:-}" ]; then
+    case "$XDG_CONFIG_HOME" in
+      /*) home="$XDG_CONFIG_HOME/doflow/failures" ;;
+      *) return 0 ;;
+    esac
+  else
+    case "${HOME:-}" in
+      /*) home="$HOME/.config/doflow/failures" ;;
+      *) return 0 ;;
+    esac
+  fi
+
+  # Case-insensitive, whitespace trimmed at the ends only: the same reading the Node writer has.
+  setting="$(printf '%s' "${DOFLOW_FAILURE_CAPTURE:-}" | tr '[:upper:]' '[:lower:]')" || return 0
+  setting="${setting#"${setting%%[![:space:]]*}"}"
+  setting="${setting%"${setting##*[![:space:]]}"}"
+  case "$setting" in
+    off|0|false|no) return 0 ;;
+  esac
+  [ -f "$home/off" ] && return 0
+
+  # The command is a verb the dispatcher has already matched against its own tables, or `dispatcher`.
+  [[ "$command" =~ ^[a-z][a-z0-9-]{0,39}$ ]] || command="dispatcher"
+  [[ "$kind" =~ ^[A-Za-z][A-Za-z0-9._:-]{0,39}$ ]] || return 0
+  [[ "$status" =~ ^[0-9]{1,3}$ ]] || status="null"
+
+  harness="${DOFLOW_AGENT:-}"
+  [[ "$harness" =~ ^[A-Za-z0-9._-]{1,40}$ ]] || harness="none"
+
+  # script_version of the nearest install manifest: the project install first, then the global one.
+  for candidate in "${CONFIG_DIR:-}" "${HOME:-}/.doflow"; do
+    [ -n "$candidate" ] && [ -f "$candidate/.install-manifest.json" ] || continue
+    version="$(sed -n 's/^[[:space:]]*"script_version"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' "$candidate/.install-manifest.json" | head -n 1)" || version=""
+    [ -n "$version" ] && break
+  done
+  [[ "$version" =~ ^[A-Za-z0-9._+-]{1,40}$ ]] || version="unknown"
+
+  # The working directory, home prefix written as `~`, cut to 200 bytes, control characters turned
+  # into spaces and every quote and backslash escaped, so the line stays one valid JSON string.
+  cwd="$(pwd 2>/dev/null)" || cwd=""
+  hp="${HOME:-}"
+  hp="${hp%/}"
+  if [ -n "$hp" ]; then
+    case "$cwd" in
+      "$hp") cwd="~" ;;
+      "$hp"/*) cwd="~${cwd#"$hp"}" ;;
+    esac
+  fi
+  project="$(printf '%s' "${cwd:0:200}" | tr '\001-\037\177' ' ')" || project=""
+  project="${project//\\/\\\\}"
+  project="${project//\"/\\\"}"
+
+  at="$(date -u +%Y-%m-%dT%H:%M:%S.000Z)" || return 0
+  line="{\"v\":1,\"at\":\"$at\",\"source\":\"dispatcher\",\"command\":\"$command\",\"harness\":\"$harness\",\"version\":\"$version\",\"project\":\"$project\",\"kind\":\"$kind\",\"message\":\"\",\"frame\":null,\"exit\":$status}"
+  if [ "${#line}" -gt 999 ]; then
+    line="{\"v\":1,\"at\":\"$at\",\"source\":\"dispatcher\",\"command\":\"$command\",\"harness\":\"$harness\",\"version\":\"$version\",\"project\":\"\",\"kind\":\"$kind\",\"message\":\"\",\"frame\":null,\"exit\":$status}"
+  fi
+
+  umask 077
+  mkdir -p "$home" || return 0
+  # Only ever append to a regular file: opening a FIFO for append would block forever.
+  [ ! -e "$home/events.jsonl" ] || [ -f "$home/events.jsonl" ] || return 0
+  printf '%s\n' "$line" >>"$home/events.jsonl" || return 0
+}
+
+capture_failure() {
+  ( capture_failure_write "$@" ) >/dev/null 2>&1 || true
+  return 0
+}
+
+# After a verb ran: a status outside {0, 1, 2} is a crash worth recording (a signal, a runtime that
+# died), minus what is not DoFlow's fault (DEC-031): 127 (command not found), 130, 141 and 143
+# (interrupted, broken pipe, terminated) and the task-not-found status 3 of `task-brief`. A Node
+# crash exits 1 and is recorded by the CLI itself, so it is never counted twice.
+capture_exit_status() {
+  local verb="${1:-}" status="${2:-0}"
+  case "$status" in
+    0|1|2|127|130|141|143) return 0 ;;
+    3) [ "$verb" = "task-brief" ] && return 0 ;;
+  esac
+  capture_failure "$verb" "exit-$status" "$status"
+  return 0
+}
+
+# ---------------------------------------------------------------------------- self-resolution
+
+# `readlink -f` is GNU-only and arrived late on BSD; resolve the chain by hand so the dispatcher
+# keeps working on the oldest shell we support (macOS bash 3.2). Bounded, because a symlink loop
+# must produce a message rather than hang.
+resolve_real_dir() {
+  local src="$1" dir hops=0
+  while [ -L "$src" ]; do
+    hops=$((hops + 1))
+    if [ "$hops" -gt 40 ]; then
+      capture_failure "dispatcher" "symlink-loop" 2
+      printf 'doflow-run: symlink loop resolving %s\n' "$1" >&2
+      exit 2
+    fi
+    dir="$(cd -P "$(dirname "$src")" >/dev/null 2>&1 && pwd)"
+    src="$(readlink "$src")"
+    case "$src" in
+      /*) ;;
+       *) src="$dir/$src" ;;
+    esac
+  done
+  cd -P "$(dirname "$src")" >/dev/null 2>&1 && pwd
+}
+
+SCRIPT_DIR="$(resolve_real_dir "${BASH_SOURCE[0]}")"
+
+# The install root that owns state. Mirrors the locator's resolution order (design.md §4.1) so a
+# verb dispatched inside a project records against that project, not against wherever the
+# dispatcher itself happens to live.
+resolve_config_dir() {
+  local dir
+  if [ -n "${DOFLOW_CONFIG_DIR:-}" ]; then
+    printf '%s' "$DOFLOW_CONFIG_DIR"
+    return 0
+  fi
+  dir="$(pwd -P 2>/dev/null || pwd)"
+  while [ -n "$dir" ] && [ "$dir" != "/" ]; do
+    if [ -d "$dir/.doflow" ]; then
+      printf '%s' "$dir/.doflow"
+      return 0
+    fi
+    dir="$(dirname "$dir")"
+  done
+  # No project install above the caller: fall back to the install this dispatcher was copied
+  # into, and only then to the global one.
+  case "$SCRIPT_DIR" in
+    */.doflow/*) printf '%s' "${SCRIPT_DIR%%/.doflow/*}/.doflow"; return 0 ;;
+  esac
+  printf '%s' "${HOME:-.}/.doflow"
+}
+
+CONFIG_DIR="$(resolve_config_dir)"
+
+# Shell helpers sit beside this file in every shape shipped today (`.../doflow/bin` next to
+# `.../doflow/bash`); the third candidate covers the dispatcher being relocated to `<config>/bin`
+# without the helpers moving with it.
+resolve_bash_dir() {
+  local candidate
+  for candidate in \
+    "$SCRIPT_DIR/../bash" \
+    "$SCRIPT_DIR/bash" \
+    "$CONFIG_DIR/scripts/doflow/bash"
+  do
+    if [ -d "$candidate" ]; then
+      (cd -P "$candidate" >/dev/null 2>&1 && pwd)
+      return 0
+    fi
+  done
+  return 1
+}
+
+# A directory is the package root when it holds the CLI this dispatcher would exec AND a
+# package.json claiming the doflow name — `bin/doflow.js` alone would happily match an unrelated
+# project the install happens to sit inside.
+is_package_root() {
+  [ -f "$1/bin/doflow.js" ] &&
+  [ -f "$1/package.json" ] &&
+  grep -q '"name"[[:space:]]*:[[:space:]]*"[^"]*doflow"' "$1/package.json" 2>/dev/null
+}
+
+# Deliberately looser than is_package_root — no package.json check at all. Answers only "does a
+# file literally named bin/doflow.js exist above $PWD or $SCRIPT_DIR", used exclusively to shape
+# the exhaustion-time diagnostic in dispatch_node once every real resolution path in
+# resolve_node_cli has already failed (design.md R3). A strict check here would rarely fire in
+# that situation — after resolve_node_cli's own $PWD/$SCRIPT_DIR walk-ups, a directory that passes
+# the strict check would usually have already resolved successfully — so a false positive here
+# costs a slightly-off suggestion, never a wrong program behavior; the message is phrased as a
+# hedge for exactly that reason.
+has_doflow_marker_nearby() {
+  local dir start
+  for start in "$(pwd -P 2>/dev/null || pwd)" "$SCRIPT_DIR"; do
+    dir="$start"
+    while [ -n "$dir" ] && [ "$dir" != "/" ]; do
+      if [ -f "$dir/bin/doflow.js" ]; then
+        printf '%s' "$dir/bin/doflow.js"
+        return 0
+      fi
+      dir="$(dirname "$dir")"
+    done
+  done
+  return 1
+}
+
+# Order is most-specific-first: an explicit override, then the checkout this file lives in, then
+# the checkout the caller is standing in, then a project- or global-local projected runtime, then
+# a dependency pinned by the project, then whatever is on PATH. Answers through globals rather
+# than stdout, so a path containing whitespace needs no field separator to survive.
+NODE_CLI_KIND=""   # "script" = run with node, "bin" = an executable that runs itself
+NODE_CLI_PATH=""
+NODE_CLI_SOURCE=""  # which branch below resolved: override / checkout-script-dir /
+                     # checkout-pwd / project-runtime / global-runtime / node_modules / path
+resolve_node_cli() {
+  local dir project_root global_runtime_cli
+  if [ -n "${DOFLOW_CLI:-}" ] && [ -f "$DOFLOW_CLI" ]; then
+    NODE_CLI_KIND="script"; NODE_CLI_PATH="$DOFLOW_CLI"; NODE_CLI_SOURCE="override"
+    return 0
+  fi
+  dir="$SCRIPT_DIR"
+  while [ -n "$dir" ] && [ "$dir" != "/" ]; do
+    if is_package_root "$dir"; then
+      NODE_CLI_KIND="script"; NODE_CLI_PATH="$dir/bin/doflow.js"; NODE_CLI_SOURCE="checkout-script-dir"
+      return 0
+    fi
+    dir="$(dirname "$dir")"
+  done
+  # Same walk-up, started from where the caller is standing rather than where this dispatcher
+  # lives — lets a verb resolve correctly when the dispatcher being run is the global one but the
+  # caller is standing inside the actual checkout (e.g. dogfooding without `npm link`).
+  dir="$(pwd -P 2>/dev/null || pwd)"
+  while [ -n "$dir" ] && [ "$dir" != "/" ]; do
+    if is_package_root "$dir"; then
+      NODE_CLI_KIND="script"; NODE_CLI_PATH="$dir/bin/doflow.js"; NODE_CLI_SOURCE="checkout-pwd"
+      return 0
+    fi
+    dir="$(dirname "$dir")"
+  done
+  # The runtime projected alongside this dispatcher. This is the step that makes Node-backed verbs
+  # work for someone who ran `npx @khoavu882/doflow install` and nothing else: npx leaves no package
+  # behind, the install directory is not inside a checkout, and nothing lands on PATH — so before
+  # the `runtime.*` assets shipped, every Node-backed verb answered `cli-not-found` in every real
+  # install while passing in every test, because tests run inside a checkout. Layout under
+  # runtime/ mirrors the repo (bin/, src/, core/registry/) so the modules' own
+  # `path.resolve(__dirname, '..', '..')` finds the registries without any path rewriting.
+  if [ -f "$CONFIG_DIR/runtime/bin/doflow.js" ]; then
+    NODE_CLI_KIND="script"; NODE_CLI_PATH="$CONFIG_DIR/runtime/bin/doflow.js"; NODE_CLI_SOURCE="project-runtime"
+    return 0
+  fi
+  # Same runtime layout, but under the global install — covers a project-local `.doflow/` that
+  # exists but is only partial (e.g. `state/`/`worktrees/` with no `runtime/` of its own), where
+  # CONFIG_DIR resolved to that project rather than to $HOME/.doflow. Skipped when it's the exact
+  # same path already tried above (CONFIG_DIR already IS $HOME/.doflow), to avoid a redundant stat.
+  global_runtime_cli="${HOME:-}/.doflow/runtime/bin/doflow.js"
+  if [ -n "${HOME:-}" ] && [ "$global_runtime_cli" != "$CONFIG_DIR/runtime/bin/doflow.js" ] && [ -f "$global_runtime_cli" ]; then
+    NODE_CLI_KIND="script"; NODE_CLI_PATH="$global_runtime_cli"; NODE_CLI_SOURCE="global-runtime"
+    return 0
+  fi
+  project_root="$(dirname "$CONFIG_DIR")"
+  if [ -f "$project_root/node_modules/@khoavu882/doflow/bin/doflow.js" ]; then
+    NODE_CLI_KIND="script"; NODE_CLI_PATH="$project_root/node_modules/@khoavu882/doflow/bin/doflow.js"; NODE_CLI_SOURCE="node_modules"
+    return 0
+  fi
+  if command -v doflow >/dev/null 2>&1; then
+    NODE_CLI_KIND="bin"; NODE_CLI_PATH="$(command -v doflow)"; NODE_CLI_SOURCE="path"
+    return 0
+  fi
+  return 1
+}
+
+# ---------------------------------------------------------------------------------- reporting
+
+wants_json=false
+for _arg in "$@"; do
+  [ "$_arg" = "--json" ] && wants_json=true
+done
+
+# Dispatcher-level failures answer in the caller's requested shape; a caller that asked for JSON
+# and got a bare English sentence has to special-case the dispatcher, which defeats the uniform
+# contract.
+fail() {
+  local code="$1" reason="$2" message="$3" escaped
+  # A broken DoFlow install is worth recording; the other reasons are the caller's mistake or the
+  # user's environment (DEC-031) and are not.
+  case "$reason" in
+    helper-missing|helpers-not-found) capture_failure "${CAPTURE_VERB:-dispatcher}" "$reason" "$code" ;;
+  esac
+  if [ "$wants_json" = true ]; then
+    # Messages quote resolved paths, and a path is allowed to contain a quote or a backslash;
+    # unescaped, one such path turns an error report into unparseable JSON.
+    escaped="${message//\\/\\\\}"
+    escaped="${escaped//\"/\\\"}"
+    printf '{"ok":false,"error":"%s","message":"%s"}\n' "$reason" "$escaped" >&2
+  else
+    printf 'doflow-run: %s\n' "$message" >&2
+  fi
+  exit "$code"
+}
+
+usage() {
+  cat <<'EOF'
+doflow-run <verb> [args...] — the DoFlow runtime seam
+
+Every verb accepts --json and reports on stdout. Exit 0 = success,
+1 = an actionable finding, 2 = a usage or resolution error. sync-context is the
+one verb whose result is a file write rather than a report, so it acknowledges
+in plain text and --json changes nothing.
+
+Artifact and repository state:
+  paths            resolve repo root, branch, feature slug, artifact paths
+  validate         artifact index/detail consistency check
+  render-audit     regenerate audit.md from the orchestration journal
+  render-diagrams  render a chain artifact's mermaid blocks to image files
+  render-puml      render authored PlantUML sources and project them inline
+  git-state        branch class and derived branch names
+  prereqs          stage prerequisite checks
+  parallel-check   dispatch groups and write-set collisions for one plan phase
+  task-brief       task brief extraction for execution
+  brief-tools      tier, tools and report-format block for a brief (called by task-brief)
+  advise           local decision-model routing, outcomes and configuration
+  review-package   assemble a review payload
+  sync-context     write a marker-delimited block (stdin) into an agent context file
+
+Workflow and evidence:
+  classify         validate a proposed task class, return its workflow
+  workflow         resolve stages, dependencies and gates for a class
+  orchestrate      start/resume a run: complete stages, skip optional ones, decide gates
+  research-request  open, list or resolve a feature-stage research question
+  task-attempt     claim, finish, release or read the attempts on a plan's tasks
+  retrieve         BM25 search over the installed guidance tree (auto-refreshing index)
+  model-role       resolve an abstract model role to ranked, availability-annotated providers
+  route            resolve an information need to a healthy provider
+  evidence         record a stage's evidence batch, or query the ledger
+  claim            record or update a claim and its support state
+  readiness        evaluate readiness; return state and missing items
+  context-pack     emit the compiled context pack for a stage
+  retrieval-plan   declare the needs a stage will resolve, then report every declared item
+  outcome          record a task's terminal state with its basis, or show what was recorded
+  scaffold         emit the code scaffold the active feature's artifacts imply
+  decision         register, list or compact the active feature's decisions
+  followup         record, list, take, settle, promote or report what a feature left unfinished
+  lifecycle        overview, init, status, release or merged: follow-ups and feature tracking for the project
+  goal             add, check, link, list or close a goal and its checklist
+  failure          list, settle or switch off the failures DoFlow captured on this machine
+
+Verification and recovery:
+  verify           compile the contract, run checks, emit the report
+  recover          classify a failure, return the targeted action
+  leak-scan        report DoFlow-internal identifiers in shipped files
+
+Observability:
+  trace            current run trajectory
+  stats            aggregate run usage
+  indicators       per-stage and per-gate timings from the orchestration record
+  discover         missed opportunities in recorded runs
+  inventory        both scopes at once: shadowed assets, drift, unmanaged contenders
+  capabilities     provider resolution
+  doctor           installation and provider health
+  storage          report stored data and its retention bounds
+EOF
+}
+
+# ------------------------------------------------------------------------------------- clocks
+
+# Millisecond clocks are not portable: EPOCHREALTIME is bash 5+, `date +%N` exists on GNU and on
+# recent BSD but the GNU width modifier `%3N` does not, and older BSD has neither. Probe once and
+# keep the answer. The perl path pays its own interpreter startup inside the measured span, so
+# durations recorded through it read a few milliseconds high — accepted, because the alternative
+# on such a host is whole-second granularity.
+detect_clock() {
+  local nanos
+  if [ -n "${EPOCHREALTIME:-}" ]; then printf 'bash'; return 0; fi
+  # Require exactly nine digits: `%s%N` is only safe to read as one number when %N is
+  # zero-padded, and a date that prints a literal "N" fails this test rather than poisoning
+  # every duration with a non-numeric suffix.
+  nanos="$(date -u +%N 2>/dev/null || true)"
+  case "$nanos" in
+    [0-9][0-9][0-9][0-9][0-9][0-9][0-9][0-9][0-9]) printf 'nanos'; return 0 ;;
+  esac
+  if command -v perl >/dev/null 2>&1; then printf 'perl'; return 0; fi
+  printf 'seconds'
+}
+
+CLOCK="$(detect_clock)"
+
+now_ms() {
+  local raw
+  case "$CLOCK" in
+    bash)
+      raw="${EPOCHREALTIME/./}"
+      printf '%s' "${raw:0:13}"
+      ;;
+    nanos)
+      # One call, not %s then %N, so the reading cannot straddle a second boundary.
+      printf '%s' "$(( $(date -u +%s%N) / 1000000 ))"
+      ;;
+    perl)
+      perl -MTime::HiRes -e 'printf "%d", Time::HiRes::time() * 1000'
+      ;;
+    *)
+      printf '%s' "$(( $(date -u +%s) * 1000 ))"
+      ;;
+  esac
+}
+
+# --------------------------------------------------------------------------------- run ledger
+
+# One metadata record per dispatched verb (FR-011). Metadata ONLY — the verb name comes from the
+# dispatcher's own table and the argument count is a count, so no argument value, no command
+# output and no file content can reach the ledger (NFR-004).
+#
+# Tracing never changes what a verb returned. Every step is failure-tolerant and the function
+# always succeeds: an unwritable state directory degrades observability, not the run.
+trace_run() {
+  local verb="$1" code="$2" duration="$3" argc="$4" started_at="$5"
+  local runs_dir="$CONFIG_DIR/state/runs"
+  mkdir -p "$runs_dir" 2>/dev/null || return 0
+  printf '{"timestamp":"%s","verb":"%s","exit_code":%s,"duration_ms":%s,"arg_count":%s}\n' \
+    "$started_at" "$verb" "$code" "$duration" "$argc" \
+    >>"$runs_dir/$(date -u +%Y-%m-%d).jsonl" 2>/dev/null || return 0
+  return 0
+}
+
+# ----------------------------------------------------------------------------------- dispatch
+
+# The two arms of the verb table (design.md §4.2). Together they also answer "is this a verb at
+# all", so there is no third list to keep in step.
+#
+# Every helper a *skill* names has to appear here, or that skill has no way to reach it except by
+# inlining its own resolver — the exact pattern C.4 removes. `do-parallel-check.sh` and
+# `sync-context.sh` are here for that reason and no other. `do-exec-paths.sh` deliberately is not:
+# it is called by do-task-brief.sh and do-review-package.sh, never by a skill, so exposing it would
+# widen the public surface without removing a single resolver.
+shell_helper_for() {
+  case "$1" in
+    paths)          printf 'do-paths.sh' ;;
+    validate)       printf 'validate-artifacts.sh' ;;
+    render-audit)   printf 'render-audit.sh' ;;
+    render-diagrams) printf 'render-diagrams.sh' ;;
+    render-puml)    printf 'render-puml.sh' ;;
+    git-state)      printf 'do-git-state.sh' ;;
+    prereqs)        printf 'do-prereqs.sh' ;;
+    parallel-check) printf 'do-parallel-check.sh' ;;
+    task-brief)     printf 'do-task-brief.sh' ;;
+    review-package) printf 'do-review-package.sh' ;;
+    sync-context)   printf 'sync-context.sh' ;;
+    *) return 1 ;;
+  esac
+}
+
+# The whole Node namespace, including the verbs later phases still have to build. Tracking which
+# of them the CLI implements *today* would mean a second inventory drifting against the CLI's own
+# command list; an unbuilt verb is dispatched and the CLI answers for itself.
+is_node_verb() {
+  case "$1" in
+    classify|workflow|route|evidence|claim|readiness|context-pack|retrieval-plan|outcome|scaffold|decision|followup|lifecycle|goal|failure|verify|recover|leak-scan|\
+trace|stats|indicators|discover|inventory|capabilities|doctor|orchestrate|research-request|task-attempt|retrieve|model-role|storage|brief-tools|advise) return 0 ;;
+    *) return 1 ;;
+  esac
+}
+
+dispatch_shell() {
+  local verb="$1"; shift
+  local helper bash_dir script
+  helper="$(shell_helper_for "$verb")"
+  if ! bash_dir="$(resolve_bash_dir)"; then
+    fail 2 "helpers-not-found" \
+      "cannot locate the shell helpers; searched $SCRIPT_DIR/../bash, $SCRIPT_DIR/bash and $CONFIG_DIR/scripts/doflow/bash"
+  fi
+  script="$bash_dir/$helper"
+  [ -f "$script" ] || fail 2 "helper-missing" "verb '$verb' needs $script, which does not exist"
+  bash "$script" "$@"
+}
+
+dispatch_node() {
+  local verb="$1"; shift
+  local marker tmpfile rc first_line
+  if ! resolve_node_cli; then
+    if marker="$(has_doflow_marker_nearby)"; then
+      fail 2 "unlinked-checkout" \
+        "verb '$verb' is served by the Node CLI, which could not be located; a file named bin/doflow.js was found near here ($marker) — if this is a doflow checkout, running \`npm link\` may resolve this"
+    fi
+    fail 2 "cli-not-found" \
+      "verb '$verb' is served by the Node CLI, which could not be located; set DOFLOW_CLI to a doflow.js path, install the package (npm i -g @khoavu882/doflow), or run from a checkout"
+  fi
+  if [ "$NODE_CLI_KIND" = "script" ]; then
+    command -v node >/dev/null 2>&1 || fail 2 "node-not-found" \
+      "verb '$verb' needs node on PATH to run $NODE_CLI_PATH"
+    case "$NODE_CLI_SOURCE" in
+      project-runtime|global-runtime)
+        # These two sources are a *projected copy* of the runtime, not the checkout itself, so
+        # they can drift out of sync with the working tree's registry. Stdout still streams
+        # directly; only stderr is captured, so a version-drift crash can be told apart from a
+        # verb legitimately reporting a finding (e.g. readiness's NEEDS_EVIDENCE) before either
+        # reaches the caller.
+        tmpfile="$(mktemp)"
+        trap 'rm -f "$tmpfile" 2>/dev/null || true' EXIT
+        rc=0
+        node "$NODE_CLI_PATH" "$verb" "$@" 2>"$tmpfile" || rc=$?
+        if [ "$rc" -ne 0 ]; then
+          first_line=""
+          IFS= read -r first_line <"$tmpfile" || true
+          # Matched loosely (not anchored to position 0): bin/doflow.js's own top-level catch
+          # prepends "[ERROR] " to every thrown message before it ever reaches stderr, so an
+          # anchored match against the registry loader's raw prefix never fires in practice.
+          case "$first_line" in
+            *"Invalid DoFlow registry:"*)
+              fail 2 "stale-runtime" \
+                "verb '$verb' failed against $NODE_CLI_PATH, which appears out of date relative to the working checkout; reinstall or re-run the doflow installer to refresh it"
+              ;;
+          esac
+        fi
+        cat "$tmpfile" >&2
+        rm -f "$tmpfile"
+        trap - EXIT
+        return "$rc"
+        ;;
+      *)
+        node "$NODE_CLI_PATH" "$verb" "$@"
+        ;;
+    esac
+  else
+    "$NODE_CLI_PATH" "$verb" "$@"
+  fi
+}
+
+main() {
+  local verb rc started_ms started_at ended_ms argc
+
+  verb="${1:-}"
+  case "$verb" in
+    "")
+      usage >&2
+      fail 2 "no-verb" "no verb given"
+      ;;
+    -h|--help|help)
+      usage
+      exit 0
+      ;;
+  esac
+  shift
+
+  if ! shell_helper_for "$verb" >/dev/null 2>&1 && ! is_node_verb "$verb"; then
+    fail 2 "unknown-verb" "unknown verb '$verb' — run 'doflow-run --help' for the verb list"
+  fi
+
+  CAPTURE_VERB="$verb"
+  argc=$#
+  started_at="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+  started_ms="$(now_ms)"
+
+  # `|| rc=$?` rather than a bare call: the verb's exit code is the dispatcher's exit code, and
+  # under `set -e` a failing verb would otherwise abort before the run is ever recorded.
+  rc=0
+  if shell_helper_for "$verb" >/dev/null 2>&1; then
+    dispatch_shell "$verb" "$@" || rc=$?
+  else
+    dispatch_node "$verb" "$@" || rc=$?
+  fi
+
+  ended_ms="$(now_ms)"
+  trace_run "$verb" "$rc" "$(( ended_ms - started_ms ))" "$argc" "$started_at" || true
+  capture_exit_status "$verb" "$rc"
+
+  exit "$rc"
+}
+
+main "$@"