fix(tooling): keep prettier off the documentation corpus

Prettier's Markdown printer is not a formatting no-op on hard-wrapped
prose. Reproduced against the repo's own prettier 3.3.3: it joins
blockquote lines onto the preceding one, drops the `>` from continuation
lines, and reads the `*` inside a code span as an emphasis marker —
rewriting `/api/v1/*` to `/api/v1/_` and demoting a sentence clause to a
list item in phase-01-repository-tooling.md.

What fired was the editor. `.vscode/settings.json` maps `[markdown]` to
the Prettier extension for the whole repository, so any save or Format
Document reaches `docs/`. The hook was never the caller here — hooks are
opt-in via `make hooks` and `core.hooksPath` is unset — but it carried
the same hazard for anyone who ran it, feeding prettier every staged
`*.md` and `*.json` in the tree.

Nothing asked for or checked that formatting: no CI job runs prettier,
and `make format` invokes it from `frontend/`. So both callers now stop
at that boundary. A root `.prettierignore` (`/*` plus `!/frontend/`)
covers the editor and any root-cwd run; the hook classifies only paths
under `frontend/`, since it runs with `frontend/` as its working
directory where the ignore file does not apply. Verified A/B against a
deliberately unformatted probe: ignored at the root, still formatted
inside the workspace.

Restores both damaged documents to main's text and re-applies the
intended edits on top, so no prettier residue survives, and records the
defect in Phase 01's known-defects list beside the other two.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: cemililik

.githooks/pre-commit

@@ -7,8 +7,8 @@
 #
 # Languages handled:
 #   *.cs                              → dotnet format (whitespace + style)
-#   *.{ts,tsx,js,jsx,mjs,cjs}         → prettier --write + ESLint via pnpm
-#   *.{json,md}                       → prettier --write
+#   frontend/**.{ts,tsx,js,jsx,mjs,cjs} → prettier --write + ESLint via pnpm
+#   frontend/**.{json,md}               → prettier --write
 #
 # Intentionally NOT handled: *.yml / *.yaml. Compose / Dapr / APISIX YAMLs
 # are comment-heavy and prettier reflows them in a way that hurts review
@@ -80,10 +80,24 @@ all_staged=()
 # diff --cached` invocation on every commit).
 while IFS= read -r -d '' f; do
     all_staged+=("$f")
+    #
+    # Prettier is scoped to `frontend/` on purpose. It is a frontend tool here:
+    # `make format` runs it from that directory, and no CI job verifies its
+    # output anywhere. Pointed at the documentation corpus it is not a no-op —
+    # its Markdown printer joins blockquote lines, drops the `>` from
+    # continuations, and reads the `*` inside a code span as an emphasis
+    # marker — which silently rewrote `/api/v1/*` to `/api/v1/_` in a roadmap
+    # record. The root `.prettierignore` draws the same boundary for the
+    # editor; this filter draws it here, because prettier runs from
+    # `frontend/` where that file does not apply.
     case "$f" in
-        *.cs)                                         cs_files+=("$f") ;;
-        *.ts|*.tsx|*.js|*.jsx|*.mjs|*.cjs)           js_like_files+=("$f") ;;
-        *.json|*.md)                                  prettier_only_files+=("$f") ;;
+        *.cs) cs_files+=("$f") ;;
+        frontend/*)
+            case "$f" in
+                *.ts|*.tsx|*.js|*.jsx|*.mjs|*.cjs)   js_like_files+=("$f") ;;
+                *.json|*.md)                          prettier_only_files+=("$f") ;;
+            esac
+            ;;
     esac
 done < <(staged_files)
 

.github/CONTRIBUTING.md

@@ -10,7 +10,7 @@ Configure these in **GitHub → Settings → Branches → Branch protection rule
 
 > **Two settings are deferred — maintainer decision, 2026-08-10.** While
 > LearnStack has one active contributor, the live `main` rule sets
-> **Require approvals: 0** and leaves **Do not allow bypassing** _off_. A second
+> **Require approvals: 0** and leaves **Do not allow bypassing** *off*. A second
 > approver on a single-contributor repository blocks every merge, and admin
 > enforcement with no second admin blocks the only person who could unblock it.
 > The settings below are the **target state**, not the current one.
@@ -31,7 +31,6 @@ Configure these in **GitHub → Settings → Branches → Branch protection rule
   - Dismiss stale approvals when new commits are pushed: **on**.
   - Require review from CODEOWNERS: **off** (no CODEOWNERS file yet).
 - **Require status checks to pass before merging**
-
   - Require branches to be up to date before merging: **on**.
   - Required status checks (the job names from `.github/workflows/ci.yml`):
     - `backend (build + unit + arch + contract)`
@@ -46,7 +45,6 @@ Configure these in **GitHub → Settings → Branches → Branch protection rule
     `(deferred …)` suffix, and add the new name both to this list and to the live
     branch-protection setting. Setting the variable alone leaves a job that runs
     but gates nothing.
-
     - `backend integration (Testcontainers — deferred)` — Phase 02a **Packet 7**,
       with the first cross-tenant isolation test.
     - `openapi diff (deferred to Phase 02d)` — **Phase 02d**, with the first real
@@ -57,7 +55,6 @@ Configure these in **GitHub → Settings → Branches → Branch protection rule
     GitHub matches required checks **by name**, so the rename is the dangerous
     half: a renamed check that nobody re-required is a check that no longer blocks
     anything, and the PR still shows green.
-
 - **Require conversation resolution before merging**: on.
 - **Require signed commits**: optional (off until the team rolls out signing keys).
 - **Require linear history**: on (we use squash-merge or rebase-merge, never bubble).
@@ -80,7 +77,7 @@ Per CLAUDE.md § Commit conventions:
   `Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>`
   (replace the model name when authoring with a different assistant).
 - `docs(scope)` for doc-only commits; scope ∈ `architecture | decisions |
-standards | roadmap` or omitted for cross-cutting changes.
+  standards | roadmap` or omitted for cross-cutting changes.
 
 ## Pull requests
 
@@ -102,12 +99,23 @@ make test           # unit + arch + contract + vitest
 ```
 
 The pre-commit hook (activated by `make install`) runs, on staged files only:
-`dotnet format` on `*.cs`; prettier on JS/TS/JSON/MD; `next lint --fix` on
-JS/TS under `frontend/apps/web` — the one workspace with a `lint` script, so
-this is exactly what `pnpm -r lint` covers in CI; and, when the binary is on
-PATH, `leakwatch scan fs <staged-file>`. So the lint / typecheck / test /
-secret-scan pass above is mostly a sanity check. CI re-runs every check as a
-hard gate, so a bypassed local commit will fail the PR build.
+`dotnet format` on `*.cs`; prettier on JS / TS / JSON / Markdown **under
+`frontend/`**; `next lint --fix` on JS / TS under `frontend/apps/web` — the one
+workspace with a `lint` script, so this is exactly what `pnpm -r lint` covers in
+CI; and, when the binary is on PATH, `leakwatch scan fs <staged-file>`. So the
+lint / typecheck / test / secret-scan pass above is mostly a sanity check. CI
+re-runs every check as a hard gate, so a bypassed local commit will fail the PR
+build.
+
+Prettier stops at the `frontend/` boundary, and the root `.prettierignore`
+is what enforces it in your editor — `.vscode/settings.json` maps `[markdown]`
+to the Prettier extension, which honours that file, so neither format-on-save
+nor an explicit Format Document reaches `docs/`. Keep it that way: prettier's
+Markdown printer rewrites hard-wrapped prose — it joins blockquote lines and
+reads `*` inside a code span as emphasis — and it corrupted a roadmap record
+doing exactly that. Nothing verifies its output outside the frontend workspace
+anyway, since no CI job runs prettier and `make format` invokes it from
+`frontend/`.
 
 Older Leakwatch builds — including the `v1.5.0` CI pins — only accept a
 directory target. The hook detects that and skips the local scan with an

.prettierignore

@@ -0,0 +1,20 @@
+# Prettier is scoped to the frontend workspace.
+#
+# `make format` already runs it from `frontend/`, and no CI job verifies its
+# output anywhere in this repository. Outside that workspace every file is
+# hand-authored — the documentation corpus is hard-wrapped prose with
+# blockquote-heavy delivery records, and prettier's Markdown printer rewrites
+# it: it joins blockquote lines onto the preceding one, drops the `>` from
+# continuation lines, and reads the `*` inside a code span as an emphasis
+# marker. It silently turned `/api/v1/*` into `/api/v1/_` in
+# docs/roadmap/phase-01-repository-tooling.md.
+#
+# This file is what stops the editor. `.vscode/settings.json` maps `[markdown]`
+# to the Prettier extension, which honours `.prettierignore` from the workspace
+# root — so ignoring here covers both format-on-save and an explicit
+# Format Document. The pre-commit hook runs prettier with `frontend/` as its
+# working directory, where this file does not apply, so it carries the same
+# boundary as a path filter of its own.
+
+/*
+!/frontend/

Makefile

@@ -149,7 +149,7 @@ install: .env hooks ## Restore backend NuGet + frontend pnpm deps + activate git
 .PHONY: hooks
 hooks: ## Activate the repo's pre-commit hook (.githooks/pre-commit).
 	@git config core.hooksPath .githooks
-	@printf "$(CYAN)git hooks → .githooks/ (pre-commit: dotnet format + prettier + eslint + leakwatch if available)$(RESET)\n"
+	@printf "$(CYAN)git hooks → .githooks/ (pre-commit: dotnet format on *.cs, prettier + next lint under frontend/, leakwatch if available)$(RESET)\n"
 
 # ─── Env scaffolding ──────────────────────────────────────────────────────
 # `.env` is gitignored; this rule copies `.env.example` on first run so the