[tech-debt] Framework guidance still shows a write-mode formatter as the pre-push gate command (bootstrapped projects inherit the #394 anti-pattern)

[rucka]

Story Statement

As a team bootstrapping a project with pair
I want the framework's own guidance to describe a pre-push gate that CHECKS formatting rather than applying it
So that a new project does not start with the write-mode pre-push formatter pair just removed from itself

Epic Context

Parent Epic: framework guidance / quality gates (no epic — standalone tech debt)
Status: Todo
Priority: P2 (Could-Have)

Problem

#394 established, for this repo, that a pre-push gate must never run a formatter in write mode: at pre-push the commits already exist, so a write-mode formatter rewrites the working tree without touching what is being pushed — the author then either sweeps unrelated reformats into the next commit or pushes with --no-verify (ADL 2026-07-31-pre-push-gate-is-check-only.md).

The framework surfaces still teach the opposite:

• packages/knowledge-hub/dataset/.pair/adoption/tech/way-of-working.md
  • line 14: "Quality gate includes: type checking (ts:check), testing (test), linting (lint), formatting (prettier:fix)."
  • line 26 (Custom Gate Registry): | 1 | Formatting | pnpm prettier:fix | formatting | No | Prettier auto-fix and verify |
• .pair/knowledge/guidelines/quality-assurance/quality-standards/quality-gates.md line 160: the Command column example is pnpm prettier:fix.

Every project bootstrapped from the dataset therefore starts with the exact pathology #394 catalogued three times in two days here (PRs #388, #408, #411). The framework's own code-design/quality-standards/shared-config-packages.md already mentions the pre-commit/lint-staged alternative, so the guidance is inconsistent as well as wrong-by-default.

Likely In Scope

• Dataset adoption template + KB guideline: gate example runs a formatting check (format:check / prettier:check), with the write-mode command documented as the developer's deliberate fix step (pnpm format)
• A one-line rationale in the KB (why a pre-push formatter cannot fix the commits being pushed) so the guidance carries its reason, not just its shape
• Mirror discipline: .pair/knowledge/** ↔ packages/knowledge-hub/dataset/.pair/knowledge/** kept consistent
• Check whether /pair-capability-setup-gates generates a write-mode formatter step and align it

Likely Out of Scope

• Anything in this repo's own gate (already done in [tech-debt] Pre-push quality-gate runs prettier:fix/mdlint:fix repo-wide in WRITE mode — authors bypass the hook #394 / PR [US-394] fix: pre-push gate checks formatting instead of applying it (a write-mode formatter cannot fix the commits being pushed) #412)
• CI enforcement of format:check ([tech-debt] CI does not run format:check — the check-only pre-push gate is the only enforcement point (--no-verify skips it) #413) and the coverage gap outside workspace packages ([tech-debt] format:check does not cover files outside workspace packages (.pair/**, scripts/**, root-level JSON) #414)
• Changing prettier/markdownlint rules

Acceptance Criteria (draft)

• No framework surface (KB guideline or dataset adoption template) shows a write-mode formatter as a pre-push/quality-gate command
• The check-mode rationale is stated once in the KB and referenced, not duplicated
• A freshly bootstrapped project's way-of-working.md gate registry describes a formatting check

Notes

Filed from the independent review of PR #412 (story #394), where the framework-scope drift was explicitly and deliberately left out of scope ("promoting this project decision to framework guidance is a framework-audience decision, deliberately not made here" — ADL Consequences + PR Review Areas). Promoting it changes what pair recommends to every user and touches the KB/dataset mirror pair, so it needs its own decision and its own story rather than a drive-by edit.