@getarbiter/cli 0.5.0

package/dist/templates/agents-md/AGENTS.md.ejs

@@ -0,0 +1,517 @@
+# <%= projectName %> — AGENTS.md
+
+> **Canonical governance for AI coding agents.**
+> All tools read this file. Tool-specific extensions: `.claude/CLAUDE.md`, `.agents/CODEX.md`
+>
+> Standard: [AGENTS.md — AAIF / Linux Foundation](https://agents.md/)
+
+---
+
+## Project
+
+| Fact | Value |
+|------|-------|
+| **What** | <%= description %> |
+| **Stack** | <%= language %><% if (framework) { %> / <%= framework %><% } %> |
+| **Build** | `<%= buildCommand %>` |
+| **Test** | `<%= testCommand %>` |
+| **Gate** | `node scripts/check-all.mjs` (mandatory before commit) |
+
+---
+
+## Authority Hierarchy
+
+When documents conflict, higher level wins. No debate.
+
+```
+Level 1:  AGENTS.md — invariants + governance (this file)
+Level 2:  Architecture docs (docs/SYSTEM/ARCHITECTURE.md, PROJECT_STATUS.md)
+Level 2.5: DECISION_REGISTRY.md — blocked project decisions (D-NN, #2036)
+Level 3:  Source code + tests — implementation truth
+```
+
+Blocked decisions live in `DECISION_REGISTRY.md` (D-NN — one rule lives in ONE
+registry; a decision that matures into a permanent rule promotes to a PROJ-NN
+invariant). The decision-registry gate fails on orphan D-NN decisions.
+
+---
+
+## Iron Laws
+
+Behavioral protocol rules that sit above the invariant catalog — process discipline,
+not a checkable gate. Violation protocol: **STOP → REFUSE → cite the law**.
+
+### Worktree Isolation Is Mandatory For Parallel Agents
+
+Concurrent agents must each work in an isolated git worktree. Shared-tree parallel
+editing — two or more agents writing into the same working tree at once — is
+prohibited: git index state, lockfiles, and in-flight diffs corrupt under
+concurrent writers, with no clean recovery path. One agent, one worktree, one
+branch.
+
+### Complete Means Merged To Main
+
+No task, PR, or issue may be reported complete before its PR is merged green on
+`main`. Open is not done. A PR is owned until merged: follow it through CI and fix
+each red by root cause (read the failing job's log, fix the underlying cause,
+push, re-verify), repeated until every check passes and it merges. Handing back or
+abandoning a red PR, or reporting a task complete while its PR is still open, is a
+process violation.
+
+### Root-Cause-First After Any Failure
+
+On an error, stop the patch-spiral. Do not attempt a second fix before performing
+structural analysis: read the actual failure, trace it to its origin, and only
+then apply the fix that addresses the root cause. A patch applied without
+diagnosis is a guess, not a fix, and tends to compound rather than resolve.
+
+### Verification-Before-Victory
+
+Run targeted local verification — an end-to-end exercise of the changed behavior,
+not just a green typecheck or unit-test run — before every push. This is the
+dominant agent failure mode: of observed real agent errors, the majority (5 of 8)
+were claims of success without the change ever having been exercised. Review
+layers do not prevent this; only verification does.
+
+---
+
+## Invariants
+
+Violation protocol: **STOP → REFUSE → cite INV-XX**.
+
+<% for (const [tier, tierInvariants] of invariantsByTier.entries()) { -%>
+### <%- tierLabels[tier] %>
+
+<% for (const inv of tierInvariants) { -%>- **<%- inv.id %>:** <%- (inv.languageDetail && inv.languageDetail[language]) ? inv.languageDetail[language] : inv.title %>
+<% } -%>
+
+<% } -%>
+---
+
+## Coding Standards
+
+<% if (language === 'typescript') { %>### TypeScript
+
+- Strict mode always on (`"strict": true` in tsconfig)
+- No `any` — use `unknown` and narrow, or create proper types
+- Prefer `const` over `let`, never `var`
+- Async/await over callbacks or raw Promises
+- Named exports preferred over default exports
+- File naming: `kebab-case.ts`<% if (architectureStyle === 'hexagonal') { %>
+
+### Architecture Verification (M22a)
+
+Generated `eslint-plugin-boundaries` config enforces hexagonal layer isolation (hard gate, L2+).
+
+**Peer deps**: `npm i -D eslint@^9 eslint-plugin-boundaries @typescript-eslint/parser`
+
+**Setup**: in your root ESLint config, add:
+```js
+extends: ['./.eslintrc-boundaries.cjs']
+```
+
+**Rules enforced**:
+
+| Layer | Allowed dependencies | Notes |
+|-------|---------------------|-------|
+| `src/domain/**` | none | No framework imports; no Node built-ins; no browser globals |
+| `src/application/**` | `domain` | Ports defined here |
+| `src/adapters/**` | `application`, `domain` | Inbound + outbound adapters |
+| `src/infrastructure/**` | `application`, `domain` | Bootstrap + config |
+
+**Suppressions**: add exemptions to `suppressions/boundaries-baseline.json` with `scope` (file-pattern glob) + `expiresAt` (wave-migration date). Enforced by `check-suppressions.mjs` L1 gate.
+<% } %><% } %><% if (language === 'rust') { %>### Rust
+
+- All public items must have documentation comments
+- Error handling: use `?` operator and typed `Result<T, E>`
+- No `.unwrap()` or `.expect()` in library code; test code may use `.expect("...")`
+- Use `clippy::pedantic` lint level
+- Prefer `&str` over `String` in function parameters<% if (architectureStyle === 'hexagonal') { %>
+
+### Architecture Verification (M22b)
+
+Generated `cargo-deny` + `clippy.toml` + domain-purity grep enforce hexagonal layer isolation (hard gate, L2+).
+
+**Peer deps**: `cargo install cargo-deny`
+
+**Setup**: the generated `deny.toml` and `clippy.toml` are placed at the project root. No `Cargo.toml` changes needed.
+
+**Rules enforced**:
+
+| Layer | Mechanism | What it bans |
+|-------|-----------|-------------|
+| Project (all layers) | cargo-deny `[bans]` | Framework crates as direct dependencies (sqlx, axum, reqwest, …) |
+| Project (all layers) | `clippy.toml` `disallowed_types` | Framework types anywhere in code (sqlx::Pool, axum::Router, …) |
+| `src/domain/**` | grep scan in `check-boundaries.mjs` | `use sqlx`, `use axum`, `use diesel`, … — module-level enforcer |
+
+**Suppressions**: add exemptions to `suppressions/boundaries-baseline.json` with `scope` (file-pattern glob) + `expiresAt` (wave-migration date). Enforced by `check-suppressions.mjs` L1 gate.
+<% } %><% } %><% if (language === 'java') { %>### Java
+
+- Hexagonal architecture: domain → no framework imports
+- Use constructor injection exclusively (no field injection)
+- Records for immutable data transfer objects
+- No nullable fields without explicit `@Nullable` annotation
+- Method length ≤ 65 LOC, cyclomatic complexity ≤ 15
+- **Integration testing: RestAssured mandatory** — MockMvc is forbidden (INV-29)
+  - Use `@SpringBootTest(webEnvironment = RANDOM_PORT)` with RestAssured
+  - MockMvc bypasses real HTTP serialization, filters, and exception handlers
+  - `@AutoConfigureMockMvc` is prohibited; use a real embedded server<% if (architectureStyle === 'hexagonal' && basePackage) { %>
+
+### Architecture Verification (M22)
+
+Generated ArchUnit test suite enforces hexagonal boundaries (hard gate, L2+).
+
+**Setup**: add to `build.gradle`:
+```groovy
+apply from: 'gradle/arch-test-deps.gradle'
+```
+
+**Rules enforced** (`src/test/java/<%= basePackage.replace(/\./g, '/') %>/architecture/`):
+
+| Class | Rules |
+|-------|-------|
+| `DomainPurityTest` | No Spring/JPA/Hibernate imports in `domain.**` |
+| `DependencyFlowTest` | Adapters → ports only; application → domain only; domain has no outbound deps |
+| `PortsIndependenceTest` | `application.port.in/out` must not depend on adapters or infrastructure |
+| `TestCoverageArchTest` | `*ControllerIT` classes must reside in `adapter.in.web` |<% if (hasDatabase && hasPublicApi) { %>
+| `RestAssuredArchTest` | All `*ControllerIT` must extend `RestAssuredBaseIT` |<% } %>
+
+**Suppressions**: add exemptions to `suppressions/archunit-baseline.json` with `scope` (class-pattern glob) + `expiresAt` (wave-migration date).
+<% } %><% if (basePackage) { %>
+
+### Module Boundaries (Spring Modulith)
+
+If this is a Spring Boot project, the generated `ApplicationModulesTest` (`src/test/java/<%= basePackage.replace(/\./g, '/') %>/modulith/`) verifies module boundaries via `ApplicationModules.of(...).verify()` (#1886).
+
+**Setup** (Gradle): add to `build.gradle`:
+```groovy
+apply from: 'gradle/modulith-deps.gradle'
+```
+
+**Setup** (Maven): see `docs/modulith-maven-setup.md` for the `<dependency>` snippet.
+<% } %><% if (enableDebtGates && buildTool === 'gradle') { %>
+
+### Coverage Gate (JaCoCo)
+
+Generated `gradle/jacoco.gradle` wires `jacocoTestCoverageVerification` as a hard gate on `check` (#1887-F).
+
+**Setup**: add to `build.gradle`:
+```groovy
+apply from: 'gradle/jacoco.gradle'
+```
+<% } %><% if (contractType === 'rest-owned' && buildTool === 'gradle') { %>
+
+### Contract Testing (Pact provider verification)
+
+Generated `config/pact-deps.gradle` wires the Pact provider-verification dependencies + broker system properties (#1887-F).
+
+**Setup**: add to `build.gradle`:
+```groovy
+apply from: 'config/pact-deps.gradle'
+```
+<% } %><% if (contractType === 'rest-public' && buildTool === 'gradle') { %>
+
+### Contract Testing (OpenAPI exporter)
+
+Generated `config/export-openapi-java.gradle` wires the `org.springdoc.openapi-gradle-plugin` + `generateOpenApiDocs` task, producing `contracts/openapi-current.yaml` for the diff test (INV-43, #1887-F).
+
+**Setup**: add to `build.gradle`:
+```groovy
+plugins {
+    id 'org.springdoc.openapi-gradle-plugin' version '1.8.0'
+}
+```
+```groovy
+apply from: 'config/export-openapi-java.gradle'
+```
+<% } %><% if (hasDatabase && governanceLevel !== 'L1' && buildTool === 'gradle') { %>
+
+### Integration Testing (Testcontainers)
+
+Generated `config/testcontainers-deps.gradle` wires the Testcontainers + PostgreSQL test dependencies (M26, #1887-F).
+
+**Setup**: add to `build.gradle`:
+```groovy
+apply from: 'config/testcontainers-deps.gradle'
+```
+<% } %><% } %><% if (language === 'kotlin' && enableDebtGates && buildTool === 'gradle') { %>### Coverage Gate (Kover)
+
+Generated `kover.gradle` wires `koverVerify`/`koverXmlReport` as a hard gate (#1887-F).
+
+**Setup**: add to `build.gradle`:
+```groovy
+plugins {
+    id 'org.jetbrains.kotlinx.kover' version '0.9.8'
+}
+```
+```groovy
+apply from: 'kover.gradle'
+```
+<% } %><% if (language === 'go') { %>### Go
+
+- All exported functions must have documentation comments
+- Error handling: check every returned error — no `_ = err` patterns
+- Use `gofmt` for formatting (enforced by CI)
+- Use `golangci-lint` with project-level config
+- Prefer table-driven tests
+- File naming: `snake_case.go`<% if (architectureStyle === 'hexagonal') { %>
+
+### Architecture Verification (M22c)
+
+Generated depguard config + domain-purity grep enforce hexagonal layer isolation (hard gate, L2+).
+
+**Peer deps**: `golangci-lint >= 2.0`
+
+**Setup**: the generated `.golangci-boundaries.yml` is placed at the project root. No `go.mod` changes needed.
+
+**Rules enforced**:
+
+| Layer | Mechanism | What it bans |
+|-------|-----------|-------------|
+| Project (all layers) | depguard `main` rule in `.golangci-boundaries.yml` | Framework imports in business logic (gorm, gin, echo, fiber, …) |
+| `internal/domain/**` | depguard `domain-purity` rule | Framework imports in domain packages |
+| `internal/domain/**` | grep scan in `scripts/check-boundaries.mjs` | `"gorm.io/…"`, `"github.com/gin-gonic/…"`, … — toolchain-free enforcer |
+
+**Suppressions**: add exemptions to `suppressions/boundaries-baseline.json` with `scope` (file-pattern glob) + `expiresAt` (wave-migration date). Enforced by `check-suppressions.mjs` L1 gate.
+<% } %><% } %><% if (language === 'python') { %>### Python
+
+- Type annotations required on all public function signatures
+- Use `ruff` for linting and formatting
+- Use `pytest` for testing with fixtures over setUp/tearDown
+- No bare `except:` — always specify exception type
+- File naming: `snake_case.py`
+- Prefer dataclasses or Pydantic models for structured data<% if (architectureStyle === 'hexagonal') { %>
+
+### Architecture Verification (M22d)
+
+Generated `import-linter` + `ruff` banned-api + domain-purity grep enforce hexagonal layer isolation (hard gate, L2+).
+
+**Peer deps**: `pip install import-linter` (ruff assumed — required for L1 lint).
+
+**Setup**: the generated `.importlinter` and `ruff-boundaries.toml` sit at the project root. **One-time action**: open `.importlinter` and replace `yourpkg` with your actual top-level package name. No `pyproject.toml` changes are made.
+
+**Assumed layout**: `src/<pkg>/domain/`, `src/<pkg>/application/`, `src/<pkg>/adapters/`, `src/<pkg>/infrastructure/`. Flat-layout projects must adapt the `src/domain/` path in `scripts/check-boundaries.mjs` and `ruff-boundaries.toml`.
+
+**Rules enforced**:
+
+| Layer | Mechanism | What it bans |
+|-------|-----------|-------------|
+| `<pkg>.domain` | import-linter `forbidden` contract | Framework modules (django, flask, fastapi, sqlalchemy, httpx, …) |
+| All layers | import-linter `layers` contract | Upward imports (domain cannot import application; application cannot import adapters; …) |
+| `src/domain/**/*.py` | ruff `TID251` banned-api via `ruff-boundaries.toml` | Same framework module list — caught at file granularity with line numbers |
+| `src/domain/**/*.py` | pure-Node grep scan in `check-boundaries.mjs` | `import X`, `from X import …` — enforces L1 without Python deps installed |
+
+**Suppressions**: add exemptions to `suppressions/boundaries-baseline.json` with `scope` (file-pattern glob) + `expiresAt` (wave-migration date). Enforced by `check-suppressions.mjs` L1 gate.
+<% } %><% } %>
+
+---
+
+## Testing Policy
+
+<% if (governanceLevel === 'L1') { %>### L1 (Minimal)
+
+- Unit tests for all business logic
+- No mocking of internal modules (only external boundaries)
+- Coverage target: 70%<% } %><% if (governanceLevel === 'L2') { %>### L2 (Standard)
+
+- Unit tests: 80% coverage minimum
+- Integration tests for all external boundaries (database, APIs)
+- No mocking of internal modules — only boundary mocks
+- TDD preferred: test first, then implement<% } %><% if (governanceLevel === 'L3') { %>### L3 (Full Audit)
+
+- Unit tests: 85% coverage minimum
+- Integration tests: all external boundaries covered
+- E2E tests: critical user journeys covered
+- Mutation testing: required (85% score minimum)
+- TDD required: test first is non-negotiable<% } %><% if (governanceLevel === 'L4') { %>### L4 (Audit/Compliance)
+
+- Unit tests: 85% coverage minimum
+- Integration tests: all external boundaries covered
+- E2E tests: critical user journeys covered
+- Mutation testing: required (85% score minimum)
+- Evidence harness: all test runs captured, retained, and auditable
+- STRIDE risk assessment: required for auth/external boundary changes
+- TDD required: test first is non-negotiable<% } %>
+
+---
+
+## Commit Convention
+
+```
+type(scope): summary
+
+Types: feat, fix, refactor, test, docs, ci, chore, perf
+Scope: optional — module or area affected
+Summary: imperative, lowercase, ≤ 72 chars
+```
+
+Examples:
+- `feat(auth): add OAuth2 token refresh`
+- `fix(#123): resolve null pointer in payment flow`
+- `test: add integration tests for user registration`
+
+---
+
+## Branch Strategy
+
+- Main branch: `main` — protected, requires PR + passing CI
+- Task branches: `task/#NNN-short-description`
+- No direct commits to `main`
+
+---
+
+## Gate System
+
+```
+L1 (fast, pre-commit):    <%= lintCommand %>
+                          <%= formatCommand %>
+                          <%= testCommand %>
+
+L2 (full, pre-push):      L1 + coverage + audit + integration tests
+
+L3 (deep, nightly/CI):    L2 + E2E + mutation testing
+
+L4 (compliance):          L3 + evidence harness + STRIDE risk + TRACK_ROUTER
+```
+
+Run locally:
+```bash
+node scripts/check-all.mjs L1   # before commit
+node scripts/check-all.mjs L2   # before push
+```
+
+---
+
+## Enforcement Chain
+
+Changes pass through five enforcement layers:
+
+| Layer | Mechanism | Coverage |
+|-------|-----------|----------|
+| Edit-time | Claude Code hooks (`.claude/hooks/`) | Claude Code edits only |
+| Pre-commit | `.githooks/pre-commit` — runs L1 gate | All editors (`git commit`) |
+| Pre-push | `.githooks/pre-push` — runs L2 gate | All pushes |
+| CI | GitHub Actions / equivalent | All PRs |
+| Branch protection | See ADR-007 | Force-push, direct merge |
+
+<% if (language === 'typescript') { %>Install hooks: `git config core.hooksPath .githooks` (auto-applied via `npm install` — see `package.json` `prepare` script).
+<% } else { %>Install hooks: `git config core.hooksPath .githooks` (or run `./scripts/setup-hooks.sh`).
+<% } %>Bypass surface: only `git commit --no-verify` (documented, audited at PR review).
+
+---
+<% if (enableDebtGates) { -%>
+<% const threshold = isL3Plus ? 85 : 80; -%>
+
+## Tech Debt Gates
+
+Enforced at L2+ (automated, runs in CI and locally via `node scripts/check-all.mjs L2`):
+
+| Check | Tool | Threshold |
+|-------|------|-----------|
+<% if (language === 'typescript') { %>| Coverage | vitest / jest | <%= threshold %>% lines |
+| Complexity | ESLint `complexity` rule | max 15 |
+| Dead Code | Knip | zero unused exports |
+| Circular Deps | madge | zero cycles |
+<% if (isL3Plus) { %>| Mutation testing (Stryker) | @stryker-mutator/core | 85% mutation score |
+<% } %><% } %><% if (language === 'rust') { %>| Coverage | cargo-tarpaulin / llvm-cov | <%= threshold %>% |
+| Complexity | `clippy::pedantic` | enforced |
+| Dead Code | `warn(dead_code)` (clippy) | zero warnings |
+<% if (isL3Plus) { %>| Mutation testing (cargo-mutants) | cargo-mutants (beta) | 85% mutation score |
+<% } %><% } %><% if (language === 'java') { %>| Coverage | JaCoCo | <%= threshold %>% |
+| Complexity | PMD `CyclomaticComplexity` | max 15 |
+| Dead/Unused Code | PMD UnusedCode rules | zero violations |
+<% if (isL3Plus) { %>| Mutation testing (pitest) | PIT 1.15+ | 85% mutation score |
+<% } %><% } %><% if (language === 'go') { %>| Coverage | go test -coverprofile | <%= threshold %>% |
+| Complexity | golangci-lint `gocyclo` | max 15 |
+| Dead Code | golangci-lint `deadcode,unused` | zero findings |
+<% } %><% if (language === 'python') { %>| Coverage | pytest-cov | <%= threshold %>% |
+| Complexity | ruff `C901,PLR` rules | max 15 |
+| Unused Imports | ruff `F401,F811` | zero findings |
+<% if (isL3Plus) { %>| Mutation testing (mutmut) | mutmut (beta) | 85% mutation score |
+<% } %><% } %>
+---
+
+## Debt Ratchet
+
+Proactive debt regression prevention. Baseline metrics stored in `debt-baseline.json` (commit this file).
+
+**Commands:**
+- `node scripts/capture-debt-baseline.mjs` — Capture current metrics as baseline
+- `node scripts/capture-debt-baseline.mjs --update` — Tighten baseline (only accepts improvements, never loosens)
+- `node scripts/debt-report.mjs` — Print current vs baseline comparison report
+- `node scripts/debt-report.mjs --gate` — Fail if any metric regressed (used in L2 gate)
+
+**Tracked:** coverage, complexity violations, dead code count, TODO count
+
+**Rule:** Never manually edit `debt-baseline.json` to loosen metrics — that defeats the ratchet. Only run `--update` after genuine improvements.
+
+---
+<% } %><% if (enableSecurityScanning) { %>
+## Security Scanning (INV-11/12/13)
+
+Security gates run as L2+ hard requirements. PII scan is HARD (no grace period) and runs before all other gates.
+
+| Scanner | Tool | Gate Level | Trigger |
+|---------|------|-----------|---------|
+| Secrets detection | gitleaks | L2 HARD | `gitleaks detect --source . --baseline-path suppressions/.gitleaksignore` |
+| PII scan | pii-scan.mjs | L2 HARD (no grace) | `node scripts/pii-scan.mjs` |
+<% if (language === 'typescript') { %>| Dep audit | npm audit | L2 HARD | `npm audit --omit=dev --audit-level=high` |
+<% } %><% if (language === 'rust') { %>| Dep audit | cargo audit | L2 HARD | `cargo audit` |
+<% } %><% if (language === 'java' || language === 'kotlin') { %>| Dep audit | Trivy fs | L2 HARD | `trivy fs --scanners vuln --severity HIGH,CRITICAL --exit-code 1 --ignorefile .trivyignore .` |
+<% } %><% if (language === 'go') { %>| Dep audit | govulncheck | L2 HARD | `govulncheck ./...` |
+<% } %><% if (language === 'python') { %>| Dep audit | pip-audit | L2 HARD | `pip-audit` |
+<% } %>
+**Suppression files** (user-edited, not overwritten):
+- `suppressions/.gitleaksignore` — allowlisted gitleaks findings
+- `suppressions/pii-allowlist.json` — allowlisted PII patterns (format: `[{"pattern": "...", "reason": "..."}]`)
+<% if (language === 'java' || language === 'kotlin') { %>
+**Java/Kotlin dep audit**: Trivy fs suppression file: `.trivyignore` (root; format `CVE-ID exp:YYYY-MM-DD # reason=... owner=@handle`, INV-31).
+<% } %>
+**Claude hook**: `check-no-pii.mjs` (PostToolUse, Edit|Write) blocks PII from being written to source files.
+
+---
+<% } -%>
+<% { const _lanes = Array.isArray(lanes) ? lanes : []; const _multiLane = _lanes.length >= 2; if (_multiLane) { -%>
+---
+
+## Lane Discipline
+
+This project uses lane-isolated development. **Cross-stack rule:** if a task touches more than one lane, STOP and split into separate tasks/PRs.
+
+| Lane | Scope | Role |
+|------|-------|------|
+<% if (_lanes.includes('frontend')) { %>| **frontend** | `frontend/` | UI — components, styles, client logic |
+<% } %><% if (_lanes.includes('backend')) { %>| **backend** | `backend/` | Server — APIs, domain, persistence |
+<% } %><% if (_lanes.includes('docs')) { %>| **docs** | `docs/` | Documentation (READ-ONLY src, WRITE-ONLY docs) |
+<% } %>
+**Single-lane task**: identify lane, run lane gate, PR touches only that lane's files.
+**Cross-lane task**: STOP → split into N single-lane PRs, one per affected lane.
+<% } } -%>
+
+## Multi-Agent Tool Extensions
+
+This project uses AGENTS.md as the canonical source. Tool-specific files add only what each tool uniquely needs:
+
+| File | Tool | Purpose |
+|------|------|---------|
+| `.claude/CLAUDE.md` | Claude Code | Hook configuration, sub-agents, slash commands |
+| `.agents/CODEX.md` | OpenAI Codex | Plan JSON schema, execution router |
+
+When using Claude Code: read `.claude/CLAUDE.md` for Claude-specific configuration.
+When using Codex: read `.agents/CODEX.md` for Codex-specific configuration.
+<% if (typeof installedSkills !== 'undefined' && installedSkills.length > 0) { %>
+
+---
+
+## Integrations
+
+Installed Claude Code skills detected at init time. These replace the corresponding built-in arbiter skill generators — do not regenerate the listed files.
+
+| Skill ID | Owner | Role | Replaces |
+|----------|-------|------|---------|
+<% for (const skill of installedSkills) { %>| `<%= skill.skillId %>` | <%= skill.pluginOwner %> | <%= skill.role || '—' %> | <% const skipped = (skippedGenerators || []).filter(s => s.replacedBy === skill.skillId).map(s => '`' + s.generator + '`').join(', '); %><%= skipped || '—' %> |
+<% } %>
+
+**Note:** Skill SKILL.md files listed under "Replaces" are not generated — the installed plugin provides superior coverage. Reference the plugin's documentation directly.
+<% } %>
+All governance rules are in **this file**.

package/dist/templates/api-e2e/README.md.ejs

@@ -0,0 +1,33 @@
+# Live API e2e (`tests/api/`)
+
+Non-mocked end-to-end tests that run against the **real booted binary** over real HTTP.
+Required for service archetypes by **INV-126** (`api-e2e.json` `required:true`).
+
+## Why this layer exists
+
+Unit and integration tests can be fully green while the running product is broken: a
+field present in the domain/DB but never wired into the HTTP input struct returns `400`,
+and nothing in the mocked test pyramid catches it. This suite closes that gap by asserting
+on responses from the actual server.
+
+## Running
+
+```bash
+./tests/api/run.sh
+```
+
+`run.sh` builds the binary, boots it (use a throwaway DB and a harness auth-bypass — never
+production credentials), waits for `/health`, runs the suite against `API_BASE_URL`, and
+tears the server down on exit.
+
+## The gate
+
+`scripts/check-api-e2e.mjs` (INV-126) fails the gate if this suite is **absent or empty**
+for a service archetype. It checks presence + non-emptiness only; the live run happens in
+CI/L2 via `run.sh`. Assertion quality is covered separately by the anti-proforma gate
+(INV-118).
+
+## Customising
+
+Adapt the boot command in `run.sh` and add real request/response assertions to the starter
+suite file. Keep at least one assertion against a live HTTP response so the gate stays green.

package/dist/templates/api-e2e/go-httptest.go.ejs

@@ -0,0 +1,43 @@
+//go:build apie2e
+// +build apie2e
+
+// SPDX-License-Identifier: Apache-2.0
+// Live-API e2e (INV-126): runs against the REAL booted server, no mocks.
+// API_BASE_URL points at the running binary (tests/api/run.sh boots it).
+// Tagged `apie2e` (#1840 F4 tranche-3) so it is excluded from the default
+// `go test ./...` / `go vet ./...` — the generated L1 gate's unit-test step
+// must never require a live server on :8080. tests/api/run.sh passes
+// `-tags apie2e` to run it for real, after booting the binary. Mirrors the
+// `bdd`-tagged suite's isolation pattern (internal/bdd/example_test.go).
+package api_test
+
+import (
+	"net/http"
+	"os"
+	"testing"
+	"time"
+)
+
+func baseURL() string {
+	if v := os.Getenv("API_BASE_URL"); v != "" {
+		return v
+	}
+	return "http://127.0.0.1:8080"
+}
+
+// TestLiveHealth hits the running binary over real HTTP.
+func TestLiveHealth(t *testing.T) {
+	client := &http.Client{Timeout: 5 * time.Second}
+	resp, err := client.Get(baseURL() + "/health")
+	if err != nil {
+		t.Fatalf("live request failed (is the binary running?): %v", err)
+	}
+	defer resp.Body.Close()
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("GET /health: want 200, got %d", resp.StatusCode)
+	}
+
+	// Add real request/response assertions exercising the live HTTP surface here —
+	// this layer catches "domain green, HTTP wiring broken" bugs (e.g. a field in
+	// the domain/DB never wired into the request input struct).
+}

package/dist/templates/api-e2e/java-restassured.java.ejs

@@ -0,0 +1,28 @@
+// SPDX-License-Identifier: Apache-2.0
+// Live-API e2e (INV-126): runs against the REAL booted server, no mocks.
+// API_BASE_URL points at the running binary (tests/api/run.sh boots it).
+package <%- basePackage || 'com.example' %>.api;
+
+import static io.restassured.RestAssured.given;
+import static org.hamcrest.Matchers.notNullValue;
+
+import io.restassured.RestAssured;
+import org.junit.jupiter.api.BeforeAll;
+import org.junit.jupiter.api.Test;
+
+class ApiE2ETest {
+
+  @BeforeAll
+  static void configureBaseUri() {
+    String base = System.getenv("API_BASE_URL");
+    RestAssured.baseURI = (base != null && !base.isEmpty()) ? base : "http://127.0.0.1:8080";
+  }
+
+  @Test
+  void healthEndpointReturns200FromRunningBinary() {
+    given().when().get("/health").then().statusCode(200).body(notNullValue());
+
+    // Add real request/response assertions exercising the live HTTP surface here —
+    // this layer catches "domain green, HTTP wiring broken" bugs.
+  }
+}

package/dist/templates/api-e2e/kotlin-restassured.kt.ejs

@@ -0,0 +1,30 @@
+// SPDX-License-Identifier: Apache-2.0
+// Live-API e2e (INV-126): runs against the REAL booted server, no mocks.
+// API_BASE_URL points at the running binary (tests/api/run.sh boots it).
+package <%- basePackage || 'com.example' %>.api
+
+import io.restassured.RestAssured
+import io.restassured.RestAssured.given
+import org.hamcrest.Matchers.notNullValue
+import org.junit.jupiter.api.BeforeAll
+import org.junit.jupiter.api.Test
+
+class ApiE2ETest {
+
+  companion object {
+    @JvmStatic
+    @BeforeAll
+    fun configureBaseUri() {
+      val base = System.getenv("API_BASE_URL")
+      RestAssured.baseURI = if (!base.isNullOrEmpty()) base else "http://127.0.0.1:8080"
+    }
+  }
+
+  @Test
+  fun healthEndpointReturns200FromRunningBinary() {
+    given().`when`().get("/health").then().statusCode(200).body(notNullValue())
+
+    // Add real request/response assertions exercising the live HTTP surface here —
+    // this layer catches "domain green, HTTP wiring broken" bugs.
+  }
+}

package/dist/templates/api-e2e/manifest.json.ejs

@@ -0,0 +1,8 @@
+{
+  "archetype": "<%- archetype %>",
+  "required": <%- required %>,
+  "suiteDir": "<%- suiteDir %>",
+  "framework": "<%- framework %>",
+  "glob": "<%- glob %>",
+  "suiteCount": <%- suiteCount %>
+}