@getarbiter/cli 0.5.0

package/dist/templates/docs/skeletons/arc42-full.md.ejs

@@ -0,0 +1,59 @@
+# <%= title %>
+
+_Full arc42 — enterprise column. Includes a C4 Context/Container section (the `>2 deployable
+units` trigger promoted this from the Canvas). Keep each section short; link out to detail docs
+rather than inlining them._
+
+## Introduction and Goals
+
+<!-- What this system is for and who it serves, then the top quality goals it is optimised for and
+     the stakeholders who care. This is arc42 section 1: a reader who knows nothing should be able
+     to stop here and still know why the system exists. -->
+
+## Context
+
+<!-- System scope and boundary: who/what it talks to, in and out of scope. -->
+
+## Constraints
+
+<!-- Technical, organizational, and regulatory constraints. -->
+
+## C4 — Context & Container
+
+<!-- C4 Level 1 (Context) and Level 2 (Container) diagrams or their textual equivalent. -->
+
+## Solution strategy
+
+<!-- The top-level technology and pattern decisions, and why. -->
+
+## Building blocks
+
+<!-- Level 1 (and, where useful, level 2) decomposition — components, responsibilities, interfaces. -->
+
+## Runtime
+
+<!-- The important runtime scenarios: primary request flow, async/background paths, failure/retry. -->
+
+## Deployment
+
+<!-- Infrastructure, environments, and the path from commit to production. -->
+
+## Cross-cutting concepts
+
+<!-- Concerns that cut across building blocks: auth, logging, error handling, i18n, etc. -->
+
+## Decisions
+
+<!-- Link to docs/ADR — this section indexes, it does not restate. -->
+
+## Quality
+
+<!-- Quality tree / scenarios: which attributes matter, how they're measured and met. -->
+
+## Risks & technical debt
+
+<!-- Known architectural risks and debt; link docs/technical-debt.md for the full register. -->
+
+## Glossary
+
+<!-- Domain terms specific to this architecture; link docs/GLOSSARY.md for the full list. -->

package/dist/templates/docs/skeletons/decision-registry.md.ejs

@@ -0,0 +1,38 @@
+# Decision Registry — <%= projectName %>
+
+Registro delle **decisioni di progetto bloccate** (modello a 3 strati: Leggi → D-NN → ADR).
+Ogni D-NN dichiara il proprio enforcement; una decisione senza enforcement né esenzione
+`documentale` fa fallire `scripts/check-decision-registry.mjs` (decisione orfana).
+
+## Leggi
+
+*Sezione opzionale — le leggi immutabili del progetto (es. "una legge non cambia mai senza
+un D-NN"). Eliminarla se non usata.*
+
+- (nessuna legge registrata)
+
+## Decisioni
+
+| D-NN | decisione | razionale | decisore | data |
+| --- | --- | --- | --- | --- |
+| D-01 | (esempio — prima decisione bloccata) | (perché è bloccata) | (decisore) | <%= today %> |
+Enforcement: documentale
+
+> **Formato (leggibile dal gate):** ogni riga della tabella è una decisione `D-NN`. La riga
+> subito sotto la riga della tabella (senza riga vuota in mezzo) dichiara l'enforcement:
+> `Enforcement: <gate|test>` oppure `Enforcement: documentale` (esenzione esplicita —
+> il gate passa con una nota). Una D-NN senza riga Enforcement è una **decisione orfana**
+> e il gate fallisce nominandola. Rimuovere la riga di esempio quando la prima decisione reale
+> viene registrata.
+
+## Promozione a invariante (PROJ-NN)
+
+Una D-NN che matura in regola permanente si promuove a **PROJ-NN** — un invariante dichiarato
+dal progetto via `governance.projectInvariants[]` in `arbiter.json` (ADR-112). La regola vive
+in **UN solo registro**: una volta promossa a PROJ-NN, la riga D-NN viene rimossa da qui.
+
+## Changelog
+
+### v0.1.0 — <%= today %>
+
+- Registro decisioni iniziale (scaffold `arbiter`).

package/dist/templates/docs/skeletons/er-model.md.ejs

@@ -0,0 +1,19 @@
+# <%= title %>
+
+## Entities
+
+<!-- One entry per entity: name + one-line purpose. -->
+
+## Relations
+
+<!-- Entity-to-entity relations (cardinality, ownership direction). A diagram is welcome here. -->
+
+## Classification / PII columns
+
+| Entity | Field | Classification | PII? |
+|---|---|---|---|
+| <!-- entity --> | <!-- field --> | public / internal / confidential / restricted | yes / no |
+
+## Retention
+
+<!-- Retention period per entity (or link docs/data/retention.md if that's the SSOT). -->

package/dist/templates/docs/skeletons/glossary.md.ejs

@@ -0,0 +1,8 @@
+# <%= title %>
+
+_Domain + project terminology. Add a term as soon as it causes a cross-author misunderstanding —
+don't wait to backfill the whole vocabulary at once._
+
+| Term | Definition | Owner |
+|---|---|---|
+| <!-- term --> | <!-- one unambiguous sentence --> | <!-- who to ask --> |

package/dist/templates/docs/skeletons/governance.md.ejs

@@ -0,0 +1,13 @@
+# <%= title %>
+
+## Decision rights
+
+<!-- Who can decide what (architecture, dependency adds, process changes) — RACI or a short list. -->
+
+## Gate ladder
+
+<!-- The enforcement bands in use (advisory → soft → hard) and what promotes a gate between them. -->
+
+## Escalation
+
+<!-- What happens when a gate is bypassed or a decision is contested — the actual escalation path. -->

package/dist/templates/docs/skeletons/slo.md.ejs

@@ -0,0 +1,21 @@
+# <%= title %>
+
+## Objectives
+
+<!-- The 2-4 outcomes users actually care about (availability, latency, correctness, freshness). -->
+
+## SLIs
+
+<!-- The concrete, measurable indicators for each objective (e.g. p99 latency, error rate). -->
+
+## Targets
+
+<!-- The numeric target + measurement window per SLI (e.g. 99.9% over 30d). -->
+
+## Error budget
+
+<!-- Budget = 1 - target, the policy for spending it, and what happens at exhaustion. -->
+
+## Alerting hooks
+
+<!-- Which SLI breaches page on-call vs file a ticket; link the runbook/incident doc. -->

package/dist/templates/docs/skeletons/technical-debt.md.ejs

@@ -0,0 +1,8 @@
+# <%= title %>
+
+_Register table — known shortcuts, their cost, and the payback plan. Add an entry the moment a
+shortcut is taken; a debt register written after the fact is a wishlist, not a register._
+
+| Item | Class | Interest | Plan |
+|---|---|---|---|
+| <!-- what was shortcut --> | <!-- architectural / test / dependency / docs --> | <!-- cost of NOT paying it back, and how it compounds --> | <!-- issue/ADR link + trigger to pay it back --> |

package/dist/templates/docs/skeletons/test-strategy.md.ejs

@@ -0,0 +1,14 @@
+# <%= title %>
+
+## Pyramid
+
+<!-- The test levels this project uses (unit/integration/e2e/contract) and roughly what share of
+     coverage each owns. Link the real ratio source (e.g. test-pyramid.json) if one exists. -->
+
+## Coverage policy
+
+<!-- What must be covered before merge (new code, critical paths) and what is intentionally not. -->
+
+## Gate mapping
+
+<!-- Which test level runs at which gate (pre-push / PR / nightly / release) and why. -->

package/dist/templates/docs/skeletons/threat-model-4q.md.ejs

@@ -0,0 +1,20 @@
+# <%= title %>
+
+_Four-question threat model (Shostack) — right-sized for solo/small. Move to `threat-model-stride`
+once the `public`/`customer-data` trigger fires._
+
+## What are we building?
+
+<!-- One diagram or short description of the system/feature and its trust boundaries. -->
+
+## What can go wrong?
+
+<!-- Brainstormed list of threats — do not filter yet, completeness first. -->
+
+## What are we going to do about it?
+
+<!-- For each threat above: mitigate, accept, transfer, or eliminate — and how. -->
+
+## Did we do a good job?
+
+<!-- How this model will be re-validated (review cadence, trigger for re-run). -->

package/dist/templates/docs/skeletons/threat-model-stride.md.ejs

@@ -0,0 +1,22 @@
+# <%= title %>
+
+_STRIDE threat model — enterprise column. One row per component per applicable STRIDE category;
+delete categories that genuinely don't apply to a component rather than leaving them blank._
+
+## Components in scope
+
+<!-- List the components/trust boundaries this model covers. -->
+
+## STRIDE table
+
+| Component | Spoofing | Tampering | Repudiation | Info disclosure | DoS | Elevation of privilege |
+|---|---|---|---|---|---|---|
+| <!-- component --> | <!-- threat/mitigation --> | | | | | |
+
+## Mitigations tracker
+
+<!-- Link each mitigation above to an issue/ADR/config so it is auditable, not just documented. -->
+
+## Re-validation
+
+<!-- Cadence and triggers (new component, new trust boundary, incident) for re-running this model. -->

package/dist/templates/docs/specs/atomic-task-list.md.ejs

@@ -0,0 +1,57 @@
+# Atomic Task List — <%= projectName %>
+
+_Generated by arbiter. A template for decomposing a feature into **atomic tasks**:
+the smallest units that can each be shipped, tested, and reviewed on their own._
+
+## What "Atomic" Means
+
+A task is atomic when **all** of these hold:
+
+- **Independently shippable** — it can merge to the main branch without waiting on
+  a sibling task.
+- **Single responsibility** — one behavioural change, one reason to exist.
+- **Testable in isolation** — it has its own failing test before any code (TDD red).
+- **Bounded** — small enough to plan, implement, and review in one sitting.
+- **Acceptance-defined** — "done" is written down before work starts.
+
+If a task cannot satisfy these, split it further or record the dependency.
+
+## Decomposition Procedure
+
+1. State the feature outcome in one sentence.
+2. List the observable behaviours it requires.
+3. Turn each behaviour into one atomic task below.
+4. Mark dependencies explicitly — an atomic task may be *blocked by* another, but
+   must not *silently assume* another's code.
+5. Sequence so that every task lands green.
+
+## Task Template
+
+Copy this block per task.
+
+### TASK-NN — <short imperative title>
+
+- **Outcome:** what is observably true after this task merges.
+- **Depends on:** TASK-MM | none
+- **TDD red:** the failing test that proves the gap (path + assertion).
+- **Acceptance criteria:**
+  - [ ] _criterion 1 (observable, testable)_
+  - [ ] _criterion 2_
+- **Out of scope:** what this task deliberately does NOT do.
+- **Gate:** `node scripts/check-all.mjs L2` green.
+
+## Task List
+
+| ID      | Title | Depends on | Status |
+| ------- | ----- | ---------- | ------ |
+| TASK-01 | _…_   | none       | todo   |
+| TASK-02 | _…_   | TASK-01    | todo   |
+
+## Anti-Patterns
+
+| Anti-pattern | Why it fails |
+| ------------ | ------------ |
+| "Big bang" task touching many layers | Un-reviewable, un-revertable |
+| Task with no failing test first | No proof the change was needed |
+| Acceptance criteria written after coding | Confirmation bias, scope drift |
+| Hidden dependency between "independent" tasks | Breaks the main branch on partial merge |

package/dist/templates/docs/steering/product.md.ejs

@@ -0,0 +1,44 @@
+# Product Steering — <%= projectName %>
+
+_Generated by arbiter. The "why" an agent needs so its technical choices serve the
+product, not just the compiler. Fill these in; they decay fast — review on each
+milestone._
+
+## One-Line Description
+
+<%= description %>
+
+## Problem
+
+What pain does <%= projectName %> remove? Who feels it today, and how do they cope
+without this product?
+
+_Replace with your problem statement._
+
+## Users
+
+| User type | Goal | Success looks like |
+| --------- | ---- | ------------------ |
+| _primary_ | _…_  | _…_                |
+| _secondary_ | _…_ | _…_               |
+
+## Value & Differentiators
+
+Why this over the alternatives (including "do nothing")? List the 2–3 things that
+must stay true for the product to be worth using.
+
+- _…_
+- _…_
+
+## In Scope / Out of Scope
+
+| In scope (now) | Out of scope (explicitly) |
+| -------------- | ------------------------- |
+| _…_            | _…_                       |
+
+## Non-Negotiables
+
+Product-level constraints an agent must never trade away for convenience
+(e.g. data privacy, latency budget, accessibility, regulatory commitments).
+
+- _…_

package/dist/templates/docs/steering/structure.md.ejs

@@ -0,0 +1,49 @@
+# Structure Steering — <%= projectName %>
+
+_Generated by arbiter. A steering doc is durable project context an AI agent reads
+**before** touching code, so its choices match how this codebase is actually laid
+out. Keep it short, current, and specific._
+
+## Purpose
+
+This document anchors **where things live and where they must not**. When an agent
+proposes a change, it should locate the change against this map first.
+
+## Directory Map
+
+Replace the placeholders below with your real top-level layout:
+
+```
+.
+├── src/            # production code
+├── __tests__/      # tests (mirror src/ structure)
+├── docs/           # this directory — steering, specs, runbooks, ADRs
+└── scripts/        # build / gate / automation
+```
+
+## Module Boundaries
+
+Record the boundaries that the architecture gate enforces (ArchUnit / eslint
+boundaries / import-linter, depending on stack). An agent must not cross these.
+
+| Layer / Module | May depend on | Must NOT depend on |
+| -------------- | ------------- | ------------------ |
+| _domain_       | _nothing_     | _infra, web_       |
+| _application_  | _domain_      | _web_              |
+| _infra / web_  | _application_ | _other infra_      |
+
+## Naming & Placement Conventions
+
+- Tests live beside or mirror the unit under test.
+- New files: run the refactor-first survey before adding one (does it already exist?).
+- Generated files carry an arbiter marker — never hand-edit a generated artifact.
+
+## Where to Look First
+
+| If you are changing… | Start in… |
+| -------------------- | --------- |
+| business logic       | `src/` (domain/application) |
+| a gate or check      | `scripts/` |
+| project context      | `docs/steering/` (this file) |
+| a feature spec       | `docs/specs/` |
+| a bug                | `docs/bugs/` + `.evidence/` |

package/dist/templates/docs/steering/tech.md.ejs

@@ -0,0 +1,53 @@
+# Tech Steering — <%= projectName %>
+
+_Generated by arbiter. The technology baseline an agent must respect: language,
+toolchain, and the commands that prove a change is sound._
+
+## Stack
+
+| Aspect            | Value |
+| ----------------- | ----- |
+| Language          | <%= language %> |
+| Archetype         | <%= archetype %> |
+| Build tool        | <%= buildTool %> |
+| Governance level  | <%= governanceLevel %> |
+
+> Do not introduce a second language, framework, or build tool without an ADR
+> under `docs/adr/`. The architecture gate and CI are wired to the stack above.
+
+## Authoritative Commands
+
+These are the only commands that count as evidence. An agent claiming "it works"
+must show output from these, not a description.
+
+```bash
+# Build
+<%= buildCommand %>
+
+# Test
+<%= testCommand %>
+
+# Lint
+<%= lintCommand %>
+
+# Format (check)
+<%= formatCommand %>
+```
+
+## Gate
+
+The gate is the single source of truth for "green":
+
+```bash
+node scripts/check-all.mjs L1   # fast: lint + format + unit
+node scripts/check-all.mjs L2   # full: L1 + coverage + integration
+```
+
+A change is not done until the gate passes. No `--no-verify`, no editing a gate
+to make it pass.
+
+## Constraints an Agent Must Honor
+
+- Match existing patterns — read neighbouring code before writing.
+- No new dependency without justification recorded in an ADR or the PR body.
+- No suppression (lint-disable, ignore) without an inline reason and a task ID.

package/dist/templates/documentation/cli-catalog.md.ejs

@@ -0,0 +1,21 @@
+# Commands Catalog
+
+_Generated by arbiter for **<%= projectName %>**. Update `arbiter.json` to reflect changes._
+
+## Development Commands
+
+| Purpose | Command                |
+| ------- | ---------------------- |
+| Build   | `<%= buildCommand %>`  |
+| Test    | `<%= testCommand %>`   |
+| Lint    | `<%= lintCommand %>`   |
+| Format  | `<%= formatCommand %>` |
+
+## Gate Commands
+
+| Purpose        | Command                         |
+| -------------- | ------------------------------- |
+| L1 gate (fast) | `node scripts/check-all.mjs L1` |
+| L2 gate (full) | `node scripts/check-all.mjs L2` |
+
+> Run L1 before every commit, L2 before every push.

package/dist/templates/e2e/E2E_CONSTITUTION.md.ejs

@@ -0,0 +1,77 @@
+# E2E Constitution — <%= projectName %>
+<!-- arbiter-managed: e2e-constitution (#1817, A4) -->
+
+**Status:** RATIFIED
+**Scope:** every Playwright (or equivalent) spec under `tests/e2e/` or `e2e/`
+
+---
+
+## Why this exists
+
+Every rule below was paid for in a real incident: a flaky-looking test that was
+actually a real regression, a "green" suite that shipped a dead button, a smoke
+run that passed against a dev server no user ever touches. Determinism is not a
+style preference — it is what makes a passing suite mean something.
+
+This file is **yours to edit**. Arbiter installs it once and never overwrites
+your changes on re-run (see `docs/GOVERNANCE/FRONTEND_CONSTITUTION.md` for the
+same customizable-install contract, if present in this repo).
+
+---
+
+## The 10 rules
+
+1. **Selectors: testid-contract only.** No CSS class, XPath, or visible-text
+   selectors. A test that breaks because a label changed is not testing
+   behavior — it is testing copy.
+
+2. **Fake clock, installed before the first navigation.** Every spec that
+   touches a date/time-dependent flow installs a fake clock *before* the first
+   `page.goto()`. Real wall-clock time in a spec is a race waiting to happen.
+
+3. **Future-only dates.** Never hardcode a past date into a form or fixture
+   validated by the app under test. Use a dynamic (`now + N`) or fixed
+   far-future date. A past date silently rotting into "invalid" is a recurring
+   failure class, not a one-off.
+
+4. **Dedicated seed per spec.** Each spec provisions and owns its data. No
+   spec reads or mutates a fixture shared with another spec — shared mutable
+   state is how "flaky" tests are born.
+
+5. **Deterministic external providers.** Any third-party or network dependency
+   (payment, weather, geocoding, email, …) is stubbed with a fixed payload in
+   CI. No live external call ever gates a merge.
+
+6. **No `sleep` / no `waitForTimeout`.** Wait on an explicit condition — a
+   network response, a DOM state, a testid becoming visible. A fixed sleep is
+   either too short (flaky) or too long (slow), never both right.
+
+7. **Zero-retry `@smoke` tier (INV-130, #1817 A3).** The `@smoke` tier runs
+   with **zero** retries — `retryLadder({ tier: "smoke" })` force-truncates the
+   ladder to a single attempt, non-bypassably. Retries hide races; `@smoke`
+   exists specifically to catch them. Non-smoke tiers may still retry.
+
+8. **Quarantine annotates, never suppresses (INV-130, #1817 A3).** A known-
+   flaky test may be quarantined — owner, linked issue, and a TTL — but it
+   still runs and still reports. An entry that is incomplete or past its TTL
+   fails closed (`scripts/check-e2e-quarantine.mjs`).
+   Quarantine is a spotlight, not a mute button.
+
+9. **No skip without an issue and a TTL.** A bare `test.skip(...)` is a gate
+   violation. Every skip carries a linked issue and an expiry — an
+   unaccountable skip rots into a permanent blind spot no one remembers.
+
+10. **Smoke runs against the built artifact.** The `@smoke` tier exercises the
+    actual production build, not a dev server. A dev-server-only green suite
+    can ship a build that is broken in ways the dev server never shows.
+
+---
+
+## Enforcement pointers
+
+- Rules 7–8 are mechanically enforced: `scripts/check-e2e-quarantine.mjs`
+  (Track-B, generated) and `DISC-e2e-quarantine`
+  (`src/conformance/dimensions.ts`, Track-A).
+- Rules 1–6, 9–10 are process discipline — reviewed at PR time, not (yet)
+  mechanically gated. A future gate absorbing one of these into a script
+  should link back here, not duplicate the rationale.

package/dist/templates/e2e/playwright-python/conftest.py.ejs

@@ -0,0 +1,22 @@
+# pytest-playwright conftest — #366 (CANON-02/03).
+#
+# E2E_BASE_URL overrides the default for CI / non-localhost targets.
+# Pair with scripts/lib/ephemeral-server.mjs (#358): the runner brings up
+# the server, then invokes `pytest tests/e2e`, which picks up these fixtures.
+
+import os
+
+import pytest
+from playwright.sync_api import Page
+
+
+@pytest.fixture(scope="session")
+def base_url() -> str:
+    return os.environ.get("E2E_BASE_URL", "http://localhost:8000")
+
+
+@pytest.fixture
+def page(page: Page) -> Page:
+    # Re-export the pytest-playwright `page` fixture so tests can request it
+    # without importing it from the plugin namespace directly.
+    return page

package/dist/templates/e2e/playwright-python/run_axe.py.ejs

@@ -0,0 +1,99 @@
+# a11y axe-playwright-python wrapper — INV-61 (#1149, CANON-02).
+#
+# Threshold policy (mirrors run-axe.ts, deliberate — not negotiable without
+# an INV revision):
+#   - HARD-raise on impact == 'critical'
+#   - HARD-raise on unclassified impact (None) — never silently pass
+#   - LOG without raise on serious / moderate / minor — captured as evidence
+#
+# Downstream projects may ratchet stricter (e.g. raise on 'serious') by
+# extending or replacing this helper. They may NOT loosen it without recording
+# a project-level exception that cites INV-61.
+#
+# Tag set: full WCAG 2.2 AA — wcag2a + wcag2aa + wcag21a + wcag21aa + wcag22aa.
+# Covers: target-size (2.5.8), focus-appearance (2.4.11), accessible-auth (3.3.8).
+# WCAG 2.2 AA is the 2026 baseline — do NOT drop to wcag2a+wcag2aa only.
+#
+# Minimum version: axe-playwright-python>=0.1.7 (bundles axe-core >=4.5.0, which
+# introduced the wcag22aa tag). Older versions silently ignore wcag22aa and yield
+# false-negative passes — pin the version in requirements.txt / pyproject.toml.
+#
+# Must use sync_playwright.Axe — pytest-playwright's `page` fixture is
+# synchronous. Swapping to async_playwright.Axe without await produces a
+# coroutine object instead of AxeResults and raises AttributeError.
+
+import warnings
+from typing import TYPE_CHECKING
+
+from axe_playwright_python.sync_playwright import Axe
+
+if TYPE_CHECKING:
+    from playwright.sync_api import Page
+
+# Instantiate once — re-reading axe.min.js per-call is wasteful.
+_AXE = Axe()
+
+_A11Y_OPTIONS = {
+    "resultTypes": ["violations"],
+    "runOnly": {
+        "type": "tag",
+        "values": ["wcag2a", "wcag2aa", "wcag21a", "wcag21aa", "wcag22aa"],
+    },
+}
+
+_HARD_FAIL_IMPACTS = {"critical"}
+
+
+def run_axe(page: "Page", label: str) -> None:
+    """Run axe-core against the current page and enforce INV-61.
+
+    Raises on critical violations or unclassified (None) impact.
+    Logs serious / moderate / minor violations without raising.
+    """
+    results = _AXE.run(page, options=_A11Y_OPTIONS)
+    response = results.response
+    if "violations" not in response:
+        raise AssertionError(
+            f"[a11y][{label}] axe response missing 'violations' key — "
+            "check axe-playwright-python version (>=0.1.7 required). "
+            f"Keys present: {list(response.keys())}"
+        )
+    violations = response["violations"]
+
+    hard_failures = []
+    unclassified = []
+    soft = []
+
+    for v in violations:
+        impact = v.get("impact")
+        if impact is None:
+            unclassified.append(v)
+        elif impact in _HARD_FAIL_IMPACTS:
+            hard_failures.append(v)
+        else:
+            soft.append(v)
+
+    for v in soft:
+        impact_label = v.get("impact", "?")
+        warnings.warn(
+            f"[a11y][{label}] {impact_label}: {v.get('id')} — {v.get('help')}",
+            stacklevel=2,
+        )
+
+    # Merge both failure categories into one raise so all violations surface
+    # in a single error report (not just the first category encountered).
+    if hard_failures or unclassified:
+        parts = []
+        if hard_failures:
+            parts.append(
+                "critical: "
+                + ", ".join(
+                    f"{v.get('id')} ({len(v.get('nodes', []))} node(s))"
+                    for v in hard_failures
+                )
+            )
+        if unclassified:
+            parts.append(
+                "unclassified: " + ", ".join(v.get("id", "?") for v in unclassified)
+            )
+        raise AssertionError(f"[a11y][{label}] INV-61: {'; '.join(parts)}")