# Decision — pgFormatter on Windows dev (Q.HARD.002 / Audit P3 carryforward)

> **Date:** 2026-05-14
> **Status:** carryforward `[FIX-DEFER]` — accepted as known-deferred technical-tooling gap
> **Raised in:** Portal Full Audit #2 (Q.HARD.002), confirmed in Audit #3 Phase 1D
> **Related findings:** Audit #3 `findings.md` Phase 1D — «pgFormatter perl-not-in-PATH carryforward»

## Context

`npm run format:sql:check` falls on the Windows dev VM because the `perl`
interpreter is not on the system PATH. pgFormatter (`bin/pgFormatter/pg_format`)
is a Perl script and physically present in the repository, but cannot execute
without a Perl runtime.

`db/schema.sql` formatting was inherited from the original delivery; we
have not re-formatted it since. The auditor flagged a probable formatting
diff of ~6284 lines (handoff baseline measurement), but cannot quantify it
on this machine without resolving the Perl issue.

## Decision rationale (3-hypothesis comparison)

1. **`choco install strawberryperl`** — adds ~150 MB toolchain. Works
   universally, but Strawberry Perl is a heavyweight install and
   re-introduces a build dep into the dev-machine inventory that
   `project_phase1_strategy.md` explicitly kept lean (native Windows stack
   sans Docker/WSL2/Cygwin/Perl).
2. **Replace with `sqlfluff`** (Python-based) — feasible since Python is
   partially present, but `sqlfluff` opinions differ from pgFormatter's and
   running it would force a re-format of `db/schema.sql` (~6000 lines of
   code). That creates an enormous unrelated diff in any next PR.
3. **Use `pg_format` via Docker** — adds Docker dependency which the
   project explicitly avoids (`project_phase1_strategy.md`).
4. **Drop automated SQL formatting** — accept manual hygiene + `squawk`
   (linter) covers SQL correctness. pgFormatter is purely cosmetic in our
   flow (whitespace + keyword case).

## Selected option

**Carry forward (option 4 — drop automated SQL formatting until further
notice).** Production SQL hygiene is covered by squawk (no migration-rule
violations in current `db/schema.sql`). pgFormatter is purely cosmetic in
our pipeline. Re-evaluate at Б-1 closure (Managed Postgres in Yandex Cloud
introduces a formal infrastructure cycle, and revisiting SQL toolchain at
that point is cheap).

## Action items (none for this commit)

- ✅ Decision documented (this file)
- ✅ `npm run format:sql:check` remains in `package.json` for future use
  on machines where Perl IS available
- ✅ `npm run lint:sql` (squawk) continues to gate `db/schema.sql` in
  pre-commit

## Cross-references

- Audit #2 finding Q.HARD.002 — first appearance
- Audit #3 `findings.md` Phase 1D — confirmed deferral, no regression
- `memory/feedback_environment.md` — Windows dev quirks inventory
- `project_phase1_strategy.md` — native Windows stack rationale

## Axe-core .v-overlay-container region landmark — addendum

Separate but related P3 carryforward: axe-core flags
`.v-overlay-container` (Vuetify portal mount-point for overlays/menus) as
missing region landmark. This is a **structural Vuetify pattern**, not a
real a11y issue.

**Decision:** no test-config whitelist needed at this point because the
project has NO permanent axe-core test setup (axe-core is invoked only
inside ad-hoc Playwright MCP audits — not part of CI's `npm run test:*`).
If a permanent axe-core suite is introduced (e.g. as part of a future
Audit #4 hardening), add `exclude: [['.v-overlay-container']]` at that
point. Until then — accept the audit-time finding as informational.
