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

package/README.md

@@ -1,3 +1,35 @@
-# Temporary Holding Version
+# @data-matters.io/agent-harness
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Spec-Driven Development with Claude Code, installed into a product repository:
+the Definition of Done as executable gates, a task loop that implements an
+approved OpenSpec change one task per session, and the standards the agent
+follows.
+
+## Install
+
+Pin the package exactly and let the project's install generate the harness:
+
+```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
+```
+
+```json
+{ "scripts": { "prepare": "harness install" } }
+```
+
+`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.
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `harness init` | First adoption: the project-owned and seeded files, `CLAUDE.md`, the `.gitignore` entries |
+| `harness install` | (Re)generates the git-ignored files; idempotent |
+| `harness check` | Fails when the generated files are stale or edited, or a required file is missing |
+| `harness update-files` | Three-way merge of the seeded files (`.claude/settings.json`, `openspec/config.yaml`) after a bump |
+| `harness pr-scope` | Classifies a pull request for CI (spec-only or not) without installing the project |
+
+Run `harness --help` for the options.

package/bin/harness

@@ -0,0 +1,338 @@
+#!/usr/bin/env bash
+# The harness CLI (ADR 0021): installs agent-harness into a product repository
+# from the @data-matters.io/agent-harness package pinned in its devDependencies.
+#
+# 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`.
+#                  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
+#                  "prepare": "harness install".
+#   check          fails when a generated file is missing or differs from this
+#                  package, a generated file is tracked by git, a .gitignore
+#                  entry or a required committed file is missing, or a seeded
+#                  file needs `update-files`. Reports, without failing, drift
+#                  of the project-owned gate files from the stack preset.
+#   update-files   three-way merge of the seeded, committed files
+#                  (.claude/settings.json, openspec/config.yaml) with this
+#                  package's templates; exits 2 on a conflict.
+#   pr-scope       runs this package's pr-scope.sh (CI scope job, no install).
+#   version        prints the package version.
+#
+# Environment:
+#   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}"; }
+die() { echo "harness: $*" >&2; exit 1; }
+
+pkg="$(cd "$(dirname "$(readlink -f "${BASH_SOURCE[0]}")")/.." && pwd)"
+templates="$pkg/templates"
+project="${HARNESS_PROJECT_DIR:-$PWD}"
+
+version() {
+  local v=""
+  [[ -f "$pkg/package.json" ]] \
+    && v="$(sed -nE 's/^[[:space:]]*"version"[[:space:]]*:[[:space:]]*"([^"]+)".*/\1/p' "$pkg/package.json" | head -n1)"
+  [[ -n "$v" ]] || v="$(git -C "$pkg" rev-parse --short HEAD 2>/dev/null || echo unknown)"
+  echo "$v"
+}
+
+# The .gitignore block for the generated files.
+ignore_entries=(
+  ".harness/*.sh"
+  ".harness/models.conf"
+  ".harness/standards/"
+  ".harness/CLAUDE.harness.md"
+  ".harness/.generated"
+  ".claude/hooks/stop-gates.sh"
+  ".harness/state/"
+  ".harness/logs/"
+)
+# Seeded files: committed, merged by update-files against the template they
+# were last merged from, kept in .harness/seeded/ (committed too).
+seeded=(.claude/settings.json openspec/config.yaml)
+seed_src() {
+  case "$1" in
+    .claude/settings.json) echo "$templates/.claude/settings.json" ;;
+    openspec/config.yaml) echo "$templates/openspec/config.yaml" ;;
+  esac
+}
+
+stack_of() { cat "$project/.harness/STACK" 2>/dev/null || true; }
+
+# render <dest>: every generated file, as this package produces it for the
+# project's stack. Prints their paths, relative to <dest>.
+render() {
+  local dest="$1" stack f
+  stack="$(stack_of)"
+  mkdir -p "$dest/.harness/standards" "$dest/.claude/hooks"
+  for f in "$templates"/.harness/*.sh; do
+    cp "$f" "$dest/.harness/$(basename "$f")"
+  done
+  cp "$templates/.harness/models.conf" "$dest/.harness/models.conf"
+  cp "$templates/.claude/hooks/stop-gates.sh" "$dest/.claude/hooks/stop-gates.sh"
+  chmod +x "$dest"/.harness/*.sh "$dest"/.claude/hooks/*.sh
+  local imports=()
+  for f in "$pkg"/standards/*.md; do
+    cp "$f" "$dest/.harness/standards/"
+    imports+=("@standards/$(basename "$f")")
+  done
+  if [[ -n "$stack" ]]; then
+    [[ -d "$pkg/standards/stacks/$stack" ]] || die "unknown stack '$stack' in .harness/STACK"
+    mkdir -p "$dest/.harness/standards/stack"
+    for f in "$pkg/standards/stacks/$stack"/*.md; do
+      [[ -e "$f" ]] || continue
+      cp "$f" "$dest/.harness/standards/stack/"
+      imports+=("@standards/stack/$(basename "$f")")
+    done
+  fi
+  render_claude "$stack" "${imports[@]}" >"$dest/.harness/CLAUDE.harness.md"
+  (cd "$dest" && find . -type f | sed 's|^\./||' | sort)
+}
+
+# render_claude <stack> <import...>: the harness part of CLAUDE.md, i.e.
+# CLAUDE.md.tmpl from its first section to the "## Project" one. Imports are
+# relative to .harness/, where the file lives.
+render_claude() {
+  local stack="$1" line on=0; shift
+  echo "<!-- Generated by \`harness install\` from @data-matters.io/agent-harness"
+  echo "     $(version). Do not edit: the next install overwrites it. -->"
+  echo
+  while IFS= read -r line; do
+    [[ "$line" == "## Project" ]] && break
+    [[ "$line" == "## "* ]] && on=1
+    (( on )) || continue
+    if [[ "$line" == "{{STANDARDS_IMPORTS}}" ]]; then
+      printf '%s\n' "$@"
+      if [[ -n "$stack" && -f "$templates/stacks/$stack/claude-imports.md" ]]; then
+        echo
+        sed -E 's|^@\.harness/|@|; t; s|^@|@../|' "$templates/stacks/$stack/claude-imports.md"
+      fi
+      continue
+    fi
+    printf '%s\n' "$line"
+  done <"$templates/CLAUDE.md.tmpl" | sed -e :a -e '/^\n*$/{$d;N;ba' -e '}'
+}
+
+initialized() { [[ -f "$project/.harness/autonomy" ]]; }
+
+cmd_install() {
+  if ! initialized; then
+    echo "harness: $project is not initialized (no .harness/autonomy); run \`harness init\`"
+    return 0
+  fi
+  local tmp p
+  tmp="$(mktemp -d)"
+  render "$tmp/out" >"$tmp/list"
+  # Generated files this version no longer ships.
+  if [[ -f "$project/.harness/.generated" ]]; then
+    while IFS= read -r p; do
+      if [[ -n "$p" ]] && ! grep -qxF "$p" "$tmp/list"; then rm -f "$project/$p"; fi
+    done <"$project/.harness/.generated"
+  fi
+  (cd "$tmp/out" && cp -R --preserve=mode . "$project/")
+  cp "$tmp/list" "$project/.harness/.generated"
+  rm -rf "$tmp"
+  echo "harness: agent-harness $(version) installed in $project"
+}
+
+cmd_check() {
+  local tmp p problems=() notes=() stack src tracked
+  for p in .harness/STACK .harness/autonomy .harness/gates.conf .github/workflows/gates.yml CLAUDE.md "${seeded[@]}"; do
+    [[ -f "$project/$p" ]] || problems+=("$p: missing (committed file; \`harness init\` writes it)")
+  done
+  [[ -f "$project/.harness/VERSION" ]] \
+    && problems+=(".harness/VERSION: left from sync-project.sh; remove it (the version is the devDependency)")
+  if [[ -f "$project/CLAUDE.md" ]] && ! grep -qxF '@.harness/CLAUDE.harness.md' "$project/CLAUDE.md"; then
+    problems+=("CLAUDE.md: does not import the harness part (add the line @.harness/CLAUDE.harness.md)")
+  fi
+  for p in "${ignore_entries[@]}"; do
+    grep -qxF "$p" "$project/.gitignore" 2>/dev/null || problems+=(".gitignore: missing entry $p")
+  done
+  tmp="$(mktemp -d)"
+  render "$tmp/out" >"$tmp/list"
+  if git -C "$project" rev-parse --git-dir >/dev/null 2>&1; then
+    tracked="$(cd "$project" && xargs -r git ls-files -- <"$tmp/list")"
+    [[ -z "$tracked" ]] || while IFS= read -r p; do
+      problems+=("$p: generated but tracked by git (git rm --cached $p)")
+    done <<<"$tracked"
+  fi
+  while IFS= read -r p; do
+    if [[ ! -f "$project/$p" ]]; then problems+=("$p: not installed (run harness install)")
+    elif ! cmp -s "$project/$p" "$tmp/out/$p"; then problems+=("$p: differs from agent-harness $(version) (run harness install; never edit it)")
+    fi
+  done <"$tmp/list"
+  for p in "${seeded[@]}"; do
+    src="$(seed_src "$p")"
+    if [[ ! -f "$project/.harness/seeded/$p" ]]; then problems+=(".harness/seeded/$p: missing merge base (run harness update-files)")
+    elif ! cmp -s "$project/.harness/seeded/$p" "$src"; then problems+=("$p: the template changed (run harness update-files and commit the result)")
+    fi
+  done
+  stack="$(stack_of)"
+  if [[ -n "$stack" && -d "$templates/stacks/$stack" ]]; then
+    for p in .harness/gates.conf:gates.conf .github/workflows/gates.yml:gates.yml; do
+      if [[ -f "$project/${p%%:*}" ]] && ! cmp -s "$project/${p%%:*}" "$templates/stacks/$stack/${p#*:}"; then
+        notes+=("${p%%:*}: differs from the $stack preset (project-owned; review templates/stacks/$stack/${p#*:})")
+      fi
+    done
+  fi
+  rm -rf "$tmp"
+  (( ${#notes[@]} == 0 )) || printf 'harness: note: %s\n' "${notes[@]}"
+  if (( ${#problems[@]} > 0 )); then
+    printf 'harness: %s\n' "${problems[@]}" >&2
+    echo "harness: check failed (${#problems[@]} problem(s)) against agent-harness $(version)" >&2
+    return 1
+  fi
+  echo "harness: check passed (agent-harness $(version))"
+}
+
+cmd_update_files() {
+  local p src base local_file conflicts=0
+  for p in "${seeded[@]}"; do
+    src="$(seed_src "$p")"
+    base="$project/.harness/seeded/$p"
+    local_file="$project/$p"
+    mkdir -p "$(dirname "$base")" "$(dirname "$local_file")"
+    if [[ ! -f "$local_file" ]]; then
+      cp "$src" "$local_file"; echo "  $p: added"
+    elif cmp -s "$local_file" "$src"; then
+      :
+    elif [[ ! -f "$base" ]]; then
+      cp "$src" "$local_file.harness-new"
+      echo "  $p: CONFLICT (customized, no merge base; new version in $p.harness-new)"
+      conflicts=$((conflicts + 1))
+      continue
+    elif cmp -s "$base" "$src"; then
+      continue
+    elif cmp -s "$local_file" "$base"; then
+      cp "$src" "$local_file"; echo "  $p: updated"
+    elif git merge-file -L local -L base -L "agent-harness $(version)" "$local_file" "$base" "$src"; then
+      echo "  $p: merged (local changes kept)"
+    else
+      echo "  $p: CONFLICT (markers in the file)"
+      conflicts=$((conflicts + 1))
+    fi
+    cp "$src" "$base"
+  done
+  if (( conflicts > 0 )); then
+    echo "harness: $conflicts conflict(s) to resolve before committing" >&2
+    return 2
+  fi
+}
+
+cmd_init() {
+  local mode="" name="" stack="" conflicts=() gates_conf_src ci_src p
+  while [[ $# -gt 0 ]]; do
+    case "$1" in
+      --new|--existing|--template) mode="${1#--}"; shift ;;
+      --name) name="$2"; shift 2 ;;
+      --stack) stack="$2"; shift 2 ;;
+      *) die "init: unexpected argument: $1" ;;
+    esac
+  done
+  [[ -n "$mode" ]] || usage 1
+  [[ ! -f "$project/.harness/VERSION" ]] \
+    || die "init: $project has a harness installed by sync-project.sh (.harness/VERSION); migrate it instead"
+  gates_conf_src="$templates/.harness/gates.conf.example"
+  ci_src="$templates/.github/workflows/gates.yml"
+  if [[ -n "$stack" ]]; then
+    [[ -d "$templates/stacks/$stack" ]] || die "init: unknown stack '$stack' (available: $(ls "$templates/stacks" | tr '\n' ' '))"
+    gates_conf_src="$templates/stacks/$stack/gates.conf"
+    ci_src="$templates/stacks/$stack/gates.yml"
+  fi
+  name="${name:-$(basename "$project")}"
+  [[ "$mode" == template ]] && name="__REPO_NAME__"
+
+  # seed <src> <dest>: writes a committed file unless it exists.
+  seed() {
+    if [[ -e "$project/$2" ]]; then conflicts+=("$2"); return; fi
+    mkdir -p "$(dirname "$project/$2")"
+    cp "$1" "$project/$2"
+  }
+  seed "$gates_conf_src" .harness/gates.conf
+  seed "$ci_src" .github/workflows/gates.yml
+  for p in "${seeded[@]}"; do
+    seed "$(seed_src "$p")" "$p"
+    mkdir -p "$(dirname "$project/.harness/seeded/$p")"
+    cp "$(seed_src "$p")" "$project/.harness/seeded/$p"
+  done
+  mkdir -p "$project/.harness"
+  echo "$stack" >"$project/.harness/STACK"
+  if [[ ! -e "$project/.harness/autonomy" ]]; then
+    if [[ "$mode" == existing ]]; then echo disabled; else echo enabled; fi >"$project/.harness/autonomy"
+  fi
+  if [[ -e "$project/CLAUDE.md" ]]; then
+    grep -qxF '@.harness/CLAUDE.harness.md' "$project/CLAUDE.md" \
+      || conflicts+=("CLAUDE.md (add the line @.harness/CLAUDE.harness.md above the project section)")
+  else
+    cat >"$project/CLAUDE.md" <<EOF
+# CLAUDE.md — \`$name\`
+
+<!-- The harness part (workflow, Definition of Done, standards) is generated
+     by \`harness install\` from @data-matters.io/agent-harness into
+     .harness/CLAUDE.harness.md; never copy it here. Project-specific context
+     goes in the "Project" section. -->
+
+@.harness/CLAUDE.harness.md
+
+## Project
+
+<!-- Architecture overview, key commands, domain vocabulary, gotchas. -->
+EOF
+  fi
+  touch "$project/.gitignore"
+  if ! grep -qxF "${ignore_entries[0]}" "$project/.gitignore"; then
+    [[ ! -s "$project/.gitignore" ]] || echo >>"$project/.gitignore"
+    echo "# agent-harness: generated by \`harness install\` (ADR 0021)" >>"$project/.gitignore"
+  fi
+  for p in "${ignore_entries[@]}"; do
+    grep -qxF "$p" "$project/.gitignore" || echo "$p" >>"$project/.gitignore"
+  done
+  # 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")"
+  fi
+  cmd_install
+
+  echo "harness: initialized $project ($mode project${stack:+, stack: $stack})"
+  if (( ${#conflicts[@]} > 0 )); then
+    echo
+    echo "Existing files left untouched (merge manually):"
+    printf '  - %s\n' "${conflicts[@]}"
+  fi
+  # shellcheck source=scripts/toolchain.sh
+  . "$pkg/scripts/toolchain.sh"
+  cat <<EOF
+
+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).
+  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.
+EOF
+  if [[ "$mode" == existing ]]; then
+    echo "  5. Add characterization tests for the critical flows, then: echo enabled > .harness/autonomy"
+  fi
+}
+
+[[ $# -gt 0 ]] || usage 1
+command="$1"; shift
+case "$command" in
+  -h|--help|help) usage 0 ;;
+  version|--version) version ;;
+  init) cmd_init "$@" ;;
+  install) [[ $# -eq 0 ]] || usage 1; cmd_install ;;
+  check) [[ $# -eq 0 ]] || usage 1; cmd_check ;;
+  update-files) [[ $# -eq 0 ]] || usage 1; cmd_update_files ;;
+  pr-scope) cd "$project" && exec bash "$templates/.harness/pr-scope.sh" "$@" ;;
+  *) echo "harness: unknown command '$command'" >&2; usage 1 ;;
+esac

package/package.json

@@ -1,6 +1,31 @@
 {
   "name": "@data-matters.io/agent-harness",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "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"
+  },
+  "bin": {
+    "harness": "bin/harness"
+  },
+  "files": [
+    "bin/harness",
+    "templates/CLAUDE.md.tmpl",
+    "templates/.claude/",
+    "templates/.github/",
+    "templates/.harness/",
+    "templates/openspec/",
+    "templates/stacks/",
+    "standards/",
+    "scripts/next-agent-rules.sh",
+    "scripts/toolchain.sh"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "devDependencies": {
+    "@changesets/cli": "3.0.3"
+  }
 }

package/scripts/next-agent-rules.sh

@@ -0,0 +1,67 @@
+#!/usr/bin/env bash
+# Keeps the Next.js agent-rules block in AGENTS.md, out of CLAUDE.md (ADR 0018).
+#
+# Usage: scripts/next-agent-rules.sh <project-dir>
+#
+# `next dev` (Next.js 16+) writes a managed block between
+# <!-- BEGIN:nextjs-agent-rules --> and <!-- END:nextjs-agent-rules --> when an
+# AI agent runs it: into AGENTS.md when that file exists, otherwise at the end of
+# CLAUDE.md, which the harness renders. This script:
+#   - moves a block found in CLAUDE.md into AGENTS.md (created if missing);
+#   - creates AGENTS.md when there is none, with the block generated by the
+#     project's own Next.js (node_modules/next) or, without it, empty markers
+#     that `next dev` fills in;
+#   - never changes an AGENTS.md that already holds the block.
+# Prints what it did ("moved", "created", "unchanged"); CLAUDE.md imports
+# AGENTS.md through the harness-rendered nextjs section.
+set -euo pipefail
+
+usage() { sed -n '2,16p' "$0" | sed 's/^# \{0,1\}//'; exit "${1:-0}"; }
+[[ $# -eq 1 && "$1" != -h && "$1" != --help ]] || usage 1
+dir="$1"
+start='<!-- BEGIN:nextjs-agent-rules -->'
+end='<!-- END:nextjs-agent-rules -->'
+agents="$dir/AGENTS.md"
+claude="$dir/CLAUDE.md"
+
+has_block() { [[ -f "$1" ]] && grep -qF "$start" "$1" && grep -qF "$end" "$1"; }
+
+if has_block "$claude"; then
+  block="$(awk -v s="$start" -v e="$end" 'index($0, s) { on = 1 } on { print } index($0, e) { on = 0 }' "$claude")"
+  # Drop the block and the blank lines `next dev` put before it.
+  awk -v s="$start" -v e="$end" '
+    index($0, s) { skip = 1 }
+    !skip { lines[++n] = $0 }
+    skip && index($0, e) { skip = 0 }
+    END { while (n > 0 && lines[n] == "") n--; for (i = 1; i <= n; i++) print lines[i] }' "$claude" >"$claude.tmp"
+  mv "$claude.tmp" "$claude"
+  if has_block "$agents"; then
+    echo "moved (AGENTS.md already had the block; removed it from CLAUDE.md)"
+  else
+    if [[ -s "$agents" ]]; then printf '\n%s\n' "$block" >>"$agents"; else printf '%s\n' "$block" >"$agents"; fi
+    echo "moved"
+  fi
+  exit 0
+fi
+
+if [[ -f "$agents" ]]; then
+  echo "unchanged"
+  exit 0
+fi
+
+# Ask the project's Next.js for the block of its own version.
+block=""
+if [[ -f "$dir/node_modules/next/dist/server/lib/generate-agent-files.js" ]] && command -v node >/dev/null; then
+  tmp="$(mktemp -d)"
+  : >"$tmp/AGENTS.md"
+  if node -e 'require(process.argv[1]).writeAgentFiles(process.argv[2])' \
+      "$dir/node_modules/next/dist/server/lib/generate-agent-files.js" "$tmp" >/dev/null 2>&1 \
+    && has_block "$tmp/AGENTS.md"; then
+    block="$(sed -e '/./,$!d' "$tmp/AGENTS.md")"
+  fi
+  rm -rf "$tmp"
+fi
+[[ -n "$block" ]] || block="$start
+$end"
+printf '%s\n' "$block" >"$agents"
+echo "created"

package/scripts/toolchain.sh

@@ -0,0 +1,14 @@
+# Package-manager versions for every harnessed project and machine (ADR 0014).
+# Sourced by vps-doctor.sh, sync-project.sh and the tests; change them here only,
+# after checking the registry (`npm view pnpm dist-tags.latest`) and the
+# pnpm/action-setup release that supports the pnpm major.
+# shellcheck shell=bash disable=SC2034
+
+# Projects: package.json "packageManager" and "devEngines.packageManager", exact.
+HARNESS_PNPM_VERSION="12.11.2"
+# CI: reads the version from packageManager. pnpm 12 needs v6.1.0 or newer;
+# the floating @v6 tag still points to v6.0.10.
+HARNESS_PNPM_ACTION="pnpm/action-setup@v6.1.0"
+# Machines (VPS): npm installed at the user level (npm config get prefix).
+# Projects never run npm: devEngines.packageManager makes it refuse.
+HARNESS_NPM_VERSION="12.2.0"

package/standards/conventions.md

@@ -0,0 +1,68 @@
+# Conventions
+
+Conventions shared by every stack. Stack-specific naming and layout live in
+`stack/conventions.md` (in a product repo, `.harness/standards/stack/`).
+
+## Language
+
+- **All artifacts are in English**: code, identifiers, comments, docs, specs,
+  ADRs, commit messages, branch names, PR titles/descriptions, logs, file names.
+- User-facing strings go through the stack's i18n mechanism, not hardcoded.
+- **Chat is the only exception**: agents reply in the user's language.
+
+## Formatting and lint
+
+Owned entirely by `@data-matters.io/eslint-config`, which also ships `eslint`
+and `prettier` with pinned versions. Do not declare them as direct
+dependencies and do not add local rules that contradict the preset; propose
+changes upstream instead.
+
+- pnpm >= 10 no longer hoists their binaries by default: expose them with
+  `publicHoistPattern` in `pnpm-workspace.yaml`.
+- Prettier (runs inside ESLint for JS/TS; the `prettier` CLI formats JSON,
+  Markdown, YAML and CSS): single quotes, semicolons, trailing commas,
+  2-space indent, 120-column print width, LF.
+- Severity convention: `error` = correctness/security, `warn` =
+  style/quality. **The lint gate runs with `--max-warnings 0`**, so warnings
+  still block "done".
+- Scripts: `lint` is read-only (CI), `lint:fix` fixes; `format` checks,
+  `format:fix` writes.
+- Architecture rules are lint rules from the preset (see
+  `stack/architecture.md`); they fail the build instead of relying on review.
+- Pre-commit hook: `data-matters-eslint-init` as `postinstall`. No husky.
+- `.editorconfig` comes from the eslint-config package.
+
+## TypeScript
+
+- `strict` mode; no `any` (use `unknown` and narrow). Test files are exempt.
+- Unused parameters/variables must be prefixed with `_`.
+- No non-null assertions (`!`) outside tests.
+- Cross-folder imports use path aliases (`@/…`), never `../../`.
+- Validation at boundaries with Zod; types derive from schemas (`z.infer`) or
+  from Prisma rather than being duplicated by hand.
+
+## Commits and branches
+
+- [Conventional Commits](https://www.conventionalcommits.org/):
+  `<type>(<scope>): <summary>`, imperative, ≤ 72 chars. Breaking changes use
+  `!` and a `BREAKING CHANGE:` body.
+- Types: `feat`, `fix`, `refactor`, `test`, `docs`, `chore`, `ci`, `perf`.
+- One task, one commit. In the task loop the runner commits; agents never
+  commit or push.
+- `main` is protected; everything lands via PR, and CI must pass.
+- Spec branches: `spec/<openspec-change-id>`, only
+  `openspec/changes/<change-id>/`, PR titled `spec: <change-id>`, opened by
+  `.harness/spec-pr.sh` (it and CI's `pr-scope.sh` refuse anything else).
+  Change branches: `change/<openspec-change-id>`, created from `main` after
+  the spec PR is merged. Other work: `<type>/<short-kebab-description>`.
+
+## Comments
+
+- Explain _why_, not _what_. Public functions and classes get a short JSDoc.
+- Delete commented-out code. `TODO` references a change id: `TODO(change-id): …`.
+
+## Local workflow
+
+`make` is the entry point (`make help`): `make setup` on first run, then the
+stack's dev target, and `make ci-check` for CI parity. Agents use
+`.harness/gates.sh` as the source of truth for "done".

package/standards/dod.md

@@ -0,0 +1,53 @@
+# Definition of Done
+
+A task is done when **every gate passes**. The agent's own assessment is never
+a completion criterion.
+
+## Human DoD → executable gate
+
+| Human criterion                                                 | Gate                  | Required  |
+| --------------------------------------------------------------- | --------------------- | --------- |
+| Behaviour matches the spec scenarios; coverage floor holds      | `test`                | yes       |
+| Code follows conventions and architecture rules (zero warnings) | `lint`                | yes       |
+| No type errors                                                  | `typecheck`           | yes       |
+| The artifact builds                                             | `build`               | yes       |
+| Adapters work against real dependencies                         | `integration` (extra) | per stack |
+| Migrations apply and the seed runs on an empty database         | `db` (extra)          | Prisma    |
+| Flows work end to end                                           | `e2e` (extra)         | per stack |
+| No known vulnerable dependencies                                | `security` (extra)    | optional  |
+
+The commands behind each gate are in the stack preset (`.harness/gates.conf`,
+source `templates/stacks/<stack>/gates.conf`) and summarized in
+`stack/stack.md`. `.harness/gates.sh` runs them:
+
+| Where                   | Gates                                              |
+| ----------------------- | -------------------------------------------------- |
+| Claude Code `Stop` hook | `STOP_GATES` (fast profile: lint, typecheck, test) |
+| Task loop               | all                                                |
+| CI (`gates.yml`)        | all                                                |
+
+## Rules
+
+- A required gate that is not configured **fails**. To skip one, set it
+  explicitly to `skip:<reason>`; the reason shows up in every gate run.
+- A task is not done if it passes because tests were deleted, weakened or
+  skipped, or because lint rules were disabled inline (`eslint-disable`)
+  without a justification comment.
+- A task is not done if it changes the intent of an existing test (what it
+  asserts) without that change being part of the approved spec.
+- Each task that changes behaviour adds or updates at least one test that
+  would fail without the change.
+- Every spec scenario maps to at least one test by the time the change is
+  archived.
+- All artifacts are in English (see `conventions.md`). Not machine-checked
+  yet; enforced during PR review.
+
+## Human checkpoints
+
+1. **Before execution**: proposal, delta specs and `tasks.md` are reviewed in
+   a spec-only PR (`spec: <change-id>`) and approved by merging it (ADR 0011).
+   `run-tasks.sh` refuses changes that are not on `main`, and CI validates
+   spec PRs with `openspec validate --strict` instead of the gates. Only the
+   task loop implements: `/opsx:apply` is disabled (ADR 0013).
+2. **Before merge**: the PR is reviewed. CI re-runs the gates independently,
+   and the `main` ruleset requires it to pass.

package/standards/stack.md

@@ -0,0 +1,42 @@
+# Stack
+
+Derived from the reference repositories (see ADR 0007). Every product starts
+from one of the app templates; both share the same harness, workflow and
+standards, and differ only in the framework.
+
+| Stack    | Template                         | Use for                                | Details                  |
+| -------- | -------------------------------- | -------------------------------------- | ------------------------ |
+| `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` |
+
+In a product repo, the chosen stack's files are in `.harness/standards/stack/`.
+
+## Shared by every stack
+
+| Area            | Choice                                                                                |
+| --------------- | ------------------------------------------------------------------------------------- |
+| Language        | TypeScript, `strict: true`                                                            |
+| Package manager | pnpm 12.11.2, exact in `packageManager` + `devEngines` (ADR 0014); one lockfile       |
+| npm             | Never in a project (`devEngines` makes it refuse); 12.2.0 on machines, user-level     |
+| Validation      | Zod 4                                                                                 |
+| ORM / database  | Prisma 7 (`@prisma/adapter-pg`) / PostgreSQL 16+                                      |
+| Testing         | Jest 30 + `ts-jest`                                                                   |
+| Lint / format   | `@data-matters.io/eslint-config` 4.x (stack preset; brings `eslint` and `prettier`)   |
+| Git hooks       | `data-matters-eslint-init` (postinstall). No husky.                                   |
+| Local infra     | Podman (preferred) or Docker via Compose, driven by `make`                            |
+| Spec workflow   | OpenSpec (ADR 0002) + agent-harness                                                   |
+| OpenSpec CLI    | `@fission-ai/openspec` devDependency, exact pin (`.harness/openspec.sh`; ADR 0013)    |
+| CI              | GitHub Actions: the template's `ci.yaml` plus `gates.yml` running `.harness/gates.sh` |
+| CI on spec PRs  | Jobs gated on `.harness/pr-scope.sh`: spec-only PRs run `openspec validate` only      |
+| Hosting         | VPS, provisioned via `vps-bootstrap`                                                  |
+| Secrets         | Environment variables (or a secrets manager); never committed                         |
+
+## Stack presets
+
+`templates/stacks/<stack>/` holds the gate commands (`gates.conf`) and the CI
+workflow (`gates.yml`) validated against each template:
+
+| Stack    | Validated against            |
+| -------- | ---------------------------- |
+| `nextjs` | see `stacks/nextjs/stack.md` |
+| `nestjs` | see `stacks/nestjs/stack.md` |