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

package/templates/.harness/run-tasks.sh

@@ -0,0 +1,461 @@
+#!/usr/bin/env bash
+# Autonomous task loop for one OpenSpec change.
+#
+# For each pending task (`- [ ] ...`) in openspec/changes/<change-id>/tasks.md:
+#   1. run Claude Code headless in a fresh session, scoped to that task;
+#   2. run .harness/gates.sh independently of the agent;
+#   3. pass → mark the task done and make one commit;
+#      fail → retry with the gate output as feedback, up to N attempts;
+#      still failing → stop and escalate to a human.
+# Each attempt runs at a reasoning level (ADR 0020): the task's level (impl in
+# .harness/models.conf, or a <!-- level: Rn --> marker on the task line), twice,
+# then one level up per attempt (R2, R2, R3, R4). Attempts that changed nothing
+# climb only once. The level's --model/--effort are passed when
+# HARNESS_MODEL_ROUTING=on (measure mode only records the level). With routing
+# on, a session that ends on a usage limit or missing usage credits is repeated
+# one level down (R4 → R3 → R2 → R1) instead of pausing; the summary records
+# that session as "fallback" and the next at the level it ran. Pausing (exit 3)
+# is kept at R1 and with routing off.
+# Before the first task it installs the dependencies the spec declares
+# (.harness/deps.sh, ADR 0015) in their own commit; an agent that changes
+# dependency files escalates the run.
+#
+# Usage: .harness/run-tasks.sh <change-id> [--max-attempts N] [--open-pr] [--force] [--check]
+#
+# Only approved changes run: the change must be on the base branch, merged there
+# through its spec PR (ADR 0011), and the change files on the work branch must
+# match the approved ones (tasks.md checkboxes aside). Work happens on
+# change/<id>, created from the base branch; --open-pr links the spec PR.
+# --check runs the preconditions only (approval, autonomy, clean worktree) and exits.
+#
+# The loop runs in a git worktree of its own (ADR 0012), never in the checkout it
+# is started from: see harness_worktree in .harness/lib.sh for the location.
+# Dependencies are installed there on first use. State and logs stay in the main
+# checkout (.harness/state, .harness/logs). The worktree is removed once every
+# task is done; on escalation or pause it is kept for a human or the next run.
+#
+# Exit codes: 0 all tasks done, 2 a task escalated after N attempts,
+#             3 paused because the agent hit the account usage limit,
+#             4 stopped between two tasks on request (.harness/state/stop-<id>,
+#               written by `loop.sh stop <id> --after-task`; the work is
+#               committed and the worktree kept).
+#
+# Environment:
+#   HARNESS_BASE_BRANCH      branch holding approved specs (default main)
+#   HARNESS_WORKTREES_DIR    parent directory of the loop worktrees
+#   HARNESS_WORKTREE_SETUP   command run once in a new worktree (default: install
+#                            dependencies from the lockfile); HARNESS_MAIN_CHECKOUT
+#                            points at the main checkout, e.g. to copy a .env
+#   HARNESS_MAX_ATTEMPTS     attempts per task (default 4: the level ladder, ADR 0020)
+#   HARNESS_TASK_TIMEOUT     max seconds per agent session (default 1800)
+#   HARNESS_PERMISSION_MODE  claude --permission-mode (default acceptEdits)
+#   HARNESS_CLAUDE_ARGS      extra args for claude (experiments; models come from models.conf)
+#   HARNESS_COMMIT_TYPE      conventional commit type (default feat)
+set -euo pipefail
+
+usage() { sed -n '2,50p' "$0" | sed 's/^# \{0,1\}//'; exit "${1:-0}"; }
+die() { echo "run-tasks: $*" >&2; exit 1; }
+
+[[ $# -ge 1 ]] || usage 1
+[[ "$1" == "-h" || "$1" == "--help" ]] && usage 0
+change="$1"; shift
+
+max_attempts="${HARNESS_MAX_ATTEMPTS:-4}"
+timeout_s="${HARNESS_TASK_TIMEOUT:-1800}"
+permission_mode="${HARNESS_PERMISSION_MODE:-acceptEdits}"
+commit_type="${HARNESS_COMMIT_TYPE:-feat}"
+open_pr=0
+force=0
+check_only=0
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --max-attempts) max_attempts="$2"; shift 2 ;;
+    --open-pr) open_pr=1; shift ;;
+    --force) force=1; shift ;;
+    --check) check_only=1; shift ;;
+    *) die "unknown option: $1" ;;
+  esac
+done
+
+git rev-parse --git-dir >/dev/null 2>&1 || die "not inside a git repository"
+# shellcheck source-path=SCRIPTDIR source=lib.sh
+. "$(dirname "${BASH_SOURCE[0]}")/lib.sh"
+root="$(harness_root)"
+cd "$root"
+wt="$(harness_worktree "$change")"
+# Machine settings (skipped gates, TELEGRAM_STATE_DIR for the agent sessions)
+# also when run-tasks.sh is started directly instead of through loop.sh.
+harness_load_env
+
+change_dir="openspec/changes/$change"
+tasks="$change_dir/tasks.md"
+[[ -x .harness/gates.sh ]] || die ".harness/gates.sh missing or not executable"
+command -v claude >/dev/null || die "claude CLI not found"
+
+autonomy="$(cat .harness/autonomy 2>/dev/null || echo disabled)"
+if [[ "$autonomy" != "enabled" && $force -eq 0 ]]; then
+  die "autonomy is '$autonomy' (.harness/autonomy). Add characterization tests first, or pass --force."
+fi
+
+# The spec is approved when its spec PR is merged: the change is on the base
+# branch. Compare against the remote copy when there is one, so a stale local
+# branch neither hides an approval nor fakes one.
+base_branch="${HARNESS_BASE_BRANCH:-main}"
+base_ref="$base_branch"
+if git remote get-url origin >/dev/null 2>&1; then
+  git fetch -q origin "$base_branch" || die "cannot fetch origin/$base_branch"
+  base_ref="origin/$base_branch"
+fi
+git rev-parse -q --verify "$base_ref^{commit}" >/dev/null || die "base branch $base_ref not found"
+if ! git cat-file -e "$base_ref:$tasks" 2>/dev/null; then
+  die "change $change is not on $base_ref, so its spec is not approved. Open the spec PR from spec/$change and merge it first (ADR 0011)."
+fi
+
+branch="change/$change"
+if git rev-parse -q --verify "refs/heads/$branch" >/dev/null; then
+  start_ref="$branch"
+else
+  start_ref="$base_ref"
+fi
+if [[ -d "$wt" ]]; then
+  [[ "$(git -C "$wt" branch --show-current 2>/dev/null)" == "$branch" ]] \
+    || die "$wt exists but is not a worktree on $branch; remove it (git worktree remove) and re-run"
+  [[ -z "$(git -C "$wt" status --porcelain)" ]] \
+    || die "worktree $wt has uncommitted work (left by an escalation?). Finish or discard it there first."
+fi
+
+# The work branch implements exactly the approved spec: every change file
+# matches the base branch, except for the checkboxes the loop ticks in tasks.md.
+unchecked() { sed -E 's/^([[:space:]]*- )\[x\] /\1[ ] /'; }
+if ! git diff --quiet "$base_ref" "$start_ref" -- "$change_dir" ":(exclude)$tasks" \
+  || ! cmp -s <(git show "$base_ref:$tasks" | unchecked) <(git show "$start_ref:$tasks" 2>/dev/null | unchecked); then
+  die "$change_dir on $branch differs from the approved spec on $base_ref. Spec changes go through a new spec PR; then rebase $branch on $base_branch."
+fi
+
+if [[ $check_only -eq 1 ]]; then
+  echo "run-tasks: change $change is approved and ready to run on $branch in $wt."
+  exit 0
+fi
+
+# Work in the change's own worktree, so the checkout the loop was started from
+# (where specs are written) is never switched or cleaned under anyone's feet.
+if [[ ! -d "$wt" ]]; then
+  mkdir -p "$(dirname "$wt")"
+  if [[ "$start_ref" == "$branch" ]]; then
+    git worktree add -q "$wt" "$branch" \
+      || die "cannot check out $branch in $wt; if it is checked out elsewhere (git worktree list), switch that checkout away"
+  else
+    git worktree add -q --no-track -b "$branch" "$wt" "$base_ref" || die "cannot create worktree $wt"
+  fi
+  setup="${HARNESS_WORKTREE_SETUP:-}"
+  if [[ -z "$setup" ]]; then
+    if [[ -f "$wt/pnpm-lock.yaml" ]]; then setup="pnpm install --frozen-lockfile"
+    elif [[ -f "$wt/package-lock.json" ]]; then setup="npm ci"
+    fi
+  fi
+  if [[ -n "$setup" ]]; then
+    mkdir -p ".harness/logs/$change"
+    echo "==> worktree setup: $setup"
+    if ! (cd "$wt" && HARNESS_MAIN_CHECKOUT="$root" bash -c "$setup") >".harness/logs/$change/worktree-setup.log" 2>&1; then
+      # Without its dependencies the worktree is useless; the next run starts over.
+      git worktree remove --force "$wt"
+      die "worktree setup failed ($setup); see .harness/logs/$change/worktree-setup.log"
+    fi
+  fi
+  # A harness installed from the package (ADR 0021): the worktree gets the
+  # version its own lockfile pins, even when the install skipped "prepare".
+  if [[ -x "$wt/node_modules/.bin/harness" ]]; then
+    mkdir -p ".harness/logs/$change"
+    if ! (cd "$wt" && node_modules/.bin/harness install) >>".harness/logs/$change/worktree-setup.log" 2>&1; then
+      git worktree remove --force "$wt"
+      die "harness install failed in the worktree; see .harness/logs/$change/worktree-setup.log"
+    fi
+  fi
+fi
+
+log_dir="$root/.harness/logs/$change"
+mkdir -p "$log_dir" "$root/.harness/state"
+
+# Runner state for .harness/status.sh: key=value lines, rewritten on every step.
+state_file="$root/.harness/state/run-$change"
+run_status="running"
+cur_task_id=""
+cur_task=""
+cur_attempt=0
+attempt_started=""
+write_state() {
+  {
+    echo "status=$run_status"
+    echo "pid=$$"
+    echo "started=$run_started"
+    echo "task_id=$cur_task_id"
+    echo "task=$cur_task"
+    echo "attempt=$cur_attempt"
+    echo "max_attempts=$max_attempts"
+    echo "attempt_started=$attempt_started"
+    echo "updated=$(date +%s)"
+  } >"$state_file"
+}
+run_started="$(date +%s)"
+# Anything that ends the run without setting a final status was interrupted.
+trap '[[ "$run_status" == running ]] && run_status=interrupted; write_state' EXIT
+write_state
+cd "$wt"
+summary="$log_dir/summary.tsv"
+summary_header=$'timestamp\ttask\tattempt\tduration_s\tresult\tlevel\tmodel\teffort\tcost_usd\toutput_tokens\tcache_read_tokens'
+if [[ ! -f "$summary" ]]; then
+  printf '%s\n' "$summary_header" >"$summary"
+elif [[ "$(head -n1 "$summary")" == $'timestamp\ttask\tattempt\tduration_s\tresult' ]]; then
+  sed -i "1s/.*/$summary_header/" "$summary"   # older runs: same first columns, new ones empty
+fi
+
+next_task() { grep -n -m1 -E '^[[:space:]]*- \[ \] ' "$tasks" || true; }
+
+# Dependencies the approved spec declares (design.md "## Dependencies", ADR 0015)
+# are installed by the loop, never by the agent, in one commit before the tasks.
+# Anything deps.sh refuses (an undeclared change, a version conflict) escalates.
+dep_files=(package.json pnpm-lock.yaml pnpm-workspace.yaml)
+if [[ -x .harness/deps.sh && -f package.json ]]; then
+  if ! .harness/deps.sh install "$change_dir" >"$log_dir/deps.log" 2>&1; then
+    run_status="escalated"
+    echo "run-tasks: the declared dependencies could not be installed; escalating." >&2
+    tail -n 20 "$log_dir/deps.log" >&2
+    exit 2
+  fi
+  if [[ -n "$(git status --porcelain -- "${dep_files[@]}")" ]]; then
+    git add -- "${dep_files[@]}"
+    printf 'chore(%s): add the dependencies declared by the spec\n\nInstalled by the task loop from the "## Dependencies" section of\n%s/design.md (exact versions, no other dependency changed):\n\n%s\n' \
+      "$change" "$change_dir" "$(grep '^deps: added' "$log_dir/deps.log" | sed 's/^deps: added //')" | git commit -q -F -
+    echo "==> dependencies declared by the spec installed and committed"
+  fi
+fi
+
+build_prompt() {
+  local task="$1" feedback="$2"
+  cat <<EOF
+You are running inside the autonomous task loop of agent-harness.
+
+Change: $change (files in $change_dir/: proposal.md, design.md if present, specs/, tasks.md)
+Your task (exactly one):
+  $task
+
+Instructions:
+- Read the proposal, design and delta specs relevant to this task before coding.
+- Implement ONLY this task, following CLAUDE.md and .harness/standards/.
+- Add or update tests that prove the task's behaviour; write the failing test first.
+- Run .harness/gates.sh and iterate until it exits 0.
+- Do NOT edit files in $change_dir/: it is the approved spec. If it is wrong, stop and say so.
+- Do NOT edit tasks.md, do NOT commit, do NOT push. The loop does that.
+- Do NOT add, remove or update packages, and do NOT edit package.json, pnpm-lock.yaml or
+  pnpm-workspace.yaml: the loop already installed the dependencies the spec declares. If the
+  task needs a package the spec does not declare, stop and name it in your final message.
+- Never change what an existing test asserts to make it match the code. If an existing
+  test conflicts with the code, stop and explain the conflict in your final message.
+- If the task cannot be done as specified, stop and explain why in your final message.
+- All artifacts in English.
+EOF
+  if [[ -n "$feedback" ]]; then
+    cat <<EOF
+
+A previous attempt left work in the tree but the gates failed with:
+--------
+$feedback
+--------
+Continue from the current state and fix these failures.
+EOF
+  fi
+}
+
+# Conventional-commit summary from a task line: drop the task id and backticks,
+# keep the first sentence, and cut at a word boundary to fit 72 chars with the prefix.
+commit_summary() {
+  local text max
+  text="$(sed -E -e 's/^[0-9]+(\.[0-9]+)*[[:space:]]+//' -e 's/`//g' -e 's/\. .*$//' -e 's/\.$//' <<<"$1")"
+  max=$(( 72 - ${#commit_type} - ${#change} - 4 ))
+  if (( ${#text} > max )); then
+    text="${text:0:max-3}"
+    text="${text% *}..."
+  fi
+  printf '%s' "$text"
+}
+
+untrusted_warned=0
+warn_if_untrusted() {
+  if [[ $untrusted_warned -eq 0 ]] && grep -q "workspace has not been trusted" "$1" 2>/dev/null; then
+    echo "    warning: Claude Code ignores .claude/settings.json permissions in this untrusted" >&2
+    echo "             workspace; the agent cannot run gates itself. Trust it once interactively." >&2
+    untrusted_warned=1
+  fi
+}
+
+# record <task> <attempt> <duration> <result>: one summary row for the attempt,
+# with its level, model, effort, cost and tokens (ADR 0020); the same session
+# also goes to the machine-wide ledger.
+record() {
+  local usage effort model cost out cache
+  effort="$(harness_flag_value "${level_flags:-}" --effort)"
+  usage="$(harness_record_usage "$(basename "$root")" "$change" impl "${level:-}" "${effort:-default}" "$2" "$4" \
+    "$log_dir/task-$1-attempt-$2.json")"
+  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\n' "$(date -Iseconds)" "$1" "$2" "$3" "$4" \
+    "${level:-}" "$model" "${effort:-default}" "$cost" "$out" "$cache" >>"$summary"
+}
+
+while line="$(next_task)"; [[ -n "$line" ]]; do
+  # A stop requested while the previous task ran is honoured here, between tasks,
+  # when everything is committed (ADR 0022, spec amendment of a change in progress).
+  if [[ -f "$root/.harness/state/stop-$change" ]]; then
+    rm -f "$root/.harness/state/stop-$change"
+    run_status="stopped"
+    echo "run-tasks: stopped between tasks on request; the work is committed on $branch in $wt."
+    exit 4
+  fi
+  ln="${line%%:*}"
+  task="$(sed -E 's/^[[:space:]]*- \[ \] //' <<<"${line#*:}")"
+  # The spec author's level for this task (ADR 0020), stripped from the text
+  # that becomes the prompt and the commit.
+  level_override="$(grep -oE '<!--[[:space:]]*level:[[:space:]]*R[1-4][[:space:]]*-->' <<<"$task" | grep -oE 'R[1-4]' || true)"
+  task="$(sed -E 's/[[:space:]]*<!--[[:space:]]*level:[^>]*-->//g' <<<"$task")"
+  base_level="$(harness_task_level impl "$level_override")" || base_level="R2"
+  gate_fails=0 nochange=0 levels_tried="" level_cap=""
+  task_id="$(grep -oE '^[0-9]+(\.[0-9]+)*' <<<"$task" || echo "L$ln")"
+  summary_line="$(commit_summary "$task")"
+  feedback=""
+  echo "==> task $task_id: $task (level $base_level${level_override:+, set by the spec})"
+
+  done_ok=0
+  for (( attempt = 1; attempt <= max_attempts; attempt++ )); do
+    # Two attempts at the task's level, then one level up per failure; attempts
+    # that changed nothing climb only once (they count as at most two failures).
+    fails=$(( gate_fails + (nochange > 2 ? 2 : nochange) ))
+    level="$(harness_level_climb "$base_level" $(( fails > 1 ? fails - 1 : 0 )))"
+    # After a usage-error fallback the task stays at or below that level.
+    if [[ -n "$level_cap" ]] && (( ${level#R} > ${level_cap#R} )); then level="$level_cap"; fi
+    level_flags="$(harness_level_flags "$level")"
+    [[ " $levels_tried " == *" $level "* ]] || levels_tried="${levels_tried:+$levels_tried }$level"
+    echo "    attempt $attempt/$max_attempts at $level${level_flags:+ ($level_flags)}"
+    cur_task_id="$task_id"; cur_task="$summary_line"; cur_attempt="$attempt"; attempt_started="$(date +%s)"
+    write_state
+    start=$(date +%s)
+    session_json="$log_dir/task-$task_id-attempt-$attempt.json"
+    while :; do
+      # shellcheck disable=SC2086
+      build_prompt "$task" "$feedback" | timeout "$timeout_s" "${HARNESS_CLAUDE[@]}" -p \
+        --output-format json \
+        --permission-mode "$permission_mode" \
+        --disallowedTools "Bash(git commit:*)" "Bash(git push:*)" "Bash(.harness/spec-pr.sh:*)" \
+          "Bash(pnpm add:*)" "Bash(pnpm remove:*)" "Bash(pnpm update:*)" "Bash(npm install:*)" \
+        ${level_flags} ${HARNESS_CLAUDE_ARGS:-} \
+        >"$session_json" 2>&1 || true
+
+      warn_if_untrusted "$session_json"
+
+      # Out of usage (limit or credits) at this level: with routing on, the
+      # same attempt goes to the level below instead of pausing (ADR 0020,
+      # amendment). The interrupted session left partial work: discard it. The
+      # fallback level also caps the rest of this task's ladder.
+      if harness_usage_error "$session_json" && lower="$(harness_level_descend "$level")"; then
+        record "$task_id" "$attempt" "$(( $(date +%s) - start ))" fallback
+        git checkout -- . && git clean -fdq
+        echo "    usage error at $level; falling back to $lower"
+        .harness/notify.sh info "$change: task $task_id: $level is out of usage, falling back to $lower" 2>/dev/null || true
+        level_cap="$lower"
+        level="$lower"
+        level_flags="$(harness_level_flags "$level")"
+        [[ " $levels_tried " == *" $level "* ]] || levels_tried="${levels_tried:+$levels_tried }$level"
+        start=$(date +%s)
+        continue
+      fi
+      break
+    done
+
+    # An account usage limit ends the session early; retrying only burns the
+    # remaining attempts on the same error. Pause and let a human resume (at R1,
+    # or with routing off, where there is no lower model to try).
+    if harness_usage_error "$session_json"; then
+      record "$task_id" "$attempt" "$(( $(date +%s) - start ))" paused
+      run_status="paused"
+      # The interrupted attempt left partial, unverified work: discard it.
+      git checkout -- . && git clean -fdq
+      echo "run-tasks: the agent session hit the account usage limit; pausing." >&2
+      echo "  Task $task_id is not done; its partial attempt was discarded. Re-run after the limit resets." >&2
+      exit 3
+    fi
+
+    # The agent must not touch the approved spec; restoring tasks.md also keeps
+    # its line numbers valid.
+    git checkout -- "$change_dir"
+    git clean -fdq -- "$change_dir"
+
+    # Only the spec declares dependencies: an agent that changed them needs a
+    # package the spec does not have. Retrying cannot fix that; a human decides.
+    if [[ -n "$(git status --porcelain -- "${dep_files[@]}")" ]]; then
+      record "$task_id" "$attempt" "$(( $(date +%s) - start ))" deps
+      run_status="escalated"
+      echo "run-tasks: task $task_id changed dependency files; undeclared dependencies need a spec change." >&2
+      echo "  Work in progress is left uncommitted on branch $branch in $wt." >&2
+      exit 2
+    fi
+
+    # A task that changed nothing is not done, even if the gates pass on the old code.
+    if [[ -z "$(git status --porcelain -- . ":(exclude)$tasks")" ]]; then
+      record "$task_id" "$attempt" "$(( $(date +%s) - start ))" fail
+      feedback="The previous attempt changed no files, so the task was not implemented. Implement it."
+      nochange=$(( nochange + 1 ))
+      echo "    FAIL (no changes)"
+      continue
+    fi
+
+    if gate_out="$(.harness/gates.sh 2>&1)"; then
+      record "$task_id" "$attempt" "$(( $(date +%s) - start ))" pass
+      sed -i "${ln}s/- \[ \]/- [x]/" "$tasks"
+      git add -A
+      printf '%s(%s): %s\n\nTask %s of OpenSpec change %s, completed by the task loop:\n\n%s\n' \
+        "$commit_type" "$change" "$summary_line" "$task_id" "$change" "$task" | fold -s -w 72 | git commit -q -F -
+      echo "    PASS → committed"
+      if [[ -x .harness/notify.sh ]]; then
+        .harness/notify.sh task-passed "$change: task $task_id passed — $summary_line"
+      fi
+      done_ok=1
+      break
+    fi
+
+    record "$task_id" "$attempt" "$(( $(date +%s) - start ))" fail
+    printf '%s\n' "$gate_out" >"$log_dir/task-$task_id-attempt-$attempt.gates.log"
+    feedback="$(tail -n 120 <<<"$gate_out")"
+    gate_fails=$(( gate_fails + 1 ))
+    echo "    FAIL"
+  done
+
+  if [[ $done_ok -eq 0 ]]; then
+    run_status="escalated"
+    echo "run-tasks: task $task_id failed $max_attempts attempts (levels $levels_tried); escalating." >&2
+    echo "  Work in progress is left uncommitted on branch $branch in $wt." >&2
+    echo "  Logs: $log_dir/task-$task_id-attempt-*" >&2
+    exit 2
+  fi
+done
+
+run_status="done"
+cur_task_id=""; cur_task=""; cur_attempt=0; attempt_started=""
+echo "run-tasks: all tasks in $tasks are done."
+
+if [[ $open_pr -eq 1 ]]; then
+  command -v gh >/dev/null || die "gh CLI not found; cannot open PR"
+  git push -u origin "$branch"
+  spec_pr="$(gh pr list --state merged --head "spec/$change" --json url --jq '.[0].url // empty' 2>/dev/null || true)"
+  body="$(mktemp)"
+  {
+    echo "Implements OpenSpec change \`$change\`, approved in ${spec_pr:-its spec PR (branch spec/$change; not found)}."
+    echo
+    cat "$change_dir/proposal.md"
+  } >"$body"
+  gh pr create --head "$branch" --base "$base_branch" --title "change: $change" --body-file "$body"
+  rm -f "$body"
+fi
+
+# Everything is committed on $branch: the worktree is no longer needed.
+cd "$root"
+git worktree remove --force "$wt"
+echo "run-tasks: removed worktree $wt (branch $branch keeps the work)."
+

package/templates/.harness/spec-pr.sh

@@ -0,0 +1,157 @@
+#!/usr/bin/env bash
+# Last step of proposing a change (ADR 0011, ADR 0013): opens, or updates, the
+# spec-only pull request whose merge approves the spec.
+#
+# Usage: .harness/spec-pr.sh <change-id>
+#
+#   1. validates the change with the pinned OpenSpec CLI (--strict), its
+#      declared packages (.harness/deps.sh check), the changes listed under
+#      "## Depends on" in proposal.md (each must exist: open, merged or
+#      archived), and simulates its archive in a scratch copy of openspec/
+#      (after archiving the unarchived changes it depends on): the merged
+#      specs must pass `validate --all --strict`;
+#   2. moves to branch spec/<change-id> (created from the base branch, carrying
+#      the uncommitted change files) unless already on it;
+#   3. refuses anything outside openspec/changes/<change-id>/, in the working
+#      tree or in the branch's commits;
+#   4. commits the change files, pushes, and opens the PR "spec: <change-id>",
+#      or reuses the open one, and prints its URL.
+#
+# Environment:
+#   HARNESS_BASE_BRANCH  branch the spec PR targets (default main)
+set -euo pipefail
+
+usage() { sed -n '2,20p' "$0" | sed 's/^# \{0,1\}//'; exit "${1:-0}"; }
+die() { echo "spec-pr: $*" >&2; exit 1; }
+
+[[ $# -eq 1 ]] || usage 1
+[[ "$1" == "-h" || "$1" == "--help" ]] && usage 0
+change="$1"
+[[ "$change" =~ ^[a-z0-9][a-z0-9-]*$ ]] || die "invalid change id '$change' (kebab-case expected)"
+
+root="$(git rev-parse --show-toplevel)" || die "not inside a git repository"
+cd "$root"
+change_dir="openspec/changes/$change"
+branch="spec/$change"
+base_branch="${HARNESS_BASE_BRANCH:-main}"
+
+[[ -f "$change_dir/proposal.md" && -f "$change_dir/tasks.md" ]] \
+  || die "$change_dir needs at least proposal.md and tasks.md"
+command -v gh >/dev/null || die "gh CLI not found"
+
+.harness/openspec.sh validate "$change" --type change --strict --no-interactive \
+  || die "openspec validate failed; fix the change before opening its spec PR"
+# Task levels (ADR 0020): only <!-- level: R1 --> to <!-- level: R4 -->.
+bad_levels="$(grep -nE '<!--[[:space:]]*level' "$change_dir/tasks.md" \
+  | grep -vE '<!--[[:space:]]*level:[[:space:]]*R[1-4][[:space:]]*-->' || true)"
+[[ -z "$bad_levels" ]] || die "invalid task level in $change_dir/tasks.md (use <!-- level: R1 --> to R4):
+$bad_levels"
+# The loop installs exactly what design.md declares (ADR 0015): check it now.
+if [[ -x .harness/deps.sh ]]; then
+  .harness/deps.sh check "$change_dir" || die "fix the ## Dependencies section of $change_dir/design.md"
+fi
+
+# Depends on (ADR 0022, section 5): optional list of change ids in proposal.md,
+# one kebab-case id in backticks per bullet. In an item that is more than an id
+# (prose), the first backticked token that is an existing change is the id; items
+# without one (PR references such as #63) are ignored with a warning. An item
+# that is only an id must exist.
+dep_items="$(awk '/^## /{ on = ($0 ~ /^## Depends on[ \t]*$/); next } on && /^[ \t]*[-*][ \t]+/ { sub(/^[ \t]*[-*][ \t]+/, ""); print }' "$change_dir/proposal.md")"
+
+# Only the change's own files may be pending: anything else would leak into the spec PR.
+outside="$(git status --porcelain --untracked-files=all | cut -c4- | grep -v "^$change_dir/" || true)"
+[[ -z "$outside" ]] || die "uncommitted files outside $change_dir/ (commit, stash or remove them first):
+$outside"
+
+git fetch -q origin "$base_branch" || die "cannot fetch origin/$base_branch"
+# change_exists <id>: open (in the tree or as a spec/ or change/ branch), merged or archived.
+change_exists() {
+  [[ -d "openspec/changes/$1" ]] \
+    || git cat-file -e "origin/$base_branch:openspec/changes/$1" 2>/dev/null \
+    || git ls-tree --name-only "origin/$base_branch" openspec/changes/archive/ 2>/dev/null | grep -qE "/[0-9]{4}-[0-9]{2}-[0-9]{2}-$1\$" \
+    || compgen -G "openspec/changes/archive/*-$1" >/dev/null \
+    || git rev-parse -q --verify "refs/remotes/origin/spec/$1" >/dev/null \
+    || git rev-parse -q --verify "refs/remotes/origin/change/$1" >/dev/null
+}
+depends=()
+while IFS= read -r item; do
+  [[ -n "$item" ]] || continue
+  bare="$(sed -E 's/^[[:space:]]*`?"?//; s/"?`?[[:space:]]*$//' <<<"$item")"
+  if [[ "$bare" =~ ^[a-z0-9]+(-[a-z0-9]+)*$ ]]; then
+    [[ "$bare" != "$change" ]] || die "$change lists itself under ## Depends on"
+    change_exists "$bare" || die "## Depends on lists '$bare', which is not a change (open, merged or archived); fix proposal.md"
+    depends+=("$bare"); continue
+  fi
+  found=""
+  while IFS= read -r tok; do
+    [[ "$tok" =~ ^[a-z0-9]+(-[a-z0-9]+)*$ && "$tok" != "$change" ]] && change_exists "$tok" && { found="$tok"; break; }
+  done < <(grep -oE '`[^`]+`' <<<"$item" | tr -d '`')
+  if [[ -n "$found" ]]; then depends+=("$found"); else echo "spec-pr: warning: ignoring ## Depends on item without a change id: ${item:0:80}" >&2; fi
+done <<<"$dep_items"
+
+# Simulate the archive (ADR 0022, section 4) in a scratch copy of openspec/: the
+# watcher archives this change after its implementation PR is merged, and
+# `validate --all --strict` must still pass then (a merged requirement over 500
+# characters, a MODIFIED requirement that is not there). The changes it depends
+# on that are not archived yet are archived first, in the order listed.
+scratch="$(mktemp -d)"
+trap 'rm -rf "$scratch"' EXIT
+cp -r openspec "$scratch/openspec"
+for dep in "${depends[@]}" "$change"; do
+  [[ -d "$scratch/openspec/changes/$dep" ]] || continue
+  (cd "$scratch" && "$root/.harness/openspec.sh" archive "$dep" --yes </dev/null) >"$scratch/out" 2>&1 \
+    || die "simulated archive of $dep failed; its delta does not apply on top of the current specs (is a change it builds on still unarchived? list it under ## Depends on):
+$(tail -n 8 "$scratch/out")"
+done
+(cd "$scratch" && "$root/.harness/openspec.sh" validate --all --strict --no-interactive </dev/null) >"$scratch/out" 2>&1 \
+  || die "openspec validate --all --strict fails after the simulated archive of $change; fix the spec (split a requirement over 500 characters, move detail into scenarios):
+$(tail -n 12 "$scratch/out")"
+
+if [[ "$(git branch --show-current)" != "$branch" ]]; then
+  if git rev-parse -q --verify "refs/heads/$branch" >/dev/null; then
+    git switch -q "$branch" || die "cannot switch to $branch"
+  else
+    git switch -q --no-track -c "$branch" "origin/$base_branch" \
+      || die "cannot create $branch from origin/$base_branch with the pending change files"
+  fi
+fi
+
+committed_outside="$(git diff --name-only "origin/$base_branch...HEAD" | grep -v "^$change_dir/" || true)"
+[[ -z "$committed_outside" ]] || die "$branch has commits outside $change_dir/; a spec PR contains only the spec:
+$committed_outside"
+
+if [[ -n "$(git status --porcelain --untracked-files=all -- "$change_dir")" ]]; then
+  git add -A -- "$change_dir"
+  if git cat-file -e "origin/$base_branch:$change_dir/tasks.md" 2>/dev/null \
+    || [[ -n "$(git log --oneline "origin/$base_branch..HEAD")" ]]; then
+    msg="docs($change): update OpenSpec change"
+  else
+    msg="docs($change): propose OpenSpec change"
+  fi
+  git commit -q -m "$msg" -- "$change_dir"
+fi
+[[ -n "$(git log --oneline "origin/$base_branch..HEAD")" ]] \
+  || die "$change_dir is identical on origin/$base_branch: nothing to propose"
+
+git push -q -u origin "$branch"
+
+url="$(gh pr list --state open --head "$branch" --json url --jq '.[0].url // empty' 2>/dev/null || true)"
+if [[ -n "$url" ]]; then
+  echo "spec-pr: updated $url"
+  exit 0
+fi
+
+body="$(mktemp)"
+trap 'rm -rf "$scratch"; rm -f "$body"' EXIT
+{
+  echo "OpenSpec change \`$change\`, for review. **Merging this PR approves the spec** (ADR 0011);"
+  echo "nothing is implemented until then. Comment here; adjustments land on \`$branch\`."
+  echo
+  cat "$change_dir/proposal.md"
+  echo
+  echo "## Tasks"
+  echo
+  grep -E '^[[:space:]]*- \[[ xX]\] ' "$change_dir/tasks.md" || true
+} >"$body"
+url="$(gh pr create --base "$base_branch" --head "$branch" --title "spec: $change" --body-file "$body")"
+echo "spec-pr: opened $url"