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

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` |

package/standards/stacks/nestjs/architecture.md

@@ -0,0 +1,75 @@
+# Architecture: NestJS
+
+Architecture for backend services, as established by the app template
+(`nestjs-new-app`). Deviations need an ADR in the product repo.
+
+## Layout
+
+```
+src/
+├── main.ts, app.module.ts      # composition root
+├── modules/<feature>/          # self-contained feature modules
+│   ├── domain/                 # entities, value objects, errors, ports — no framework imports
+│   ├── application/            # services orchestrating the domain (use cases)
+│   ├── adapters/
+│   │   ├── inbound/            # controllers
+│   │   └── outbound/           # Prisma repositories implementing domain ports
+│   ├── dto/                    # request/response shapes, validated with Zod
+│   ├── <feature>.module.ts
+│   └── README.md
+└── shared/                     # cross-cutting infrastructure (config, database,
+                                # problem-details, authn, authz, observability, …)
+db/                             # schema.prisma, migrations/ (local), seed.ts
+deploy/                         # k8s manifests, reviewed SQL for deployed databases
+test/                           # e2e specs
+```
+
+`me` is the reference for a feature module at its smallest; `health` shows the
+same shape with an extension seam (indicators) instead of a database.
+
+## Dependency rules
+
+| Rule                                                                                           | Enforced by                                                 |
+| ---------------------------------------------------------------------------------------------- | ----------------------------------------------------------- |
+| A feature module never imports another feature module; shared code lives in `@/shared/*`       | `@data-matters.io/nestjs-module-boundaries` (lint, error)   |
+| No parent-relative imports: use `@/` or a same-directory `./`                                  | `@data-matters.io/no-parent-relative-imports` (lint, error) |
+| No `process.env` outside the config layer (config loader and secrets bootstrap are exempt)     | `@data-matters.io/no-process-env` (lint, error)             |
+| `domain/` has no framework or Prisma imports                                                   | architecture test (`*.arch.spec.ts`)                        |
+| Controllers depend on application services, services on domain ports; adapters implement ports | PR review                                                   |
+
+## Request flow
+
+```
+controller (adapters/inbound)  → Zod-validated DTO, @RequireAccess
+  → application service         → domain logic, depends on ports only
+    → repository port (domain)  ← Prisma adapter (adapters/outbound)
+```
+
+- **Validation** at the boundary with the Zod validation pipe; DTO types come
+  from the schemas.
+- **Errors** are RFC 9457 problem details. Throw subclasses of the abstract
+  `AppProblemError`; the global `problem-details` filter renders them. Never
+  hand-build error bodies.
+- **Configuration** only through the typed `ConfigService`; new settings get a
+  Zod schema in their module's `schema/` and fail fast at startup.
+- **Persistence** follows `src/shared/database/README.md`: one pooled
+  `PrismaService`, repositories behind domain ports, explicit mappers,
+  interactive transactions for multi-write operations.
+- **Schema changes**: `db/schema.prisma` is the source of truth. Local
+  migrations via `make db-migrate`; deployed databases receive a reviewed SQL
+  diff (`make db-diff`) in `deploy/db/`, applied by the data pipeline. The app
+  never migrates on startup or deploy, so changes must be expand/contract
+  compatible.
+
+## Authentication and authorization
+
+Entra ID authentication is optional and switchable by configuration. Every
+route is authenticated unless marked `@Public()`; protected routes declare
+their access level with `@RequireAccess`, and tests cover both the allowed and
+the denied path.
+
+## Observability
+
+Log through the injected Pino logger (structured, with correlation IDs and
+redaction), never `console`. Outbound HTTP calls use the shared headers module
+so correlation and trace context propagate.

package/standards/stacks/nestjs/conventions.md

@@ -0,0 +1,33 @@
+# Conventions: NestJS
+
+Extends the shared `conventions.md`.
+
+## Code
+
+- Aliases: `@/…` (maps to `src/`) and `@root/…` (repo root). No `../`.
+- Classes use NestJS decorators; dependency injection through constructors.
+  Ports are injected by token, not by concrete class.
+- Each feature module and each shared module has a `README.md` describing its
+  purpose, configuration and extension points.
+
+## Naming
+
+| Kind                          | Convention                                                                | Example                         |
+| ----------------------------- | ------------------------------------------------------------------------- | ------------------------------- |
+| Feature module folder         | kebab-case under `src/modules/`                                           | `src/modules/me/`               |
+| Module / controller / service | `<name>.module.ts`, `<name>.controller.ts`, `<name>.service.ts`           | `health.controller.ts`          |
+| DTO                           | `dto/<name>.dto.ts`                                                       | `dto/me-response.dto.ts`        |
+| Port                          | `domain/ports/<name>.port.ts` (use-case ports end in `.use-case.port.ts`) | `check-health.use-case.port.ts` |
+| Config schema                 | `schema/<name>.schema.ts`                                                 | `schema/database.schema.ts`     |
+| Unit test                     | `<file>.spec.ts` beside the code or in `__tests__/`                       | `health.service.spec.ts`        |
+| Property-based test           | `<topic>.pbt.spec.ts`                                                     | `headers.pbt.spec.ts`           |
+| Architecture test             | `<topic>.arch.spec.ts`                                                    | `domain-purity.arch.spec.ts`    |
+| Integration test              | `<topic>.integration.test.ts`                                             | `prisma.integration.test.ts`    |
+| E2E test                      | `test/<topic>.e2e-spec.ts`                                                | `test/auth.e2e-spec.ts`         |
+| Prisma models                 | PascalCase models, camelCase fields, UPPER_CASE enum values               | —                               |
+| Env vars                      | `UPPER_SNAKE_CASE`, grouped by prefix (`DB_…`, `AUTH_…`, `DD_…`)          | `DB_POOL_MAX`                   |
+
+## Local workflow
+
+`make setup`, `make dev`, `make ci-check`; database targets `make db-migrate`,
+`make db-diff`, `make db-verify`.

package/standards/stacks/nestjs/stack.md

@@ -0,0 +1,34 @@
+# Stack: NestJS backend services
+
+Template: `data-matters-io/nestjs-new-app` (reviewed at `b916be8`, with
+`@data-matters.io/eslint-config` 4.0.0).
+
+| Area                | Choice                                                                                                                                                             | Version |
+| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------- |
+| Runtime             | Node.js                                                                                                                                                            | 22.x+   |
+| Framework           | NestJS on Express (`@nestjs/platform-express`)                                                                                                                     | 11.x    |
+| Architecture        | Hexagonal feature modules (see `architecture.md`)                                                                                                                  | —       |
+| Config              | Typed, Zod-validated `ConfigService`, loaded once at startup (fail-fast)                                                                                           | —       |
+| Secrets             | AWS Secrets Manager resolved into the config pipeline                                                                                                              | —       |
+| API docs            | OpenAPI via `@nestjs/swagger` (Zod-backed decorators)                                                                                                              | 11.x    |
+| Errors              | RFC 9457 problem details (`application/problem+json`) via a global filter                                                                                          | —       |
+| HTTP hardening      | Helmet, CORS, `@nestjs/throttler` rate limiting                                                                                                                    | —       |
+| Auth                | Microsoft Entra ID (JWT via `jose`, BFF cookie session via `@azure/msal-node`), optional                                                                           | —       |
+| Authorization       | `@RequireAccess` + `AccessLevelGuard`                                                                                                                              | —       |
+| Observability       | Pino structured logs, correlation IDs, Datadog transport, OpenTelemetry API                                                                                        | —       |
+| Database migrations | `prisma migrate dev` locally only; deployed schemas change through a reviewed SQL diff (`prisma migrate diff --script`) run by the data pipeline, never by the app | —       |
+| Testing             | Jest + `supertest` (e2e), `fast-check` (property-based), Testcontainers (integration)                                                                              | 30.x    |
+| Lint preset         | `nestjs` (typed linting, `@darraghor/nestjs-typed`, module-boundary rules)                                                                                         | 4.x     |
+| Packaging / deploy  | Docker image; Kubernetes manifests in `deploy/k8s`                                                                                                                 | —       |
+
+## Gates (`templates/stacks/nestjs/gates.conf`)
+
+| Gate                | Command                                                                                      |
+| ------------------- | -------------------------------------------------------------------------------------------- |
+| setup               | `prisma generate`                                                                            |
+| test                | `jest --coverage --coverageThreshold` (floor: 85% lines, statements, branches and functions) |
+| lint                | `eslint . --max-warnings 0`                                                                  |
+| typecheck           | `tsc --noEmit -p tsconfig.json` (includes tests; `tsconfig.build.json` does not)             |
+| build               | `nest build`                                                                                 |
+| e2e (extra)         | `jest --config ./test/jest-e2e.json`                                                         |
+| integration (extra) | `jest --config ./test/jest-integration.json` (needs Docker or Podman)                        |

package/standards/stacks/nestjs/testing.md

@@ -0,0 +1,31 @@
+# Testing: NestJS
+
+Extends the shared `testing.md`.
+
+Tooling: Jest 30 + `ts-jest` (`testEnvironment: node`), `@nestjs/testing`,
+`supertest` for HTTP, `fast-check` for property-based tests, Testcontainers
+(`@testcontainers/postgresql`) for integration.
+
+## Tiers
+
+| Tier                                               | Pattern                        | Config                       | Status                                                       |
+| -------------------------------------------------- | ------------------------------ | ---------------------------- | ------------------------------------------------------------ |
+| Unit (incl. property-based and architecture tests) | `src/**/*.spec.ts`             | `package.json#jest`          | in use; `test` gate                                          |
+| Integration                                        | `src/**/*.integration.test.ts` | `test/jest-integration.json` | in use; `integration` extra gate (Docker or Podman required) |
+| E2E                                                | `test/*.e2e-spec.ts`           | `test/jest-e2e.json`         | in use; `e2e` extra gate                                     |
+
+## Rules
+
+- Unit tests build the module under test with `Test.createTestingModule`,
+  replacing ports with fakes; no database, no network.
+- Invariants that hold for any input (header maps, redaction, pagination,
+  transaction atomicity) get a property-based test.
+- Repository adapters are covered by integration tests against a real
+  PostgreSQL started by Testcontainers, never by mocking Prisma.
+- E2E tests boot the application and assert on HTTP status, headers and
+  RFC 9457 bodies, including the unauthenticated and forbidden paths.
+
+## Coverage floor
+
+85% on lines, statements, branches and functions over every file in `src/`
+(template measured 92.0% / 92.7% / 90.8% / 93.5% on 2026-10-01).

package/standards/stacks/nextjs/architecture.md

@@ -0,0 +1,97 @@
+# Architecture: Next.js
+
+Architecture for Next.js products, as established by the app template
+(`nextjs-new-app`). Deviations need an ADR in the product repo.
+
+## Feature-Based Architecture (FBA)
+
+A feature is self-contained: deleting its folder must not break the project.
+
+```
+app/
+├── (features)/                 # route group; not part of the URL
+│   ├── (<feature>)/            # one route group per feature
+│   │   ├── <route>/page.tsx    # pages
+│   │   ├── api/<route>/route.ts        # route handlers (thin)
+│   │   ├── api/<route>/<entity>.controller.ts
+│   │   ├── components/         # feature components (+ __tests__/)
+│   │   ├── hooks/              # feature hooks (+ __tests__/)
+│   │   ├── contexts/           # feature React contexts
+│   │   ├── types/              # feature types
+│   │   └── test-fixtures.ts    # make<Entity>() factories for tests
+│   ├── layout.tsx
+│   └── page.tsx
+├── shared/                     # code used by 3+ features
+│   ├── components/{ui,layout,auth}/
+│   ├── config/                 # rbac.ts, route-permissions.ts, menuItems.json
+│   ├── core/                   # BaseController
+│   ├── hooks/ libs/ providers/ types/ utils/ messages/
+db/                             # schema.prisma, migrations/, seed.ts
+proxy.ts                        # Next.js middleware (route protection)
+```
+
+## Dependency rules
+
+| Rule                                                                                   | Enforced by                                                                               |
+| -------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
+| A feature never imports from another feature                                           | `@data-matters.io/fba-boundaries` (lint, error)                                           |
+| `shared/` never imports from `(features)/`                                             | `@data-matters.io/fba-boundaries` (lint, error)                                           |
+| Code moves to `shared/` only when a third feature needs it (rule of three)             | PR review                                                                                 |
+| Cross-folder imports use path aliases (`@/`, `@shared/*`, `@features/*`), not `../../` | `@data-matters.io/no-deep-relative-imports` (lint, warn → blocks with `--max-warnings 0`) |
+
+## Request flow (server)
+
+```
+proxy.ts (authn, route permissions)
+  → route.ts          thin: check permission, delegate, map result to NextResponse
+    → <Entity>Controller extends BaseController   validation (Zod) + data access
+      → Prisma
+```
+
+- **Route handlers** check permissions with `requirePermission(request, PERMISSIONS.X)`
+  first, then delegate to the controller. No business logic or Prisma calls in
+  `route.ts`.
+- **Controllers** extend `app/shared/core/base-controller.ts` for CRUD
+  (pagination, search via `buildSearchFilter`, Prisma error mapping) and
+  override only what differs.
+- **Validation** at the boundary with Zod schemas. Schema-first: prefer
+  deriving TypeScript types from schemas (`z.infer`) or Prisma over
+  hand-written duplicates.
+- **Response contract**: build responses with `app/shared/libs/http-responses.ts`,
+  never hand-built `NextResponse.json(...)`. Collections are JSON:API documents
+  (`{ data, meta, links }`, `buildPaginatedResponse`); errors are RFC 9457
+  problem details (`application/problem+json`, `problemResponse` and its
+  status shortcuts, `validationProblem` for Zod errors).
+- **Errors**: Prisma errors map to problem details (P2002 → 409, P2025 → 404,
+  P2003 → 400). Log details only in development; never leak internals in
+  production responses.
+- Route handler params are `Promise`s in Next.js 16: `await params`.
+
+## Authorization (RBAC)
+
+Three layers, all driven by `app/shared/config/rbac.ts` (`PERMISSIONS`) and
+`route-permissions.ts`:
+
+1. **Middleware** (`proxy.ts`): blocks unauthorized routes.
+2. **API**: `requirePermission` in every route handler that mutates or reads
+   protected data.
+3. **UI**: `RequireAuth` / `RequirePermission` / `RequireRole` components and
+   `useUserAccess`; menu entries declare `permissions`/`roles`.
+
+A new protected capability adds a permission constant, protects all three
+layers and has tests for the denied path.
+
+## Client
+
+- Data fetching in feature hooks (`useX`, `useCreateX`, …) returning
+  `{ data, isLoading, error, … }`; components stay presentational.
+- UI primitives come from `@/app/shared/components/ui` (shadcn/ui). Do not
+  add another component library.
+- Accessibility target: WCAG 2.1 AA (labels, keyboard navigation, focus,
+  contrast). jsx-a11y rules run in lint.
+
+## Configuration and secrets
+
+- Configuration from environment variables; `env-example` documents every
+  variable with **placeholder values only**.
+- `.env*` files are git-ignored and never read by agents.

package/standards/stacks/nextjs/conventions.md

@@ -0,0 +1,32 @@
+# Conventions: Next.js
+
+Extends the shared `conventions.md`.
+
+## Code
+
+- Components are arrow functions (`react/function-component-definition`).
+- Type-only imports inline: `import { type Foo } from '…'`.
+- Import order (auto-fixed by lint): builtin → external → internal (`@/…`) →
+  parent → sibling → index → type, alphabetical, blank line between groups,
+  React first.
+- Aliases: `@/*`, `@app/*`, `@shared/*`, `@features/*`.
+- User-facing strings go through `app/shared/messages/{en,es,pt}.json`.
+
+## Naming
+
+| Kind                | Convention                                                  | Example                            |
+| ------------------- | ----------------------------------------------------------- | ---------------------------------- |
+| Feature folder      | route group, kebab-case                                     | `app/(features)/(admin)/`          |
+| Feature component   | PascalCase `.tsx`                                           | `UserForm.tsx`                     |
+| shadcn/ui primitive | kebab-case `.tsx` (shadcn default)                          | `radio-group.tsx`                  |
+| Hook                | `useX.ts`, one hook per file                                | `useCreateUser.ts`                 |
+| Controller          | `<entity>.controller.ts` next to its route                  | `user.controller.ts`               |
+| Types               | `types/<entity>.ts`                                         | `types/user.ts`                    |
+| Tests               | `__tests__/<file>.test.ts(x)` beside the code               | `hooks/__tests__/useUsers.test.ts` |
+| Test factories      | `make<Entity>()` in `test-fixtures.ts`                      | `makeUser()`                       |
+| Prisma models       | PascalCase models, camelCase fields, UPPER_CASE enum values | `User.status: ACTIVE`              |
+| Env vars            | UPPER_SNAKE_CASE                                            | `NEXTAUTH_SECRET`                  |
+
+## Local workflow
+
+`make setup`, `make dev`, `make ci-check` (format → lint → typecheck → tests).

package/standards/stacks/nextjs/stack.md

@@ -0,0 +1,40 @@
+# Stack: Next.js web applications
+
+Template: `data-matters-io/nextjs-new-app` (reviewed at `164057b`, with
+`@data-matters.io/eslint-config` 4.0.0).
+
+| Area           | Choice                                                                                                        | Version |
+| -------------- | ------------------------------------------------------------------------------------------------------------- | ------- |
+| Runtime        | Node.js                                                                                                       | 24.x    |
+| Framework      | Next.js, App Router, Turbopack builds                                                                         | 16.x    |
+| UI             | React                                                                                                         | 19.x    |
+| Styling        | Tailwind CSS                                                                                                  | 4.x     |
+| Components     | shadcn/ui (Radix UI primitives), `lucide-react` icons, `class-variance-authority` + `tailwind-merge` (`cn()`) | —       |
+| Theming        | `next-themes` (dark mode)                                                                                     | —       |
+| Auth           | NextAuth.js (Google provider) + in-app RBAC                                                                   | 4.x     |
+| API responses  | JSON:API documents; errors as RFC 9457 problem details                                                        | —       |
+| Notifications  | `react-hot-toast`                                                                                             | —       |
+| Error tracking | GlitchTip via `@sentry/nextjs`                                                                                | —       |
+| i18n           | In-app messages (`app/shared/messages/{en,es,pt}.json`)                                                       | —       |
+| Testing        | Jest + React Testing Library (jsdom)                                                                          | 30.x    |
+| Lint preset    | `nextjs` (React, a11y, Core Web Vitals, FBA rules)                                                            | 4.x     |
+
+## Agent rules from Next.js (ADR 0018)
+
+`next dev` keeps a version-matched "agent rules" block in `AGENTS.md`, which is
+committed and owned by Next.js. The harness-rendered `CLAUDE.md` imports it
+(`@AGENTS.md`), and the block never goes into `CLAUDE.md`:
+`scripts/next-agent-rules.sh` (run by `init-project.sh` and `sync-project.sh`)
+moves it out of `CLAUDE.md` and creates `AGENTS.md` when it is missing. Commit
+`AGENTS.md` changes with the Next.js upgrade that causes them.
+
+## Gates (`templates/stacks/nextjs/gates.conf`)
+
+| Gate             | Command                                                                           |
+| ---------------- | --------------------------------------------------------------------------------- |
+| setup            | `prisma generate`                                                                 |
+| test             | `jest --coverageThreshold` (floor: 85% lines, statements, branches and functions) |
+| lint             | `eslint . --max-warnings 0`                                                       |
+| typecheck        | `tsc --noEmit`                                                                    |
+| build            | `next build`                                                                      |
+| integration, e2e | pending (see `testing.md`)                                                        |

package/standards/stacks/nextjs/testing.md

@@ -0,0 +1,33 @@
+# Testing: Next.js
+
+Extends the shared `testing.md`.
+
+Tooling: Jest 30 + React Testing Library (jsdom), `ts-jest`, setup in
+`jest.setup.tsx`, helpers in `app/shared/test-utils.tsx` and
+`app/shared/test-helpers.ts`. The template also has an e2e smoke test
+(`scripts/smoke-test.ts`, `pnpm test:smoke`) run by its own `ci.yaml` against
+a built app and PostgreSQL.
+
+## Tiers
+
+| Tier        | Pattern                                                                                                      | Status                                            |
+| ----------- | ------------------------------------------------------------------------------------------------------------ | ------------------------------------------------- |
+| Unit        | `__tests__/*.test.ts(x)` beside the code                                                                     | in use; `test` gate                               |
+| Integration | `*.integration.test.ts` (controllers + Prisma against PostgreSQL via Testcontainers, as in `nestjs-new-app`) | **pending**: to be implemented in a future change |
+| E2E         | `pnpm test:smoke`                                                                                            | template CI only; not yet a harness gate          |
+
+## Rules
+
+- Unit tests do not touch the network or the database: mock `fetch` and the
+  Prisma client. Controllers are tested through their public methods with a
+  real `Request`.
+- Components are tested through accessible queries (`getByRole`,
+  `getByLabelText`), not implementation details.
+- RBAC: every protected route/component tests both the allowed and the denied
+  path.
+
+## Coverage floor
+
+85% on lines, statements, branches and functions, over every file in `app/`
+plus `proxy.ts` (`collectCoverageFrom` in `jest.config.ts`; the `(examples)`
+showcase pages are excluded).

package/standards/testing.md

@@ -0,0 +1,58 @@
+# Testing
+
+Principles shared by every stack. Tooling, file patterns and tiers in use are
+in `stack/testing.md`.
+
+## Tiers
+
+| Tier        | Scope                                                          | Runs in                           |
+| ----------- | -------------------------------------------------------------- | --------------------------------- |
+| Unit        | One unit in isolation; no network, no database                 | `test` gate (Stop hook, loop, CI) |
+| Integration | Adapters against real dependencies (PostgreSQL in a container) | extra gate (loop, CI)             |
+| E2E         | Full flows through the public interface (HTTP API, UI)         | extra gate (loop, CI)             |
+
+A tier the stack does not use yet is listed as **pending** in
+`stack/testing.md`; the first change that needs it sets it up.
+
+## Rules
+
+- Each spec scenario (`#### Scenario:` in OpenSpec) has at least one test.
+  Put the scenario name in the test title.
+- Write the failing test first, then the code.
+- Never change what an existing test asserts to make it pass. A conflict
+  between a test and the code is reported to a human; a confirmed
+  out-of-scope bug is recorded with `it.failing` and an exact assertion.
+- Test data comes from factories, not ad-hoc literals repeated across tests.
+- Access control: every protected route tests both the allowed and the
+  denied path.
+- Deterministic: no real clock or randomness without injection. Flaky tests
+  are bugs and block the gate.
+
+## Coverage
+
+- **Measured over all source files**, not only the ones some test imports:
+  untested modules must count as uncovered (`collectCoverageFrom`). The only
+  exclusions allowed are tests and their helpers, generated code, declaration
+  files, `*.example.*` reference files and template showcase code; each one is
+  listed in the coverage configuration.
+- **Executable statements, not lines of text**: use the statement-based
+  (istanbul / `babel`) provider, so type-only files weigh nothing.
+- **Floor: 85% on lines, statements, branches and functions**, in every
+  stack, enforced by the `test` gate. A product may raise it, never lower it;
+  lowering it needs an ADR.
+
+## Existing projects
+
+An existing project below 85% enters the harness with a **coverage ratchet**
+(ADR 0009):
+
+1. Measure coverage honestly (all source files, statement-based) and set the
+   gate floor to that baseline. `.harness/autonomy` is `disabled`.
+2. Add **characterization tests** for the critical flows, run with
+   `run-tasks.sh --force` under supervision. They pin current behaviour, even
+   if wrong; suspicious behaviour gets a `// Characterization: looks like a
+bug — …` comment and is reported, never fixed in the same change.
+3. Set `.harness/autonomy` to `enabled`.
+4. After every merged change, raise the floor to the new measured coverage.
+   The floor never goes down; 85% on every metric is the target, after which
+   the shared floor applies.

package/templates/.claude/hooks/stop-gates.sh

@@ -0,0 +1,43 @@
+#!/usr/bin/env bash
+# Claude Code Stop hook: blocks the agent from finishing while DoD gates fail.
+#
+# - No uncommitted changes → nothing to verify, allow stop.
+# - Gates fail → exit 2; stderr is fed back to the agent so it keeps working.
+# - After HARNESS_STOP_MAX_BLOCKS consecutive blocks in one session, allow the
+#   stop so a human (or the task loop's retry logic) can take over.
+set -uo pipefail
+
+input="$(cat)"
+project_dir="${CLAUDE_PROJECT_DIR:-$(pwd)}"
+cd "$project_dir" || exit 0
+
+gates="$project_dir/.harness/gates.sh"
+[[ -x "$gates" ]] || exit 0
+[[ -n "$(git status --porcelain 2>/dev/null)" ]] || exit 0
+
+session_id="$(printf '%s' "$input" | sed -n 's/.*"session_id"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' | head -n1)"
+state_dir="$project_dir/.harness/state"
+mkdir -p "$state_dir"
+counter="$state_dir/stop-blocks-${session_id:-unknown}"
+max="${HARNESS_STOP_MAX_BLOCKS:-5}"
+
+if output="$("$gates" --stop 2>&1)"; then
+  rm -f "$counter"
+  exit 0
+fi
+
+n=$(( $(cat "$counter" 2>/dev/null || echo 0) + 1 ))
+if (( n > max )); then
+  rm -f "$counter"
+  echo "Stop hook: gates still failing after $max attempts; allowing stop for human review." >&2
+  exit 0
+fi
+echo "$n" > "$counter"
+
+{
+  echo "Definition of Done not met: gates failed (block $n/$max)."
+  echo "Fix the failures below, then finish. Do not weaken, skip or delete tests to pass."
+  echo
+  echo "$output"
+} >&2
+exit 2

package/templates/.claude/settings.json

@@ -0,0 +1,72 @@
+{
+  "$schema": "https://json.schemastore.org/claude-code-settings.json",
+  "permissions": {
+    "allow": [
+      "Bash(.harness/gates.sh:*)",
+      "Bash(.harness/status.sh:*)",
+      "Bash(.harness/loop.sh:*)",
+      "Bash(.harness/spec-pr.sh:*)",
+      "Bash(.harness/openspec.sh:*)",
+      "Bash(git status:*)",
+      "Bash(git diff:*)",
+      "Bash(git log:*)",
+      "Bash(git show:*)",
+      "Bash(openspec list:*)",
+      "Bash(openspec show:*)",
+      "Bash(openspec validate:*)",
+      "Bash(node_modules/.bin/openspec:*)",
+      "Bash(gh pr view:*)",
+      "Bash(gh pr list:*)",
+      "Bash(pnpm test:*)",
+      "Bash(pnpm exec jest:*)",
+      "Bash(pnpm exec eslint:*)",
+      "Bash(pnpm exec tsc:*)",
+      "Bash(node_modules/.bin/jest:*)",
+      "Bash(node_modules/.bin/eslint:*)",
+      "Bash(node_modules/.bin/tsc:*)"
+    ],
+    "deny": [
+      "Read(./.env)",
+      "Read(./.env.*)",
+      "Edit(./.harness/gates.sh)",
+      "Edit(./.harness/gates.conf)",
+      "Edit(./.claude/settings.json)",
+      "Edit(./.claude/hooks/**)",
+      "Bash(git push --force:*)",
+      "Bash(git push -f:*)",
+      "Edit(./.harness/loop.sh)",
+      "Edit(./.harness/notify.sh)",
+      "Edit(./.harness/run-tasks.sh)",
+      "Edit(./.harness/lib.sh)",
+      "Edit(./.harness/spec-pr.sh)",
+      "Edit(./.harness/openspec.sh)",
+      "Edit(./.harness/pr-scope.sh)",
+      "Edit(./.harness/deps.sh)",
+      "Edit(./.harness/db-smoke.sh)",
+      "Edit(./.harness/models.conf)",
+      "Edit(./.harness/models.local.conf)",
+      "Edit(./.harness/model-flags.sh)",
+      "Skill(opsx:apply)",
+      "Skill(skill:opsx:apply)",
+      "Skill(openspec-apply-change)",
+      "Skill(skill:openspec-apply-change)"
+    ]
+  },
+  "skillOverrides": {
+    "opsx:apply": "off",
+    "openspec-apply-change": "off"
+  },
+  "hooks": {
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/stop-gates.sh",
+            "timeout": 900
+          }
+        ]
+      }
+    ]
+  }
+}

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