@getarbiter/cli 0.5.0

package/dist/templates/resilience/RESILIENCE.md.ejs

@@ -0,0 +1,310 @@
+# Resilience Patterns
+
+> **Advisory** — This document is generated by arbiter for `backend-web-db` projects at L2+.
+> It prescribes the recommended defaults. Override where your service's SLA/SLO demands differ.
+
+## Defaults at a glance
+
+| Pattern | Default |
+|---------|---------|
+| Retry attempts | 3 (including initial) |
+| Initial backoff | 1 s |
+| Max backoff cap | 30 s |
+| Backoff multiplier | 2× |
+| Jitter | 50 % randomised |
+| Retry on | 5xx + connection/timeout only — **never 4xx** |
+| Circuit-breaker threshold | 50 % failure rate |
+| Circuit-breaker min-calls | 10 |
+| CB decorator order | CB wraps retry (CB sees final outcome) |
+| Per-attempt timeout | 5 s |
+| Rate-limiter (token bucket) | 100 req/s sustained, burst 20, per-client key |
+
+---
+
+## Circuit Breaker
+
+A circuit breaker prevents cascading failures by opening (stopping calls) once failures exceed
+a threshold, then allowing a probe call in half-open state before closing again.
+
+**Critical ordering:** place the circuit breaker as the **outer** decorator wrapping retry.
+The CB observes the final result of the whole retry sequence — not each individual attempt.
+
+<% if (language === 'typescript' || language === 'multi') { %>
+### TypeScript — cockatiel
+
+```typescript
+import {
+  ExponentialBackoff,
+  SamplingBreaker,
+  circuitBreaker,
+  handleWhen,
+  retry,
+  wrap,
+} from 'cockatiel'
+import type { IPolicy } from 'cockatiel'
+
+/** Error thrown for HTTP 4xx responses — must NOT be retried. */
+export class ClientError extends Error {
+  constructor(
+    public readonly status: number,
+    message: string,
+  ) {
+    super(message)
+    this.name = 'ClientError'
+  }
+}
+
+/** Error thrown for HTTP 5xx / connectivity failures — eligible for retry. */
+export class ServerError extends Error {
+  constructor(
+    public readonly status: number,
+    message: string,
+  ) {
+    super(message)
+    this.name = 'ServerError'
+  }
+}
+
+/**
+ * Build a resilience policy: circuit-breaker (outer) wrapping retry (inner).
+ * The CB observes the final outcome of the whole retry sequence.
+ *
+ * IMPORTANT: use handleWhen, not handleAll. handleAll retries every error
+ * including 4xx (ClientError). handleWhen lets us exclude 4xx explicitly.
+ */
+export function buildResiliencePolicy(): IPolicy {
+  // Retry only on ServerError and network errors — never ClientError (4xx).
+  const retryPolicy = retry(handleWhen((err) => !(err instanceof ClientError)), {
+    maxAttempts: 3,
+    backoff: new ExponentialBackoff({
+      initialDelay: 1_000, // 1 s
+      maxDelay: 30_000, // 30 s cap
+      exponent: 2,
+      random: true, // 50 % jitter
+    }),
+  })
+
+  // CB observes the final result of the whole retry sequence.
+  const cbPolicy = circuitBreaker(handleWhen((err) => !(err instanceof ClientError)), {
+    halfOpenAfter: 5_000,
+    breaker: new SamplingBreaker({
+      threshold: 0.5, // open at 50 % failure rate
+      duration: 30_000, // 30 s sampling window
+      minimumRps: 10, // minimum calls before evaluating
+    }),
+  })
+
+  // CB outer, retry inner
+  return wrap(cbPolicy, retryPolicy)
+}
+
+/** Call an external service with the resilience policy applied. */
+const policy = buildResiliencePolicy()
+
+export function callWithResilience<T>(fn: () => Promise<T>): Promise<T> {
+  return policy.execute(fn)
+}
+
+// Usage:
+// const data = await callWithResilience(async () => {
+//   const response = await fetch(url, { signal: AbortSignal.timeout(5_000) })
+//   if (response.status >= 400 && response.status < 500) {
+//     throw new ClientError(response.status, `Client error: ${response.status}`)
+//   }
+//   if (!response.ok) {
+//     throw new ServerError(response.status, `Server error: ${response.status}`)
+//   }
+//   return response.json() as Promise<T>
+// })
+```
+
+<% } %>
+<% if (language === 'java' || language === 'multi') { %>
+### Java — Resilience4j
+
+```xml
+<!-- pom.xml -->
+<dependency>
+  <groupId>io.github.resilience4j</groupId>
+  <artifactId>resilience4j-spring-boot3</artifactId>
+</dependency>
+```
+
+```yaml
+# application.yml
+resilience4j:
+  circuitbreaker:
+    instances:
+      default:
+        failure-rate-threshold: 50          # open at 50 % failure rate
+        minimum-number-of-calls: 10         # min calls before evaluating
+        wait-duration-in-open-state: 10s
+        permitted-number-of-calls-in-half-open-state: 3
+        sliding-window-type: COUNT_BASED
+        sliding-window-size: 20
+  retry:
+    instances:
+      default:
+        max-attempts: 3
+        wait-duration: 1s
+        enable-exponential-backoff: true
+        exponential-backoff-multiplier: 2
+        exponential-max-wait-duration: 30s  # 30 s cap
+        retry-exception-predicate: com.example.resilience.ServerErrorPredicate
+        ignore-exceptions:
+          - com.example.resilience.ClientErrorException   # never retry 4xx
+  timelimiter:
+    instances:
+      default:
+        timeout-duration: 5s               # per-attempt timeout
+```
+
+```java
+// ServerErrorPredicate.java
+package com.example.resilience;
+
+import java.util.function.Predicate;
+
+/** Retry only on server errors and connectivity failures — never 4xx. */
+public class ServerErrorPredicate implements Predicate<Throwable> {
+    @Override
+    public boolean test(Throwable t) {
+        if (t instanceof ClientErrorException) return false; // 4xx — never retry
+        if (t instanceof ServerErrorException) return true;  // 5xx — retry
+        if (t instanceof java.net.ConnectException) return true;
+        if (t instanceof java.net.SocketTimeoutException) return true;
+        return false;
+    }
+}
+```
+
+**Critical:** annotate your service method with CB outer, retry inner:
+
+```java
+@CircuitBreaker(name = "default", fallbackMethod = "fallback")
+@Retry(name = "default")
+@TimeLimiter(name = "default")
+public CompletableFuture<Response> callExternalService(Request request) {
+    // ...
+}
+```
+
+<% } %>
+<% if (language !== 'typescript' && language !== 'java' && language !== 'multi') { %>
+### Your stack — <%= language %>
+
+Language-specific circuit-breaker and retry libraries are not prescribed here for `<%= language %>`.
+Consult your stack's resilience library (e.g. tenacity for Python, go-resiliency for Go, or
+a service-mesh policy). Apply the same defaults: 3 attempts, 1 s→30 s exponential+jitter,
+never retry 4xx, CB at 50 % over 10 calls, CB outer-wraps-retry.
+
+<% } %>
+
+---
+
+## Retry / Backoff
+
+**Rule:** retry `5xx` and connectivity failures only. **Never retry 4xx** — the client must fix
+the request. Retrying 4xx amplifies load without any chance of success.
+
+| Parameter | Value | Notes |
+|-----------|-------|-------|
+| Max attempts | 3 | Includes the initial attempt |
+| Initial interval | 1 s | |
+| Max interval | 30 s | Cap prevents unbounded wait |
+| Multiplier | 2× | Exponential backoff |
+| Jitter | 50 % | Prevents thundering-herd on simultaneous failures |
+| Retryable | `5xx`, `ConnectException`, `SocketTimeoutException` | |
+| Non-retryable | `4xx` | Surface immediately; do not retry |
+
+---
+
+## Timeout Budget
+
+**5 s per attempt** — not for the whole retry sequence. Total worst-case: `5 s × 3 = 15 s`,
+plus backoff between retries (`1 s + 2 s = 3 s`), so ≈18 s maximum. Set your caller's timeout
+to accommodate this if the call is synchronous and user-facing.
+
+---
+
+## Rate Limiter
+
+Token-bucket defaults: **100 req/s sustained, burst 20, keyed per client/tenant**.
+
+Apply upstream (at the entry point, not the outbound adapter) to protect your service from
+overload. If you are calling a third-party API, apply the rate limiter at the outbound adapter
+keyed on the external service to stay within their quota.
+
+<% if (language === 'typescript' || language === 'multi') { %>
+```typescript
+import { RateLimiterMemory } from 'rate-limiter-flexible'
+
+const rateLimiter = new RateLimiterMemory({
+  points: 100,     // 100 tokens
+  duration: 1,     // per second
+})
+
+// Burst: allow 20 extra
+const burstLimiter = new RateLimiterMemory({
+  points: 20,
+  duration: 1,
+  blockDuration: 0,
+})
+```
+<% } %>
+<% if (language === 'java' || language === 'multi') { %>
+```yaml
+# application.yml
+resilience4j:
+  ratelimiter:
+    instances:
+      default:
+        limit-for-period: 100         # 100 req/s sustained
+        limit-refresh-period: 1s
+        timeout-duration: 0           # fail fast on exceed
+```
+<% } %>
+
+---
+
+## External-call / Adapter Checklist
+
+When adding a new external call or adapter, verify each item:
+
+- [ ] **Isolated CB+retry instance per target** — one per external service/tenant, lazily created
+      and cached by key. Shared instances amplify blast radius across unrelated targets.
+- [ ] **Config at instance creation** — values read once at construction time. Explicit cache
+      invalidation (restart or reload) required to pick up changes.
+- [ ] **Test seam** — inject a configurable interval/delay function so integration tests can
+      use fast (0 ms) intervals without touching production configuration.
+- [ ] **Graceful degradation** — invalid or missing config falls back to the defaults above,
+      not to an error or panic.
+- [ ] **SSRF allowlist** — validate outbound URLs at dispatch time: require HTTPS, block
+      private RFC-1918 ranges, loopback (127.x, ::1), and link-local (169.254.x).
+- [ ] **No secrets in logs** — sanitize URLs (strip query tokens), headers, and response bodies
+      before logging. Never log Authorization or X-Api-Key values.
+- [ ] **At-least-once delivery** — retry semantics mean consumers must be idempotent. Document
+      this contract in the consumer's integration guide.
+- [ ] **Dead-letter after max attempts** — route undeliverable messages to a DLQ or dead-letter
+      topic after exhausting retries. Do not silently drop.
+- [ ] **Retry on 5xx only** — verify the retry predicate excludes 4xx explicitly. A broad
+      `catch(Exception)` retry predicate is a bug.
+
+<% if (isL3Plus) { %>
+
+---
+
+## L3/L4 enforcement
+
+At governance level `<%= governanceLevel %>` the following are hard requirements in addition to
+the advisory defaults above:
+
+- **Circuit-breaker metrics exported** — CB state (open/closed/half-open) + failure rate must
+  be observable via the service's metrics endpoint (Prometheus/Micrometer scrape target).
+- **Retry count metric** — instrument retry attempts per target with a labelled counter.
+- **Runbook linked** — each CB instance must have a corresponding runbook entry describing
+  the escalation path when it opens and remains open beyond the alert threshold.
+- **Load-test evidence** — the retry+CB policy must be exercised under simulated failure
+  conditions (e.g. Toxiproxy/Chaos Monkey) and the CB-open event must appear in traces.
+
+<% } %>

package/dist/templates/root/.gitignore.ejs

@@ -0,0 +1,85 @@
+# <%= projectName %> — generated by arbiter (skipIfExists: never overwritten)
+# Add project-specific entries below.
+
+# Dependencies
+node_modules/
+vendor/
+
+# Build output
+dist/
+build/
+target/
+*.egg-info/
+__pycache__/
+*.pyc
+
+# Test / coverage artifacts
+coverage/
+.nyc_output/
+*.lcov
+
+# jscpd duplication report (CANON-22 gate byproduct)
+report/
+
+# VitePress build temp output
+website/.vitepress/.temp/
+
+# Environment / secrets
+.env
+.env.local
+.env.*.local
+
+# Editor / OS
+.DS_Store
+Thumbs.db
+*.swp
+*.swo
+
+# Arbiter evidence harness (local retention)
+.evidence/
+
+# Arbiter local runtime state.
+# `/**` and not `/` (#2313): git cannot re-include a file whose PARENT DIRECTORY
+# stays excluded, so a blanket `.arbiter/` makes every negation below dead text.
+# The TDD evidence files are carved out because the L2 gate reads them from a
+# FRESH CI checkout, and because the produced-here guard in
+# scripts/check-tdd-evidence.mjs (#2307) diffs them against the merge-base — an
+# untracked evidence file makes that guard permanently inert. Everything else
+# under .arbiter/ is machine-local runtime state (plan run history, ship attempt
+# counters, worktrees, private notes) and stays ignored.
+.arbiter/**
+!.arbiter/evidence/
+!.arbiter/evidence/tdd/
+!.arbiter/evidence/tdd/*.json
+!.arbiter/evidence/journey/
+!.arbiter/evidence/journey/*.json
+.agents-dispatched
+.claude/.task-*
+.claude/.task/
+.claude/plans/
+
+# Arbiter backup turds (written by runtime; never commit)
+*.arbiter-backup
+.arbiter-generated.json.bak.*
+<% /* #1407: stack-aware entries — GREENFIELD-PREVENTION ONLY.
+      generateEvidenceRetention renders this with skipIfExists:true, so an
+      EXISTING .gitignore is never rewritten. The extended repo-hygiene GATE
+      (scripts/check-no-tracked-artifacts.mjs) is the retroactive catch for
+      already-tracked artifacts; brownfield .gitignore-merge-on-update is OUT
+      of scope (see ADR-047 / follow-up). language is always present; guard
+      databaseEngine because it is optional in ProjectConfig (EJS with(locals)
+      would throw on a bare reference to an absent key). */ %>
+<% if (language === 'go') { %>
+# Go compiled binary (module-root, named after the project) (#1407)
+/<%= projectName %>
+<% } %><% if (language === 'rust') { %>
+# Rust build output (#1407)
+/target/
+<% } %><% if (typeof databaseEngine !== 'undefined' && databaseEngine === 'sqlite') { %>
+# SQLite data/state files — must never be committed (#1407, INV-129)
+*.sqlite
+*.sqlite3
+*.db
+*.db-shm
+*.db-wal
+<% } %>

package/dist/templates/root/CODEOWNERS.ejs

@@ -0,0 +1,18 @@
+<%# CODEOWNERS — auto-generated by arbiter %>
+* @<%= githubOwner %>
+<%# #1720 (gap 2a/2b): guards were literal === 'L2' || === 'L3' / === 'L3', silently
+    excluding L4 — L4 got the WEAKEST CODEOWNERS of all levels. isL2Plus/isL3Plus
+    (levelAtLeast SSOT, #1516) keep L4 a strict superset of L3. %>
+<% if (isL2Plus) { %>
+# Security-sensitive paths require owner approval
+.github/workflows/ @<%= githubOwner %>
+.githooks/ @<%= githubOwner %>
+scripts/check-all.mjs @<%= githubOwner %>
+AGENTS.md @<%= githubOwner %>
+<% } %>
+<% if (isL3Plus) { %>
+# Governance and security documentation
+docs/SECURITY/ @<%= githubOwner %>
+docs/GOVERNANCE/ @<%= githubOwner %>
+docs/SECURE_CODING_CHECKLIST.md @<%= githubOwner %>
+<% } %>

package/dist/templates/root/CONTRIBUTING.md.ejs

@@ -0,0 +1,62 @@
+# Contributing to <%= projectName %>
+
+Thank you for considering contributing to **<%= projectName %>**.
+
+## Getting Started
+
+1. Fork the repository
+2. Create a task branch: `git checkout -b task/#NNN-short-description`
+3. Make your changes following the guidelines below
+4. Run the quality gate: `<%= testCommand %>`
+5. Commit with the [conventional format](#commit-format)
+6. Open a Pull Request
+
+## Branch Naming
+
+```
+task/#NNN-short-description
+```
+
+Where `#NNN` is the GitHub issue number. No direct commits to `main`.
+
+## Commit Format
+
+```
+type(scope): summary
+
+- Detail of what changed
+- Detail of what changed
+```
+
+**Types:** `feat`, `fix`, `refactor`, `test`, `docs`, `chore`, `ci`
+
+## Code Standards
+
+See `AGENTS.md` for the full coding standards, invariants, and testing policy.
+
+Key rules:
+- All code must pass the quality gate before committing<% if (language === 'typescript') { %>
+- No `any` types — use proper type annotations<% } %><% if (language === 'rust') { %>
+- No `.unwrap()` — use proper error handling<% } %>
+- No orphan TODOs — every `TODO` must reference a task ID (`TODO(#NNN)`)
+- Tests required for new functionality
+
+## Quality Gate
+
+```bash
+<%= testCommand %>
+```
+
+<% if (lintCommand) { %>**Lint:** `<%= lintCommand %>`
+<% } %><% if (formatCommand) { %>**Format:** `<%= formatCommand %>`
+<% } %>
+## Pull Requests
+
+- Fill out the PR template completely
+- Link the related issue
+- Ensure the gate passes in CI
+- Request review from a code owner
+
+## Questions?
+
+Open a [discussion](https://github.com/<%= githubOwner %>/<%= githubRepo %>/discussions) or reach out to the maintainers.

package/dist/templates/root/SECURITY.md.ejs

@@ -0,0 +1,19 @@
+# Security Policy
+
+## Reporting a Vulnerability
+
+**Do not open a public GitHub issue for security vulnerabilities.**
+
+Report security issues privately to the maintainer:
+- Email: (configure your contact email)
+- Or use GitHub's private vulnerability reporting: Settings → Security → Advisories
+
+## Scope
+
+This policy applies to the `<%= projectName %>` codebase.
+
+## Response Timeline
+
+- Acknowledgment: within 48 hours
+- Initial assessment: within 7 days
+- Fix timeline: depends on severity (critical: 24-48h, high: 7 days, medium: 30 days)

package/dist/templates/root/TEST_TAXONOMY.md.ejs

@@ -0,0 +1,100 @@
+# Test Taxonomy — <%= projectName %>
+
+<!-- arbiter-managed: test-pyramid-profile (INV-89) -->
+<!-- Archetype: <%= archetype %> -->
+
+This document defines the test pyramid for **<%= projectName %>**.
+Each level maps to a CI stage in `ci.yml` and a check in `scripts/check-all.mjs`.
+
+---
+
+## Pyramid Levels
+
+| Level | Description | Tools |
+|-------|-------------|-------|
+<% for (const level of levels) { -%>
+| **<%= level.name %>** | <%= level.description %> | `<%= level.tools %>` |
+<% } %>
+
+---
+
+## Conventions
+
+- **L1 tests** run on every commit (pre-commit hook via `scripts/check-all.mjs L1`).
+- **L2+ tests** run on push/PR (`scripts/check-all.mjs L2`).
+- Test files live next to the code they test (co-located) or in a top-level `tests/` directory.
+- Every public function/method must have at least one test.
+<% if (hasContainerIntegration) { %>
+- Testcontainers are the preferred integration harness — no mocked DB connections in integration tests.
+<% } %><% if (hasPropertyTests) { %>
+- Property-based tests must cover all public API inputs. Use `fast-check` / `Hypothesis` / `proptest`.
+<% } %><% if (hasE2ETests) { %>
+- E2E tests run headless in CI (Playwright recommended).
+<% } %>
+
+---
+
+## Test Type Codes
+
+| Code | Name | Description |
+|------|------|-------------|
+| **UT** | Unit Test | Pure function / class isolation — no I/O, no DB (INV-26) |
+| **IT** | Integration Test | Two or more real collaborators (DB, queue, cache) — Testcontainers where applicable |
+| **AU** | API / Contract Unit | HTTP boundary — input validation, error contracts, OpenAPI parity (INV-47) |
+| **ST** | System / E2E Test | Full stack — real infra, real browser (Playwright) where applicable |
+| **SC** | Scenario / BDD Test | Gherkin scenarios — cross-module behavior from the user's perspective |
+| **SN** | Snapshot Test | Golden-file / snapshot regressions — UI, serialisation, report output |
+| **E2E** | End-to-End Test | Alias for ST; used when framing is user-journey centric |
+
+---
+
+## Universal Quality Dimensions
+
+Every test level must address the applicable subset of the 17 universal dimensions below.
+Primary codes indicate which test type most naturally covers each dimension.
+
+| # | Dimension | Primary Code | INV Reference |
+|---|-----------|-------------|---------------|
+| 1 | Owner isolation — tenant/user data cannot bleed across boundaries | IT / AU | INV-19 |
+| 2 | RBAC — role permissions enforced at every endpoint and query | AU / IT | INV-19 |
+| 3 | Input validation — all public inputs validated; invalid inputs rejected with correct status | AU / UT | INV-47 |
+| 4 | Error contracts — error codes, messages, and HTTP status are stable and documented | AU | INV-47 |
+| 5 | OpenAPI parity — generated/written spec matches actual handler behaviour | AU | INV-47 |
+| 6 | Pagination — list endpoints honour page/limit/cursor; no unbounded scans | AU / IT | INV-14 |
+| 7 | Idempotency — mutating operations safe to retry (PUT / PATCH / DELETE) | AU / IT | INV-14 |
+| 8 | Migration integrity — DB migrations are reversible and tested in CI | IT | INV-30 |
+| 9 | Observability — structured logs emitted for all error paths; spans created for I/O | UT / IT | INV-17 |
+| 10 | Perf / N+1 — no N+1 queries; latency budgets asserted in integration layer | IT | INV-14 |
+| 11 | Failure recovery — circuit-breakers, retries, and fallbacks exercised | IT / ST | INV-17 |
+| 12 | DTO roundtrip — serialise → deserialise identity holds for every public DTO | UT / AU | INV-47 |
+| 13 | Entity–schema parity — ORM entity fields match DB column types | IT | INV-30 |
+| 14 | Cross-module ref integrity — FK/ref constraints never violated in test fixtures | IT | INV-30 |
+| 15 | Profile security — user profile data never returned to wrong owner | AU / IT | INV-19 |
+| 16 | Backward compat — existing clients unaffected by new release (schema + API) | AU / ST | INV-47 |
+| 17 | Contract test coverage — published consumer contracts verified per deploy | AU | INV-48 |
+<% const _domainDims = (typeof domainDims !== 'undefined' && Array.isArray(domainDims)) ? domainDims : [] %><% if (_domainDims.length > 0) { %>
+
+### Domain-Specific Dimensions
+
+The following dimensions are project-specific (sourced from `arbiter.json` `taxonomy.domainDims[]`):
+
+<% for (const dim of _domainDims) { %>- `<%= dim %>`
+<% } %>
+<% } %>
+
+---
+
+## Decision Matrix — Change Type → Required Dimensions
+
+| Change Type | Mandatory Dimensions | Recommended Codes |
+|-------------|----------------------|-------------------|
+| New API endpoint | 1–5, 16 | AU + IT |
+| New DB entity / migration | 8, 13, 14 | IT |
+| Auth / permission change | 1, 2, 15 | AU + IT |
+| New list / search endpoint | 6, 10 | AU + IT |
+| Mutating endpoint (create/update/delete) | 7, 14 | AU + IT |
+| New public DTO / schema | 4, 5, 12, 16 | AU + UT |
+| External service integration | 11 | IT + ST |
+| Background job / worker | 9, 11 | IT |
+| UI feature | 3, 4 | SN + ST |
+| Cross-module feature | 14, 15 | IT + SC |

package/dist/templates/root/commitlint.config.js.ejs

@@ -0,0 +1,4 @@
+// @ts-check
+module.exports = {
+  extends: ['@commitlint/config-conventional'],
+};

package/dist/templates/root/docs/METHOD/CANONICAL_PATHS.md.ejs

@@ -0,0 +1,24 @@
+# Canonical Paths — <%= projectName %>
+
+**Purpose:** Aliasing registry for documents that have moved. Before reporting a broken link, check this file for the current location of the referenced document.
+**Location:** `docs/METHOD/CANONICAL_PATHS.md`
+
+---
+
+## Aliases
+
+| Old Path | Current Path | Moved Date |
+|----------|--------------|------------|
+
+---
+
+## Usage
+
+When a document is moved or renamed:
+
+1. Add a row to the Aliases table above: old path → new path + ISO date.
+2. Do **not** remove the old entry until all references are updated.
+3. Run `node scripts/check-doc-links.mjs` to verify no broken links remain after the redirect is added.
+4. Run `node scripts/check-canonical-paths.mjs` to confirm the new path exists.
+
+> Entries may be purged once all references are updated and the old path no longer appears in any document.