Merge branch 'main' into worktree-content-fixes

docs/solutions/architecture-patterns/git-sync-secret-exposure-and-tracked-file-boomerang.md

@@ -1,6 +1,7 @@
 ---
 title: "Secret exposure under bidirectional Grav git-sync: gitignore is the only boundary (and the tracked-file boomerang trap)"
 date: 2026-07-05
+last_updated: 2026-07-05
 module: git-sync
 problem_type: architecture_pattern
 component: tooling
@@ -174,6 +175,69 @@ committing looks clean locally, but Grav re-appends it at runtime and the next
 sync re-commits and re-pushes it. The only durable fixes are the
 companion-private-file pattern or disabling the feature.
 
+### Untracking an already-committed secret under a live sync — freeze every server first
+
+`.gitignore` (and git-sync's `ignore` field) only affects **untracked** files.
+Once a secret has actually been *committed* to the shared repo, ignoring it does
+nothing — removing it means rewriting history. Doing that while a bidirectional
+sync is live has its own trap.
+
+**A `direction: both` server silently reverts your force-push.** Concrete
+incident (2026-07-05, a second occurrence of this doc's trap): `config/security-private.php`
+and `config/versions.yaml` had been committed to Gitea `main` (auto-commit
+`d1643a7`, merged at `f8c45fc`). Force-pushing `main` back to the clean commit
+`32c3d8c` *looked* successful — and within seconds Gitea was back at `f8c45fc`.
+Cause: prod's git-sync is `direction: both` and its local `HEAD` was still
+`f8c45fc`; on its next sync it re-pushed the stale, secret-bearing commit and
+undid the rewrite. The pull-only test server never fought back — **only
+push-enabled servers do.**
+
+**The rule: freeze git-sync on _every_ server (push *and* pull) before rewriting
+shared history.** A pull server mid-rewrite can also resurrect a half-removed
+state. The safe sequence that worked:
+
+1. **Freeze all sync.** `make remote-git-sync-disable-{test,prod}` (flips
+   `enabled: false` in the env-path `git-sync.yaml`).
+2. **Audit where the live secret actually lives — before any `reset --hard`.** A
+   destructive reset *deletes* working-tree files tracked now but absent in the
+   target commit. `config/security-private.php` was such a file — but it was a
+   **stray duplicate**; the authoritative 290-byte copy lives at
+   `env/intotheeast.com/config/security-private.php` (mode 600), which git-sync
+   had copied into `config/`. Because `env/` is gitignored and outside every
+   tracked folder, it survives the reset and *wins* Grav's config merge — so
+   dropping the `config/` copy is safe. **Verify this first** with a secret-safe
+   audit that lists existence + size + `git ls-files` tracking and **never prints
+   contents** (added as `make remote-secrets-audit`; it `ls` / `git ls-files`,
+   never `cat`).
+3. **Force-push `main` to the clean commit.** It sticks now — no server is pushing.
+4. **Reset each server** with `make remote-fetch-content-{test,prod}`
+   (`fetch` → `sparse-checkout disable` → `reset --hard origin/main`). This
+   deletes the stray tracked `config/` copies; the `env/` originals remain.
+5. **Verify** `git ls-files` shows no secret tracked and the `env/` copy is intact
+   on every host.
+6. **Re-enable sync** (`make remote-git-sync-enable-*`), preserving each server's
+   `direction`. Local `HEAD` now equals Gitea `main`, so there is nothing bad to
+   push.
+
+Two gotchas inside step 4:
+
+- **Stale remote-tracking ref.** `reset --hard origin/main` resets to the
+  server's *cached* `refs/remotes/origin/main`, not to Gitea directly. If that ref
+  is stale the reset lands on the wrong commit — confirm the `fetch` force-updated
+  it (`+ f8c45fc...32c3d8c main -> origin/main (forced update)`) before trusting
+  the reset.
+- **`sparse-checkout disable` before `reset --hard`** — otherwise the reset only
+  touches paths inside the sparse pattern and can skip/wipe directories outside it.
+
+**Durable exclusion goes in git-sync's `ignore:` config field, never a
+hand-edited `.gitignore`.** git-sync owns `.gitignore`: on load it regenerates it
+from `folders` (`/*`, `!/pages`, `!/config`, `!/themes`) and **appends** the
+`ignore:` entries. Hand edits are clobbered on the next sync; `ignore:` entries
+persist because git-sync writes them back every time. So the secret paths belong
+in `ignore:` — but that only prevents *future* tracking. The history rewrite
+(steps 1–5) is still required *in addition to* the ignore entries to remove a
+secret that is already committed, not instead of them.
+
 ## Why This Matters
 
 Two quiet, cross-environmental failure modes:
@@ -207,6 +271,9 @@ strength of folder scoping alone.
 - **Reviewing a "stop tracking this secret" cleanup** for whether it will stick:
   is the secret in its own gitignored path (holds) or a line inside a tracked
   functional file that something regenerates (boomerangs)?
+- **Rewriting shared history (force-push, `filter-repo`, `reset --hard`) on a
+  git-sync-managed repo** — freeze sync on every server first, audit where the
+  live secret authoritatively lives before any destructive reset, then re-enable.
 
 ## Examples
 
@@ -229,6 +296,15 @@ per-install and re-commits under sync. The fix that *sticks* is the
 companion-private-file pattern or `popularity.enabled: false` — **not** stripping
 the `salt:` line.
 
+**Force-push revert example.** With `config/security-private.php` +
+`config/versions.yaml` already committed to Gitea `main` (`f8c45fc`), a
+`git push --force origin main` back to the clean `32c3d8c` was undone within
+seconds — prod's `direction: both` git-sync re-pushed its stale `f8c45fc` `HEAD`.
+The rewrite only held after `make remote-git-sync-disable-{test,prod}` froze both
+servers first; then force-push → `make remote-fetch-content-{test,prod}` →
+re-enable. Verified afterward: `git ls-files` on every host lists no secret, and
+each host's `env/…/security-private.php` is intact.
+
 ## Related
 
 - `docs/solutions/conventions/grav-plugin-config-must-be-tracked-override.md` — the