@data-matters.io/agent-harness 0.1.1 → 0.1.3

package/README.md

@@ -18,7 +18,7 @@ minimumReleaseAgeExclude:
 
 ```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

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "@data-matters.io/agent-harness",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Spec-Driven Development with Claude Code: gates, task loop and standards installed into a product repository",
   "license": "UNLICENSED",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/data-matters-io/data-matters-agent-harness.git"
+    "url": "git+https://github.com/data-matters-io/agent-harness.git"
   },
   "bin": {
     "harness": "bin/harness"

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/.claude/settings.json

@@ -43,6 +43,7 @@
       "Edit(./.harness/pr-scope.sh)",
       "Edit(./.harness/deps.sh)",
       "Edit(./.harness/db-smoke.sh)",
+      "Edit(./.harness/app-smoke.sh)",
       "Edit(./.harness/models.conf)",
       "Edit(./.harness/models.local.conf)",
       "Edit(./.harness/model-flags.sh)",

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

@@ -0,0 +1,107 @@
+#!/usr/bin/env bash
+# Application smoke gate (ADR 0024): builds the app, starts it against a migrated
+# and seeded database, runs the project's end-to-end smoke test, stops the app.
+# Meant for GATE_FINAL in gates.conf: it is slow (build + server + database), so
+# it runs once at the end of a change, not on every task or in the Stop hook.
+#
+# Usage: .harness/app-smoke.sh --url <url> --start <cmd> --test <cmd> [options]
+#   --url <url>       where the app answers; any HTTP response counts as up
+#   --start <cmd>     starts the server (runs in the background, in its own process group)
+#   --test <cmd>      the smoke test; its exit code is the gate's
+#   --build <cmd>     run first (e.g. the production build)
+#   --migrate <cmd> --seed <cmd>
+#                     prepare a throwaway database through .harness/db-smoke.sh
+#                     (ADR 0016); the commands get DATABASE_URL. Without them the
+#                     app runs against whatever the environment configures
+#   --if-exists <f>   pass without running anything when <f> does not exist, so a
+#                     preset can carry the gate for projects that may not have the test
+#   --wait <seconds>  how long to wait for the app (default 120)
+#
+# Example (gates.conf, nextjs):
+#   GATE_FINAL=("smoke:.harness/app-smoke.sh --if-exists scripts/smoke-test.ts \
+#     --migrate '$bin/prisma migrate deploy' --seed '$bin/prisma db seed' \
+#     --build '$bin/next build' --start '$bin/next start -p 3100' \
+#     --url http://127.0.0.1:3100 --test '$bin/tsx scripts/smoke-test.ts'")
+#
+# The server log goes to .harness/state/gates/app-smoke-server.log and its tail is
+# printed when the app does not come up or the test fails. A machine that cannot
+# run it skips the gate with HARNESS_SKIP_GATES=smoke (CI still can).
+set -euo pipefail
+
+usage() { sed -n '2,28p' "$0" | sed 's/^# \{0,1\}//'; exit "${1:-0}"; }
+die() { echo "app-smoke: $*" >&2; exit 1; }
+
+url="" start="" test_cmd="" build="" migrate="" seed="" if_exists="" wait_s=120 inner=0
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --url) url="${2:?}"; shift 2 ;;
+    --start) start="${2:?}"; shift 2 ;;
+    --test) test_cmd="${2:?}"; shift 2 ;;
+    --build) build="${2:?}"; shift 2 ;;
+    --migrate) migrate="${2:?}"; shift 2 ;;
+    --seed) seed="${2:?}"; shift 2 ;;
+    --if-exists) if_exists="${2:?}"; shift 2 ;;
+    --wait) wait_s="${2:?}"; shift 2 ;;
+    --inner) inner=1; shift ;;
+    -h|--help) usage 0 ;;
+    *) die "unknown option: $1" ;;
+  esac
+done
+[[ -n "$url" && -n "$start" && -n "$test_cmd" ]] || usage 1
+[[ "$wait_s" =~ ^[0-9]+$ ]] || die "--wait needs a number of seconds"
+[[ "$url" =~ ^https?://([^/:]+):([0-9]+)(/.*)?$ ]] || die "--url needs http(s)://host:port"
+host="${BASH_REMATCH[1]}" port="${BASH_REMATCH[2]}"
+
+if [[ -n "$if_exists" && ! -e "$if_exists" ]]; then
+  echo "app-smoke: no $if_exists in this project; nothing to run"
+  exit 0
+fi
+
+# With a database to prepare, hand over to db-smoke.sh, which keeps its container
+# alive while this script runs again (--inner) as its check command.
+if [[ $inner -eq 0 && ( -n "$migrate" || -n "$seed" ) ]]; then
+  [[ -n "$migrate" && -n "$seed" ]] || die "--migrate and --seed go together"
+  inner_cmd="$(printf '%q ' "$0" --inner --url "$url" --start "$start" --test "$test_cmd" --wait "$wait_s")"
+  [[ -z "$build" ]] || inner_cmd+="$(printf -- "--build %q" "$build")"
+  exec "$(dirname "$0")/db-smoke.sh" "$migrate" "$seed" "$inner_cmd"
+fi
+
+log_dir="${HARNESS_STATE_DIR:-.harness/state}/gates"
+mkdir -p "$log_dir"
+server_log="$log_dir/app-smoke-server.log"
+server_pid=""
+stop_server() {
+  [[ -n "$server_pid" ]] || return 0
+  kill -TERM -- "-$server_pid" 2>/dev/null || true
+  sleep 1
+  kill -KILL -- "-$server_pid" 2>/dev/null || true
+}
+trap stop_server EXIT
+show_server_log() { echo "----- last 40 lines of the server log -----"; tail -n 40 "$server_log" 2>/dev/null || true; echo "-----"; }
+
+export PATH="$PWD/node_modules/.bin:$PATH"
+if [[ -n "$build" ]]; then
+  echo "app-smoke: build: $build"
+  bash -c "$build" || die "build failed"
+fi
+
+# The port must be free: a leftover server would answer instead of this build.
+if (exec 3<>"/dev/tcp/$host/$port") 2>/dev/null; then die "$host:$port is already in use"; fi
+echo "app-smoke: start: $start"
+setsid bash -c "$start" >"$server_log" 2>&1 &
+server_pid=$!
+
+up=0
+for (( i = 0; i < wait_s; i++ )); do
+  kill -0 "$server_pid" 2>/dev/null || { show_server_log; die "the app exited before answering on $url"; }
+  if (exec 3<>"/dev/tcp/$host/$port") 2>/dev/null; then up=1; break; fi
+  sleep 1
+done
+[[ $up -eq 1 ]] || { show_server_log; die "the app did not answer on $url within ${wait_s}s"; }
+
+echo "app-smoke: test: $test_cmd"
+if ! BASE_URL="${url%/}" bash -c "$test_cmd"; then
+  show_server_log
+  die "the smoke test failed"
+fi
+echo "app-smoke: passed"

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

@@ -29,3 +29,12 @@ GATE_EXTRA=(
   # "coverage:npm run test:coverage -- --coverage.thresholds.lines=80"
   # "security:npm audit --audit-level=high"
 )
+
+# Optional final gates (ADR 0024): slow end-to-end checks ("name:command"). The task
+# loop runs them once, after the last task and before the change's PR opens; a
+# failure gets repair sessions. Never in a default run, the Stop hook or per task.
+# `.harness/gates.sh --final` (or `gates.sh <name>`) runs them by hand or in CI.
+# .harness/app-smoke.sh builds, starts the app on a seeded database and runs a test.
+GATE_FINAL=(
+  # "smoke:.harness/app-smoke.sh --if-exists scripts/smoke-test.ts --migrate '...' --seed '...' --build '...' --start '...' --url http://127.0.0.1:3100 --test '...'"
+)

package/templates/.harness/gates.sh

@@ -2,10 +2,14 @@
 # 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)
+# Usage: .harness/gates.sh [--stop|--final] [gate ...]
+#   no args   run every gate but the final ones (task loop, CI)
 #   --stop    run only STOP_GATES from gates.conf (fast profile for the Stop hook)
-#   gate ...  run only the named gates
+#   --final   run only GATE_FINAL from gates.conf: slow end-to-end checks that run
+#             once, at the end of a change in the task loop, before its PR opens
+#             (ADR 0024); `gates.sh --final` runs them in CI or by hand
+#   --has-final  exit 0 when GATE_FINAL is not empty, 1 otherwise (runs nothing)
+#   gate ...  run only the named gates (final ones included)
 #
 # HARNESS_SKIP_GATES="name ..." skips the named gates on this machine (e.g.
 # integration where no container runtime exists). Skips are printed on every
@@ -25,12 +29,22 @@ REQUIRED_GATES=(test lint typecheck build)
 GATE_EXTRA=()
 GATE_SETUP=""
 STOP_GATES=()
+GATE_FINAL=()
 # shellcheck source=/dev/null
 source "$conf"
 
 selected=("$@")
 if [[ "${1-}" == "--stop" ]]; then
   selected=("${STOP_GATES[@]}")
+elif [[ "${1-}" == "--has-final" ]]; then
+  [[ ${#GATE_FINAL[@]} -gt 0 ]]; exit
+elif [[ "${1-}" == "--final" ]]; then
+  selected=()
+  for entry in "${GATE_FINAL[@]}"; do selected+=("${entry%%:*}"); done
+  if [[ ${#selected[@]} -eq 0 ]]; then
+    echo "gates: no final gates configured (GATE_FINAL)"
+    exit 0
+  fi
 fi
 
 log_dir="$root/.harness/state/gates"
@@ -49,9 +63,18 @@ for entry in "${GATE_EXTRA[@]}"; do
   names+=("${entry%%:*}")
   cmds+=("${entry#*:}")
 done
+# Final gates run only on request (--final or by name), never in a default run.
+final_names=" "
+for entry in "${GATE_FINAL[@]}"; do
+  names+=("${entry%%:*}")
+  cmds+=("${entry#*:}")
+  final_names+="${entry%%:*} "
+done
 
 is_selected() {
-  [[ ${#selected[@]} -eq 0 ]] && return 0
+  if [[ ${#selected[@]} -eq 0 ]]; then
+    [[ "$final_names" != *" $1 "* ]]; return
+  fi
   local s
   for s in "${selected[@]}"; do [[ "$s" == "$1" ]] && return 0; done
   return 1

package/templates/.harness/lib.sh

@@ -93,9 +93,11 @@ harness_claude_flags() {
 
 # 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.
+# another model..."), not on the work. Claude Code names the window in the
+# message ("You've hit your 5-hour limit", "...your weekly limit", "...your
+# session limit") and sets api_error to usage_limit_reached, so both are matched.
 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
+  grep -qiE "hit your [^\"]{0,40}limit|usage_limit_reached|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

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

@@ -16,6 +16,10 @@
 # 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.
+# After the last task, the final gates (GATE_FINAL in gates.conf, ADR 0024:
+# slow end-to-end checks such as the app smoke test) run once, before the PR is
+# opened; a failure gets up to HARNESS_FINAL_ATTEMPTS repair sessions with the
+# output as feedback, then escalates. A change with no GATE_FINAL skips the step.
 # 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.
@@ -47,13 +51,14 @@
 #                            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_FINAL_ATTEMPTS   repair sessions for failing final gates (default 2)
 #   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}"; }
+usage() { sed -n '2,54p' "$0" | sed 's/^# \{0,1\}//'; exit "${1:-0}"; }
 die() { echo "run-tasks: $*" >&2; exit 1; }
 
 [[ $# -ge 1 ]] || usage 1
@@ -436,6 +441,81 @@ while line="$(next_task)"; [[ -n "$line" ]]; do
   fi
 done
 
+# ---- final gates (ADR 0024): once, after the last task, before the PR opens.
+# They are slow (build, server, database), so they are not part of every task's
+# gates. A failure is repaired like a task: the agent gets the output, the loop
+# re-runs the gates. HARNESS_SKIP_GATES skips them like any other gate.
+final_attempts="${HARNESS_FINAL_ATTEMPTS:-2}"
+final_gate_out=""
+if [[ -x .harness/gates.sh ]] && .harness/gates.sh --has-final; then
+  echo "==> final gates"
+  final_ok=0
+  for (( attempt = 0; attempt <= final_attempts; attempt++ )); do
+    if (( attempt > 0 )); then
+      level="$(harness_task_level impl "")" || level="R2"
+      level="$(harness_level_climb "$level" "$attempt")"
+      level_flags="$(harness_level_flags "$level")"
+      cur_task_id="final"; cur_task="final gates"; cur_attempt="$attempt"; attempt_started="$(date +%s)"
+      write_state
+      echo "    repair $attempt/$final_attempts at $level${level_flags:+ ($level_flags)}"
+      start=$(date +%s)
+      session_json="$log_dir/task-final-attempt-$attempt.json"
+      # shellcheck disable=SC2086
+      build_prompt "make the final gates pass: .harness/gates.sh --final (end-to-end checks run once at the end of the change). Fix the code or tests the change touched; the approved spec is the reference." "$final_gate_out" \
+        | 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"
+      if harness_usage_error "$session_json"; then
+        record final "$attempt" "$(( $(date +%s) - start ))" paused
+        run_status="paused"
+        git checkout -- . && git clean -fdq
+        echo "run-tasks: the agent session hit the account usage limit; pausing." >&2
+        echo "  The final gates are not done; re-run after the limit resets." >&2
+        exit 3
+      fi
+      git checkout -- "$change_dir"
+      git clean -fdq -- "$change_dir"
+      if [[ -n "$(git status --porcelain -- "${dep_files[@]}")" ]]; then
+        record final "$attempt" "$(( $(date +%s) - start ))" deps
+        run_status="escalated"
+        echo "run-tasks: the final-gates repair changed dependency files; undeclared dependencies need a spec change." >&2
+        exit 2
+      fi
+    fi
+    # A repair must keep every other gate green too.
+    if (( attempt > 0 )) && ! gate_out="$(.harness/gates.sh 2>&1)"; then
+      record final "$attempt" "$(( $(date +%s) - start ))" fail
+      final_gate_out="$(tail -n 120 <<<"$gate_out")"
+      echo "    FAIL (the repair broke the regular gates)"
+      continue
+    fi
+    if final_gate_out="$(.harness/gates.sh --final 2>&1)"; then
+      (( attempt == 0 )) || record final "$attempt" "$(( $(date +%s) - start ))" pass
+      final_ok=1
+      break
+    fi
+    printf '%s\n' "$final_gate_out" >"$log_dir/final-gates-attempt-$attempt.log"
+    (( attempt == 0 )) || record final "$attempt" "$(( $(date +%s) - start ))" fail
+    final_gate_out="$(tail -n 120 <<<"$final_gate_out")"
+    echo "    FAIL (final gates)"
+  done
+  if [[ $final_ok -eq 0 ]]; then
+    run_status="escalated"
+    echo "run-tasks: the final gates still fail after $final_attempts repair attempts; escalating." >&2
+    echo "  Work in progress is left on branch $branch in $wt. Logs: $log_dir/final-gates-attempt-*.log" >&2
+    exit 2
+  fi
+  if [[ -n "$(git status --porcelain)" ]]; then
+    git add -A
+    printf 'fix(%s): make the final gates pass\n\nRepaired by the task loop after .harness/gates.sh --final failed:\n\n%s\n' \
+      "$change" "$(head -n 20 "$log_dir/final-gates-attempt-0.log" 2>/dev/null)" | fold -s -w 72 | git commit -q -F -
+    echo "    final gates repaired → committed"
+  fi
+  echo "    final gates PASS"
+fi
+
 run_status="done"
 cur_task_id=""; cur_task=""; cur_attempt=0; attempt_started=""
 echo "run-tasks: all tasks in $tasks are done."

package/templates/stacks/nextjs/gates.conf

@@ -24,6 +24,10 @@ GATE_BUILD="$bin/next build"
 # Formats openspec/ after an archive (the archive output is not formatted).
 FORMAT_SPECS="$bin/prettier --write openspec"
 
+# Placeholder environment for the smoke test's build and server: no real login or
+# external service is involved (the test signs its own sessions with the secret).
+smoke_env="NEXTAUTH_URL=http://127.0.0.1:3100 NEXTAUTH_SECRET=harness-smoke-secret-not-used-anywhere-else GOOGLE_CLIENT_ID=smoke.apps.googleusercontent.com GOOGLE_CLIENT_SECRET=smoke NEXT_TELEMETRY_DISABLED=1"
+
 # Stop hook runs the fast gates (~40s); build (~60s) runs in the loop and CI.
 STOP_GATES=(lint typecheck test)
 
@@ -34,3 +38,13 @@ GATE_EXTRA=(
   "db:.harness/db-smoke.sh '$bin/prisma migrate deploy' '$bin/prisma db seed'"
   # "security:pnpm audit --audit-level high"
 )
+
+# Final gates (ADR 0024): slow end-to-end checks. The task loop runs them once, at
+# the end of a change, before its PR opens (not per task, not in the Stop hook);
+# `.harness/gates.sh --final` runs them by hand. The end-to-end smoke test needs a
+# migrated and seeded database and a running app; the gate passes by itself in a
+# project without scripts/smoke-test.ts. HARNESS_SKIP_GATES=smoke on a machine
+# without a container runtime; CI runs it in its own e2e job.
+GATE_FINAL=(
+  "smoke:.harness/app-smoke.sh --if-exists scripts/smoke-test.ts --migrate '$bin/prisma migrate deploy' --seed '$bin/prisma db seed' --build 'env $smoke_env $bin/next build' --start 'env $smoke_env $bin/next start -p 3100' --url http://127.0.0.1:3100 --test 'env $smoke_env $bin/tsx scripts/smoke-test.ts'"
+)

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