docs(13): capture phase context

2026-06-11 18:28:58 -04:00
parent 234384c142
commit 8fbc68f993
2 changed files with 205 additions and 0 deletions
@@ -0,0 +1,91 @@
+# Phase 13: Real Lint Gate (ESLint) - Discussion Log
+
+> **Audit trail only.** Do not use as input to planning, research, or execution agents.
+> Decisions are captured in CONTEXT.md — this log preserves the alternatives considered.
+
+**Date:** 2026-06-11
+**Phase:** 13-real-lint-gate-eslint
+**Areas discussed:** Rule strictness, Existing-violation strategy, Prettier scope, Lint file coverage
+
+---
+
+## Rule Strictness — ruleset
+
+| Option | Description | Selected |
+|--------|-------------|----------|
+| `recommended` (non-type-aware) | Syntactic only, fast, no tsconfig wiring; misses async/promise bugs | |
+| `recommendedTypeChecked` | Type-aware; catches floating/misused promises + unsafe any; needs projectService, slower, more first-run violations | ✓ |
+| `strict`/`strictTypeChecked` | Maximal rules; heavy churn + bikeshed risk | |
+
+**User's choice:** `recommendedTypeChecked`
+**Notes:** Motivated by async-heavy backend (outbox/push/reminder schedulers). projectService: true.
+
+## Rule Strictness — gate threshold
+
+| Option | Description | Selected |
+|--------|-------------|----------|
+| `--max-warnings 0` | Any warning fails CI; every rule is error-or-off | ✓ |
+| Errors only | Warnings surface but don't fail; softer rollout, accumulation risk | |
+| You decide | Pick based on first-run count | |
+
+**User's choice:** `--max-warnings 0`
+
+---
+
+## Existing-Violation Strategy
+
+| Option | Description | Selected |
+|--------|-------------|----------|
+| Fix all violations now | Phase green across both apps; real bugs fixed; larger phase | ✓ |
+| Minimal green ruleset, ratchet later | Enable only passing rules; small phase, weaker gate, deferred work | |
+| Baseline file (snapshot + ratchet) | Snapshot current violations as accepted; new-only fails; extra tooling | |
+
+**User's choice:** Fix all violations now
+**Notes:** Hard constraint added (D-13-06): fixes must address the violation, not mask it — no blanket eslint-disable, no `void` to silence floating promises; suppressions need justifying comments.
+
+---
+
+## Prettier Scope
+
+| Option | Description | Selected |
+|--------|-------------|----------|
+| `eslint-config-prettier` only | Disable conflicting format rules, no Prettier itself; phase stays ESLint-only | |
+| Add Prettier + format gate too | Full lint+format; scope creep beyond goal; reformats all files now | ✓ |
+| Defer Prettier entirely | ESLint only, no config-prettier; future conflict risk | |
+
+**User's choice:** Add Prettier + format gate too
+**Notes:** Expands ROADMAP Phase 13 goal ("ESLint only") — flagged for planning to update ROADMAP one-liner + success criteria. Follow-up decided wiring: standalone `prettier --check` + eslint-config-prettier (rejected eslint-plugin-prettier).
+
+### Prettier wiring (follow-up)
+
+| Option | Description | Selected |
+|--------|-------------|----------|
+| Standalone + config-prettier | Separate `prettier --check` CI step + eslint-config-prettier off-switch; clean separation | ✓ |
+| eslint-plugin-prettier | Prettier as an ESLint rule; one gate, slower/noisier, discouraged | |
+
+**User's choice:** Standalone + eslint-config-prettier
+
+---
+
+## Lint File Coverage
+
+| Option | Description | Selected |
+|--------|-------------|----------|
+| All TS/TSX: src + tests + e2e + configs | Most thorough; needs projectService + config-file override; more first-run fixes | ✓ |
+| src/ + tests, skip configs | Simpler, configs unchecked | |
+| src/ only | Smallest scope; tests + e2e harness + configs unlinted | |
+
+**User's choice:** All TS/TSX (src + tests + e2e + configs)
+**Notes:** Config files need a non-type-checked override block (D-13-10).
+
+---
+
+## Claude's Discretion
+
+- Flat-config file layout (single root vs per-app)
+- Exact `.prettierrc` options (standard defaults)
+- CI step ordering within `fast-checks`
+
+## Deferred Ideas
+
+None — Prettier was folded into scope, not deferred. Reviewed-but-not-folded: the Phase 8 Gitea-CI todo (already complete, matched on shared keywords only).