Plan: claude-quickstart Alignment

## Known Agent Biases

AI agents trend toward recommending older, heavily-documented tools over newer, better alternatives. When making architectural recommendations, always perform web research for current state of the art (see delivery-protocol.md). Known stale defaults to watch for:

- OpenSSL over rustls (rustls is mandated — see `deny.toml`)
- Selenium/Cypress over Playwright (Playwright is mandated for E2E)
- `reqwest` with `openssl-sys` over `reqwest` with `rustls-tls` feature
- `chrono` over `jiff` or `time` (evaluate current state before choosing)
- Heavyweight ORMs over lightweight query builders
- Class-based or inheritance-heavy patterns over composition and traits

This list is a living document. When you catch an outdated recommendation, add it here.

## ADR Conventions

Architecture Decision Records document non-obvious architectural choices:

- Location: `docs/modules/ROOT/pages/adrs/` (AsciiDoc format)
- Write an ADR when: choosing a framework, database, protocol, or design pattern that has viable alternatives
- Format: Status, Context, Decision, Consequences
- ADRs are immutable once accepted — supersede with a new ADR, do not edit

## Critical Rules

1. **Never dismiss test failures as transient** — investigate root cause. Only classify as edge case after thorough analysis.
2. **All checks must pass before push** — fmt, clippy, tests (enforced by hook)
3. **Test results in `test-results/`** — check this directory for failure context before investigating
4. **Never weaken a test to make code pass** — fix the code, not the test. Specifically:
   - Never delete, skip, or `#[ignore]` a test to make CI pass
   - Never loosen assertions (e.g., `assert_eq!` → `assert!`, widening tolerance, removing checks) to accommodate broken code
   - Never change expected values to match wrong output
   - The ONLY reason to modify a test is if the test itself is genuinely incorrect — and that must be explained in the commit message
5. **All test types produce JUnit XML** — unit, integration, and E2E tests all output to `test-results/`

[profile.default]
fail-fast = false
slow-timeout = { period = "60s", terminate-after = 2 }

[profile.integration]
fail-fast = false
slow-timeout = { period = "120s", terminate-after = 2 }
junit = { path = "../../test-results/integration/results.xml" }

[profile.ci]
fail-fast = false
junit = { path = "../../test-results/unit/results.xml" }

# Enforce LF line endings for all text files
* text=auto eol=lf

# Existing LFS rules
docs/modules/ROOT/images/screenshots/*.png filter=lfs diff=lfs merge=lfs -text

# CRAIG Development Environment
# Copy to .env and fill in values

# Service ports (defaults shown — only override if port conflict)
# CRAIG_RULES__PORT=8001
# CRAIG_CASES__PORT=8002
# CRAIG_PLACEMENT__PORT=8003
# CRAIG_EXCHANGE__PORT=8004
# CRAIG_FINANCIAL__PORT=8005
# CRAIG_REPORTING__PORT=8006
# CRAIG_SECURITY__PORT=8007
# CRAIG_INTAKE__PORT=8008
# CRAIG_WEB__PORT=8080

# Keycloak (devstack defaults)
# CRAIG_WEB__OIDC_ISSUER=http://host.docker.internal:8180/realms/craig
# CRAIG_WEB__KEYCLOAK_CLIENT_ID=craig-ui

# Session (MUST change in production)
CRAIG_WEB__SESSION_SECRET=change-me-in-production-use-64-random-chars

# CORS (restrict in production)
# CRAIG_RULES__CORS_ORIGINS=*

# Seed data
CRAIG_SEED=42
CRAIG_FAMILIES=12

## Architectural Recommendations

Before recommending a new dependency, framework, library, or architectural pattern:

1. **Research current state of the art** — search crates.io, official docs, and recent release notes. Do not rely on training data alone.
2. **Identify at least 3 alternatives** — including the option you are inclined toward.
3. **Compare on**: maintenance activity (last release date, commit frequency), community adoption, security posture, alignment with existing project conventions (pure Rust, musl-compatible, AGPL-compatible license).
4. **Present the comparison** to the user before proceeding — do not unilaterally choose.
5. **Document the decision** in an ADR if it introduces a new architectural choice.

AI agents trend toward recommending older, heavily-documented tools over newer, better alternatives because training data favors established projects. This process exists to counteract that bias.

## Container Runtime

- **Alpine is mandatory** for all container images (build and runtime stages)
- Build stage: `rust:1.94-alpine` (current), runtime stage: `alpine:latest`
- All images must run as non-root user, include HEALTHCHECK, use multi-stage builds
- `.dockerignore` excludes `target/`, `.git/`, `node_modules/`
- Alpine uses musl — use `rustls` (not `openssl`) for TLS. The `openssl` crate is banned in `deny.toml`.

## Dependency Management

- Use latest stable versions. Pin to non-latest only with documented reason.
- Workspace-level dependency management (`[workspace.dependencies]`)
- `cargo deny` for license allowlist (AGPL-compatible), duplicate detection, advisory DB
- `cargo audit` in CI (blocking)
- Monthly dependency review: `cargo update` + full test verification

## Task Runner

- **`cargo xtask` is the mandatory task runner** for all project automation
- No shell scripts for project automation — use xtask instead
- Standard subcommands: `dev`, `test`, `e2e`, `validate`, `check-docs`
- Project-specific: `seed`, `screenshots`