@data-matters.io/agent-harness 0.0.0-stage → 0.1.1

package/templates/.github/workflows/gates.yml

@@ -0,0 +1,41 @@
+name: gates
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+jobs:
+  gates:
+    runs-on: ubuntu-latest
+    steps:
+      # fetch-depth 2: HEAD is the PR merge commit and HEAD^1 its base, enough
+      # to list the files the pull request changes.
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 2
+
+      # TODO: toolchain setup and dependency install for this project's stack
+      # (see .harness/standards/stack.md): actions/setup-node, then
+      # pnpm/action-setup@v6.1.0 (reads package.json#packageManager; ADR 0014)
+      # and `pnpm install --frozen-lockfile`. Every step below needs it: OpenSpec
+      # is a pinned devDependency, and a harness installed from the package
+      # (ADR 0021) generates .harness/ during the install.
+
+      - name: Check the harness
+        run: if [[ -x node_modules/.bin/harness ]]; then node_modules/.bin/harness check; fi
+
+      # Spec-only PRs (ADR 0011, 0013) validate the specs instead of running the
+      # DoD gates; pr-scope.sh also fails a spec/<id> PR that changes anything
+      # outside openspec/changes/<id>/. Pushes to main always run the gates.
+      - name: Classify pull request
+        id: scope
+        run: .harness/pr-scope.sh >>"$GITHUB_OUTPUT"
+
+      - name: Validate OpenSpec changes and specs
+        if: steps.scope.outputs.spec_only == 'true'
+        run: .harness/openspec.sh validate --all --strict --no-interactive
+
+      - name: Run DoD gates
+        if: steps.scope.outputs.spec_only != 'true'
+        run: .harness/gates.sh

package/templates/.harness/db-smoke.sh

@@ -0,0 +1,75 @@
+#!/usr/bin/env bash
+# Database smoke gate (ADR 0016): applies the migrations and runs the seed on an
+# empty PostgreSQL, through the same Prisma setup the app uses. Unit tests mock
+# the database, so this is the gate that sees a broken migration, seed or driver.
+#
+# Usage: .harness/db-smoke.sh <migrate-command> <seed-command> [<check-command>]
+#   e.g. in gates.conf:
+#   GATE_EXTRA=("db:.harness/db-smoke.sh '$bin/prisma migrate deploy' '$bin/prisma db seed'")
+#
+# A seed that does not run fails too: `prisma db seed` exits 0 when no seed is
+# configured, so its output must show that the seed command was executed.
+#
+# Database: HARNESS_DB_SMOKE_URL when set (CI: the postgres service of gates.yml),
+# otherwise a throwaway container (docker or podman) removed afterwards. Without
+# a container runtime it fails; skip it on such a machine with
+# HARNESS_SKIP_GATES=db (CI still runs it). The commands get DATABASE_URL.
+#
+# Environment:
+#   HARNESS_DB_SMOKE_URL    use this database instead of a container
+#   HARNESS_DB_SMOKE_IMAGE  container image (default postgres:16-alpine)
+set -euo pipefail
+
+usage() { sed -n '2,20p' "$0" | sed 's/^# \{0,1\}//'; exit "${1:-0}"; }
+die() { echo "db-smoke: $*" >&2; exit 1; }
+
+[[ "${1:-}" == "-h" || "${1:-}" == "--help" ]] && usage 0
+[[ $# -ge 2 ]] || usage 1
+
+url="${HARNESS_DB_SMOKE_URL:-}"
+runtime="" container=""
+cleanup() { if [[ -n "$container" ]]; then "$runtime" rm -f "$container" >/dev/null 2>&1 || true; fi; }
+trap cleanup EXIT
+
+if [[ -z "$url" ]]; then
+  for candidate in docker podman; do
+    if command -v "$candidate" >/dev/null 2>&1 && "$candidate" info >/dev/null 2>&1; then runtime="$candidate"; break; fi
+  done
+  [[ -n "$runtime" ]] || die "no usable container runtime; set HARNESS_SKIP_GATES=db on this machine (CI still runs it)"
+  password="smoke$RANDOM$RANDOM"
+  container="$("$runtime" run -d --rm -e POSTGRES_USER=smoke -e POSTGRES_PASSWORD="$password" -e POSTGRES_DB=smoke \
+    -p 127.0.0.1::5432 "${HARNESS_DB_SMOKE_IMAGE:-postgres:16-alpine}")" || die "could not start a PostgreSQL container"
+  port="$("$runtime" port "$container" 5432/tcp | head -n1 | sed 's/.*://')"
+  # TCP only answers once the image's init server is gone and the real one is up.
+  for (( i = 0; i < 60; i++ )); do
+    "$runtime" exec "$container" pg_isready -q -h 127.0.0.1 -U smoke -d smoke 2>/dev/null && break
+    sleep 1
+  done
+  "$runtime" exec "$container" pg_isready -q -h 127.0.0.1 -U smoke -d smoke || die "PostgreSQL did not become ready"
+  url="postgresql://smoke:$password@127.0.0.1:$port/smoke"
+fi
+
+export DATABASE_URL="$url"
+# Prisma runs the seed command from its config (e.g. `tsx db/seed.ts`) the way
+# pnpm scripts do: with the project's binaries on PATH.
+export PATH="$PWD/node_modules/.bin:$PATH"
+echo "db-smoke: migrate: $1"
+bash -c "$1" || die "migrations failed"
+echo "db-smoke: seed: $2"
+seed_log="$(mktemp)"
+trap 'rm -f "$seed_log"; cleanup' EXIT
+bash -c "$2" 2>&1 | tee "$seed_log"
+[[ "${PIPESTATUS[0]}" -eq 0 ]] || die "seed failed"
+# `prisma db seed` exits 0 when no seed is configured (Prisma 7 reads only
+# migrations.seed in prisma.config.ts): that is a seed that never ran.
+if grep -qi 'No seed command configured' "$seed_log"; then
+  die "no seed ran: Prisma found no seed command (Prisma 7 reads migrations.seed in prisma.config.ts)"
+fi
+if [[ "$2" == *"prisma db seed"* ]] && ! grep -q 'seed command has been executed' "$seed_log"; then
+  die "no seed ran: Prisma did not report executing the seed command"
+fi
+if [[ -n "${3:-}" ]]; then
+  echo "db-smoke: check: $3"
+  bash -c "$3" || die "check failed"
+fi
+echo "db-smoke: migrations and seed passed"

package/templates/.harness/deps.sh

@@ -0,0 +1,219 @@
+#!/usr/bin/env bash
+# Dependencies an approved spec declares (ADR 0015): checks the declaration and
+# installs exactly those packages, touching nothing else.
+#
+# Usage: .harness/deps.sh check <change-dir>     validate the declaration (spec-pr.sh)
+#        .harness/deps.sh list <change-dir>      print it, one "kind name version" per line
+#        .harness/deps.sh install <change-dir>   add what package.json lacks (run-tasks.sh)
+#
+# The declaration is the "## Dependencies" section of <change-dir>/design.md.
+# Every bullet in it is one of:
+#   - dependency: <name>@<x.y.z>
+#   - devDependency: <name>@<x.y.z>
+#   - allow-build: <name>        (lets an installed package run its install script)
+# Values may be in backticks; other text in the section is prose.
+#
+# install runs `pnpm add --save-exact` without a terminal. A package with an
+# install script that is not declared as allow-build is denied in
+# pnpm-workspace.yaml (`allowBuilds: <name>: false`). Afterwards it verifies that
+# only the declared entries were added to package.json, that no locked package
+# was removed or changed version, and that pnpm-workspace.yaml only gained
+# allowBuilds entries. On any surprise it restores the files and exits 2.
+#
+# Exit codes: 0 ok, 1 usage or invalid declaration, 2 install refused.
+#
+# Environment:
+#   HARNESS_DEPS_TIMEOUT   seconds per pnpm call (default 600)
+#   HARNESS_DEPS_OFFLINE   1 = check skips the registry lookup
+set -euo pipefail
+
+usage() { sed -n '2,27p' "$0" | sed 's/^# \{0,1\}//'; exit "${1:-0}"; }
+die() { echo "deps: $*" >&2; exit 1; }
+refuse() { echo "deps: $*" >&2; exit 2; }
+
+[[ $# -eq 2 ]] || usage 1
+cmd="$1"
+change_dir="${2%/}"
+design="$change_dir/design.md"
+
+name_re='(@[a-z0-9][a-z0-9._-]*/)?[a-z0-9][a-z0-9._-]*'
+version_re='[0-9]+\.[0-9]+\.[0-9]+(-[0-9A-Za-z.-]+)?'
+
+# section: the lines of "## Dependencies" in design.md (empty when absent).
+section() {
+  [[ -f "$design" ]] || return 0
+  awk '/^## /{ on = ($0 ~ /^## Dependencies[[:space:]]*$/); next } on' "$design"
+}
+
+# parse: prints "kind name version" per declared entry (version "-" for
+# allow-build); fails on a bullet that does not follow the grammar.
+parse() {
+  local line body kind value bad=0
+  while IFS= read -r line; do
+    [[ "$line" =~ ^[[:space:]]*[-*][[:space:]]+(.*)$ ]] || continue
+    body="${BASH_REMATCH[1]//\`/}"
+    if [[ "$body" =~ ^(dependency|devDependency|allow-build):[[:space:]]*([^[:space:]]+)[[:space:]]*$ ]]; then
+      kind="${BASH_REMATCH[1]}"
+      value="${BASH_REMATCH[2]}"
+      if [[ "$kind" == allow-build ]]; then
+        if [[ "$value" =~ ^${name_re}$ ]]; then echo "$kind $value -"; continue; fi
+      elif [[ "$value" =~ ^(${name_re})@(${version_re})$ ]]; then
+        echo "$kind ${BASH_REMATCH[1]} ${BASH_REMATCH[3]}"
+        continue
+      fi
+    fi
+    echo "deps: $design: '${line#"${line%%[![:space:]]*}"}' is not '- dependency|devDependency: <name>@<x.y.z>' or '- allow-build: <name>'" >&2
+    bad=1
+  done < <(section)
+  return "$bad"
+}
+
+declared="$(parse)" || die "invalid ## Dependencies section in $design"
+
+case "$cmd" in
+  list)
+    [[ -z "$declared" ]] || echo "$declared"
+    exit 0 ;;
+  check)
+    if [[ -n "$declared" && "${HARNESS_DEPS_OFFLINE:-0}" != 1 ]]; then
+      while read -r kind name version; do
+        [[ "$kind" == allow-build ]] && continue
+        found="$(pnpm view "$name@$version" version 2>/dev/null </dev/null || true)"
+        [[ "$found" == "$version" ]] || die "$name@$version is not published in the registry"
+      done <<<"$declared"
+    fi
+    echo "deps: $(grep -c . <<<"$declared" || true) declared entr(y/ies) in $design are valid"
+    exit 0 ;;
+  install) ;;
+  *) usage 1 ;;
+esac
+
+# ---------------------------------------------------------------- install --
+
+[[ -f package.json ]] || die "run it from the project root (no package.json here)"
+[[ -n "$declared" ]] || { echo "deps: nothing declared"; exit 0; }
+
+# current <section> <name>: the specifier package.json has for it, if any.
+current() {
+  node -e 'const p = require("./package.json"); process.stdout.write((p[process.argv[1]] || {})[process.argv[2]] || "")' "$1" "$2"
+}
+
+prod=() dev=() allow=() wanted=()
+while read -r kind name version; do
+  case "$kind" in
+    allow-build) allow+=("$name"); continue ;;
+    dependency) section_name=dependencies other=devDependencies ;;
+    devDependency) section_name=devDependencies other=dependencies ;;
+  esac
+  have="$(current "$section_name" "$name")"
+  [[ -z "$(current "$other" "$name")" ]] || refuse "$name is in $other, the spec declares it as $kind"
+  if [[ "$have" == "$version" ]]; then continue; fi
+  [[ -z "$have" ]] || refuse "package.json has $name $have, the spec declares $version; changing it needs a spec change"
+  wanted+=("$section_name $name $version")
+  if [[ "$kind" == dependency ]]; then prod+=("$name@$version"); else dev+=("$name@$version"); fi
+done <<<"$declared"
+if [[ ${#wanted[@]} -eq 0 ]]; then
+  echo "deps: every declared dependency is already in package.json"
+  exit 0
+fi
+
+dep_files=(package.json pnpm-lock.yaml pnpm-workspace.yaml)
+[[ -z "$(git status --porcelain -- "${dep_files[@]}")" ]] || refuse "dependency files have uncommitted changes"
+status_before="$(git status --porcelain --untracked-files=all | grep -vE ' (package.json|pnpm-lock.yaml|pnpm-workspace.yaml)$' || true)"
+before="$(mktemp -d)"
+trap 'rm -rf "$before"' EXIT
+cp package.json "$before/package.json"
+[[ -f pnpm-lock.yaml ]] && cp pnpm-lock.yaml "$before/pnpm-lock.yaml"
+[[ -f pnpm-workspace.yaml ]] && cp pnpm-workspace.yaml "$before/pnpm-workspace.yaml"
+
+restore() {
+  local f
+  for f in "${dep_files[@]}"; do
+    if git ls-files --error-unmatch "$f" >/dev/null 2>&1; then git checkout -q -- "$f"; else rm -f "$f"; fi
+  done
+  refuse "$1"
+}
+
+# pnpm_add <flags...> -- <specs...>: one non-interactive pnpm add. A package with
+# an undeclared install script is denied and the add is repeated once.
+pnpm_add() {
+  local flags=() specs=() out denied=() name a
+  while [[ "$1" != -- ]]; do flags+=("$1"); shift; done
+  shift
+  specs=("$@")
+  for a in "${allow[@]}"; do flags+=(--allow-build "$a"); done
+  if out="$(CI=1 timeout "${HARNESS_DEPS_TIMEOUT:-600}" pnpm add --save-exact "${flags[@]}" "${specs[@]}" </dev/null 2>&1)"; then
+    printf '%s\n' "$out"
+    return 0
+  fi
+  printf '%s\n' "$out"
+  grep -q ERR_PNPM_IGNORED_BUILDS <<<"$out" || return 1
+  while read -r name; do
+    [[ -n "$name" ]] && denied+=(--allow-build "!$name")
+  done < <(grep -oE 'Ignored build scripts: .*' <<<"$out" | sed 's/^Ignored build scripts: //' | tr ',' '\n' \
+    | sed -E 's/^[[:space:]]+//; s/[[:space:]]+$//; s/@[^@]+$//')
+  [[ ${#denied[@]} -gt 0 ]] || return 1
+  echo "deps: denying install scripts not declared as allow-build:$(printf ' %s' "${denied[@]}" | sed 's/ --allow-build !/ /g')"
+  CI=1 timeout "${HARNESS_DEPS_TIMEOUT:-600}" pnpm add --save-exact "${flags[@]}" "${denied[@]}" "${specs[@]}" </dev/null 2>&1
+}
+
+if [[ ${#prod[@]} -gt 0 ]]; then pnpm_add -- "${prod[@]}" || restore "pnpm add ${prod[*]} failed"; fi
+if [[ ${#dev[@]} -gt 0 ]]; then pnpm_add --save-dev -- "${dev[@]}" || restore "pnpm add -D ${dev[*]} failed"; fi
+
+# ----------------------------------------------------------------- verify --
+
+# package.json: exactly the declared entries were added, nothing else changed.
+if ! node -e '
+  const fs = require("fs");
+  const [beforeFile, ...wanted] = process.argv.slice(1);
+  const a = JSON.parse(fs.readFileSync(beforeFile, "utf8")), b = JSON.parse(fs.readFileSync("package.json", "utf8"));
+  for (const w of wanted) { const [s, n, v] = w.split(" "); a[s] = { ...(a[s] || {}), [n]: v }; }
+  const norm = (o) => JSON.stringify(o, Object.keys(o).sort());
+  for (const k of new Set([...Object.keys(a), ...Object.keys(b)])) {
+    const x = a[k], y = b[k];
+    const same = (x && typeof x === "object" && y && typeof y === "object") ? norm(x) === norm(y) : JSON.stringify(x) === JSON.stringify(y);
+    if (!same) { console.error("deps: package.json field " + k + " differs from the declaration"); process.exit(1); }
+  }' "$before/package.json" "${wanted[@]}"; then
+  restore "package.json changed beyond the declared dependencies"
+fi
+
+# lock_keys <file>: locked packages and snapshots.
+lock_keys() {
+  [[ -f "$1" ]] || return 0
+  awk '/^---/{ sec = ""; next } /^[A-Za-z]/{ sec = $0; next }
+       (sec == "packages:" || sec == "snapshots:") && /^  [^ ]/ { k = $0; sub(/^ +/, "", k); gsub(/'\''/, "", k); print sec k }' "$1" | sort -u
+}
+# importer_versions <file>: "name version" of every direct dependency.
+importer_versions() {
+  [[ -f "$1" ]] || return 0
+  awk '/^---/{ sec = ""; next } /^[A-Za-z]/{ sec = $0; next }
+       sec == "importers:" && /^      [^ ].*:$/ { n = $0; sub(/^ +/, "", n); sub(/:$/, "", n); gsub(/'\''/, "", n); next }
+       sec == "importers:" && /^        version: / { v = $0; sub(/^ +version: /, "", v); print n " " v }' "$1" | sort -u
+}
+
+removed="$(comm -23 <(lock_keys "$before/pnpm-lock.yaml") <(lock_keys pnpm-lock.yaml))"
+[[ -z "$removed" ]] || restore "the lockfile lost or changed locked packages (other dependencies would move):
+$(head -n 20 <<<"$removed")"
+
+added_names=" $(printf '%s\n' "${wanted[@]}" | awk '{ print $2 }' | tr '\n' ' ')"
+moved="$(comm -3 <(importer_versions "$before/pnpm-lock.yaml") <(importer_versions pnpm-lock.yaml) \
+  | sed 's/^[[:space:]]*//' | while read -r n v; do [[ "$added_names" == *" $n "* ]] || echo "$n $v"; done)"
+[[ -z "$moved" ]] || restore "direct dependencies outside the declaration changed:
+$moved"
+
+if [[ -f pnpm-workspace.yaml ]]; then
+  unexpected="$(diff "$before/pnpm-workspace.yaml" pnpm-workspace.yaml 2>/dev/null | grep -E '^[<>]' \
+    | grep -vE "^> +'?${name_re}'?: (true|false)$" | grep -vE '^> allowBuilds:$' || true)"
+  if [[ ! -f "$before/pnpm-workspace.yaml" ]]; then
+    unexpected="$(grep -vE "^ +'?${name_re}'?: (true|false)$|^allowBuilds:$|^$" pnpm-workspace.yaml || true)"
+  fi
+  [[ -z "$unexpected" ]] || restore "pnpm-workspace.yaml changed beyond allowBuilds entries:
+$unexpected"
+fi
+
+others="$(comm -13 <(sort <<<"$status_before") \
+  <(git status --porcelain --untracked-files=all | grep -vE ' (package.json|pnpm-lock.yaml|pnpm-workspace.yaml)$' | sort) || true)"
+[[ -z "$others" ]] || restore "pnpm add changed other files:
+$others"
+
+echo "deps: added ${wanted[*]}"

package/templates/.harness/gates.conf.example

@@ -0,0 +1,31 @@
+# Gate commands for this project. Sourced by .harness/gates.sh.
+# Each command runs with `bash -c` from the repo root; exit 0 = pass.
+#
+# Required gates: test, lint, typecheck, build.
+# An empty/unset required gate FAILS. To skip one deliberately, use
+#   GATE_X="skip:<reason>"
+# and revisit it: the reason is printed on every run.
+
+GATE_TEST=""
+GATE_LINT=""        # must include architecture rules (see .harness/standards/stack/architecture.md)
+GATE_TYPECHECK=""
+GATE_BUILD=""
+
+# Optional: command run once before the gates (code generation, etc.).
+# Its failure fails the whole run.
+GATE_SETUP=""
+
+# Optional: command that formats the OpenSpec files, run from the repo root by
+# the archive PR action (the archive output is not formatted; ADR 0022).
+# Empty = no formatting step.
+FORMAT_SPECS=""
+
+# Gates run by the Claude Code Stop hook (fast profile). Empty = all gates.
+# The task loop and CI always run every gate.
+STOP_GATES=()
+
+# Optional extra gates, run after the required ones, in order: "name:command".
+GATE_EXTRA=(
+  # "coverage:npm run test:coverage -- --coverage.thresholds.lines=80"
+  # "security:npm audit --audit-level=high"
+)

package/templates/.harness/gates.sh

@@ -0,0 +1,108 @@
+#!/usr/bin/env bash
+# Runs every Definition-of-Done gate declared in .harness/gates.conf.
+# Exit 0 only if all gates pass. Used by the Stop hook, the task loop and CI.
+#
+# Usage: .harness/gates.sh [--stop] [gate ...]
+#   no args   run every gate (task loop, CI)
+#   --stop    run only STOP_GATES from gates.conf (fast profile for the Stop hook)
+#   gate ...  run only the named gates
+#
+# HARNESS_SKIP_GATES="name ..." skips the named gates on this machine (e.g.
+# integration where no container runtime exists). Skips are printed on every
+# run; CI never sets it.
+set -uo pipefail
+
+root="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+cd "$root" || exit 1
+
+conf="$root/.harness/gates.conf"
+if [[ ! -f "$conf" ]]; then
+  echo "gates: missing $conf (copy gates.conf.example and fill it in)" >&2
+  exit 1
+fi
+
+REQUIRED_GATES=(test lint typecheck build)
+GATE_EXTRA=()
+GATE_SETUP=""
+STOP_GATES=()
+# shellcheck source=/dev/null
+source "$conf"
+
+selected=("$@")
+if [[ "${1-}" == "--stop" ]]; then
+  selected=("${STOP_GATES[@]}")
+fi
+
+log_dir="$root/.harness/state/gates"
+mkdir -p "$log_dir"
+tail_lines="${HARNESS_GATE_TAIL:-60}"
+
+# Build the ordered list of (name, command) pairs.
+names=()
+cmds=()
+for gate in "${REQUIRED_GATES[@]}"; do
+  var="GATE_${gate^^}"
+  names+=("$gate")
+  cmds+=("${!var-}")
+done
+for entry in "${GATE_EXTRA[@]}"; do
+  names+=("${entry%%:*}")
+  cmds+=("${entry#*:}")
+done
+
+is_selected() {
+  [[ ${#selected[@]} -eq 0 ]] && return 0
+  local s
+  for s in "${selected[@]}"; do [[ "$s" == "$1" ]] && return 0; done
+  return 1
+}
+
+# Setup runs before any gate (e.g. code generation); its failure fails everything.
+if [[ -n "$GATE_SETUP" ]]; then
+  if ! bash -c "$GATE_SETUP" >"$log_dir/setup.log" 2>&1; then
+    echo "FAIL  setup  \$ $GATE_SETUP"
+    tail -n "$tail_lines" "$log_dir/setup.log"
+    echo "gates: FAILED (setup)"
+    exit 1
+  fi
+fi
+
+failed=()
+for i in "${!names[@]}"; do
+  name="${names[$i]}"
+  cmd="${cmds[$i]}"
+  is_selected "$name" || continue
+
+  if [[ " ${HARNESS_SKIP_GATES:-} " == *" $name "* ]]; then
+    echo "SKIP  $name  (HARNESS_SKIP_GATES on this machine)"
+    continue
+  fi
+
+  if [[ -z "$cmd" ]]; then
+    echo "FAIL  $name  (not configured; set GATE_${name^^} or 'skip:<reason>')"
+    failed+=("$name")
+    continue
+  fi
+  if [[ "$cmd" == skip:* ]]; then
+    echo "SKIP  $name  (${cmd#skip:})"
+    continue
+  fi
+
+  log="$log_dir/$name.log"
+  start=$(date +%s)
+  if bash -c "$cmd" >"$log" 2>&1; then
+    echo "PASS  $name  ($(( $(date +%s) - start ))s)"
+  else
+    echo "FAIL  $name  ($(( $(date +%s) - start ))s)  \$ $cmd"
+    echo "----- last $tail_lines lines of $name output -----"
+    tail -n "$tail_lines" "$log"
+    echo "-----"
+    failed+=("$name")
+  fi
+done
+
+if [[ ${#failed[@]} -gt 0 ]]; then
+  echo "gates: FAILED (${failed[*]})"
+  exit 1
+fi
+echo "gates: all passed"

package/templates/.harness/lib.sh

@@ -0,0 +1,169 @@
+# Shared helpers for the .harness scripts. Source it; do not run it.
+# shellcheck shell=bash
+
+# Main checkout of the repository, also when called from one of its worktrees:
+# loop state and logs always live there.
+harness_root() {
+  local common
+  common="$(git rev-parse --path-format=absolute --git-common-dir)" || return 1
+  dirname "$common"
+}
+
+# Loads the machine-level harness settings (HARNESS_ENV_FILE, default
+# ~/.config/harness/env) and exports every variable in them, so they reach the
+# gates and every Claude Code session the harness starts, also when it is started
+# by a timer with an empty environment. TELEGRAM_STATE_DIR there keeps those
+# sessions away from the operator's Telegram channel (see env.example).
+harness_load_env() {
+  local env_file="${HARNESS_ENV_FILE:-$HOME/.config/harness/env}"
+  [[ -f "$env_file" ]] || return 0
+  set -a
+  # shellcheck source=/dev/null
+  . "$env_file"
+  set +a
+}
+
+# HARNESS_CLAUDE: the command that starts Claude Code for an agent session (an
+# array, so it works after `timeout`). The bot token and chat id are left out of
+# the session's environment: only notify.sh needs them, and it reads the env file
+# itself. TELEGRAM_STATE_DIR from the env file is kept.
+# shellcheck disable=SC2034  # used by the scripts that source this file
+HARNESS_CLAUDE=(env -u HARNESS_TELEGRAM_BOT_TOKEN -u HARNESS_TELEGRAM_CHAT_ID claude)
+
+# Worktree where the task loop runs a change (ADR 0012), outside the checkout so
+# lint, tests and type-checks of the main checkout never see it:
+#   ${HARNESS_WORKTREES_DIR:-<parent of the checkout>/.harness-worktrees/<repo>}/<change-id>
+harness_worktree() {
+  local root
+  root="$(harness_root)" || return 1
+  echo "${HARNESS_WORKTREES_DIR:-$(dirname "$root")/.harness-worktrees/$(basename "$root")}/$1"
+}
+
+# ------------------------------------------------- model routing (ADR 0020) --
+# harness_models: loads models.conf next to this file (or in HARNESS_MODELS_DIR), then the project's
+# models.local.conf and $HARNESS_MODELS_FILE, in a subshell-safe way (callers
+# use the functions below, which run it in a subshell).
+harness_models() {
+  # HARNESS_MODELS_DIR: read another project's mapping with this code (the
+  # watcher runs the harness's newest lib.sh against each project's models.conf).
+  local base="${HARNESS_MODELS_DIR:-$(dirname "${BASH_SOURCE[0]}")}"
+  # shellcheck source=/dev/null
+  . "$base/models.conf" || return 1
+  # shellcheck source=/dev/null
+  [[ -f "$base/models.local.conf" ]] && . "$base/models.local.conf"
+  # shellcheck source=/dev/null
+  [[ -n "${HARNESS_MODELS_FILE:-}" && -f "$HARNESS_MODELS_FILE" ]] && . "$HARNESS_MODELS_FILE"
+  return 0
+}
+
+# harness_task_level <task-type> [<level override>]: the level (R1-R4).
+harness_task_level() {
+  (
+    harness_models || exit 1
+    local level="${2:-}" var="TASK_$1"
+    [[ -n "$level" ]] || level="${!var:-}"
+    [[ "$level" =~ ^R[1-4]$ ]] || { echo "harness: unknown task type or level '$1${2:+/$2}'" >&2; exit 1; }
+    echo "$level"
+  )
+}
+
+# harness_level_climb <level> <steps>: the level <steps> above, capped at R4.
+harness_level_climb() {
+  local n="${1#R}"; n=$(( n + $2 )); (( n > 4 )) && n=4; (( n < 1 )) && n=1
+  echo "R$n"
+}
+
+# harness_level_flags <level>: the claude flags for a level; empty while
+# HARNESS_MODEL_ROUTING is not "on" (measure mode, decision 7).
+harness_level_flags() {
+  (
+    harness_models || exit 1
+    [[ "$1" =~ ^R[1-4]$ ]] || { echo "harness: unknown level '$1'" >&2; exit 1; }
+    [[ "${HARNESS_MODEL_ROUTING:-measure}" == on ]] || exit 0
+    echo "${!1}"
+  )
+}
+
+# harness_claude_flags <task-type> [<level override>]: the claude flags for a
+# task. The single entry point from task to model and effort.
+harness_claude_flags() {
+  local level; level="$(harness_task_level "$@")" || return 1
+  harness_level_flags "$level"
+}
+
+# harness_usage_error <session.json>: the session ended on an account usage
+# limit or on missing usage credits ("You're out of usage credits. Switch to
+# another model..."), not on the work.
+harness_usage_error() {
+  grep -qiE "hit your (session|usage) limit|usage limit reached|out of usage credits|credit balance is too low" "$1" 2>/dev/null
+}
+
+# harness_level_descend <level>: the level one below, for the fallback after a
+# usage error (ADR 0020, amendment). Fails at R1, and unless
+# HARNESS_MODEL_ROUTING=on: without routing no model is chosen, so there is
+# nothing to switch to and the callers keep their pause (or escalation).
+harness_level_descend() {
+  [[ "${HARNESS_MODEL_ROUTING:-measure}" == on ]] || return 1
+  local n="${1#R}"
+  [[ "$1" =~ ^R[1-4]$ ]] && (( n > 1 )) || return 1
+  echo "R$((n - 1))"
+}
+
+# harness_flag_value <flags> <--flag>: e.g. the --effort of a level's flags.
+harness_flag_value() {
+  # shellcheck disable=SC2206
+  local words=($1) i
+  for (( i = 0; i < ${#words[@]}; i++ )); do
+    [[ "${words[$i]}" == "$2" ]] && { echo "${words[$((i + 1))]:-}"; return 0; }
+  done
+}
+
+# ------------------------------------------------- usage ledger (ADR 0020) --
+# A session log is claude -p --output-format json with stderr merged in, so
+# warnings such as "Ignoring N permissions.allow entries ... this workspace has
+# not been trusted" can surround the JSON. session(<file>) parses the whole file
+# or, failing that, the last line that is a JSON object ({} when none is).
+harness_session_js='const session = (f) => {
+  let s = ""; try { s = require("fs").readFileSync(f, "utf8"); } catch { return {}; }
+  try { return JSON.parse(s) || {}; } catch {}
+  for (const l of s.split("\n").reverse()) {
+    if (l.trimStart().startsWith("{")) { try { return JSON.parse(l) || {}; } catch {} }
+  }
+  return {};
+};'
+
+# harness_session_reply <session.json>: the session's final message (empty when
+# there is none); fails when the session ended on an error (is_error).
+harness_session_reply() {
+  node -e "$harness_session_js"'
+    const d = session(process.argv[1]);
+    process.stdout.write(typeof d.result === "string" ? d.result : "");
+    process.exitCode = d.is_error ? 1 : 0;' "$1" 2>/dev/null
+}
+
+# harness_session_usage <session.json>: "model<TAB>cost_usd<TAB>output_tokens<TAB>cache_read_tokens"
+# from a claude -p --output-format json result (models joined by "+").
+harness_session_usage() {
+  node -e "$harness_session_js"'
+    const d = session(process.argv[1]);
+    const mu = d.modelUsage || {};
+    const sum = (k) => Object.values(mu).reduce((a, m) => a + (m[k] || 0), 0);
+    const cost = typeof d.total_cost_usd === "number" ? d.total_cost_usd : sum("costUSD");
+    process.stdout.write([Object.keys(mu).join("+") || "unknown", cost.toFixed(4),
+      sum("outputTokens"), sum("cacheReadInputTokens")].join("\t"));' "$1" 2>/dev/null \
+    || printf 'unknown\t0.0000\t0\t0'
+}
+
+# harness_record_usage <project> <ref> <task-type> <level> <effort> <attempt> <result> <session.json>:
+# one line in the machine-wide ledger (HARNESS_USAGE_LEDGER, default
+# ~/.local/state/harness/usage.tsv); prints the session's usage columns.
+harness_record_usage() {
+  local ledger="${HARNESS_USAGE_LEDGER:-$HOME/.local/state/harness/usage.tsv}" usage
+  usage="$(harness_session_usage "$8")"
+  mkdir -p "$(dirname "$ledger")"
+  [[ -s "$ledger" ]] || printf 'timestamp\tproject\tref\ttask_type\tlevel\tmodel\teffort\tcost_usd\toutput_tokens\tcache_read_tokens\tresult\tattempt\n' >"$ledger"
+  IFS=$'\t' read -r model cost out cache <<<"$usage"
+  printf '%s\t%s\t%s\t%s\t%s\t%s\t%s\t%s\t%s\t%s\t%s\t%s\n' "$(date -Iseconds)" "$1" "$2" "$3" "$4" \
+    "$model" "${5:-default}" "$cost" "$out" "$cache" "$7" "$6" >>"$ledger"
+  printf '%s' "$usage"
+}