@data-matters.io/agent-harness 0.1.0 → 0.1.2

package/README.md

@@ -7,18 +7,27 @@ follows.
 
 ## Install
 
-Pin the package exactly and let the project's install generate the harness:
+Pin the package exactly and let the project's install generate the harness.
+pnpm refuses a version younger than its minimum release age: to adopt a
+release on its first day, list it in `pnpm-workspace.yaml` first.
+
+```yaml
+minimumReleaseAgeExclude:
+  - '@data-matters.io/agent-harness@<version>'
+```
 
 ```sh
 pnpm add -D -E @data-matters.io/agent-harness
-pnpm exec harness init --new --stack nextjs   # or nestjs; --existing for a codebase without tests
+pnpm exec harness init --new --stack nextjs   # or nestjs, vite; --existing for a codebase without tests
 ```
 
 ```json
 { "scripts": { "prepare": "harness install" } }
 ```
 
-`harness install` writes the generated files (`.harness/*.sh`,
+`harness init` also writes `.github/dependabot.yml`: weekly bumps of the
+harness only, after a 2-day cooldown, so each bump is past pnpm's minimum
+release age. `harness install` writes the generated files (`.harness/*.sh`,
 `.harness/standards/`, `.harness/CLAUDE.harness.md`, the Claude Code Stop hook)
 and they stay git-ignored, so they always match the pinned version.
 

package/bin/harness

@@ -5,8 +5,10 @@
 # Usage: harness <command> [options]   (run from the product repository root)
 #
 #   init (--new | --existing | --template) [--name <name>] [--stack <stack>]
-#                  first adoption: writes the project-owned and seeded files,
-#                  the .gitignore entries and CLAUDE.md, then runs `install`.
+#                  first adoption: writes the project-owned and seeded files
+#                  (with .github/dependabot.yml), the .gitignore entries,
+#                  CLAUDE.md and this version's minimumReleaseAgeExclude entry
+#                  in pnpm-workspace.yaml, then runs `install`.
 #                  Never overwrites an existing file; conflicts are reported.
 #   install        (re)generates the git-ignored harness files from this
 #                  package; idempotent. Run by the project's
@@ -26,7 +28,7 @@
 #   HARNESS_PROJECT_DIR  product repository (default: the current directory)
 set -euo pipefail
 
-usage() { sed -n '2,26p' "$0" | sed 's/^# \{0,1\}//'; exit "${1:-0}"; }
+usage() { sed -n '2,28p' "$0" | sed 's/^# \{0,1\}//'; exit "${1:-0}"; }
 die() { echo "harness: $*" >&2; exit 1; }
 
 pkg="$(cd "$(dirname "$(readlink -f "${BASH_SOURCE[0]}")")/.." && pwd)"
@@ -120,6 +122,25 @@ render_claude() {
 
 initialized() { [[ -f "$project/.harness/autonomy" ]]; }
 
+# release_age_exclude <version>: lists this package's exact version in
+# pnpm-workspace.yaml's minimumReleaseAgeExclude. pnpm refuses a version younger
+# than its minimum release age, also in a frozen CI install, and a harness
+# release is installed the day it is published. Prints added, present, or
+# manual (an inline list this cannot edit safely).
+release_age_exclude() {
+  local f="$project/pnpm-workspace.yaml" entry="'@data-matters.io/agent-harness@$1'"
+  if grep -qF "@data-matters.io/agent-harness@$1" "$f" 2>/dev/null; then echo present; return; fi
+  if grep -qE '^minimumReleaseAgeExclude:[[:space:]]*$' "$f" 2>/dev/null; then
+    sed -i "/^minimumReleaseAgeExclude:[[:space:]]*\$/a\\  - $entry" "$f"
+  elif grep -q '^minimumReleaseAgeExclude:' "$f" 2>/dev/null; then
+    echo manual; return
+  else
+    [[ ! -s "$f" || -z "$(tail -c1 "$f")" ]] || echo >>"$f"
+    printf 'minimumReleaseAgeExclude:\n  - %s\n' "$entry" >>"$f"
+  fi
+  echo added
+}
+
 cmd_install() {
   if ! initialized; then
     echo "harness: $project is not initialized (no .harness/autonomy); run \`harness init\`"
@@ -180,6 +201,8 @@ cmd_check() {
       fi
     done
   fi
+  [[ -f "$project/.github/dependabot.yml" ]] \
+    || notes+=(".github/dependabot.yml: missing; harness bumps arrive as Dependabot PRs (templates/.github/dependabot.yml)")
   rm -rf "$tmp"
   (( ${#notes[@]} == 0 )) || printf 'harness: note: %s\n' "${notes[@]}"
   if (( ${#problems[@]} > 0 )); then
@@ -255,6 +278,7 @@ cmd_init() {
   }
   seed "$gates_conf_src" .harness/gates.conf
   seed "$ci_src" .github/workflows/gates.yml
+  seed "$templates/.github/dependabot.yml" .github/dependabot.yml
   for p in "${seeded[@]}"; do
     seed "$(seed_src "$p")" "$p"
     mkdir -p "$(dirname "$project/.harness/seeded/$p")"
@@ -292,6 +316,13 @@ EOF
   for p in "${ignore_entries[@]}"; do
     grep -qxF "$p" "$project/.gitignore" || echo "$p" >>"$project/.gitignore"
   done
+  # A release-version (not a git commit) is excluded from pnpm's minimum age.
+  if [[ "$(version)" =~ ^[0-9]+\.[0-9]+\.[0-9]+ ]]; then
+    case "$(release_age_exclude "$(version)")" in
+      added) echo "pnpm-workspace.yaml: @data-matters.io/agent-harness@$(version) added to minimumReleaseAgeExclude" ;;
+      manual) conflicts+=("pnpm-workspace.yaml (add '@data-matters.io/agent-harness@$(version)' to minimumReleaseAgeExclude)") ;;
+    esac
+  fi
   # Next.js keeps its agent rules in AGENTS.md (ADR 0018).
   if [[ "$stack" == nextjs ]]; then
     echo "AGENTS.md: $("$pkg/scripts/next-agent-rules.sh" "$project")"
@@ -312,12 +343,17 @@ Next steps:
   1. Pin the harness and run it on every install (package.json):
        pnpm add -D -E @data-matters.io/agent-harness@$(version)
        "scripts": { "prepare": "harness install" }
-  2. Review .harness/gates.conf and .github/workflows/gates.yml (project-owned).
+     pnpm refuses a release younger than its minimum release age: the version
+     is in pnpm-workspace.yaml's minimumReleaseAgeExclude; Dependabot bumps
+     (.github/dependabot.yml) wait 2 days, so later versions need no entry.
+  2. Review .harness/gates.conf, .github/workflows/gates.yml and
+     .github/dependabot.yml (project-owned).
   3. Pin pnpm (ADR 0014): "packageManager": "pnpm@$HARNESS_PNPM_VERSION" and
      devEngines.packageManager { name pnpm, version $HARNESS_PNPM_VERSION, onFail error }.
      Add OpenSpec as a pinned devDependency (version in .harness/openspec.sh).
-  4. Commit the project-owned and seeded files, .harness/seeded/, CLAUDE.md and
-     .gitignore; run harness check, then .harness/gates.sh until it is green.
+  4. Commit the project-owned and seeded files, .harness/seeded/, CLAUDE.md,
+     .gitignore and pnpm-workspace.yaml; run harness check, then
+     .harness/gates.sh until it is green.
 EOF
   if [[ "$mode" == existing ]]; then
     echo "  5. Add characterization tests for the critical flows, then: echo enabled > .harness/autonomy"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@data-matters.io/agent-harness",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Spec-Driven Development with Claude Code: gates, task loop and standards installed into a product repository",
   "license": "UNLICENSED",
   "repository": {
@@ -25,7 +25,8 @@
   "engines": {
     "node": ">=22"
   },
+  "packageManager": "pnpm@12.11.2",
   "devDependencies": {
     "@changesets/cli": "3.0.3"
   }
-}
+}

package/standards/stack.md

@@ -8,6 +8,7 @@ standards, and differ only in the framework.
 | -------- | -------------------------------- | -------------------------------------- | ------------------------ |
 | `nextjs` | `data-matters-io/nextjs-new-app` | Web applications (UI + route handlers) | `stacks/nextjs/stack.md` |
 | `nestjs` | `data-matters-io/nestjs-new-app` | Backend services (HTTP APIs)           | `stacks/nestjs/stack.md` |
+| `vite`   | none (ADR 0023)                  | Static Vite + TypeScript sites, no DB  | `stacks/vite/stack.md`   |
 
 In a product repo, the chosen stack's files are in `.harness/standards/stack/`.
 
@@ -40,3 +41,4 @@ workflow (`gates.yml`) validated against each template:
 | -------- | ---------------------------- |
 | `nextjs` | see `stacks/nextjs/stack.md` |
 | `nestjs` | see `stacks/nestjs/stack.md` |
+| `vite`   | see `stacks/vite/stack.md`   |

package/standards/stacks/vite/architecture.md

@@ -0,0 +1,10 @@
+# Architecture: Vite static sites
+
+A static site: everything runs in the browser and `vite build` emits `dist/`.
+Deviations need an ADR in the product repo.
+
+- Source in `src/`, entry from `index.html`; tests beside the code.
+- No server, no database, no secrets: nothing in `src/` or `dist/` may hold one.
+- Keep pure logic (data, rules) in modules apart from DOM code, so it is
+  testable without a browser.
+- Dependencies are added only when the spec declares them (ADR 0015).

package/standards/stacks/vite/conventions.md

@@ -0,0 +1,13 @@
+# Conventions: Vite static sites
+
+Extends the shared `conventions.md`.
+
+- Type-only imports inline: `import { type Foo } from '…'`.
+- Import order is auto-fixed by lint (`@data-matters.io/eslint-config`).
+- Files are kebab-case `.ts`; tests are `<file>.test.ts` beside the code.
+- Env vars exposed to the client use the `VITE_` prefix and are never secret.
+
+## Local workflow
+
+`pnpm dev`, `pnpm build`, `pnpm test`, `pnpm lint`, `pnpm typecheck` and
+`pnpm gates` (all gates).

package/standards/stacks/vite/stack.md

@@ -0,0 +1,27 @@
+# Stack: Vite static sites
+
+No app template: the preset is derived from `data-matters-io/play-around-world`
+(ADR 0023), with `@data-matters.io/eslint-config` 4.0.0.
+
+| Area         | Choice                                    | Version |
+| ------------ | ----------------------------------------- | ------- |
+| Runtime      | Node.js (build and tooling only)          | 24.x    |
+| Bundler      | Vite, static output in `dist/`            | 8.x     |
+| Language     | TypeScript, `strict: true`                | 5.9.x   |
+| Testing      | Vitest + jsdom, coverage with istanbul    | 5.x     |
+| Lint preset  | `typescript`                              | 4.x     |
+| Backend / DB | None: no server, no Prisma, no PostgreSQL | —       |
+
+## Gates (`templates/stacks/vite/gates.conf`)
+
+| Gate      | Command                                                                        |
+| --------- | ------------------------------------------------------------------------------ |
+| setup     | none                                                                           |
+| test      | `vitest run` with istanbul (floor: 85% lines, statements, branches, functions) |
+| lint      | `eslint . --max-warnings 0`                                                    |
+| typecheck | `tsc --noEmit`                                                                 |
+| build     | `vite build`                                                                   |
+| db        | none (no database)                                                             |
+
+The coverage floor lives in `gates.conf`, not in `vite.config.ts`, so an agent
+cannot lower it.

package/standards/stacks/vite/testing.md

@@ -0,0 +1,25 @@
+# Testing: Vite static sites
+
+Extends the shared `testing.md`.
+
+Tooling: Vitest 5 with jsdom, coverage provider istanbul
+(`@vitest/coverage-istanbul`).
+
+## Tiers
+
+| Tier        | Pattern                        | Status              |
+| ----------- | ------------------------------ | ------------------- |
+| Unit        | `src/**/*.test.ts` beside code | in use; `test` gate |
+| Integration | none: there is no backend      | not applicable      |
+| E2E         | none yet                       | not a harness gate  |
+
+## Rules
+
+- Unit tests do not touch the network.
+- DOM code is tested through jsdom with accessible queries, not implementation
+  details.
+
+## Coverage floor
+
+85% on lines, statements, branches and functions, over every file matching
+`src/**/*.ts` (set in `gates.conf`).

package/templates/.github/dependabot.yml

@@ -0,0 +1,19 @@
+# Harness bumps (ADR 0021): a weekly PR for the exactly pinned
+# @data-matters.io/agent-harness, with its changelog in the PR body. Other
+# dependencies are not managed by Dependabot here.
+version: 2
+updates:
+  - package-ecosystem: npm
+    directory: /
+    schedule:
+      interval: weekly
+    allow:
+      - dependency-name: '@data-matters.io/agent-harness'
+    # pnpm refuses versions younger than its minimum release age unless they are
+    # listed in minimumReleaseAgeExclude (pnpm-workspace.yaml); waiting keeps the
+    # frozen install in CI green without editing that list on every bump.
+    cooldown:
+      default-days: 2
+    commit-message:
+      prefix: chore
+      include: scope

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

@@ -15,6 +15,11 @@ GATE_BUILD=""
 # 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=()

package/templates/.harness/lib.sh

@@ -91,6 +91,24 @@ harness_claude_flags() {
   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
@@ -101,11 +119,33 @@ harness_flag_value() {
 }
 
 # ------------------------------------------------- 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 '
-    let d = {}; try { d = JSON.parse(require("fs").readFileSync(process.argv[1], "utf8")); } catch {}
+  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");

package/templates/.harness/loop.sh

@@ -5,7 +5,7 @@
 #
 # Usage: .harness/loop.sh start <change-id> [run-tasks options]
 #        .harness/loop.sh status [change-id]
-#        .harness/loop.sh stop <change-id>
+#        .harness/loop.sh stop <change-id> [--after-task]
 #        .harness/loop.sh logs <change-id>
 #
 # The supervisor runs run-tasks.sh --open-pr and reacts to its exit code:
@@ -13,9 +13,16 @@
 #   2  escalated   → notify; a human takes over
 #   3  paused (account usage limit; run-tasks discarded the partial attempt)
 #      → notify, wait HARNESS_RESUME_INTERVAL seconds (default 900), try again
+#   4  stopped between two tasks (`stop --after-task`) → notify; restart later
 # run-tasks works in the change's own git worktree (ADR 0012): the checkout this
 # runs from is never switched or cleaned, so specs can be written meanwhile.
 # Notifications go through .harness/notify.sh (Telegram when configured).
+#
+# Started from inside a systemd unit (the spec PR watcher's oneshot service, any
+# other service), the supervisor gets a transient scope of its own
+# (systemd-run --user --scope, unit harness-loop-<project>-<change>-<time>):
+# setsid alone keeps it in the unit's cgroup, and systemd kills the cgroup when
+# the unit ends. `status` reports a supervisor that died before finishing.
 set -euo pipefail
 
 # shellcheck source-path=SCRIPTDIR source=lib.sh
@@ -33,8 +40,36 @@ die() { echo "loop: $*" >&2; exit 1; }
 pid_file() { echo "$state_dir/loop-$1.pid"; }
 running() { local f; f="$(pid_file "$1")"; [[ -f "$f" ]] && kill -0 "$(cat "$f")" 2>/dev/null; }
 
+# scope_prefix <change>: the systemd-run prefix that puts the supervisor in a
+# scope of its own when this runs inside a systemd unit (INVOCATION_ID), unless
+# it already is in a harness-loop scope; nothing otherwise or without a user
+# manager to talk to. It runs in a subshell (mapfile < <(...)), so the caller
+# must have XDG_RUNTIME_DIR set already: an export here would never reach the
+# systemd-run of the parent ("Failed to connect to bus").
+scope_prefix() {
+  [[ -n "${INVOCATION_ID:-}" ]] || return 0
+  grep -q '/harness-loop-[^/]*\.scope$' /proc/self/cgroup 2>/dev/null && return 0
+  command -v systemd-run >/dev/null 2>&1 || return 0
+  systemd-run --user --scope --quiet true >/dev/null 2>&1 || return 0
+  printf '%s\n' systemd-run --user --scope --quiet --collect \
+    --unit "harness-loop-$(basename "$root" | tr -c 'A-Za-z0-9_.\n-' '-')-$1-$(date +%s)" --
+}
+
+# close_inherited_fds: the supervisor outlives whoever started it, and a lock
+# fd it inherited (the spec PR watcher's, a project lock) would stay locked for
+# as long as the loop runs. Everything above stderr is closed.
+close_inherited_fds() {
+  local f fd
+  for f in /proc/$$/fd/*; do
+    fd="${f##*/}"
+    [[ "$fd" =~ ^[0-9]+$ ]] && (( fd > 2 )) && eval "exec $fd>&-" 2>/dev/null
+  done
+  return 0
+}
+
 supervise() {
   local change="$1"; shift
+  close_inherited_fds
   local interval="${HARNESS_RESUME_INTERVAL:-900}" log=".harness/logs/$change/runner.log" rc pr every reason
   mkdir -p ".harness/logs/$change"
   .harness/notify.sh started "Loop started for change $change"
@@ -57,6 +92,9 @@ supervise() {
         .harness/notify.sh paused "Change $change paused by the account usage limit; retrying every $every"
         sleep "$interval"
         .harness/notify.sh resumed "Resuming change $change" ;;
+      4)
+        .harness/notify.sh info "Change $change stopped at the end of a task on request; restart with .harness/loop.sh start $change"
+        break ;;
       *)
         .harness/notify.sh error "Change $change stopped with exit code $rc. See .harness/logs/$change/runner.log"
         break ;;
@@ -73,22 +111,52 @@ case "$cmd" in
     # Fail here, not in the background: the spec must be approved (merged into
     # the base branch through its spec PR, ADR 0011) and its worktree clean.
     .harness/run-tasks.sh "$change" --check "$@" >/dev/null || die "change $change cannot start (see above)"
-    setsid nohup "$0" __supervise "$change" "$@" >/dev/null 2>&1 </dev/null &
+    rm -f "$state_dir/stop-$change"   # a stop requested for an earlier run
+    # A systemd unit (a service) has no XDG_RUNTIME_DIR; the user bus is there.
+    [[ -z "${INVOCATION_ID:-}" ]] || export XDG_RUNTIME_DIR="${XDG_RUNTIME_DIR:-/run/user/$(id -u)}"
+    mapfile -t scope < <(scope_prefix "$change")
+    setsid nohup "${scope[@]}" "$0" __supervise "$change" "$@" >/dev/null 2>&1 </dev/null &
     echo $! >"$(pid_file "$change")"
+    # Do not return before the supervisor is in its scope: the unit that called
+    # this may end right after, and its cgroup is killed with whatever is left.
+    if (( ${#scope[@]} )); then
+      for (( i = 0; i < 100; i++ )); do
+        grep -q '/harness-loop-[^/]*\.scope$' "/proc/$!/cgroup" 2>/dev/null && break
+        kill -0 $! 2>/dev/null || break
+        sleep 0.1
+      done
+      grep -q '/harness-loop-[^/]*\.scope$' "/proc/$!/cgroup" 2>/dev/null \
+        || echo "loop: warning: the supervisor is not in its own systemd scope; it may stop with the calling unit" >&2
+    fi
     echo "loop: started $change in the background (pid $!). Follow it with .harness/loop.sh status $change"
     ;;
   __supervise)
     supervise "$@" ;;
   status)
     if [[ -n "${1:-}" ]]; then
-      running "$1" && echo "supervisor: running (pid $(cat "$(pid_file "$1")"))" || echo "supervisor: not running"
+      if running "$1"; then
+        echo "supervisor: running (pid $(cat "$(pid_file "$1")"))"
+      elif [[ -f "$(pid_file "$1")" ]]; then
+        # The supervisor removes its pid file when it finishes, even on errors.
+        echo "supervisor: DIED before finishing (pid $(cat "$(pid_file "$1")"), no final notification)." \
+          "Last runner and worktree-setup logs are in .harness/logs/$1/; restart with .harness/loop.sh start $1"
+      else
+        echo "supervisor: not running"
+      fi
       .harness/status.sh "$1"
     else
       .harness/status.sh
     fi ;;
   stop)
-    change="${1:-}"; [[ -n "$change" ]] || die "usage: loop.sh stop <change-id>"
+    change="${1:-}"; [[ -n "$change" ]] || die "usage: loop.sh stop <change-id> [--after-task]"
     running "$change" || die "no loop running for $change"
+    if [[ "${2:-}" == --after-task ]]; then
+      # Graceful: the task in progress finishes and is committed, then run-tasks
+      # exits between tasks and the supervisor ends (the worktree is kept).
+      touch "$state_dir/stop-$change"
+      echo "loop: $change will stop at the end of its current task"
+      exit 0
+    fi
     pkill -TERM -s "$(ps -o sid= -p "$(cat "$(pid_file "$change")")" | tr -d ' ')" || true
     rm -f "$(pid_file "$change")"
     .harness/notify.sh error "Loop for change $change stopped by request"
@@ -97,5 +165,5 @@ case "$cmd" in
     change="${1:-}"; [[ -n "$change" ]] || die "usage: loop.sh logs <change-id>"
     tail -n 40 ".harness/logs/$change/runner.log" ;;
   *)
-    sed -n '2,18p' "$0" | sed 's/^# \{0,1\}//'; exit 1 ;;
+    sed -n '2,24p' "$0" | sed 's/^# \{0,1\}//'; exit 1 ;;
 esac

package/templates/.harness/models.conf

@@ -27,4 +27,5 @@ TASK_ci_fix_retry=R3     # failing checks after a failed fix (watcher, ADR 0019)
 TASK_review_comments=R2  # owner comments on implementation/sync PRs (ADR 0019, 1b)
 TASK_diagnosis=R3        # explaining an escalation
 TASK_review=R3           # PR review
+TASK_archive_fix=R2      # editorial split of a merged requirement over 500 characters (ADR 0022)
 TASK_routine=R1          # hand edits around sync and archive

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

@@ -11,7 +11,11 @@
 # .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).
+# 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.
@@ -31,7 +35,10 @@
 # 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.
+#             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)
@@ -46,7 +53,7 @@
 #   HARNESS_COMMIT_TYPE      conventional commit type (default feat)
 set -euo pipefail
 
-usage() { sed -n '2,46p' "$0" | sed 's/^# \{0,1\}//'; exit "${1:-0}"; }
+usage() { sed -n '2,50p' "$0" | sed 's/^# \{0,1\}//'; exit "${1:-0}"; }
 die() { echo "run-tasks: $*" >&2; exit 1; }
 
 [[ $# -ge 1 ]] || usage 1
@@ -295,6 +302,14 @@ record() {
 }
 
 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
@@ -302,7 +317,7 @@ while line="$(next_task)"; [[ -n "$line" ]]; do
   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=""
+  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=""
@@ -314,26 +329,50 @@ while line="$(next_task)"; [[ -n "$line" ]]; do
     # 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)
-    # 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:-} \
-      >"$log_dir/task-$task_id-attempt-$attempt.json" 2>&1 || true
-
-    warn_if_untrusted "$log_dir/task-$task_id-attempt-$attempt.json"
+    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.
-    if grep -qiE "hit your (session|usage) limit|usage limit reached" "$log_dir/task-$task_id-attempt-$attempt.json"; then
+    # 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.

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

@@ -4,8 +4,12 @@
 #
 # Usage: .harness/spec-pr.sh <change-id>
 #
-#   1. validates the change with the pinned OpenSpec CLI (--strict) and its
-#      declared dependencies (.harness/deps.sh check);
+#   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
@@ -17,7 +21,7 @@
 #   HARNESS_BASE_BRANCH  branch the spec PR targets (default main)
 set -euo pipefail
 
-usage() { sed -n '2,17p' "$0" | sed 's/^# \{0,1\}//'; exit "${1:-0}"; }
+usage() { sed -n '2,20p' "$0" | sed 's/^# \{0,1\}//'; exit "${1:-0}"; }
 die() { echo "spec-pr: $*" >&2; exit 1; }
 
 [[ $# -eq 1 ]] || usage 1
@@ -47,12 +51,62 @@ 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"
@@ -88,7 +142,7 @@ if [[ -n "$url" ]]; then
 fi
 
 body="$(mktemp)"
-trap 'rm -f "$body"' EXIT
+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\`."

package/templates/.harness/status.sh

@@ -140,7 +140,7 @@ usage() {
   printf '%-16s %-5s %-30s %8s %10s %10s  %s\n' TASK LEVEL MODEL SESSIONS "COST US\$" "AVG US\$" "1ST-ATTEMPT PASS"
   tail -n +2 "$ledger" | awk -F'\t' '
     { k = $4 "\t" $5 "\t" $6; n[k]++; c[k] += $8
-      if ($12 == 1) { first[k]++; if ($11 == "pass" || $11 == "fixed" || $11 == "replied") ok[k]++ } }
+      if ($12 == 1 && $11 != "fallback") { first[k]++; if ($11 == "pass" || $11 == "fixed" || $11 == "replied") ok[k]++ } }
     END { for (k in n) { split(k, f, "\t")
             rate = first[k] ? sprintf("%d%% (%d/%d)", 100 * ok[k] / first[k], ok[k], first[k]) : "-"
             printf "%-16s %-5s %-30s %8d %10.2f %10.2f  %s\n", f[1], f[2], f[3], n[k], c[k], c[k] / n[k], rate } }' | sort

package/templates/CLAUDE.md.tmpl

@@ -46,15 +46,35 @@ an OpenSpec workflow or skill says `openspec <args>`, run
    `openspec-apply-change` skill are disabled in `.claude/settings.json`. Do
    not edit the approved spec while implementing; a spec change needs a new
    spec PR.
-5. **Archive**: right after the implementation PR is merged, archive the
-   change in a new branch and PR so the delta is merged into
-   `openspec/specs/`, then run the formatter on `openspec/` (the archive
-   output is not Prettier-formatted).
-
-A change that builds on another change's requirements is proposed only after
-that change is archived, and uses `MODIFIED` on the existing requirement
-instead of `ADDED` next to it. Otherwise the archived spec ends up with
-contradicting requirements that `openspec validate` does not detect.
+5. **Archive**: after the implementation PR is merged, the change is archived
+   on branch `archive/<change-id>` and the PR `archive: <change-id>` merges
+   its delta into `openspec/specs/`. The PR watcher does it by itself (ADR
+   0022): `openspec archive <id> --yes`, the formatter on `openspec/`
+   (`FORMAT_SPECS` in `.harness/gates.conf`; the archive output is not
+   formatted) and `validate --all --strict`. Where there is no watcher, do
+   the same by hand, in that order, on that branch. Merging the archive PR is
+   the user's action. If `validate --strict` fails after the archive because a
+   merged requirement is over 500 characters, the fix is editorial: split the
+   requirement or move detail into scenarios, without changing behaviour, and
+   list each edit in the PR description.
+
+**Dependencies between changes.** A change that builds on requirements another
+change adds or modifies lists it in `proposal.md` under an optional
+`## Depends on` section: one change id in backticks per bullet, e.g.
+``- `role-deactivation-guard` ``. `.harness/spec-pr.sh` checks that each id is
+a change (open, merged or archived); the watcher starts the change only after
+those are archived and archives in that order. Use `MODIFIED` on an existing
+requirement instead of `ADDED` next to it. Otherwise the archived spec ends up
+with contradicting requirements that `openspec validate` does not detect.
+
+**Whoever writes a spec simulates its archive.** The merged specs must still
+pass `.harness/openspec.sh validate --all --strict` after the archive, and a
+requirement over 500 characters, or a `MODIFIED` one that is not in
+`openspec/specs/` yet, only fails then. `.harness/spec-pr.sh` runs that
+simulation in a scratch copy of `openspec/` (archiving first the unarchived
+changes listed under `## Depends on`) and refuses the spec PR if it fails: fix
+the spec before opening the PR, keeping each requirement under 500 characters
+and the detail in scenarios.
 
 Write tasks so each one is small, independently verifiable by the gates, and
 ends in a green state. The loop picks the model from the task's reasoning
@@ -117,8 +137,10 @@ work; the task loop implements it.
   gate failure, explain the cause in the channel and propose the next step.
   The work in progress stays uncommitted in the loop worktree (path in the
   runner log); the loop refuses to restart until it is finished or discarded.
-- After the user merges the implementation PR, archive the change in a new
-  branch and PR.
+- After the user merges the implementation PR, the watcher opens the archive
+  PR (workflow step 5) and the channel is told. Without a watcher on this
+  machine, archive the change by hand in branch `archive/<change-id>`, as step
+  5 says.
 - Every comment you post on a pull request ends with the line
   `<!-- harness-agent -->`: GitHub may show it under the user's account, and
   the watcher ignores marked comments instead of treating them as review.

package/templates/stacks/nestjs/gates.conf

@@ -18,6 +18,9 @@ GATE_LINT="$bin/eslint . --max-warnings 0"
 GATE_TYPECHECK="$bin/tsc --noEmit -p tsconfig.json"
 GATE_BUILD="$bin/nest build"
 
+# Formats openspec/ after an archive (the archive output is not formatted).
+FORMAT_SPECS="$bin/prettier --write openspec"
+
 # Stop hook runs the fast gates; e2e and integration run in the loop and CI.
 STOP_GATES=(lint typecheck test)
 

package/templates/stacks/nextjs/gates.conf

@@ -21,6 +21,9 @@ GATE_LINT="$bin/eslint . --max-warnings 0"
 GATE_TYPECHECK="$bin/tsc --noEmit"
 GATE_BUILD="$bin/next build"
 
+# Formats openspec/ after an archive (the archive output is not formatted).
+FORMAT_SPECS="$bin/prettier --write openspec"
+
 # Stop hook runs the fast gates (~40s); build (~60s) runs in the loop and CI.
 STOP_GATES=(lint typecheck test)
 

package/templates/stacks/vite/gates.conf

@@ -0,0 +1,31 @@
+# Gate commands for a static Vite + TypeScript site (no database, no server).
+# Sourced by .harness/gates.sh from the repo root. Validated against
+# data-matters-io/play-around-world: vite 8.3.5, typescript 5.9.3, vitest 5.0.5,
+# @vitest/coverage-istanbul 5.0.5, jsdom 30.1.3, @data-matters.io/eslint-config 4.0.0.
+
+# Gates call node_modules/.bin directly instead of `pnpm exec`: a gate must never
+# install or mutate anything (same rule as the other stack presets). Dependencies
+# are installed beforehand (`pnpm install --frozen-lockfile`).
+bin="node_modules/.bin"
+
+# No setup step: nothing to generate before the gates run.
+GATE_SETUP=""
+
+# Coverage floor 85% on every metric, statement-based (istanbul), measured over
+# every source file (standards/testing.md). Kept here, not in vite.config.ts, so
+# an agent cannot lower it. Raise it as coverage grows; never lower it.
+GATE_TEST="$bin/vitest run --coverage.enabled --coverage.provider=istanbul --coverage.include='src/**/*.ts' --coverage.thresholds.lines=85 --coverage.thresholds.statements=85 --coverage.thresholds.branches=85 --coverage.thresholds.functions=85"
+# Read-only and zero warnings (@data-matters.io/eslint-config, typescript preset).
+GATE_LINT="$bin/eslint . --max-warnings 0"
+GATE_TYPECHECK="$bin/tsc --noEmit"
+GATE_BUILD="$bin/vite build"
+
+# Formats openspec/ after an archive (the archive output is not formatted).
+FORMAT_SPECS="$bin/prettier --write openspec"
+
+# Stop hook runs the fast gates; build runs in the loop and CI.
+STOP_GATES=(lint typecheck test)
+
+GATE_EXTRA=(
+  # "security:pnpm audit --audit-level high"
+)

package/templates/stacks/vite/gates.yml

@@ -0,0 +1,50 @@
+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
+
+      # Reads the exact pnpm version from package.json#packageManager (ADR 0014).
+      # pnpm 12 needs v6.1.0+; the floating @v6 tag is older.
+      - uses: pnpm/action-setup@v6.1.0
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 24
+          cache: pnpm
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      # A harness installed from the package (ADR 0021) is generated by the
+      # install's "prepare"; a missing or stale one fails here.
+      - name: Check the harness
+        run: if [[ -x node_modules/.bin/harness ]]; then node_modules/.bin/harness check; fi
+
+      # After the install: with the package, .harness/ is generated by it.
+      # 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"
+
+      # OpenSpec is a pinned devDependency (.harness/openspec.sh).
+      - 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