@getarbiter/cli 0.5.0

package/dist/templates/docs/bugs/bug-analysis.md.ejs

@@ -0,0 +1,47 @@
+# Bug Analysis — <%= projectName %>
+
+_Generated by arbiter. Structured root-cause analysis. The goal is to move from
+"it's broken" to a single, evidenced root cause **before** writing any fix._
+
+> Companion to the auto-captured `.evidence/<task>/DEBUG_STATE.md` written by the
+> `debug-state-on-failure` hook when a gate/test command fails. Pull its
+> Command / Output / History into the sections below.
+
+## 1. Reproduction (confirmed)
+
+- [ ] Reproduced locally on a clean checkout
+- [ ] Minimal reproduction isolated (smallest input that triggers it)
+
+```
+# minimal repro command / input
+```
+
+## 2. Hypotheses
+
+List candidate causes, then rule each in or out with evidence. Do not stop at the
+first plausible one.
+
+| # | Hypothesis | Evidence for | Evidence against | Verdict |
+| - | ---------- | ------------ | ---------------- | ------- |
+| 1 | _…_        | _…_          | _…_              | ruled in/out |
+| 2 | _…_        | _…_          | _…_              | ruled in/out |
+
+## 3. Root Cause
+
+State the single root cause, supported by the evidence above. Distinguish the
+**root cause** (why it happened) from the **symptom** (what the user saw). A fix
+that only addresses the symptom is a stop condition — record tech debt or fix the
+cause.
+
+## 4. Blast Radius
+
+- Other code paths that share this root cause: _…_
+- Tests that *should* have caught it but didn't: _…_ (this gap is part of the fix)
+
+## 5. Fix Strategy
+
+- Root-cause fix: _…_
+- Regression test to add first (TDD red): _path + assertion_
+- Out of scope: _…_
+
+→ Once fixed, verify via `docs/bugs/bug-verification.md`.

package/dist/templates/docs/bugs/bug-report.md.ejs

@@ -0,0 +1,51 @@
+# Bug Report — <%= projectName %>
+
+_Generated by arbiter. The intake template: capture a bug precisely enough that
+anyone (human or agent) can reproduce it without asking follow-up questions._
+
+> Copy this file to `docs/bugs/<short-slug>.md` per bug, or paste into the issue
+> tracker. One report = one bug.
+
+## Summary
+
+One sentence: what is broken, for whom.
+
+## Environment
+
+| Field        | Value |
+| ------------ | ----- |
+| Version / SHA | _…_  |
+| Platform / OS | _…_  |
+| Config / level | _…_ |
+
+## Steps to Reproduce
+
+1. _…_
+2. _…_
+3. _…_
+
+A bug without reliable reproduction steps is a hypothesis, not a bug. If
+reproduction is intermittent, state the frequency and any correlating signal.
+
+## Expected Behaviour
+
+What *should* have happened, and why (cite the spec / steering doc / test that
+defines the contract).
+
+## Actual Behaviour
+
+What happened instead. Paste the exact error, log line, or screenshot — not a
+paraphrase.
+
+## Impact / Severity
+
+| Severity | Definition | This bug |
+| -------- | ---------- | -------- |
+| Critical | data loss / security / outage | ☐ |
+| High     | core flow broken, no workaround | ☐ |
+| Medium   | degraded, workaround exists | ☐ |
+| Low      | cosmetic / minor | ☐ |
+
+## Next Step
+
+Route to triage → see `docs/bugs/bug-analysis.md`.

package/dist/templates/docs/bugs/bug-verification.md.ejs

@@ -0,0 +1,42 @@
+# Bug Verification — <%= projectName %>
+
+_Generated by arbiter. The closing step: prove the fix works, prove it stays fixed,
+and prove nothing else broke. A bug is not closed until this checklist is green._
+
+> Evidence trail: the `debug-state-on-failure` hook records failed gate/test runs
+> to `.evidence/<task>/DEBUG_STATE.md`. Reference that file here — the transition
+> from FAIL entries to a passing run is the durable proof the fix landed.
+
+## 1. Regression Test First
+
+- [ ] A test that **fails on the buggy code** was written (TDD red) and committed
+- [ ] The same test **passes on the fixed code** (TDD green)
+- [ ] Test path: `_…_`
+
+Without a test that failed before the fix, you have not verified the fix — you
+have asserted it.
+
+## 2. Fix Verified
+
+- [ ] Original reproduction steps no longer trigger the bug
+- [ ] The root cause from `bug-analysis.md` is addressed (not just the symptom)
+- [ ] Blast-radius siblings (other paths sharing the cause) checked
+
+## 3. No Regression
+
+- [ ] Full gate green: `node scripts/check-all.mjs L2`
+- [ ] Coverage did not drop below the threshold for the touched files
+- [ ] `.evidence/<task>/DEBUG_STATE.md` shows the final command passing
+
+## 4. Evidence
+
+| Artifact | Location |
+| -------- | -------- |
+| Failing-then-passing test | _path_ |
+| Gate run output | _paste / link_ |
+| DEBUG_STATE history | `.evidence/<task>/DEBUG_STATE.md` |
+
+## 5. Close-Out
+
+- [ ] Root cause and fix summarised in the PR / issue
+- [ ] Follow-up tech debt (if any symptom-only mitigation remained) recorded with a task ID

package/dist/templates/docs/runbooks/deployment.md.ejs

@@ -0,0 +1,119 @@
+# Deployment Runbook — <%= projectName %>
+
+_Generated by arbiter. Update steps to match your deployment platform._
+
+## Overview
+
+| Field | Value |
+|-------|-------|
+| Service | `<%= projectName %>` |
+| Normal deploy time | ~5 min (container swap) |
+| Rollback time | ~2 min (revision rollback) |
+| Rollback runbook | `docs/runbooks/rollback.md` |
+
+---
+
+## § 1 — Pre-Deployment
+
+Complete the PROD checklist (`docs/runbooks/prod-checklist.md`) before proceeding.
+
+```bash
+# Confirm gate is green on the release branch
+node scripts/check-all.mjs L2
+```
+
+---
+
+## § 2 — Build & Tag
+
+```bash
+# Build and tag the release image
+# (substitute with your CI system or container build command)
+docker build -t <registry>/<%= projectName %>:<version> .
+docker push <registry>/<%= projectName %>:<version>
+```
+
+If your CI pipeline builds the image automatically on tag push:
+
+```bash
+git tag v<version>
+git push origin v<version>
+```
+
+---
+
+## § 3 — Deploy
+
+### Option A — CI/CD Pipeline (preferred)
+
+Trigger the release workflow in your CI system with the target version:
+- GitHub Actions: workflow dispatch or tag push triggers release job
+- Azure DevOps / Jenkins / other: see your pipeline configuration
+
+### Option B — Manual Deploy (break-glass)
+
+```bash
+# Azure Container Apps
+az containerapp update \
+  --name <app-name> \
+  --resource-group <rg> \
+  --image <registry>/<%= projectName %>:<version>
+
+# Kubernetes
+kubectl set image deployment/<deployment-name> \
+  <container-name>=<registry>/<%= projectName %>:<version>
+kubectl rollout status deployment/<deployment-name>
+```
+
+---
+
+## § 4 — Post-Deployment Verification
+
+```bash
+# Health probes
+curl -sf https://<host>/health/liveness  | jq .
+curl -sf https://<host>/health/readiness | jq .
+
+# Confirm the deployed version
+curl -sf https://<host>/health | jq '.version // .info.version'
+```
+
+Expected: HTTP 200, `{"status": "UP"}`, version matches target tag.
+
+Wait 2–3 minutes after deployment before declaring success (allow metrics to stabilise).
+
+---
+
+## § 5 — Smoke Test
+
+Run critical path smoke tests against production:
+
+```bash
+# Replace with your smoke test command
+# e.g. node scripts/smoke.mjs --env=prod
+```
+
+Manual smoke tests (minimum):
+- [ ] Service responds at base health URL
+- [ ] Authentication flow succeeds
+- [ ] One read and one write operation succeed end-to-end
+
+---
+
+## § 6 — Rollback Trigger Criteria
+
+Initiate rollback (`docs/runbooks/rollback.md`) if:
+
+- Error rate > 5× baseline within 5 minutes of deployment
+- Health probes fail for > 60 seconds
+- Critical user flow fails smoke test
+- P99 latency > 3× baseline sustained for > 2 minutes
+
+---
+
+## § 7 — Post-Deployment
+
+- [ ] Alert on-call engineer deployment is complete
+- [ ] Update deployment ticket with version and timestamp
+- [ ] Monitor dashboards for 15 minutes after deployment
+- [ ] Close deployment ticket if no issues observed

package/dist/templates/docs/runbooks/prod-checklist.md.ejs

@@ -0,0 +1,90 @@
+# PROD Environment Checklist — <%= projectName %>
+
+_Generated by arbiter. Complete before every production deployment._
+
+> **Purpose**: Pre-deployment verification. Deliver to the DevOps/Infra team before go-live.
+
+---
+
+## § 1 — Code & Build
+
+- [ ] All acceptance criteria on the deployment ticket are closed
+- [ ] PR reviewed and approved (minimum 2 reviewers for L3 governance)
+- [ ] Gate passes: `node scripts/check-all.mjs L2` exits 0
+- [ ] Build artifact tagged with the release version (e.g., `v1.2.3`)
+- [ ] No critical or high CVEs in `npm audit` / `mvn verify` / equivalent
+
+---
+
+## § 2 — Database / Migrations
+
+- [ ] Migration files committed alongside application code
+- [ ] Migration runs successfully on a staging DB snapshot
+- [ ] Rollback migration documented and tested (if schema change)
+- [ ] No irreversible DDL (DROP COLUMN, TRUNCATE) without backup confirmed
+
+---
+
+## § 3 — Configuration & Secrets
+
+- [ ] All required environment variables documented in `.env.example`
+- [ ] Secrets provisioned in secret manager (not hardcoded or in version control)
+- [ ] Config drift check: staging config matches production template
+- [ ] Health check URLs configured for liveness/readiness probes
+
+---
+
+## § 4 — Infrastructure
+
+- [ ] Container image built from tagged commit (not from `main` HEAD)
+- [ ] Container registry access verified (pull secret / service account)
+- [ ] CPU and memory limits set appropriately for expected load
+- [ ] Autoscaling rules configured (min/max replicas)
+- [ ] Load balancer / reverse proxy config updated if routing changed
+
+---
+
+## § 5 — Observability
+
+- [ ] Structured logging in place (no raw print statements)
+- [ ] Log level set to INFO in production (DEBUG disabled)
+- [ ] Error alerting configured (alert fires within 2 min of error spike)
+- [ ] Dashboards exist: latency, traffic, error rate, saturation (4 golden signals)
+- [ ] Distributed tracing propagates correlation IDs across service calls
+
+---
+
+## § 6 — Security
+
+- [ ] `gitleaks detect` passes (no secrets in code)
+- [ ] PII scan passes: `node scripts/pii-scan.mjs`
+<% if (isL3Plus) { %>
+- [ ] STRIDE threat model reviewed for changes to auth/external boundaries
+- [ ] Pen test scope updated if new endpoints added
+- [ ] Data classification confirmed (does this release touch PII/financial data?)
+<% } %>
+
+---
+
+## § 7 — Deployment Execution
+
+- [ ] Maintenance window communicated (if applicable)
+- [ ] Rollback plan confirmed (see `docs/runbooks/rollback.md`)
+- [ ] On-call engineer available during deployment
+- [ ] Deployment proceeds → verify health probes within 5 min
+- [ ] Smoke test critical user flows after deployment
+
+---
+
+## § 8 — Go / No-Go Gate
+
+| Check | Status |
+|-------|--------|
+| All §1–§6 items checked | [ ] |
+| Staging smoke test passed | [ ] |
+| On-call engineer briefed | [ ] |
+| Rollback path confirmed | [ ] |
+
+**Decision**: [ ] GO &nbsp;&nbsp; [ ] NO-GO
+
+Authorised by: `[NAME]` &nbsp;&nbsp; Date: `[DATE]`

package/dist/templates/docs/runbooks/rollback.md.ejs

@@ -0,0 +1,124 @@
+# Rollback Runbook — <%= projectName %>
+
+_Generated by arbiter. Update to reflect your deployment platform and rollback strategy._
+
+## Decision Tree — Rollback vs Fix-Forward
+
+Before executing a rollback, use this decision tree:
+
+```
+Is the issue data corruption?
+├── YES → Rollback immediately. Data integrity > availability.
+└── NO →
+    Is the bug causing complete service unavailability?
+    ├── YES →
+    │   Can the previous revision handle current load?
+    │   ├── YES → Container revision rollback (§2). DB rollback only if schema broke.
+    │   └── NO  → Fix-forward + scale up. Rollback would just move the problem.
+    └── NO (degraded but functional) →
+        Is a fix deployable within 30 minutes?
+        ├── YES → Fix-forward. Deploy hotfix PR.
+        └── NO  → Rollback (§2). DB schema rollback rarely needed for logic bugs.
+```
+
+**Rule of thumb**: rollback is fast and reversible — prefer it when uncertain.
+DB schema rollback is irreversible for data; plan carefully.
+
+---
+
+## § 1 — Prerequisites
+
+- [ ] Access to deployment platform (CI/CD, container registry, or platform console)
+- [ ] Confirmation of the last known-good version/tag/SHA
+- [ ] Alert channel open (Slack, PagerDuty, or equivalent)
+- [ ] At least one team member aware that rollback is in progress
+
+---
+
+## § 2 — Container Revision Rollback
+
+### Step 1: Identify the target revision
+
+```bash
+# List recent deployments / revisions
+# (substitute with your platform's equivalent)
+# Example: Azure Container Apps
+az containerapp revision list --name <app-name> --resource-group <rg> \
+  --query "[].{name:name,active:properties.active,createdAt:systemData.createdAt}" \
+  --output table
+
+# Example: Kubernetes
+kubectl rollout history deployment/<deployment-name>
+```
+
+### Step 2: Activate the target revision
+
+```bash
+# Azure Container Apps — activate a specific revision
+az containerapp revision activate --name <app-name> --resource-group <rg> \
+  --revision <revision-name>
+
+# Then deactivate the bad revision
+az containerapp revision deactivate --name <app-name> --resource-group <rg> \
+  --revision <bad-revision-name>
+
+# Kubernetes — rollback to previous
+kubectl rollout undo deployment/<deployment-name>
+
+# Kubernetes — rollback to specific revision
+kubectl rollout undo deployment/<deployment-name> --to-revision=<N>
+```
+
+### Step 3: Verify health
+
+```bash
+# Check liveness / readiness probes
+curl -sf https://<host>/health/liveness  | jq .
+curl -sf https://<host>/health/readiness | jq .
+
+# Tail logs for errors
+# (substitute with your platform's log command)
+```
+
+---
+
+## § 3 — Database Schema Rollback
+
+> **WARNING**: Schema rollbacks can destroy data. Proceed only when data corruption is confirmed or a schema change caused the outage.
+
+- [ ] Identify the migration that introduced the issue
+- [ ] Confirm a rollback migration exists or can be safely crafted
+- [ ] Back up the current database before any DDL change
+- [ ] Apply the rollback migration in the migration tool
+
+```bash
+# Example: Flyway
+./mvnw flyway:undo
+
+# Example: Liquibase
+liquibase rollbackCount 1
+
+# Example: alembic (Python)
+alembic downgrade -1
+```
+
+---
+
+## § 4 — Post-Rollback Checklist
+
+- [ ] Liveness and readiness probes GREEN
+- [ ] Error rate returned to baseline (check dashboards)
+- [ ] Alert channel updated with rollback status
+- [ ] Incident ticket opened (include: timeline, cause hypothesis, rollback steps taken)
+- [ ] Follow-up PR opened to fix the root cause and re-deploy
+
+---
+
+## § 5 — Anti-Patterns
+
+| Anti-Pattern | Why It Fails |
+|---|---|
+| Rolling back DB schema without backup | Irreversible data loss |
+| Partial rollback (app only, not config) | Config drift causes silent failures |
+| Rolling back without checking traffic | Rollback may not reduce load spike |
+| Skipping post-rollback health check | Leaves team in uncertainty |

package/dist/templates/docs/runbooks/troubleshooting.md.ejs

@@ -0,0 +1,130 @@
+# Troubleshooting Runbook — <%= projectName %>
+
+_Generated by arbiter. Update symptom table for your service._
+
+## § 1 — Health & Smoke Check
+
+Verify the service is alive before any investigation.
+
+```bash
+# Liveness + readiness probes
+curl -sf https://<host>/health/liveness  | jq .
+curl -sf https://<host>/health/readiness | jq .
+
+# Full health (includes dependency indicators)
+curl -sf https://<host>/health | jq .
+```
+
+Expected response: HTTP 200 with `{"status": "UP"}`.
+
+---
+
+## § 2 — Symptom-Based Diagnosis
+
+| Symptom | Likely Cause | First Action |
+|---------|-------------|--------------|
+| 503 / connection refused | Service not running | Check process / container status |
+| 500 Internal Server Error | Bug in request path | Check application logs |
+| Slow responses (p99 > SLA) | DB / cache contention | Check DB connections, slow query log |
+| Authentication failures | Token config mismatch | Verify auth provider and client config |
+| High memory / OOM kill | Memory leak | Heap dump + restart; profile offline |
+| Message queue backlog | Consumer stopped | Restart consumer; check dead-letter queue |
+| Dependency unhealthy | External service down | Check third-party status page |
+
+---
+
+## § 3 — Log Investigation
+
+```bash
+# Application logs (substitute with your platform)
+# Azure Container Apps
+az containerapp logs show --name <app-name> --resource-group <rg> --follow
+
+# Kubernetes
+kubectl logs -f deployment/<deployment-name> --tail=100
+
+# Filter for errors
+# ... | grep -E "ERROR|Exception|WARN"
+```
+
+Common log patterns to look for:
+
+- `Connection refused` → database or cache not reachable
+- `Timeout` → slow query or overloaded dependency
+- `OutOfMemoryError` → heap exhaustion
+- `NullPointerException` / `TypeError` → code bug in request path
+
+---
+
+## § 4 — Database Checks
+
+```bash
+# Check active connections
+# PostgreSQL
+psql -c "SELECT count(*), state FROM pg_stat_activity GROUP BY state;"
+
+# Check for long-running queries (>30s)
+psql -c "SELECT pid, now() - query_start AS duration, query FROM pg_stat_activity WHERE state = 'active' AND now() - query_start > interval '30 seconds';"
+
+# Kill a blocking query
+psql -c "SELECT pg_terminate_backend(<pid>);"
+```
+
+---
+
+## § 5 — Cache / Queue Checks
+
+```bash
+# Redis — check memory and connected clients
+redis-cli info memory | grep used_memory_human
+redis-cli info clients | grep connected_clients
+
+# RabbitMQ / SQS — check queue depth (substitute with your tool)
+# For RabbitMQ: use Management UI → Queues tab
+# For AWS SQS: aws sqs get-queue-attributes ...
+```
+
+---
+
+## § 6 — Escalation Path
+
+1. **L1** — On-call engineer: identify symptom, check dashboards
+2. **L2** — Service owner: root-cause analysis, hotfix or rollback decision
+3. **L3** — Platform / infra team: if infrastructure-level issue
+
+Escalation contacts: `[FILL IN]`
+
+---
+
+## § 7 — Recovery Actions by Category
+
+### Application crash / restart loop
+
+```bash
+# Force restart the container / pod
+# Azure Container Apps
+az containerapp revision restart --name <app-name> --resource-group <rg>
+
+# Kubernetes
+kubectl rollout restart deployment/<deployment-name>
+```
+
+### Database connection pool exhausted
+
+1. Restart the application to release connections
+2. Investigate active connection count
+3. Tune pool size if demand legitimately increased
+
+### Circuit breaker open
+
+1. Identify which downstream service triggered the circuit breaker
+2. Verify downstream service health
+3. Circuit will close automatically after cooldown period (or restart app to force reset)
+
+---
+
+## § 8 — Post-Incident
+
+- [ ] Write incident retrospective (within 48h)
+- [ ] Create follow-up tickets for root cause fixes
+- [ ] Update this runbook with any new symptoms/remedies discovered

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

@@ -0,0 +1,46 @@
+# <%= title %>
+
+_Arc42 Canvas — single-page architecture overview. Right-sized for a solo/small team: expand to
+the full arc42 (`arc42-full`) once the `>2 deployable units` trigger fires._
+
+## 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
+
+<!-- Who/what this system talks to (users, other systems, external APIs). One diagram or list. -->
+
+## Constraints
+
+<!-- Technical, organizational, or regulatory constraints that shaped the design. -->
+
+## Solution strategy
+
+<!-- The 3-5 top-level decisions (stack, architecture style, key patterns) and why. -->
+
+## Building blocks
+
+<!-- The main components/modules and their responsibilities — one level of decomposition. -->
+
+## Runtime
+
+<!-- The 1-3 most important runtime scenarios (request flow, background job, failure path). -->
+
+## Deployment
+
+<!-- Where this runs (environments, infra), and how a change reaches production. -->
+
+## Decisions
+
+<!-- Link to docs/ADR — do not duplicate rationale here, point at the record. -->
+
+## Quality
+
+<!-- The quality attributes that matter most (perf, security, availability) and how they're met. -->
+
+## Risks
+
+<!-- Known architectural risks or technical debt with an outsized blast radius. -->