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

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

@@ -0,0 +1,103 @@
+#!/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) and its
+#      declared dependencies (.harness/deps.sh check);
+#   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,17p' "$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
+
+# 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"
+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 -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"

package/templates/.harness/status.sh

@@ -0,0 +1,155 @@
+#!/usr/bin/env bash
+# Shows the state of OpenSpec changes and of the task loop.
+#
+# Usage: .harness/status.sh              # overview of every active change
+#        .harness/status.sh <change-id>  # details: tasks, runner, attempts, cost, last failure
+#        .harness/status.sh --usage      # machine ledger: cost and first-attempt success
+#                                        # per task type, level and model (ADR 0020)
+#
+# Progress of a change the loop is working on is read from its worktree (ADR 0012),
+# so it does not depend on the branch checked out here.
+set -euo pipefail
+
+# shellcheck source-path=SCRIPTDIR source=lib.sh
+. "$(dirname "${BASH_SOURCE[0]}")/lib.sh"
+root="$(harness_root)"
+cd "$root"
+
+now=$(date +%s)
+changes_dir="openspec/changes"
+
+human_duration() {
+  local s=$1
+  if (( s >= 3600 )); then printf '%dh%02dm' $((s / 3600)) $((s % 3600 / 60))
+  elif (( s >= 60 )); then printf '%dm%02ds' $((s / 60)) $((s % 60))
+  else printf '%ds' "$s"; fi
+}
+
+# tasks_of <change-id>: prints its tasks.md from the loop worktree, else from the
+# change/<id> branch (worktree already removed), else from this checkout.
+tasks_of() {
+  local wt file="$changes_dir/$1/tasks.md"
+  wt="$(harness_worktree "$1")"
+  if [[ -f "$wt/$file" ]]; then cat "$wt/$file"
+  elif git cat-file -e "refs/heads/change/$1:$file" 2>/dev/null; then git show "refs/heads/change/$1:$file"
+  elif [[ -f "$file" ]]; then cat "$file"
+  else return 1; fi
+}
+
+# Changes active here or in a loop worktree, one per line.
+active_changes() {
+  local dir wt_parent
+  wt_parent="$(dirname "$(harness_worktree x)")"
+  for dir in "$changes_dir"/*/ "$wt_parent"/*/"$changes_dir"/*/; do
+    [[ -f "$dir/tasks.md" ]] && basename "$dir"
+  done | grep -vx archive | sort -u || true
+}
+
+# count_tasks <tasks.md content> → "<done> <total>"
+count_tasks() {
+  local n_done total
+  n_done=$(grep -cE '^[[:space:]]*- \[[xX]\] ' <<<"$1" || true)
+  total=$(grep -cE '^[[:space:]]*- \[[ xX]\] ' <<<"$1" || true)
+  echo "$n_done $total"
+}
+
+# Reads the runner state file into state_* variables; returns 1 if absent.
+load_state() {
+  local file=".harness/state/run-$1" key value
+  state_status="" state_pid="" state_task_id="" state_task="" state_attempt="" state_max_attempts=""
+  # shellcheck disable=SC2034  # state_updated is part of the file format, unused here
+  state_started="" state_attempt_started="" state_updated=""
+  [[ -f "$file" ]] || return 1
+  while IFS='=' read -r key value; do
+    printf -v "state_$key" '%s' "$value"
+  done <"$file"
+  # A "running" state whose process is gone was killed without cleanup.
+  if [[ "$state_status" == running ]] && ! kill -0 "$state_pid" 2>/dev/null; then
+    state_status="stale"
+  fi
+}
+
+total_cost() {
+  local dir=".harness/logs/$1"
+  [[ -d "$dir" ]] || { echo "0.00"; return; }
+  cat "$dir"/task-*-attempt-*.json 2>/dev/null \
+    | grep -o '"total_cost_usd":[0-9.]*' | cut -d: -f2 \
+    | awk '{ s += $1 } END { printf "%.2f", s }'
+}
+
+overview() {
+  local found=0 change counts
+  printf '%-36s %-8s %-12s %s\n' CHANGE TASKS LOOP COST
+  while IFS= read -r change; do
+    [[ -n "$change" ]] || continue
+    found=1
+    read -r d t <<<"$(count_tasks "$(tasks_of "$change")")"
+    counts="$d/$t"
+    if load_state "$change"; then loop="$state_status"; else loop="-"; fi
+    printf '%-36s %-8s %-12s US$ %s\n' "$change" "$counts" "$loop" "$(total_cost "$change")"
+  done < <(active_changes)
+  (( found )) || echo "(no active changes in $changes_dir)"
+}
+
+details() {
+  local change="$1" tasks log_dir=".harness/logs/$1"
+  tasks="$(tasks_of "$1")" || { echo "status: no change $1 (no $changes_dir/$1/tasks.md here, in its worktree or on change/$1)" >&2; exit 1; }
+
+  read -r d t <<<"$(count_tasks "$tasks")"
+  echo "Change: $change  ($d/$t tasks done, US\$ $(total_cost "$change") spent)"
+  echo
+  grep -E '^[[:space:]]*- \[[ xX]\] ' <<<"$tasks" | sed -E \
+    -e 's/^[[:space:]]*- \[[xX]\] /  [x] /' -e 's/^[[:space:]]*- \[ \] /  [ ] /' \
+    | cut -c1-100
+  echo
+
+  if load_state "$change"; then
+    echo "Loop: $state_status  (started $(human_duration $((now - state_started))) ago)"
+    if [[ "$state_status" == running || "$state_status" == stale ]]; then
+      echo "  task $state_task_id, attempt $state_attempt/$state_max_attempts," \
+        "running for $(human_duration $((now - state_attempt_started)))"
+      echo "  $state_task"
+    fi
+  else
+    echo "Loop: never run"
+  fi
+
+  if [[ -f "$log_dir/summary.tsv" ]] && (( $(wc -l <"$log_dir/summary.tsv") > 1 )); then
+    echo
+    echo "Attempts:"
+    tail -n +2 "$log_dir/summary.tsv" | while IFS=$'\t' read -r ts task attempt dur result level model effort cost _; do
+      printf '  %-6s attempt %-2s %-5s %8s   %s' "$task" "$attempt" "$result" "$(human_duration "$dur")" "${ts:0:19}"
+      [[ -n "${level:-}" ]] && printf '   %s %s/%s US$ %s' "$level" "$model" "$effort" "$cost"
+      echo
+    done
+  fi
+
+  local last_fail
+  last_fail="$(ls -t "$log_dir"/task-*-attempt-*.gates.log 2>/dev/null | head -n1 || true)"
+  if [[ -n "$last_fail" ]]; then
+    echo
+    echo "Last failure: $last_fail"
+    grep -E '^(FAIL|gates:)' "$last_fail" | sed 's/^/  /'
+  fi
+}
+
+# usage: aggregates the machine-wide ledger (ADR 0020, calibration).
+usage() {
+  local ledger="${HARNESS_USAGE_LEDGER:-$HOME/.local/state/harness/usage.tsv}"
+  [[ -s "$ledger" ]] || { echo "(no sessions recorded in $ledger)"; return 0; }
+  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]++ } }
+    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
+  printf '%-16s %-5s %-30s %8s %10.2f\n' total "" "" "$(( $(wc -l <"$ledger") - 1 ))" \
+    "$(tail -n +2 "$ledger" | awk -F'\t' '{ s += $8 } END { print s + 0 }')"
+}
+
+case "${1:-}" in
+  "") overview ;;
+  --usage) usage ;;
+  *) details "$1" ;;
+esac

package/templates/CLAUDE.md.tmpl

@@ -0,0 +1,137 @@
+# CLAUDE.md — `{{PROJECT_NAME}}`
+
+<!-- Project-specific context goes in the "Project" section at the end.
+     Everything above it comes from agent-harness (version in
+     .harness/VERSION). -->
+
+## Language rule (mandatory)
+
+- **Every artifact you produce MUST be in English**: code, identifiers,
+  comments, docs, specs, commit messages, PR text, logs.
+- **Chat is the only exception**: reply in the same language the user writes in.
+
+## Standards
+
+Follow these; they are the source of truth for how this product is built.
+Shared standards are in `.harness/standards/`; the ones specific to this
+product's stack are in `.harness/standards/stack/`.
+
+{{STANDARDS_IMPORTS}}
+
+## Workflow: Spec-Driven Development (OpenSpec)
+
+The OpenSpec CLI is a pinned devDependency, never a global install: wherever
+an OpenSpec workflow or skill says `openspec <args>`, run
+`.harness/openspec.sh <args>` instead.
+
+1. **Propose**: every non-trivial change starts as an OpenSpec change under
+   `openspec/changes/<change-id>/` (`proposal.md`, delta `specs/`, optional
+   `design.md`, `tasks.md`), e.g. with `/opsx:propose`. Write only those
+   files; nothing else in the repository changes in a proposal.
+2. **Spec PR (last step of proposing)**: run `.harness/spec-pr.sh <change-id>`.
+   It validates the change (`--strict`), moves it to branch `spec/<change-id>`
+   from `main`, refuses files outside the change directory, commits, pushes
+   and opens (or updates) the PR `spec: <change-id>`, printing its URL. CI
+   validates a spec PR with OpenSpec instead of the gates.
+3. **Human checkpoint**: the user reviews and comments on the spec PR.
+   Address comments by editing the change on `spec/<change-id>` and running
+   `.harness/spec-pr.sh <change-id>` again. **Merging the spec PR is the
+   approval**; never merge it yourself and never implement before it is
+   merged. `.harness/run-tasks.sh` refuses a change that is not on `main`.
+4. **Apply**: only the task loop implements a change:
+   `.harness/loop.sh start <change-id>` (or `.harness/run-tasks.sh`), one
+   fresh session per task, on a new branch `change/<change-id>` created from
+   `main`; it opens the implementation PR linking the spec PR. Do not
+   implement tasks in an interactive session: `/opsx:apply` and the
+   `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.
+
+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
+level (ADR 0020): mark a task `<!-- level: R3 -->` at the end of its line when
+it needs design judgement the spec cannot fully pin down, `<!-- level: R1 -->`
+when it is a mechanical edit, and nothing otherwise (R2).
+
+**Dependencies (ADR 0015).** A change that adds packages declares them in
+`design.md` under `## Dependencies`, one bullet each, with exact versions:
+`- dependency: <name>@<x.y.z>`, `- devDependency: <name>@<x.y.z>`, and
+`- allow-build: <name>` only for a package that must run its install script.
+The reviewer approves them with the spec. The task loop installs exactly these
+before the first task (`.harness/deps.sh`), denies any other install script,
+and refuses changes to other dependencies. No task adds packages, and an agent
+in the loop never edits `package.json`, the lockfile or `pnpm-workspace.yaml`:
+a missing package escalates and needs a spec change.
+
+## Definition of Done
+
+- Done means `.harness/gates.sh` exits 0. Your own assessment is not enough.
+- A `Stop` hook runs the gates when you finish with uncommitted changes and
+  sends failures back to you.
+- Never make gates pass by deleting, skipping or weakening tests, or by
+  editing `.harness/gates.*` or `.claude/`.
+- Never invert the intent of an existing test to match the code. If an
+  existing test conflicts with the code or cannot pass honestly, stop and
+  report the conflict; the human decides which one is wrong. A confirmed bug
+  that is out of scope is recorded with `it.failing` and an exact assertion.
+
+## When the user talks to you through a channel (Telegram)
+
+You are the session the user reaches from the channel. You plan and start
+work; the task loop implements it.
+
+- A request for a change becomes an OpenSpec change (`/opsx:propose`) and
+  ends with `.harness/spec-pr.sh <change-id>` (workflow steps 1–2). Reply in
+  the channel with the PR link and a short summary: why, the requirements and
+  scenarios, the tasks, and any behaviour change. Then wait.
+- Review comments on the spec PR or in the channel are addressed on
+  `spec/<change-id>` and pushed with `.harness/spec-pr.sh <change-id>`; reply
+  with what changed.
+- Merging the spec PR starts the work: the spec PR watcher (ADR 0017) runs
+  `.harness/loop.sh start <change-id>` and notifies the channel, and it also
+  addresses the user's review comments on the spec PR by itself. With
+  `HARNESS_WATCH_PR_HEALTH=fix` it also fixes failing checks and conflicts on
+  every PR and handles review comments on implementation and sync PRs
+  (ADR 0019). Do not start the loop again or address those comments in this
+  session. If the user asks
+  you to start and `.harness/loop.sh status <change-id>` shows no loop (no
+  watcher on this machine), check the merge with `gh pr view spec/<change-id>`
+  and run `.harness/loop.sh start <change-id>`, then reply that it started.
+  The loop works in its own git worktree, so you can keep writing other specs
+  here meanwhile; never edit that worktree yourself. Never merge the spec PR,
+  never implement the tasks yourself in this session, and never approve on
+  the user's behalf.
+- The loop reports progress to the channel by itself (task passed, paused by
+  the usage limit, escalated, done with the PR link). When asked for status,
+  answer from `.harness/loop.sh status <change-id>`.
+- If the loop escalates, read `.harness/status.sh <change-id>` and the last
+  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.
+- 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.
+
+## When running inside the task loop
+
+The loop prompt tells you when you are in it. In that case:
+
+- Implement **only** the assigned task. Do not start other tasks.
+- Do **not** edit `tasks.md`, commit, or push; the loop does that.
+- If the task is impossible or the spec is ambiguous, stop and explain why in
+  your final message instead of guessing.
+
+## Project
+
+<!-- Architecture overview, key commands, domain vocabulary, gotchas. -->

package/templates/openspec/config.yaml

@@ -0,0 +1,38 @@
+schema: spec-driven
+
+context: |
+  Language: English. All artifacts must be written in English.
+  Keep OpenSpec structural headings and SHALL/MUST keywords in English.
+
+  This project follows the agent-harness standards. Read them before writing
+  any artifact and do not contradict them:
+    - .harness/standards/*.md        shared: conventions, testing, dod, stack
+    - .harness/standards/stack/*.md  this product's stack: stack, architecture,
+                                     conventions, testing
+  Done means `.harness/gates.sh` exits 0 (see dod.md).
+
+rules:
+  proposal:
+    - Include a "Non-goals" section.
+    - Call out any behaviour change to existing code explicitly.
+  specs:
+    - Every requirement has at least one "#### Scenario:" that maps to an automated test.
+    - Security-relevant requirements include a negative scenario (what must be rejected).
+    - To change an existing requirement use MODIFIED with its full text; do not ADD a contradicting one.
+  design:
+    - "Packages the change adds go in a '## Dependencies' section, one bullet each: '- dependency: <name>@<x.y.z>' or '- devDependency: <name>@<x.y.z>' (exact versions; '- allow-build: <name>' only when a package must run its install script). The task loop installs exactly these; anything else escalates."
+  tasks:
+    - Do not write tasks that add, remove or update packages; the loop installs the dependencies declared in design.md before the first task.
+    - 'Mark a task <!-- level: R3 --> at the end of its line when it needs design judgement the spec cannot fully pin down, <!-- level: R1 --> when it is a mechanical edit; leave it out otherwise (R2). The loop picks the model from the level (ADR 0020).'
+    - Use checkbox lines "- [ ] N.M <description>"; the task loop parses this exact format.
+    - Start each task with a short imperative title sentence; it becomes the commit subject.
+    - Each task is small, independently implementable, and leaves every gate green.
+    - Each task names the files it touches and the tests it adds.
+    - Do not include tasks for manual QA, deployment or archiving.
+
+operations:
+  apply:
+    guidance:
+      - Only the harness task loop applies changes (.harness/loop.sh start <change-id>), after the spec PR is merged.
+      - Implement one task at a time; run .harness/gates.sh before finishing.
+      - Never change what an existing test asserts; report conflicts instead.

package/templates/stacks/nestjs/gates.conf

@@ -0,0 +1,32 @@
+# Gate commands for a NestJS service created from data-matters-io/nestjs-new-app.
+# Sourced by .harness/gates.sh.
+#
+# Gates call node_modules/.bin directly instead of `pnpm exec`: pnpm 11 runs a
+# dependency check before `exec` that may trigger `pnpm install`, and a gate must
+# never install or mutate anything. Dependencies are installed beforehand
+# (`make setup` locally, `pnpm install --frozen-lockfile` in CI).
+bin="node_modules/.bin"
+
+GATE_SETUP="$bin/prisma generate"
+
+# Coverage floor: set just below the template's measured coverage. Raise it
+# as coverage grows; never lower it (standards/testing.md).
+GATE_TEST="$bin/jest --silent --coverage --coverageThreshold='{\"global\":{\"lines\":85,\"statements\":85,\"branches\":85,\"functions\":85}}'"
+# Read-only and zero warnings: warnings still count as not done.
+GATE_LINT="$bin/eslint . --max-warnings 0"
+# The root tsconfig also covers tests (tsconfig.build.json excludes them).
+GATE_TYPECHECK="$bin/tsc --noEmit -p tsconfig.json"
+GATE_BUILD="$bin/nest build"
+
+# Stop hook runs the fast gates; e2e and integration run in the loop and CI.
+STOP_GATES=(lint typecheck test)
+
+GATE_EXTRA=(
+  "e2e:NODE_OPTIONS=--experimental-vm-modules $bin/jest --silent --config ./test/jest-e2e.json --runInBand"
+  # Integration tests start PostgreSQL with Testcontainers: needs Docker or Podman.
+  "integration:NODE_OPTIONS=--experimental-vm-modules $bin/jest --silent --config ./test/jest-integration.json --runInBand"
+  # Database smoke (ADR 0016): migrations and seed on an empty PostgreSQL, through
+  # the app's Prisma setup. Throwaway container locally (HARNESS_SKIP_GATES=db
+  # without one); the postgres service of gates.yml in CI.
+  "db:.harness/db-smoke.sh '$bin/prisma migrate deploy' '$bin/prisma db seed'"
+)

package/templates/stacks/nestjs/gates.yml

@@ -0,0 +1,71 @@
+name: gates
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+jobs:
+  gates:
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    # PostgreSQL for the db gate (.harness/db-smoke.sh, ADR 0016): migrations and
+    # seed run here, inside the required gates job.
+    services:
+      postgres:
+        image: postgres:16-alpine
+        env:
+          POSTGRES_USER: smoke
+          POSTGRES_PASSWORD: smoke
+          POSTGRES_DB: smoke
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd "pg_isready -U smoke -d smoke"
+          --health-interval 5s
+          --health-timeout 5s
+          --health-retries 20
+    env:
+      HARNESS_DB_SMOKE_URL: postgresql://smoke:smoke@localhost:5432/smoke
+    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: 22
+          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
+
+      # The integration gate starts PostgreSQL with Testcontainers, using the
+      # runner's Docker daemon.
+      - name: Run DoD gates
+        if: steps.scope.outputs.spec_only != 'true'
+        run: .harness/gates.sh

package/templates/stacks/nextjs/claude-imports.md

@@ -0,0 +1,4 @@
+Next.js rules maintained by `next dev` in `AGENTS.md` (ADR 0018); read them
+before writing Next.js code:
+
+@AGENTS.md

package/templates/stacks/nextjs/gates.conf

@@ -0,0 +1,33 @@
+# Gate commands for a Next.js product created from data-matters-io/nextjs-new-app.
+# Sourced by .harness/gates.sh. Validated against nextjs-new-app@61c7a10.
+
+# Gates call node_modules/.bin directly instead of `pnpm exec`: pnpm 11 runs a
+# dependency check before `exec` that may trigger `pnpm install`, and a gate must
+# never install or mutate anything. Dependencies are installed beforehand
+# (`make install` locally, `pnpm install --frozen-lockfile` in CI).
+bin="node_modules/.bin"
+
+# `prisma generate` resolves DATABASE_URL from the config even though it never
+# connects; a placeholder keeps gates working in clean environments (CI, VPS, loop).
+export DATABASE_URL="${DATABASE_URL:-postgresql://gate:gate@localhost:5432/gate}"
+GATE_SETUP="$bin/prisma generate"
+
+# Coverage floor: set just below the template's measured coverage. Raise it
+# as coverage grows; never lower it (standards/testing.md).
+GATE_TEST="$bin/jest --silent --coverageThreshold='{\"global\":{\"lines\":85,\"statements\":85,\"branches\":85,\"functions\":85}}'"
+# Read-only and zero warnings: warnings are style/quality rules from
+# @data-matters.io/eslint-config and still count as not done.
+GATE_LINT="$bin/eslint . --max-warnings 0"
+GATE_TYPECHECK="$bin/tsc --noEmit"
+GATE_BUILD="$bin/next build"
+
+# Stop hook runs the fast gates (~40s); build (~60s) runs in the loop and CI.
+STOP_GATES=(lint typecheck test)
+
+GATE_EXTRA=(
+  # Database smoke (ADR 0016): migrations and seed on an empty PostgreSQL, through
+  # the app's Prisma setup. Throwaway container locally (HARNESS_SKIP_GATES=db
+  # without one); the postgres service of gates.yml in CI.
+  "db:.harness/db-smoke.sh '$bin/prisma migrate deploy' '$bin/prisma db seed'"
+  # "security:pnpm audit --audit-level high"
+)

package/templates/stacks/nextjs/gates.yml

@@ -0,0 +1,68 @@
+name: gates
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+jobs:
+  gates:
+    runs-on: ubuntu-latest
+    # PostgreSQL for the db gate (.harness/db-smoke.sh, ADR 0016): migrations and
+    # seed run here, inside the required gates job.
+    services:
+      postgres:
+        image: postgres:16-alpine
+        env:
+          POSTGRES_USER: smoke
+          POSTGRES_PASSWORD: smoke
+          POSTGRES_DB: smoke
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd "pg_isready -U smoke -d smoke"
+          --health-interval 5s
+          --health-timeout 5s
+          --health-retries 20
+    env:
+      HARNESS_DB_SMOKE_URL: postgresql://smoke:smoke@localhost:5432/smoke
+    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